Skip to content

Commit Messages

One-liner

A well-crafted commit message explains why a change was made, turning git history into permanent, navigable documentation.

Why it matters

The diff shows what changed. The commit message explains why. Without the why, future developers (including you in six months) must reverse-engineer intent from code alone. Good commit messages make git blame useful, make reverts safe, and make code review efficient. Bad ones ("fix bug", "update code", "WIP") provide zero information and waste everyone's time.

Core concept

Think of commit messages as entries in a ship's logbook. Each entry records not just what happened ("turned 15° starboard") but why ("to avoid shallow reef spotted by lookout"). Months later, when reviewing the route, the logbook explains the journey. Without reasons, the route looks arbitrary.

A commit message is a letter to a future developer. The diff is the attachment; the message is the context that makes the attachment meaningful.

How it works

  1. Subject line (≤50 chars) — answers "what does this commit do?" in imperative mood ("Add feature", not "Added feature").
  2. Blank line — separates subject from body; tools rely on this convention.
  3. Body (wrapped at 72 chars) — explains why the change was necessary, what approach was chosen, what alternatives were considered.
  4. Footer — references issues, notes breaking changes, credits co-authors.
  5. Conventional prefix — feat:, fix:, refactor:, etc. enables automated changelogs and semantic versioning.

Key terms

  • Imperative mood — "Add validation" not "Added validation"; completes "If applied, this commit will ___"
  • Conventional Commits — format type(scope): subject enabling automated changelog generation
  • 72-character wrap — body line width that displays correctly in git log, email, and terminal tools
  • Breaking change — noted in footer as BREAKING CHANGE: for semantic version major bumps
  • git log --oneline — shows only subject lines, demonstrating why they must be self-contained

Common misconceptions

  • "Nobody reads commit messages" — git blame, git bisect, code review, and incident investigation all rely heavily on commit messages. They're read more often than you think.
  • "The code is self-documenting" — Code shows the current state. Only the commit message explains the transition: what was wrong before, why this approach was chosen over alternatives.
  • "Short messages save time" — They shift the cost to future readers who now must read diffs and reconstruct intent. A 2-minute message now saves 30-minute investigations later.

When to use / not use

✓ Use when: always. Every commit deserves at minimum a clear subject line. Non-trivial changes deserve a body explaining the reasoning.

✗ Don't use lengthy bodies when: the change is truly trivial (fix typo, remove trailing whitespace), the subject line is fully self-explanatory, or you're making WIP commits that will be squashed before merge.

Example

# Good commit with body
git commit -m "fix(auth): increase token timeout to 30s

The 5s default caused 12% failure rate on high-latency
connections. 30s matches the OAuth provider's max response
time. Considered per-region timeouts but deferred for
simplicity.

Fixes: PROJ-4521"

Next steps

  1. Set up a commit-msg hook that enforces subject length (≤50 chars) and conventional commit format
  2. Use git commit (without -m) to open your editor for multi-line messages with proper formatting
  3. Review your recent git log --oneline — any entry that says "fix" or "update" without context is a candidate for better practices going forward