git-commit

Git Commit

Purpose

Define how commits are written and scoped across this project's repositories. Consistent history is what makes git log, git blame, and git bisect useful — and what lets a human or AI agent reconstruct why a change happened months later. This is the canonical convention; deviations need a documented decision (an ADR).

Trigger

You are about to run git commit (including --amend or a squash), or you are writing or rewriting a commit message.

Inputs

• A working tree with staged changes that form a single logical unit of work (see Workflow rules).
• A clear understanding of what the change does and why it is being made.

Commit message rules

1. Subject line under 50 characters. Hard ceiling. Shorter is fine.
2. Capitalize the subject line. First letter uppercase.
3. Use the imperative mood in the subject. Write Add user export, not Added user export or Adds user export. Read it as "this commit will…".
4. No period at the end of the subject line.
5. A body is optional — use judgment. When the subject line alone fully explains the change, skip the body. Add one only when the why isn't obvious from the subject and diff alone.
6. Separate subject from body with a blank line. Required whenever a body is present — many git tools rely on it.
7. Wrap the body at 72 characters. Hard limit at 80. Long lines break git log in terminals.
8. Use the body for what and why, not how — and keep it compact. The diff already shows how; the body captures what the diff cannot: motivation, constraints, alternatives considered, consequences. If the caveman skill is available, use it to draft a terse, filler-free body.
9. No Conventional Commits prefixes. Do not prefix subjects with feat:, fix:, chore:, etc.
10. Do not touch the author or committer fields. They stay whatever ~/.gitconfig is set to on the machine running the commit. Do not pass --author, do not set GIT_AUTHOR_* or GIT_COMMITTER_*, and do not modify these fields by any other means.
11. Do not reference issues in the commit. No #123, no Closes #123, no issue URLs. Issue tracking lives outside the commit message.

Workflow rules

1. One logical change per commit. Each commit wraps a single coherent change. Don't mix a bug fix and a feature, or a refactor and a behavior change. If you find yourself writing "and" in the subject, split the commit.
2. No half-done work. Commit only when a logical component is complete — it builds, makes sense on its own, and does not leave the tree broken. Use a local branch, git stash, or amend until the unit is whole.
3. Group related changes. Files touched for the same reason belong in the same commit, even if they live in different parts of the tree.

Output

• A commit on the current branch whose subject — and body, when present — conforms to the rules above.
• A history that reads as a sequence of complete, single-purpose changes.