On Detailed Commit Messages

Xander Griff, Sat Dec 10 2022 • git communication teams

The usefulness of a good commit

In the world of software development, git is far and away the most widely used version tracking software. Git is primarily a tool for collaboration, allowing its users to share code and consolidate codebase history with relative ease. If you’re looking to improve your understanding of git, I’d recommend checking out this lecture from MIT’s The Missing Semester of Your CS Education. For the sake of this post though, you’ll need only know that the fundamental unit of history in git is the commit. You can consider it to be a snapshot in time for your code. Alongside all the autogenerated metadata that git uses to collate the vast history of your code, git allows us a single portal to include our own information: a commit message.

Commit messages are a great opportunity to leave a trace of context for our collaborators and future-selves. They’re essential for communicating the purpose and intent of code changes to other members of in a team. When working on a large codebase with multiple developers, it can be difficult to keep track of all of the changes being made. By writing descriptive commit messages, you can make it easier for other developers to understand what your code is doing and why.

In addition to being useful for communication, well-written git commit messages can help you and your team to better understand the history of your codebase. By looking back at the commit messages for previous changes, you can quickly see what changes were made and why, which can be helpful for debugging and refactoring.

Furthermore, good git commit messages can also serve as a form of documentation for your code. By writing clear and concise messages that describe the changes made in each commit, you can create a written record of the evolution of your codebase that can be useful for future reference.

Which makes it all the more frustrating when, during a debug session or when trying to dig into a murky chunk of legacy code, you run into commit messages like the following:

“Fix bug”
“Update”
“Code changes”
“Does it work now??”

The structure of a commit message

A relevant xkcd comic indicates that this is perhaps a universal experience. But hold on. What does a good commit really look like?

While there’s no strict rule for the structure of a good git commit message, I’ve got some some general guidelines that I use to write fully contextualized commit messages. The structure is as follows:

Start with a brief, one-line summary of the changes made in the commit. This should be no more than 50-70 characters in length (so that it doesn’t get cut-off in Github commit summaries), and should provide a high-level overview of the changes that were made.
Add a blank line after the summary, and then provide a more detailed description of the changes made in the commit. This should be a paragraph or two in length, and should provide specific information about what was changed and why.
If necessary, add additional information or context to the commit message. This could include links to related issues, mention of other related commits, or any other relevant details.

Here is an example of a well-structured, briefly-written git commit message:

Fix bug in login form where password was not being validated

Previously, the login form was not properly validating the user's password,
which could allow unauthorized access to the system. This commit fixes the
bug by adding the missing password validation code.

Fixes #123

This is a relatively lightweight system for improving commit messages. For a more detailed system, check out Conventional Changelog, which outlines a proposed specification for wringing the most out of your commit messages. For a emoji-themed system, check out Gitmoji.

Tools for making your commits better

Call me an optimist, but I’d hazard a guess that most developers aren’t actively trying to write commit messages without detail. It’s gotta be acknowledged that it’s actively difficult to write them. Given that it takes time and effort, I’d be remiss not to suggest a few solutions that’ll help make writing good commit messages easier:

Use a commit message template: Many Git tools, such as Git itself and popular code hosting platforms like GitHub and GitLab, allow you to specify a commit message template that will be used when creating new commits. This is a relatively lightweight solution that, while not perscriptive, can give you and your team an outline for easily improving commit messages.
Use a linter: A linter is a tool that checks your code for formatting and style errors. Many linters, such as commitlint and commitcheck, can be configured to check the formatting and style of your commit messages, and to report any issues or violations. This can help to ensure that your commit messages are well-formatted and easy to read.
Use a commit message generator: Some tools, like Commitizen, can help you to generate well-structured and descriptive commit messages automatically. These tools can prompt you for information about the changes that were made, and can use that information to generate a particularly formatted and fully fleshed-out commit message.

By using templates, linters, and commit message generators, you can ensure that your commit messages are consistent, well-formatted, and descriptive.

Concluding Thoughts

Writing detailed git commit messages is a practice that, althought sometimes difficult to formulate, can pay dividends. Not only do well-written commit messages make it easier for others to understand the changes you've made to the codebase, but they also serve as a useful reference for yourself and your team.

By following a simple structure (and perhaps using tools like gitmoji and commitlint), you can make it even easier to improve the quality of your commit messages and take your code collaboration to the next level. So let's all commit (sorry) to writing clear, concise, and descriptive git commit messages from now on!