Commit Message

Suggest clear, conventional commit messages from git diff, staged changes, and context.

When to Use

• •User is about to commit and asks for a message
• •User wants to summarize staged or unstaged changes
• •User asks "what commit message should I use?"

Workflow

1. •Inspect changes: git diff --staged (or git diff if nothing staged)
2. •Identify type: feat, fix, docs, style, refactor, test, chore
3. •Identify scope: optional, e.g. auth, api, ui
4. •Summarize: Short imperative description
5. •Optional body: Why and what, if non-obvious
6. •Optional footer: Fixes #N, Breaking change

Conventional Commit Format

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

[optional body]

[optional footer]

Types

Scope (optional)

• •Package, module, or area: auth, api, ui, cli
• •Infer from changed paths: src/auth/ → scope auth

Short description

• •Imperative, lowercase, no period: "add login" not "added login"
• •Under ~50 chars for subject line
• •What changed, not why (why can go in body)

Examples

From diff that adds OAuth login:

feat(auth): add OAuth2 login

From diff that fixes null in user lookup:

fix(api): handle null in user lookup

From diff that only touches README:

docs: update README installation steps

From diff that refactors store without changing behavior:

refactor(store): extract user selectors

From diff that upgrades deps:

chore(deps): upgrade react to 18.2

Body (optional)

Use when:

• •Why isn't obvious from the diff
• •Breaking change
• •Non-trivial rationale

feat(api): add pagination to list endpoint

BREAKING CHANGE: list endpoint now returns { items, nextCursor } instead of a plain array.

Footer (optional)

• •Fixes #123 or Closes #123 for issues
• •Breaking change: ... for breaking changes

Gathering Context

# Staged changes (preferred)
git diff --staged --stat
git diff --staged

# Unstaged if nothing staged
git diff --stat
git diff

# Recent commits for style
git log -3 --oneline

Infer type and scope from:

• •File paths (e.g. src/auth/, docs/)
• •Content (new function vs rename vs delete)
• •Test files → type test or mention in body

Multiple Logical Changes

If staged changes mix multiple concerns:

• •Suggest splitting: "Consider committing in 2 commits: 1) feat(auth): ... 2) docs: ..."
• •Or suggest one message that covers the main theme and note "includes X and Y" in body

Tone

• •Neutral and factual
• •Imperative mood ("add" not "added")
• •No emoji or hype in the message unless project convention uses them

Anti-Patterns

• •❌ "fix stuff", "update", "WIP"
• •❌ Past tense ("fixed bug")
• •❌ Period at end of subject
• •❌ Very long subject line (wrap in body instead)