Git Commit Conventions
Commit Message Format
type: short description in imperative mood
Optional body paragraph.
- No scope — use
feat: add X, notfeat(module): add X. - Lowercase type and description.
- Imperative mood: "add X", "fix Y", "remove Z" — not "added", "adding", "fixes".
- No period at the end.
- Max ~72 characters on the subject line.
- Optional body (blank line after subject): use for context, not mechanics.
Allowed Types
| Type | When to use |
|---|---|
feat |
New feature or behaviour |
fix |
Bug fix |
test |
Adding or fixing tests only |
docs |
Documentation only |
refactor |
Code change with no feature/fix |
chore |
Build, tooling, config, deps |
build |
Build system changes |
perf |
Performance improvement |
style |
Formatting, whitespace — no logic change |
revert |
Reverts a previous commit |
Examples
A complete commit with body:
feat: add retry policy to HTTP client
Wrap outbound calls in a retry with exponential backoff so
transient failures from downstream services don't fail the request.
A minimal commit:
fix: handle null input in prompt builder
Subject-only quick reference:
test: add unit tests for retry backoff logic
chore: update dependencies
docs: document skill frontmatter spec
refactor: extract connection string builder to helper
Branch Naming
{type}/{short-description}
- Use the commit type directly (
feat,fix,chore, etc.) — not expanded forms. - Description uses hyphens to separate words, kept to 3–5 meaningful words.
Branch Name Examples
feat/add-query-meter-api
fix/api-client-retry-policy
chore/update-skill-frontmatter
docs/add-orchestrator-guide
Merge Strategy
PRs merge with a squash merge by default unless the branch has a meaningful commit history worth preserving.
Co-Authored-By Trailer
Commits in this repo end with a Co-Authored-By: Claude ... <noreply@anthropic.com> trailer and a Claude-Session: line. These are applied automatically from the agent's environment/system instructions — do not hand-type them into the message body, and do not invent or alter the email or session URL. Write your type: description subject and optional body as normal; the trailers are appended below the body, separated by a blank line, as the last lines of the message.
Quick Checklist
- Subject line:
type: description(lowercase, imperative, no scope, no period) - Type is one of the allowed types above
- Optional body explains the why, not the what
- Branch:
type/short-description
Anti-Pattern
Forbidden: Amending commits unless the user explicitly asks. After a pre-commit hook failure, create a NEW commit.