Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Plumbing Commands

git interpret-trailers command

Reference for git interpret-trailers: add, replace and parse key-value trailers like Signed-off-by in commit messages, with --trailer, --where and --parse.

A trailer is a Key: value line in the last paragraph of a commit message, such as Signed-off-by: Ada <[email protected]> or Co-authored-by: .... git interpret-trailers reads a message, then adds, edits or extracts trailers according to your options. It treats the message as plain text, so it also works on any file that follows the same layout.

It is the tool behind git commit --trailer, and it is the right way to script trailers in hooks, release tools and review workflows without breaking the message format with careless echo calls.

Terminal
git interpret-trailers --trailer "Reviewed-by: Ada <[email protected]>" < message.txt
git interpret-trailers --parse < message.txt

Try it

Bash Add trailers to a message

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Parse, replace and position trailers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git interpret-trailers [<options>] [(--trailer <key>[(=|:)<value>])...] [--parse] [<file>...]
Name Description
<file> Message file(s) to read. With none, standard input is used.
--trailer <key>[:=]<value> Add this trailer. Repeat for several. The separator can be : or =.
--where <placement> Where to put new trailers: after (default, after similar trailers), before, end, or start.
--if-exists <action> When a trailer with the same key exists: addIfDifferentNeighbor (default), addIfDifferent, add, replace, or doNothing.
--if-missing <action> When no trailer with that key exists: add (default) or doNothing.
--parse Shorthand for --only-trailers --only-input --unfold: just print the trailers already in the message.
--only-trailers Print only the trailer block, not the rest of the message.
--only-input Do not add or process trailers from configuration or --trailer; print what was in the input.
--unfold Join continuation lines of long trailer values into one line.
--in-place Edit the file instead of printing.
--trim-empty Drop trailers whose value is empty.
--no-divider Treat a --- line as ordinary text rather than the end of the commit message.

Output: the message with the trailer block updated, written to standard output (or in place). If the message has no trailer block, a blank line and a new block are appended.

Edge cases: a "trailer block" needs at least 25% of its lines to be Key: value lines (or to contain a Git-style trailer such as Signed-off-by), otherwise Git starts a new block.

Usage notes

  • Keys can be abbreviated through configuration. Set trailer.<token>.key, .command, .ifexists and .ifmissing to define defaults, for example a sign token that expands to Signed-off-by.
  • Duplicates. With the default addIfDifferentNeighbor, a repeated trailer is added unless the same line sits directly next to the insertion point. Use --if-exists replace for keys that should occur once, such as Ticket.
  • Where trailers go. --where after puts a new trailer after the last trailer with the same key, grouping reviews together; end always appends.
  • git commit --trailer and git format-patch --signoff use the same machinery; git log --format='%(trailers:key=Fixes,valueonly)' reads trailers in log output.
  • Cherry-pick. git cherry-pick -x adds a (cherry picked from commit ...) line that is not a trailer; keep that in mind when parsing.
  • Do not hand-edit with echo >>. A trailing newline or a missing blank line separating body and trailers makes Git misread the block.
  • --- lines. In patch emails, a --- marks the start of the diffstat. By default the command stops there; use --no-divider if your text legitimately contains that line.