Commit

Make Atomic Git Commits

Core Principle

Each commit = one logical change, one intention. If you cannot describe the commit in one sentence without "and", split it.

• "Fix null pointer dereference in checkout flow" — passes
• "Fix cart quantity bug and update user model and add tests" — fails ("and") → three commits

Each commit must be independent (understandable alone), buildable (compiles, tests pass), and complete (no partial work).

Atomic ≠ tiny. A refactor touching 20 files can be one atomic commit if it does one thing. The test: can it be reverted independently?

Red Flags — Split Now

• Subject contains "and" or two commit types apply (e.g. feat + fix)
• You're tempted to write "misc", "various", "cleanup", or "updates"
• The body describes unrelated effects
• Change A can be reverted independently from change B

Revert-Boundary Gate

Before committing a large staged diff, list the independent revert boundaries in one-line phrases. If more than one phrase is required, split the commit — even if the changes are coupled or all tests only pass after the full refactor. "They are coupled" is not an atomicity argument; use transitional buildable commits or explain why no independent revert boundary exists.

Common Rationalizations

Message Rules

Discover Convention First

Run git log --oneline -20 and match the repo's existing format exactly:

• Prefix format: Conventional types (feat:, fix:)? Module names (auth:, ui:)? None?
• Capitalization/punctuation: Sentence case or lowercase? Trailing period?
• Scopes: If parenthesized scopes exist (feat(auth):), use existing ones. Never invent scopes. Never use commit types as scopes (fix(perf): is wrong when perf is intended as a type).

No commit history? Pick one convention and apply consistently. Conventional Commits (type(scope): summary) or plain prefix (area: summary).

Subject Line

• Max 72 characters. Always commit through the length gate script — never call git commit directly. Write the matching script below to an executable file and run it; it enforces the limit and is the only sanctioned commit command. Never count characters yourself — it does not work.

  #!/usr/bin/env bash
  # commit-length-gate.sh "subject" ["body paragraph" ...] — each arg after the subject becomes a -m body paragraph.
  set -euo pipefail
  [[ $# -ge 1 ]] || { echo "usage: $0 \"subject\" [\"body\"...]" >&2; exit 1; }
  s=$1; shift
  ((${#s} <= 72)) || { echo "Subject too long: ${#s} chars (max 72): $s" >&2; exit 1; }
  a=(-m "$s"); for b in "$@"; do a+=(-m "$b"); done
  exec git commit "${a[@]}"
  

  # commit-length-gate.ps1 "subject" ["body paragraph" ...] — each arg after the subject becomes a -m body paragraph.
  param([Parameter(Mandatory, Position = 0)][string]$Subject, [Parameter(ValueFromRemainingArguments)][string[]]$Body)
  if ($Subject.Length -gt 72) { throw "Subject too long: $($Subject.Length) chars (max 72)`n$Subject" }
  $c = @('-m', $Subject) + @(foreach ($p in $Body) { '-m', $p })
  git commit @c
  

• Start with an imperative verb after any prefix: add, fix, extract, remove. Not feature, make, let's.

• Formal technical language. No conversational constructions ("make X Y, not Z", "do X instead of Y").

Body

Prefer no body. Make the subject self-explanatory. Only add a body when the subject genuinely cannot carry the explanation.

Body explains WHY, not WHAT — the diff shows what changed. Write prose, never bullet points or checklists. A one-line why-statement is almost always sufficient; if you need more than 3 -m paragraphs, your commit isn't atomic.

Forbidden in Messages

• File lists: Git tracks files. "3 files changed, 5 tests added" is noise.
• Plan-internal terminology: No task numbers ("Task 3"), wave/phase names, step labels. Commits must stand alone in git log. Reference ticket IDs from issue trackers, not planning artifacts.

Commit Types

When a change is both restructuring and performance, choose the emphasis.

Common Mistakes

Emergency Exception

During active P1 outages, land the minimal fix first. Clean up history in a follow-up commit.