Skip to content

Commit 791677a

Browse files
gitstergitster
committed
Merge branch 'jp/doc-trailer-config'
Documentaiton updates. * jp/doc-trailer-config: config.txt: add trailer.* variables
2 parents 5b9d01b + 6bba6f6 commit 791677a

File tree

3 files changed

+140
-135
lines changed

3 files changed

+140
-135
lines changed

‎Documentation/config.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -540,6 +540,8 @@ include::config/tar.txt[]
540540

541541
include::config/trace2.txt[]
542542

543+
include::config/trailer.txt[]
544+
543545
include::config/transfer.txt[]
544546

545547
include::config/uploadarchive.txt[]

‎Documentation/config/trailer.txt

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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

Lines changed: 2 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -186,142 +186,9 @@ OPTIONS
186186
CONFIGURATION VARIABLES
187187
-----------------------
188188

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[]
222190

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[]
325192

326193
EXAMPLES
327194
--------

0 commit comments

Comments
 (0)