While looking through the ConventionalCommit spec I stumbled upon a feature of Git I somehow always thought was there but hadn’t realize was actually part of the Git toolchain itself: Trailers!
In Git, trailers are key-value pairs written inside of commit messages that, for instance, make things like references to JIRA tickets programmatically accessible. Let’s take a look at the following commit message:
Awesome new feature Some details about this commit JIRA-Ref: PROJ-123
The last line is an example for a trailer. It consists of a token (
JIRA-Ref), a separator (
:), and a value (
interpret-trailers the Git command offers a subcommand for extracting and manipulating these trailers. Using various configuration options, (among others) the following operations can be performed:
- Add a trailer if it is not present (using a shell command)
- Remove a trailer if present
- Modify a trailer if present (using a shell command)
A call to
git inspect-trailers could, for instance, be integrated into a commit-msg hook script in order to do some modifications or using pre-commit to prevent commit messages not including, for instance, certain trailers or explicitly adding trailers with information from the context of a commit.
In general, you’ll probably most often need to implement a bit of scripting around trailers, the git subcommand just makes it a bit easier so that you don’t have to extract the trailers yourself:
$ git config trailer.jiraref.key "JIRA-Ref" $ git config trailer.jiraref.ifexists replace $ git config trailer.jiraref.command "echo https://jira.company.com/secure/\$ARG"
Let’s now take the same commit message that we create above and interpret it.
git inspect-trailers will then replace the JIRA-Ref line like this:
$ cat message.txt | git interpret-trailers Awesome new feature Some details about this commit. JIRA-Ref: https://jira.company.com/secure/PROJ-123
You can also use inspect-trailers to get just the token/value pairs:
$ cat message.txt | git interpret-trailers --only-trailers JIRA-Ref: https://jira.company.com/secure/PROJ-123
I haven’t yet tried to script my way around trailers but I’d assume I’d do something like this if I need more complex logic for updating the trailers:
- Extract just the trailers using the
- Massage the values into the for that I want
- Modify the commit message by passing the new trailers using something like
cat message.txt | git interpret-trailers --trailer JIRA-Ref=my-new-ref
In such a scenario, I’d probably also remove the
trailer.jiraref.command option that we set before simply to have all the processing logic inside (2) and not being split between that and the git configuration.
Coming to think of it, trailers might be a nice way to include a list of all the reviewers that checked a pull-request/merge-request before it was merged! Implementing that as some kind of hook/action for GitLab or GitHub might also be a nice coding dojo project 😄
Do you want to give me feedback about this article in private? Please send it to email@example.com.
Alternatively, this website also supports Webmentions. If you write a post on a blog that supports this technique, I should get notified about your link 🙂