curiositech/git-best-practices

Git Best Practices

Expert in the specific Git workflows, conventions, and patterns that make development teams — and solo developers working with AI coding agents — productive. Not "how to use git" but "how to use git well."

Activation Triggers

Activate on: "branching strategy", "commit conventions", "git hooks", "pre-commit", "husky", "lint-staged", "trunk-based development", "git worktree", "monorepo git", "PR review workflow", "conventional commits", "git workflow", "merge strategy", "rebase vs merge", "git conflict resolution"

NOT for: CI/CD pipelines -> github-actions-pipeline-builder | Repo hosting -> devops-automator | Multi-agent orchestration -> multi-agent-coordination

Branching Strategy Decision Matrix

| Strategy | Team Size | Release Cadence | Complexity | Best For | |----------|-----------|-----------------|------------|----------| | Trunk-Based | Any | Continuous | Low | SaaS, microservices, AI agents | | GitHub Flow | 2-20 | Daily/weekly | Low | Most teams, open source | | GitFlow | 10+ | Scheduled releases | High | Mobile apps, versioned libraries | | Ship/Show/Ask | Any | Continuous | Medium | High-trust teams |

Trunk-Based Development (Recommended Default)

main ──●──●──●──●──●──●──●──●──●── (always deployable)
        \   /  \     /  \       /
         ●─●    ●──●    ●──●──●
        (hours)  (1 day) (2 days max)

Rules:

1. main is always deployable. Period.
2. Feature branches live max 2 days. Shorter is better.
3. Feature flags gate incomplete work, not long-lived branches.
4. Every merge to main triggers CI. Green means deployable.
5. No release branches unless you ship packaged software.

When NOT to use trunk-based:

• Mobile apps with app store review cycles
• Libraries with semantic versioning and support branches
• Teams without CI/CD automation

GitHub Flow

main ──●──────●──────●──────●──── (protected, PR-only merges)
        \    / \    / \    /
         ●──●   ●──●   ●──●
        feature  fix   feature

Rules:

1. main is protected. No direct pushes.
2. Create branch from main, do work, open PR.
3. PR gets reviewed, CI passes, squash-merge to main.
4. Delete branch after merge.

Ship / Show / Ask Framework

| Category | Action | When | |----------|--------|------| | Ship | Merge directly to main | Typos, config, deps, obvious fixes | | Show | Open PR, merge immediately, review async | Straightforward changes, established patterns | | Ask | Open PR, wait for review | New architecture, risky changes, unfamiliar code |

Conventional Commits

The Specification

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

| Type | When | Bumps | |------|------|-------| | feat | New user-facing feature | MINOR | | fix | Bug fix | PATCH | | docs | Documentation only | - | | style | Formatting, whitespace (not CSS) | - | | refactor | Code change that neither fixes nor adds | - | | perf | Performance improvement | - | | test | Adding/fixing tests | - | | build | Build system, dependencies | - | | ci | CI/CD changes | - | | chore | Maintenance, tooling | - | | revert | Reverts a previous commit | - |

Breaking Changes

feat(auth)!: replace API key with OAuth2

BREAKING CHANGE: The `apiKey` parameter in `createClient()` has been
removed. Use `oauth: { clientId, clientSecret }` instead.

Migration: npx @your-tool/codemod v2-to-v3

The ! after the type/scope and BREAKING CHANGE: footer both signal a MAJOR version bump.

Good vs Bad Commit Messages

# BAD - what, not why
fix: update code
feat: add stuff
chore: changes

# GOOD - why, with context
fix(auth): prevent token refresh race condition on slow networks
feat(search): add fuzzy matching for skill names with Levenshtein distance
chore(deps): bump vitest to 3.1 for Node 22 compatibility

Enforcing with commitlint

# Install
npm install -D @commitlint/cli @commitlint/config-conventional

# Configure
echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js

# Hook into Husky
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

Git Hooks: Husky + lint-staged

Setup (Modern Husky v9+)

# Install
npm install -D husky lint-staged

# Initialize husky
npx husky init

# The init command creates .husky/ and adds a prepare script
# Edit .husky/pre-commit:
echo "npx lint-staged" > .husky/pre-commit

lint-staged Configuration

