Commit Message Best Practices
debt(d3/e1/b3/t5)
Closest to 'default linter catches the common case' (d3). The term's detection_hints specify commitlint, husky, and git-hooks as tools that can enforce commit message standards. These are commonly integrated into CI/CD pipelines and pre-commit hooks, catching violations before code is merged. Not quite d1 since it requires explicit setup, but readily available tooling exists.
Closest to 'one-line patch or single-call swap' (e1). The quick_fix is straightforward: rewrite the commit message following the 'what and why' pattern. Git allows amending recent commits (git commit --amend) or interactive rebase for older ones. Each fix is a single message rewrite with no code changes required.
Closest to 'localised tax' (b3). Poor commit messages create a localized documentation debt — they don't poison code execution or architecture, but they do impose a persistent minor tax when developers need to understand change history. The impact is contained to git archaeology rather than affecting runtime behavior or system structure.
Closest to 'notable trap' (t5). The misconception field explicitly states developers think commit messages are for themselves rather than future maintainers. This is a documented gotcha that most developers eventually learn through painful experience debugging code 18 months later. The 'obvious' approach (describing what you did in past tense) contradicts the imperative style that git itself uses.
Also Known As
TL;DR
Explanation
The seven rules of a good commit: (1) Separate subject from body with a blank line, (2) Limit subject to 50 chars, (3) Capitalise subject, (4) No period at end, (5) Use imperative mood ('Add' not 'Added'), (6) Wrap body at 72 chars, (7) Use the body to explain what and why, not how. Conventional Commits format (feat:, fix:, chore:) enables automated semantic versioning and changelog generation. git log --oneline should tell a story of the project's evolution.
Common Misconception
Why It Matters
Common Mistakes
- 'WIP', 'fix', 'update', 'misc' — meaningless; what work, what fix, what update?
- Subject line > 72 characters — truncated in most git tools.
- No body explaining the why — the diff shows what changed; the message should explain why.
- Past tense ('Added feature') instead of imperative ('Add feature') — inconsistent with git's own messages.
Code Examples
# Useless commit history:
git log --oneline
abc123 fix
def456 update
ghi789 WIP
jkl012 changes
# 6 months later: which commit introduced the security regression?
# No way to know without reading every diff# Conventional Commits — searchable, automatable:
git log --oneline
abc123 fix(auth): prevent session fixation after password reset
def456 feat(checkout): add Apple Pay support
ghi789 refactor(user): extract email validation to ValueObject
jkl012 security: rotate JWT signing key after exposure in logs
# Full commit with body:
fix(auth): prevent session fixation after password reset
Session was not regenerated after successful password reset,
allowing an attacker with a pre-existing session ID to take
over the account. Fixes CVE-2026-1234.
Closes #456