Git commit message conventions and best practices
How to write a git commit message properly is a topic that's been broached many times.
Any seasoned developer who's rifled through Git logs in a project they've just been parachuted into knows that programmers need constant reminders about git commit message guidelines and best practices.
Git commit message best practices
The seven commonly accepted git commit message best practices are as follows:
- Limit the subject line to 50 characters.
- Capitalize only the first letter in the subject line.
- Don't put a period at the end of the subject line.
- Insert a blank line between the subject line and the body.
- Wrap the body at 72 characters.
- Use the imperative mood.
- Describe what was done and why, but not how.
The 50-character title limit
There are two reasons you should limit the git subject line to 50 characters.
First of all, when others sift through your sea of commits, they can quickly scan a 50-character title to determine the purpose of the commit.
Secondly, this practice forces the developer to really think about the work they just performed and to succinctly describe it.
If a developer can't describe the purpose of the commit in 50 characters or less, it's a good indication that they aren't committing enough, they put far too much into a single commit or they don't really have a good idea of the problem they tried to solve or the feature they wanted to create.
If you develop incrementally and commit often, it shouldn't be a problem to describe a commit in 50 characters or less.
Controlled capitalization
In terms of format, capitalize the first letter of the subject line but don't force unnecessary capitalization anywhere else. Other developers might use case-sensitive tools to search for a given entry in the commit log, and you don't want to complicate the process and cause a failed search because you used The instead of the somewhere in the prose.
Watch your grammar and typesetting
Think of your subject line like a newspaper headline. Neither a git subject line nor a newspaper headline should end with a period.
The optional body of a git commit may contain periods. In fact, a body paragraph in your commit should follow all the standard rules of well-formed grammar and typesetting.
Always insert an empty line between the subject line and the body. This space allows for various git tools to effectively format commit histories. When asked for a concise git history, many tools print out just the first line of each commit. Keep this separate from the body and you'll make the git commit history easier to work with.
Adhere to the 72-character limit
Another rule about how to write a git commit message properly is to limit the body width to 72 characters. Now, this doesn't mean you must set your text editor to word wrap at 72. This git commit message guideline means you must concertedly add a carriage return when the body of your commit message approaches 72 characters.
This is another rule driven primarily by the tool set many Git developers use. If you look at a git commit history on GitHub, the 72-character line limit doesn't matter because the GitHub UI performs line wrapping for you. However, many software developers use other tools that don't perform this function. If you don't add your own carriage returns, fellow developers that use Emacs or Vi will be forced to scroll right four or five times to read the git commit content.
Write git commit messages imperatively
If you want to write a git commit message according to the commonly accepted guidelines, use the imperative mood. This means you must resist the temptation to use gerunds or past tense in your subject lines.
Don't write a git commit subject line that talks about what you did, or what you are doing. Instead, describe what was done.
- Fixed the fencepost error. //bad
- Fixing the fencepost error. //bad
- Fix the fencepost error. //good
The imperative mood is the one git commit message guideline that developers tend to violate most often.
Describe what was done and why, but not how
To help write imperatively, here's a good rule of thumb. Imagine appending the git commit message to the following statement: If applied, this commit will __. The resulting sentence should make grammatical sense. As you can see from the following three examples, gerunds and past tense commits fail the test, while the imperative tense does not:
- If applied, this commit will fixed the fencepost error.
- If applied, this commit will fixing the fencepost error.
- If applied, this commit will fix the fencepost error.
There is a degree of ethnocentricity built into this rule. It works well for those who speak English, but it doesn't necessarily translate to other languages. Furthermore, there are certainly corner cases where a nonsensical commit message might actually work grammatically in this scenario. Generally speaking, though, it's a good test to help developers avoid mistakes when they craft their git commit subject lines.
The git commit body
Not every git commit requires a body. Sometimes a descriptive subject line is sufficient, but if you want more detail you can add a body.
The goal of a commit message is to concisely explain what and why, so that other developers on the team can quickly go through the git log and figure out the purpose of a particular commit. There is no need to go into extra details pertaining to how a given problem was fixed, or what was done to implement a new feature. If those details are needed, a developer can simply perform a diff on the code and look at the actual code changes.
However, a commit message footer is the appropriate place to add Jira ticket references or other commits that are pertinent to the current commit. These pieces of information are often useful, but they tend to read awkwardly in the subject line.
At the same time, don't get lazy and simply quote a Jira ticket instead of providing a good git commit message. If you say, "Go look at Jira ticket 8154," this doesn't provide immediate context for someone going through the Git log.
AngularJS git commit message conventions
For a good case study, I always suggest the conventions AngularJS applies to commit messages. They buck the trend of starting the title with an uppercase letter, and instead insist that each commit start with one of the following seven words:
- chore
- docs
- style
- feat
- fix
- refactor
- test
With this set of commit types, it's easy for developers who inspect codebase changes to skip over trivial commits that update documentation or simply format a piece of code, and instead focus on commits that affect the codebase.
Along with these seven words, AngularJS git commit messages also try to specify the component that changed. Again, this makes it easier for developers to focus on repository changes that affect the component on which they are working.
When you look at the commit history of the AngularJS project on GitHub, you quickly realize how a meaningful and consistent convention for git commit messages can make it much easier to maintain a large project with many contributors.
Cameron McKenzie has been a Java EE software engineer for 20 years. His current specialties include Agile development; DevOps; Spring; and container-based technologies such as Docker, Swarm and Kubernetes.