Skip to contentSkip to conversation

doc: interpret-trailers: convert to synopsis and update options

PATCH Superseded [email protected] 4 participants 17 messages Mar 11 – Mar 16 Documentation

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index fd335fe772a..8a6c1bff472 100644
@@ -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
#2 lore raw

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.

#3 lore raw

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 verbatim replaces a pair of sqs inside verbatim in 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 backticks around 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/

#4 lore raw

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
---
 Documentation/git-interpret-trailers.adoc | 126 +++++++++++-----------
 1 file changed, 63 insertions(+), 63 deletions(-)
(quoted diff) +0 -0

b/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 -1
 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.

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 -0
 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

Quoted 15 lines
Documentation/git-interpret-trailers.adoc +4 -4
 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:
 
 ------------------------------------------------

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 -3
 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`

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 -1
 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

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 last

Documentation/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 -4
 	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

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 -3
 	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

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 -4
 	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

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, replace and doNothing.

---if-missing <action>::
---no-if-missing::
+--if-missing <action>::
+--no-if-missing::

Documentation/git-interpret-trailers.adoc +0 -2
 	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

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>.ifMissing 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-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

doNothing or add.

---only-trailers::
+--only-trailers::

Documentation/git-interpret-trailers.adoc +1 -1
 	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

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 -1
 	variables.
 
---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 -1
 	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

Documentation/git-interpret-trailers.adoc

Quoted 2 lines
Documentation/git-interpret-trailers.adoc +0 -0
 	input 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 a git-version trailer:
+
------------

 $ cat temp.txt

Thanks.

#5 lore raw

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 values

We 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 a git-version trailer:
+
------------

 $ cat temp.txt

I’ll incorporate all of these in the next round.

#6 lore raw

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 to
git interpret-trailers -h.

Also normalize to the “stuck form” (see gitcli(7)) like what was done in 806337c7 (doc: notes: use stuck form throughout, 2025-05-27).[1]

Also normalize the order of the regular and negated options according to the current convention.[2]

Also note that --no-trailer will reset the list.

† 1: See also https://lore.kernel.org/git/[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
index 8a6c1bff472..e5da0462fad 100644
@@ -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
#7 lore raw

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
index 60bc221c88b..a382f68fe9e 100644
@@ -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
#8 lore raw

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

#9 lore raw

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".

#10 lore raw
In reply to [email protected]
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

#11 lore raw
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

#12 lore raw

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
index a382f68fe9e..1bc70192d3a 100644
@@ -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
index e5da0462fad..77b4f63b05c 100644
@@ -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
index 41b0750e5af..4b617c3ecb0 100644
@@ -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
#13 lore raw

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
index fd335fe772a..ea47f2f7ae5 100644
@@ -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
#14 lore raw

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 to
git interpret-trailers -h.

Also normalize to the “stuck form” (see gitcli(7)) like what was done in 806337c7 (doc: notes: use stuck form throughout, 2025-05-27).[1]

Also normalize the order of the regular and negated options according to the current convention.[2]

Also note that --no-trailer will reset the list.

† 1: See also https://lore.kernel.org/git/[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
index ea47f2f7ae5..77b4f63b05c 100644
@@ -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
#15 lore raw

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
index 60bc221c88b..1bc70192d3a 100644
@@ -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
#16 lore raw

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
index 41b0750e5af..4b617c3ecb0 100644
@@ -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