Git version control

Git Version Control

<skill_scope skill="git-version-control"> Related skills:

• software-engineer — Design principles that inform commit granularity
• test-driven-development — Test-commit cycles and when to commit during TDD

This skill covers Git commit standards, branch strategy, and LLM-assisted development workflows. It emphasizes atomic commits, meaningful commit messages, and high-frequency integration. </skill_scope>

Core Philosophy

<core_philosophy> "Commit Often, Perfect Later, Publish Once" — Seth Robertson

Integration frequency is the most powerful determinant of branching success. Elite teams integrate multiple times daily. "If it hurts, do it more often." — Martin Fowler

Revertability principle: Commits should represent meaningful units of work that could be reverted independently without breaking the system. </core_philosophy>

Commit Practices

<atomic_commits> Atomic commit decision: "If you can describe what you did in a short sentence and it makes sense, commit."

When larger commits are acceptable: Initial prototyping (squash before review), closely coupled changes, when over-granularity loses context.

Time guideline: 30-60 min ideal, max 4 hours. See <commit_triggers> for event-based commit points. </atomic_commits>

Commit Triggers

<commit_triggers> Commits are responses to completion events, not scheduled activities.

Commit discipline isn't about remembering to commit—it's about recognizing completion signals.

<observable_completion_events>

Observable Completion Events

Event	Action	Rationale
Tests pass after a change	Commit	Green is a save point
Build succeeds after a change	Commit	Working state confirmed
Linter/type checker passes	Commit	Code meets standards
Todo item marked complete	Commit	Logical unit finished
User confirms functionality	Commit	Acceptance achieved
Configuration value tweaked	Commit	Discrete, working change

Key insight: Passing tests/builds are commit signals, not just validation. Green means save your progress. </observable_completion_events>

<transition_points>

Transition Points

Transition	Action	Rationale
Before starting different task	Commit current work	Clean separation
Before risky/experimental change	Commit as checkpoint	Safe rollback point
After reverting failed approach	Commit clean state	Document decision
Before context window compaction	Commit all work	Preserve across sessions
</transition_points>

<conversational_cues>

LLM-Assisted Conversational Cues

In LLM-assisted development, user messages signal completion:

User Says	Likely Meaning	Action
"That works", "looks good", "perfect"	Acceptance	Commit
"Done", "ship it", "let's move on"	Task complete	Commit
"Now let's work on..."	Topic change	Commit previous work first
"Can you also..."	Scope expansion	Consider committing current state

Anti-pattern: Batching multiple unrelated changes because "I'll commit later." Each completion event deserves its own commit. </conversational_cues> </commit_triggers>

Branch Discipline

<branch_discipline> Before committing, verify you're on the appropriate branch. Default to committing a finished, self-contained change directly to mainline; reach for a feature branch only when the work will span more than one commit, or when it would overlap other in-progress work.

Situation	Action
Single self-contained commit, no overlap with other in-progress work	Commit directly to mainline
Work expected to span more than one commit	Create a feature branch first
Change overlaps other uncommitted or parallel work (e.g., shared files, a concurrent effort)	Isolate on a feature branch or worktree
Already on a feature branch	Commit freely

A feature branch earns its cost for two reasons: it groups a multi-commit unit of work so it can be reviewed and merged as one unit, and it isolates a change that would otherwise mix with other in-progress work. A single finished commit that meets neither condition gains nothing from a branch; mainline is the target, and creating a branch for it only adds ceremony.

LLM-assisted pattern: For one finished, self-contained change, commit it to mainline. Create a branch when you expect follow-up commits on the same unit of work, or when the change would entangle with other uncommitted work in the same files. When you genuinely can't tell whether follow-up commits are coming, ask rather than defaulting to a branch.

<merge_strategy> Merge strategy for completed branches:

Branch State	Recommended Merge	Rationale
1-2 clean commits	ff-merge or rebase-merge	Preserves meaningful history
3-5 commits	Consider squash-merge	Balance history vs. noise
>5 commits	Strongly prefer squash-merge	Collapse implementation noise
Messy/WIP commits	Squash-merge	Hide the sausage-making

