Smart Commit
Create meaningful conventional commits by analyzing your actual changes.
Workflow
Step 1: Assess the working tree
Run these commands to understand the current state:
git status
git diff --stat
git diff --cached --statStep 2: Handle unstaged changes
If nothing is staged (git diff --cached is empty):
- Show the user what files have changed
- Suggest what to stage based on logical grouping (e.g., "these 3 files are all related to the auth refactor")
- Ask if they want to stage all, or select specific files
- Stage the approved files with
git add <files>
If changes are already staged, proceed to analysis.
Step 3: Analyze the diff
Read the full staged diff:
git diff --cachedDetermine the commit type from the changes:
| Signal | Type |
|---|---|
| New files with new functionality | feat |
| New test files or test additions | test |
| Changes to existing logic fixing incorrect behavior | fix |
| Structural changes without behavior change | refactor |
| package.json, tsconfig, CI config changes | chore |
| Build/bundler config changes | build |
| README, docs, comments only | docs |
| Formatting, whitespace, semicolons only | style |
| Performance improvements | perf |
Determine the scope from the primary directory or module affected:
src/api/->apisrc/components/auth/->authtests/->tests- Root config files -> omit scope
- Multiple unrelated areas -> omit scope
Step 4: Check for user overrides
If the user provided arguments via $ARGUMENTS:
- Single word (e.g.,
fix) -> use as commit type - Two words (e.g.,
refactor api) -> use as type and scope - Otherwise -> use auto-detected values
Step 5: Compose the commit message
Format: type(scope): imperative short description
Rules:
- Subject line max 72 characters
- Use imperative mood ("add", "fix", "refactor", not "added", "fixes")
- Don't end with a period
- Body explains WHY this change was made, not what changed (the diff shows what)
- If changes are trivial (typo fix, formatting), skip the body
Example:
feat(auth): add JWT refresh token rotation
Tokens were expiring mid-session for users with slow connections.
Rotating refresh tokens extends the session without compromising
security, since each refresh token can only be used once.Step 6: Confirm and commit
Show the user the proposed commit message and ask for confirmation.
If confirmed, run:
git commit -m "<message>"Then verify with:
git log --oneline -1Show the committed hash and message.
Tips
- Run after completing a logical unit of work, not after every file change
- If the diff is too large for one commit, suggest splitting into multiple commits
- For breaking changes, add
!after the scope:feat(api)!: change response format - The body should answer "if someone reads this commit in 6 months, will they understand WHY?"