git-workflow

Git Workflow

Branching Strategies

Trunk-Based (Recommended for most teams)

main ←── short-lived feature branches (< 2 days)
  └── release/* (cut when ready, hotfix → cherry-pick back)

• All developers commit to main (or merge within 24h)
• Use feature flags for incomplete work, not long-lived branches
• CI must pass on every commit to main

GitHub Flow

git checkout -b feat/user-avatars
# work, commit, push
gh pr create --base main --fill
# review → squash merge → auto-deploy

GitFlow (when you need it)

main ← tagged releases only
develop ← integration branch
  ├── feature/* → develop
  ├── release/* → main + develop
  └── hotfix/*  → main + develop

Commit Conventions (Conventional Commits)

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Enforce with commitlint: npx husky add .husky/commit-msg 'npx commitlint --edit $1'

Git Hooks (Husky + lint-staged)

npx husky init
npm i -D lint-staged

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

# .husky/pre-commit
npx lint-staged

# .husky/commit-msg
npx commitlint --edit $1

Code Review Checklist

• PR is < 400 lines (split if larger)
• Tests cover new behavior and edge cases
• No secrets, credentials, or PII in diff
• Breaking changes documented and flagged
• Error handling is explicit (no swallowed errors)
• No TODO without a linked issue
• DB migrations are reversible
• API changes are backward-compatible (or versioned)

See references/pr-template.md for a reusable PR template.

Rebase vs Merge

# Update feature branch (never rebase shared branches)
git fetch origin && git rebase origin/main

# Interactive rebase to clean up before PR
git rebase -i HEAD~5

Cherry-Pick Workflow

# Hotfix: fix on main, cherry-pick to release
git checkout main && git cherry-pick <sha>
git checkout release/2.3 && git cherry-pick <sha>

Always cherry-pick forward (oldest branch → newest). Never backport without testing.

Tag & Release Strategy

# Semantic versioning tags
git tag -a v2.4.0 -m "Release 2.4.0"
git push origin v2.4.0

# Automate with semantic-release or release-please
# Trigger: push to main → analyze commits → bump version → tag → changelog

See references/release-config.json for semantic-release configuration.

Monorepo Patterns

# Nx — affected-only CI
npx nx affected --target=test --base=origin/main

# Turborepo
npx turbo run build --filter=...[origin/main]

# CODEOWNERS for per-package review
# .github/CODEOWNERS
/packages/auth/**  @auth-team
/packages/api/**   @api-team

.gitignore Best Practices

# OS
.DS_Store
Thumbs.db

# Dependencies
node_modules/
vendor/

# Build output
dist/
.next/
*.tsbuildinfo

# Environment (NEVER commit secrets)
.env
.env.local
.env.*.local

# IDE
.idea/
.vscode/settings.json

Use git check-ignore -v <file> to debug. Use references/gitignore-templates/ for language-specific templates.

Quick Reference

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Find commit that introduced a bug
git bisect start && git bisect bad && git bisect good v2.0.0

# Clean up merged branches
git branch --merged main | grep -v main | xargs git branch -d

# Amend without changing message
git commit --amend --no-edit

# Stash with name
git stash push -m "wip: auth refactor"