principle-version-control

Version Control & Collaboration

git log is a debugging instrument. Its quality depends entirely on the discipline of the people who wrote to it.

Atomic commits — one logical change

One commit, one reason to revert it. The test: can you describe the change in a short subject line without using "and"?

• Atomic commits make git bisect effective — a failing test traces to the exact change that introduced it.
• Atomic commits make reverts safe — reverting "add feature X" does not also undo "fix unrelated bug Y".
• Split a large change by concern: refactor first (pure mechanical moves), then behavior change, then test additions.

Commit messages — what makes them load-bearing

Subject line: imperative mood, ≤50 characters, no trailing period. Body: wrap at 72 characters, explain why, not what.

[type] Short imperative subject (≤50 chars)

Why this change was made. What would break if reverted.
Link the issue or ticket. Note non-obvious constraints.

Format schemes — Conventional Commits (feat:, fix:), [type] Subject, JIRA-prefix — are all valid conventions. Pick one; apply consistently and enforce via a commit-msg hook. Example: the swe-workbench plugin repo enforces [type] Subject via .githooks/commit-msg. Before authoring commit messages, detect the host repo's convention via the detection step in swe-workbench:workflow-commit-and-pr.

Never mix formatting and logic

Formatting commits (whitespace, import sort, rename) belong in a separate commit from behavior changes. Reviewers can skim a formatting-only commit in seconds; mixing it into a logic commit makes the diff unreadable and breaks git blame for every touched line.

Branching — feature-branch vs trunk-based

Feature branches work when: CI is slower than a few minutes, teams have >2 engineers, or releases are discrete.

• Keep branches short-lived (days, not weeks). Long-lived branches accumulate merge debt.
• Branch naming convention keeps the log readable — feat/<issue>-<slug>, fix/<slug>, chore/<slug>.