Version Control

Concept of the skill

Use when designing or maintaining the shape of a repository's git history — choosing a branching model, deciding rebase vs merge, sizing commits, linking commits to tracker tickets, tagging releases, running parallel work across worktrees, and resolving the merge conflicts that arise from any of the above.

Coverage

• Branching strategy selection: trunk-based development (default for product teams), Git Flow (only for shipped libraries with multiple supported versions), and the warning signs that a chosen model is failing
• Atomic commit discipline: one logical change per commit, the test that distinguishes "atomic" from "small," and how to split a commit that snuck two changes together
• History shape: rebase over merge for feature integration, squash on merge for keeping main linear, when to allow merge commits (rare — release branches with parallel hotfix history)
• Provenance: the convention that every commit references its originating tracker ticket, and the enforcement options (commit-message hook, CI check, social convention)
• Release tagging: annotated tags with provenance, SemVer 2.0.0 mapping, hotfix flow from a tag without polluting main
• Worktree lifecycle: when to use worktrees, how to keep them clean, and the multi-agent failure mode worktrees prevent (parallel-session index contamination)
• Path-limited commits: the git commit --only -- <paths> discipline that prevents a parallel session from injecting unrelated staged files into your commit
• Conflict resolution: structural conflicts (one side renamed, one side edited) versus content conflicts; when to abandon a rebase and recreate the branch

Philosophy of the skill

A repository's history is a decision log. When the log is noisy — merge commits where rebases would have been cleaner, multi-purpose commits that mix a fix with a feature, missing tracker IDs, branches that lived for a month — the team loses the ability to answer two questions that matter under pressure: "why did this change?" and "can I revert just this without taking everything else with it?" Both questions become archaeology rather than lookup.