Write Git Commit Messages That Your Colleagues Will Love

8UbD...AfY8

14 Jul 2022

Git commit messages are how we communicate to our future selves. They help you understand why a certain line of code was added to the code base. That's why knowing how to write a good Git commit message is important.

We've all been there; "Git is confusing", "Why can't I just push to the main branch?", "No one will ever read this message". These thoughts are normal and most people that have learned Git can probably relate. You might not appreciate good commit messages until you work with a code base that's been around for years. Or when you return to an old project of yours.

In this article, I'll show you how to write Git commit messages that you and your colleagues will love.

Why Git Commit Messages Are Important

Have you opened up an old project and checked the commit messages with git log? If not, I recommend you do that now. If they're not filled with "Fix styling" or "Add endpoint" then great job! If you're like the rest of us, read on 😄

Or perhaps you joined a company with a code base that's been around for a few years. And you're trying to understand why some piece of code was added. Will you break anything if you change it? In this case, a good commit message is invaluable.

Simply put, by writing good Git commit messages you are future-proofing yourself and your colleagues. And as developers, we are reading a lot more code than writing it.

Reading vs. Writing Code

Uncle Bob (Robert C. Martin - author of popular programming books such as Clean Code) says

“Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. ...[Therefore,] making it easy to read makes it easier to write.” (ref.)

At times, to understand the code you will also need to read the commit message. I hope that you now see that the effort of writing a good commit message is worth it!

How To Write Good Git Commit Messages

Now that you're convinced that commit messages are important, let's look at how you can write them in a way that your colleagues will love!

A commit message consists of two parts: the subject line and the body. Here's an example from the bitcoin repo.

commit eb0b56b19017ab5c16c745e6da39c53126924ed6
Author: Pieter Wuille <pieter.wuille@gmail.com>
Date:   Fri Aug 1 22:57:55 2014 +0200

   Simplify serialize.h's exception handling

   Remove the 'state' and 'exceptmask' from serialize.h's stream
   implementations, as well as related methods.
   ...

The first line is the subject and what follows after the new-line is the body.

Focus On The Why

This is the most important rule. And it's also the most common mistake. Commit messages should explain why the code was added, not what was added. To see the what I can just read the code. But to understand the why I can only guess.

Even if I'm the author of the code, I will eventually forget the why.

Use Imperative Mood In The Subject Line

Imperative mood means "used to demand or require that an action be performed". This is the mood Git uses by default, and so should you.

For example, the git revert command will create a so-called "revert commit" for you. This commit will have a subject line with an imperative mood - "Revert 'Add field to schema'".
You can think about it that you are telling the system/app/etc. how to behave. This might be awkward at first but you'll get used to it.

Note: You can write in whatever mood you prefer for commit bodies.

Restrict Subject Line Length to 50 Characters

Have you ever seen a commit message on GitHub that ends with ...? That's because GitHub truncates the subject line if it goes above 72 characters. The rest of the subject line moves to the commit body.

50 characters is the recommendation by GitHub. The limit exists to make the commit more readable. And you're forced to explain your code changes in a concise and comprehensible way.

If you're having problems explaining your code changes with 50 characters you might be committing too many changes at once. If this is the case, you should split the commit into multiple commits.

Conclusion

These are the three most important rules to follow when writing Git commit messages. If you follow these rules your colleagues will quickly understand what the commit is about.

To summarise: