Write Git Commit Messages That Your Colleagues Will Love
Tags: webdev, javascript, git, beginners
Published: 2022-07-01 12:58:58

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.](https://www.goodreads.com/quotes/835238-indeed-the-ratio-of-time-spent-reading-versus-writing-is))

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](https://github.com/bitcoin/bitcoin/commit/eb0b56b19017ab5c16c745e6da39c53126924ed6) repo.

```git
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:
* Focus On The Why
* Use Imperative Mood In Subject Line
* Restrict Subject Line Length to 50 Characters

To learn more git commit best practices, check out [this excellent blog post](https://cbea.ms/git-commit/).

---

_Connect with me on [Twitter](https://twitter.com/prplcode), [LinkedIn](https://linkedin.com/in/simeg), or [GitHub](https://github.com/simeg)_