Writing a Good Git Commit Message

Before we jump into the best practices for composing top tier Git commit messages, let’s start with a quick refresher on what a commit is in Git.

Git commits are a way to “record changes to a repository.” A Git repository is the collection of files tracked in the .git folder of a project. In simple terms, a commit is a snapshot of your local repository. 

It can be helpful to think of a commit as a checkpoint or savepoint for your project. In many video games, checkpoints are reached and your progress is saved after completing a specific action or challenge. Similarly, a Git commit is usually performed after a significant contribution is made to your project and you want to save your progress. 

With that perspective, it’s easy to understand why `git commit` is one of the most frequently used Git commands. Each time a developer performs a commit, they’re given the option to write what’s called a commit message. Git commit messages are used to explain the function of the commit. 

What Makes a Good Commit

If by taking a quick look at previous commit messages, you can discern what each commit does and why the change was made, you’re on the right track. But if your commit messages are confusing or disorganized, then you can help your future self and your team by improving your commit message practices with help from this article.

For example, if you committed after making a simple update to the README file of a project, you might include a message that looks something like this: “Updates README for punctuation”. Now imagine a README file update with any of the following commit messages: “uPdatEd puNcTUatiOn”, “made fixes”, or “Chipotle rules”. It’s easy to see how this style of commit message could get out of control. While you might get away with one or two off-topic or unclear commit messages, they can quickly come back to haunt you and your team after they start adding up.

In this article, we will go over how to write good Git commit messages using GitKraken Desktop’s CLI and GUI, as well as tips and tricks you can apply to your commit messages to improve team communication and improve repository health. Even though the examples we’ll reference are in GitKraken Desktop, these tips are just as applicable for VS Code users. 

Git Commit Workflow

Before you can start writing top-notch commit messages, you first need to understand the workflow associated with making a Git commit. In order to make a commit, a developer must:

1. Make changes 
2. Stage changes
3. Commit changes

Making changes involves adding, deleting, or changing anything on a local branch. Anything changed on that branch is included in what’s called a working directory. 

Staging changes means taking the files that you’ve changed and moving them to a “ready to commit” state called the staging directory. You may also hear developers refer to the staging directory as the staging area or index. You can stage as many files as you want, but it’s important to note that multiple files staged together will all share the same commit message. 

This means that you’ll want to be sure that the commits all relate to each other in a way that makes sense to you and your team. You could, for example, feasibly stage a group of files that all focus on a specific hotfix you are working on. Conversely, it wouldn’t make sense to stage multiple files if each file focuses on an entirely different scope of your project. 

Committing, as we’ve covered, is the act of creating a snapshot of your local repository. This is how developers save their work and is a common Git command. 

Commit History

A record of all the commits included in a project is called the commit history and can be accessed in a variety of ways depending on what Git tools you use. Accessing the commit history using GitKraken Desktop can be done by running git log in the built-in CLI, or by simply viewing the GUI’s central commit graph. 

If you use VS Code, you can leverage GitLens to expose your project’s commit history on every line of code, as shown below. The ability to quickly identify the commit message associated with a line of code, as well as authorship information, is incredibly valuable. Writing good commit messages that clearly explain what the code does makes this functionality all the more helpful.

A project’s commit history is valuable for you in the future, and for any other developers that contribute to the code because it provides context as to what has been done in the project. As developers get busy, established project documentation tends to fall behind and get stale. When this happens, many developers turn to the commit history to learn about the project and identify recent updates. In that light, writing meaningful and easy to understand commit messages becomes even more important.

Git Commit Message Structure

There are two main components of a Git commit message: the title or summary, and the description. The commit message title is limited to 72 characters, and the description has no character limit. While those are the established character limits, most developers suggest that the commit message summary be no longer than 50 characters, and the description be limited to 72. 

Ultimately, the trick to structuring an exceptional commit message is to find the proper balance between brevity and detail. Brief enough that it’s easy to read, but detailed enough that it’s easy to understand. 

Standardize Git Commit Message Structure

When writing commit messages, consistency is key. Whether you’re working solo or collaborating on an open source project with hundreds of contributors, maintaining a consistent style and adhering to the established commit message conventions is of paramount importance. 

Establishing a standardized commit message structure helps keep your repository clean, legible, and makes it easier for project contributors to understand the purpose behind each commit. 

If you’re working on a team, a project lead should communicate the expected commit message guidelines. Most open source projects have instructions in their documentation on commit message best practices. If you’re unable to find clear documentation, you can always take a look at the commit history and model your messages based on past commits. 

Admittedly, following a standardized commit message can feel tedious at times, but taking the time to construct a thoughtful message now will not only save you time in the long run during code reviews or project audits, it’s a simple way to distinguish yourself from your peers, and is much appreciated by project managers. 

ProTip: Some teams include a special character like * in their commit message summaries to indicate that there is more information written in the commit message description. 

Quick Git Commit Message Tips

There are a few things you can do to improve your Git commit messages right off the bat: 

1. Avoid unnecessary capitalization 
2. Double check your spelling
3. Don’t end commit message summaries with punctuation 

Abiding by these simple guidelines makes it easier to search and filter commits, as well as simply making your repository look more visually appealing. Not only are these steps quick and easy to apply, but your team members will thank you.

Using Imperative Verb Form

Another best practice to help you write good Git commit messages is to use imperative verb form. Using imperative verb form ensures that potential verbs used in your commit messages, like “fixed” or “updated” are written in the correct tense to “fix” and “updated”. 

This has become a defacto standard on many Git projects. One way to ensure your messages comply with the standard is to apply the formula: “If applied, my commit will…” You can apply this to the example:

