Claude Command: Commit

Create well-formatted commits using conventional commit messages.

Usage

/commit
/commit --atomic
/commit --no-verify
/commit --dry-run
/commit --amend

Security Invariants

Two rules cannot be bypassed by any flag, including --no-verify:

1. Credential scanning runs on every commit. --no-verify skips git hooks but never the secret scan.
2. The command never runs git add on initial staging. The user stages their own changes. (Exceptions: after the user confirms a split proposal, the command may re-stage groups on their behalf — see Splitting Commits; and under --atomic, where group-by-group staging is the point — see Atomic Mode.)

Step-by-Step Flow

1. Check for staged files — git diff --cached --name-only. If empty, abort:

   Error: No staged files found. Stage changes with `git add` before running /commit.

   Exceptions: with --amend, proceed even when nothing is staged (message-only amends are valid); with --atomic, work from the whole tree — see Atomic Mode.
2. Inspect the diff — git diff --cached. If empty (binary-only changes), fall back to filenames, git diff --cached --summary, and extensions to infer intent.
3. Scan for credentials — see Credential Scanning. Unbypassable.
4. Hook handling — never run hooks manually. git commit invokes them natively and honours core.hooksPath (Husky, lefthook, pre-commit framework). Running them ahead of time causes double execution and misses tools that don't write to .git/hooks/. If the commit fails on a hook, show the full output and prompt [R]etry / [S]kip hook (re-run with --no-verify) / [A]bort.
5. Analyze the diff — if multiple distinct concerns are present, propose splitting (see Splitting Commits).
6. Generate commit message(s) — see Commit Message Format.
7. Dry-run short-circuit — under --dry-run, print the proposed message(s) and staged file list, then exit.
8. Commit — execute git commit. Pass --no-verify through when set.

Commit Message Format

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

[optional body]

[optional footer]

Subject line rules

• Type — one of the standard types below. Required.
• Scope — area of the codebase affected. Inferred from paths (see below).
• ! — appended for breaking changes. E.g. feat!: or feat(api)!:. Always paired with a BREAKING CHANGE: footer.
• Description — imperative mood ("add feature", not "added" or "adds").
• Lowercase after the colon. feat: add login, not feat: Add login. Changelog tooling depends on this.
• No trailing period.
• Length — ≤ 72 characters total; aim for ≤ 50.

When to write a body

The body should explain why, not what. The diff already shows what changed.

Include a body when a teammate reading the commit in six months wouldn't understand the reason from the diff alone — subtle bug fixes, performance tradeoffs, design decisions, non-obvious constraints.

Skip the body when the diff is self-explanatory — renames, formatting, dependency bumps, straightforward additions.

Wrap at 72 characters.

Body anti-patterns to avoid

• Bullet lists when prose would read better. Reserve bullets for genuinely enumerable items.
• Restating filenames or function names already visible in the diff.
• Filler openings like "This commit...", "Updates the code to...", "Made changes that...".
• Marketing adjectives — "comprehensive", "robust", "seamless", "powerful".
• Summarising the diff line by line. If the body reads like a changelog of the diff, delete it.

Footers

• BREAKING CHANGE: <description> — required when ! is in the subject.
• Refs #123 — default for issue references inferred from the branch.
• Closes #123 — only when the user explicitly says the issue is done. Never inferred from the diff alone; the command can't reliably know whether a change completes an issue without reading it.
• Co-authored-by: — only for real human pairing partners.

Never add AI attribution. No "Generated by Claude", no "Co-authored-by: Claude".

Scope inference

• All files under one directory → that directory is the scope. Applied silently.
• Files span multiple paths but share a meaningful segment (src/auth/... + tests/auth/...) → use the shared segment.
• Unrelated paths → omit the scope.
• Ambiguous (two equally plausible candidates) → prompt the user.

Breaking change detection

Signals: removed/renamed public exports, deleted endpoints, renamed CLI flags, schema-incompatible migrations, major version bumps. When detected:

