While often ignored, the author of a commit is as vital as the subject and body. After all, the name reveals who committed the changes so we know who to speak to for support if we want to talk about architecture/implementation or get clarity on changes in general. Ideally, a commit’s documentation should provide all of the context necessary so no one has to track down the original author in the first place — assuming the engineer is still part of the team/company! Sometimes this documentation will be the only explanation you ever get.

In the screenshot above, we see my full name, both first and last. At a bare minimum, every author in your repository should have a first and last name with proper capitalization and punctuation. Seriously, in future years, you might not want to be known as the witty or silly handle with which you committed code.

In addition to your full name, a proper email address should be used as well. Although, not shown in the screenshot above, the email address should consist of the author’s handle and company domain. Example:

Lastly, an avatar should be associated with the email address via a service like Gravatar or uploaded and associated with the account through whatever service is used to host the Git repository. For several reasons, the avatar should be an accurate representation who the person is in real life. Sketches, cartoons, abstract art, etc. hinder engineers from identifying the individual when seeking help or wanting to collaborate on work. Real pictures make the commits more authentic too.

Git Lint can aid in this endeavor by enforcing all authors use full names and email addresses. See the various author and email linters for further details.

Returning to our example, the subject of the above commit is:

What makes this a great subject is the proper use of the Added prefix, used in the past tense. Past tense is important because, once you’ve committed code, the changes are made and therefore already in the past. Plus, our Git history is a view of the past so the tense is right here in the name! The same applies when using commands such as git log, git show, git blame, etc. After years of writing Git commits, I’ve found there are only five prefixes you ever need to use:

For more details, check out the Git Lint Commit Subject Prefix style guide.

Using only these five prefix provides additional value when assembling project changes and/or release notes when you group and alphabetically sort them for distribution. Even better, tools like Milestoner can further automate the process so you have less work to do when communicating changes to your engineering team, stakeholders, and/or customers.

In addition to the commit prefix, the rest of our example’s subject is clear in that we know cache inspection support was added. A Git commit subject is always meant to tell us what is being committed to the code base and nothing more. Sometimes you might see people add story IDs or other forms of identification but the subject is not the place for this information. Metadata, like that, should always go in the body of the commit message via trailers, which we’ll discuss shortly.

Almost every commit should have a body to explain why the commit was made. The purpose of the body is to always support the subject and explain why the commit is necessary. Here’s only the commit message body from the screenshot above:

There are several important qualities worth pointing out here:

By the way, all of the above and more is automatically checked for you when using Git Lint. For more on this, read through the Git Lint documentation related to Commit Bodies as there are several checks for ensuring your bodies are of high quality.

As mentioned in the Git Lint Style Guide, all commits should be atomic, which means each commit should be the smallest and most concise unit of work possible. As a general rule of thumb, this means only the implementation and test:

Regardless of the above being a Ruby implementation, the concept being applied is that we have both the implementation (label.rb) and test (label_spec.rb) which comprises this Git commit. When reviewing this code or looking at the history of changes to these files we’ll always have the implementation and test bound together so we can understand what the code is and why the code was added.

Atomic commits improve your workflow too, especially a Git Rebase Workflow. I find detailed commits easier to fix, squash, edit, drop, cherry pick, etc. while working on a feature branch during the course of development. Large, messy, commits are never as easy to work with due to being inherently harder to untangle and manage. Stay small because you’ll be happier, agile, and more flexible. I promise.

Git Trailers are where all metadata associated with a commit goes:

If you’ve never used trailers before, here’s a quick breakdown of the above:

Trailers always go at the end of a commit message, after the body per Git specification, and should never be used in the subject or body. Doing so ensures a commit message remains readable by fellow engineers and keeps the metadata in a format that is useful for post-processing by a computer. Git Lint can aid in this endeavor as well.