Skip to content

Commit c450315

Browse files
LemmingAvalanchegitster
authored andcommitted
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 806337c (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>
1 parent 67c93dd commit c450315

1 file changed

Lines changed: 43 additions & 23 deletions

File tree

Documentation/git-interpret-trailers.adoc

Lines changed: 43 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -112,76 +112,96 @@ rules for RFC 822 headers. For example they do not follow the encoding rule.
112112
OPTIONS
113113
-------
114114
`--in-place`::
115-
Edit the files in place.
115+
`--no-in-place`::
116+
Edit the files in place. The default is `--no-in-place`.
116117

117118
`--trim-empty`::
119+
`--no-trim-empty`::
118120
If the _<value>_ part of any trailer contains only whitespace,
119121
the whole trailer will be removed from the output.
120122
This applies to existing trailers as well as new trailers.
123+
+
124+
The default is `--no-trim-empty`.
121125

122-
`--trailer <key>[(=|:)<value>]`::
126+
`--trailer=<key>[(=|:)<value>]`::
127+
`--no-trailer`::
123128
Specify a (_<key>_, _<value>_) pair that should be applied as a
124-
trailer to the inputs. See the description of this
125-
command.
129+
trailer to the inputs. See the description of this command. Can
130+
be given multiple times.
131+
+
132+
Use `--no-trailer` to reset the list.
126133

127-
`--where <placement>`::
134+
`--where=<placement>`::
128135
`--no-where`::
129136
Specify where all new trailers will be added. A setting
130137
provided with `--where` overrides the `trailer.where` and any
131138
applicable `trailer.<keyAlias>.where` configuration variables
132139
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
135-
variables are no longer overridden. Possible placements are `after`,
140+
`--where` or `--no-where`. Possible placements are `after`,
136141
`before`, `end` or `start`.
142+
+
143+
Use `--no-where` to clear the effect of any previous use of `--where`,
144+
such that the relevant configuration variables are no longer overridden.
137145

138-
`--if-exists <action>`::
146+
`--if-exists=<action>`::
139147
`--no-if-exists`::
140148
Specify what action will be performed when there is already at
141149
least one trailer with the same _<key>_ in the input. A setting
142150
provided with `--if-exists` overrides the `trailer.ifExists` and any
143151
applicable `trailer.<keyAlias>.ifExists` configuration variables
144152
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
147-
variables are no longer overridden. Possible actions are `addIfDifferent`,
153+
`--if-exists` or `--no-if-exists`. Possible actions are `addIfDifferent`,
148154
`addIfDifferentNeighbor`, `add`, `replace` and `doNothing`.
155+
+
156+
Use `--no-if-exists` to clear the effect of any previous use of
157+
`--if-exists`, such that the relevant configuration variables are no
158+
longer overridden.
149159

150-
`--if-missing <action>`::
160+
`--if-missing=<action>`::
151161
`--no-if-missing`::
152162
Specify what action will be performed when there is no other
153163
trailer with the same _<key>_ in the input. A setting
154164
provided with `--if-missing` overrides the `trailer.ifMissing` and any
155165
applicable `trailer.<keyAlias>.ifMissing` configuration variables
156166
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
159-
configuration variables are no longer overridden. Possible actions are `doNothing`
160-
or `add`.
167+
`--if-missing` or `--no-if-missing`. Possible actions are
168+
`doNothing` or `add`.
169+
+
170+
Use `--no-if-missing` to clear the effect of any previous use of
171+
`--if-missing`, such that the relevant configuration variables are no
172+
longer overridden.
161173

162174
`--only-trailers`::
163-
Output only the trailers, not any other parts of the input.
175+
`--no-only-trailers`::
176+
Output only the trailers, not any other parts of the
177+
input. The default is `--no-only-trailers`.
164178

165179
`--only-input`::
180+
`--no-only-input`::
166181
Output only trailers that exist in the input; do not add any
167182
from the command-line or by applying `trailer.*` configuration
168-
variables.
183+
variables. The default is `--no-only-input`.
169184

170185
`--unfold`::
186+
`--no-unfold`::
171187
If a trailer has a value that runs over multiple lines (aka "folded"),
172-
reformat the value into a single line.
188+
reformat the value into a single line. The default is `--no-unfold`.
173189

174190
`--parse`::
175191
A convenience alias for `--only-trailers --only-input
176192
--unfold`. This makes it easier to only see the trailers coming from the
177193
input without influencing them with any command line options or
178194
configuration variables, while also making the output machine-friendly with
179195
`--unfold`.
196+
+
197+
There is no convenience alias to negate this alias.
180198

199+
`--divider`::
181200
`--no-divider`::
182-
Do not treat `---` as the end of the commit message. Use this
183-
when you know your input contains just the commit message itself
184-
(and not an email or the output of linkgit:git-format-patch[1]).
201+
Treat `---` as the end of the commit message. This is the default.
202+
Use `--no-divider` when you know your input contains just the
203+
commit message itself (and not an email or the output of
204+
linkgit:git-format-patch[1]).
185205

186206
CONFIGURATION VARIABLES
187207
-----------------------

0 commit comments

Comments
 (0)