doc: interpret-trailers: convert to synopsis and update options
cover doc: interpret-trailers: convert to synopsis and update options
From: Kristoffer Haugsbakk <[email protected]>
Topic name: doc-interpret-trailers-1
Topic summary: Convert to synopsis style and update options.
[3/1] doc: interpret-trailers: convert to synopsis style [3/2] doc: interpret-trailers: normalize and fill out options [3/3] doc: config: convert trailers section to synopsis style
Documentation/config/trailer.adoc | 121 +++++++-------- Documentation/git-interpret-trailers.adoc | 170 ++++++++++++---------- 2 files changed, 156 insertions(+), 135 deletions(-)
base-commit: 67ad42147a7acc2af6074753ebd03d904476118f
Signature · 1 line
2.53.0.32.gf6228eaf9cc
PATCH 1/3 doc: interpret-trailers: convert to synopsis style
From: Kristoffer Haugsbakk <[email protected]>
See e.g. 0ae23ab5 (doc: convert git worktree to synopsis style, 2025-10-05) for the markup rules for this style.
There aren’t many subtleties to the transformation of this doc since it doesn’t use any advanced constructs. The only thing is that ": " is used instead of ': ' to refer to effective inline-verbatim with a space (␠). I also use (_) for emphasis although (') gives the same result.
Also prefer linking to Git commands instead of saying e.g. git format-patch.
--- Documentation/git-interpret-trailers.adoc | 126 +++++++++++----------- 1 file changed, 63 insertions(+), 63 deletions(-)
Documentation/git-interpret-trailers.adoc +63 -63
@@ -7,14 +7,14 @@ git-interpret-trailers - Add or parse structured information in commit messages SYNOPSIS -------- -[verse] -'git interpret-trailers' [--in-place] [--trim-empty] +[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 +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
@@ -27,10 +27,10 @@ Signed-off-by: Alice <[email protected]> Signed-off-by: Bob <[email protected]> ------------------------------------------------ -the last two lines starting with "Signed-off-by" are trailers. +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. +_<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.
@@ -43,7 +43,7 @@ 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. +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.
@@ -53,24 +53,24 @@ 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 +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 +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>_ 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). +This means that the trimmed _<key>_ and _<value>_ will be separated by +": " (one colon followed by one space). -For convenience, a <key-alias> can be configured to make using `--trailer` +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 <keyAlias> must be a prefix -of the full <key> string, although case sensitivity does not matter. For +`trailer.<key-alias>.key` configuration variable. The _<keyAlias>_ must be a prefix +of the full _<key>_ string, although case sensitivity does not matter. For example, if you have ------------------------------------------------
@@ -91,13 +91,13 @@ 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 +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 +_<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:
@@ -111,77 +111,77 @@ rules for RFC 822 headers. For example they do not follow the encoding rule. OPTIONS ------- ---in-place:: +`--in-place`:: Edit the files in place. ---trim-empty:: - If the <value> part of any trailer contains only whitespace, +`--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. ---trailer <key>[(=|:)<value>]:: - Specify a (<key>, <value>) pair that should be applied as a +`--trailer <key>[(=|:)<value>]`:: + Specify a (_<key>_, _<value>_) pair that should be applied as a trailer to the inputs. See the description of this command. ---where <placement>:: ---no-where:: +`--where <placement>`:: +`--no-where`:: Specify where all new trailers will be added. A setting - provided with '--where' overrides the `trailer.where` and any + provided with `--where` overrides the `trailer.where` and any applicable `trailer.<keyAlias>.where` configuration variables - and applies to all '--trailer' options until the next occurrence of - '--where' or '--no-where'. Upon encountering '--no-where', clear the - effect of any previous use of '--where', such that the relevant configuration + and applies to all `--trailer` options until the next occurrence of + `--where` or `--no-where`. Upon encountering `--no-where`, clear the + effect of any previous use of `--where`, such that the relevant configuration variables are no longer overridden. Possible placements are `after`, `before`, `end` or `start`. ---if-exists <action>:: ---no-if-exists:: +`--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 + least one trailer with the same _<key>_ in the input. A setting + provided with `--if-exists` overrides the `trailer.ifExists` and any applicable `trailer.<keyAlias>.ifExists` configuration variables - and applies to all '--trailer' options until the next occurrence of - '--if-exists' or '--no-if-exists'. Upon encountering '--no-if-exists', clear the - effect of any previous use of '--if-exists', such that the relevant configuration + and applies to all `--trailer` options until the next occurrence of + `--if-exists` or `--no-if-exists`. Upon encountering `--no-if-exists`, clear the + effect of any previous use of `--if-exists`, such that the relevant configuration variables are no longer overridden. Possible actions are `addIfDifferent`, `addIfDifferentNeighbor`, `add`, `replace` and `doNothing`. ---if-missing <action>:: ---no-if-missing:: +`--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 + trailer with the same _<key>_ in the input. A setting + provided with `--if-missing` overrides the `trailer.ifMissing` and any applicable `trailer.<keyAlias>.ifMissing` configuration variables - and applies to all '--trailer' options until the next occurrence of - '--if-missing' or '--no-if-missing'. Upon encountering '--no-if-missing', - clear the effect of any previous use of '--if-missing', such that the relevant + and applies to all `--trailer` options until the next occurrence of + `--if-missing` or `--no-if-missing`. Upon encountering `--no-if-missing`, + clear the effect of any previous use of `--if-missing`, such that the relevant configuration variables are no longer overridden. Possible actions are `doNothing` or `add`. ---only-trailers:: +`--only-trailers`:: Output only the trailers, not any other parts of the input. ---only-input:: +`--only-input`:: Output only trailers that exist in the input; do not add any from the command-line or by applying `trailer.*` configuration variables. ---unfold:: +`--unfold`:: If a trailer has a value that runs over multiple lines (aka "folded"), reformat the value into a single line. ---parse:: +`--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. + `--unfold`. ---no-divider:: +`--no-divider`:: Do not treat `---` as the end of the commit message. Use this when you know your input contains just the commit message itself - (and not an email or the output of `git format-patch`). + (and not an email or the output of linkgit:git-format-patch[1]). CONFIGURATION VARIABLES -----------------------
@@ -193,7 +193,7 @@ include::config/trailer.adoc[] EXAMPLES -------- -* Configure a 'sign' trailer with a 'Signed-off-by' key, and then +* Configure a `sign` trailer with a `Signed-off-by` key, and then add two of these trailers to a commit message file: + ------------
@@ -230,8 +230,8 @@ Signed-off-by: Bob <[email protected]> Acked-by: Alice <[email protected]> ------------ -* Extract the last commit as a patch, and add a 'Cc' and a - 'Reviewed-by' trailer to it: +* Extract the last commit as a patch, and add a `Cc` and a + `Reviewed-by` trailer to it: + ------------ $ git format-patch -1
@@ -239,9 +239,9 @@ $ git format-patch -1 $ git interpret-trailers --trailer 'Cc: Alice <[email protected]>' --trailer 'Reviewed-by: Bob <[email protected]>' 0001-foo.patch >0001-bar.patch ------------ -* Configure a 'sign' trailer with a command to automatically add a - 'Signed-off-by: ' with the author information only if there is no - 'Signed-off-by: ' already, and show how it works: +* Configure a `sign` trailer with a command to automatically add a + "Signed-off-by: " with the author information only if there is no + "Signed-off-by: " already, and show how it works: + ------------ $ cat msg1.txt
@@ -272,7 +272,7 @@ body text Signed-off-by: Alice <[email protected]> ------------ -* Configure a 'fix' trailer with a key that contains a '#' and no +* Configure a `fix` trailer with a key that contains a `#` and no space after this character, and show how it works: + ------------
@@ -284,7 +284,7 @@ subject Fix #42 ------------ -* Configure a 'help' trailer with a cmd use a script `glog-find-author` +* 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: +
@@ -308,7 +308,7 @@ Helped-by: Junio C Hamano <[email protected]> Helped-by: Christian Couder <[email protected]> ------------ -* Configure a 'ref' trailer with a cmd use a script `glog-grep` +* 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: +
@@ -331,7 +331,7 @@ body text Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07) ------------ -* Configure a 'see' trailer with a command to show the subject of a +* Configure a `see` trailer with a command to show the subject of a commit that is related, and show how it works: + ------------
@@ -359,8 +359,8 @@ 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' to remove trailers with empty values and - to add a 'git-version' trailer: + linkgit:git-interpret-trailers[1] to remove trailers with empty values and + to add a `git-version` trailer: + ------------ $ cat temp.txt
Signature · 1 line
2.53.0.32.gf6228eaf9cc
Re: [PATCH 1/3] doc: interpret-trailers: convert to synopsis style
Quoted 2 lines · [email protected] writes:
...s. The only thing is that
": "is
used instead of': '...
The description says that a pair of dqs inside verbatim replaces a pair of sqs inside verbatim in the original.
Does this refer to this change?
Documentation/git-interpret-trailers.adoc are applied to each input and the way any existing trailer in · line 68
Quoted 4 lines
Documentation/git-interpret-trailers.adoc +2
-2-This means that the trimmed <key> and <value> will be separated by -`': '` (one colon followed by one space). +This means that the trimmed _<key>_ and _<value>_ will be separated by +": " (one colon followed by one space).
We seem to have lost the backticks around the thing. Intended? Does the thing still typeset as verbatim in the manpages?
Thanks.
Re: [PATCH 1/3] doc: interpret-trailers: convert to synopsis style
Quoted 8 lines · Junio C Hamano
Quoted 2 lines · [email protected] writes:
...s. The only thing is that
": "is
used instead of': '...The description says that a pair of dqs inside
verbatimreplaces a pair of sqs insideverbatimin the original.
Quoted 8 lines
Does this refer to this change?
Documentation/git-interpret-trailers.adoc are applied to each input and the way any existing trailer in · line 68
Quoted 4 lines
Documentation/git-interpret-trailers.adoc +2
-2-This means that the trimmed <key> and <value> will be separated by -`': '` (one colon followed by one space). +This means that the trimmed _<key>_ and _<value>_ will be separated by +": " (one colon followed by one space).We seem to have lost the
backticksaround the thing. Intended?
Yes it is intended. It seems to be the current approach to “verbatim” (in spirit) that ends in a space is to use "<verbatim> ".
I had this arrow from Documentation/pretty-formats.adoc in the back of my mind when editing this part:[1]
pointer=<value>;; Shown between HEAD and the branch it points to, if any.
Defaults to "{nbsp}->{nbsp}".
So (finally looking back at this) maybe I need to use the no-break space expression here.
† 1: This part was recently changed although this {nbsp}->{nbsp} part
did not change: a34d1d53 (doc: convert git-show to synopsis style, 2026-02-06)
Quoted 1 line
Does the thing still typeset as verbatim in the manpages?
No. It’s just regular text.
For that matter: my setup (perhaps flawed[2]) also renders ': ' in the preimage as regular text in the HTML output.
🔗 2: https://lore.kernel.org/git/9570525.CDJkKcVGEf@piment-oiseau/
Re: [PATCH 1/3] doc: interpret-trailers: convert to synopsis style
In reply to [email protected]Quoted 14 lines · On Wednesday, 11 March 2026 23:31:04 CET [email protected] wrote:
From: Kristoffer Haugsbakk <[email protected]>
See e.g.
0ae23ab5(doc: convert git worktree to synopsis style, 2025-10-05) for the markup rules for this style.There aren’t many subtleties to the transformation of this doc since it doesn’t use any advanced constructs. The only thing is that
": "is used instead of': 'to refer to effective inline-verbatim with a space (␠). I also use (_) for emphasis although (') gives the same result.Also prefer linking to Git commands instead of saying e.g.
git format-patch.
Quoted 7 lines
Signed-off-by Kristoffer Haugsbakk <[email protected]>--- Documentation/git-interpret-trailers.adoc | 126 +++++++++++----------- 1 file changed, 63 insertions(+), 63 deletions(-)(quoted diff) +0
-0b/Documentation/git-interpret-trailers.adoc index
fd335fe772a..8a6c1bff472
100644
Documentation/git-interpret-trailers.adoc git-interpret-trailers - Add or parse structured
Quoted 3 lines
Documentation/git-interpret-trailers.adoc +0
-0@@ -7,14 +7,14 @@ git-interpret-trailers - Add or parse structured
information in
Documentation/git-interpret-trailers.adoc
Quoted 9 lines
commit messages
SYNOPSIS
--------
-[verse]
-'git interpret-trailers' [--in-place] [--trim-empty] +[synopsis]Documentation/git-interpret-trailers.adoc +1
-0+git interpret-trailers [--in-place] [--trim-empty] [(--trailer (<key>|<key-alias>)
[(=|:)<value>])...]
Documentation/git-interpret-trailers.adoc to each input file. The result is emitted on the standard
Quoted 23 lines
Documentation/git-interpret-trailers.adoc +3
-3[--parse] [<file>...] DESCRIPTION ----------- -Add or parse 'trailer' lines that look similar to RFC 822 e-mail +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@@ -27,10 +27,10 @@ Signed-off-by: Alice <[email protected]> Signed-off-by: Bob <[email protected]> ------------------------------------------------ -the last two lines starting with "Signed-off-by" are trailers. +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. +_<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.@@ -43,7 +43,7 @@ to each input file. The result is emitted on the standard
output.
Documentation/git-interpret-trailers.adoc to each input file. The result is emitted on the standard output.
Quoted 4 lines
Documentation/git-interpret-trailers.adoc +0
-1This 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.
Documentation/git-interpret-trailers.adoc to each input file. The result is emitted on the standard · line 45
Quoted 1 line
Documentation/git-interpret-trailers.adoc +1
-0+includes a commit message (as above), a `---` divider line, and a patch
part.
Documentation/git-interpret-trailers.adoc are applied to each input and the way any existing
Quoted 4 lines
Documentation/git-interpret-trailers.adoc +0
-0For 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.@@ -53,24 +53,24 @@ are applied to each input and the way any existing
trailer in
Quoted 15 lines
Documentation/git-interpret-trailers.adoc +4
-4the input is changed. They also make it possible to automatically add some trailers. -By default, a '<key>=<value>' or '<key>:<value>' argument given +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 +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>_ and _<value>_ will appear in the output like this: ------------------------------------------------
Documentation/git-interpret-trailers.adoc are applied to each input and the way any existing trailer in
Quoted 10 lines
Documentation/git-interpret-trailers.adoc +3
-3key: value ------------------------------------------------ -This means that the trimmed <key> and <value> will be separated by -`': '` (one colon followed by one space). +This means that the trimmed _<key>_ and _<value>_ will be separated by +": " (one colon followed by one space). -For convenience, a <key-alias> can be configured to make using `--trailer` +For convenience, a _<key-alias>_ can be configured to make using `--
trailer`
Documentation/git-interpret-trailers.adoc are applied to each input and the way any existing · line 72
Quoted 2 lines
Documentation/git-interpret-trailers.adoc +0
-1shorter to type on the command line. This can be configured using the -'trailer.<key-alias>.key' configuration variable. The <keyAlias> must be a
prefix
Documentation/git-interpret-trailers.adoc are applied to each input and the way any existing · line 72
Quoted 2 lines
Documentation/git-interpret-trailers.adoc +1
-1-of the full <key> string, although case sensitivity does not matter. For +`trailer.<key-alias>.key` configuration variable. The _<keyAlias>_ must be
Here, I guess that _<keyAlias>_ is in fact _<key-alias>_ . We do not use camelCase for placeholders.
Quoted 2 lines
a
prefix +of the full _<key>_ string, although case sensitivity does not
matter. For
Documentation/git-interpret-trailers.adoc least one Git-generated or user-configured trailer and
Quoted 4 lines
example, if you have
------------------------------------------------
Documentation/git-interpret-trailers.adoc +0
-0@@ -91,13 +91,13 @@ least one Git-generated or user-configured trailer and
consists
Quoted 4 lines
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 lastDocumentation/git-interpret-trailers.adoc +0
-1-non-whitespace lines before a line that starts with '---' (followed by a
Documentation/git-interpret-trailers.adoc least one Git-generated or user-configured trailer and consists of at
Quoted 10 lines
Documentation/git-interpret-trailers.adoc +4
-3+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 +_<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
Documentation/git-interpret-trailers.adoc rules for RFC 822 headers. For example they do not
Quoted 4 lines
with each subsequent line starting with at least one whitespace, like the "folding" in RFC 822. Example:
Documentation/git-interpret-trailers.adoc +0
-0@@ -111,77 +111,77 @@ rules for RFC 822 headers. For example they do not
follow the
Quoted 20 lines
encoding rule.
OPTIONS
-------
---in-place::
+--in-place::Documentation/git-interpret-trailers.adoc +4
-4Edit the files in place. ---trim-empty:: - If the <value> part of any trailer contains only whitespace, +`--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. ---trailer <key>[(=|:)<value>]:: - Specify a (<key>, <value>) pair that should be applied as a +`--trailer <key>[(=|:)<value>]`:: + Specify a (_<key>_, _<value>_) pair that should be applied as a trailer to the inputs. See the description of this
Documentation/git-interpret-trailers.adoc rules for RFC 822 headers. For example they do not follow the encoding rule. · line 131
Quoted 10 lines
Documentation/git-interpret-trailers.adoc +3
-3command. ---where <placement>:: ---no-where:: +`--where <placement>`:: +`--no-where`:: Specify where all new trailers will be added. A setting - provided with '--where' overrides the `trailer.where` and any + provided with `--where` overrides the `trailer.where` and any applicable `trailer.<keyAlias>.where` configuration variables
Here also, it's <key-alias> instead of <keyAlias> .
Documentation/git-interpret-trailers.adoc rules for RFC 822 headers. For example they do not follow the encoding rule.
Quoted 3 lines
Documentation/git-interpret-trailers.adoc +0
-3- and applies to all '--trailer' options until the next occurrence of - '--where' or '--no-where'. Upon encountering '--no-where', clear the - effect of any previous use of '--where', such that the relevant
configuration
Documentation/git-interpret-trailers.adoc rules for RFC 822 headers. For example they do not follow the encoding rule.
Quoted 3 lines
Documentation/git-interpret-trailers.adoc +3
-0+ and applies to all `--trailer` options until the next occurrence of + `--where` or `--no-where`. Upon encountering `--no-where`, clear the + effect of any previous use of `--where`, such that the relevant
configuration
Documentation/git-interpret-trailers.adoc rules for RFC 822 headers. For example they do not follow the encoding rule. · line 143
Quoted 13 lines
Documentation/git-interpret-trailers.adoc +4
-4variables are no longer overridden. Possible placements are `after`, `before`, `end` or `start`. ---if-exists <action>:: ---no-if-exists:: +`--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 + least one trailer with the same _<key>_ in the input. A setting + provided with `--if-exists` overrides the `trailer.ifExists` and any applicable `trailer.<keyAlias>.ifExists` configuration variables
Idem
Documentation/git-interpret-trailers.adoc
Quoted 2 lines
Documentation/git-interpret-trailers.adoc +0
-2- and applies to all '--trailer' options until the next occurrence of - '--if-exists' or '--no-if-exists'. Upon encountering '--no-if-
exists', clear the
Documentation/git-interpret-trailers.adoc
Quoted 1 line
Documentation/git-interpret-trailers.adoc +0
-1- effect of any previous use of '--if-exists', such that the relevant
configuration
Documentation/git-interpret-trailers.adoc
Quoted 2 lines
Documentation/git-interpret-trailers.adoc +2
-0+ and applies to all `--trailer` options until the next occurrence of + `--if-exists` or `--no-if-exists`. Upon encountering `--no-if-
exists`, clear the
Documentation/git-interpret-trailers.adoc
Quoted 1 line
Documentation/git-interpret-trailers.adoc +1
-0+ effect of any previous use of `--if-exists`, such that the relevant
configuration
Documentation/git-interpret-trailers.adoc rules for RFC 822 headers. For example they do not follow the encoding rule.
Quoted 10 lines
variables are no longer overridden. Possible actions are
addIfDifferent,addIfDifferentNeighbor,add,replaceanddoNothing.---if-missing <action>::
---no-if-missing::
+--if-missing <action>::
+--no-if-missing::Documentation/git-interpret-trailers.adoc +0
-2Specify 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
Documentation/git-interpret-trailers.adoc
Quoted 2 lines
Documentation/git-interpret-trailers.adoc +2
-0+ trailer with the same _<key>_ in the input. A setting + provided with `--if-missing` overrides the `trailer.ifMissing` and
any
Quoted 1 line
applicable
trailer.<keyAlias>.ifMissingconfiguration variables
Idem
Documentation/git-interpret-trailers.adoc
Quoted 2 lines
Documentation/git-interpret-trailers.adoc +0
-2- and applies to all '--trailer' options until the next occurrence of - '--if-missing' or '--no-if-missing'. Upon encountering '--no-if-
missing',
Documentation/git-interpret-trailers.adoc
Quoted 1 line
Documentation/git-interpret-trailers.adoc +0
-1- clear the effect of any previous use of '--if-missing', such that
the relevant
Documentation/git-interpret-trailers.adoc
Quoted 2 lines
Documentation/git-interpret-trailers.adoc +2
-0+ and applies to all `--trailer` options until the next occurrence of + `--if-missing` or `--no-if-missing`. Upon encountering `--no-if-
missing`,
Documentation/git-interpret-trailers.adoc
Quoted 1 line
Documentation/git-interpret-trailers.adoc +1
-0+ clear the effect of any previous use of `--if-missing`, such that
the relevant
Quoted 1 line
configuration variables are no longer overridden. Possible actions
are
Documentation/git-interpret-trailers.adoc rules for RFC 822 headers. For example they do not follow the encoding rule. · line 167
Quoted 10 lines
doNothingoradd.---only-trailers::
+--only-trailers::Documentation/git-interpret-trailers.adoc +1
-1Output only the trailers, not any other parts of the input. ---only-input:: +`--only-input`:: Output only trailers that exist in the input; do not add any from the command-line or by applying `trailer.*` configuration
The star here stands for a placeholder. Let's name it and use synopsis style:
trailer.<key-alias>
Documentation/git-interpret-trailers.adoc rules for RFC 822 headers. For example they do not follow the encoding rule.
Quoted 5 lines
Documentation/git-interpret-trailers.adoc +1
-1variables. ---unfold:: +`--unfold`:: If a trailer has a value that runs over multiple lines (aka
"folded"),
Documentation/git-interpret-trailers.adoc rules for RFC 822 headers. For example they do not follow the encoding rule.
Quoted 6 lines
Documentation/git-interpret-trailers.adoc +1
-1reformat the value into a single line. ---parse:: +`--parse`:: A convenience alias for `--only-trailers --only-input --unfold`. This makes it easier to only see the trailers coming from
the
Documentation/git-interpret-trailers.adoc
Quoted 2 lines
Documentation/git-interpret-trailers.adoc +0
-0input without influencing them with any command line options or configuration variables, while also making the output machine-
friendly with
Quoted 33 lines
Documentation/git-interpret-trailers.adoc +6
-6- --unfold. + `--unfold`. ---no-divider:: +`--no-divider`:: Do not treat `---` as the end of the commit message. Use this when you know your input contains just the commit message itself - (and not an email or the output of `git format-patch`). + (and not an email or the output of linkgit:git-format-patch[1]). CONFIGURATION VARIABLES -----------------------@@ -193,7 +193,7 @@ include::config/trailer.adoc[] EXAMPLES -------- -* Configure a 'sign' trailer with a 'Signed-off-by' key, and then +* Configure a `sign` trailer with a `Signed-off-by` key, and then add two of these trailers to a commit message file: + ------------@@ -230,8 +230,8 @@ Signed-off-by: Bob <[email protected]> Acked-by: Alice <[email protected]> ------------ -* Extract the last commit as a patch, and add a 'Cc' and a - 'Reviewed-by' trailer to it: +* Extract the last commit as a patch, and add a `Cc` and a + `Reviewed-by` trailer to it: + ------------ $ git format-patch -1
Documentation/git-interpret-trailers.adoc $ git format-patch -1 · line 239
Quoted 1 line
Documentation/git-interpret-trailers.adoc +0
-0@@ -239,9 +239,9 @@ $ git format-patch -1 $ git interpret-trailers --trailer 'Cc: Alice <[email protected]>' --
trailer
Quoted 1 line
'Reviewed-by: Bob <[email protected]>' 0001-foo.patch >0001-bar.patch
------------
Quoted 47 lines
Documentation/git-interpret-trailers.adoc +7
-7-* Configure a 'sign' trailer with a command to automatically add a - 'Signed-off-by: ' with the author information only if there is no - 'Signed-off-by: ' already, and show how it works: +* Configure a `sign` trailer with a command to automatically add a + "Signed-off-by: " with the author information only if there is no + "Signed-off-by: " already, and show how it works: + ------------ $ cat msg1.txt@@ -272,7 +272,7 @@ body text Signed-off-by: Alice <[email protected]> ------------ -* Configure a 'fix' trailer with a key that contains a '#' and no +* Configure a `fix` trailer with a key that contains a `#` and no space after this character, and show how it works: + ------------@@ -284,7 +284,7 @@ subject Fix #42 ------------ -* Configure a 'help' trailer with a cmd use a script `glog-find-author` +* 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: +@@ -308,7 +308,7 @@ Helped-by: Junio C Hamano <[email protected]> Helped-by: Christian Couder <[email protected]> ------------ -* Configure a 'ref' trailer with a cmd use a script `glog-grep` +* 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: +@@ -331,7 +331,7 @@ body text Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07) ------------ -* Configure a 'see' trailer with a command to show the subject of a +* Configure a `see` trailer with a command to show the subject of a commit that is related, and show how it works: + ------------
Documentation/git-interpret-trailers.adoc See-also: fe3187489d69c4 (subject of related commit) · line 362
Quoted 6 lines
Documentation/git-interpret-trailers.adoc +1
-2@@ -359,8 +359,8 @@ 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' to remove trailers with empty values and - to add a 'git-version' trailer: + linkgit:git-interpret-trailers[1] to remove trailers with empty values
We are already in the manual page of git-interpret-trailer. It is useless to provide a link to the current manpage.
Quoted 5 lines
and
+ to add agit-versiontrailer:
+
------------$ cat temp.txt
Thanks.
Re: [PATCH 1/3] doc: interpret-trailers: convert to synopsis style
Thank you for the review.
Quoted 12 lines · Jean-Noël AVILA
Documentation/git-interpret-trailers.adoc See-also: fe3187489d69c4 (subject of related commit) · line 362
Quoted 8 lines
[snip]
Documentation/git-interpret-trailers.adoc +1
-2@@ -359,8 +359,8 @@ 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' to remove trailers with empty values and - to add a 'git-version' trailer: + linkgit:git-interpret-trailers[1] to remove trailers with empty valuesWe are already in the manual page of git-interpret-trailer. It is useless to provide a link to the current manpage.
What should be written here? The existing git interpret-trailers or git-interpret-trailers(1)?
Quoted 5 lines
Quoted 5 lines
and
+ to add agit-versiontrailer:
+
------------$ cat temp.txt
I’ll incorporate all of these in the next round.
PATCH 2/3 doc: interpret-trailers: normalize and fill out options
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Some negated options are missing according togit 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/[email protected]/
† 2: https://lore.kernel.org/git/[email protected]/
--- Documentation/git-interpret-trailers.adoc | 66 +++++++++++++++-------- 1 file changed, 43 insertions(+), 23 deletions(-)
Documentation/git-interpret-trailers.adoc +43 -23
@@ -112,64 +112,80 @@ rules for RFC 822 headers. For example they do not follow the encoding rule. OPTIONS ------- `--in-place`:: - Edit the files 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>]`:: +`--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. + trailer to the inputs. See the description of this command. Can + be given multiple times. ++ +Use `--no-trailer` to reset the list. -`--where <placement>`:: +`--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.<keyAlias>.where` configuration variables and applies to all `--trailer` options until the next occurrence of - `--where` or `--no-where`. Upon encountering `--no-where`, clear the - effect of any previous use of `--where`, such that the relevant configuration - variables are no longer overridden. Possible placements are `after`, + `--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>`:: +`--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.<keyAlias>.ifExists` configuration variables and applies to all `--trailer` options until the next occurrence of - `--if-exists` or `--no-if-exists`. Upon encountering `--no-if-exists`, clear the - effect of any previous use of `--if-exists`, such that the relevant configuration - variables are no longer overridden. Possible actions are `addIfDifferent`, + `--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>`:: +`--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.<keyAlias>.ifMissing` configuration variables and applies to all `--trailer` options until the next occurrence of - `--if-missing` or `--no-if-missing`. Upon encountering `--no-if-missing`, - clear the effect of any previous use of `--if-missing`, such that the relevant - configuration variables are no longer overridden. Possible actions are `doNothing` - or `add`. + `--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`:: - Output only the trailers, not any other parts of the input. +`--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.*` configuration - variables. + 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. + reformat the value into a single line. The default is `--no-unfold`. `--parse`:: A convenience alias for `--only-trailers --only-input
@@ -177,11 +193,15 @@ OPTIONS 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`:: - Do not treat `---` as the end of the commit message. Use this - when you know your input contains just the commit message itself - (and not an email or the output of linkgit:git-format-patch[1]). + 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 -----------------------
Signature · 1 line
2.53.0.32.gf6228eaf9cc
PATCH 3/3 doc: config: convert trailers section to synopsis style
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Convert this part of the configuration documentation to synopsis style so that all of git-interpret-trailers(1) is consistent.
--- Documentation/config/trailer.adoc | 121 +++++++++++++++--------------- 1 file changed, 61 insertions(+), 60 deletions(-)
Documentation/config/trailer.adoc +61 -60
@@ -1,21 +1,21 @@ -trailer.separators:: +`trailer.separators`:: This option tells which characters are recognized as trailer - separators. By default only ':' is recognized as a trailer - separator, except that '=' is always accepted on the command + separators. By default only `:` is recognized as a trailer + separator, except that `=` is always accepted on the command line for compatibility with other git commands. + The first character given by this option will be the default character used when another separator is not specified in the config for this trailer. + -For example, if the value for this option is "%=$", then only lines -using the format '<key><sep><value>' with <sep> containing '%', '=' -or '$' and then spaces will be considered trailers. And '%' will be +For example, if the value for this option is `%=$`, then only lines +using the format _<key><sep><value>_ with _<sep>_ containing `%`, `=` +or `$` and then spaces will be considered trailers. And `%` will be the default separator used, so by default trailers will appear like: -'<key>% <value>' (one percent sign and one space will appear between +`<key>% <value>` (one percent sign and one space will appear between the key and the value). -trailer.where:: +`trailer.where`:: This option tells where a new trailer will be added. + This can be `end`, which is the default, `start`, `after` or `before`.
@@ -27,41 +27,41 @@ If it is `start`, then each new trailer will appear at the start, instead of the end, of the existing trailers. + If it is `after`, then each new trailer will appear just after the -last trailer with the same <key>. +last trailer with the same _<key>_. + If it is `before`, then each new trailer will appear just before the -first trailer with the same <key>. +first trailer with the same _<key>_. -trailer.ifexists:: +`trailer.ifexists`:: This option makes it possible to choose what action will be performed when there is already at least one trailer with the - same <key> in the input. + same _<key>_ in the input. + The valid values for this option are: `addIfDifferentNeighbor` (this is the default), `addIfDifferent`, `add`, `replace` or `doNothing`. + With `addIfDifferentNeighbor`, a new trailer will be added only if no -trailer with the same (<key>, <value>) pair is above or below the line +trailer with the same (_<key>_, _<value>_) pair is above or below the line where the new trailer will be added. + With `addIfDifferent`, a new trailer will be added only if no trailer -with the same (<key>, <value>) pair is already in the input. +with the same (_<key>_, _<value>_) pair is already in the input. + With `add`, a new trailer will be added, even if some trailers with -the same (<key>, <value>) pair are already in the input. +the same (_<key>_, _<value>_) pair are already in the input. + -With `replace`, an existing trailer with the same <key> will be +With `replace`, an existing trailer with the same _<key>_ will be deleted and the new trailer will be added. The deleted trailer will be -the closest one (with the same <key>) to the place where the new one +the closest one (with the same _<key>_) to the place where the new one will be added. + With `doNothing`, nothing will be done; that is no new trailer will be -added if there is already one with the same <key> in the input. +added if there is already one with the same _<key>_ in the input. -trailer.ifmissing:: +`trailer.ifmissing`:: This option makes it possible to choose what action will be performed when there is not yet any trailer with the same - <key> in the input. + _<key>_ in the input. + The valid values for this option are: `add` (this is the default) and `doNothing`.
@@ -70,67 +70,68 @@ With `add`, a new trailer will be added. + With `doNothing`, nothing will be done. -trailer.<keyAlias>.key:: - Defines a <keyAlias> for the <key>. The <keyAlias> must be a - prefix (case does not matter) of the <key>. For example, in `git - config trailer.ack.key "Acked-by"` the "Acked-by" is the <key> and - the "ack" is the <keyAlias>. This configuration allows the shorter +`trailer.<keyAlias>.key`:: + Defines a _<keyAlias>_ for the _<key>_. The _<keyAlias>_ must be a + prefix (case does not matter) of the _<key>_. For example, in `git + config trailer.ack.key "Acked-by"` the `Acked-by` is the _<key>_ and + the `ack` is the _<keyAlias>_. This configuration allows the shorter `--trailer "ack:..."` invocation on the command line using the "ack" - <keyAlias> instead of the longer `--trailer "Acked-by:..."`. + `<keyAlias>` instead of the longer `--trailer "Acked-by:..."`. + -At the end of the <key>, a separator can appear and then some -space characters. By default the only valid separator is ':', +At the end of the _<key>_, a separator can appear and then some +space characters. By default the only valid separator is `:`, but this can be changed using the `trailer.separators` config variable. + If there is a separator in the key, then it overrides the default separator when adding the trailer. -trailer.<keyAlias>.where:: - This option takes the same values as the 'trailer.where' +`trailer.<keyAlias>.where`:: + This option takes the same values as the `trailer.where` configuration variable and it overrides what is specified by - that option for trailers with the specified <keyAlias>. + that option for trailers with the specified _<keyAlias>_. -trailer.<keyAlias>.ifexists:: - This option takes the same values as the 'trailer.ifexists' +`trailer.<keyAlias>.ifexists`:: + This option takes the same values as the `trailer.ifexists` configuration variable and it overrides what is specified by - that option for trailers with the specified <keyAlias>. + that option for trailers with the specified _<keyAlias>_. -trailer.<keyAlias>.ifmissing:: - This option takes the same values as the 'trailer.ifmissing' +`trailer.<keyAlias>.ifmissing`:: + This option takes the same values as the `trailer.ifmissing` configuration variable and it overrides what is specified by - that option for trailers with the specified <keyAlias>. + that option for trailers with the specified _<keyAlias>_. -trailer.<keyAlias>.command:: - Deprecated in favor of 'trailer.<keyAlias>.cmd'. - This option behaves in the same way as 'trailer.<keyAlias>.cmd', except +`trailer.<keyAlias>.command`:: + Deprecated in favor of `trailer.<keyAlias>.cmd`. + This option behaves in the same way as `trailer.<keyAlias>.cmd`, except that it doesn't pass anything as argument to the specified command. - Instead the first occurrence of substring $ARG is replaced by the - <value> that would be passed as argument. + Instead the first occurrence of substring `$ARG` is replaced by the + _<value>_ that would be passed as argument. + -Note that $ARG in the user's command is -only replaced once and that the original way of replacing $ARG is not safe. +Note that `$ARG` in the user's command is +only replaced once and that the original way of replacing `$ARG` is not safe. + -When both 'trailer.<keyAlias>.cmd' and 'trailer.<keyAlias>.command' are given -for the same <keyAlias>, 'trailer.<keyAlias>.cmd' is used and -'trailer.<keyAlias>.command' is ignored. +When both `trailer.<keyAlias>.cmd` and `trailer.<keyAlias>.command` are given +for the same _<keyAlias>_, `trailer.<keyAlias>.cmd` is used and +`trailer.<keyAlias>.command` is ignored. -trailer.<keyAlias>.cmd:: +`trailer.<keyAlias>.cmd`:: This option can be used to specify a shell command that will be called - once to automatically add a trailer with the specified <keyAlias>, and then - called each time a '--trailer <keyAlias>=<value>' argument is specified to - modify the <value> of the trailer that this option would produce. + once to automatically add a trailer with the specified _<keyAlias>_, and then + called each time a `--trailer <keyAlias>=<value>` argument is specified to + modify the _<value>_ of the trailer that this option would produce. + When the specified command is first called to add a trailer -with the specified <keyAlias>, the behavior is as if a special -'--trailer <keyAlias>=<value>' argument was added at the beginning -of the "git interpret-trailers" command, where <value> -is taken to be the standard output of the command with any -leading and trailing whitespace trimmed off. +with the specified _<keyAlias>_, the behavior is as if a special +`--trailer <keyAlias>=<value>` argument was added at the beginning +of linkgit:git-interpret-trailers[1], where _<value>_ is taken to be the +standard output of the command with any leading and trailing whitespace +trimmed off. + -If some '--trailer <keyAlias>=<value>' arguments are also passed +If some `--trailer <keyAlias>=<value>` arguments are also passed on the command line, the command is called again once for each -of these arguments with the same <keyAlias>. And the <value> part +of these arguments with the same _<keyAlias>_. And the _<value>_ part of these arguments, if any, will be passed to the command as its -first argument. This way the command can produce a <value> computed -from the <value> passed in the '--trailer <keyAlias>=<value>' argument. +first argument. This way the command can produce a _<value>_ computed +from the _<value>_ passed in the `--trailer <keyAlias>=<value>` +argument.
Signature · 1 line
2.53.0.32.gf6228eaf9cc
Re: [PATCH 3/3] doc: config: convert trailers section to synopsis style
Hello,
Except the replacement of <keyAlias> by <key-alias>, this is all good.
Thanks
Re: [PATCH 3/3] doc: config: convert trailers section to synopsis style
Quoted 5 lines · Jean-Noël AVILA
Hello,
Except the replacement of <keyAlias> by <key-alias>, this is all good.
Thanks
Thanks for a review (and of courese, thanks for working on it, Kristoffer).
Will mark the topic as "expecting a hopefully small and final reroll".
Quoted 9 lines · [email protected] writes:
From: Kristoffer Haugsbakk <[email protected]>
Topic name: doc-interpret-trailers-1
Topic summary: Convert to synopsis style and update options.
[3/1] doc: interpret-trailers: convert to synopsis style [3/2] doc: interpret-trailers: normalize and fill out options [3/3] doc: config: convert trailers section to synopsis style
Somebody swapped %(count) and %(total)?
Quoted 6 lines
Documentation/config/trailer.adoc | 121 +++++++-------- Documentation/git-interpret-trailers.adoc | 170 ++++++++++++---------- 2 files changed, 156 insertions(+), 135 deletions(-)base-commit:
67ad42147a7acc2af6074753ebd03d904476118f
Quoted 6 lines · Junio C Hamano
Quoted 4 lines · [email protected] writes:
From: Kristoffer Haugsbakk <[email protected]>
Topic name: doc-interpret-trailers-1
Quoted 7 lines
Quoted 5 lines
Topic summary: Convert to synopsis style and update options.
[3/1] doc: interpret-trailers: convert to synopsis style [3/2] doc: interpret-trailers: normalize and fill out options [3/3] doc: config: convert trailers section to synopsis style
Somebody swapped %(count) and %(total)?
Somebody.
Quoted 8 lines
Quoted 8 lines
Documentation/config/trailer.adoc | 121 +++++++-------- Documentation/git-interpret-trailers.adoc | 170 ++++++++++++---------- 2 files changed, 156 insertions(+), 135 deletions(-)base-commit:
67ad42147a7acc2af6074753ebd03d904476118f
v2 cover doc: interpret-trailers: convert to synopsis and update options
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Topic name (applied): doc-interpret-trailers-1
Topic summary: Convert to synopsis style and update options.
§ Changes in v2
Apply changes from reviews by Jean-Noël and Junio. See the notes on the patches for details.
The last patch is new. To use trailer.<key-alias> instead of trailer.* in the source code (translation strings), in line with the docs.
[1/4] doc: interpret-trailers: convert to synopsis style [2/4] doc: interpret-trailers: normalize and fill out options [3/4] doc: config: convert trailers section to synopsis style [4/4] interpret-trailers: use placeholder instead of *
Documentation/config/trailer.adoc | 121 +++++++------- Documentation/git-interpret-trailers.adoc | 193 ++++++++++++---------- builtin/interpret-trailers.c | 2 +- 3 files changed, 169 insertions(+), 147 deletions(-)
Interdiff against v1:
Documentation/config/trailer.adoc +24 -24
@@ -70,13 +70,13 @@ With `add`, a new trailer will be added. + With `doNothing`, nothing will be done. -`trailer.<keyAlias>.key`:: - Defines a _<keyAlias>_ for the _<key>_. The _<keyAlias>_ must be a +`trailer.<key-alias>.key`:: + Defines a _<key-alias>_ for the _<key>_. The _<key-alias>_ must be a prefix (case does not matter) of the _<key>_. For example, in `git config trailer.ack.key "Acked-by"` the `Acked-by` is the _<key>_ and - the `ack` is the _<keyAlias>_. This configuration allows the shorter + the `ack` is the _<key-alias>_. This configuration allows the shorter `--trailer "ack:..."` invocation on the command line using the "ack" - `<keyAlias>` instead of the longer `--trailer "Acked-by:..."`. + `<key-alias>` instead of the longer `--trailer "Acked-by:..."`. + At the end of the _<key>_, a separator can appear and then some space characters. By default the only valid separator is `:`,
@@ -86,24 +86,24 @@ variable. If there is a separator in the key, then it overrides the default separator when adding the trailer. -`trailer.<keyAlias>.where`:: +`trailer.<key-alias>.where`:: This option takes the same values as the `trailer.where` configuration variable and it overrides what is specified by - that option for trailers with the specified _<keyAlias>_. + that option for trailers with the specified _<key-alias>_. -`trailer.<keyAlias>.ifexists`:: +`trailer.<key-alias>.ifexists`:: This option takes the same values as the `trailer.ifexists` configuration variable and it overrides what is specified by - that option for trailers with the specified _<keyAlias>_. + that option for trailers with the specified _<key-alias>_. -`trailer.<keyAlias>.ifmissing`:: +`trailer.<key-alias>.ifmissing`:: This option takes the same values as the `trailer.ifmissing` configuration variable and it overrides what is specified by - that option for trailers with the specified _<keyAlias>_. + that option for trailers with the specified _<key-alias>_. -`trailer.<keyAlias>.command`:: - Deprecated in favor of `trailer.<keyAlias>.cmd`. - This option behaves in the same way as `trailer.<keyAlias>.cmd`, except +`trailer.<key-alias>.command`:: + Deprecated in favor of `trailer.<key-alias>.cmd`. + This option behaves in the same way as `trailer.<key-alias>.cmd`, except that it doesn't pass anything as argument to the specified command. Instead the first occurrence of substring `$ARG` is replaced by the _<value>_ that would be passed as argument.
@@ -111,27 +111,27 @@ separator when adding the trailer. Note that `$ARG` in the user's command is only replaced once and that the original way of replacing `$ARG` is not safe. + -When both `trailer.<keyAlias>.cmd` and `trailer.<keyAlias>.command` are given -for the same _<keyAlias>_, `trailer.<keyAlias>.cmd` is used and -`trailer.<keyAlias>.command` is ignored. +When both `trailer.<key-alias>.cmd` and `trailer.<key-alias>.command` are given +for the same _<key-alias>_, `trailer.<key-alias>.cmd` is used and +`trailer.<key-alias>.command` is ignored. -`trailer.<keyAlias>.cmd`:: +`trailer.<key-alias>.cmd`:: This option can be used to specify a shell command that will be called - once to automatically add a trailer with the specified _<keyAlias>_, and then - called each time a `--trailer <keyAlias>=<value>` argument is specified to + once to automatically add a trailer with the specified _<key-alias>_, and then + called each time a `--trailer <key-alias>=<value>` argument is specified to modify the _<value>_ of the trailer that this option would produce. + When the specified command is first called to add a trailer -with the specified _<keyAlias>_, the behavior is as if a special -`--trailer <keyAlias>=<value>` argument was added at the beginning +with the specified _<key-alias>_, the behavior is as if a special +`--trailer <key-alias>=<value>` argument was added at the beginning of linkgit:git-interpret-trailers[1], where _<value>_ is taken to be the standard output of the command with any leading and trailing whitespace trimmed off. + -If some `--trailer <keyAlias>=<value>` arguments are also passed +If some `--trailer <key-alias>=<value>` arguments are also passed on the command line, the command is called again once for each -of these arguments with the same _<keyAlias>_. And the _<value>_ part +of these arguments with the same _<key-alias>_. And the _<value>_ part of these arguments, if any, will be passed to the command as its first argument. This way the command can produce a _<value>_ computed -from the _<value>_ passed in the `--trailer <keyAlias>=<value>` +from the _<value>_ passed in the `--trailer <key-alias>=<value>` argument.
Documentation/git-interpret-trailers.adoc +16 -15
@@ -35,11 +35,12 @@ 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.*` 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. +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
@@ -65,11 +66,11 @@ key: value ------------------------------------------------ This means that the trimmed _<key>_ and _<value>_ will be separated by -": " (one colon followed by one space). +"`:`{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 _<keyAlias>_ must be a prefix +`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
@@ -135,7 +136,7 @@ Use `--no-trailer` to reset the list. `--no-where`:: Specify where all new trailers will be added. A setting provided with `--where` overrides the `trailer.where` and any - applicable `trailer.<keyAlias>.where` configuration variables + 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`.
@@ -148,7 +149,7 @@ such that the relevant configuration variables are no longer overridden. 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.<keyAlias>.ifExists` configuration variables + 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`.
@@ -162,7 +163,7 @@ longer overridden. 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.<keyAlias>.ifMissing` configuration variables + 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`.
@@ -179,7 +180,7 @@ longer overridden. `--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.*` configuration + from the command-line or by applying `trailer.<key-alias>` configuration variables. The default is `--no-only-input`. `--unfold`::
@@ -260,8 +261,8 @@ $ git interpret-trailers --trailer 'Cc: Alice <[email protected]>' --trailer 'Re ------------ * Configure a `sign` trailer with a command to automatically add a - "Signed-off-by: " with the author information only if there is no - "Signed-off-by: " already, and show how it works: + "`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
@@ -379,8 +380,8 @@ 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 - linkgit:git-interpret-trailers[1] to remove trailers with empty values and - to add a `git-version` trailer: + git-interpret-trailers(1) to remove trailers with empty values and to + add a `git-version` trailer: + ------------ $ cat temp.txt
builtin/interpret-trailers.c +1 -1
@@ -211,7 +211,7 @@ int cmd_interpret_trailers(int argc, N_("action if trailer is missing"), option_parse_if_missing),OPT_BOOL (0 ,"only-trailers" , &opts.only_trailers,N_ ("output only the trailers" )), -OPT_BOOL (0 ,"only-input" , &opts.only_input,N_ ("do not apply trailer.* configuration variables" )), +OPT_BOOL (0 ,"only-input" , &opts.only_input,N_ ("do not apply trailer.<key-alias> configuration variables" )),OPT_BOOL (0 ,"unfold" , &opts.unfold,N_ ("reformat multiline trailer values as single-line values" )),OPT_CALLBACK_F (0 ,"parse" , &opts,NULL ,N_ ("alias for --only-trailers --only-input --unfold" ), PARSE_OPT_NOARG | PARSE_OPT_NONEG, parse_opt_parse),
Range-diff against v1:
1: 87ec90d0adb ! 1: f9a4622feaf doc: interpret-trailers: convert to synopsis style
@@ Commit message
2025-10-05) for the markup rules for this style.
There aren’t many subtleties to the transformation of this doc since it
- doesn’t use any advanced constructs. The only thing is that ": " is
+ doesn’t use any advanced constructs. The only thing is that ":{nbsp}" is
used instead of ': ' to refer to effective inline-verbatim with
- a space (␠). I also use (_) for emphasis although (') gives the
+ a space (␠).[1] I also use (_) for emphasis although (') gives the
same result.
- Also prefer linking to Git commands instead of saying
- e.g. git format-patch.
+ Also prefer linking to Git commands instead of saying e.g. `git
+ format-patch`. But for this command we can type out git-interpret-
+ trailers(1) to avoid a self-reference.
+
+ Also replace camel case <keyAlias> with kebab case <key-alias>.
+ And while doing that make sure to replace trailer.* with
+ trailer.<key-alias>.
+
+ † 1: Similar to "tag:{nbsp}" in Documentation/pretty-formats.adoc
@@ Documentation/git-interpret-trailers.adoc: Signed-off-by: Alice <[email protected]
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.
-@@ Documentation/git-interpret-trailers.adoc: to each input file. The result is emitted on the standard output. +
+-Otherwise, this command applies trailer.* 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.
++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
@@ Documentation/git-interpret-trailers.adoc: are applied to each input and the way
-This means that the trimmed <key> and <value> will be separated by -': ' (one colon followed by one space).
+This means that the trimmed _<key>_ and _<value>_ will be separated by
-+": " (one colon followed by one space).
++":{nbsp}" (one colon followed by one space).
-For convenience, a <key-alias> can be configured to make using --trailer +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 <keyAlias> must be a prefix -of the full <key> string, although case sensitivity does not matter. For
-+trailer.<key-alias>.key configuration variable. The _<keyAlias>_ must be a prefix ++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
@@ Documentation/git-interpret-trailers.adoc: rules for RFC 822 headers. For exampl
+--no-where::
Specify where all new trailers will be added. A setting
- provided with '--where' overrides the trailer.where and any
-+ provided with --where overrides the trailer.where and any
- applicable trailer.<keyAlias>.where configuration variables
+- applicable trailer.<keyAlias>.where configuration variables
- and applies to all '--trailer' options until the next occurrence of
- '--where' or '--no-where'. Upon encountering '--no-where', clear the
- effect of any previous use of '--where', such that the relevant configuration
++ 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. Upon encountering --no-where, clear the
+ effect of any previous use of --where, such that the relevant configuration
@@ Documentation/git-interpret-trailers.adoc: rules for RFC 822 headers. For exampl
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
-+ least one trailer with the same _<key>_ in the input. A setting
-+ provided with --if-exists overrides the trailer.ifExists and any
- applicable trailer.<keyAlias>.ifExists configuration variables
+- applicable trailer.<keyAlias>.ifExists configuration variables
- and applies to all '--trailer' options until the next occurrence of
- '--if-exists' or '--no-if-exists'. Upon encountering '--no-if-exists', clear the
- effect of any previous use of '--if-exists', such that the relevant configuration
++ 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. Upon encountering --no-if-exists, clear the
+ effect of any previous use of --if-exists, such that the relevant configuration
@@ Documentation/git-interpret-trailers.adoc: rules for RFC 822 headers. For exampl
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
-+ trailer with the same _<key>_ in the input. A setting
-+ provided with --if-missing overrides the trailer.ifMissing and any
- applicable trailer.<keyAlias>.ifMissing configuration variables
+- applicable trailer.<keyAlias>.ifMissing configuration variables
- and applies to all '--trailer' options until the next occurrence of
- '--if-missing' or '--no-if-missing'. Upon encountering '--no-if-missing',
- clear the effect of any previous use of '--if-missing', such that the relevant
++ 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. Upon encountering --no-if-missing,
+ clear the effect of any previous use of --if-missing, such that the relevant
@@ Documentation/git-interpret-trailers.adoc: rules for RFC 822 headers. For exampl
---only-input::
+--only-input::
Output only trailers that exist in the input; do not add any
- from the command-line or by applying trailer.* configuration
+- from the command-line or by applying trailer.* configuration
++ from the command-line or by applying trailer.<key-alias> configuration
variables.
---unfold::
@@ Documentation/git-interpret-trailers.adoc: $ git format-patch -1
- 'Signed-off-by: ' with the author information only if there is no
- 'Signed-off-by: ' already, and show how it works:
+* Configure a sign trailer with a command to automatically add a
-+ "Signed-off-by: " with the author information only if there is no -+ "Signed-off-by: " already, and show how it works:
++ "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
@@ Documentation/git-interpret-trailers.adoc: See-also: fe3187489d69c4 (subject of
trailers), then configure a commit-msg hook that uses
- 'git interpret-trailers' to remove trailers with empty values and
- to add a 'git-version' trailer:
-+ linkgit:git-interpret-trailers[1] to remove trailers with empty values and -+ to add a git-version trailer:
++ git-interpret-trailers(1) to remove trailers with empty values and to ++ add a git-version trailer:
+
------------
$ cat temp.txt
2: e24f8a3d37e ! 2: e04853c499e doc: interpret-trailers: normalize and fill out options
@@ Documentation/git-interpret-trailers.adoc: rules for RFC 822 headers. For exampl
--no-where::
Specify where all new trailers will be added. A setting
provided with --where overrides the trailer.where and any
- applicable trailer.<keyAlias>.where configuration variables
+ applicable trailer.<key-alias>.where configuration variables
and applies to all --trailer options until the next occurrence of
- --where or --no-where. Upon encountering --no-where, clear the
- effect of any previous use of --where, such that the relevant configuration
@@ Documentation/git-interpret-trailers.adoc: rules for RFC 822 headers. For exampl
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.<keyAlias>.ifExists configuration variables
+ applicable trailer.<key-alias>.ifExists configuration variables
and applies to all --trailer options until the next occurrence of
- --if-exists or --no-if-exists. Upon encountering --no-if-exists, clear the
- effect of any previous use of --if-exists, such that the relevant configuration
@@ Documentation/git-interpret-trailers.adoc: rules for RFC 822 headers. For exampl
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.<keyAlias>.ifMissing configuration variables
+ applicable trailer.<key-alias>.ifMissing configuration variables
and applies to all --trailer options until the next occurrence of
- --if-missing or --no-if-missing. Upon encountering --no-if-missing,
- clear the effect of any previous use of --if-missing, such that the relevant
@@ Documentation/git-interpret-trailers.adoc: rules for RFC 822 headers. For exampl
--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.* configuration
+ from the command-line or by applying trailer.<key-alias> configuration
- variables.
+ variables. The default is --no-only-input.
3: 10f11ebb078 ! 3: ed1eb37b935 doc: config: convert trailers section to synopsis style
@@ Commit message
Convert this part of the configuration documentation to synopsis style so that all of git-interpret-trailers(1) is consistent.
+ See the commit message from two commits ago.
+
## Documentation/config/trailer.adoc ##
@@ Documentation/config/trailer.adoc: With add, a new trailer will be added.
- prefix (case does not matter) of the <key>. For example, in `git
- config trailer.ack.key "Acked-by"` the "Acked-by" is the <key> and
- the "ack" is the <keyAlias>. This configuration allows the shorter
-+trailer.<keyAlias>.key::
-+ Defines a _<keyAlias>_ for the _<key>_. The _<keyAlias>_ must be a
++trailer.<key-alias>.key::
++ Defines a _<key-alias>_ for the _<key>_. The _<key-alias>_ must be a
+ prefix (case does not matter) of the _<key>_. For example, in `git
+ config trailer.ack.key "Acked-by" the Acked-by` is the _<key>_ and
-+ the ack is the _<keyAlias>_. This configuration allows the shorter
++ the ack is the _<key-alias>_. This configuration allows the shorter
--trailer "ack:..." invocation on the command line using the "ack"
- <keyAlias> instead of the longer --trailer "Acked-by:...".
-+ <keyAlias> instead of the longer --trailer "Acked-by:...".
++ <key-alias> instead of the longer --trailer "Acked-by:...".
+
-At the end of the <key>, a separator can appear and then some -space characters. By default the only valid separator is ':',
@@ Documentation/config/trailer.adoc: With add, a new trailer will be added.
-trailer.<keyAlias>.where::
- This option takes the same values as the 'trailer.where'
-+trailer.<keyAlias>.where::
++trailer.<key-alias>.where::
+ This option takes the same values as the trailer.where
configuration variable and it overrides what is specified by
- that option for trailers with the specified <keyAlias>.
-+ that option for trailers with the specified _<keyAlias>_.
++ that option for trailers with the specified _<key-alias>_.
-trailer.<keyAlias>.ifexists::
- This option takes the same values as the 'trailer.ifexists'
-+trailer.<keyAlias>.ifexists::
++trailer.<key-alias>.ifexists::
+ This option takes the same values as the trailer.ifexists
configuration variable and it overrides what is specified by
- that option for trailers with the specified <keyAlias>.
-+ that option for trailers with the specified _<keyAlias>_.
++ that option for trailers with the specified _<key-alias>_.
-trailer.<keyAlias>.ifmissing::
- This option takes the same values as the 'trailer.ifmissing'
-+trailer.<keyAlias>.ifmissing::
++trailer.<key-alias>.ifmissing::
+ This option takes the same values as the trailer.ifmissing
configuration variable and it overrides what is specified by
- that option for trailers with the specified <keyAlias>.
-+ that option for trailers with the specified _<keyAlias>_.
++ that option for trailers with the specified _<key-alias>_.
-trailer.<keyAlias>.command::
- Deprecated in favor of 'trailer.<keyAlias>.cmd'.
- This option behaves in the same way as 'trailer.<keyAlias>.cmd', except
-+trailer.<keyAlias>.command::
-+ Deprecated in favor of trailer.<keyAlias>.cmd.
-+ This option behaves in the same way as trailer.<keyAlias>.cmd, except
++trailer.<key-alias>.command::
++ Deprecated in favor of trailer.<key-alias>.cmd.
++ This option behaves in the same way as trailer.<key-alias>.cmd, except
that it doesn't pass anything as argument to the specified command.
- Instead the first occurrence of substring $ARG is replaced by the
- <value> that would be passed as argument.
@@ Documentation/config/trailer.adoc: With add, a new trailer will be added.
-When both 'trailer.<keyAlias>.cmd' and 'trailer.<keyAlias>.command' are given -for the same <keyAlias>, 'trailer.<keyAlias>.cmd' is used and -'trailer.<keyAlias>.command' is ignored.
-+When both trailer.<keyAlias>.cmd and trailer.<keyAlias>.command are given -+for the same _<keyAlias>_, trailer.<keyAlias>.cmd is used and -+trailer.<keyAlias>.command is ignored.
++When both trailer.<key-alias>.cmd and trailer.<key-alias>.command are given ++for the same _<key-alias>_, trailer.<key-alias>.cmd is used and ++trailer.<key-alias>.command is ignored.
-trailer.<keyAlias>.cmd::
-+trailer.<keyAlias>.cmd::
++trailer.<key-alias>.cmd::
This option can be used to specify a shell command that will be called
- once to automatically add a trailer with the specified <keyAlias>, and then
- called each time a '--trailer <keyAlias>=<value>' argument is specified to
- modify the <value> of the trailer that this option would produce.
-+ once to automatically add a trailer with the specified _<keyAlias>_, and then
-+ called each time a --trailer <keyAlias>=<value> argument is specified to
++ once to automatically add a trailer with the specified _<key-alias>_, and then
++ called each time a --trailer <key-alias>=<value> argument is specified to
+ modify the _<value>_ of the trailer that this option would produce.
+
When the specified command is first called to add a trailer
@@ Documentation/config/trailer.adoc: With add, a new trailer will be added.
-of the "git interpret-trailers" command, where <value>
-is taken to be the standard output of the command with any -leading and trailing whitespace trimmed off.
-+with the specified _<keyAlias>_, the behavior is as if a special -+--trailer <keyAlias>=<value> argument was added at the beginning ++with the specified _<key-alias>_, the behavior is as if a special ++--trailer <key-alias>=<value> argument was added at the beginning
+of linkgit:git-interpret-trailers[1], where _<value>_ is taken to be the +standard output of the command with any leading and trailing whitespace +trimmed off.
+
-If some '--trailer <keyAlias>=<value>' arguments are also passed
-+If some --trailer <keyAlias>=<value> arguments are also passed ++If some --trailer <key-alias>=<value> arguments are also passed
on the command line, the command is called again once for each
-of these arguments with the same <keyAlias>. And the <value> part
-+of these arguments with the same _<keyAlias>_. And the _<value>_ part ++of these arguments with the same _<key-alias>_. And the _<value>_ part
of these arguments, if any, will be passed to the command as its
-first argument. This way the command can produce a <value> computed -from the <value> passed in the '--trailer <keyAlias>=<value>' argument. +first argument. This way the command can produce a _<value>_ computed
-+from the _<value>_ passed in the --trailer <keyAlias>=<value> ++from the _<value>_ passed in the --trailer <key-alias>=<value>
+argument.
-: ----------- > 4: 1feb6933662 interpret-trailers: use placeholder instead of *
base-commit: 67ad42147a7acc2af6074753ebd03d904476118f
Signature · 1 line
2.53.0.32.gf6228eaf9cc
PATCH v2 1/4 doc: interpret-trailers: convert to synopsis style
From: Kristoffer Haugsbakk <[email protected]>
See e.g. 0ae23ab5 (doc: convert git worktree to synopsis style, 2025-10-05) for the markup rules for this style.
There aren’t many subtleties to the transformation of this doc since it doesn’t use any advanced constructs. The only thing is that ":{nbsp}" is used instead of ': ' to refer to effective inline-verbatim with a space (␠).[1] I also use (_) for emphasis although (') gives the same result.
Also prefer linking to Git commands instead of saying e.g. git format-patch. But for this command we can type out git-interpret- trailers(1) to avoid a self-reference.
Also replace camel case <keyAlias> with kebab case <key-alias>. And while doing that make sure to replace trailer.* with trailer.<key-alias>.
† 1: Similar to "tag:{nbsp}" in Documentation/pretty-formats.adoc
---
Notes (series):
v2:
• <keyAlias> → <key-alias> (no camelcase)
• trailer.* → trailer.<key-alias>
• No linkgit for this command (it would link to itself); replace with plain git-interpret-trailers(1)
• Use ":{nbsp}" for the verbatim-but-ends-in-space case
This is inspired by Documentation/pretty-formats.adoc:
tag=<value>: Shown before tag names. Defaults to "tag:{nbsp}".
See: https://lore.kernel.org/git/[email protected]/
• And also apply the NBSP treatment to two trailer mentions that originally had a trailing space
Documentation/git-interpret-trailers.adoc | 145 +++++++++++----------- 1 file changed, 73 insertions(+), 72 deletions(-)
Documentation/git-interpret-trailers.adoc +73 -72
@@ -7,14 +7,14 @@ git-interpret-trailers - Add or parse structured information in commit messages SYNOPSIS -------- -[verse] -'git interpret-trailers' [--in-place] [--trim-empty] +[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 +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
@@ -27,23 +27,24 @@ Signed-off-by: Alice <[email protected]> Signed-off-by: Bob <[email protected]> ------------------------------------------------ -the last two lines starting with "Signed-off-by" are trailers. +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. +_<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.*` 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. +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. +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.
@@ -53,24 +54,24 @@ 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 +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 +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>_ 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). +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` +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 <keyAlias> must be a prefix -of the full <key> string, although case sensitivity does not matter. For +`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 ------------------------------------------------
@@ -91,13 +92,13 @@ 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 +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 +_<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:
@@ -111,77 +112,77 @@ rules for RFC 822 headers. For example they do not follow the encoding rule. OPTIONS ------- ---in-place:: +`--in-place`:: Edit the files in place. ---trim-empty:: - If the <value> part of any trailer contains only whitespace, +`--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. ---trailer <key>[(=|:)<value>]:: - Specify a (<key>, <value>) pair that should be applied as a +`--trailer <key>[(=|:)<value>]`:: + Specify a (_<key>_, _<value>_) pair that should be applied as a trailer to the inputs. See the description of this command. ---where <placement>:: ---no-where:: +`--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.<keyAlias>.where` configuration variables - and applies to all '--trailer' options until the next occurrence of - '--where' or '--no-where'. Upon encountering '--no-where', clear the - effect of any previous use of '--where', such that the relevant configuration + 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`. Upon encountering `--no-where`, clear the + effect of any previous use of `--where`, such that the relevant configuration variables are no longer overridden. Possible placements are `after`, `before`, `end` or `start`. ---if-exists <action>:: ---no-if-exists:: +`--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.<keyAlias>.ifExists` configuration variables - and applies to all '--trailer' options until the next occurrence of - '--if-exists' or '--no-if-exists'. Upon encountering '--no-if-exists', clear the - effect of any previous use of '--if-exists', such that the relevant configuration + 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`. Upon encountering `--no-if-exists`, clear the + effect of any previous use of `--if-exists`, such that the relevant configuration variables are no longer overridden. Possible actions are `addIfDifferent`, `addIfDifferentNeighbor`, `add`, `replace` and `doNothing`. ---if-missing <action>:: ---no-if-missing:: +`--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.<keyAlias>.ifMissing` configuration variables - and applies to all '--trailer' options until the next occurrence of - '--if-missing' or '--no-if-missing'. Upon encountering '--no-if-missing', - clear the effect of any previous use of '--if-missing', such that the relevant + 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`. Upon encountering `--no-if-missing`, + clear the effect of any previous use of `--if-missing`, such that the relevant configuration variables are no longer overridden. Possible actions are `doNothing` or `add`. ---only-trailers:: +`--only-trailers`:: Output only the trailers, not any other parts of the input. ---only-input:: +`--only-input`:: Output only trailers that exist in the input; do not add any - from the command-line or by applying `trailer.*` configuration + from the command-line or by applying `trailer.<key-alias>` configuration variables. ---unfold:: +`--unfold`:: If a trailer has a value that runs over multiple lines (aka "folded"), reformat the value into a single line. ---parse:: +`--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. + `--unfold`. ---no-divider:: +`--no-divider`:: Do not treat `---` as the end of the commit message. Use this when you know your input contains just the commit message itself - (and not an email or the output of `git format-patch`). + (and not an email or the output of linkgit:git-format-patch[1]). CONFIGURATION VARIABLES -----------------------
@@ -193,7 +194,7 @@ include::config/trailer.adoc[] EXAMPLES -------- -* Configure a 'sign' trailer with a 'Signed-off-by' key, and then +* Configure a `sign` trailer with a `Signed-off-by` key, and then add two of these trailers to a commit message file: + ------------
@@ -230,8 +231,8 @@ Signed-off-by: Bob <[email protected]> Acked-by: Alice <[email protected]> ------------ -* Extract the last commit as a patch, and add a 'Cc' and a - 'Reviewed-by' trailer to it: +* Extract the last commit as a patch, and add a `Cc` and a + `Reviewed-by` trailer to it: + ------------ $ git format-patch -1
@@ -239,9 +240,9 @@ $ git format-patch -1 $ git interpret-trailers --trailer 'Cc: Alice <[email protected]>' --trailer 'Reviewed-by: Bob <[email protected]>' 0001-foo.patch >0001-bar.patch ------------ -* Configure a 'sign' trailer with a command to automatically add a - 'Signed-off-by: ' with the author information only if there is no - 'Signed-off-by: ' already, and show how it works: +* 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
@@ -272,7 +273,7 @@ body text Signed-off-by: Alice <[email protected]> ------------ -* Configure a 'fix' trailer with a key that contains a '#' and no +* Configure a `fix` trailer with a key that contains a `#` and no space after this character, and show how it works: + ------------
@@ -284,7 +285,7 @@ subject Fix #42 ------------ -* Configure a 'help' trailer with a cmd use a script `glog-find-author` +* 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: +
@@ -308,7 +309,7 @@ Helped-by: Junio C Hamano <[email protected]> Helped-by: Christian Couder <[email protected]> ------------ -* Configure a 'ref' trailer with a cmd use a script `glog-grep` +* 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: +
@@ -331,7 +332,7 @@ body text Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07) ------------ -* Configure a 'see' trailer with a command to show the subject of a +* Configure a `see` trailer with a command to show the subject of a commit that is related, and show how it works: + ------------
@@ -359,8 +360,8 @@ 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' to remove trailers with empty values and - to add a 'git-version' trailer: + git-interpret-trailers(1) to remove trailers with empty values and to + add a `git-version` trailer: + ------------ $ cat temp.txt
Signature · 1 line
2.53.0.32.gf6228eaf9cc
PATCH v2 2/4 doc: interpret-trailers: normalize and fill out options
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Some negated options are missing according togit 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/[email protected]/
† 2: https://lore.kernel.org/git/[email protected]/
--- Documentation/git-interpret-trailers.adoc | 66 +++++++++++++++-------- 1 file changed, 43 insertions(+), 23 deletions(-)
Documentation/git-interpret-trailers.adoc +43 -23
@@ -113,64 +113,80 @@ rules for RFC 822 headers. For example they do not follow the encoding rule. OPTIONS ------- `--in-place`:: - Edit the files 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>]`:: +`--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. + trailer to the inputs. See the description of this command. Can + be given multiple times. ++ +Use `--no-trailer` to reset the list. -`--where <placement>`:: +`--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`. Upon encountering `--no-where`, clear the - effect of any previous use of `--where`, such that the relevant configuration - variables are no longer overridden. Possible placements are `after`, + `--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>`:: +`--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`. Upon encountering `--no-if-exists`, clear the - effect of any previous use of `--if-exists`, such that the relevant configuration - variables are no longer overridden. Possible actions are `addIfDifferent`, + `--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>`:: +`--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`. Upon encountering `--no-if-missing`, - clear the effect of any previous use of `--if-missing`, such that the relevant - configuration variables are no longer overridden. Possible actions are `doNothing` - or `add`. + `--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`:: - Output only the trailers, not any other parts of the input. +`--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. + 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. + reformat the value into a single line. The default is `--no-unfold`. `--parse`:: A convenience alias for `--only-trailers --only-input
@@ -178,11 +194,15 @@ OPTIONS 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`:: - Do not treat `---` as the end of the commit message. Use this - when you know your input contains just the commit message itself - (and not an email or the output of linkgit:git-format-patch[1]). + 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 -----------------------
Signature · 1 line
2.53.0.32.gf6228eaf9cc
PATCH v2 3/4 doc: config: convert trailers section to synopsis style
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Convert this part of the configuration documentation to synopsis style so that all of git-interpret-trailers(1) is consistent.
See the commit message from two commits ago.
---
Notes (series):
v2:
• <keyAlias> → <key-alias> (no camelcase)
• Refer to two-commits-ago for an explanation of the changes
Documentation/config/trailer.adoc | 121 +++++++++++++++--------------- 1 file changed, 61 insertions(+), 60 deletions(-)
Documentation/config/trailer.adoc +61 -60
@@ -1,21 +1,21 @@ -trailer.separators:: +`trailer.separators`:: This option tells which characters are recognized as trailer - separators. By default only ':' is recognized as a trailer - separator, except that '=' is always accepted on the command + separators. By default only `:` is recognized as a trailer + separator, except that `=` is always accepted on the command line for compatibility with other git commands. + The first character given by this option will be the default character used when another separator is not specified in the config for this trailer. + -For example, if the value for this option is "%=$", then only lines -using the format '<key><sep><value>' with <sep> containing '%', '=' -or '$' and then spaces will be considered trailers. And '%' will be +For example, if the value for this option is `%=$`, then only lines +using the format _<key><sep><value>_ with _<sep>_ containing `%`, `=` +or `$` and then spaces will be considered trailers. And `%` will be the default separator used, so by default trailers will appear like: -'<key>% <value>' (one percent sign and one space will appear between +`<key>% <value>` (one percent sign and one space will appear between the key and the value). -trailer.where:: +`trailer.where`:: This option tells where a new trailer will be added. + This can be `end`, which is the default, `start`, `after` or `before`.
@@ -27,41 +27,41 @@ If it is `start`, then each new trailer will appear at the start, instead of the end, of the existing trailers. + If it is `after`, then each new trailer will appear just after the -last trailer with the same <key>. +last trailer with the same _<key>_. + If it is `before`, then each new trailer will appear just before the -first trailer with the same <key>. +first trailer with the same _<key>_. -trailer.ifexists:: +`trailer.ifexists`:: This option makes it possible to choose what action will be performed when there is already at least one trailer with the - same <key> in the input. + same _<key>_ in the input. + The valid values for this option are: `addIfDifferentNeighbor` (this is the default), `addIfDifferent`, `add`, `replace` or `doNothing`. + With `addIfDifferentNeighbor`, a new trailer will be added only if no -trailer with the same (<key>, <value>) pair is above or below the line +trailer with the same (_<key>_, _<value>_) pair is above or below the line where the new trailer will be added. + With `addIfDifferent`, a new trailer will be added only if no trailer -with the same (<key>, <value>) pair is already in the input. +with the same (_<key>_, _<value>_) pair is already in the input. + With `add`, a new trailer will be added, even if some trailers with -the same (<key>, <value>) pair are already in the input. +the same (_<key>_, _<value>_) pair are already in the input. + -With `replace`, an existing trailer with the same <key> will be +With `replace`, an existing trailer with the same _<key>_ will be deleted and the new trailer will be added. The deleted trailer will be -the closest one (with the same <key>) to the place where the new one +the closest one (with the same _<key>_) to the place where the new one will be added. + With `doNothing`, nothing will be done; that is no new trailer will be -added if there is already one with the same <key> in the input. +added if there is already one with the same _<key>_ in the input. -trailer.ifmissing:: +`trailer.ifmissing`:: This option makes it possible to choose what action will be performed when there is not yet any trailer with the same - <key> in the input. + _<key>_ in the input. + The valid values for this option are: `add` (this is the default) and `doNothing`.
@@ -70,67 +70,68 @@ With `add`, a new trailer will be added. + With `doNothing`, nothing will be done. -trailer.<keyAlias>.key:: - Defines a <keyAlias> for the <key>. The <keyAlias> must be a - prefix (case does not matter) of the <key>. For example, in `git - config trailer.ack.key "Acked-by"` the "Acked-by" is the <key> and - the "ack" is the <keyAlias>. This configuration allows the shorter +`trailer.<key-alias>.key`:: + Defines a _<key-alias>_ for the _<key>_. The _<key-alias>_ must be a + prefix (case does not matter) of the _<key>_. For example, in `git + config trailer.ack.key "Acked-by"` the `Acked-by` is the _<key>_ and + the `ack` is the _<key-alias>_. This configuration allows the shorter `--trailer "ack:..."` invocation on the command line using the "ack" - <keyAlias> instead of the longer `--trailer "Acked-by:..."`. + `<key-alias>` instead of the longer `--trailer "Acked-by:..."`. + -At the end of the <key>, a separator can appear and then some -space characters. By default the only valid separator is ':', +At the end of the _<key>_, a separator can appear and then some +space characters. By default the only valid separator is `:`, but this can be changed using the `trailer.separators` config variable. + If there is a separator in the key, then it overrides the default separator when adding the trailer. -trailer.<keyAlias>.where:: - This option takes the same values as the 'trailer.where' +`trailer.<key-alias>.where`:: + This option takes the same values as the `trailer.where` configuration variable and it overrides what is specified by - that option for trailers with the specified <keyAlias>. + that option for trailers with the specified _<key-alias>_. -trailer.<keyAlias>.ifexists:: - This option takes the same values as the 'trailer.ifexists' +`trailer.<key-alias>.ifexists`:: + This option takes the same values as the `trailer.ifexists` configuration variable and it overrides what is specified by - that option for trailers with the specified <keyAlias>. + that option for trailers with the specified _<key-alias>_. -trailer.<keyAlias>.ifmissing:: - This option takes the same values as the 'trailer.ifmissing' +`trailer.<key-alias>.ifmissing`:: + This option takes the same values as the `trailer.ifmissing` configuration variable and it overrides what is specified by - that option for trailers with the specified <keyAlias>. + that option for trailers with the specified _<key-alias>_. -trailer.<keyAlias>.command:: - Deprecated in favor of 'trailer.<keyAlias>.cmd'. - This option behaves in the same way as 'trailer.<keyAlias>.cmd', except +`trailer.<key-alias>.command`:: + Deprecated in favor of `trailer.<key-alias>.cmd`. + This option behaves in the same way as `trailer.<key-alias>.cmd`, except that it doesn't pass anything as argument to the specified command. - Instead the first occurrence of substring $ARG is replaced by the - <value> that would be passed as argument. + Instead the first occurrence of substring `$ARG` is replaced by the + _<value>_ that would be passed as argument. + -Note that $ARG in the user's command is -only replaced once and that the original way of replacing $ARG is not safe. +Note that `$ARG` in the user's command is +only replaced once and that the original way of replacing `$ARG` is not safe. + -When both 'trailer.<keyAlias>.cmd' and 'trailer.<keyAlias>.command' are given -for the same <keyAlias>, 'trailer.<keyAlias>.cmd' is used and -'trailer.<keyAlias>.command' is ignored. +When both `trailer.<key-alias>.cmd` and `trailer.<key-alias>.command` are given +for the same _<key-alias>_, `trailer.<key-alias>.cmd` is used and +`trailer.<key-alias>.command` is ignored. -trailer.<keyAlias>.cmd:: +`trailer.<key-alias>.cmd`:: This option can be used to specify a shell command that will be called - once to automatically add a trailer with the specified <keyAlias>, and then - called each time a '--trailer <keyAlias>=<value>' argument is specified to - modify the <value> of the trailer that this option would produce. + once to automatically add a trailer with the specified _<key-alias>_, and then + called each time a `--trailer <key-alias>=<value>` argument is specified to + modify the _<value>_ of the trailer that this option would produce. + When the specified command is first called to add a trailer -with the specified <keyAlias>, the behavior is as if a special -'--trailer <keyAlias>=<value>' argument was added at the beginning -of the "git interpret-trailers" command, where <value> -is taken to be the standard output of the command with any -leading and trailing whitespace trimmed off. +with the specified _<key-alias>_, the behavior is as if a special +`--trailer <key-alias>=<value>` argument was added at the beginning +of linkgit:git-interpret-trailers[1], where _<value>_ is taken to be the +standard output of the command with any leading and trailing whitespace +trimmed off. + -If some '--trailer <keyAlias>=<value>' arguments are also passed +If some `--trailer <key-alias>=<value>` arguments are also passed on the command line, the command is called again once for each -of these arguments with the same <keyAlias>. And the <value> part +of these arguments with the same _<key-alias>_. And the _<value>_ part of these arguments, if any, will be passed to the command as its -first argument. This way the command can produce a <value> computed -from the <value> passed in the '--trailer <keyAlias>=<value>' argument. +first argument. This way the command can produce a _<value>_ computed +from the _<value>_ passed in the `--trailer <key-alias>=<value>` +argument.
Signature · 1 line
2.53.0.32.gf6228eaf9cc
PATCH v2 4/4 interpret-trailers: use placeholder instead of *
In reply to [email protected]From: Kristoffer Haugsbakk <[email protected]>
Use <key-alias> instead of * in order to be consistent with the documentation.
--- builtin/interpret-trailers.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
builtin/interpret-trailers.c +1 -1
@@ -211,7 +211,7 @@ int cmd_interpret_trailers(int argc, N_("action if trailer is missing"), option_parse_if_missing),OPT_BOOL (0 ,"only-trailers" , &opts.only_trailers,N_ ("output only the trailers" )), -OPT_BOOL (0 ,"only-input" , &opts.only_input,N_ ("do not apply trailer.* configuration variables" )), +OPT_BOOL (0 ,"only-input" , &opts.only_input,N_ ("do not apply trailer.<key-alias> configuration variables" )),OPT_BOOL (0 ,"unfold" , &opts.unfold,N_ ("reformat multiline trailer values as single-line values" )),OPT_CALLBACK_F (0 ,"parse" , &opts,NULL ,N_ ("alias for --only-trailers --only-input --unfold" ), PARSE_OPT_NOARG | PARSE_OPT_NONEG, parse_opt_parse),
Signature · 1 line
2.53.0.32.gf6228eaf9cc