In my Git courses and workshops, I teach how to write a good commit message. For me a great commit message has to be clean, precise, specific to solve one thing at a time and traceable. But there is actually more precision we can add to a commit message as I recently have found out. The future in using Git is called Conventional Commits and fosters an even more human and machine readable way of writing good messages for our commits.
I like Git very much, you might know that by now. And I am getting excited like a tomb raider when I discover something new about it. So here is my latest discovery.
A commit in Git is an object which points to a so-called snapshot object whereas the snapshot object then references the actual files we want to save in our local repository. In other words: the commit command is used to save changes to our local repository after staging them. However, when you create a commit, Git will ask us to add a message to the commit and that is what is called the commit message. A commit message lets us identify the changes we have added to the local repository with that commit. Now you can imagine that the better such a message is formulated, the better you and others can understand why this commit is/was needed (and which bugs may have been introduced ). By forcing us to write precise commit messages, we more and more realize that the less we put into one single commit, the better others can review (reviewability) our PRs. And not only that, but by improving our writing style we can also improve the readability and traceability of our changes we put into a repository.
Since I started out with using Git and digging deeper into it by creating an online course for TAU, giving workshops all over the place and gaining real world experiences with it at my customers, I started to care about writing good commit messages. Because besides all the nice things we gain with it from above, we also will get a shiny commit history on our main production branch (and of course on other branches, depending on the branching strategy we choose).
Recently as I was out there, I stumbled across Conventional Commits - a simple guide on how to add a human and machine readable format to commit messages.
But how does now a good commit message look like according to this guide? Here is how the structure looks like:
The header with the <type> is mandatory and has to be a one liner. The <scope> in the header on the other hand is optional as it is project specific (here an example from the Angular spec. For example an exclamation mark (!) might be used to draw a reviewer’s and later on a readers attention. Then using a gitmoji right after the colon (:) makes it even easier to spot what changes a commit introduces. Even if someone is unfamiliar with the message itself, one can quickly understand the general idea behind a commit. But be aware that not all of the remote repository managers out there do support gitmojis (e.g. GitHub does support them!). The <subject> contains a detailed description of the change. In order to write a great subject, one should:
- use the imperative form (e.g. correct and not corrects or correcting)
- not capitalize the first letter
- not putting a dot (.) to its end.
The body is optional. If used, it should contain the detailed motivation of the change.
The footer is also optional. If used it can for example contain the reference to the (GitHub, JIRA) issue which is meant to be solved. Further it can also contain a breaking changes block like in this example here.
But how would I apply the new things learned from above? Here a first example of commit message I came up with:
Now it is on us to go back to our projects at work (and of course also our private ones) and experiment, practice and improve the thing we do by applying conventional commit messages. 😄
Here are some IDE extensions which support us in writing conventional commit messages.
Visual Studio Code Extension:
Of course there are tons of more tools available
Conventional commit messages makes it easy for your teammates and 3rd parties to tag along and contribute to a common code base. Further it makes it easy for tools to process commits.
I hope you have learned something new as I did.
Enjoy, stay safe and be happy 🙂