NAME¶

git-interpret-trailers - Add or parse metadata in commit messages

SYNOPSIS¶

git interpret-trailers [--in-place] [--trim-empty]
			[(--trailer (<key>|<key-alias>)[(=|:)<value>])...]
			[--parse] [<file>...]

DESCRIPTION¶

Add or parse trailer metadata at the end of the otherwise free-form part of a commit message, or any other kind of text.

A trailer in its simplest form is a key-value pair with a colon as a separator. The key consists of ASCII alphanumeric characters and hyphens (-). A trailer block consists of one or more trailers. The trailer block needs to be preceded by a blank line, where a blank line is either an empty or a whitespace-only line. For example, in the following commit message

subject
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Signed-off-by: Alice <alice@example.com>
Signed-off-by: Bob <bob@example.com>

the last two lines starting with Signed-off-by are trailers.

This command reads 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 coming from the input, without influencing them with any command line options or configuration variables.

Otherwise, this command applies trailer.<key-alias> configuration variables (which could potentially add new trailers, as well as reposition them), as well as any command line arguments that can override configuration variables (such as --trailer=... which could also add new trailers), to each input file. The result is emitted on the standard output.

This command can also operate on the output of git-format-patch(1), which is more elaborate than a plain commit message. Namely, such output includes a commit message (as above), a --- divider line, and a patch part. For these inputs, the divider and patch parts are not modified by this command and are emitted as is on the output, unless --no-divider is specified.

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

Let’s consider new trailers added with --trailer. By default, the new trailer will appear at the end of the trailer block. Also by default, this new trailer will only be added if the last trailer is different to it. A trailer block will be created with only that trailer if a trailer block does not already exist. Recall that a trailer block needs to be preceded by a blank line, so a blank line will be inserted before the new trailer block in that case.

This is how the new trailer is added: a <key>=<value> or <key>:<value> argument given using --trailer will be appended after the existing trailers. The <key> and <value> parts will be trimmed to remove starting and trailing whitespace, and the resulting trimmed <key> and <value> will appear in the output like this:

key: value

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

Existing trailers are extracted from the input by looking for the trailer block. A trailer block is 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 trailer block is by definition at the end of the commit message. The message in turn is either (i) at the end of the input, or (ii) the last non-whitespace lines before a line that starts with --- (followed by a space or the end of the line).

For convenience, a <key-alias> can be configured to make using --trailer shorter to type on the command line. This can be configured using the trailer.<key-alias>.key configuration variable. The <key-alias> must be a prefix of the full <key> string, although case sensitivity does not matter. For example, if you have

trailer.sign.key "Signed-off-by: "

in your configuration, you only need to specify --trailer="sign: foo" on the command line instead of --trailer="Signed-off-by: foo".

When reading trailers, there can be no whitespace before or inside the <key>, but any number of regular space and tab characters are allowed between the <key> and the separator. There can be whitespaces before, inside or after the <value>. The <value> may be split over multiple lines with each subsequent line starting with at least one whitespace, like the "folding" in RFC 822. Example:

key: This is a very long value, with spaces and


  newlines in it.

OTHER RULES¶

What was covered in the previous section are the rules that are relevant for regular use. The following points are included for completeness.

OPTIONS¶

--in-place, --no-in-place

--trim-empty, --no-trim-empty

--trailer=<key>[(=|:)<value>], --no-trailer

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

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

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

--only-trailers, --no-only-trailers

--only-input, --no-only-input

--unfold, --no-unfold

--parse

--divider, --no-divider

CONFIGURATION VARIABLES¶

Everything below this line in this section is selectively included from the git-config(1) documentation. The content is the same as what’s found there:

trailer.separators

trailer.where

trailer.ifexists

trailer.ifmissing

trailer.<key-alias>.key

trailer.<key-alias>.where

trailer.<key-alias>.ifexists

trailer.<key-alias>.ifmissing

trailer.<key-alias>.command

trailer.<key-alias>.cmd

EXAMPLES¶

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

$ cat msg.txt
subject
body text
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
body text
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

$ cat msg1.txt
subject
body text
$ git config trailer.sign.key "Signed-off-by: "
$ git config trailer.sign.ifmissing add
$ git config trailer.sign.ifexists doNothing
$ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
$ git interpret-trailers --trailer sign <msg1.txt
subject
body text
Signed-off-by: Bob <bob@example.com>
$ cat msg2.txt
subject
body text
Signed-off-by: Alice <alice@example.com>
$ git interpret-trailers --trailer sign <msg2.txt
subject
body text
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

$ cat ~/bin/glog-find-author
#!/bin/sh
test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true
$ cat msg.txt
subject
body text
$ git config trailer.help.key "Helped-by: "
$ git config trailer.help.ifExists "addIfDifferentNeighbor"
$ git config trailer.help.cmd "~/bin/glog-find-author"
$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt
subject
body text
Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Christian Couder <christian.couder@gmail.com>

$ cat ~/bin/glog-grep
#!/bin/sh
test -n "$1" && git log --grep "$1" --pretty=reference -1 || true
$ cat msg.txt
subject
body text
$ git config trailer.ref.key "Reference-to: "
$ git config trailer.ref.ifExists "replace"
$ git config trailer.ref.cmd "~/bin/glog-grep"
$ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt
subject
body text
Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)

$ cat msg.txt
subject
body text
see: HEAD~2
$ cat ~/bin/glog-ref
#!/bin/sh
git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14
$ git config trailer.see.key "See-also: "
$ git config trailer.see.ifExists "replace"
$ git config trailer.see.ifMissing "doNothing"
$ git config trailer.see.cmd "glog-ref"
$ git interpret-trailers --trailer=see <msg.txt
subject
body text
See-also: fe3187489d69c4 (subject of related commit)

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

$ cat msg.txt
subject
Skapad-på: some-branch
Hash-in-v6.11: 45c12d3269fe48f22834320c782ffe86c3560f2c
Reviewed-by: Alice <alice@example.com>
$ git interpret-trailers --only-trailers <msg.txt
$

SEE ALSO¶

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

GIT¶

Part of the git(1) suite