mirror of
https://github.com/git-for-windows/git.git
synced 2026-04-03 14:04:52 -05:00
bec94f79e4
Some negated options are missing according to
`git interpret-trailers -h`.
Also normalize to the “stuck form” (see gitcli(7)) like what was done
in 806337c7 (doc: notes: use stuck form throughout, 2025-05-27).[1]
Also normalize the order of the regular and negated options according to
the current convention.[2]
Also note that `--no-trailer` will reset the list.
† 1: See also https://lore.kernel.org/git/6f7d027e-088a-4d66-92af-b8d1c32d730c@app.fastmail.com/
† 2: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
412 lines
13 KiB
Plaintext
412 lines
13 KiB
Plaintext
git-interpret-trailers(1)
|
|
=========================
|
|
|
|
NAME
|
|
----
|
|
git-interpret-trailers - Add or parse structured information in commit messages
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[synopsis]
|
|
git interpret-trailers [--in-place] [--trim-empty]
|
|
[(--trailer (<key>|<key-alias>)[(=|:)<value>])...]
|
|
[--parse] [<file>...]
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
Add or parse _trailer_ lines that look similar to RFC 822 e-mail
|
|
headers, at the end of the otherwise free-form part of a commit
|
|
message. 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 linkgit: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.
|
|
|
|
By default, a `<key>=<value>` or `<key>:<value>` argument given
|
|
using `--trailer` will be appended after the existing trailers only if
|
|
the last trailer has a different (_<key>_, _<value>_) pair (or if there
|
|
is no existing trailer). 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
|
|
"`:`{nbsp}" (one colon followed by one space).
|
|
|
|
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"`.
|
|
|
|
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
|
|
at the end of the input. A blank line will be added before the new
|
|
trailer if there isn't one already.
|
|
|
|
Existing trailers are extracted from the input 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 input or be the last
|
|
non-whitespace lines before a line that starts with `---` (followed by a
|
|
space or the end of the line).
|
|
|
|
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.
|
|
------------------------------------------------
|
|
|
|
Note that trailers do not follow (nor are they intended to follow) many of the
|
|
rules for RFC 822 headers. For example they do not follow the encoding rule.
|
|
|
|
OPTIONS
|
|
-------
|
|
`--in-place`::
|
|
`--no-in-place`::
|
|
Edit the files in place. The default is `--no-in-place`.
|
|
|
|
`--trim-empty`::
|
|
`--no-trim-empty`::
|
|
If the _<value>_ part of any trailer contains only whitespace,
|
|
the whole trailer will be removed from the output.
|
|
This applies to existing trailers as well as new trailers.
|
|
+
|
|
The default is `--no-trim-empty`.
|
|
|
|
`--trailer=<key>[(=|:)<value>]`::
|
|
`--no-trailer`::
|
|
Specify a (_<key>_, _<value>_) pair that should be applied as a
|
|
trailer to the inputs. See the description of this command. Can
|
|
be given multiple times.
|
|
+
|
|
Use `--no-trailer` to reset the list.
|
|
|
|
`--where=<placement>`::
|
|
`--no-where`::
|
|
Specify where all new trailers will be added. A setting
|
|
provided with `--where` overrides the `trailer.where` and any
|
|
applicable `trailer.<key-alias>.where` configuration variables
|
|
and applies to all `--trailer` options until the next occurrence of
|
|
`--where` or `--no-where`. Possible placements are `after`,
|
|
`before`, `end` or `start`.
|
|
+
|
|
Use `--no-where` to clear the effect of any previous use of `--where`,
|
|
such that the relevant configuration variables are no longer overridden.
|
|
|
|
`--if-exists=<action>`::
|
|
`--no-if-exists`::
|
|
Specify what action will be performed when there is already at
|
|
least one trailer with the same _<key>_ in the input. A setting
|
|
provided with `--if-exists` overrides the `trailer.ifExists` and any
|
|
applicable `trailer.<key-alias>.ifExists` configuration variables
|
|
and applies to all `--trailer` options until the next occurrence of
|
|
`--if-exists` or `--no-if-exists`. Possible actions are `addIfDifferent`,
|
|
`addIfDifferentNeighbor`, `add`, `replace` and `doNothing`.
|
|
+
|
|
Use `--no-if-exists` to clear the effect of any previous use of
|
|
`--if-exists`, such that the relevant configuration variables are no
|
|
longer overridden.
|
|
|
|
`--if-missing=<action>`::
|
|
`--no-if-missing`::
|
|
Specify what action will be performed when there is no other
|
|
trailer with the same _<key>_ in the input. A setting
|
|
provided with `--if-missing` overrides the `trailer.ifMissing` and any
|
|
applicable `trailer.<key-alias>.ifMissing` configuration variables
|
|
and applies to all `--trailer` options until the next occurrence of
|
|
`--if-missing` or `--no-if-missing`. Possible actions are
|
|
`doNothing` or `add`.
|
|
+
|
|
Use `--no-if-missing` to clear the effect of any previous use of
|
|
`--if-missing`, such that the relevant configuration variables are no
|
|
longer overridden.
|
|
|
|
`--only-trailers`::
|
|
`--no-only-trailers`::
|
|
Output only the trailers, not any other parts of the
|
|
input. The default is `--no-only-trailers`.
|
|
|
|
`--only-input`::
|
|
`--no-only-input`::
|
|
Output only trailers that exist in the input; do not add any
|
|
from the command-line or by applying `trailer.<key-alias>` configuration
|
|
variables. The default is `--no-only-input`.
|
|
|
|
`--unfold`::
|
|
`--no-unfold`::
|
|
If a trailer has a value that runs over multiple lines (aka "folded"),
|
|
reformat the value into a single line. The default is `--no-unfold`.
|
|
|
|
`--parse`::
|
|
A convenience alias for `--only-trailers --only-input
|
|
--unfold`. This makes it easier to only see the trailers coming from the
|
|
input without influencing them with any command line options or
|
|
configuration variables, while also making the output machine-friendly with
|
|
`--unfold`.
|
|
+
|
|
There is no convenience alias to negate this alias.
|
|
|
|
`--divider`::
|
|
`--no-divider`::
|
|
Treat `---` as the end of the commit message. This is the default.
|
|
Use `--no-divider` when you know your input contains just the
|
|
commit message itself (and not an email or the output of
|
|
linkgit:git-format-patch[1]).
|
|
|
|
CONFIGURATION VARIABLES
|
|
-----------------------
|
|
|
|
include::includes/cmd-config-section-all.adoc[]
|
|
|
|
include::config/trailer.adoc[]
|
|
|
|
EXAMPLES
|
|
--------
|
|
|
|
* Configure a `sign` trailer with a `Signed-off-by` key, and then
|
|
add two of these trailers to a commit message file:
|
|
+
|
|
------------
|
|
$ 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>
|
|
------------
|
|
|
|
* Use the `--in-place` option to edit a commit message file in place:
|
|
+
|
|
------------
|
|
$ 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>
|
|
------------
|
|
|
|
* Extract the last commit as a patch, and add a `Cc` and a
|
|
`Reviewed-by` trailer to it:
|
|
+
|
|
------------
|
|
$ 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
|
|
------------
|
|
|
|
* Configure a `sign` trailer with a command to automatically add a
|
|
"`Signed-off-by:`{nbsp}" with the author information only if there is no
|
|
"`Signed-off-by:`{nbsp}" already, and show how it works:
|
|
+
|
|
------------
|
|
$ 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>
|
|
------------
|
|
|
|
* Configure a `fix` trailer with a key that contains a `#` and no
|
|
space after this character, and show how it works:
|
|
+
|
|
------------
|
|
$ git config trailer.separators ":#"
|
|
$ git config trailer.fix.key "Fix #"
|
|
$ echo "subject" | git interpret-trailers --trailer fix=42
|
|
subject
|
|
|
|
Fix #42
|
|
------------
|
|
|
|
* Configure a `help` trailer with a cmd use a script `glog-find-author`
|
|
which search specified author identity from git log in git repository
|
|
and show how it works:
|
|
+
|
|
------------
|
|
$ 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>
|
|
------------
|
|
|
|
* Configure a `ref` trailer with a cmd use a script `glog-grep`
|
|
to grep last relevant commit from git log in the git repository
|
|
and show how it works:
|
|
+
|
|
------------
|
|
$ 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)
|
|
------------
|
|
|
|
* Configure a `see` trailer with a command to show the subject of a
|
|
commit that is related, and show how it works:
|
|
+
|
|
------------
|
|
$ 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)
|
|
------------
|
|
|
|
* Configure a commit template with some trailers with empty values
|
|
(using sed to show and keep the trailing spaces at the end of the
|
|
trailers), then configure a commit-msg hook that uses
|
|
git-interpret-trailers(1) to remove trailers with empty values and to
|
|
add a `git-version` trailer:
|
|
+
|
|
------------
|
|
$ 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
|
|
------------
|
|
|
|
SEE ALSO
|
|
--------
|
|
linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1]
|
|
|
|
GIT
|
|
---
|
|
Part of the linkgit:git[1] suite
|