atomic-commits

Atomic commits

Atomic = one concern per commit, not one file. A healthy average sits around 5–10 files / ~100 lines per commit; megacommits aren't.

The rules

1. Use the project's committer wrapper if present. Look for scripts/committer (or equivalent). It enforces the rules below automatically and is preferred over raw git commit. A reference implementation lives at templates/committer in this plugin — symlink it into scripts/committer if the project doesn't have one.
2. Stage explicit paths. Never git add ., git add -A, git add --all. List the files you intend to commit by name.
3. Conventional Commits format. type(scope): subject — types are feat, fix, refactor, test, docs, perf, build, ci, chore, style, revert.
4. Verb-led, specific subjects. extract X from Y, unify Z handlers, drop unused Q. Never cleanup, improve, update stuff, misc changes.
5. One concern per commit. Split unrelated changes into separate commits even if they're in the same file.
6. Never bypass hooks. No --no-verify, -n, --no-gpg-sign, -c commit.gpgsign=false. If a hook fails, see hook-discipline.
7. Soft warning at ~400 lines diff. Big diffs are sometimes correct (scaffolds, large renames) but usually a sign two commits got bundled. Pause and reconsider before pushing through.

Why

A single megacommit is expensive to lose and impossible to review. If the agent crashes mid-run, everything since the last commit is gone. Atomic commits are cheap to lose, easy to review, and preserve the why of each change in the log. Reflexive git add -A is the most common path to accidentally bundling secrets, build artifacts, and unrelated work.

How to apply

# Preferred — project committer wrapper
scripts/committer feat\(parser\): extract token stream from lexer -- src/parser.py tests/test_parser.py

# Acceptable fallback
git add src/parser.py tests/test_parser.py
git commit -m "feat(parser): extract token stream from lexer"

Commit early, commit often. After each green test pass, commit. Don't batch modules waiting for a "better" commit point — there isn't one.

When you don't need permission

For atomic commits of work you did in this session, commit autonomously after each unit of work. Don't sweep up unrelated in-progress changes from the working tree without saying so.

Exit condition

The commit landed, hooks passed, the message names what changed and the diff contains only that concern.