commit

Commit workflow

Turn the current working-tree changes into one or more well-formed commits. Committing only — pushing, amending, rebasing, and tagging happen only when explicitly requested, never as follow-through.

Survey first

1. git status --short — full picture of modified, renamed, untracked. Note anything already staged that you did not stage.
2. git log --oneline -10 — calibrate message style against this repo's actual history, not assumptions.
3. Read the diffs (git diff, git diff --stat, plus untracked files) well enough to explain why each change exists, not just what it touches. Never commit content you haven't looked at.
4. On main? Branch when the work is more than one commit, or an intermediate state would break while deployed — the trigger and the name are ~/.claude/CLAUDE.md § "Branch naming"'s — and from the first commit when it is bound for land, which refuses to start from main. Work in a repo that lands by pull request is bound for land: a pull-request rule on main (land step 7 has the two reads), or (#<n>) and Merge pull request subjects in the log above; a fast-forward landing leaves none. A repo's own committed convention wins, in its CONTRIBUTING.md or agent instructions: one that commits straight to main answers no, and then you commit where you stand. Say which way you went. In a shared tree git switch -c moves HEAD for everyone — see below.

An empty git status --short is the whole answer. Report that there is nothing to commit and stop; don't work through the diffs to confirm it. git diff --stat prints nothing on a clean tree, and reading that silence as a failed command rather than as the answer is a real failure mode — observed 2026-09-09, three tool calls spent re-asking the same question.

Splitting into commits

• One logical unit per commit. A rename, a new feature, and a docs catch-up are three commits even when they touch the same file. Test: could each commit's subject line be written without "and"?
• Review grouping is not a commit boundary. Parts approved together in one review are still separate commits when each stands on its own in history — independently revertible, citable, worth landing alone. Bundle only when the parts are mutually dependent for meaning: a claim and the caveat qualifying it, a rename and its call sites. Tiebreak for a docs batch — which shape would you rather read in git log a year from now?
• Every commit must be self-consistent. No commit may reference a name, file, or skill that doesn't exist yet at that point in history, and none may leave the repo in a broken intermediate state. Order accordingly (e.g. a rename lands before anything citing the new name).
• When one file straddles commits, reach for interactive git add -p where your harness offers it. Some do not: an agent shell with no interactive stdin cannot drive it, and the prompt either hangs or reads EOF. Where it is unavailable, stage through the index: scripts/stage-part.py builds the next commit's version of the file from the changed blocks a regex picks and writes it straight into the index, leaving the working tree at its final state. Read the TAKE and skip line it prints for each block, then git diff --cached, before each commit; an empty git status --short after the last commit proves the commits add up to the file on disk. Usage, limits, and the blob built by hand for changes no unchanged line separates: references/index-staging.md. Stepping the file through intermediate states on disk is the fallback — edit it down to the first commit's portion, commit, restore the next portion, commit again — and rewrites the working tree, so verify the final state matches the intended end state exactly. Stepping assumes you own the whole file. If another session has uncommitted work in it, stepping rewrites their in-flight text — commit only what is yours and leave the rest with a note.
• Stage explicit paths only. No git add -A / git add . — they silently sweep in untracked or unrelated files.
• Verify the index before each commit. git diff --cached -- <paths> must show your change and nothing else. The diff you read in the survey is not what git add staged: the file can change in between, and git add <path> takes every hunk in the file, not the hunk you meant. --stat is not enough — a foreign hunk in a file you also edited has a stat line that looks exactly right. This is the last point at which a swept-in change is free to fix — and in a shared tree it has to gate the commit rather than precede it; see below.
• Renames go through git mv (or are staged so git detects the rename) so history follows the file.