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.

This command reads some patches or commit messages from either the <file> arguments or the standard input if no <file> is specified. If --parse is specified, the output consists of the parsed trailers.

Otherwise, this command applies the arguments passed using the --trailer option, if any, to the commit message part of each input file. The result is emitted on the standard output.

Some configuration variables control the way the --trailer arguments are applied to each commit message and the way any existing trailer in the commit message is changed. They also make it possible to automatically add some trailers.

By default, a <token>=<value> or <token>:<value> argument given using --trailer will be appended after the existing trailers only if the last trailer has a different (<token>, <value>) pair (or if there is no existing trailer). The <token> and <value> parts will be trimmed to remove starting and trailing whitespace, and the resulting trimmed <token> and <value> will appear in the message like this:

token: value

This means that the trimmed <token> and <value> will be separated by ': ' (one colon followed by one space).

By default the new trailer will appear at the end of all the existing trailers. If there is no existing trailer, the new trailer will appear after the commit message part of the output, and, if there is no line with only spaces at the end of the commit message part, one blank line will be added before the new trailer.

Existing trailers are extracted from the input message by looking for a group of one or more lines that (i) is all trailers, or (ii) contains at least one Git-generated or user-configured trailer and consists of at least 25% trailers. The group must be preceded by one or more empty (or whitespace-only) lines. The group must either be at the end of the message or be the last non-whitespace lines before a line that starts with --- (followed by a space or the end of the line). Such three minus signs start the patch part of the message. See also --no-divider below.

When reading trailers, there can be whitespaces after the token, the separator and the value. There can also be whitespaces inside the token and the value. The value may be split over multiple lines with each subsequent line starting with whitespace, like the "folding" in RFC 822.

Note that trailers do not follow and are not intended to follow many rules for RFC 822 headers. For example they do not follow the encoding rules and probably many other rules.

OPTIONS

--in-place

--trim-empty

--trailer <token>[(=|:)<value>]

--where <placement>, --no-where

--if-exists <action>, --no-if-exists

--if-missing <action>, --no-if-missing

--only-trailers

--only-input

--unfold

--parse

--no-divider

CONFIGURATION VARIABLES

trailer.separators

trailer.where

trailer.ifexists

trailer.ifmissing

trailer.<token>.key

trailer.<token>.where

trailer.<token>.ifexists

trailer.<token>.ifmissing

trailer.<token>.command

EXAMPLES

$ git config trailer.sign.key "Signed-off-by"
$ cat msg.txt
subject
message
$ cat msg.txt | git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>'
subject
message
Signed-off-by: Alice <alice@example.com>
Signed-off-by: Bob <bob@example.com>

$ cat msg.txt
subject
message
Signed-off-by: Bob <bob@example.com>
$ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt
$ cat msg.txt
subject
message
Signed-off-by: Bob <bob@example.com>
Acked-by: Alice <alice@example.com>

$ git format-patch -1
0001-foo.patch
$ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Reviewed-by: Bob <bob@example.com>' 0001-foo.patch >0001-bar.patch

$ git config trailer.sign.key "Signed-off-by: "
$ git config trailer.sign.ifmissing add
$ git config trailer.sign.ifexists doNothing
$ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
$ git interpret-trailers <<EOF
> EOF
Signed-off-by: Bob <bob@example.com>
$ git interpret-trailers <<EOF
> Signed-off-by: Alice <alice@example.com>
> EOF
Signed-off-by: Alice <alice@example.com>

$ git config trailer.separators ":#"
$ git config trailer.fix.key "Fix #"
$ echo "subject" | git interpret-trailers --trailer fix=42
subject
Fix #42

$ git config trailer.see.key "See-also: "
$ git config trailer.see.ifExists "replace"
$ git config trailer.see.ifMissing "doNothing"
$ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG"
$ git interpret-trailers <<EOF
> subject
>
> message
>
> see: HEAD~2
> EOF
subject
message
See-also: fe3187489d69c4 (subject of related commit)

$ sed -e 's/ Z$/ /' >commit_template.txt <<EOF
> ***subject***
>
> ***message***
>
> Fixes: Z
> Cc: Z
> Reviewed-by: Z
> Signed-off-by: Z
> EOF
$ git config commit.template commit_template.txt
$ cat >.git/hooks/commit-msg <<EOF
> #!/bin/sh
> git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new"
> mv "\$1.new" "\$1"
> EOF
$ chmod +x .git/hooks/commit-msg

SEE ALSO

git-commit(1), git-format-patch(1), git-config(1)

GIT

Part of the git(1) suite