Git Mastery
Enforce distributed-first, async-friendly git workflows with automated quality gates.
Commits: Atomic + Conventional
Every commit must be:
- Single logical change (use
git add -pfor selective staging) - Complete (code + tests + docs together)
- Independently buildable and testable
- Describable without "and" in subject
Format: type(scope): subject (50 chars max)
feat(auth): add OAuth2 login flow
fix(api): handle null response in user endpoint
docs(readme): add deployment instructions
refactor(db): extract query builder
Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore
BREAKING CHANGE: Add footer BREAKING CHANGE: description → triggers MAJOR version.
Branches: Short-Lived + Typed
Naming: type/issue-description (lowercase, hyphens, <60 chars)
feature/123-oauth-login
fix/456-null-pointer-api
hotfix/critical-auth-bypass
Rules:
- Max 3 days old (escalate if longer)
- Delete immediately after merge
- Rebase onto main daily:
git pull --rebase origin main - Never push directly to main
Merge Strategy (Algorithmic)
| Condition | Strategy |
|---|---|
| <3 days, single author, atomic | Rebase (linear history) |
| Multi-author or external PR | Merge (preserve context) |
| Many fixup/experimental commits | Squash (clean history) |
Main branch: fast-forward only (git config merge.ff only).
PR Workflow
- CI passes before human review (lint, type-check, test, security)
- CODEOWNERS auto-assigns reviewers
- 1-2 approvals required
- Squash fixup commits before merge
- Branch auto-deleted on merge
Context-rich PRs: Include motivation, alternatives considered, areas of concern.
Performance (Large Repos)
Enable commit-graph:
git config core.commitGraph true
git config gc.writeCommitGraph true
Clone optimization:
git clone --filter=blob:none URL # Partial clone
git sparse-checkout set src/ # Only needed paths
Large files (>10MB): Use Git LFS.
Anti-Patterns
- Mixed commits ("fix auth and update logging")
- Long-lived branches (>1 week without escalation)
- Manual merge strategy choice (use decision tree)
- Requiring sync coordination across timezones
- Large binary files in git history
- WIP/fix typo commits in main history
References
- conflict-resolution.md - Distributed async conflict patterns
- feature-flags.md - Flag-driven development for long features
- release-automation.md - Semantic versioning automation
Commit Conventions
See references/commit-conventions.md for detailed commit message standards including:
- Conventional commit format (type(scope): subject)
- Imperative mood rules
- Body and footer conventions
- Breaking change format