doc: interpret-trailers: normalize and fill out options
Some negated options are missing according to `git interpret-trailers -h`. Also normalize to the “stuck form” (see gitcli(7)) like what was done in 806337c7 (doc: notes: use stuck form throughout, 2025-05-27).[1] Also normalize the order of the regular and negated options according to the current convention.[2] Also note that `--no-trailer` will reset the list. † 1: See also https://lore.kernel.org/git/6f7d027e-088a-4d66-92af-b8d1c32d730c@app.fastmail.com/ † 2: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/ Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Kristoffer Haugsbakk committed
Mar 16, 2026 at 22:48 UTC
bec94f79e4b7473adf70c7b0623057883c549d16
1 file changed
+43
-23
Documentation/git-interpret-trailers.adoc
+43
-23
@@ -113,64 +113,80 @@ rules for RFC 822 headers. For example they do not follow the encoding rule.
113
OPTIONS
114
-------
115
`--in-place`::
116
- Edit the files in place.
116
+`--no-in-place`::
117
+ Edit the files in place. The default is `--no-in-place`.
118
119
`--trim-empty`::
120
+`--no-trim-empty`::
121
If the _<value>_ part of any trailer contains only whitespace,
122
the whole trailer will be removed from the output.
123
This applies to existing trailers as well as new trailers.
124
++
125
+The default is `--no-trim-empty`.
126
123
-`--trailer <key>[(=|:)<value>]`::
127
+`--trailer=<key>[(=|:)<value>]`::
128
+`--no-trailer`::
129
Specify a (_<key>_, _<value>_) pair that should be applied as a
125
- trailer to the inputs. See the description of this
126
- command.
130
+ trailer to the inputs. See the description of this command. Can
131
+ be given multiple times.
132
++
133
+Use `--no-trailer` to reset the list.
134
128
-`--where <placement>`::
135
+`--where=<placement>`::
136
`--no-where`::
137
Specify where all new trailers will be added. A setting
138
provided with `--where` overrides the `trailer.where` and any
139
applicable `trailer.<key-alias>.where` configuration variables
140
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`,
141
+ `--where` or `--no-where`. Possible placements are `after`,
142
`before`, `end` or `start`.
143
++
144
+Use `--no-where` to clear the effect of any previous use of `--where`,
145
+such that the relevant configuration variables are no longer overridden.
146
139
-`--if-exists <action>`::
147
+`--if-exists=<action>`::
148
`--no-if-exists`::
149
Specify what action will be performed when there is already at
150
least one trailer with the same _<key>_ in the input. A setting
151
provided with `--if-exists` overrides the `trailer.ifExists` and any
152
applicable `trailer.<key-alias>.ifExists` configuration variables
153
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`,
154
+ `--if-exists` or `--no-if-exists`. Possible actions are `addIfDifferent`,
155
`addIfDifferentNeighbor`, `add`, `replace` and `doNothing`.
156
++
157
+Use `--no-if-exists` to clear the effect of any previous use of
158
+`--if-exists`, such that the relevant configuration variables are no
159
+longer overridden.
160
151
-`--if-missing <action>`::
161
+`--if-missing=<action>`::
162
`--no-if-missing`::
163
Specify what action will be performed when there is no other
164
trailer with the same _<key>_ in the input. A setting
165
provided with `--if-missing` overrides the `trailer.ifMissing` and any
166
applicable `trailer.<key-alias>.ifMissing` configuration variables
167
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`.
168
+ `--if-missing` or `--no-if-missing`. Possible actions are
169
+ `doNothing` or `add`.
170
++
171
+Use `--no-if-missing` to clear the effect of any previous use of
172
+`--if-missing`, such that the relevant configuration variables are no
173
+longer overridden.
174
175
`--only-trailers`::
164
- Output only the trailers, not any other parts of the input.
176
+`--no-only-trailers`::
177
+ Output only the trailers, not any other parts of the
178
+ input. The default is `--no-only-trailers`.
179
180
`--only-input`::
181
+`--no-only-input`::
182
Output only trailers that exist in the input; do not add any
183
from the command-line or by applying `trailer.<key-alias>` configuration
169
- variables.
184
+ variables. The default is `--no-only-input`.
185
186
`--unfold`::
187
+`--no-unfold`::
188
If a trailer has a value that runs over multiple lines (aka "folded"),
173
- reformat the value into a single line.
189
+ reformat the value into a single line. The default is `--no-unfold`.
190
191
`--parse`::
192
A convenience alias for `--only-trailers --only-input
@@ -178,11 +194,15 @@ OPTIONS
194
input without influencing them with any command line options or
195
configuration variables, while also making the output machine-friendly with
196
`--unfold`.
197
++
198
+There is no convenience alias to negate this alias.
199
200
+`--divider`::
201
`--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
185
- (and not an email or the output of linkgit:git-format-patch[1]).
202
+ Treat `---` as the end of the commit message. This is the default.
203
+ Use `--no-divider` when you know your input contains just the
204
+ commit message itself (and not an email or the output of
205
+ linkgit:git-format-patch[1]).
206
207
CONFIGURATION VARIABLES
208
-----------------------