By default, you can leverage the --trailer option as first introduced in Git 2.32.0 when creating commit messages. Example:

When you run the above, you’ll end up with the following output (depending on how you like to format git show):

Notice the Milestone trailer is added at the bottom of the commit message. This where all trailers (metadata) exists which provides a rich source of information for post-processing tools like Milestoner (more on this shortly). Even better, you can add multiple trailers at once. Example:

Once again, notice we have the following trailer information at the bottom of the commit message:

In this case, we know this commit is a patch for the abc issue as found within the Tana issue tracker. That’s a lot of useful information we can use later without degrading the readability of our commit messages. 🚀

Now that you have a taste of what Git Trailers are, let’s talk about why trailers are important. 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):

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 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:

Assuming you’ve enjoyed learning about Git Trailers and would like to put them to use in your own projects, I highly recommend the following tooling to aid in this endeavor (you can pilfer from my Dotfiles project as well):

While the above tools are architected by me, and apologies for the self promotion, I’ve been using these tools on all of my projects for years to great effect. If you’ll indulge me a bit longer — and using Milestoner — you can build nice release notes for the above. Example (i.e. milestoner build --format web):

All of this is made possible due to having tooling that can read and parse your Git Trailers so your commit messages remain enjoyable to read for faster collaboration with your colleagues. Not bad for an automated workflow! 🚀

I hope you’ve enjoyed learning about Git Trailers, what they are, why they are important, and how to leverage them so you can immediately apply them to your own workflow. Writing high quality software doesn’t have to be tedious nor does collaboration have to be grueling. With a little ingenuity and tooling, you can make your engineering workflows a breeze. Enjoy!