“If applied, my commit will (INSERT COMMIT MESSAGE TEXT)”

Summary:

Add new Kief-the-kraken Keanu-Kief to keif gallery

Description:

Modify menu.yml and keif-gallery.md related to ticket #12345

Jira Integration Issue ID or Ticket Number

One way to include additional context to your commit message is to reference an associated Jira issue ID. While this should not be used as a replacement for a quality commit message, adding a Jira ID can help other developers on your team reference additional information regarding what your commit addresses. 

GitKraken Desktop Pro users can leverage the Jira integration to start using this practice in their workflows. 

To write a commit message tied to a Jira issue using GitKraken Desktop Pro follow these steps:

1. Select JIRA ISSUES from the left panel
2. Find the issue you want to reference 
3. Identify the issue ID
4. Select the ellipses next to the issue and click Copy issue link

Commit the changes that relate to the issue and compose a Git commit message that looks like the example below: 

Summary:

Update electron version to enable faster speeds <closes Jira Issue #123>

Description:

Changes the abc in order to comply with xyz. See Jira ticket #123 for further details. paste issue link

Conventional Commits

The conventional commit message style is another way you can level up your commit messages. The conventional commits structure involves starting your commit message with a specified commit type. Commit types include:

Feat– feature

Fix– bug fixes

Docs– changes to the documentation like README

Style– style or formatting change 

Perf – improves code performance

Test– test a feature

Using the conventional commit method makes it easy for project contributors to filter and search for specific commits, as shown in the example below: 

Summary:

Docs: Fixes typo on in-from-the-depths.md

Description:

Closes ticket #54321

Git Commit Frequently

Another simple way to dramatically improve the quality and utility of your commit messages is to commit more frequently. Not only is committing often a good idea in the first place because it ensures that your work is saved, it also makes it easy to keep your commit messages succinct and to the point. 

Let’s say, for example, that you’ve completed a full day’s work and haven’t committed any of it. Crafting a clear and concise commit message is going to be nearly impossible. 

On the other hand, if you commit often, it’s easy to write out a simple commit message like the one below that clearly gets the point across without taking up too much time or being verbose. 

How to Create Great Commit Message with the Command Line

To put your newfound Git commit message best practices to use using the Git CLI in GitKraken, you will first need to select Terminal from the top toolbar. 

Now, you need to stage the changes from your working directory. Running git status is a good way to view files that need to be staged. From here, you have two options: you can stage an individual file, which is what’s generally recommended, using git add <file name>, or, you can stage all of the files in your working directory using git add -all. 

One amazing advantage to using the CLI in GitKraken Desktop is that you don’t have to run git status again to confirm that your file was staged correctly. 

GitKraken Desktop makes it easy to visually confirm whether the expected Git action is truly happening with its famous commit graph and helpful commit panel. The commit graph shows you the project’s commit history, while the commit panel on the right displays a file as it moves from the working directory to the staging directory, and finally, to the commit message. 

From here, you can apply the Git commit message best practices you’ve learned by using git commit -m <Summary>, or the more detailed git commit -m <Summary> -m <Description>. Deciding which of these to use will depend on the standardized commit message mechanics agreed upon by your team, or the project’s default message structure. 

Keep in mind,  writing a comprehensive and detailed commit message now will save you time in the future. 

How to Write a Good Commit Message using GitKraken Desktop

Composing commit messages is simple using the GUI in GitKraken Desktop. Start by staging the files from your working directory that you want to commit. You’ll notice that GitKraken Desktop keeps a list of all the unstaged files in your working directory in the “Commit Panel” located on the right side of the UI. 

If you’ve made changes to multiple files in your working directory but want to stage a specific file, hover over the file name and click the Stage File button that appears just to the right of the file name. To stage all of your changes, simply select the Stage all changes button on the upper right side of the panel.

You can easily verify that your files are staged using GitKraken Desktop as they move down the Commit Panel from the Unstaged Files section to Staged Files section just below. 

Once your file is staged,  you’re ready to compose a top tier commit message. Navigate to the section marked Commit Message at the bottom of the Commit Panel and select Summary. 

Here, you have 72 characters to summarize the purpose of your commit and apply the best practices covered in this article. When you’re satisfied with your commit summary, you have the option to select Description just below to provide additional context. Follow the guidelines established by your team or project lead to fill out a detailed description. 

When you’re satisfied with your commit message, select the green Commit changes to (#) file button. You can verify that your commit was successful by referencing the central commit graph.

How to Edit a Git Commit Message

Because committing is so common in Git workflows, it’s almost guaranteed that at some point you’ll need to know how to edit a Git commit message. The most common reasons that would require you to change a Git commit message include typos and adding clarifying content. 

To Git edit a commit message in GitKraken Desktop, simply select the commit, navigate over the commit panel, click into the box with the current commit message displayed, make the necessary edits, and then select the green Update Message button. Simple as that! 

To Git change a commit message in the command line, you can use:

 git commit --amend -m “new commit message” 

You should be aware that you can only edit your most recent commit. That’s why it’s so important to make sure you scrutinize the spelling and formatting of each commit message. 

Changing the Git commit message associated with an older commit requires you to revert a Git commit, and is a much more nuclear option. 

Quality Git Commit Messages = Time Saver Later on

Applying these Git commit message best practices will help improve your ability to navigate your project’s history, understand changes, and provide useful direction for the future of your project. Writing comprehensive commit messages doesn’t have to be tedious or unreasonably time consuming. Plus, tools like GitLens and GitKraken Desktop are here to help you capture the benefits of writing high-quality commit messages in intuitive and unobtrusive ways!