git interpret-trailers

The Co-authored-by:/Signed-off-by: handler.

🎯 What & why

Reads or injects structured trailers (the Key: value lines at the bottom of commit messages, like Signed-off-by: or Co-authored-by:). The canonical tool for scripting trailer policy.

🧠 Mental model

A commit message is subject\n\nbody\n\ntrailers. interpret-trailers is a parser/editor for that last block and nothing else - it never touches subject or body.

🛠️ Synopsis

git interpret-trailers [<options>] [--parse] [<file>...]

# Add trailers (reads message from stdin, writes to stdout):
git interpret-trailers --trailer "Signed-off-by: A <a@x>" < msg.txt

# Edit a file in place:
git interpret-trailers --in-place --trailer "Acked-by: B <b@y>" msg.txt

# Just list existing trailers:
git interpret-trailers --parse < msg.txt
git log -1 --format=%B | git interpret-trailers --only-trailers --parse

🎚️ Switches & options

Flag	What it does
`--trailer <key>=<value>`	Trailer to add (also accepts `Key: value` form)
`--in-place`	Rewrite the input file instead of writing to stdout
`--if-exists=<action>`	addIfDifferent \| addIfDifferentNeighbor \| add \| replace \| doNothing
`--if-missing=<action>`	add \| doNothing
`--no-divider`	Don't treat `---` as the end of the message (for `git am`-style input)
`--parse`	Equivalent to `--only-trailers --only-input --unfold`
`--only-trailers`	Output only the trailer block, not the rest of the message

💡 Use cases

A prepare-commit-msg hook that auto-appends Signed-off-by: for the current user.
CI script that asserts every commit has a Reviewed-by: trailer.
Bulk rewrite messages during a git filter-repo to add a Change-Id:.
Extract trailers from git log output for changelog generation.

🧪 Examples

Add a sign-off

git interpret-trailers --trailer "Signed-off-by: $(git config user.name) <$(git config user.email)>" --in-place msg.txt

Add only if missing

git interpret-trailers --if-exists=doNothing --trailer 'Co-authored-by: X <x@y>' --in-place msg.txt

List trailers of HEAD

git log -1 --format=%B | git interpret-trailers --parse

Replace existing trailer

git interpret-trailers --if-exists=replace --trailer 'Reviewed-by: New <n@x>' --in-place msg.txt

🎓 Recommendations

Configure trailer.<token>.key, .ifExists, .ifMissing in git config to set per-trailer defaults instead of repeating flags.
Use it in commit-msg hooks for policy, not in prepare-commit-msg if you want users to see/edit the trailer.
Pair --parse --only-trailers for clean machine-readable output.

🪤 Common pitfalls

Trailers must be in a contiguous block at the end - a stray blank line or non-trailer line breaks parsing.
--trailer key=value and --trailer 'key: value' both work, but = is friendlier in shell scripts.
Default --if-exists is addIfDifferentNeighbor, which can produce duplicate trailers separated by other trailers.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.