What is 'git interpret-trailers?' used for?

git is the de-facto standard for version control these days. As a software developer, you will be comfortable using common git-commands, like init, add, commit etc. However, there are some quite exotic git-commands out there. One of my favorite – that surprisingly few people seem to know about – is git bisect, which can be incredibly useful if you need to identify which commit introduced a breaking change. Especially, if there are a large number of commits that you need to go through.

Recently I stumbled upon an even more obscure git command: git interpret-trailers. At the time of writing, there are only 34 search results on stackoverflow for git interpret-trailers (as compared to 967 for git bisect).

So what does git interpret-trailers actually do?

From its man-page:

NAME
    git-interpret-trailers - Add or parse structured information in commit messages

SYNOPSIS
    git interpret-trailers [<options>] [(--trailer <token>[(=|:)<value>])…] [<file>…]
    git interpret-trailers [<options>] [--parse] [<file>…]
DESCRIPTION
    Help parsing or adding trailers lines, that look similar to RFC 822 e-mail headers, at the 
    end of the otherwise free-form part of a commit message.
    ...

But what is it good for?

Basically, this helps you deal with (somewhat) structured meta-data in commit-messages. For example, the git project’s “Signed-off-by:” is implemented this way. As noted in the github-blog, since version 2.33 git commit has a new --trailer flag, which can now be used instead of manually adding those trailers in commit-messages. Maybe trailers will gain more traction with this new flag?

For smaller projects, using trailers is probably overkill. But if you need to add machine-readable meta-data to your commit-messages, git interpret-trailers can be life-safer.

The conditional options for parsing trails are especially powerful. Here is the description for the option trailer.ifexists, which configures what action should taken if a trailer exists in the parsed text (from the man-page):

trailer.ifexists
This option makes it possible to choose what action will be performed when there is already at least one trailer with the same <token> in the message.

The valid values for this option are: addIfDifferentNeighbor (this is the default), addIfDifferent, add, replace or doNothing.

With addIfDifferentNeighbor, a new trailer will be added only if no trailer with the same (<token>, <value>) pair is above or below the line where the new trailer will be added.

With addIfDifferent, a new trailer will be added only if no trailer with the same (<token>, <value>) pair is already in the message.

With add, a new trailer will be added, even if some trailers with the same (<token>, <value>) pair are already in the message.

With replace, an existing trailer with the same <token> will be deleted and the new trailer will be added. The deleted trailer will be the closest one (with the same <token>) to the place where the new one will be added.

With doNothing, nothing will be done; that is no new trailer will be added if there is already one with the same <token> in the message.

This can come in pretty handy! If this sounds helpful to you, have a look at the examples the bottom of the git interpret-trailers man-page.

misc

But what is it good for?

If you liked this post, please, do share it:

See also