Commit
Conventional commit. No confirm. No dry-run.
Flow
- Parallel:
git status + git diff --staged.
- Nothing staged -> stage relevant. Paths >
-A. Never .env / creds / secrets.
- Parallel:
git diff --staged (if just staged) + git log --oneline -5.
- Read diff -> one commit or many (see Atomic) -> write msg.
- Commit now. Many groups + already mass-staged ->
git restore --staged . to unstage (modern idiom; git reset HEAD also fine), then stage+commit per group. Loop til clean.
- Print hash + one-liner per commit.
Atomic
Mixed concerns -> split. No mega-commit.
Group by:
- type —
feat / fix / docs / refactor / test never share
- scope — diff modules/pkgs = diff commits
- logical unit — one thing per commit. Each builds + tests alone.
Split signals:
1 unrelated area
- behavior + format/rename mixed (format separate)
- summary needs "and" / "also" / "+"
- unsure -> ask user how to group
Msg Format
<header>
<footer>
header required. footer optional. No body, ever.
If the header can't carry the change, the commit isn't atomic -> split it (see Atomic). The "why" lives in the PR body, the issue, or the code comment — not here.
Header
<type>(<scope>): <short summary>
- type:
build|chore|ci|docs|feat|fix|perf|refactor|test
- scope: optional. Affected area/module/pkg. Lowercase, kebab/short noun. One scope only — pick the dominant one, else omit.
- summary: imperative present ("add" not "added"/"adds"), lowercase, no trailing
.
- whole header ≤ 72 chars. Tighter is better; aim ≤ 50 for the summary itself.
- no ticket IDs in header (go in footer). No emoji. No
[WIP].
Type Pick
Pick the most specific. Behavior change > non-behavior. User-visible > internal.
SemVer bump column is the canonical mapping used by cliff.toml across all repositories. feat!: / BREAKING CHANGE: footer always -> MAJOR regardless of type.
| Type |
SemVer |
Use when |
Examples |
| feat |
MINOR |
New user-visible capability or API |
new endpoint, new CLI flag, new component, new public function |
| fix |
PATCH |
Restoring intended behavior after a defect |
crash on null input, wrong calc, regression repair |
| perf |
PATCH |
Same behavior, measurably faster / lighter |
cache hot path, drop O(n²) loop, lazy-load |
| refactor |
PATCH |
Code shape changes; behavior identical |
rename, extract, inline, move file, dedupe — no API or output change |
| test |
none |
Test files only |
add coverage, fix flake, rename test |
| docs |
none |
Docs / comments / README / changelog only |
prose edits, JSDoc, ADRs, doc-only typos |
| build |
none |
Build system, deps, lockfiles, packaging |
package.json deps, uv.lock, Dockerfile, bundler config |
| ci |
none |
CI/CD pipeline config |
GH Actions workflow, release pipeline, branch protection scripts |
| chore |
none |
Repository maintenance with no code/build/CI/docs effect |
.gitignore, editor config, tooling configs not tied to build |
Tiebreakers
- Bug ->
fix > refactor > chore.
- Perf ->
perf > refactor.
- New feature ships with its tests -> single
feat commit. Tests for existing code -> test.
- README typo ->
docs. README rewrite that ships new product info -> still docs (no code).
- Bumping a dep that fixes a bug here ->
fix (your bug) or build (just the bump). Pick by user-visible effect.
- Lockfile-only churn from
install -> build. Tooling config like biome.json formatting rules -> chore. CI workflow YAML -> ci.
- Renaming for clarity ->
refactor. Renaming to land a new API -> part of the feat.
- Formatting / whitespace -> separate
chore commit.
- Revert ->
revert: prefix, never one of the above (see Revert).
Footer
Trailers only. One per line, Token: value, after a single blank line below the header. Order: breaking change -> deprecation -> refs.
Allowed tokens:
BREAKING CHANGE: <summary> — exact spelling (Angular spec). Detail + migration steps follow on subsequent lines, ≤ 5 lines.DEPRECATED: <what> — same shape; include upgrade path. ≤ 5 lines.Fixes #<n> / Closes #<n> / Resolves #<n> — issue auto-close. Multiple -> one per line or comma-separated.Refs: #<n> / See: <url> — non-closing references.
BREAKING CHANGE: <summary>
<detail + migration>
Fixes #<n>
DEPRECATED: <what>
<detail + upgrade path>
Closes #<n>
Footer rules:
- No
Co-Authored-By: / "Generated with Claude" / tool-attribution trailers ever, unless user explicitly asks. Why -> standing user policy.
- No
Signed-off-by: unless the repository's CONTRIBUTING requires DCO.
- No empty/placeholder trailers. No footer at all is fine.
- Breaking change without migration steps -> ask user before committing. Reviewers need the upgrade path.
Revert
revert: + reverted header, then a single line: This reverts commit <SHA>.
Reason -> append to that same line only if non-obvious. Nothing else.
Rules
- One logical change per commit. Else split.
- Never
--no-verify / --no-gpg-sign unless asked. Why -> hooks catch real failures (lint, type, secret scan); skipping = shipping broken code.
- Pre-commit hook fail -> fix + re-stage + new commit. No amend. Why -> hook fail means the commit didn't happen;
--amend would modify the previous (unrelated) commit and silently rewrite it.
1---2name: git-commit3description: Run git commit using Angular conventional commit format. Use when the user asks to commit, create a commit, /git-commit, or save changes to git. Also trigger on "snapshot this", "save my work", "check in changes", "wrap up", "ship this locally", or whenever the user finishes a logical unit of work and the tree is dirty. Boundary with `git-pr-create`: this skill owns only the explicitly local framing — bare "ship this" / "ship it" / "send for review" means the work should leave the machine, which is `git-pr-create`'s flow. Stages relevant files and commits immediately without asking for confirmation.4---56# Commit78Conventional commit. No confirm. No dry-run.910## Flow11121. Parallel: `git status` + `git diff --staged`.132. Nothing staged -> stage relevant. Paths > `-A`. Never `.env` / creds / secrets.143. Parallel: `git diff --staged` (if just staged) + `git log --oneline -5`.154. Read diff -> one commit or many (see **Atomic**) -> write msg.165. Commit now. Many groups + already mass-staged -> `git restore --staged .` to unstage (modern idiom; `git reset HEAD` also fine), then stage+commit per group. Loop til clean.176. Print hash + one-liner per commit.1819## Atomic2021Mixed concerns -> split. No mega-commit.2223Group by:2425- **type** — `feat` / `fix` / `docs` / `refactor` / `test` never share26- **scope** — diff modules/pkgs = diff commits27- **logical unit** — one thing per commit. Each builds + tests alone.2829Split signals:3031- > 1 unrelated area32- behavior + format/rename mixed (format separate)33- summary needs "and" / "also" / "+"34- unsure -> ask user how to group3536## Msg Format3738```39<header>4041<footer>42```4344`header` required. `footer` optional. **No body, ever.**4546If the header can't carry the change, the commit isn't atomic -> split it (see **Atomic**). The "why" lives in the PR body, the issue, or the code comment — not here.4748### Header4950```51<type>(<scope>): <short summary>52```5354- type: `build|chore|ci|docs|feat|fix|perf|refactor|test`55- scope: optional. Affected area/module/pkg. Lowercase, kebab/short noun. One scope only — pick the dominant one, else omit.56- summary: imperative present ("add" not "added"/"adds"), lowercase, no trailing `.`57- whole header ≤ 72 chars. Tighter is better; aim ≤ 50 for the summary itself.58- no ticket IDs in header (go in footer). No emoji. No `[WIP]`.5960#### Type Pick6162Pick the most specific. Behavior change > non-behavior. User-visible > internal.6364SemVer bump column is the canonical mapping used by `cliff.toml` across all repositories. `feat!:` / `BREAKING CHANGE:` footer always -> MAJOR regardless of type.6566| Type | SemVer | Use when | Examples |67| ------------ | ------ | -------------------------------------------------- | -------------------------------------------------------------------- |68| **feat** | MINOR | New user-visible capability or API | new endpoint, new CLI flag, new component, new public function |69| **fix** | PATCH | Restoring intended behavior after a defect | crash on null input, wrong calc, regression repair |70| **perf** | PATCH | Same behavior, measurably faster / lighter | cache hot path, drop O(n²) loop, lazy-load |71| **refactor** | PATCH | Code shape changes; behavior identical | rename, extract, inline, move file, dedupe — no API or output change |72| **test** | none | Test files only | add coverage, fix flake, rename test |73| **docs** | none | Docs / comments / `README` / changelog only | prose edits, JSDoc, ADRs, doc-only typos |74| **build** | none | Build system, deps, lockfiles, packaging | `package.json` deps, `uv.lock`, Dockerfile, bundler config |75| **ci** | none | CI/CD pipeline config | GH Actions workflow, release pipeline, branch protection scripts |76| **chore** | none | Repository maintenance with no code/build/CI/docs effect | `.gitignore`, editor config, tooling configs not tied to build |7778#### Tiebreakers7980- Bug -> `fix` > `refactor` > `chore`.81- Perf -> `perf` > `refactor`.82- New feature ships with its tests -> single `feat` commit. Tests for **existing** code -> `test`.83- README typo -> `docs`. README rewrite that ships new product info -> still `docs` (no code).84- Bumping a dep that fixes a bug here -> `fix` (your bug) or `build` (just the bump). Pick by user-visible effect.85- Lockfile-only churn from `install` -> `build`. Tooling config like `biome.json` formatting rules -> `chore`. CI workflow YAML -> `ci`.86- Renaming for clarity -> `refactor`. Renaming to land a new API -> part of the `feat`.87- Formatting / whitespace -> separate `chore` commit.88- Revert -> `revert:` prefix, never one of the above (see **Revert**).8990### Footer9192Trailers only. One per line, `Token: value`, after a single blank line below the header. Order: breaking change -> deprecation -> refs.9394Allowed tokens:9596- `BREAKING CHANGE: <summary>` — exact spelling (Angular spec). Detail + migration steps follow on subsequent lines, ≤ 5 lines.97- `DEPRECATED: <what>` — same shape; include upgrade path. ≤ 5 lines.98- `Fixes #<n>` / `Closes #<n>` / `Resolves #<n>` — issue auto-close. Multiple -> one per line or comma-separated.99- `Refs: #<n>` / `See: <url>` — non-closing references.100101```102BREAKING CHANGE: <summary>103104<detail + migration>105106Fixes #<n>107```108109```110DEPRECATED: <what>111112<detail + upgrade path>113114Closes #<n>115```116117Footer rules:118119- No `Co-Authored-By:` / "Generated with Claude" / tool-attribution trailers ever, unless user explicitly asks. Why -> standing user policy.120- No `Signed-off-by:` unless the repository's `CONTRIBUTING` requires DCO.121- No empty/placeholder trailers. No footer at all is fine.122- Breaking change without migration steps -> ask user before committing. Reviewers need the upgrade path.123124## Revert125126`revert: ` + reverted header, then a single line: `This reverts commit <SHA>`.127128Reason -> append to that same line only if non-obvious. Nothing else.129130## Rules131132- One logical change per commit. Else split.133- Never `--no-verify` / `--no-gpg-sign` unless asked. Why -> hooks catch real failures (lint, type, secret scan); skipping = shipping broken code.134- Pre-commit hook fail -> fix + re-stage + **new** commit. No amend. Why -> hook fail means the commit didn't happen; `--amend` would modify the **previous** (unrelated) commit and silently rewrite it.
pivoshenko