Commit Message Best Practices

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

References

• ↗ https://www.conventionalcommits.org/
• ↗ https://cbea.ms/git-commit/

Tags

Related Terms