Writing Good Commit Messages
Your commit messages are your communication with future developers (including yourself). A good message saves hours of detective work later.
⚠️Think about it
Six months from now, will you remember why you made a change? Your commit message is a gift to your future self.
The Anatomy of a Good Commit Message
# Good commit message structure:
Subject line: 50 chars or less (imperative mood)
# Blank line separates subject from body
Optional body: Explain the "why" not the "what".
Wrap at 72 characters. Can be multiple paragraphs.✍️
Use imperative mood
Write as if giving a command: "Add feature" not "Added feature". Tip: complete the sentence "If applied, this commit will..."
🎯
Be specific
Instead of "Fix bug", say "Fix crash when user submits empty form".
🧭
Explain the why
The code shows WHAT changed. The message should explain WHY.
Good vs Bad Examples
✗
Bad Messages
- "fix"
- "WIP"
- "Update files"
- "asdfasdf"
- "Changes"
- "Fixed the thing"
✓
Good Messages
- "Fix null pointer in user auth"
- "Add email validation to signup"
- "Refactor cart to use Redux"
- "Remove deprecated API calls"
- "Update docs for v2 migration"
- "Improve search performance"
Common Commit Types
Many teams use prefixes to categorize commits. Here is a popular convention:
feat:New feature
fix:Bug fix
docs:Documentation
style:Formatting, no code change
refactor:Code restructuring
test:Adding tests
chore:Maintenance tasks
perf:Performance improvement
ℹ️Example
feat: Add dark mode toggle to settings
Check Your Understanding
Answer these to test your commit message instincts:
1. Which commit message is better?
Fixed bug
Fix login button not responding on mobile Safari
Changes
Update code
2. What should a commit message focus on?
How many lines of code changed
The time it took to make the change
Why the change was made and what it affects
The files that were modified
3. Which is a good practice for commits?
Include all changes from the entire day in one commit
Make small, focused commits that do one thing
Only commit when a feature is 100% complete
Avoid committing until you have at least 500 lines changed
Key Takeaways
- •Be specific - vague messages help no one.
- •Use imperative mood - "Add" not "Added".
- •Keep subject under 50 characters - be concise.
- •Explain the why - context is invaluable.
- •Commit often - smaller commits are easier to understand.