/git-version-control

name: git-version-control
description: Git commit standards, branch strategy, and LLM-assisted development workflows. Use when making commits, managing branches, or working in high-velocity LLM-assisted development contexts. Covers atomic commits, conventional commits, branching strategies (trunk-based, GitHub flow), merge vs rebase decisions, and recovery patterns.

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[^robertson]

**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. </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:** Squash-merge a feature branch to mainline when it's ready for release. A branch is created only for multi-commit or overlapping work (see the table above), so its intermediate commits are implementation exploration, not history worth carrying onto mainline. Squashing lands the whole unit of work as a single mainline commit, so mainline tells the story of *what* changed, not *how you figured it out*.

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 abo