The most obvious is avoiding these kinds of commit messages which are unnecessarily unfriendly to read due to not being proper human friendly sentences:

Notice the examples above all deal with the same kind of commit message which could me more easily be distilled and reformatted to the following as previously discussed in my Git Commit Anatomy article:

Now we have a nicely formatted Git commit message with a project subject (i.e. what), body (i.e. why), and trailers (i.e. metadata) which yields the following benefits:

There is no specification on the kinds of trailers you can or can’t use because, by default, they only need to be key/value pairs at the bottom of your commit message. That said, I’ve been working to formalize this more to where I generally use all or some of the following:

The above can be broken down as follows:

The Git Interpret Trailers specification doesn’t have a hard limit what you can use for a trailer but the general rule of thumb is to format your trailers as follows:

Given the above, you could create the following commit with a subject, body, and trailer information:

Now you can use Git Interpret Trailers to inspect the trailers of any commit (be it saved or unsaved):

Taking this a step further, you can include trailers in your logs by using pretty formats. Here’s a simplified version of my Dotfiles gtail function which displays all commits made since the last tag in reverse order:

The format to pay attention to is: %(trailers:key=Milestone,valueonly=true,separator=). This formats my trailer as follows:

The result of the above looks like this:

Keep in mind that 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 program. Git Lint can aid in this endeavor by ensuring each commit message is consistently formatted and prevent garbage in, garbage out situations.

We’ve discussed what Git Commit Trailers are and why they are important so now I want to teach you how to make use of them in an automated fashion. This is where Git Branch Descriptions and Git Hooks come into play.

Git Branch Descriptions, if not familiar, are a nice way to provide additional information about the current branch you are working with and you can add descriptions as easily as running the following from the command line:

Assuming you saved the following message for your branch:

You’d then be able to view this information via the following command:

💡 Ensure you always provide a subject for your branch description or git interpret-trailers won’t be able to parse your trailers. In other words, you can’t have only trailers in your branch description you must have a subject, space, and trailers.

Next, you can automatically apply the above to each commit message by adding a prepare-commit-msg Git Hook which triggers after preparing the default commit message but before your editor is launched. As a quick start, you can copy and edit the sample Git Hook provided for you when creating a new repository (assuming you are currently in the root of your repository). Example:

💡 I use global Git Hooks so I don’t have to maintain duplicate copies of my Git Hooks across multiple repositories. That said, using your current repository for experimentation is a quick way to get started.

Now that you are editing your .git/hooks/prepare-commit-msg hook, you can copy and past the following implementation into it. Each line is documented so you can quickly grok the implementation:

You might be curious about the case statement. To elaborate, we can potentially have the following kinds of commits:

We only care about the first two. The template (kind) uses sd since sd is easier to use than sed or awk. I also want to be conscious of any custom Git commit templates (i.e. ~/.config/git/template, see my Git Configuration article for more info) so need the trailers to be added before the commit message comments begin. In other words, the end of the commit message.

When you combine the above together, you get a nice workflow. Example:

Now when you run git log on the above (depending on how you like to format your logs), you should something similar to the following output:

Trailers serve a slightly different purpose than what we used for commits. For instance, you wouldn’t want to use the same trailers for tags as used with commits because the context is entirely different. Instead, using trailers that provide statistical information is better for reporting purposes. What I’ve found to be most useful is the following:

Using Git Interpret Trailers, you can format your trailers by piping tag output to interpret trailers for parsing:

You can also list your tags with formatting as follows:

The above will produce output that looks like this:

Notice I use separator=| where the pipe character serves as a delimiter for all keys so the column command can format everything as a table of data. To spruce this up further, you can apply color to individual trailers but requires more syntax. Example:

The above will produce output as follows:

Notice I use the pipe character to delimit each trailer between the reseting and starting new colors. This is important for the column command to delimit and format properly. You also have to supply separator= with no value to prevent new line characters (default behavior) from showing up in your output. While tedious, there isn’t a way to avoid this behavior due to Git ensuring backwards compatibility with earlier versions.

The URI trailer is not shown in any of the above examples because the URI can sometimes be long and consume too much screen real-estate so only statistical information is displayed instead. Feel free to customize for your own purposes, though.

For more on all of this, check out the following: