Conventional Commits

Commit Messages That Matter: Conventional Commits

After this page you can write a subject line other people and tools can parse.

Shape of a message

type(scope): short summary

Optional body: why, not what. Wrap at 72 characters.

Optional footer:
Fixes: #12
BREAKING CHANGE: /ping now returns JSON

The subject is one line, imperative, about 50 characters, no trailing period. Git itself does not enforce this. Forges, changelog generators, and git log --grep benefit when you do.

Types this book uses

Type	When
feat	A user-visible capability
fix	A bug
docs	README, comments, this book’s desk docs
chore	Tooling, ignore files, no user-facing change
refactor	Same behavior, different code
test	Tests only
ci	Pipeline files (later parts)

scope is optional: feat(api):, fix(web):. For desk-api a scope of ping or auth is enough.

Examples that match the desk:

feat(ping): return JSON from /ping
fix(ping): treat empty name as 400
docs: document GET /ping in README
chore: ignore .env and __pycache__

Why bother

git log --oneline --grep '^fix'
git log --oneline --grep '^feat(ping)'

Later, platform governance (chapter 31) can require this shape in a server-side hook. A client-side commit-msg hook (chapter 13) can reject a bad subject before the object exists.

What to put in the body

The subject is what. The body is why and any context git log should keep:

git commit -m "fix(ping): treat empty name as 400" -m "The handler returned 200 and an empty body, so the desk-web health check looked up. Reject empty names at the edge."

Skip the body when the subject is the whole story.

Trailers

Signed-off-by: Ada Desk <ada@example.com>
Co-authored-by: Sam Desk <sam@example.com>
Fixes: #18

git interpret-trailers reads these. Signed-off-by is a project convention (Linux kernel, some forges). Use it when the project asks. Co-authored-by is how forges attribute a second author on a squash.

A local alias

git config --global alias.cm '!f() { git commit -m "$1"; }; f'

Aliases are optional. The skill is the subject line, not the shortcut.