| name | atomic-commits |
| description | Break unstaged or mixed changes into small, atomic, logical git commits with Conventional Commit messages. Use when the user asks to commit, stage, or split changes — e.g. 'help me commit', 'commit my changes', 'break these into logical commits', 'what should I commit first', 'stage my changes', 'commit atomically', or 'make atomic commits'. Uses git diff, git add -p, and Conventional Commits (feat:/fix:/refactor:/chore:/docs:/test:/style:/perf:/build:/ci). |
| license | MIT |
Atomic Commits
Guide the user from a dirty working tree to a clean commit history where each commit is one logical change with a clear Conventional Commit message.
Workflow
1. Analyze changes
Run in parallel:
git status
git diff
git diff --cached
If there are too many files, also run git diff --stat for a summary.
2. Propose a commit plan
Group changes into atomic commits. Present the plan as an ordered table:
| # | Scope | Files | Commit message |
|---|
| 1 | ... | ... | type(scope): description |
Grouping rules (priority order):
- One concern per commit. Separate refactorings from features from bug fixes. If a file has changes for two concerns, plan to use
git add -p to split hunks within that file.
- Dependencies first. If commit B depends on commit A, order A before B.
- Tests alongside or after. Tests for a change go in the same commit or the immediately following one — never alone in a distant commit.
- Config/infra before features. Build/config changes that features depend on come first.
Commit message format — Conventional Commits:
type(scope): imperative-mood summary
Optional body explaining why, not what.
Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.
Scope: optional but encouraged — the module, package, or area affected.
Rules:
- Imperative mood: "add feature" not "added feature"
- Lowercase summary, no period at end
- Under 72 characters for the summary line
- Body wraps at 72 characters
3. Execute — one commit at a time
For each proposed commit:
- Stage exactly the right files/hunks:
git add <files> or git add -p <file>
- Show the user what will be committed:
git diff --cached --stat
- Create the commit:
git commit -m "type(scope): summary"
- If a pre-commit hook modifies files, handle the result (amend only if hook changes are expected and the user agrees)
Within-file splitting: When a single file contains changes for multiple commits, use git add -p interactively is not an option in this environment. Instead:
- Use
git add -p equivalents by staging specific line ranges via patch mode, or
- Create a temporary stash, apply partial changes, commit, then repeat
Practical approach: use git diff <file> to identify hunk boundaries, then git add -p with scripted responses, or advise the user to run git add -p <file> manually for that specific file if the hunks are interleaved.
4. Verify
After all commits, run git log --oneline -<N> to show the resulting history and confirm with the user.
Edge Cases
- No changes to commit: Say so. Do not create empty commits.
- Only one logical change: Skip the table; make a single commit directly.
- Untracked files: Include in the plan. Stage with
git add.
- Binary files: Cannot split with
git add -p. Assign to the most relevant commit.
- Merge conflicts: Do not attempt to resolve as part of this workflow. Alert the user.
