doc: interpret-trailers: convert to synopsis style
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` Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Kristoffer Haugsbakk committed
Mar 16, 2026 at 22:48 UTC
daa91c693eb1fef0cd04aed8c6b37ee79d5897e0
1 file changed
+73
-72
Documentation/git-interpret-trailers.adoc
+73
-72
@@ -7,14 +7,14 @@ git-interpret-trailers - Add or parse structured information in commit messages
7
8
SYNOPSIS
9
--------
10
-[verse]
11
-'git interpret-trailers' [--in-place] [--trim-empty]
10
+[synopsis]
11
+git interpret-trailers [--in-place] [--trim-empty]
12
[(--trailer (<key>|<key-alias>)[(=|:)<value>])...]
13
[--parse] [<file>...]
14
15
DESCRIPTION
16
-----------
17
-Add or parse 'trailer' lines that look similar to RFC 822 e-mail
17
+Add or parse _trailer_ lines that look similar to RFC 822 e-mail
18
headers, at the end of the otherwise free-form part of a commit
19
message. For example, in the following commit message
20
@@ -27,23 +27,24 @@ Signed-off-by: Alice <alice@example.com>
27
Signed-off-by: Bob <bob@example.com>
28
------------------------------------------------
29
30
-the last two lines starting with "Signed-off-by" are trailers.
30
+the last two lines starting with `Signed-off-by` are trailers.
31
32
This command reads commit messages from either the
33
-<file> arguments or the standard input if no <file> is specified.
33
+_<file>_ arguments or the standard input if no _<file>_ is specified.
34
If `--parse` is specified, the output consists of the parsed trailers
35
coming from the input, without influencing them with any command line
36
options or configuration variables.
37
38
-Otherwise, this command applies `trailer.*` configuration variables
39
-(which could potentially add new trailers, as well as reposition them),
40
-as well as any command line arguments that can override configuration
41
-variables (such as `--trailer=...` which could also add new trailers),
42
-to each input file. The result is emitted on the standard output.
38
+Otherwise, this command applies `trailer.<key-alias>` configuration
39
+variables (which could potentially add new trailers, as well as
40
+reposition them), as well as any command line arguments that can
41
+override configuration variables (such as `--trailer=...` which could
42
+also add new trailers), to each input file. The result is emitted on the
43
+standard output.
44
45
This command can also operate on the output of linkgit:git-format-patch[1],
46
which is more elaborate than a plain commit message. Namely, such output
46
-includes a commit message (as above), a "---" divider line, and a patch part.
47
+includes a commit message (as above), a `---` divider line, and a patch part.
48
For these inputs, the divider and patch parts are not modified by
49
this command and are emitted as is on the output, unless
50
`--no-divider` is specified.
@@ -53,24 +54,24 @@ are applied to each input and the way any existing trailer in
54
the input is changed. They also make it possible to
55
automatically add some trailers.
56
56
-By default, a '<key>=<value>' or '<key>:<value>' argument given
57
+By default, a `<key>=<value>` or `<key>:<value>` argument given
58
using `--trailer` will be appended after the existing trailers only if
58
-the last trailer has a different (<key>, <value>) pair (or if there
59
-is no existing trailer). The <key> and <value> parts will be trimmed
59
+the last trailer has a different (_<key>_, _<value>_) pair (or if there
60
+is no existing trailer). The _<key>_ and _<value>_ parts will be trimmed
61
to remove starting and trailing whitespace, and the resulting trimmed
61
-<key> and <value> will appear in the output like this:
62
+_<key>_ and _<value>_ will appear in the output like this:
63
64
------------------------------------------------
65
key: value
66
------------------------------------------------
67
67
-This means that the trimmed <key> and <value> will be separated by
68
-`': '` (one colon followed by one space).
68
+This means that the trimmed _<key>_ and _<value>_ will be separated by
69
+"`:`{nbsp}" (one colon followed by one space).
70
70
-For convenience, a <key-alias> can be configured to make using `--trailer`
71
+For convenience, a _<key-alias>_ can be configured to make using `--trailer`
72
shorter to type on the command line. This can be configured using the
72
-'trailer.<key-alias>.key' configuration variable. The <keyAlias> must be a prefix
73
-of the full <key> string, although case sensitivity does not matter. For
73
+`trailer.<key-alias>.key` configuration variable. The _<key-alias>_ must be a prefix
74
+of the full _<key>_ string, although case sensitivity does not matter. For
75
example, if you have
76
77
------------------------------------------------
@@ -91,13 +92,13 @@ least one Git-generated or user-configured trailer and consists of at
92
least 25% trailers.
93
The group must be preceded by one or more empty (or whitespace-only) lines.
94
The group must either be at the end of the input or be the last
94
-non-whitespace lines before a line that starts with '---' (followed by a
95
+non-whitespace lines before a line that starts with `---` (followed by a
96
space or the end of the line).
97
98
When reading trailers, there can be no whitespace before or inside the
98
-<key>, but any number of regular space and tab characters are allowed
99
-between the <key> and the separator. There can be whitespaces before,
100
-inside or after the <value>. The <value> may be split over multiple lines
99
+_<key>_, but any number of regular space and tab characters are allowed
100
+between the _<key>_ and the separator. There can be whitespaces before,
101
+inside or after the _<value>_. The _<value>_ may be split over multiple lines
102
with each subsequent line starting with at least one whitespace, like
103
the "folding" in RFC 822. Example:
104
@@ -111,77 +112,77 @@ rules for RFC 822 headers. For example they do not follow the encoding rule.
112
113
OPTIONS
114
-------
114
---in-place::
115
+`--in-place`::
116
Edit the files in place.
117
117
---trim-empty::
118
- If the <value> part of any trailer contains only whitespace,
118
+`--trim-empty`::
119
+ If the _<value>_ part of any trailer contains only whitespace,
120
the whole trailer will be removed from the output.
121
This applies to existing trailers as well as new trailers.
122
122
---trailer <key>[(=|:)<value>]::
123
- Specify a (<key>, <value>) pair that should be applied as a
123
+`--trailer <key>[(=|:)<value>]`::
124
+ Specify a (_<key>_, _<value>_) pair that should be applied as a
125
trailer to the inputs. See the description of this
126
command.
127
127
---where <placement>::
128
---no-where::
128
+`--where <placement>`::
129
+`--no-where`::
130
Specify where all new trailers will be added. A setting
130
- provided with '--where' overrides the `trailer.where` and any
131
- applicable `trailer.<keyAlias>.where` configuration variables
132
- and applies to all '--trailer' options until the next occurrence of
133
- '--where' or '--no-where'. Upon encountering '--no-where', clear the
134
- effect of any previous use of '--where', such that the relevant configuration
131
+ provided with `--where` overrides the `trailer.where` and any
132
+ applicable `trailer.<key-alias>.where` configuration variables
133
+ and applies to all `--trailer` options until the next occurrence of
134
+ `--where` or `--no-where`. Upon encountering `--no-where`, clear the
135
+ effect of any previous use of `--where`, such that the relevant configuration
136
variables are no longer overridden. Possible placements are `after`,
137
`before`, `end` or `start`.
138
138
---if-exists <action>::
139
---no-if-exists::
139
+`--if-exists <action>`::
140
+`--no-if-exists`::
141
Specify what action will be performed when there is already at
141
- least one trailer with the same <key> in the input. A setting
142
- provided with '--if-exists' overrides the `trailer.ifExists` and any
143
- applicable `trailer.<keyAlias>.ifExists` configuration variables
144
- and applies to all '--trailer' options until the next occurrence of
145
- '--if-exists' or '--no-if-exists'. Upon encountering '--no-if-exists', clear the
146
- effect of any previous use of '--if-exists', such that the relevant configuration
142
+ least one trailer with the same _<key>_ in the input. A setting
143
+ provided with `--if-exists` overrides the `trailer.ifExists` and any
144
+ applicable `trailer.<key-alias>.ifExists` configuration variables
145
+ and applies to all `--trailer` options until the next occurrence of
146
+ `--if-exists` or `--no-if-exists`. Upon encountering `--no-if-exists`, clear the
147
+ effect of any previous use of `--if-exists`, such that the relevant configuration
148
variables are no longer overridden. Possible actions are `addIfDifferent`,
149
`addIfDifferentNeighbor`, `add`, `replace` and `doNothing`.
150
150
---if-missing <action>::
151
---no-if-missing::
151
+`--if-missing <action>`::
152
+`--no-if-missing`::
153
Specify what action will be performed when there is no other
153
- trailer with the same <key> in the input. A setting
154
- provided with '--if-missing' overrides the `trailer.ifMissing` and any
155
- applicable `trailer.<keyAlias>.ifMissing` configuration variables
156
- and applies to all '--trailer' options until the next occurrence of
157
- '--if-missing' or '--no-if-missing'. Upon encountering '--no-if-missing',
158
- clear the effect of any previous use of '--if-missing', such that the relevant
154
+ trailer with the same _<key>_ in the input. A setting
155
+ provided with `--if-missing` overrides the `trailer.ifMissing` and any
156
+ applicable `trailer.<key-alias>.ifMissing` configuration variables
157
+ and applies to all `--trailer` options until the next occurrence of
158
+ `--if-missing` or `--no-if-missing`. Upon encountering `--no-if-missing`,
159
+ clear the effect of any previous use of `--if-missing`, such that the relevant
160
configuration variables are no longer overridden. Possible actions are `doNothing`
161
or `add`.
162
162
---only-trailers::
163
+`--only-trailers`::
164
Output only the trailers, not any other parts of the input.
165
165
---only-input::
166
+`--only-input`::
167
Output only trailers that exist in the input; do not add any
167
- from the command-line or by applying `trailer.*` configuration
168
+ from the command-line or by applying `trailer.<key-alias>` configuration
169
variables.
170
170
---unfold::
171
+`--unfold`::
172
If a trailer has a value that runs over multiple lines (aka "folded"),
173
reformat the value into a single line.
174
174
---parse::
175
+`--parse`::
176
A convenience alias for `--only-trailers --only-input
177
--unfold`. This makes it easier to only see the trailers coming from the
178
input without influencing them with any command line options or
179
configuration variables, while also making the output machine-friendly with
179
- --unfold.
180
+ `--unfold`.
181
181
---no-divider::
182
+`--no-divider`::
183
Do not treat `---` as the end of the commit message. Use this
184
when you know your input contains just the commit message itself
184
- (and not an email or the output of `git format-patch`).
185
+ (and not an email or the output of linkgit:git-format-patch[1]).
186
187
CONFIGURATION VARIABLES
188
-----------------------
@@ -193,7 +194,7 @@ include::config/trailer.adoc[]
194
EXAMPLES
195
--------
196
196
-* Configure a 'sign' trailer with a 'Signed-off-by' key, and then
197
+* Configure a `sign` trailer with a `Signed-off-by` key, and then
198
add two of these trailers to a commit message file:
199
+
200
------------
@@ -230,8 +231,8 @@ Signed-off-by: Bob <bob@example.com>
231
Acked-by: Alice <alice@example.com>
232
------------
233
233
-* Extract the last commit as a patch, and add a 'Cc' and a
234
- 'Reviewed-by' trailer to it:
234
+* Extract the last commit as a patch, and add a `Cc` and a
235
+ `Reviewed-by` trailer to it:
236
+
237
------------
238
$ git format-patch -1
@@ -239,9 +240,9 @@ $ git format-patch -1
240
$ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Reviewed-by: Bob <bob@example.com>' 0001-foo.patch >0001-bar.patch
241
------------
242
242
-* Configure a 'sign' trailer with a command to automatically add a
243
- 'Signed-off-by: ' with the author information only if there is no
244
- 'Signed-off-by: ' already, and show how it works:
243
+* Configure a `sign` trailer with a command to automatically add a
244
+ "`Signed-off-by:`{nbsp}" with the author information only if there is no
245
+ "`Signed-off-by:`{nbsp}" already, and show how it works:
246
+
247
------------
248
$ cat msg1.txt
@@ -272,7 +273,7 @@ body text
273
Signed-off-by: Alice <alice@example.com>
274
------------
275
275
-* Configure a 'fix' trailer with a key that contains a '#' and no
276
+* Configure a `fix` trailer with a key that contains a `#` and no
277
space after this character, and show how it works:
278
+
279
------------
@@ -284,7 +285,7 @@ subject
285
Fix #42
286
------------
287
287
-* Configure a 'help' trailer with a cmd use a script `glog-find-author`
288
+* Configure a `help` trailer with a cmd use a script `glog-find-author`
289
which search specified author identity from git log in git repository
290
and show how it works:
291
+
@@ -308,7 +309,7 @@ Helped-by: Junio C Hamano <gitster@pobox.com>
309
Helped-by: Christian Couder <christian.couder@gmail.com>
310
------------
311
311
-* Configure a 'ref' trailer with a cmd use a script `glog-grep`
312
+* Configure a `ref` trailer with a cmd use a script `glog-grep`
313
to grep last relevant commit from git log in the git repository
314
and show how it works:
315
+
@@ -331,7 +332,7 @@ body text
332
Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
333
------------
334
334
-* Configure a 'see' trailer with a command to show the subject of a
335
+* Configure a `see` trailer with a command to show the subject of a
336
commit that is related, and show how it works:
337
+
338
------------
@@ -359,8 +360,8 @@ See-also: fe3187489d69c4 (subject of related commit)
360
* Configure a commit template with some trailers with empty values
361
(using sed to show and keep the trailing spaces at the end of the
362
trailers), then configure a commit-msg hook that uses
362
- 'git interpret-trailers' to remove trailers with empty values and
363
- to add a 'git-version' trailer:
363
+ git-interpret-trailers(1) to remove trailers with empty values and to
364
+ add a `git-version` trailer:
365
+
366
------------
367
$ cat temp.txt