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 done and updated .

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 git commit

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

A well-formed 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 git

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 commit-template.txt:

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.

Wrap up

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

Share this post