How to Write a Good Git Commit Message

Introduction

A good Git commit message is crucial for effective collaboration and maintaining a high-quality codebase. It provides context, clarity, and understanding of the changes made to the code, which helps other developers understand the purpose and reasoning behind those changes.

In essence, a Git commit message is a brief explanation of the changes made to the codebase. It includes the title, a short description, and an optional body, detailing the modifications made to the code. The message is then committed to the Git repository, providing a record of the changes and a means of tracking the evolution of the codebase over time.

In this article, we'll explore the importance of writing good Git commit messages, discuss the key elements of a well-crafted message, and provide practical tips and examples to help you write effective and informative commit messages. By the end of this article, you'll have a clear understanding of how to write a good Git commit message, and why it's such an essential aspect of software development.

Anatomy of a Git commit message

A Git commit message typically consists of three parts: the subject line, the body, and the footer.

Subject Line

The subject line is the first and most important part of a commit message. It should be a brief summary of the changes made in the commit. The subject line should be no more than 50 characters long and should be written in the imperative tense (e.g., Add feature X rather than Added feature X). It should also be specific and informative, indicating what the commit does, rather than why it does it.

Body

The body of a commit message should provide more detailed information about the changes made in the commit. It should be written in complete sentences and paragraphs, and should explain the reasoning behind the changes made. The body should be wrapped at 72 characters per line, and should be separated from the subject line by a blank line.

Footer

The footer of a commit message is optional but can be used to provide additional information about the commit, such as the issue or bug tracker ID that the commit resolves, or any breaking changes that may have been introduced.

Best practices for writing a good Git commit message

When it comes to writing a good Git commit message, it's important to follow some best practices to ensure that your messages are clear, concise, and informative. Here are some tips to help you write better commit messages:

Keep it concise and meaningful

A good commit message should be short and to the point, while still conveying the essence of the changes made. Ideally, your commit message should be no more than 50 characters long, and should summarize the changes made in a clear and meaningful way.

Example: Fix typo in README.md

Use imperative mood in the title

Your commit message title should be written in the imperative mood, which gives it a clear and direct tone. This is because the title is essentially a command that tells other developers what the commit does.

Example: Add new feature to dashboard

Use conventional commits

Conventional commits are a set of guidelines that help standardize commit messages across different projects. Following these guidelines can help make your commit messages more consistent and easier to read.

Example: feat: add new feature to dashboard

Provide context in the body

The body of your commit message should provide additional context about the changes made. This can include details about why the changes were made, how they were implemented, and any potential side effects.

Example:

Fix typo in README.md

The typo was causing confusion for new users, so I corrected it to improve readability.

Use the footer for metadata and related issues

The footer of your commit message can be used to provide metadata about the changes made, such as related issues or pull requests. This can help other developers understand the context of the changes and find related information more easily.

Example:

Add new feature to dashboard

Resolves #123

This feature adds a new widget to the dashboard that displays real-time data about user activity.

By following these best practices, you can write clear and concise commit messages that are meaningful and informative to other developers. This can improve collaboration and make it easier to maintain your codebase over time.

Tools and tips to improve Git commit messages

Git commit messages are an essential part of any development workflow. They provide a way for developers to communicate their changes to other members of the team, making it easier to understand what has been done and why. However, writing good Git commit messages can be challenging. Here are some tools and tips that can help:

Using Git hooks to enforce commit message format

Git hooks are scripts that are run automatically by Git at certain points in the commit process. You can use Git hooks to enforce a specific commit message format, so that all messages follow a consistent structure. This can be helpful in ensuring that your commit messages are informative and easy to read.

To set up a Git hook to enforce a commit message format, you can create a pre-commit hook that checks the message and rejects the commit if it doesn't meet the specified format. For example, you can enforce a message format that includes a short summary of the changes, followed by a more detailed explanation of the changes, like this:

[summary] Brief summary of changes

[details] Detailed explanation of changes, including any relevant context or background information.

To create a pre-commit hook that enforces this format, you can create a script in the .git/hooks directory called pre-commit and add the following code:

#!/bin/sh

commit_msg_file=$1

if ! grep -q "\[summary\]" "$commit_msg_file"; then
    echo "Commit message must include [summary] tag"
    exit 1
fi

if ! grep -q "\[details\]" "$commit_msg_file"; then
    echo "Commit message must include [details] tag"
    exit 1
fi

This script will check that the commit message includes both a [summary] and a [details] tag, and will reject the commit if either tag is missing.

Setting up a commit message template

Another way to ensure consistent commit messages is to set up a commit message template. This can be especially helpful if you have a large team working on the same codebase, as it ensures that everyone is following the same message format.

To set up a commit message template, you can create a file called .gitmessage in your home directory, and add the following content:

[summary]

[details]

Then, you can tell Git to use this file as a template for commit messages by running the following command:

git config --global commit.template ~/.gitmessage

Now, every time you run git commit, Git will open your text editor with the commit message template pre-filled, making it easy to write a consistent message.

Using tools like commitizen or git-cz to simplify commit message writing

Finally, you can use tools like commitizen or git-cz to simplify the process of writing commit messages. These tools provide a guided interface for writing commit messages, prompting you to include all the necessary information and formatting the message according to a specific template.

To use commitizen, you can install it globally using npm:

npm install -g commitizen

Then, you can run git cz instead of git commit to use the commitizen interface. Commitizen will prompt you to fill in information about the type of change (e.g. feature, bugfix, etc.), the affected files, and a brief summary of the changes.

Git-cz is a similar tool that you can install with the following command:

npm install -g git-cz

To use git-cz, you can run git cz instead of git commit, and it will guide you through the process of writing a commit message.

By using these tools and tips, you can simplify the process of writing Git commit messages and ensure that they provide the necessary context to your team.

Conclusion

Writing good Git commit messages is essential for software development as it improves collaboration and code maintenance. A well-crafted message provides context, clarity, and understanding of the changes made to the codebase, helping other developers understand the purpose and reasoning behind those changes. By following best practices such as keeping messages concise and meaningful, using the imperative mood, providing context in the body, and using the footer for metadata, you can write informative and effective Git commit messages that benefit your team and project.

Additionally, using tools like Git hooks to enforce commit message format, setting up a commit message template, and using tools like commitizen or git-cz can simplify message writing. Writing better Git commit messages can improve collaboration, code maintenance, and overall development efficiency. Remember, a good Git commit message can make all the difference, so start implementing these best practices today.

About the author

Paula Isabel Signo is a technical writer at OSSPH and a web developer. In her free time, Paula contributes to various open-source projects, volunteers in the community, and shares her knowledge by writing articles and tutorials. Connect with Paula here to learn more about her work and interests.