Git Best Practices
for Modern Development

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

# 1. Work on your feature branch
git checkout -b feat/new-widget

# 2. Make commits...
git commit -m "feat(widget): add base component"
git commit -m "feat(widget): add click handler"

# 3. Before merging, rebase onto latest main
git fetch origin
git rebase origin/main

# 4. Resolve any conflicts, then force-push your branch
git push --force-with-lease

# 5. Create PR and merge (squash or merge commit)

# Squash merge a feature branch
git merge --squash feat/new-widget
git commit # Write a single summary commit message

# On GitHub: use the "Squash and merge" button on PRs

# Install Husky and lint-staged
npm install --save-dev husky lint-staged

# Initialize Husky
npx husky init

# Create pre-commit hook
echo "npx lint-staged" > .husky/pre-commit

{
  "lint-staged": {
    "*.{js,ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md,yml}": ["prettier --write"],
    "*.css": ["stylelint --fix", "prettier --write"]
  }
}

pre-commit:
  parallel: true
  commands:
    lint:
      glob: "*.{js,ts,tsx}"
      run: npx eslint --fix {staged_files}
    format:
      glob: "*.{js,ts,tsx,json,md}"
      run: npx prettier --write {staged_files}
    typecheck:
      run: npx tsc --noEmit

commit-msg:
  commands:
    validate:
      run: npx commitlint --edit {1}

# Environment & secrets
.env
.env.*
!.env.example
*.pem
*.key
credentials.json
service-account.json

# Dependencies
node_modules/
vendor/
.venv/

# Build output
dist/
build/
.next/
out/

# IDE & OS
.DS_Store
.idea/
.vscode/settings.json
*.swp

# Configure SSH signing
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true
git config --global tag.gpgsign true

# Verify a signed commit
git log --show-signature -1

# Install gitleaks
brew install gitleaks

# Scan current state
gitleaks detect --source .

# Scan full history
gitleaks detect --source . --log-opts="--all"

# Use as pre-commit hook
gitleaks protect --staged

# Create a new worktree for a feature branch
git worktree add ../my-project-feat feat/new-feature

# Create worktree with a new branch
git worktree add -b feat/auth ../my-project-auth

# List all worktrees
git worktree list

# Remove a worktree when done
git worktree remove ../my-project-feat

# Prune stale worktree metadata
git worktree prune

# Set up parallel worktrees for multiple features
git worktree add -b feat/auth   ../project-auth
git worktree add -b feat/search ../project-search
git worktree add -b fix/perf    ../project-perf

# Launch separate Claude Code sessions in each
cd ../project-auth   && claude "implement OAuth2 flow" &
cd ../project-search && claude "add full-text search" &
cd ../project-perf   && claude "optimize database queries" &

# Each agent works in isolation, no merge conflicts

# Enable autosquash globally (recommended)
git config --global rebase.autosquash true

# Make your initial commits
git commit -m "feat: add user profile page"     # abc1234
git commit -m "feat: add avatar upload"          # def5678

# Later, realize you need to fix the profile page commit
git commit --fixup=abc1234  # Creates "fixup! feat: add user profile page"

# When ready to clean up, autosquash reorders and fixups
git rebase -i --autosquash main
# The fixup commit is auto-placed after its target

# Clone with sparse checkout (only root files)
git clone --sparse https://github.com/org/monorepo.git
cd monorepo

# Add only the directories you need
git sparse-checkout add packages/auth
git sparse-checkout add packages/shared
git sparse-checkout add infra/terraform

# List current sparse-checkout patterns
git sparse-checkout list

# Combine with partial clone for maximum speed
git clone --sparse --filter=blob:none https://github.com/org/monorepo.git

# Enable background maintenance (Git 2.31+)
git maintenance start
# Runs hourly: prefetch, commit-graph, loose-objects, incremental-repack

# Manual optimization
git gc --aggressive           # Deep garbage collection
git repack -a -d --depth=250   # Optimal pack file
git commit-graph write --reachable  # Speed up log/rev-list

