A guide on commit messages

The comic is from Daniel Stori. It is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License

The time you had an archive file on your disk called "version 1" should be far away. I bet you use some tool for version control like GitHub, Gitlab, Bitbucket, ... So you must write commits everytime you want to add your code to a project. Have you ever wondered if your commits messages are good? Maybe you don't like writing them and wonder why you have to do it every time you want to push code. After all, isn't the change sufficient enough?

In this article, we will talk about writing good commit messages, and not good commits, even if these two subjects are closely linked (here is a good article from Tobias Günther that summarize well best practices about version control).

Why commit messages are important?

So, is the change sufficient? Obviously, the answer is no. But why?

Commit messages have a lot of uses. This is the first way to communicate with your fellow developers on a project. The change defines how you achieve something but the commit message explains why you are doing it. It must give enough context to avoid a developper to wonder why some code is written like that. With proper explanations you won't spend precious time asking yourself why a developer pushed this code. In some cases like open source projects, busy maintainers won't even read your code if you don't give them a minimum of information like a nicely written commit message.

Commit messages are not only for your coworkers but also for your future self as Peter Hutterer said in this great article On commit messages.

Any software project is a collaborative project. It has at least two developers, the original developer and the original developer a few weeks or months later when the train of thought has long left the station.

Peter Hutterer - On commit messages

A project is designed to be maintained in the long term. Sometimes years after a piece of code was written, you may ask yourself why it has been written like that. It happened to me this week with a function I coded only 6 months ago. With a well written commit message, it is easier to get back in the state of mind at the time you wrote this change.

Taking care of your commit messages can also simplify your daily life. Some tools becomes more interesting with a meaningful commit history like a few git commands log, rebase, cherry-pick, ... When you come back from holidays a simple git log --pretty will give you a lot of information about what your coworkers did while you were away. Writing good commit messages forces you to split your change, making it easier to review with git log -p.

Speaking of review, did you ever struggle rebasing your code on some change a developer made? It becomes easier to know why a change was made if the commit message carries real meaning. It makes rebase result much more predictible. Another example is git blame command which, by the way, isn't there to make fun of your colleagues, but to give you context on a specific line of code. It can be pretty useful when you want to refactor a piece of code.

Last but not least, a well structured commit history allows changelog generation between two versions of your project to inform your users what changed.

This is a huge amount of reasons to start taking time to write good commit messages.

How to write a good commit message

Now that you are convinced commit messages are important, let's talk about how to write good ones. I picked commit messages from a project I work on called immutadot. As you can see, these commit messages are not consistent, which makes them hard to read.

fix #72 unnecessary object copies
Fixing unshift documentation examples
seq.chain path parameter fix #18
Remove built files
Add tests
Add Circle CI base config
Rename es -> src
Add lang package with toggle, fix exports
Core package

In these commit messages, we can see a few mistakes in term of style, content and metadata. Chris Beams accurately describes these three points in his article How to Write a Git Commit Message.

Style. Markup syntax, wrap margins, grammar, capitalization, punctuation. Spell these things out, remove the guesswork, and make it all as simple as possible. The end result will be a remarkably consistent log that’s not only a pleasure to read but that actually does get read on a regular basis.

Content. What kind of information should the body of the commit message (if any) contain? What should it not contain?

Metadata. How should issue tracking IDs, pull request numbers, etc. be referenced?

Chris Beams - How to Write a Git Commit Message

We can see there are capitalized messages, metadata for only two commits... Eventually, some messages content are so light we can't figure out what the commit does. In the same article, Chris goes through 7 rules to write a good commit message :

1. Separate subject from body with a blank line
2. Limit the subject line to 50 characters
3. Capitalize the subject line
4. Do not end the subject line with a period
5. Use the imperative mood in the subject line
6. Wrap the body at 72 characters
7. Use the body to explain what and why vs. how

Chris Beams - How to Write a Git Commit Message

I personnally apply a subset of these rules:

