Safdar Ali

Posted on Jun 28

“Good Commit” vs “Your Commit”: How to Write a Perfect Git Commit Message

#git #commitmessages #versioncontrol #codequality

"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 (15)

thomas menzel • Jun 29

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"

Gopikrishna Sathyamurthy • Jun 29

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 paste~~ reminder of this article from 2014: cbea.ms/git-commit/

tacodes • Jun 29

Wow it sure is. Sigh

Will Fry • Jun 29

I mean you could make the exact same argument for "when you apply this commit it 'fixes bug 2345'".

Thaísa Vieira • Jun 28

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!

Safdar Ali • Jun 28 • Edited

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 ✨.

MuhammadAnas8 • Jun 29

Thanks for sharing

Safdar Ali • Jun 29

You're Welcome :)

Gopikrishna Sathyamurthy • Jun 29

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...

🚀 🚀 🚀

Safdar Ali • Jun 28

Thanks for 23428! 🤗

𒎏Wii 🏳️‍⚧️ • Jun 29

Personal anecdotes don’t belong in commit messages

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.

Resolve issue #456: Fix null pointer exception in UserService

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".