commit

Category: Development

Usage

commit [--all | --staged | --interactive]

Arguments

• --all: Analyze all uncommitted changes (staged + unstaged)
• --staged: Only analyze currently staged changes (default)
• --interactive: Guide through staging changes atomically before committing

Execution Method

This command delegates to the commit-expert agent (Haiku model) for fast, cost-effective execution.

Delegation: Use the Task tool with:

• subagent_type: "git-workflow:commit-expert"
• prompt: Include the mode (--staged, --all, or --interactive) and current working directory

Example:

Task(subagent_type="git-workflow:commit-expert", prompt="Run commit in --staged mode in /path/to/repo")

---

Execution Instructions for Claude Code

When this command is run, Claude Code should:

1. Analyze Changes

   • Run git status to understand current state
   • Run git diff --staged for staged changes (or git diff for all)
   • Identify the files and types of changes

2. Check for Atomic Commit Violations

   • Flag if changes span multiple unrelated concerns
   • Warn if mixing features, fixes, refactoring, and style changes
   • Suggest splitting if commit is too large (>300 lines)

3. Generate Commit Message

   • Determine appropriate type (feat, fix, docs, etc.)
   • Identify scope from file paths
   • Write clear, imperative description
   • Add body if changes are complex

4. Present for Approval

   • Show the proposed commit message
   • Allow editing before committing
   • Execute the commit

Interactive Flow

Step 1: Analyze Changes

🔍 Analyzing your changes...

Staged changes:
  M  src/auth/login.py (+45, -12)
  M  src/auth/tokens.py (+23, -5)
  A  tests/test_login.py (+89)

Unstaged changes:
  M  src/styles/button.css (+15, -3)
  M  README.md (+20)

Step 2: Atomic Commit Check

✅ Good: Changes appear to be a single logical unit
   All changes relate to authentication/login functionality

   OR

⚠️  Warning: Changes may not be atomic

   These appear to be separate concerns:
   1. Authentication changes (src/auth/*)
   2. Style changes (src/styles/button.css)
   3. Documentation (README.md)

   Recommendations:
   - Commit auth changes first: feat(auth): ...
   - Commit style changes: fix(ui): ...
   - Commit docs separately: docs: ...

   Would you like to:
   1. Proceed with current staging (not recommended)
   2. Unstage some files and commit in parts
   3. Show me how to split this commit

Step 3: Generate Commit Message

📝 Proposed commit message:

   feat(auth): add JWT refresh token rotation

   Implement automatic token refresh to improve session security.
   Tokens now rotate on each refresh, with old tokens invalidated
   after a 5-minute grace period.

   - Add refresh token rotation logic
   - Update token validation to check rotation status
   - Add tests for token refresh flow

Does this look correct?
   1. Yes, commit with this message
   2. Edit the message
   3. Change the commit type
   4. Cancel

Step 4: Commit Type Selection (if editing)

Select commit type:

   1. feat     - New feature
   2. fix      - Bug fix
   3. docs     - Documentation only
   4. style    - Code style (formatting, no logic change)
   5. refactor - Code restructuring (no feature/fix)
   6. perf     - Performance improvement
   7. test     - Adding/fixing tests
   8. build    - Build system or dependencies
   9. ci       - CI/CD configuration
   10. chore   - Maintenance tasks

Current selection: feat

Enter number or type:

Step 5: Scope Selection

Suggested scopes based on changed files:
   1. auth (src/auth/*)
   2. api (src/api/*)
   3. No scope

Enter scope or select number: auth

Step 6: Description

Write a short description (max 50 chars, imperative mood):

Examples:
   ✅ "add password reset flow"
   ✅ "fix token expiration bug"
   ❌ "added password reset" (past tense)
   ❌ "fixes the token bug" (not imperative)

Description: add JWT refresh token rotation

Step 7: Body (Optional)

Add a commit body? (Explain what and why)

   1. Yes, add details
   2. No, subject line is sufficient

[If yes]
Enter commit body (empty line to finish):
> Implement automatic token refresh to improve session security.
> Tokens now rotate on each refresh, with old tokens invalidated
> after a 5-minute grace period.
>

Step 8: Execute Commit

📋 Final commit message:

feat(auth): add JWT refresh token rotation

Implement automatic token refresh to improve session security.
Tokens now rotate on each refresh, with old tokens invalidated
after a 5-minute grace period.

Confirm commit? (yes/no/edit): yes

✅ Committed: abc1234
   feat(auth): add JWT refresh token rotation

   3 files changed, 157 insertions(+), 17 deletions(-)

Interactive Staging Mode (--interactive)

When using --interactive, guide users through staging atomic commits:

🎯 Interactive Atomic Commit Mode

Analyzing all changes to help you create atomic commits...

Found 5 modified files with different concerns:

Group 1: Authentication (recommended first commit)
   M  src/auth/login.py
   M  src/auth/tokens.py
   A  tests/test_login.py

Group 2: UI Fixes
   M  src/styles/button.css

Group 3: Documentation
   M  README.md

Stage Group 1 for commit? (yes/no/show diff): yes

[Stages files, then proceeds to commit flow]

Validation Rules

The command should enforce:

1. Message Length

   • Subject: Max 72 characters (warn at 50)
   • Body lines: Max 72 characters

2. Format

   • Type is valid conventional commit type
   • Uses imperative mood
   • No period at end of subject

3. Content Quality

   • Reject vague messages: "fix", "update", "changes", "WIP"
   • Require specificity: "fix what?", "update what?"

4. Atomic Check

   • Warn if >5 files changed
   • Warn if >300 lines changed
   • Warn if multiple file types with different purposes

5. No AI Tool Attribution

   • NEVER include "Generated with Claude Code" or similar AI attribution
   • NEVER include "Co-Authored-By: Claude" or any AI co-author footer
   • NEVER include emojis like 🤖 indicating AI generation
   • Commit messages should appear as human-written, professional commits

Error Handling

❌ No changes to commit
   Run `git status` to see the current state.

❌ Commit message too vague
   "fix bug" is not specific enough.
   Please describe what was fixed: "fix(auth): correct token expiration check"

❌ Not in a git repository
   Initialize with `git init` or navigate to a git repository.

⚠️  Unstaged changes will not be included
   Stage with `git add <file>` or use `commit --all`

Quick Commit Shortcuts

For experienced users, support quick patterns:

# Quick feature commit
commit feat auth "add password reset"

# Quick fix commit
commit fix api "handle null response"

# Quick docs commit
commit docs "update API documentation"

Integration with Git Hooks

Suggest installing hooks for enforcement:

💡 Tip: Install git hooks to enforce commit standards automatically.

   Would you like to set up:
   1. commit-msg hook (validate message format)
   2. pre-commit hook (run tests/linting)
   3. Both
   4. Skip for now

Example Outputs

Simple Commit

$ commit

🔍 Analyzing staged changes...

   M  src/utils/helpers.py (+12, -3)

✅ Single file change - good atomic commit

📝 Proposed: fix(utils): handle edge case in date parser

Commit? (yes/edit/cancel): yes

✅ Committed: def4567

Complex Commit Needing Split

$ commit --all

🔍 Analyzing all changes...

⚠️  Multiple concerns detected:

   Authentication:
      M  src/auth/login.py
      M  src/auth/session.py

   Unrelated UI fix:
      M  src/components/Header.vue

   Documentation:
      M  docs/API.md

Recommendation: Split into 3 commits

   1. Stage auth files → feat(auth): ...
   2. Stage Header.vue → fix(ui): ...
   3. Stage API.md → docs(api): ...

Would you like help staging these separately? (yes/no)