How to get more out of your Git commit message

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?
• Choosing the right commit message convention
• How to enforce Git commit message?
• Git Commit Message RegEx Cheatsheet
• Bottom line

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 versionbased 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

1. . 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:

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.

Set 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.

Pros & Cons

ProsConsA built-in Git feature, which means it can be used with every Git vendor (GitHub/GitLab/BitBucket) “out-of-the-box”No “gate-keeper” since requirements are defined by the user, meaning they can also be easily ignored by the userCan be triggered locally before every commit so the feedback loop is immediateConfigured locally so every existing and potential contributor needs to install it on their own environment

Datree policy enforcement solution

One of Datree’s services is a policy enforcement solution for compliant code and setting a custom Git commit message is one of the policies we support.

Set your custom commit message policy:

1. Signup to Datree (it’s a free trial) and connect 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:
4. Use Angular’s commit message convention
5. Link commit message to a Jira ticket
6. Choose the repositories you want the new policy to be applied to.
7. Done! Datree’s policy check automatically every pull requests to ensures all Git commit messages adhere to the commit message convention.

Pros & Cons

ProsConsEasily defined in one place so there is no need to distribute the regex across every developer and configure it locallyBased on GitHub’s ‘checks new API’, which means it’s supported only by GitHubEasily enforced from the server side so it’s harder to push non-compliant commit messages to the master branchThe check is automatically triggered by the pull request. At this stage, you get an indication if all the commits in the pull request are following correct commit message convention

Git Commit Message RegEx Cheatsheet

MethodBest PracticeRegExAdopt defacto best practicesHave a commit message^[^\s]{1,3}.*$Keep a short subject line^.{1,50}$Don’t end the subject line with a period.*[^.]$Start with a capital letter^[A-Z].+Link to a planning system – Jira((?!([A-Z0-9a-z]{1,10})-?$)[A-Z]{1}[A-Z0-9]+-\d+).+Adopt an existing conventions frameworkAngular Git commit message guidelines^(feat|fix|docs|style|refactor|test|build|ci|perf)(\(.+\))?\:\s(.{3,})Emoji-Log commit message convention^(\:package:\ NEW|\:ok_hand\: IMPROVE|\:bug\: FIX|\:rocket\: RELEASE|\:book\: DOC|\:white_check_mark\: TEST)(\(.+\)\:\s)?\:\s(.{3,})

Bottom line

It’s imperative to set up a policy that everyone adheres to 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 compliant code both make you smile more.