Writing Good Commit Descriptions
Master the art of writing concise, informative commit descriptions. Covers imperative mood, character limits, common mistakes, and examples of good vs bad descriptions.
Detailed Explanation
Best Practices for Commit Descriptions
The description (subject line) is the most important part of a commit message because it is what people see in git log --oneline, PR merge commits, changelogs, and release notes. A well-written description makes your commit history a valuable documentation tool.
The Five Rules
- Use imperative mood — "add", "fix", "change", not "added", "fixes", "changing"
- Start with lowercase — "add feature", not "Add feature"
- Keep it under 50 characters — ensures no truncation in any tool
- Do not end with a period — trailing punctuation wastes a character
- Describe the effect, not the activity — "add search" not "working on search"
Imperative Mood Test
Your description should complete this sentence:
If applied, this commit will [your description].
- "If applied, this commit will add user authentication" ✔
- "If applied, this commit will added user authentication" ✘
- "If applied, this commit will adding user authentication" ✘
Good vs Bad Descriptions
| Bad | Problem | Good |
|---|---|---|
added new button |
Past tense | add submit button to form |
Fixing stuff |
Uppercase, vague | fix null check in validator |
update. |
Period, vague | update retry logic for API calls |
WIP |
Not descriptive | add initial login form layout |
changes to the user module |
Describes activity | extract user validation helpers |
The 50-Character Budget
With the type and scope prefix, your total header line might look like:
feat(auth): add two-factor authentication
The full header is 42 characters. The description "add two-factor authentication" is 31 characters. Plan your character budget:
- Type + colon + space: ~6-12 chars
- Scope (if used): ~4-10 chars + parens
- Description: remainder up to 50 total
Action Verbs to Start With
add → New functionality
remove → Delete code or features
fix → Bug corrections
update → Modify existing behavior
refactor → Restructure without behavior change
improve → Enhancement
replace → Swap implementation
extract → Pull code into separate unit
rename → Change names
simplify → Reduce complexity
Use Case
You are onboarding new team members and want to establish a commit message convention. You need a reference guide that explains how to write clear, consistent descriptions that work well with automated changelog generators, code review tools, and git log output.