Write Better Git Commit Messages To Increase Your Productivity

Paul Knulst -

Within this guide, I will show how you can format your Git commit messages in a way that will optimize productivity not only for you but for your whole software development team. This guide assumes that you understand the basic Git workflow.

Why Should You Write Git Commit Messages Anyway?

To understand why Git Commit messages are important for everyone you can open up any personal or company project you were working on and execute git log to get a list of old commit messages that were used.

Most people will see a list of at least some commit messages that look like:

commit 74b187e20b796ef243a6d47d2bd32f17fa5c0942 
Author: *****
Date:   Wed Feb 16 17:07:55 2022 +0100
clean up

commit 6b907b81bb1075a6faa596bc639ee0939359e29a
Author: *****
Date:   Wed Feb 15 12:17:55 2022 +0100
fix format

commit fda43da641946a9c50988474b15ac8d1f7d05343|
Author: *****
Date:   Wed Feb 15 12:03:23 2022 +0100
hotfix URL

commit 09f6f131dece7bf9056063b9b4235f49caf8e0a5
Author: *****
Date:   Wed Feb 14 11:17:15 2022 +0100
redo fix

commit 75810b248462dc17adb3dae402b344f7fef85862
Author: *****
Date:   Wed Feb 14 09:35:43 2022 +0100
fix style

If you got to ask what the developer has done you cannot answer it because the Git Commit messages are not meaningful. Also, if you are asked to remove Ticket XY you do not know which commits to revert. Furthermore, if a commit introduces breaking changes you also do not know about by reading the commit messages.

If you had written readable and information complete commit messages you are future-proof yourself and every other developer. You will save time researching and troubleshooting just by writing down what was done in the Git commit messages.

General Structure Of A Commit Message

There are two different ways to create a commit message in the Terminal:

Basic:

git commit -m <your_message>

Detailed:

git commit -m <your_message> -m <detailed_description>

5 Steps To Improve Your Git Messages

  1. Capitalization and Punctuation: The first word should be capitalized and not end in punctuation.
  2. Commit type: The type of the commit has to be specified to describe your changes. You could use: Bugfix, Refactor, Hotfix
  3. Length: The first line should not be longer than 50 characters and the body should be restricted to a line length of 72 - see Linus Torvalds explanation or this helpful guide
  4. Mood: Always use imperative mood in the subject because it gives the tone you are giving an order or request
  5. Content: Direct sentences without phrases like: though, I think, kind

Content is very important and if you write it you should consider and answer the following questions while you write it down:

  • What is the reason for these changes?
  • What was the effect that my changes made?
  • Why was the change needed?
  • What are the changes in reference to?

Always try to summarize in a way that every reader understands the changes without having detailed background information about the change. Obvious changes should still be explained as detailed as possible.

As an example, compare these two commit messages:

  1. git commit -m “Add margin”
  2. git commit -m “Add margin to header because it overlaps with the breadcrumb text”

If you will read these commit messages it is obvious which one of these is more informative.

A Step Further - Use Conventional Commits

Conventional Commits is a specification that contains a lightweight convention on top of commit messages. It has an easy set of rules for creating a readable, understandable, and informative git commit history. This should lead to a more productive team where every developer can understand and maintain the git history.

When using Conventional Commits every commit message should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

The commit message contains the following three elements: header, body, footer

Commit Message Header

The header consists of a mandatory type, an optional scope, and a mandatory short description.

The type can include:

  • feat: introduce a new feature
  • fix: patches a bug in your codebase (bugfix or hotfix)
  • build: changes that affect the build system or external dependencies
  • chore: updates dependencies and does not relate to fix or feat and does not modify src or test files.
  • ci: changes that affect the continuous integration process
  • docs: updates the documentation or introduce documentation
  • style: updates the formatting of code; remove white spaces, add missing spaces, remove unnecessary newlines
  • refactor: reactors code segments to optimize readability without changing behavior
  • perf: improve performance
  • test: add/remove/update tests
  • revert: reverts one or many previous commits

The optional scope provides additional contextual information.

  • Allowed scopes depend on the project
  • Don’t use issue identifiers as scopes

The description is a short summary of the code changes.

  • Use imperative mood!
  • Only lowercase
  • No punctuation

Commit Message Body

The commit message body is optional and is provided one blank line after the description. It may consist of any number of newline paragraphs that should not exceed 72 characters. Also, the body is treated as free-form.

Footer Message Body

One or more footers are allowed and are provided one blank line after the body and must consist of a word token that is followed by a :<space> or a <space># separator, followed by a description (or any string). The word token must use — instead of spaces: Designed-By: UserX, Acked-By: John, Solves-Ticket: Jira-123

An exception to these rules happens if the commit introduces a breaking change to the software. If this is the case the footer must consist of the uppercase text BREAKING CHANGE, followed by a colon, a space, and a description.

Examples

To demonstrate the rules I added some examples of how to use Conventional Commit Messages

Commit message with the description and a breaking change footer

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Commit message with multi-paragraph body and multiple footers

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

Commit message that adds a feature based on Ticket 473

feat: send an email to the customer when a product is shipped

Solves-Ticket: Jira-473

Comparison Of Git Commit Messages

As an example, you can review the following commit messages that could be exchanged with each other but will provide different information.

Good

  1. perf: optimize loading of items on landing page
  2. feat: send an email to the customer when a product is shipped
  3. fix: add the correct company name to the footer and replacing the dummy text
  4. revert: revert a previously introduced bug in items retrieving from database

Bad

  1. optimize landing page
  2. send email
  3. oops
  4. I think I fixed it this time?

I want to show here that having a well-formatted commit message will explain the task that was accomplished in more detail, and developers who do not work on a project could also understand what was done in this Git commit.

Writing a well-formatted commit message is a beneficial skill for every developer that also enhances the productivity of the whole software development team. The communication between developers becomes better and it is easier to collaborate.

Closing Notes

Always keep in mind that commit messages are used to archive every change that was made to the software and can become a manuscript to decipher the past. Also, it could help you as a developer to make reasoned decisions in the future based on the work that was done in the past.

In this article, you learned the basics of how to improve your own Git commit messages. I hope you find this helpful and are able to apply it in your own software projects.

Also, after you applied Conventional Commits to your software development team you could introduce this npm project that could be used to automatically create changelog files from commits done using the Conventional Commit approach

I would love to hear your ideas and thoughts about these methods. If you know another approach or have any questions, please jot them down below. I try to answer them if possible.

Feel free to connect with me on Medium, LinkedIn, Twitter, and GitHub.