1. Append ! after the type or type+scope.
2. Add a BREAKING CHANGE: footer with the migration path.
3. Surface the detection to the user before committing.

Issue references from branch names

• feat/123-login → Refs #123
• fix/ENG-456-null-check → Refs ENG-456
• users/alice/feat/789-thing → Refs #789

Always Refs, never Closes, unless the user explicitly confirms.

Revert commits

revert: <original subject>

This reverts commit <sha>.

<optional reason for the revert>

Commit Types

Convey nuance through scope or body — fix(security):, chore(deps):, feat(a11y): — rather than inventing types. Stable types matter for commitlint, semantic-release, and changelogs.

When multiple types apply and splitting isn't practical, pick by user-visible impact: feat > fix > perf > refactor > others. A feature that incidentally fixes a latent bug is announced as a feat with the fix noted in the body — that's how it'll read in the changelog regardless.

Credential Scanning

Runs unconditionally on every commit.

Detection of existing scanners

Before running the built-in scan, check for these markers:

• .pre-commit-config.yaml containing detect-secrets, gitleaks, or trufflehog
• .gitleaks.toml / .gitleaksignore
• .secrets.baseline (detect-secrets)
• A secret-scan / gitleaks job in .github/workflows/

If any are found, the repo already has secret scanning wired up and the built-in scan is skipped (with a one-line notice). The hooks will catch anything during git commit anyway, and duplicating the work just doubles the false-positive surface.

Built-in scan patterns

Generic high-entropy heuristics and password = "..." style regexes are intentionally omitted — they flag hashes, UUIDs, test fixtures, and parameter names with high frequency. Vendor prefixes catch real secrets reliably; everything else is noise.

Allowlisting false positives

• Inline: a # pragma: allowlist-secret (or // pragma: allowlist-secret) comment on the same line suppresses scanning.
• Persistent: a .commit-allowlist file at repo root, one finding per line as path:line:pattern, suppresses repeats.

Resolution flow

When findings exist, list each with file, line, and pattern type. Prompt [B]lock / [A]llow once / [P]ersistently allow. Any Block aborts the commit.

Splitting Commits

Trigger criteria — different concerns, mixed types, source vs docs/config mixed, or a diff large enough that one message can't honestly describe it.

Flow

1. Propose groupings with rationale.
2. Show files and proposed message for each.
3. User confirms or adjusts.
4. The command then handles staging itself: git reset to unstage everything, then git add each group in turn and commit it before moving to the next. (The user already gave intent by staging initially and confirming the split; re-running git add manually for each group is unnecessary friction.)

Atomic Mode

/commit --atomic works from the working tree without pre-staging — for the "based on the changes, do atomic commits" flow. Also enter this mode when the user asks in prose for atomic commits with nothing staged.

1. Analyze all uncommitted changes: staged, unstaged, and untracked project files. Never sweep in files that look unrelated to the session's work (scratch files, local configs) without listing them explicitly first.
2. Group by concern and show the proposed groups, each with its files and commit message.
3. On confirmation, stage and commit each group in turn — same mechanics as a confirmed split. Credential scanning and all message rules apply per commit.
4. Never push. Never create a branch. No AI attribution — same as every mode.

Command Options

Examples

feat(auth): add OAuth2 login via Google

refactor(pipeline): replace sync file processor with async queue

The sync implementation blocked the event loop on files over a few MB,
which surfaced as request timeouts under load. The async queue caps
concurrency at a configurable limit so memory stays bounded.

Refs #118

feat(api)!: rename /users endpoint to /accounts

BREAKING CHANGE: /users is no longer available. Update all clients
to use /accounts. Response schema is unchanged.

Refs #204

revert: feat(auth): add OAuth2 login via Google

This reverts commit a1b2c3d.

The Google OAuth flow doesn't handle workspace-restricted accounts
correctly; reverting until #231 lands.