Git commit message

If you aren’t already, defining your project Git commit message convention is always on every developer’s “To-Do” list. Like flossing your teeth – everyone knows it’s necessary best practice for healthy gums and avoiding the dentist, but it ends up on the ‘I’ll move it to tomorrow’s to-do list’ aka, procrastination galore.

I’m going to break down the reasons why you really have NO excuse not to set a Git commit message convention (or floss), and the required steps in order to move this task from your “To-Do” list to “DONE” in a few simple steps!

I’ll leave your dentist to yell at you about not flossing 😁

Why use a commit message convention?

Better collaboration between potential and existing committers

It is important to communicate the nature of changes in projects in order to foster transparency to a slew of people: existing teammates, future contributors, and sometimes to the public and other stakeholders. It’s obvious why a well-formatted Git commit message convention is the best way to communicate context about a change to fellow developers (and their future selves) when requesting a peer code review. A commit message convention also makes it easier to explore a more structured commit history and to understand which notable changes have been made between each release (or version) of the project.

Squeeze the most out of git utilities

“$ git log” is a beautiful and useful snippet. A well-organized commit message history leads to more readable messages that are easy to follow when looking through the project history. Suddenly, navigating through the log output become a possible mission! Embracing a commit message convention will also help you properly use other git commands like git blame, git revert, git rebase, git shortlog and other git subcommands.

Support different automation tools

Automation, automation, automation. Once you know you can rely on a standardized Git commit message, you can start building a flow around it and leverage the power of automation to level-up your project development flow:

• Automatic generation of CHANGELOG – keeps everyone up to date on what happened between releases.
• Automatic bump ups to the correct version – determine a release semantic version based on the types of commits made per release.
• Automatic triggers to other processes – you are only limited by your own imagination on this one. For example, you can decide that a predefined string in the commit message will trigger your CI.

Choosing the right commit message convention

Now that we know that having a commit message convention is useful whether you’re working on an open source project, working on your own, or working with your team on a single project, standardizing the Git commit message is the only right way to commit!

We covered the “why” part and now we will move to the “how” part – in my opinion, there are pretty much only two ways to go:

A. Adopt defacto best practices

This approach is a simple and easy guideline, good for getting used to the idea of having a convention/have a majority of coders or junior developers on the team. It’s the top 5 best practices to implement TODAY:

1. Have a commit message – white space or no characters at all can’t be a good description for any code change.
2. Keep a short subject line – long subjects won’t look good when executing some git commands. Limit the subject line to 50 characters.
3. Don’t end the subject line with a period – it’s unnecessary. Especially when you are trying to keep the commit title to under 50 characters.
4. Start with a capital letter – straight from the source: “this is as simple as it sounds. Begin all subject lines with a capital letter”.
5. Link to a planning system – if you are working with a planning system (like Jira), it is important to create a logical link between the planning ticket number and the subsequent code change.

B. Adopt an existing conventions framework

This approach is relevant for advanced/engaged teams, the key benefit of this approach is that you can also use the supporting tools in the ecosystem of the chosen conventions. There are plenty of different conventions so I will focus on the top two:

1. Angular Git commit message guidelines – well known and proven Git commit message convention which was introduced by the Angular project (A.K.A. Google).
2. Emoji Git commit message convention – I’m not kidding, it’s a thing. Incorporating emoji in the commit message is an easy way of identifying the purpose or intention of a commit at a glance, and of course, emoji are fun 😜. Because this convention is a philosophy and not a method, if chosen, I would recommend “Emoji-Log” commit message convention (by Ahmad Awais).

How to enforce Git commit message?

If you got this far, you probably agree with my opinion that every project should have a defined commit message convention. Now, the question is how can I make sure all the project committers (me, outside contributors and teammates) are aligned about the chosen convention and apply to it? My top two solutions for that are:

🔧 1. Git hooks

🚔 2. Server-side policy enforcement

Both options explained with a guide on my original blog post (I didn't add it here to keep this post short).