Skip to content

Commit bec94f7

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 daa91c6 commit bec94f7

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
@@ -113,76 +113,96 @@ rules for RFC 822 headers. For example they do not follow the encoding rule.
113113
OPTIONS
114114
-------
115115
`--in-place`::
116-
Edit the files in place.
116+
`--no-in-place`::
117+
Edit the files in place. The default is `--no-in-place`.
117118

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

123-
`--trailer <key>[(=|:)<value>]`::
127+
`--trailer=<key>[(=|:)<value>]`::
128+
`--no-trailer`::
124129
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.
127134

128-
`--where <placement>`::
135+
`--where=<placement>`::
129136
`--no-where`::
130137
Specify where all new trailers will be added. A setting
131138
provided with `--where` overrides the `trailer.where` and any
132139
applicable `trailer.<key-alias>.where` configuration variables
133140
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`,
137142
`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.
138146

139-
`--if-exists <action>`::
147+
`--if-exists=<action>`::
140148
`--no-if-exists`::
141149
Specify what action will be performed when there is already at
142150
least one trailer with the same _<key>_ in the input. A setting
143151
provided with `--if-exists` overrides the `trailer.ifExists` and any
144152
applicable `trailer.<key-alias>.ifExists` configuration variables
145153
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`,
149155
`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.
150160

151-
`--if-missing <action>`::
161+
`--if-missing=<action>`::
152162
`--no-if-missing`::
153163
Specify what action will be performed when there is no other
154164
trailer with the same _<key>_ in the input. A setting
155165
provided with `--if-missing` overrides the `trailer.ifMissing` and any
156166
applicable `trailer.<key-alias>.ifMissing` configuration variables
157167
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.
162174

163175
`--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`.
165179

166180
`--only-input`::
181+
`--no-only-input`::
167182
Output only trailers that exist in the input; do not add any
168183
from the command-line or by applying `trailer.<key-alias>` configuration
169-
variables.
184+
variables. The default is `--no-only-input`.
170185

171186
`--unfold`::
187+
`--no-unfold`::
172188
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`.
174190

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

200+
`--divider`::
182201
`--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]).
186206

187207
CONFIGURATION VARIABLES
188208
-----------------------

0 commit comments

Comments
 (0)