The practical guide to Git commit message conventions

{{text-cta}}

Ask any developer if defining a Git commit message convention is on their to-do list, and chances are they'll tell you yes. They'll also tell you it's been on their list for quite a while but that they've never got a chance to get it done. It's a bit like flossing your teeth – everyone knows it’s a best practice for keeping your gums healthy and avoiding the trip to the dentist, but sometimes you don't "get to it".

My goal with this guide is to leave you with NO excuse for not defining a commit message convention. I’m going to explain the reasons why you should define a git commit message convention, and share detailed instructions to help you move this task from your to-do list to “DONE” in a few simple steps!

(I'll leave the conversation about your flossing habit to your dentist).

Why use a commit message convention?

‍

Better collaboration across committers

It is important to communicate the nature of changes in your projects in order to foster transparency to a slew of people: existing teammates, future contributors, and sometimes 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 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

‍

Whether you’re working on an open source project, working on your own, or with your team on a single project, standardizing your Git commit messages 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 two ways to go about doing it:

‍

1. Adopt de facto best practices

This approach is about setting a simple and easy guideline, which is good for getting folks get used to the idea of having a convention. It's also good when you work with many junior developers on the team. You can start with these top 5 best practices and implement them 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 an issue tracker – if you are working with an issue tracking system (like Jira), it is important to create a logical link between the issue ticket number and the subsequent code change.

2. Adopt an existing naming convention framework

This approach is relevant for more advanced or 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 convention

‍

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 (myself, my teammates, and outside contributors) consistently follow the convention? My top two solutions for that are:

‍

1. Git hooks

‍

Git hooks are scripts in Git that can be triggered and executed automatically, before or after different Git events. The hooks are a built-in feature of Git and can run locally.

The pre-commit hook is the relevant Git hook to set in order to enforce commit message conversion.

‍

Setting a Git (client-side) pre-commit hook

1. Cd into your project dir:
   $ cd /path-to-your-git-repo
2. Edit the hook*:
   “prepare-commit-msg.sample”
   *you can use my script and the RegEx Cheatsheet in end of this article for that.
3. Rename “prepare-commit-msg.sample” to “prepare-commit-msg”
4. Optional:
   
5. Distribute the hook among your teammates.
6. If you want to set the same hook on all your different projects, you will need to set it as a global hook.
7. All set! The hook will run before every commit and will check the commit message convention.

Git hooks pros & cons

Pros:

• A built-in Git feature, which means it can be used with every Git vendor (GitHub/GitLab/BitBucket) “out-of-the-box”
• Can be triggered locally before every commit so the feedback loop is immediate

Cons:

• No “gate-keeper” since requirements are defined by the user, meaning they can also be easily ignored by the user
• Configured locally so every existing and potential contributor needs to install it on their own environment

{{text-cta}}

2. Datree policy rules engine

‍

Datree.io (disclaimer: I'm a Co-founder) is a git-based policy rules engine that helps you automate adoption of development best practices. A Git commit message convention is a popular best practice people use Datree for.

Datree works by running automated checks on every commit and pull request, to ensure the code being committed follows all the rules you set.

To enforce a git commit message convention, you simply need set a rule and enable it.

‍

Setting a commit message policy rule

1. Sign up for Datree (unlimited 14-day free trial, and free for indie open source) and install on your repositories.
2. Create a custom commit message rule (you can use the RegEx Cheatsheet below).

3. Optional: if you don’t want to waste your time with regex, you can just activate one of our built-in rules, such as use Angular’s commit message convention, or link commit message to a Jira ticket.
4. Choose the repositories you want the new policy to be applied to.
5. Done! Datree runs an automated check on every commit to ensures all Git commit messages adhere to your convention.

Datree Pros & Cons

Pros:

• Easily defined in one place, so there is no need to distribute the regex to every developer and configure it locally
• Easily enforced from the server side, so it’s harder to push non-compliant commit messages to the master branch

Cons:

• Currently it leverages the GitHub’s Checks API, which means it only supports GitHub
• The check is automatically triggered by the pull request. This means you'll only get an indication if all the commits in the pull request are following the convention at that point in time

‍

Git Commit Message RegEx Cheatsheet

‍

[[embed=1]]

‍

Bottom line

‍

It’s imperative to set up a policy that everyone follows for commit messaging and floss your teeth. While both may seem like a pain now, they aren’t a big deal, once you start, you wonder why you waited so long and having healthy gums and clean code both make you smile more 😁