// package.json
{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,yml}": [
      "prettier --write"
    ],
    "*.test.{ts,tsx}": [
      "vitest related --run"
    ]
  }
}

Monorepo Hook Configuration

Install Husky at root, scope lint-staged by package path: "packages/core/**/*.ts": "pnpm --filter @your-org/core lint". Each package gets its own lint command, preventing cross-package leak.

Hook Performance Guidelines

| Hook | Max Time | What to Run | |------|----------|-------------| | pre-commit | <5 seconds | Lint + format staged files only | | commit-msg | <1 second | commitlint validation | | pre-push | <30 seconds | Type check + fast test suite |

If hooks are slow, developers skip them with --no-verify. Keep them fast.

Essential Hook Set

# .husky/pre-commit — fast, staged files only
npx lint-staged

# .husky/commit-msg — validate message format
npx --no -- commitlint --edit $1

# .husky/pre-push — more thorough checks
pnpm typecheck && pnpm test --run

Git Worktrees for AI Agent Isolation

Worktrees let you check out multiple branches simultaneously in separate directories, sharing the same .git history. This is the primary isolation primitive for parallel AI agents.

Basic Worktree Workflow

# Create a worktree for a feature
git worktree add ../myproject-feature-auth feature/auth

# List active worktrees
git worktree list

# Work in the worktree (it's a normal directory)
cd ../myproject-feature-auth
# ... make changes, commit, push ...

# Remove when done
git worktree remove ../myproject-feature-auth

AI Agent Worktree Pattern

# Agent 1: Working on auth
git worktree add ../project-agent-auth -b agent/auth-refactor

# Agent 2: Working on API (parallel, isolated)
git worktree add ../project-agent-api -b agent/api-endpoints

# Agent 3: Working on tests (parallel, isolated)
git worktree add ../project-agent-tests -b agent/test-coverage

# Each agent has full filesystem isolation
# Commits in any worktree are visible to all (shared .git)

# When agents finish, merge results
git merge agent/auth-refactor
git merge agent/api-endpoints
git merge agent/test-coverage

# Clean up
git worktree remove ../project-agent-auth
git worktree remove ../project-agent-api
git worktree remove ../project-agent-tests

Worktree Gotchas

| Problem | Solution | |---------|----------| | Port conflicts | Each worktree needs unique dev server ports (use env vars or port-daddy) | | Shared node_modules | Run npm install in each worktree (separate node_modules per worktree) | | Database conflicts | Use per-worktree database names or Docker containers | | Same branch twice | Git prevents this — you cannot check out a branch that's checked out elsewhere | | IDE confusion | Open each worktree as a separate workspace/window | | Stale worktrees | Run git worktree prune periodically to clean up |

Worktree Naming Convention

../project-<purpose>-<branch-slug>

# Examples:
../windags-agent-auth-refactor
../windags-agent-api-endpoints
../windags-review-pr-142
../windags-experiment-new-executor

PR Review Workflow

PR Size Guidelines

| Size | Lines Changed | Review Time | Recommendation | |------|---------------|-------------|----------------| | XS | 1-10 | Minutes | Ship or Show | | S | 10-100 | 15 min | Standard review | | M | 100-400 | 30 min | Standard review | | L | 400-1000 | 1 hour | Break it up if possible | | XL | 1000+ | Hours | Almost always should be split |

PR Template Sections

Every PR template should include: What (1-2 sentences, what and why) -> How (technical approach) -> Testing (steps + checkboxes) -> Screenshots (before/after for UI) -> Breaking Changes (none or migration path). Save as .github/pull_request_template.md.

Reviewer Checklist

Understand what/why, tests cover happy + edge path, no TODO without issue link, error handling present, no secrets in diff, breaking changes documented.

Merge Strategy

| Strategy | When | Command | |----------|------|---------| | Squash merge (default) | Feature branches, messy commits | git merge --squash feature/auth then single conventional commit | | Rebase + FF merge | Linear history, each commit meaningful | git rebase main then git merge feature/auth | | Merge commit | Long-running integration branches (rare) | git merge feature/auth |

Decision: Are all commits on the branch meaningful and tested? Yes -> rebase. No -> squash.

Monorepo Git Patterns

Sparse Checkout (Work on One Package)

# Clone with sparse checkout
git clone --sparse --filter=blob:none https://github.com/org/monorepo.git
cd monorepo

