Appearance
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:
| Rule | Why |
|---|---|
| Subject line: 50 characters max | git log --oneline truncates at 72. Keep it under 50 so it fits everywhere |
| Body: wrap at 72 characters | git 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=51Anatomy 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 WHYSubject 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 --onelinestill shows the first line only, butgit logandgit showtreat 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
| Type | When to use |
|---|---|
feat | A new feature for the user |
fix | A bug fix |
docs | Documentation only |
style | Formatting, whitespace, semicolons — no code change |
refactor | Code change that neither fixes a bug nor adds a feature |
perf | Performance improvement |
test | Adding or fixing tests |
build | Build system or external dependency changes |
ci | CI configuration and scripts |
chore | Maintenance tasks, tooling, config |
revert | Reverts 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 middlewareBreaking 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 --verbosegit commit --fixup and --squash
For interactive rebase workflow (see the Fixup guide):
bash
git commit --fixup abc1234git 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=shortcommitizen / cz-cli
Interactive CLI that walks you through a Conventional Commit:
bash
# Install (npm)
npm install -g commitizen
# Use
git czWhen 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 revertopens 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
| Mistake | Fix |
|---|---|
| Single-line message with no body | Always 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 body | git 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 -cWhen 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.