Skip to content

Writing Good Commit Messages ​

Commit messages matter more than most developers admit. git log --oneline is the first thing you read when debugging, reviewing, or triaging. If every message says "fix stuff" or "update", you are flying blind.

This guide covers the format, the conventions, and the tooling that turns commit messages into a searchable, automated history.

The 50/72 rule ​

Two hard rules every commit message should follow:

RuleWhy
Subject line: 50 characters maxgit log --oneline truncates at 72. Keep it under 50 so it fits everywhere
Body: wrap at 72 charactersgit log shows the body indented by 4 spaces. 72 keeps it readable without horizontal scroll

How to enforce it ​

bash
# Tell Git to check line length in your editor
git config --global core.commentChar "#"
git config --global core.pager "less -r"

# Use a prepare-commit-msg hook (save as .git/hooks/prepare-commit-msg)

Git does not enforce the 50/72 rule. Your editor should. In Vim:

:set textwidth=72
:set colorcolumn=51

Anatomy of a good message ​

Subject line: capitalized, no period, imperative mood, < 50 chars
               |
               v
Add rate limiter to the login endpoint

The login endpoint had no rate limiting, making it vulnerable to
brute-force attacks. This commit adds token-bucket rate limiting
with a configurable threshold.

- Rejects requests above 10 attempts per minute per IP
- Returns 429 with Retry-After header
- Config via LOGIN_RATE_LIMIT env var
       |
       v
Body: blank line, wrap at 72 chars, explain WHAT and WHY

Subject line rules ​

  • Imperative mood. "Add feature" not "Added feature" or "Adding feature". Git itself uses imperative: "Merge branch 'feature'", "Revert commit abc123".
  • Capitalize the first letter. No "fix bug" — write "Fix login redirect loop".
  • No period at the end. The subject is a title, not a sentence.
  • Prefix conventions. Many projects use a scope prefix: feat:, fix:, docs:, refactor:. These come from Conventional Commits.

Body rules ​

  • Separate from subject with a blank line. Without it, git log --oneline still shows the first line only, but git log and git show treat everything as subject.
  • Explain WHY, not WHAT. The diff shows what changed. The message explains why you did it. "Bump connection pool to 20" says what. "Bump connection pool to 20 to avoid timeout errors under peak load" says why.
  • Bullet lists for multiple effects. Use - at the start of the line, wrapped at 72.

Conventional Commits ​

Conventional Commits is a structured prefix convention that tooling can parse. It works with changelog generators, semantic-release, and CI automation.

<type>(<scope>): <description>

[optional body]

[optional footer]

Types ​

TypeWhen to use
featA new feature for the user
fixA bug fix
docsDocumentation only
styleFormatting, whitespace, semicolons — no code change
refactorCode change that neither fixes a bug nor adds a feature
perfPerformance improvement
testAdding or fixing tests
buildBuild system or external dependency changes
ciCI configuration and scripts
choreMaintenance tasks, tooling, config
revertReverts a previous commit

Examples ​

feat(api): add pagination to search endpoint

fix: handle empty response from auth service

docs: clarify rate limit behavior in README

refactor(core): extract retry logic into middleware

Breaking changes ​

Add ! after the type/scope or use BREAKING CHANGE in the footer:

feat(api)!: remove deprecated v1 endpoints

BREAKING CHANGE: The /api/v1/* endpoints have been removed.
Migrate to /api/v2/*.

Tools for commit messages ​

git commit --verbose ​

Shows the full diff in the editor while you write the message. Helps you see what you're actually committing:

bash
git commit --verbose

git commit --fixup and --squash ​

For interactive rebase workflow (see the Fixup guide):

bash
git commit --fixup abc1234

git log with formatting ​

bash
# One line per commit
git log --oneline

# Full message with diff
git log -p

# Custom format: hash, date, subject, author
git log --pretty=format:"%h %ad %s (%an)" --date=short

commitizen / cz-cli ​

Interactive CLI that walks you through a Conventional Commit:

bash
# Install (npm)
npm install -g commitizen

# Use
git cz

When the message matters most ​

  • Bug fixes. The message is the first place a teammate looks to decide if a commit is related to their issue. "Fix null pointer in login" beats "Update auth code".
  • Reverts. git revert opens a template that includes the reverted commit's subject. Fill in why you reverted.
  • Release notes. Tools that build changelogs from commit history only work if messages are structured.
  • Bisect. During git bisect, the commit message is your only clue at each step. A good message tells you whether to mark good or bad.

Pitfalls ​

MistakeFix
Single-line message with no bodyAlways explain WHY. The diff covers WHAT.
Past tense ("Added feature")Use imperative: "Add feature". Think "this commit will..."
Vague messages ("fix", "update", "stuff")One commit, one concern. Name it.
No blank line between subject and bodygit log treats the whole thing as subject. Always insert a blank line.
Mixed-case prefixes (Fix:, FIX:, fix:)Pick a convention and stick to it. Lowercase is standard.
Mentioning issue numbers without context"See #42" is useless in 6 months. Write what #42 says.

Quick reference ​

bash
# Set up editor for 72-char wrapping
git config --global core.editor "vim -c 'set textwidth=72 tw=72'"

# Show the message for any commit
git log -1 --format="%B" <sha>

# Rewrite the most recent message
git commit --amend -m "New message"

# Verify your message length
git log -1 --format="%s" | wc -c

When to break the rules ​

The 50/72 rule is a guideline, not a law. Exceptions:

  • Breaking change footnotes can push the subject past 50 chars. Keep it under 72.
  • Merge commits are generated by Git and often exceed 50. Do not edit them.
  • Fixup commits use the original commit's subject. They get squashed anyway.

Git Master — Git Reference for Every Skill Level