Every developer writes commits.
But not every developer writes useful commit messages.
A commit message is more than a label for a code change.
It becomes part of your project’s permanent history, helping teammates—and your future self—understand why something changed.
Many repositories unfortunately end up with commit histories like this:
fix
update code
changes
final fix
These messages provide almost no context.
Fortunately, a few simple conventions can make commit messages significantly clearer and more helpful.
Why Commit Messages Matter
When developers explore a repository, the commit history becomes the narrative of the project.
Good commit messages help with:
- Understanding why a change was made
- Navigating the project history
- Reviewing pull requests efficiently
- Debugging issues later
Code explains how something works.
A commit message explains why the change exists.
Without that context, even well-written code becomes harder to maintain.
The Structure of a Good Commit Message
A clean commit message usually contains two parts:
Short summary of the change (subject)
Optional explanation describing why the change was made
The first line is the subject line, which tools like git log and GitHub display prominently.
The body is optional but useful when additional explanation is needed.
Seven Simple Rules for Better Commit Messages
1. Separate the subject from the body with a blank line
This helps Git tools correctly interpret the commit structure.
Example:
Add authentication middleware
Introduce middleware that validates API tokens before
requests reach protected endpoints.
2. Keep the subject line concise (around 50 characters)
Short summaries make commit history easier to scan.
Instead of writing a long sentence, aim for a clear and compact description.
3. Capitalize the subject line
Treat the subject line like a title.
Good:
Add support for OAuth authentication
Bad:
add support for oauth authentication
4. Avoid ending the subject with a period
Commit titles behave more like headings than sentences.
Good:
Fix memory leak in cache manager
Bad:
Fix memory leak in cache manager.
5. Use the imperative mood
Write commit messages as instructions or commands.
Good examples:
Add user authentication
Fix API timeout issue
Remove unused dependencies
Avoid:
Added user authentication
Fixes API timeout issue
This style aligns naturally with Git commands such as merge or revert.
6. Wrap the body at around 72 characters
Limiting line length keeps messages readable in terminals and Git tools.
Example:
Add request logging middleware
This middleware records incoming HTTP requests and response
times to help diagnose performance issues in production.
7. Explain what and why, not how
The code already shows how the implementation works.
The commit message should explain:
- What problem is being solved
- Why the change was necessary
- Any context future developers should know
This extra context becomes extremely valuable months or years later.
A Real Example
Bad commit message:
fix bug
Better commit message:
Fix null pointer crash in user profile service
The crash occurred when a profile was requested for users
without an address record. Added a null check and fallback
handling to prevent the service from terminating.
The second message gives developers useful context about the change.
A Simple Commit Template
Many teams use a commit template to maintain consistency.
Short summary (max ~50 characters)
Explain why this change is needed.
Describe the problem being solved.
Mention any relevant context.Optional: reference issue numbers
Fixes #123
Final Thoughts
Writing good commit messages is a small habit with a big impact.
Clear commit history makes projects easier to understand, easier to maintain, and easier for others to contribute to.
If you focus on clear summaries, structured messages, and explaining why changes happen, your repository history will become far more useful.
And one day, when you're debugging a tricky issue months later, you'll be glad you did.
Reference: How to Write a Git Commit Message
Top comments (0)