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).
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.
“$ 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.
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:
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:
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:
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:
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:
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.
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.
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 😁
10 most useful git commands guide: the intuitive and actual commands for common git tasks like renaming a branch, removing files, and undoing changes, and more.
"I’ve had my fair share of rewrites and refactors, ranging from reverse engineering a 1000+ lines of a single PHP file and rewriting it as a microservice, to better scaling it for performance." A guide to code rewriting vs. refactoring.