doc: config: convert trailers section to synopsis style
Convert this part of the configuration documentation to synopsis style so that all of git-interpret-trailers(1) is consistent. See the commit message from two commits ago. 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
95bd86772eae65917fe5723ed89ee86c76907ef9
1 file changed
+61
-60
Documentation/config/trailer.adoc
+61
-60
@@ -1,21 +1,21 @@
1
-trailer.separators::
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
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
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
15
+`<key>% <value>` (one percent sign and one space will appear between
16
the key and the value).
17
18
-trailer.where::
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`.
@@ -27,41 +27,41 @@ 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>.
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>.
33
+first trailer with the same _<key>_.
34
35
-trailer.ifexists::
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.
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
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.
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.
51
+the same (_<key>_, _<value>_) pair are already in the input.
52
+
53
-With `replace`, an existing trailer with the same <key> will be
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
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.
59
+added if there is already one with the same _<key>_ in the input.
60
61
-trailer.ifmissing::
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.
64
+ _<key>_ in the input.
65
+
66
The valid values for this option are: `add` (this is the default) and
67
`doNothing`.
@@ -70,67 +70,68 @@ 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
73
+`trailer.<key-alias>.key`::
74
+ Defines a _<key-alias>_ for the _<key>_. The _<key-alias>_ 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 _<key-alias>_. 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:..."`.
79
+ `<key-alias>` 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 ':',
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'
89
+`trailer.<key-alias>.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>.
92
+ that option for trailers with the specified _<key-alias>_.
93
94
-trailer.<keyAlias>.ifexists::
95
- This option takes the same values as the 'trailer.ifexists'
94
+`trailer.<key-alias>.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>.
97
+ that option for trailers with the specified _<key-alias>_.
98
99
-trailer.<keyAlias>.ifmissing::
100
- This option takes the same values as the 'trailer.ifmissing'
99
+`trailer.<key-alias>.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>.
102
+ that option for trailers with the specified _<key-alias>_.
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
104
+`trailer.<key-alias>.command`::
105
+ Deprecated in favor of `trailer.<key-alias>.cmd`.
106
+ This option behaves in the same way as `trailer.<key-alias>.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.
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.
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.
114
+When both `trailer.<key-alias>.cmd` and `trailer.<key-alias>.command` are given
115
+for the same _<key-alias>_, `trailer.<key-alias>.cmd` is used and
116
+`trailer.<key-alias>.command` is ignored.
117
118
-trailer.<keyAlias>.cmd::
118
+`trailer.<key-alias>.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.
120
+ once to automatically add a trailer with the specified _<key-alias>_, and then
121
+ called each time a `--trailer <key-alias>=<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.
125
+with the specified _<key-alias>_, the behavior is as if a special
126
+`--trailer <key-alias>=<value>` argument was added at the beginning
127
+of linkgit:git-interpret-trailers[1], where _<value>_ is taken to be the
128
+standard output of the command with any leading and trailing whitespace
129
+trimmed off.
130
+
131
-If some '--trailer <keyAlias>=<value>' arguments are also passed
131
+If some `--trailer <key-alias>=<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
133
+of these arguments with the same _<key-alias>_. 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.
135
+first argument. This way the command can produce a _<value>_ computed
136
+from the _<value>_ passed in the `--trailer <key-alias>=<value>`
137
+argument.