• Limit the subject line to 50 characters
• Capitalize the subject line
• Use the imperative mood in the subject line

Not only does the character limit force you to be concise, which is a great skill, but it fits well with a lot of tools as explained in Tim Pope article A Note About Git Commit Messages.

I tend to think the perfect is the enemy of the good. That is why I omitted talking about commit messages body. I think we have enough work to do on the summary line. But I would add one rule as counterpart:

• Add a pull request/merge request tracking ID

Most of the time, we use tools to discuss during a code review process like GitHub, Gitlab, ... All pieces of information about the change will be at least described there. I added this rule about tracking ID so it becomes easy to find related pull/merge request. Writing a commit body is better than adding tracking IDs because if you change your repository manager solution, you will lose all this precious context information and your tracking IDs will be useless.

Here is a more recent example from a project I work on called gitmoji-changelog that follow these rules:

Make core independent from the git client (#171)
Upgrade Docker image version (#167)
Add maven preset (#172)
Add a generic preset using configuration file (#160)
Improve error messages for preset system (#161)
Publish Canary version on master push (#141)

Having a consistent style makes it much more easier to read. You can figure out the context of the change, and metadata are directly accessible. The most important thing is to find common rules in your team to ensure having a well structured commit history. There are some conventions that can help you finding these but we will be back on this subject later.

If you have difficulties to find out what message you should write, maybe you should split your commit in smaller parts. Peter Hutterer listed in his article On commit messages a few examples where it is difficult to find out a good commit message because your commit patch may not be logical.

Bonus

If you use practices like pair or mob programming, don't forget to add your coworkers names in your commit messages:

$ git commit -m "Refactor usability tests.
>
>
Co-authored-by: name <name@example.com>
Co-authored-by: another-name <another-name@example.com>"

Commit conventions

As written in the previous section, you should define a commit convention for your team. It exists open source commit conventions that could be a good source of inspiration. They also come with a whole ecosystem that includes tools to help you write commit messages, generate changelog, create releases, ... A lot of things that can take a large amount of time. There are well documented so you don't have to write documentation about your own commit message convention.

We will talk about two of them Conventional Commits and gitmoji.

Conventional Commits

It is a specification inspired from Angular commit message guidelines. It features a few interesting rules like:

• Commit must be prefixed with a type (feat, fix)
• A scope may be provided to point out a specific section of a the codebase (really interesting for monorepos)
• Breaking changes must be included in a footer section

Here is how a commit message must be structured using this specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Read more in their specification section.

gitmoji

I'm fond of gitmoji commit convention. It lies on categorizing commits using emojies. I'm a visual person so it fits well to me but I understand this convention is not made for everyone.

I was not totally honest in my previous commit examples from gitmoji-changelog. There is a missing part as you should have guessed now.

:recycle: Make core independent from the git client (#171)
:whale: Upgrade Docker image version (#167)
:sparkles: Add maven preset (#172)
:sparkles: Add a generic preset using configuration file (#160)
:recycle: Improve error messages for preset system (#161)
:construction_worker: Publish Canary version on master push (#141)

These text aliases are widely used in tools like Slack, Discord, ... Most of the repository manager tools like GitHub or GitLab interprets them and display it well in their UI:

♻️ Make core independent from the git client (#171)
🐳 Upgrade Docker image version (#167)
✨ Add maven preset (#172)
✨ Add a generic preset using configuration file (#160)
♻️ Improve error messages for preset system (#161)
👷‍♂️ Publish Canary version on master push (#141)

I like this convention because I know at first glance what kind of change do a commit. It comes with a cli called gitmoji-cli that helps you write your commit messages and I made a changelog generator for it.

There are more of them. Keep in mind that these are guidelines, you can mix them to get something that fills your need. For example, using gitmoji convention with the scope notion of conventional commits if you work on a monorepo.

Feedback is appreciated 🙏 Please tweet me if you have any questions @YvonnickFrin!