7 Git Commit Message Best Practices
When writing a git commit message, it's important to follow best practices so that your messages are clear and concise. Here are 7 of the best practices to follow.
A well-crafted git commit message is the best way to communicate context about a change to your codebase. In this article, we will discuss 7 best practices for writing git commit messages.
1. Separate subject from body with a blank line
The subject line should be used to describe the high-level change being made, while the body can be used for a more detailed description. By separating the two with a blank line, it’s easier to see at a glance what the commit is about.
It’s also important to keep the subject line under 50 characters, so that it can be easily read in most git tools. If you need to go over 50 characters, that’s fine, but anything over 72 characters should be wrapped to the next line.
2. Limit the subject line to 50 characters
The subject line is the first thing people see when they view your commit, and it should be able to stand on its own as a brief summary of what the commit contains. If the subject line is too long, it will be truncated when viewed in tools like GitHub, making it difficult to understand what the commit is about at a glance.
By keeping the subject line short and sweet, you can ensure that your commit messages are easy to read and understand, which will make it easier for people to review and merge your changes.
3. Capitalize the subject line
When git generates a log of commits, it uses the subject line to generate a summary of each commit. If the subject line is not capitalized, the summary will be difficult to read. For example, consider the following two commit messages:
Subject: Add new feature
Subject: add new feature
The first message is much easier to read than the second. Therefore, it’s important to always capitalize the subject line of your git commit messages.
4. Do not end the subject line with a period
When the subject line of a git commit message is ended with a period, it can often be interpreted as an abbreviation. For example, “Fixed bug.” would be interpreted as “Fixed bug with no further explanation.” This can often lead to confusion for other developers who are trying to understand what was changed in that particular commit.
It’s much better to write git commit messages like this:
“Fixed bug where X was not happening.”
This makes it clear that the bug has been fixed and provides some context about the issue that was being faced.
5. Use the imperative mood in the subject line
When you’re writing a git commit message, you’re essentially writing a command that tells the code to do something. For example, “fix bug” or “add feature.”
Using the imperative mood in your subject line makes it clear that you’re giving a command, which helps keep your messages consistent and easy to understand.
6. Wrap the body at 72 characters
When git generates a patch, it uses the first line of the commit message as the subject and the rest of the message as the body. The generated email will have a limited width, so if the body isn’t wrapped, it will be very difficult to read.
By wrapping the body at 72 characters, you ensure that the generated email will be easy to read. This is especially important when multiple people are working on the same codebase, as they need to be able to quickly understand each other’s commits.
It’s also worth noting that some git clients will wrap the body for you automatically. However, it’s still good practice to wrap it manually, as this ensures that the generated email will be readable even if the client doesn’t wrap it correctly.
7. Use the body to explain what and why vs. how
When reading a commit message, I want to know two things: what changed and why. The body of the commit message should explain those two things. The subject line should be a short summary (50 characters is a good rule of thumb) that tells me what changed. The body should tell me why this change was made.
The reason for this is simple: the what and the why are more important than the how. The how can be easily gleaned from the diff; what’s more important is understanding the motivation behind a change.
Of course, there are exceptions to every rule. If the how is particularly interesting or complex, it may be worth including in the commit message. But in general, keep the focus on the what and the why.