Git Commit Organizer

Git Commit Organizer

Turn a messy working tree into a clean, readable history. A good commit history is a tool for everyone who comes after you: atomic commits that each make sense on their own are easy to review, revert, and cherry-pick. This skill does exactly that — and it never commits or pushes behind your back. You always approve first.

What you can pass (all optional)

Recognize these from natural language, in any language; act on the intent, not the exact word.

Workflow

1. See what actually changed

git status
git diff --stat
git diff --cached --stat

Then read the real diffs for the files that matter (git diff <file> and git diff --cached <file>). Filenames alone don't tell you whether a change is a feature, a fix, or a refactor — the diff does. You're grouping by intent, so you need to understand the intent.

2. Detect an issue reference (optional)

Run git branch --show-current at the start — never assume the branch from earlier in the conversation, since the user may have switched. If the branch clearly embeds an identifier (common shapes: feature/412, 412-add-search, fix/PROJ-42), offer to include it as #412 / PROJ-42. Only attach an issue when the user asked for one or the branch obviously carries one. Never invent an issue number; if the user mentions one you can't find, ask.

3. Apply exclusions

By default, commit everything git already considers (tracked changes and new files); .gitignore is the source of truth for what to ignore. Only skip a path when the user asks — then leave those files unstaged rather than deleting or touching them.

4. Group changes into atomic commits

One logical change per commit. The aim is a history where each commit stands on its own and doesn't break the build. Useful groupings:

• A change and the tests that cover it belong together.
• An unrelated bug fix and a new feature belong in separate commits.
• Config, build, and dependency changes group naturally.
• Pure formatting (whitespace, import order) stays out of behavior-changing commits.
• Large renames or moves are usually their own commit, separate from edits.

If everything is genuinely one cohesive change, a single commit is the right answer — don't over-split for its own sake. When you plan more than one commit, or the grouping is at all ambiguous, show your proposed grouping and confirm before doing anything.

5. Pick the type and scope

Scope is optional: the area touched (a feature, module, or directory), short and lowercase.

6. Write the message

Format: type(scope): [#issue] short description

• Header — imperative mood ("add", not "added"), capitalized first word, no trailing period, kept under ~72 characters when you can.
• Body (optional, but include it when the why isn't obvious from the diff) — a blank line, then - bullet sentences describing what changed and why. Skip noise like "updated imports".
• gitmoji (only when enabled) — prefix the header using this map: feat ✨ · fix 🐛 · refactor ♻️ · perf ⚡ · test ✅ · docs 📝 · style 🎨 · build 📦 · ci 👷 · chore 🔧 · revert ⏪

7. Propose, then wait for approval

Always show the plan before committing — and wait for an explicit yes. For each planned commit, present the message and the exact files it will stage. Surprise commits are annoying to unwind and erode trust, so this gate is the one rule that never bends.

8. Stage and commit

Stage only the files for that group, then commit. For multi-line messages, use a heredoc so the body's formatting survives intact:

git add <specific files for this commit>
git commit -m "$(cat <<'EOF'
type(scope): #412 Short description

- What changed and why.
- Another meaningful detail.
EOF
)"

Show git log -1 after each commit so the user can see the result.

9. Confirm the result

After all commits, run git log --oneline -n <number of commits> so the new history is visible at a glance.

Hard rules

• Never push. Pushing is the user's decision, always. Don't run git push under any circumstances.
• Never commit without explicit approval (see step 7).
• No AI or tool attribution. Commits represent the project's human authors. Never add a Co-authored-by, Signed-off-by, or any trailer, footer, or text referencing an AI tool.
• English, imperative, atomic.

Examples

Scopes here (search, parser, http, readme) are generic on purpose — use whatever the repository actually calls its areas.

Example 1 — a single feature (a web app), no options

Changes: a search component plus its test.

feat(search): add fuzzy matching to the product search box

- Match results by approximate spelling so small typos still return hits.
- Cover the ranking edge cases with unit tests.

Example 2 — splitting unrelated work into two commits (a CLI tool)

Working tree has a bug fix and a dependency bump.

fix(parser): stop crashing on an empty config file

- Treat a missing or empty config as the defaults instead of throwing.

chore(deps): upgrade the HTTP client to 4.2.0

Example 3 — gitmoji + issue auto-detected from branch 412-retry-logic (a library)

♻️ refactor(http): #412 extract retry handling into its own module

- Move the backoff logic out of the client so it can be unit-tested in isolation.

Example 4 — documentation only

docs(readme): document the new --watch flag

When not to use this

• Writing or changing code (that's the work; this skill commits it afterwards).
• Resolving merge conflicts.
• Creating or describing pull/merge requests.
• Any remote operation — pushing, in particular, is never this skill's job.