]>
Commit | Line | Data |
---|---|---|
dfd66ddf CC |
1 | git-interpret-trailers(1) |
2 | ========================= | |
3 | ||
4 | NAME | |
5 | ---- | |
a34dca24 | 6 | git-interpret-trailers - Add or parse structured information in commit messages |
dfd66ddf CC |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
de613050 RD |
11 | 'git interpret-trailers' [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...] |
12 | 'git interpret-trailers' [<options>] [--parse] [<file>...] | |
dfd66ddf CC |
13 | |
14 | DESCRIPTION | |
15 | ----------- | |
99e09daf | 16 | Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail |
dfd66ddf CC |
17 | headers, at the end of the otherwise free-form part of a commit |
18 | message. | |
19 | ||
20 | This command reads some patches or commit messages from either the | |
99e09daf JK |
21 | <file> arguments or the standard input if no <file> is specified. If |
22 | `--parse` is specified, the output consists of the parsed trailers. | |
23 | ||
5a0d0c03 | 24 | Otherwise, this command applies the arguments passed using the |
99e09daf JK |
25 | `--trailer` option, if any, to the commit message part of each input |
26 | file. The result is emitted on the standard output. | |
dfd66ddf CC |
27 | |
28 | Some configuration variables control the way the `--trailer` arguments | |
29 | are applied to each commit message and the way any existing trailer in | |
30 | the commit message is changed. They also make it possible to | |
31 | automatically add some trailers. | |
32 | ||
33 | By default, a '<token>=<value>' or '<token>:<value>' argument given | |
34 | using `--trailer` will be appended after the existing trailers only if | |
35 | the last trailer has a different (<token>, <value>) pair (or if there | |
36 | is no existing trailer). The <token> and <value> parts will be trimmed | |
37 | to remove starting and trailing whitespace, and the resulting trimmed | |
38 | <token> and <value> will appear in the message like this: | |
39 | ||
40 | ------------------------------------------------ | |
41 | token: value | |
42 | ------------------------------------------------ | |
43 | ||
44 | This means that the trimmed <token> and <value> will be separated by | |
45 | `': '` (one colon followed by one space). | |
46 | ||
47 | By default the new trailer will appear at the end of all the existing | |
48 | trailers. If there is no existing trailer, the new trailer will appear | |
f745acb0 | 49 | after the commit message part of the output, and, if there is no line |
dfd66ddf CC |
50 | with only spaces at the end of the commit message part, one blank line |
51 | will be added before the new trailer. | |
52 | ||
53 | Existing trailers are extracted from the input message by looking for | |
760f1ad1 | 54 | a group of one or more lines that (i) is all trailers, or (ii) contains at |
df616b19 JT |
55 | least one Git-generated or user-configured trailer and consists of at |
56 | least 25% trailers. | |
14624506 | 57 | The group must be preceded by one or more empty (or whitespace-only) lines. |
dfd66ddf | 58 | The group must either be at the end of the message or be the last |
c188668e JK |
59 | non-whitespace lines before a line that starts with '---' (followed by a |
60 | space or the end of the line). Such three minus signs start the patch | |
1688c9a4 | 61 | part of the message. See also `--no-divider` below. |
dfd66ddf | 62 | |
c463a6b2 | 63 | When reading trailers, there can be whitespaces after the |
dfd66ddf | 64 | token, the separator and the value. There can also be whitespaces |
60ef86a1 JT |
65 | inside the token and the value. The value may be split over multiple lines with |
66 | each subsequent line starting with whitespace, like the "folding" in RFC 822. | |
dfd66ddf CC |
67 | |
68 | Note that 'trailers' do not follow and are not intended to follow many | |
60ef86a1 JT |
69 | rules for RFC 822 headers. For example they do not follow |
70 | the encoding rules and probably many other rules. | |
dfd66ddf CC |
71 | |
72 | OPTIONS | |
73 | ------- | |
e1f89863 TK |
74 | --in-place:: |
75 | Edit the files in place. | |
76 | ||
dfd66ddf CC |
77 | --trim-empty:: |
78 | If the <value> part of any trailer contains only whitespace, | |
79 | the whole trailer will be removed from the resulting message. | |
a43eb67e | 80 | This applies to existing trailers as well as new trailers. |
dfd66ddf CC |
81 | |
82 | --trailer <token>[(=|:)<value>]:: | |
83 | Specify a (<token>, <value>) pair that should be applied as a | |
84 | trailer to the input messages. See the description of this | |
85 | command. | |
86 | ||
0ea5292e PB |
87 | --where <placement>:: |
88 | --no-where:: | |
89 | Specify where all new trailers will be added. A setting | |
90 | provided with '--where' overrides all configuration variables | |
91 | and applies to all '--trailer' options until the next occurrence of | |
1e83b9bf SB |
92 | '--where' or '--no-where'. Possible values are `after`, `before`, |
93 | `end` or `start`. | |
0ea5292e PB |
94 | |
95 | --if-exists <action>:: | |
96 | --no-if-exists:: | |
97 | Specify what action will be performed when there is already at | |
98 | least one trailer with the same <token> in the message. A setting | |
99 | provided with '--if-exists' overrides all configuration variables | |
100 | and applies to all '--trailer' options until the next occurrence of | |
1e83b9bf SB |
101 | '--if-exists' or '--no-if-exists'. Possible actions are `addIfDifferent`, |
102 | `addIfDifferentNeighbor`, `add`, `replace` and `doNothing`. | |
0ea5292e PB |
103 | |
104 | --if-missing <action>:: | |
105 | --no-if-missing:: | |
106 | Specify what action will be performed when there is no other | |
107 | trailer with the same <token> in the message. A setting | |
108 | provided with '--if-missing' overrides all configuration variables | |
109 | and applies to all '--trailer' options until the next occurrence of | |
1e83b9bf SB |
110 | '--if-missing' or '--no-if-missing'. Possible actions are `doNothing` |
111 | or `add`. | |
0ea5292e | 112 | |
56c493ed JK |
113 | --only-trailers:: |
114 | Output only the trailers, not any other parts of the input. | |
115 | ||
fdbdb64f JK |
116 | --only-input:: |
117 | Output only trailers that exist in the input; do not add any | |
118 | from the command-line or by following configured `trailer.*` | |
119 | rules. | |
120 | ||
00002396 JK |
121 | --unfold:: |
122 | Remove any whitespace-continuation in trailers, so that each | |
123 | trailer appears on a line by itself with its full content. | |
124 | ||
99e09daf JK |
125 | --parse:: |
126 | A convenience alias for `--only-trailers --only-input | |
127 | --unfold`. | |
128 | ||
1688c9a4 JK |
129 | --no-divider:: |
130 | Do not treat `---` as the end of the commit message. Use this | |
131 | when you know your input contains just the commit message itself | |
132 | (and not an email or the output of `git format-patch`). | |
133 | ||
dfd66ddf CC |
134 | CONFIGURATION VARIABLES |
135 | ----------------------- | |
136 | ||
137 | trailer.separators:: | |
138 | This option tells which characters are recognized as trailer | |
139 | separators. By default only ':' is recognized as a trailer | |
140 | separator, except that '=' is always accepted on the command | |
141 | line for compatibility with other git commands. | |
142 | + | |
143 | The first character given by this option will be the default character | |
144 | used when another separator is not specified in the config for this | |
145 | trailer. | |
146 | + | |
147 | For example, if the value for this option is "%=$", then only lines | |
148 | using the format '<token><sep><value>' with <sep> containing '%', '=' | |
149 | or '$' and then spaces will be considered trailers. And '%' will be | |
150 | the default separator used, so by default trailers will appear like: | |
151 | '<token>% <value>' (one percent sign and one space will appear between | |
152 | the token and the value). | |
153 | ||
154 | trailer.where:: | |
155 | This option tells where a new trailer will be added. | |
156 | + | |
157 | This can be `end`, which is the default, `start`, `after` or `before`. | |
158 | + | |
159 | If it is `end`, then each new trailer will appear at the end of the | |
160 | existing trailers. | |
161 | + | |
162 | If it is `start`, then each new trailer will appear at the start, | |
163 | instead of the end, of the existing trailers. | |
164 | + | |
165 | If it is `after`, then each new trailer will appear just after the | |
166 | last trailer with the same <token>. | |
167 | + | |
168 | If it is `before`, then each new trailer will appear just before the | |
169 | first trailer with the same <token>. | |
170 | ||
171 | trailer.ifexists:: | |
172 | This option makes it possible to choose what action will be | |
173 | performed when there is already at least one trailer with the | |
174 | same <token> in the message. | |
175 | + | |
176 | The valid values for this option are: `addIfDifferentNeighbor` (this | |
b275da81 | 177 | is the default), `addIfDifferent`, `add`, `replace` or `doNothing`. |
dfd66ddf CC |
178 | + |
179 | With `addIfDifferentNeighbor`, a new trailer will be added only if no | |
180 | trailer with the same (<token>, <value>) pair is above or below the line | |
181 | where the new trailer will be added. | |
182 | + | |
183 | With `addIfDifferent`, a new trailer will be added only if no trailer | |
184 | with the same (<token>, <value>) pair is already in the message. | |
185 | + | |
186 | With `add`, a new trailer will be added, even if some trailers with | |
187 | the same (<token>, <value>) pair are already in the message. | |
188 | + | |
189 | With `replace`, an existing trailer with the same <token> will be | |
190 | deleted and the new trailer will be added. The deleted trailer will be | |
191 | the closest one (with the same <token>) to the place where the new one | |
192 | will be added. | |
193 | + | |
194 | With `doNothing`, nothing will be done; that is no new trailer will be | |
195 | added if there is already one with the same <token> in the message. | |
196 | ||
197 | trailer.ifmissing:: | |
198 | This option makes it possible to choose what action will be | |
199 | performed when there is not yet any trailer with the same | |
200 | <token> in the message. | |
201 | + | |
202 | The valid values for this option are: `add` (this is the default) and | |
203 | `doNothing`. | |
204 | + | |
205 | With `add`, a new trailer will be added. | |
206 | + | |
207 | With `doNothing`, nothing will be done. | |
208 | ||
209 | trailer.<token>.key:: | |
210 | This `key` will be used instead of <token> in the trailer. At | |
211 | the end of this key, a separator can appear and then some | |
212 | space characters. By default the only valid separator is ':', | |
213 | but this can be changed using the `trailer.separators` config | |
214 | variable. | |
215 | + | |
216 | If there is a separator, then the key will be used instead of both the | |
217 | <token> and the default separator when adding the trailer. | |
218 | ||
219 | trailer.<token>.where:: | |
220 | This option takes the same values as the 'trailer.where' | |
221 | configuration variable and it overrides what is specified by | |
222 | that option for trailers with the specified <token>. | |
223 | ||
c88bf543 PB |
224 | trailer.<token>.ifexists:: |
225 | This option takes the same values as the 'trailer.ifexists' | |
dfd66ddf CC |
226 | configuration variable and it overrides what is specified by |
227 | that option for trailers with the specified <token>. | |
228 | ||
229 | trailer.<token>.ifmissing:: | |
230 | This option takes the same values as the 'trailer.ifmissing' | |
231 | configuration variable and it overrides what is specified by | |
232 | that option for trailers with the specified <token>. | |
233 | ||
234 | trailer.<token>.command:: | |
235 | This option can be used to specify a shell command that will | |
236 | be called to automatically add or modify a trailer with the | |
237 | specified <token>. | |
238 | + | |
239 | When this option is specified, the behavior is as if a special | |
240 | '<token>=<value>' argument were added at the beginning of the command | |
241 | line, where <value> is taken to be the standard output of the | |
242 | specified command with any leading and trailing whitespace trimmed | |
243 | off. | |
244 | + | |
245 | If the command contains the `$ARG` string, this string will be | |
246 | replaced with the <value> part of an existing trailer with the same | |
247 | <token>, if any, before the command is launched. | |
248 | + | |
249 | If some '<token>=<value>' arguments are also passed on the command | |
250 | line, when a 'trailer.<token>.command' is configured, the command will | |
251 | also be executed for each of these arguments. And the <value> part of | |
252 | these arguments, if any, will be used to replace the `$ARG` string in | |
253 | the command. | |
254 | ||
255 | EXAMPLES | |
256 | -------- | |
257 | ||
258 | * Configure a 'sign' trailer with a 'Signed-off-by' key, and then | |
259 | add two of these trailers to a message: | |
260 | + | |
261 | ------------ | |
262 | $ git config trailer.sign.key "Signed-off-by" | |
263 | $ cat msg.txt | |
264 | subject | |
265 | ||
266 | message | |
267 | $ cat msg.txt | git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' | |
268 | subject | |
269 | ||
270 | message | |
271 | ||
272 | Signed-off-by: Alice <alice@example.com> | |
273 | Signed-off-by: Bob <bob@example.com> | |
274 | ------------ | |
275 | ||
bcf9626a | 276 | * Use the `--in-place` option to edit a message file in place: |
e1f89863 TK |
277 | + |
278 | ------------ | |
279 | $ cat msg.txt | |
280 | subject | |
281 | ||
282 | message | |
283 | ||
284 | Signed-off-by: Bob <bob@example.com> | |
285 | $ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt | |
286 | $ cat msg.txt | |
287 | subject | |
288 | ||
289 | message | |
290 | ||
291 | Signed-off-by: Bob <bob@example.com> | |
292 | Acked-by: Alice <alice@example.com> | |
293 | ------------ | |
294 | ||
dfd66ddf CC |
295 | * Extract the last commit as a patch, and add a 'Cc' and a |
296 | 'Reviewed-by' trailer to it: | |
297 | + | |
298 | ------------ | |
299 | $ git format-patch -1 | |
300 | 0001-foo.patch | |
301 | $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Reviewed-by: Bob <bob@example.com>' 0001-foo.patch >0001-bar.patch | |
302 | ------------ | |
303 | ||
304 | * Configure a 'sign' trailer with a command to automatically add a | |
305 | 'Signed-off-by: ' with the author information only if there is no | |
306 | 'Signed-off-by: ' already, and show how it works: | |
307 | + | |
308 | ------------ | |
309 | $ git config trailer.sign.key "Signed-off-by: " | |
310 | $ git config trailer.sign.ifmissing add | |
311 | $ git config trailer.sign.ifexists doNothing | |
312 | $ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"' | |
313 | $ git interpret-trailers <<EOF | |
314 | > EOF | |
315 | ||
316 | Signed-off-by: Bob <bob@example.com> | |
317 | $ git interpret-trailers <<EOF | |
318 | > Signed-off-by: Alice <alice@example.com> | |
319 | > EOF | |
320 | ||
321 | Signed-off-by: Alice <alice@example.com> | |
322 | ------------ | |
323 | ||
324 | * Configure a 'fix' trailer with a key that contains a '#' and no | |
325 | space after this character, and show how it works: | |
326 | + | |
327 | ------------ | |
328 | $ git config trailer.separators ":#" | |
329 | $ git config trailer.fix.key "Fix #" | |
330 | $ echo "subject" | git interpret-trailers --trailer fix=42 | |
331 | subject | |
332 | ||
333 | Fix #42 | |
334 | ------------ | |
335 | ||
336 | * Configure a 'see' trailer with a command to show the subject of a | |
337 | commit that is related, and show how it works: | |
338 | + | |
339 | ------------ | |
340 | $ git config trailer.see.key "See-also: " | |
341 | $ git config trailer.see.ifExists "replace" | |
342 | $ git config trailer.see.ifMissing "doNothing" | |
343 | $ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG" | |
344 | $ git interpret-trailers <<EOF | |
345 | > subject | |
346 | > | |
347 | > message | |
348 | > | |
349 | > see: HEAD~2 | |
350 | > EOF | |
351 | subject | |
352 | ||
353 | message | |
354 | ||
355 | See-also: fe3187489d69c4 (subject of related commit) | |
356 | ------------ | |
357 | ||
358 | * Configure a commit template with some trailers with empty values | |
359 | (using sed to show and keep the trailing spaces at the end of the | |
360 | trailers), then configure a commit-msg hook that uses | |
361 | 'git interpret-trailers' to remove trailers with empty values and | |
362 | to add a 'git-version' trailer: | |
363 | + | |
364 | ------------ | |
365 | $ sed -e 's/ Z$/ /' >commit_template.txt <<EOF | |
366 | > ***subject*** | |
367 | > | |
368 | > ***message*** | |
369 | > | |
370 | > Fixes: Z | |
371 | > Cc: Z | |
372 | > Reviewed-by: Z | |
373 | > Signed-off-by: Z | |
374 | > EOF | |
375 | $ git config commit.template commit_template.txt | |
376 | $ cat >.git/hooks/commit-msg <<EOF | |
377 | > #!/bin/sh | |
378 | > git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new" | |
379 | > mv "\$1.new" "\$1" | |
380 | > EOF | |
381 | $ chmod +x .git/hooks/commit-msg | |
382 | ------------ | |
383 | ||
384 | SEE ALSO | |
385 | -------- | |
386 | linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1] | |
387 | ||
388 | GIT | |
389 | --- | |
390 | Part of the linkgit:git[1] suite |