How to Take Your Git Commit Messages to The Next Level With a Commit Template

Efren Marin
5 min readDec 21, 2022

--

Whether you’re working on a solo project or part of a development team, you will have had multiple commit messages that don’t always make sense. Whether it’s the infamous “WIP” or a vague description that doesn’t encapsulate the whole story, we’re all guilty of this.

Allow me to share what has worked for me and what I’ve introduced to my development team for our daily git commits. With some planning beforehand, this will show you how to set up a git commit template for cleaner and concise messages.

Overview

Having a commit template embedded into your workflow not only allows for more detailed and precise commit messages but it also sets a standard for teams to follow.

I’ll break down the steps needed into segments.
- How to create a template file that git can use.
- How to set up a custom template on your machine.
- How to actually use it.

Creating a Template

Is your pet peeve receiving a pull request with an enormous amount of files changed and non-descriptive commit messages? Yeah, mine too. I know I’m not alone on this one so let’s begin by creating our template to help prevent this.

We will be loosely following Conventional Commits so if you are unfamiliar with this, I strongly suggest you give them a click.

Dwight demonstrates he’s ready to do this.

First start off by creating a .txt file and naming it something precise like commitTemplate.txt for example. Place this file somewhere within your folder structure where you can easily access it. I placed mine in my development folder where my repo’s are cloned.

Now populate your commit template file. You can use my example, or modify it to what you and your team need. It’s important to know a couple caveats to this template.

  • One, any line that starts with “#” will not appear in your final commit message but will show up as commented out in the template. If it does not include a “# ” then you’ll be able to type in that line.
  • Two, for the sake of `git log — oneline` keep your title under 50 characters.
  • Three, the body and footer can be up to 72 characters per line.

The template I’m sharing includes a section for the developer to type in their commit message as well as the team standard below for reference. Okay, now with that understood, here is the template we’ll be using:

# 
#########################
# Start of Commit Message
#########################
#
#
# Title

# Body


# Footer

#
#
#######################
# End of Commit Message
#######################
#
#
# Keep each commit line under 50 characters
# Following conventional commits 1.0.0
#
# Use the prefix naming convention:
# fix: patches a bug in the codebase
# feat: introduces a new feature to the codebase
# refactor: only used when refactoring code
# docs: used when modifying/creating docs
# build: when preparing for a build
#
# Commits should follow the format below:
#
# [Title]
# <type>: In under 50 characters, description of the commit
#
# [Body]
# Explain in detail what was done in this commit and
# what this is supposed to achieve. Keep this section
# under 72 characters per line.
#
# [Footer]
# Use this section to add any PR/Ticket numbers that this
# commit is solving or any co-authors. If none of these apply, # leave it empty.
#
#
#
#
#

Setting Up Our Template

With the template file created and populated, we now need to point Git to it whenever we want to commit a message.

From your terminal, in this case I’ll be using VSCode’s terminal, type in the following command and press enter.

git config - global commit.template ~/commitTemplate.txt

The only portion of this snippet that might be different is commitTemplate.txt assuming you named your file differently. Running this command points Git to your template file and will work globally for any project you work on using your machine.

Now let’s check to make sure this was processed by typing in

git config --global --list

This will now show you that commit.template is assigned to the file path where your template is.

Finally, to configure this to work with VSCode we will pass another command to the terminal. This time we will use:

git config --global core.editor "code --wait"

This handy line will make it so when we are ready to commit, it will open a new tab within VSCode so we can type in our message. Again, check for completion by running:

git config --global --list

How To Use Our Template

So you’ve created a commit template, set it up on your machine, and now it’s time to use it!

Simply go to one of your projects and get ready to make a commit. In order for this template to populate, your commit command needs to be `git commit` only. Once you type this in and press enter, a new tab will populate with your template. If you decide you are not ready for a commit, simply leave it empty and close the tab. Your terminal will let you know, “Aborting commit due to empty commit message”.

A commit template file example

Here we have populated the template with a title, body, and footer. As you can see the lines that began with “#” are commented out and we type in the empty lines we designated before. So your commits will really look like this:

feat: Included user feedback modal

Created a fully functional modal with a
form for users to fill out if they have
feedback. This feature can be accessed
from the home page menu bar on the top
right with a click.

PR#: 454

When you’re happy with your notes, simply save and close the tab and it will push your commit message. Simple as that!

Conclusion

There are no right or wrong items to include in your commit template. Every development team works off of different ideologies, but every development team can gain an advantage by having a commit template. Not only does it create a commit message standard format, but it also helps produce more detailed and succinct messages.

Takes about 5 minutes to implement this in your local environment so what do you have to lose? If you gained some value from this, I’d be happy to hear how it goes and your experience using it.

--

--

Efren Marin

Software Developer building the web one <div> at a time