Commit Message Craft

Parent: Writing and Documentation · researched 2026-05-29T18:28:28.565Z· 9 sources · 10 concepts · skill commit-message-craft

Subject line: hard limit 50 characters. Body: wrap at 72.

1. The 50/72 rule (Tim Pope, 2008)

Subject line: hard limit 50 characters. Body: wrap at 72. [source]
Mechanical rules: [source]
Subject line ≤ 50 chars. Hard ceiling is 72, but cross 50 only when truly unavoidable. [source]
Blank line between subject and body - required. [source]
Body wrap at 72. [source]
No trailing period on the subject. [source]

2. Imperative mood for the subject

Write the subject as a command the commit gives the codebase, not as a past-tense report. [source]
Test: prepend "If applied, this commit will ___". The result must be a grammatical English sentence. [source]
Add retry logic to S3 uploader - passes [source]
Added retry logic to S3 uploader - fails [source]

3. Conventional Commits: structure beyond the basics

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert [source]

4. Breaking changes: `!` and `BREAKING CHANGE:` footer

Method 1 - exclamation mark in the header: [source]
Method 2 - footer token: [source]

5. The "why not what" rule for the body

The diff already shows what changed. The body must explain why. [source]
Body content checklist: [source]
What problem did this commit solve? [source]
Why this approach and not an alternative? [source]
Any non-obvious side effect or trade-off? [source]
Links to tickets, design docs, or incident reports. [source]
Body anti-content: [source]
Don't restate the subject line. [source]
Don't narrate the diff line by line. [source]

6. Multi-commit storytelling for PR reviewers

Prep commits first - refactors, renames, type-only changes with no behavior change. [source]
The substantive commit - the one that does the actual feature/fix. [source]
Test commit(s) - if tests are separated. [source]
Cleanup commits last - docs, changelog, version bumps. [source]

7. Fixup / squash / autosquash discipline

git commit --fixup=<sha> writes a commit message starting with fixup! <original-subject>. [source]
--fixup discards the fixup's commit message; only the original is kept. Use for typo fixes. [source]
--squash keeps both messages joined. Use when the "fix" adds meaningful nuance. [source]
Never push fixup commits to a shared branch as-is. [source]

8. Signed-off-by and the Developer Certificate of Origin

Use git commit -s (or --signoff) to add automatically. [source]

9. Other trailers

Co-authored-by: Name <email> - GitHub credits both authors [source]
Closes #123, Fixes #123, Resolves #123 - GitHub auto-closes the issue [source]

Anti-Patterns

"Fixed bug" / "Updates" / "WIP" - useless. [source]
Past-tense subjects - Added, Fixed, Refactored. [source]
Restating the diff in the body. [source]
Stacking unrelated changes in one commit. [source]
Burying breaking changes without ! or BREAKING CHANGE:. [source]

References

Conventional Commits v1.0.0 specification [source]
Tim Pope - A Note About Git Commit Messages [source]
Chris Beams - How to Write a Git Commit Message [source]

Children

Conventional Commits (frontier)
Tim Pope 50/72 rule (frontier)
Imperative-mood subjects (frontier)
BREAKING CHANGE footer (frontier)
Why-not-what body discipline (frontier)
Fixup/squash/autosquash workflow (frontier)
Signed-off-by/DCO trailers (frontier)
Co-authored-by trailer (frontier)
Multi-commit storytelling (frontier)
Commit splitting heuristics (frontier)

Frontier under this node: BREAKING CHANGE footer, Co-authored-by trailer, Commit splitting heuristics, Conventional Commits, Fixup/squash/autosquash workflow, Imperative-mood subjects, Multi-commit storytelling, Signed-off-by/DCO trailers, Tim Pope 50/72 rule, Why-not-what body discipline

← the whole tree · 3D view· how to read this page