# Check out only what you need
git sparse-checkout set packages/core packages/shared

Path-Scoped Git Operations

# Log for one package
git log --oneline -- packages/core/

# Diff for one package
git diff main -- packages/ui/

# Blame within scope
git log --all --oneline -- packages/cli/src/index.ts

CODEOWNERS for Monorepos

# .github/CODEOWNERS
packages/core/       @org/core-team
packages/ui/         @org/frontend-team
packages/cli/        @org/dx-team
docs/                @org/docs-team
.github/             @org/platform-team

Git Configuration Essentials

Key settings every team should configure:

[pull]   rebase = true           # Rebase on pull instead of merge
[push]   autoSetupRemote = true  # Auto set upstream on first push
[merge]  conflictstyle = zdiff3  # Better conflict markers with common ancestor
[diff]   algorithm = histogram   # Better diff output
[rerere] enabled = true          # Remember conflict resolutions
[fetch]  prune = true            # Auto-delete stale remote branches

.gitignore essentials: node_modules/, .env*, dist/, .turbo/, .DS_Store, coverage/. Always commit lock files (pnpm-lock.yaml). Use gitignore.io for stack-specific templates. Set up ~/.gitignore_global for per-developer ignores.

Anti-Patterns

1. Long-Lived Feature Branches

Symptom: Branch diverges from main for weeks. Merge becomes a nightmare. Fix: Trunk-based development. Feature flags for incomplete work. Branch lives max 2 days.

2. "WIP" Commit Messages

Symptom: git log shows "wip", "stuff", "fix", "asdf". Fix: Squash merge into a single conventional commit. Or use git rebase -i to clean up before PR.

3. Skipping Hooks with --no-verify

Symptom: Developers routinely bypass pre-commit hooks. Fix: Hooks are too slow. Make them faster (lint-staged, not full project). Or move slow checks to pre-push.

4. Force Pushing to Shared Branches

Symptom: git push --force to main or shared feature branches. Fix: Protect main in GitHub/GitLab settings. Use --force-with-lease if you must force push to your own branch.

5. Committing Generated Files

Symptom: dist/, node_modules/, *.lock diffs pollute PRs. Fix: Add to .gitignore. Only commit lock files (package-lock.json, pnpm-lock.yaml) — those belong in version control.

6. Secrets in Git History

Symptom: API keys, passwords committed and "removed" in a later commit. They're still in history. Fix: Use git-filter-repo to rewrite history. Rotate the exposed credentials immediately. Add .env to .gitignore before first commit.

7. No Branch Protection

Symptom: Anyone can push directly to main. No required reviews. No CI gate. Fix: Enable branch protection: require PR, require 1+ review, require CI green, require up-to-date branch.

8. Rebasing Public/Shared Branches

Symptom: Rebasing a branch that others have pulled causes history divergence. Fix: Only rebase your own local branches. Once pushed and shared, merge only.

Quality Checklist

[ ] Branching strategy documented and agreed upon by team
[ ] Conventional commit format enforced via commitlint + husky
[ ] Pre-commit hooks run lint + format on staged files only (< 5 seconds)
[ ] Pre-push hooks run typecheck + tests
[ ] Branch protection enabled on main (PR required, CI green, review required)
[ ] .gitignore covers dependencies, build output, env files, OS files
[ ] PR template exists with what/how/testing/breaking sections
[ ] Merge strategy chosen and configured (squash recommended)
[ ] CODEOWNERS file maps directories to responsible teams
[ ] git config includes rebase-on-pull, prune-on-fetch, zdiff3 conflicts
[ ] Worktree conventions documented for AI agent workflows
[ ] No secrets in git history (scanned with trufflehog or gitleaks)
[ ] Lock files (pnpm-lock.yaml) committed, generated output is not

Output Artifacts

1. Git Configuration — .gitconfig recommendations, branch protection rules
2. Hook Setup — Husky + lint-staged + commitlint configuration
3. PR Template — .github/pull_request_template.md
4. CODEOWNERS — Directory-to-team ownership mapping
5. .gitignore — Comprehensive ignore rules for the stack
6. Branching Strategy Doc — Team-agreed workflow documentation
7. Worktree Scripts — Helper scripts for creating/cleaning agent worktrees