We’ve all used
git in some form or another. The code versioning system is an industry staple. With over 40 million users worldwide and 190 million repositories on GitHub,
git is here to stay.
While the concept of
git is easy - pull your code, do whatever, save, add, commit, and push - there is one thing that no one really talks about and that is the commit message.
The commit message is such a simple concept yet also one that can cause a lot of issues further down the road. Why? Because you can write whatever you want — including highly useless commit messages like
So, how exactly should we be writing
git commit messages? Here is a quick and opinionated guide on how to write a highly informative
git commit message that won't tilt your teammates.
The purpose of a
I’m sure I’m not the only one. If we are not the culprit, then we know or have encountered commit messages that do very little to inform us of anything in particular. The purpose of a
git commit message is to help us identify what code changes are made, so that in the event of a rollback, we'd know exactly what's been changed and why.
However, it’s easy to bundle fixes and feature requests into one commit — because why not? We’re already coding and we’re on a roll. While saving often is a good thing, where you save your checkpoints also matters.
The general guideline/rule is -
- make changes to only a specific portion of code at any one time
- checkpoint your code with a commit before moving onto the next task
Why is this important? because it single tasks our commit and ensures that any bugs introduced are isolated to a specific point in the code. Why you bundle bug fixes, new feature additions, and updates together into one commit, tracing issues can be a pain because you’re no longer dealing with a single change.
We make code commits to save our progress — but if that progress has an issue, we’re going to need to debug it. When there are multiple changes in various places, it is harder to pinpoint the source and where the change impact extends to.
Single tasking a
git commit makes debugging less painful and writing useful
git commit messages easier.
3 parts to a
git commit message
There are 3 parts to a good
git commit message and they are:
- the summary
- the body
- the footer
git message can inform strangers to the code what exactly you did and why you did it. It helps with rollbacks and makes tracing changes much faster than trying to figure out what
ticket 9835fi93 stands for in a commit message.
Here is an example of a bad
git commit message:
This ticket tells us nothing. Not only that, we might have to go on a ticket hunt for
Ticket #9835fi93, wherever that is located and if it still exists in the system. Now, imagine at least two dozen commits like this. Who is Roy? What is
ticket 9835fi93 and what does it entail?
git is ultimately only as useful as how you use it. Here is an example of a better
git commit message:
When it comes to
git commits, the longer you work on a project, the higher the chances of the commit messages becoming less informative over time. It takes discipline to maintain useful
git commits. This is why the three-part structure of summary, body, and footer can help keep us in line and away from one-liners that disintegrate into a button mash of words just to get it over and done with.
Creating commit templates in
To make life easier and lessen the friction of creating highly informative
git commit messages over time, you can also configure a template in
git to enforce the above structure.
This is achieved through
git.template , which is a command that lets you specify the
pathname for the file you want to use as a template for your new
git commit messages. The contents of the file can be whatever you want.
It’s good to note that
git.template is not an automated process and having a template text file will not guarantee that your commit template is enforced. The template will need to be configured for each project and up to the developer if the structure of the template is followed.
Here is an example of a template I’ve created called
Guidelines: writing useful git messages can ensure that your git commits remains useful and keep your team members happy. # FOR BUG FIXES # Summary: [what is the fix] + [where fix is applied] # Body: [description of the issue] # Footer: [ticket number] # FOR NEW FEATURE # Summary: [name of feature] # Body: [description of the feature and where it has been added] # Footer: [feature release number] # Happy coding! :)
To add the commit template to your workflow, use the following command:
git config --local commit.template "path_to_template_file/filename"
Now, when you hit the
git commit command, you'll be greeted with the contents of your git template.
This is only one of many commit template structures. Using
git.template is one way to help standardize your commit messages, especially if you’re working in a team with other developers. How detailed you want your git commit messages is ultimately up to you. One thing to keep in mind is that it should be succinct and concise. This is to prevent lower standard commit creep over time.
Low standard commits make traceability harder and defeat the purpose of using
git in the first place. When commit messages are clear, informative, and simple, it lets
git become the useful tool that it’s meant to be.
Thank you for reading and I hope you’ve enjoyed this piece.👏