smart-commits

name

smart-commits

description

Intelligent multi-commit workflow — Analyze all pending changes (staged, unstaged, untracked), group related edits into logical units, and create multiple focused commits. Use when the user asks to: (1) commit their changes, (2) create commits from their work, (3) split changes into multiple commits, (4) organize or clean up their git history, or when there are many modified files that should not be a single commit.

Smart Commits

Analyze all pending changes in the working tree, group related edits into logical commits, and execute them as a clean sequence.

Workflow

1. Assess all changes
2. Group into logical units
3. Present the plan
4. Execute commits sequentially

---

Step 1: Assess Changes

Run these in parallel:

• git status — see all modified, staged, and untracked files
• git diff — unstaged changes with full context
• git diff --cached — already-staged changes
• git log --oneline -5 — recent commit style reference

Read the diffs carefully. Understand what each file change actually does, not just that it changed.

Step 2: Group Into Logical Units

Analyze the changes and cluster them by intent — what goal does each edit serve?

Grouping rules:

• Changes to the same feature/component belong together
• A new file and the imports/references that wire it in belong together
• Test changes go with the code they test
• Config changes go with the feature that needs them
• Pure formatting/linting changes get their own commit
• Dependency additions/removals get their own commit
• Unrelated bug fixes each get their own commit

Single-commit case: If all changes serve one clear purpose, use one commit. Do not force artificial splits.

Step 3: Present the Plan

Show the proposed commit sequence before executing:

Proposed commits:

1. Add user avatar upload endpoint
   - src/api/avatar.ts (new)
   - src/api/routes.ts (modified — added avatar route)
   - src/types/user.ts (modified — added avatarUrl field)

2. Update profile page to display avatars
   - src/components/Profile.tsx (modified)
   - src/styles/profile.css (modified)

3. Add avatar upload tests
   - tests/api/avatar.test.ts (new)

Wait for user confirmation. Adjust if requested.

Step 4: Execute Commits

For each group, in order:

1. Stage only the files for that commit: git add <file1> <file2> ...
2. Commit with a descriptive message using a HEREDOC
3. Verify with git status before moving to the next group

Note: git add -p (interactive) is not supported. Stage full files in the most relevant commit.

Commit Message Rules

Format:

<what changed> in <where/scope>

<why — one or two lines only if subject isn't self-explanatory>

Style:

• Imperative mood, 50–72 character subject line
• Be specific: "Add retry logic to payment webhook handler" not "Update handler"
• Be direct: state what was done without filler
• No period at end of subject line
• Body only when the "why" isn't obvious
• NEVER include "Co-Authored-By", "Generated by AI", or any AI attribution
• NEVER use filler like "various improvements" or "minor changes"

Good examples:

Add rate limiting to /api/auth endpoints

Prevent brute-force login attempts with 5 req/min per IP limit
using the existing Redis instance.

Fix currency rounding in invoice total calculation

Extract shared validation logic into FormValidator utility

Bad examples:

Update files                     ← too vague
Fix bug                          ← which bug?
Refactoring and cleanup          ← says nothing
Add feature and fix styling      ← should be separate commits

Edge Cases

• All changes are one unit — one commit is fine, don't force splits
• User has already staged files — respect their staging, incorporate into the plan
• Binary/generated files — ask before including lock files or build artifacts
• Sensitive files (.env, credentials) — warn and exclude by default