Git Version Control

Git Version Control

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

Core Philosophy

Integration frequency is the most powerful determinant of branching success. State of DevOps research found that elite teams integrate notably more often than low performers, and continuous-integration practitioners typically integrate many times a day. "If it hurts, do it more often." — Martin Fowler[^fowler]

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

Commit Practices

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.

Commit Triggers

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

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

In LLM-assisted development, user messages signal completion:

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

Branch Discipline

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.

A branch is a single unit of work, and its contents define that unit: subunits inside a feature (e.g., a refactor the feature needed) become part of the one commit the squash creates. Concern separation happens when deciding what belongs on the branch (see the table above), so the squash takes the branch whole.

Give the squashed commit a message that summarizes the unit of work as a whole, rather than inheriting the last branch commit's message. Because the squash puts the change on mainline as one finished commit, merge only once the branch is release-ready.

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.

Branching Strategies

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

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

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.

LLM-Assisted Development Patterns

Checkpoint Commits

Git aliases (adapted from Nathan Orick's checkpoint pattern[^orick]):

[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

Commit Frequency by Context

Generate-Test-Commit-or-Revert

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.

Context Management

Recovery Patterns

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

Tool Selection

Multi-agent worktrees:

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

Anti-Patterns

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.

Common Mistakes by Background

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

Resources

Patterns:

• Martin Fowler: Branching Patterns
• ConventionalCommits.org
• Nathan Orick: Git Checkpoints

Sources

[^fowler]: Martin Fowler. 2020. Patterns for Managing Source Code Branches. Retrieved September 6, 2026 from https://martinfowler.com/articles/branching-patterns.html

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

[^orick]: Nathan Orick. Git Checkpoints. https://nathanorick.com/git-checkpoints/