Git Commit Message Generator

Command

/commit-gen

Quick Start

Stage your changes and run the command:

Copy
# Stage specific files
git add src/auth.ts src/middleware.ts

# Or stage all changes
git add -A

# Run the commit message generator
/commit-gen

Claude will analyze your staged diff, determine the commit type and scope, and generate a properly formatted commit message following the Conventional Commits specification.

How It Works

1. Reads staged diff — Runs git diff --cached to capture all staged changes
2. Analyzes change intent — Determines whether changes are a feature, fix, refactor, docs update, test, or chore
3. Detects scope — Identifies the affected module or area from file paths and changed code
4. Generates subject line — Creates a concise imperative summary (max 72 characters)
5. Writes body — Explains the why behind the change, not just the what
6. Adds footer — Includes breaking change notices, issue references, and co-authors if applicable

Commit Message Format

Follows the Conventional Commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Commit Types

Type	When to Use	Example
feat	New feature or capability	feat(auth): add OAuth2 login with Google
fix	Bug fix	fix(api): handle null response from payment gateway
docs	Documentation only	docs(readme): add deployment instructions
style	Formatting, whitespace, semicolons	style(lint): apply prettier formatting
refactor	Code change that neither fixes nor adds	refactor(db): simplify query builder pattern
test	Adding or updating tests	test(auth): add integration tests for JWT flow
perf	Performance improvement	perf(api): cache user lookups with Redis
chore	Build, CI, tooling, dependencies	chore(deps): upgrade React to v19
ci	CI/CD pipeline changes	ci(github): add Node 22 to test matrix
build	Build system or external deps	build(webpack): optimize chunk splitting
revert	Reverts a previous commit	revert: feat(auth): add OAuth2 login

Scope Guidelines

Scope identifies the module or area affected:

Frontend scopes:

• ui, components, pages, forms, layout, hooks, state, styles

Backend scopes:

• api, auth, db, middleware, routes, services, models, cache

Infrastructure scopes:

• ci, docker, k8s, terraform, nginx, deps, config

Cross-cutting scopes:

• security, logging, monitoring, i18n, a11y, seo

Subject Line Rules

• Imperative mood — "add feature" not "added feature" or "adds feature"
• No capitalization — lowercase first letter after the colon
• No period — don't end with a period
• Max 72 characters — keeps git log --oneline readable
• Be specific — "fix auth token expiry" not "fix bug"

Good vs Bad Subjects

Copy
# Good
feat(cart): add quantity selector to product cards
fix(auth): prevent session fixation on login
refactor(api): extract validation into middleware

# Bad
feat: update stuff                    # Too vague
Fix(auth): Fixed the login bug.       # Wrong mood, capitalized, period
feat(authentication-module): add new JWT-based authentication system with refresh tokens  # Too long

Body Guidelines

The body explains why the change was made, not what changed (the diff shows that):

feat(auth): add rate limiting to login endpoint

Brute force attacks were detected in production logs showing
100+ login attempts per minute from single IPs. This adds
rate limiting of 5 attempts per minute per IP using Redis
as the backing store.

The rate limit window resets after 60 seconds of no attempts.
Failed attempts return 429 with a Retry-After header.

Body Best Practices

• Wrap at 72 characters per line
• Separate subject from body with a blank line
• Explain the motivation and contrast with previous behavior
• Use bullet points for multiple changes:

refactor(core): restructure authentication module

- Move auth logic from controllers to service layer
- Extract validation into separate validators
- Update tests to use new service structure
- Add integration tests for auth flow

Footer Conventions

Breaking Changes

feat(api)!: restructure API response format

All API responses now follow the JSON:API specification
for consistency across all endpoints.

BREAKING CHANGE: Response structure changed from
{ "data": {...}, "status": "ok" } to
{ "data": {...}, "meta": {...}, "links": {...} }

Migration: Update client code to access data via
response.data instead of response.body

Issue References

fix(checkout): calculate tax correctly for EU customers

Tax calculation was using the merchant's country instead
of the customer's billing address country.

Fixes #1234
Ref #1200
Closes #1235

Co-Authors

feat(dashboard): add real-time analytics widget

Co-authored-by: Jane Smith <[email protected]>
Co-authored-by: Bob Wilson <[email protected]>

Multi-File Commit Strategy

When your staged changes span multiple files:

Related Changes — Single Commit

If all changes serve one purpose, use one commit:

Copy
git add src/services/auth.ts src/middleware/auth.ts src/tests/auth.test.ts
/commit-gen
# Result: feat(auth): add JWT token refresh mechanism

Unrelated Changes — Split Into Multiple Commits

Use interactive staging to create atomic commits:

Copy
# Stage only auth-related changes
git add -p src/services/auth.ts
/commit-gen
# Result: fix(auth): handle expired refresh tokens

# Stage remaining changes
git add -p src/utils/format.ts
/commit-gen  
# Result: style(utils): standardize date formatting

Advanced Usage

Amending the Last Commit

If the generated message needs tweaking:

Copy
# Change the message
git commit --amend -m "feat(auth): add OAuth2 with Google and GitHub"

# Add forgotten files without changing message
git add forgotten-file.ts
git commit --amend --no-edit

Commit with Verification

Copy
# Preview what will be committed
git diff --staged --stat
git diff --staged

# Generate message
/commit-gen

# Verify the commit
git log -1 --format=fuller

Selective Staging

Copy
# Stage hunks interactively
git add -p

# Review staged vs unstaged
git diff --staged    # What will be committed
git diff             # What won't be committed

# Generate message for staged changes only
/commit-gen

Commit Quality Checklist

• Changes are staged with git add
• Commit is atomic (one logical change)
• Type correctly identifies the change nature
• Scope accurately reflects the affected area
• Subject is under 72 characters, imperative mood
• Body explains why, not just what
• Breaking changes are marked with ! and BREAKING CHANGE: footer
• Related issues are referenced
• Tests pass before committing
• No unrelated changes mixed in

Configuration

Customize the generator behavior in your project's Claude settings:

Copy
{
  "commitStyle": "conventional",
  "maxSubjectLength": 72,
  "requireScope": true,
  "allowedTypes": ["feat", "fix", "docs", "style", "refactor", "test", "chore", "perf", "ci", "build"],
  "allowedScopes": ["api", "ui", "auth", "db", "config"],
  "requireBody": false,
  "requireIssueRef": false
}

Troubleshooting

No staged changes detected

Copy
# Check if anything is staged
git status
git diff --staged

# Stage changes first
git add <files>

Generated message is too generic

This usually means the diff is too large. Split into smaller, focused commits:

Copy
# Stage related files only
git add src/auth/*.ts
/commit-gen

Wrong type detected

The generator infers type from the diff. If it misidentifies, you can amend:

Copy
git commit --amend -m "fix(auth): correct type — was detected as refactor"