# Check repo stats
git count-objects -vH          # Size and object counts

# Install and initialize LFS
brew install git-lfs
git lfs install

# Track file patterns
git lfs track "*.psd"
git lfs track "*.mp4"
git lfs track "*.zip"
git lfs track "models/**"

# Verify what's tracked
git lfs ls-files

# Don't forget to commit .gitattributes
git add .gitattributes
git commit -m "chore: configure LFS tracking"

# View the reflog (all HEAD movements)
git reflog
# abc1234 HEAD@{0}: commit: feat: add search
# def5678 HEAD@{1}: rebase: squash
# 789abcd HEAD@{2}: checkout: moving from main to feat/search

# Recover a "lost" commit after bad rebase
git reset --hard HEAD@{2}

# Cherry-pick a specific lost commit
git cherry-pick abc1234

# Create a branch from a reflog entry
git branch recovery-branch HEAD@{5}

# Start bisecting
git bisect start

# Mark current commit as bad (has the bug)
git bisect bad

# Mark a known good commit (before the bug)
git bisect good v2.1.0

# Git checks out the midpoint. Test it, then:
git bisect good   # if this commit is OK
git bisect bad    # if this commit has the bug

# Repeat until Git identifies the exact commit

# Automate with a test script
git bisect run npm test

# Clean up when done
git bisect reset

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test

jobs:
  lint-and-test:
    uses: ./.github/workflows/shared-ci.yml
    with:
      node-version: '22'
    secrets: inherit

  deploy:
    needs: lint-and-test
    if: github.ref == 'refs/heads/main'
    uses: ./.github/workflows/deploy.yml
    with:
      environment: production

[alias]
  # Status & logging
  st     = status -sb
  lg     = log --oneline --graph --decorate --all
  last   = log -1 HEAD --stat

  # Branching
  co     = checkout
  br     = branch
  brd    = branch -d
  sw     = switch

  # Committing
  ci     = commit
  amend  = commit --amend --no-edit
  wip    = !git add -A && git commit -m 'WIP'

  # Undoing
  undo   = reset --soft HEAD~1
  unstage = reset HEAD --

  # Syncing
  sync   = !git fetch origin && git rebase origin/main
  pf     = push --force-with-lease

[alias]
  # Show branches sorted by last commit date
  recent = branch --sort=-committerdate --format='%(committerdate:relative)\t%(refname:short)'

  # Delete all merged branches (except main/develop)
  cleanup = !git branch --merged | grep -v '\\*\\|main\\|develop' | xargs -n 1 git branch -d

  # Show which files changed between two branches
  changed = diff --name-only

  # Interactive fixup (select commit to fix with fzf)
  fixup  = !git log --oneline -20 | fzf | awk '{print $1}' | xargs git commit --fixup

  # Who changed this file the most?
  authors = !git log --format='%aN' -- \"$1\" | sort | uniq -c | sort -rn

  # Today's commits
  today  = log --since=midnight --oneline --no-merges

[init]
  defaultBranch = main

[pull]
  rebase = true           # Rebase instead of merge on pull

[push]
  autoSetupRemote = true  # Auto-create upstream on first push
  default = current       # Push current branch by default

[fetch]
  prune = true             # Auto-remove dead remote branches

[rebase]
  autosquash = true        # Auto-fixup on interactive rebase
  autostash = true         # Auto-stash before rebase

[merge]
  conflictstyle = zdiff3   # Show base in conflict markers

[diff]
  algorithm = histogram    # Better diff output
  colorMoved = default     # Highlight moved lines

[rerere]
  enabled = true           # Remember conflict resolutions

# Always attribute AI contributions in commits
git commit -m "feat(search): add full-text search API

Implements Elasticsearch-backed search with fuzzy matching
and relevance scoring. Includes rate limiting and caching.

Co-Authored-By: Claude <noreply@anthropic.com>"