Commit planning
Grouping
A commit is one reason to change. A reviewer should be able to read it alone and revert it alone.
- Keep together: an implementation plus its tests, a type change plus its call sites, a migration plus the code that uses it, a dependency bump plus the code that needs it.
- Separate: independent features, a bug fix found while working on a feature, a pure refactor that the feature builds on (commit it first), formatting-only churn, and documentation that stands on its own.
- Don't split: a single coherent change into per-file commits, and a rename plus its fallout into separate commits.
- Order: commit so that every commit builds, with refactors and dependencies first.
- Exclude: anything you can't explain from the diff. Leave it uncommitted and ask about it.
Changes that were already staged
When you start, compare git diff --cached with git diff. Treat content the user already staged as a deliberate grouping.
- It fits the plan: Commit it as staged, either on its own or with closely matching changes.
- It cuts across the plan: This includes staged changes that are unrelated to what you're pushing, or a file partially staged in a way that splits your groups. Show the conflict and ask.
- Never unstage it silently. If you must change the index temporarily, save
git diff --cached --binaryto a file first, and restore it afterwards withgit apply --cached.
Partial staging
Interactive git add -p isn't available. Stage hunks from a patch instead:
git diff -- path/to/file > /tmp/sp-full.patch
# copy only the wanted hunks (keep the diff headers) into /tmp/sp-part.patch
git apply --cached --check --recount /tmp/sp-part.patch
git apply --cached --recount /tmp/sp-part.patch
git diff --cached -- path/to/file # confirm only the intended hunks are staged- A single hunk mixes two concerns: Split it by editing the patch's
+and-lines, and keep the context lines exact. - Mixed content in an untracked file: Run
git add -N <file>first, so that its contents appear ingit diff. - Never edit the working tree to make staging easier.
Messages
- Detect the convention: Look at the recent subjects in the context output, plus any commitlint, commitizen, or
.gitmessageconfiguration. Use Conventional Commits (type(scope): subject) when the repository uses them, or when it has no clear convention. Otherwise match the style it has. - Types:
feat,fix,refactor,perf,test,docs,build,ci,chore,style,revert. Use a scope only where the history uses scopes. Mark a breaking change with!and add aBREAKING CHANGE:footer. - Subject: Use the imperative mood. Keep it to 72 characters or fewer, with no trailing period. Name the behavior, for example
fix(auth): refresh session before expiry check, notupdate auth.ts. - Body: Add one only when the reason for the change isn't obvious from the diff. Explain the reason and any constraints, and wrap lines at 72 characters.
- Trailers: Add
Signed-off-by(usegit commit -s) or issue references only when the repository requires them. Never add a co-author trailer for an AI or agent.
File hygiene
Never commit these unless the user insists after a warning:
- Secrets and credentials:
.env*(except*.exampleand*.sample), keys, certificates,credentials*,*.tfstate,.npmrcor.pypircfiles that contain tokens. - Generated output:
node_modules/,dist/,build/,.next/,coverage/,target/,__pycache__/, and similar. The exception is a generated file the repository already tracks; regenerate it with the repository's own command. - Editor and OS files, logs,
*.orig,*.rej, temporary or scratch files, and large binaries. - Lockfile changes that don't match a manifest change, or a manifest change without its lockfile update. Also unexpected major version bumps, and registry URL changes.
When an ignorable file keeps showing up, suggest adding it to .gitignore as a separate change. Don't do that silently.