Tally All Git Trailers in a Repository

I’ve been using a lot of Git Trailers in my commit messages recently and as my thinking on which trailer keys to use has evolved, it’s been useful to look back at which ones have been used before.

git log’s --format flag can provide all sorts of useful information, including trailers. Let’s take a look:

❯ git log --format="%(trailers:keyonly)" |
  grep '\w\+' |
  grep -v https |
  sort |
  uniq -c |
  sort

We start by asking Git to give us the full log with the format of only the trailer keys. That gets passed to a (naïve, but good enough) grep '\w\+ to remove empty lines, then again through grep -v https to remove lines with “trailers” which are just links¹. Finally we tally up the results with sort | uniq -c | sort which is one of my toolbox commands to get tallies of distinct lines sorted by count ascending (so that the most common trailers are nearest the prompt).

That’s helped me remember that Issue is the key I like for linking to the related issue tracker, and not Fixes or Closes which will close related issues in GitHub or Gitlab when they’re merged in (not always what I want).

Some other favorites are:

• Co-authored-by for pairs, Reviewed-by (occasionally) for reviewers
• Documented-at, Documented-by, or Reference for linking to library or product docs
• Related-Issue for linking to issues that this commit doesn’t directly address
• Follow-up for linking to an issue that I’m splitting off from this body of work
• Feature, Fix, and Change for end-user-facing changelog entries, which I’ll script something up for to add to tags and release notes.
• I’m experimenting with Conventional and Breaking-Change for Conventional Commits information.²

While Git trailers haven’t been widely adopted, there are a few others shouting into the void as it were about how they could be useful:

• Brooke Kuhlmann at Alchemists has some proposals on useful trailers for tags and commits
• Horst Gutmann uses git interpret-trailers to expand trailers with JIRA’s project references to URLs
• Git itself suggests several trailers, mostly around attributing folks who helped, reviewed, paired, etc. on the commit.
• It also treats the Signed-off-by trailer specially with a -s, --signoff flag to git commit and several related commands.
• GitHub attribute authorship to accounts matching email addresses when using Co-authored-by (as does GitLab)
• They also allow authoring commits On-behalf-of orgs
• And skipping workflow runs with Skip-checks
• GitLab use the Changelog trailer in a similar way to how I’m using Feature, Fix, and Change to generate CHANGELOGs
• They also provide a few trailer placeholders in their commit templates.

I’d love to hear what trailers you’re using, and why! And I feel like it may be time to revisit my commit messages article with a more experienced eye. Would that be interesting to you?