Squash preference: Feature branches with more than 3-5 commits should generally be squash-merged. The intermediate commits represent implementation exploration, not meaningful history. Mainline should tell the story of what changed, not how you figured it out. </merge_strategy> </branch_discipline>

<conventional_commits> Style preference: Use full keywords (feature: not feat:). Imperative mood. Subject ≤50 chars, body wraps at 72, explain WHY.

Imperative mood test: Subject line should complete the sentence "If applied, this commit will _____."[^beams] Examples: "Add caching for API responses" ✓, "Added caching" ✗, "Adds caching" ✗.

Content principles:

• Delta, not journey — Describe what changed, not how you discovered what to change. The debugging process doesn't belong in the permanent record.
• Neutral framing — Avoid judgmental language about prior state ("fix broken", "remove wrong", "correct mistake"). Prefer neutral verbs: "update", "change", "revise".
• Outcome, not process — Don't document how you verified, tested, or arrived at the change. The commit message records what, not how you figured it out.
• Let the diff speak — Implementation details belong in the diff. The message explains intent and scope; the diff shows specifics.

Anti-pattern: "Fix incorrect attribution that cited Apple docs when the quote was actually from a community blog post" — this documents the debugging journey, uses judgmental framing, and includes detail the diff already shows.

Better: "Update source attributions" — neutral, outcome-focused, appropriate abstraction level. </conventional_commits>

<fixup_workflow>

git commit --fixup=<sha>           # Creates "fixup! Original message"
git rebase --autosquash origin/main # Squashes fixups automatically
git config --global rebase.autosquash true

</fixup_workflow>

Branching Strategies

<branching_decision>

Context	Strategy	Integration
Single production version, strong CI/CD	Trunk-Based	Multiple times daily
Continuous deployment, web apps	GitHub Flow	Daily+
Multiple production versions	Git Flow	Per release

Trunk-based: Short-lived branches (<24h), feature flags for incomplete work.

Branch naming: <category>/<ticket-id>-<description> (e.g., feature/PROJ-4521-add-oauth) </branching_decision>

<merge_vs_rebase> Rebase: Private branches, linear history, working alone. Merge: Public/shared branches, preserve collaboration history, audit trails.

GOLDEN RULE: Never rebase commits others may have based work on.

Force push safety: After rebasing a personal branch, use --force-with-lease instead of --force. It fails if someone else pushed, preventing you from overwriting their work.

git push --force-with-lease  # Safe
git push --force             # Dangerous

CRITICAL: NEVER force push to main/master branches. Even with --force-with-lease, force pushing to primary branches can destroy team history, break CI/CD pipelines, and cause widespread disruption. If this is ever requested, warn about the consequences first. </merge_vs_rebase>

<interactive_limitations> LLM-assisted context limitation: Interactive git commands (git rebase -i, git add -i, git add -p) require terminal interaction and are unavailable in LLM-assisted contexts. Use alternatives:

• Instead of git rebase -i: Use --autosquash with fixup commits
• Instead of git add -i: Use explicit git add <file> commands
• Instead of git add -p: Stage specific files, or use GUI tools </interactive_limitations>

LLM-Assisted Development Patterns

Checkpoint Commits

<llm_checkpoints> Lightweight savepoints before LLM modifications without commit overhead.

