"A good commit shows whether a developer is a good collaborator." — Peter Hutterer, Linux.
Years ago, I never realized there were specific rules for writing commit messages until my curiosity got the best of me. I used to think that straightforward messages like “added feature 2,” “fixed the bug on the Main Navigation bar,” or even “foo” were sufficient. The conviction that commit messages went largely unread proved mistaken. In reality, well-crafted commit messages are indispensable, ensuring that our future selves benefit from our diligence and thoughtfulness.
Why You Should Care About Writing Clean Commit Messages
Commits serve as the tangible building blocks of a programmer’s craft. They act as the icing on the cake of code, and when written correctly, they bring substantial value. A well-written commit message becomes indispensable because they provide context — otherwise, a commit message wouldn’t be needed in the first place.
"A good commit shows whether a developer is a good collaborator." — Peter Hutterer, Linux.
Common Mistakes in Commit Messages
Before diving into the rules, let’s address some common mistakes developers often make:
1. Vague Messages
- Example: “Fixed it”
- Why it’s bad: This provides no context on what was fixed or where.
2. Too Much Information
- Example: “Refactored the entire application, fixed all bugs, added new features, updated documentation.”
- Why it’s bad: This makes it difficult to pinpoint what exactly was done.
3. Irrelevant Details
- Example: “Had coffee, then fixed bug #1234”
- Why it’s bad: Personal anecdotes don’t belong in commit messages.
The 7 Rules for Writing Perfect Commit Messages
- Keep It Short and Sweet
- Limit the subject line to 50 characters or less.
- Example: “Add user authentication”
- Use the Imperative Mood
- Think of your commit message as a command.
- Example: “Fix login bug” instead of “Fixed login bug” or “Fixes login bug”
- Separate Subject from Body with a Blank Line
- Helps in readability and clarity.
- Example:
Add user authentication
Implemented JWT for secure authentication.
Updated user model to include password hashing.
- Capitalize the Subject Line
- Example: “Update README with installation instructions”
- Do Not End the Subject Line with a Period
- Example: “Improve performance of data fetching”
- Use the Body to Explain What and Why, Not How
- Example:
Refactor user service
Split the user service into smaller, more manageable functions.
This will help in maintaining and testing the code more efficiently.
- Be Consistent
- Maintain a consistent style across all commit messages.
Case Study: From Bad to Good
Bad Commit Message:
Fixed issue #456
Improved Commit Message:
Resolve issue #456: Fix null pointer exception in UserService
The null pointer exception was occurring due to an uninitialized object.
Added a check to initialize the object before accessing its properties.
Tips for Writing Better Commit Messages
- Think Before You Type
- Reflect on what you’ve done and why it matters.
- Use Tools and Templates
Utilize commit message templates to ensure consistency.
Example template:
Subject: [TASK] - Description
Body:
- What was done
- Why it was done
- Any additional notes
- Review Before Committing
- Always read your commit message before finalizing it.
- Collaborate with Your Team
- Discuss and agree on a commit message convention with your team.
Conclusion
Writing good commit messages is an art that every developer should master. They are not just a formality but a crucial part of the development process that aids in understanding the history and evolution of a project. By following these guidelines, you can ensure that your commit messages are clear, concise, and valuable to your team.
By adopting these practices, you’ll not only improve your own workflow but also enhance collaboration and productivity within your team. Remember, a good commit message is the hallmark of a diligent and thoughtful developer. So, next time you’re about to commit, take a moment to craft the perfect message.
That's all for today.
And also, share your favourite web dev resources to help the beginners here!
Connect with me:@ LinkedIn and checkout my Portfolio.
Explore my YouTube Channel! If you find it useful.
Please give my GitHub Projects a star ⭐️
Thanks for 23428! 🤗
Top comments (49)
Great article!! If you are interested in further improving your commit messages, take a look at conventional-commits. It can help you write commit messages in a semantic manner and help in automating a couple of things like release management and changelog generation.
conventionalcommits.org/en/v1.0.0/
github.com/semantic-release/semant...
🚀 🚀 🚀
If you found my content helpful or interesting, and you’d like to show your appreciation, why not buy me a coffee? It’s a small gesture that goes a long way in helping me keep creating more content for you.
Just click the button below to support:
This is the most valuable comment. 👍🏼
If you found my content helpful or interesting, and you’d like to show your appreciation, why not buy me a coffee? It’s a small gesture that goes a long way in helping me keep creating more content for you.
Just click the button below to support:
I might start adding these to all my comments.
Glad to hear that, It’s a small gesture that goes a long way in helping me keep creating more content for you.
Just click the button below to support:
Do Subscribe my YouTube Channel!!! If you all find it helpful as subscription is free but it will motivate me to be active here :)
While I largely agree on Ur points I'm missing why certain things matter, e.g. why the imperative style on commits? I personally prefer the "adds foo ..." Form. Reason: b/c it describes one of many logical step on a topic (branch) which has a goal, that I express then in the imperative, eg "fix bug 2345 scratch that itch"
It is to read like "when you apply this commit it will 'fix bug 2345'". Now if you have any other tense or tone, it'd be weird.
This is a good
copy pastereminder of this article from 2014: cbea.ms/git-commit/Wow it sure is. Sigh
Do Subscribe my YouTube Channel!!! If you all find it helpful as subscription is free but it will motivate me to be active here :)
I mean you could make the exact same argument for "when you apply this commit it 'fixes bug 2345'".
What does 23428 signify?
It signifies no. of ❤️ I got till date .Do Subscribe my YouTube Channel!!! If you all find it helpful as subscription is free but it will motivate me to be active here :)
If you found my content helpful or interesting, and you’d like to show your appreciation, why not buy me a coffee? It’s a small gesture that goes a long way in helping me keep creating more content for you.
Just click the button below to support:
Hey, finally I get instructions on writing good commit messages that goes beyond the "be clear and concise". Thanks!
If you found my content helpful or interesting, and you’d like to show your appreciation, why not buy me a coffee? It’s a small gesture that goes a long way in helping me keep creating more content for you.
Just click the button below to support:
Do Subscribe my YouTube Channel!!! If you all find it helpful as subscription is free but it will motivate me to be active here :)
Thanks for sharing
If you found my content helpful or interesting, and you’d like to show your appreciation, why not buy me a coffee? It’s a small gesture that goes a long way in helping me keep creating more content for you.
Just click the button below to support:
Do Subscribe my YouTube Channel!!! If you all find it helpful as subscription is free but it will motivate me to be active here :)
You're Welcome :)
That is one of the best guides about writing commits I've read. It's so clear and with simple examples, ideal even for begginers like me!
Glad to hear that ❤️ @Thaísa Vieira. Let's connect here linkedin.com/in/safdarali25. Can checkout, here I share awesome stuffs on web and for web ✨.
Not in the title line, at least. If you want to be funny in the body of the commit message, unless you're wasting the reader's time, that's not really a problem.
Personally, I find it distracting to add platform-specific information to your status line. In git terms, #456 means absolutely nothing. Most devs will know that it's some sort of issue number, but that doesn't really help at all when reading the log.
Normally, what you want to see at a glance is: What does this commit do. If you're curious why it does that, you'll read the full commit message anyway. And at that point, it's better to have a full link to the issue so it can be accessed without knowing what issue tracker is being used for the project.
Ideally, you put the explanation of the issue in the commit message; you never know when microsoft might decide to make the issue tracker a premium feature if they're feeling entitled to more of people's hard-earned money.
Overall, I think the subject line should tell you nothing more than what a commit does in a very concise way. Maaaaaybe a short tag like
[fix]or[feat]can be added too for a bit more context, but other than that, the primary rule of thumb is: "Concise status line, have fun with the body".Mentioning issue numbers in commit messages can be very helpful in short-term mid-term, especially in a setup where this will be displayed as a link to an issue or serve as a hint to automatically close the linked issue as resolved.
Yea, but they should ideally only complement a proper description of why a change was necessary, rather than defer entirely to some external system that may or may not be there anymore when someone reads the commit in 5 years.
It also serves that purpose perfectly well in the body of the commit message, so there's no reason to put it in the title line, where people want a concise summary, not a link they first have to click.
I read your article - you can find it on my YouTube channel. I should look into conventional commits.
youtu.be/tnLhwl9hC_A
If you found my content helpful or interesting, and you’d like to show your appreciation, why not buy me a coffee? It’s a small gesture that goes a long way in helping me keep creating more content for you.
Just click the button below to support:
Do Subscribe my YouTube Channel!!! If you all find it helpful as subscription is free but it will motivate me to be active here :)
No thank you, I have no interest in React nor JS.
*JajhakAllohu Khoir , Brother. *
If you found my content helpful or interesting, and you’d like to show your appreciation, why not buy me a coffee? It’s a small gesture that goes a long way in helping me keep creating more content for you.
Just click the button below to support:
Do Subscribe my YouTube Channel!!! If you all find it helpful as subscription is free but it will motivate me to be active here :)
Thanks for the insights :)
If you found my content helpful or interesting, and you’d like to show your appreciation, why not buy me a coffee? It’s a small gesture that goes a long way in helping me keep creating more content for you.
Just click the button below to support:
Do Subscribe my YouTube Channel!!! If you all find it helpful as subscription is free but it will motivate me to be active here :)
Some comments may only be visible to logged-in visitors. Sign in to view all comments.