config.txt: add trailer.* variables
The trailer.* configuration variables are currently only described in git-interpret-trailers(1) but affect git-commit and git-tag as well. Move that section into its own config/trailer.txt file and also include it in git-config(1). Signed-off-by: Julian Prein <julian@druckdev.xyz> Acked-by: Eric Sesterhenn <eric.sesterhenn@x41-dsec.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Julian Prein committed
Jan 9, 2025 at 13:25 UTC
6bba6f604ba1658ad9b6b1de6eab299fb9fb35de
3 files changed
+140
-135
Documentation/config.txt
+2
@@ -540,6 +540,8 @@ include::config/tar.txt[]
540
541
include::config/trace2.txt[]
542
543
+include::config/trailer.txt[]
544
+
545
include::config/transfer.txt[]
546
547
include::config/uploadarchive.txt[]
Documentation/config/trailer.txt
new
+136
@@ -0,0 +1,136 @@
1
+trailer.separators::
2
+ This option tells which characters are recognized as trailer
3
+ separators. By default only ':' is recognized as a trailer
4
+ separator, except that '=' is always accepted on the command
5
+ line for compatibility with other git commands.
6
++
7
+The first character given by this option will be the default character
8
+used when another separator is not specified in the config for this
9
+trailer.
10
++
11
+For example, if the value for this option is "%=$", then only lines
12
+using the format '<key><sep><value>' with <sep> containing '%', '='
13
+or '$' and then spaces will be considered trailers. And '%' will be
14
+the default separator used, so by default trailers will appear like:
15
+'<key>% <value>' (one percent sign and one space will appear between
16
+the key and the value).
17
+
18
+trailer.where::
19
+ This option tells where a new trailer will be added.
20
++
21
+This can be `end`, which is the default, `start`, `after` or `before`.
22
++
23
+If it is `end`, then each new trailer will appear at the end of the
24
+existing trailers.
25
++
26
+If it is `start`, then each new trailer will appear at the start,
27
+instead of the end, of the existing trailers.
28
++
29
+If it is `after`, then each new trailer will appear just after the
30
+last trailer with the same <key>.
31
++
32
+If it is `before`, then each new trailer will appear just before the
33
+first trailer with the same <key>.
34
+
35
+trailer.ifexists::
36
+ This option makes it possible to choose what action will be
37
+ performed when there is already at least one trailer with the
38
+ same <key> in the input.
39
++
40
+The valid values for this option are: `addIfDifferentNeighbor` (this
41
+is the default), `addIfDifferent`, `add`, `replace` or `doNothing`.
42
++
43
+With `addIfDifferentNeighbor`, a new trailer will be added only if no
44
+trailer with the same (<key>, <value>) pair is above or below the line
45
+where the new trailer will be added.
46
++
47
+With `addIfDifferent`, a new trailer will be added only if no trailer
48
+with the same (<key>, <value>) pair is already in the input.
49
++
50
+With `add`, a new trailer will be added, even if some trailers with
51
+the same (<key>, <value>) pair are already in the input.
52
++
53
+With `replace`, an existing trailer with the same <key> will be
54
+deleted and the new trailer will be added. The deleted trailer will be
55
+the closest one (with the same <key>) to the place where the new one
56
+will be added.
57
++
58
+With `doNothing`, nothing will be done; that is no new trailer will be
59
+added if there is already one with the same <key> in the input.
60
+
61
+trailer.ifmissing::
62
+ This option makes it possible to choose what action will be
63
+ performed when there is not yet any trailer with the same
64
+ <key> in the input.
65
++
66
+The valid values for this option are: `add` (this is the default) and
67
+`doNothing`.
68
++
69
+With `add`, a new trailer will be added.
70
++
71
+With `doNothing`, nothing will be done.
72
+
73
+trailer.<keyAlias>.key::
74
+ Defines a <keyAlias> for the <key>. The <keyAlias> must be a
75
+ prefix (case does not matter) of the <key>. For example, in `git
76
+ config trailer.ack.key "Acked-by"` the "Acked-by" is the <key> and
77
+ the "ack" is the <keyAlias>. This configuration allows the shorter
78
+ `--trailer "ack:..."` invocation on the command line using the "ack"
79
+ <keyAlias> instead of the longer `--trailer "Acked-by:..."`.
80
++
81
+At the end of the <key>, a separator can appear and then some
82
+space characters. By default the only valid separator is ':',
83
+but this can be changed using the `trailer.separators` config
84
+variable.
85
++
86
+If there is a separator in the key, then it overrides the default
87
+separator when adding the trailer.
88
+
89
+trailer.<keyAlias>.where::
90
+ This option takes the same values as the 'trailer.where'
91
+ configuration variable and it overrides what is specified by
92
+ that option for trailers with the specified <keyAlias>.
93
+
94
+trailer.<keyAlias>.ifexists::
95
+ This option takes the same values as the 'trailer.ifexists'
96
+ configuration variable and it overrides what is specified by
97
+ that option for trailers with the specified <keyAlias>.
98
+
99
+trailer.<keyAlias>.ifmissing::
100
+ This option takes the same values as the 'trailer.ifmissing'
101
+ configuration variable and it overrides what is specified by
102
+ that option for trailers with the specified <keyAlias>.
103
+
104
+trailer.<keyAlias>.command::
105
+ Deprecated in favor of 'trailer.<keyAlias>.cmd'.
106
+ This option behaves in the same way as 'trailer.<keyAlias>.cmd', except
107
+ that it doesn't pass anything as argument to the specified command.
108
+ Instead the first occurrence of substring $ARG is replaced by the
109
+ <value> that would be passed as argument.
110
++
111
+Note that $ARG in the user's command is
112
+only replaced once and that the original way of replacing $ARG is not safe.
113
++
114
+When both 'trailer.<keyAlias>.cmd' and 'trailer.<keyAlias>.command' are given
115
+for the same <keyAlias>, 'trailer.<keyAlias>.cmd' is used and
116
+'trailer.<keyAlias>.command' is ignored.
117
+
118
+trailer.<keyAlias>.cmd::
119
+ This option can be used to specify a shell command that will be called
120
+ once to automatically add a trailer with the specified <keyAlias>, and then
121
+ called each time a '--trailer <keyAlias>=<value>' argument is specified to
122
+ modify the <value> of the trailer that this option would produce.
123
++
124
+When the specified command is first called to add a trailer
125
+with the specified <keyAlias>, the behavior is as if a special
126
+'--trailer <keyAlias>=<value>' argument was added at the beginning
127
+of the "git interpret-trailers" command, where <value>
128
+is taken to be the standard output of the command with any
129
+leading and trailing whitespace trimmed off.
130
++
131
+If some '--trailer <keyAlias>=<value>' arguments are also passed
132
+on the command line, the command is called again once for each
133
+of these arguments with the same <keyAlias>. And the <value> part
134
+of these arguments, if any, will be passed to the command as its
135
+first argument. This way the command can produce a <value> computed
136
+from the <value> passed in the '--trailer <keyAlias>=<value>' argument.
Documentation/git-interpret-trailers.txt
+2
-135
@@ -186,142 +186,9 @@ OPTIONS
186
CONFIGURATION VARIABLES
187
-----------------------
188
189
-trailer.separators::
190
- This option tells which characters are recognized as trailer
191
- separators. By default only ':' is recognized as a trailer
192
- separator, except that '=' is always accepted on the command
193
- line for compatibility with other git commands.
194
-+
195
-The first character given by this option will be the default character
196
-used when another separator is not specified in the config for this
197
-trailer.
198
-+
199
-For example, if the value for this option is "%=$", then only lines
200
-using the format '<key><sep><value>' with <sep> containing '%', '='
201
-or '$' and then spaces will be considered trailers. And '%' will be
202
-the default separator used, so by default trailers will appear like:
203
-'<key>% <value>' (one percent sign and one space will appear between
204
-the key and the value).
205
-
206
-trailer.where::
207
- This option tells where a new trailer will be added.
208
-+
209
-This can be `end`, which is the default, `start`, `after` or `before`.
210
-+
211
-If it is `end`, then each new trailer will appear at the end of the
212
-existing trailers.
213
-+
214
-If it is `start`, then each new trailer will appear at the start,
215
-instead of the end, of the existing trailers.
216
-+
217
-If it is `after`, then each new trailer will appear just after the
218
-last trailer with the same <key>.
219
-+
220
-If it is `before`, then each new trailer will appear just before the
221
-first trailer with the same <key>.
189
+include::includes/cmd-config-section-all.txt[]
190
223
-trailer.ifexists::
224
- This option makes it possible to choose what action will be
225
- performed when there is already at least one trailer with the
226
- same <key> in the input.
227
-+
228
-The valid values for this option are: `addIfDifferentNeighbor` (this
229
-is the default), `addIfDifferent`, `add`, `replace` or `doNothing`.
230
-+
231
-With `addIfDifferentNeighbor`, a new trailer will be added only if no
232
-trailer with the same (<key>, <value>) pair is above or below the line
233
-where the new trailer will be added.
234
-+
235
-With `addIfDifferent`, a new trailer will be added only if no trailer
236
-with the same (<key>, <value>) pair is already in the input.
237
-+
238
-With `add`, a new trailer will be added, even if some trailers with
239
-the same (<key>, <value>) pair are already in the input.
240
-+
241
-With `replace`, an existing trailer with the same <key> will be
242
-deleted and the new trailer will be added. The deleted trailer will be
243
-the closest one (with the same <key>) to the place where the new one
244
-will be added.
245
-+
246
-With `doNothing`, nothing will be done; that is no new trailer will be
247
-added if there is already one with the same <key> in the input.
248
-
249
-trailer.ifmissing::
250
- This option makes it possible to choose what action will be
251
- performed when there is not yet any trailer with the same
252
- <key> in the input.
253
-+
254
-The valid values for this option are: `add` (this is the default) and
255
-`doNothing`.
256
-+
257
-With `add`, a new trailer will be added.
258
-+
259
-With `doNothing`, nothing will be done.
260
-
261
-trailer.<keyAlias>.key::
262
- Defines a <keyAlias> for the <key>. The <keyAlias> must be a
263
- prefix (case does not matter) of the <key>. For example, in `git
264
- config trailer.ack.key "Acked-by"` the "Acked-by" is the <key> and
265
- the "ack" is the <keyAlias>. This configuration allows the shorter
266
- `--trailer "ack:..."` invocation on the command line using the "ack"
267
- <keyAlias> instead of the longer `--trailer "Acked-by:..."`.
268
-+
269
-At the end of the <key>, a separator can appear and then some
270
-space characters. By default the only valid separator is ':',
271
-but this can be changed using the `trailer.separators` config
272
-variable.
273
-+
274
-If there is a separator in the key, then it overrides the default
275
-separator when adding the trailer.
276
-
277
-trailer.<keyAlias>.where::
278
- This option takes the same values as the 'trailer.where'
279
- configuration variable and it overrides what is specified by
280
- that option for trailers with the specified <keyAlias>.
281
-
282
-trailer.<keyAlias>.ifexists::
283
- This option takes the same values as the 'trailer.ifexists'
284
- configuration variable and it overrides what is specified by
285
- that option for trailers with the specified <keyAlias>.
286
-
287
-trailer.<keyAlias>.ifmissing::
288
- This option takes the same values as the 'trailer.ifmissing'
289
- configuration variable and it overrides what is specified by
290
- that option for trailers with the specified <keyAlias>.
291
-
292
-trailer.<keyAlias>.command::
293
- Deprecated in favor of 'trailer.<keyAlias>.cmd'.
294
- This option behaves in the same way as 'trailer.<keyAlias>.cmd', except
295
- that it doesn't pass anything as argument to the specified command.
296
- Instead the first occurrence of substring $ARG is replaced by the
297
- <value> that would be passed as argument.
298
-+
299
-Note that $ARG in the user's command is
300
-only replaced once and that the original way of replacing $ARG is not safe.
301
-+
302
-When both 'trailer.<keyAlias>.cmd' and 'trailer.<keyAlias>.command' are given
303
-for the same <keyAlias>, 'trailer.<keyAlias>.cmd' is used and
304
-'trailer.<keyAlias>.command' is ignored.
305
-
306
-trailer.<keyAlias>.cmd::
307
- This option can be used to specify a shell command that will be called
308
- once to automatically add a trailer with the specified <keyAlias>, and then
309
- called each time a '--trailer <keyAlias>=<value>' argument is specified to
310
- modify the <value> of the trailer that this option would produce.
311
-+
312
-When the specified command is first called to add a trailer
313
-with the specified <keyAlias>, the behavior is as if a special
314
-'--trailer <keyAlias>=<value>' argument was added at the beginning
315
-of the "git interpret-trailers" command, where <value>
316
-is taken to be the standard output of the command with any
317
-leading and trailing whitespace trimmed off.
318
-+
319
-If some '--trailer <keyAlias>=<value>' arguments are also passed
320
-on the command line, the command is called again once for each
321
-of these arguments with the same <keyAlias>. And the <value> part
322
-of these arguments, if any, will be passed to the command as its
323
-first argument. This way the command can produce a <value> computed
324
-from the <value> passed in the '--trailer <keyAlias>=<value>' argument.
191
+include::config/trailer.txt[]
192
193
EXAMPLES
194
--------