Git aliases (adapted from Nathan Orick's checkpoint pattern¹):

[alias]
checkpoint = "!f() { git add -A && git commit --no-verify -m \"SAVEPOINT\"; git tag \"checkpoint/$(date +%Y_%m_%d_%H_%M_%S)\"; git reset HEAD~1 --mixed; }; f"
listCheckpoints = tag -l "checkpoint/*"
loadCheckpoint = "!f() { git reset --hard checkpoint/$1 && git reset HEAD~1 --mixed; }; f"
deleteCheckpoint = "!f() { git tag -d checkpoint/$1; }; f"

Workflow:

git checkpoint                              # Before LLM changes
git listCheckpoints                         # View savepoints
git loadCheckpoint 2024_11_15_13_25_55      # Restore if bad

</llm_checkpoints>

Commit Frequency by Context

<commit_frequency>

Context	Frequency	Granularity
Solo prototyping	Very high	Very fine
Team feature dev	Hourly	Atomic units
Pre-review cleanup	Once	Squashed
LLM-generated code	High → Low	Fine → Squashed
</commit_frequency>

Generate-Test-Commit-or-Revert

<generate_test_commit>

1. CHECKPOINT before LLM generates code
2. TEST — run tests, build, verify
3. DECIDE — pass → commit immediately; fail → restore checkpoint
4. REVIEW — PR before merge

Key insight: AI excels at generating plausible-looking but subtly incorrect code. Time saved by being careless will dwarf the mess you'll face later.

If LLM fails 3+ times, break it down further — abstraction level too high. </generate_test_commit>

Context Management

<context_management>

git diff --no-pager --no-color HEAD^  # Full diff for review
git diff -U0                          # No context (fewer tokens)
git diff --cached                     # Staged changes only

</context_management>

Recovery Patterns

<recovery_triggers> Reflog — Recover from rebases, resets, amends. Local only, 90 days default.

git reflog
git reset --hard HEAD@{5}
git reset --hard main@{2.hours.ago}

Rerere — Auto-resolve repeated conflicts. Enable: git config --global rerere.enabled true

Bisect — O(log n) regression hunting.

git bisect start && git bisect bad HEAD && git bisect good v1.0
git bisect run make test  # Automated

</recovery_triggers>

Tool Selection

<stash_branch_worktree>

Tool	Use When
Stash	Very temporary, same day
Branch	>few hours, need sharing
Worktree	Parallel work, multi-agent

Multi-agent worktrees:

git worktree add ../agent-1-workspace feature-auth
git worktree add ../agent-2-workspace feature-payment

</stash_branch_worktree>

Anti-Patterns

<anti_patterns> Commit Anti-Patterns:

• Broken code on main: Every commit on main should pass tests and build. Use feature branches or feature flags.
• Giant mixed-concern commits: Mixing refactoring with features makes review and revert impossible. Separate concerns.
• Meaningless messages: "fix", "update", "WIP" provide no context. Explain WHY, not just WHAT.
• Committing secrets: API keys, credentials, private keys. Use .gitignore, git-secrets, or pre-commit hooks.

Branch Anti-Patterns:

• Long-lived branches (>1 week): Merge conflicts compound exponentially. Integrate frequently.
• Rebasing public branches: Rewrites shared history. Use merge for shared branches.
• No feature flags on trunk: Incomplete features on main without flags block releases.
• Force pushing to main/master: Destroys team history. Never do this.

LLM-Assisted Anti-Patterns:

• "Vibe coding" without review: LLM output requires human verification before commit.
• No checkpoints before LLM changes: Always checkpoint before LLM modifications for easy rollback.
• Context drift from large windows: Long conversations lose context. Break into smaller tasks. </anti_patterns>

Common Mistakes by Background

<common_mistakes>

From SVN/Perforce Users

• Treating branches as expensive (they're cheap in Git—use them freely)
• Expecting central locking (Git is distributed—conflicts resolve at merge)
• Not pulling before push (always git pull --rebase before pushing)
• Expecting linear history without effort (requires disciplined rebasing)

From Solo Developers

• Not considering rebase vs merge implications (matters when collaborating)
• Treating main as scratch space (use feature branches even when solo)
• Giant commits because "only I use this" (future you will regret it)
• No commit message discipline (you'll forget why in 6 months)

From GUI-Only Users

• Not understanding what commands the GUI executes (learn the underlying operations)
• Panic when something goes wrong (reflog saves almost everything)
• Not leveraging command-line power for scripting and automation </common_mistakes>

Resources

<resources> **Official:** - [Git Documentation](https://git-scm.com/docs) - [Pro Git Book](https://git-scm.com/book/en/v2)

Patterns:

• Martin Fowler: Branching Patterns
• ConventionalCommits.org
• Nathan Orick: Git Checkpoints </resources>

Sources

<sources> [^beams]: Chris Beams. 2014. How to Write a Git Commit Message. https://cbea.ms/git-commit/

Footnotes

1. Nathan Orick. Git Checkpoints. https://nathanorick.com/git-checkpoints/

   </sources> ↩