]>
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] | |
d9054a19 ÆAB |
11 | 'git interpret-trailers' [--in-place] [--trim-empty] |
12 | [(--trailer <token>[(=|:)<value>])...] | |
13 | [--parse] [<file>...] | |
dfd66ddf CC |
14 | |
15 | DESCRIPTION | |
16 | ----------- | |
00432a36 | 17 | Add or parse 'trailer' lines that look similar to RFC 822 e-mail |
dfd66ddf | 18 | headers, at the end of the otherwise free-form part of a commit |
d57fa7fc LA |
19 | message. For example, in the following commit message |
20 | ||
21 | ------------------------------------------------ | |
22 | subject | |
23 | ||
24 | Lorem ipsum dolor sit amet, consectetur adipiscing elit. | |
25 | ||
26 | Signed-off-by: Alice <alice@example.com> | |
27 | Signed-off-by: Bob <bob@example.com> | |
28 | ------------------------------------------------ | |
29 | ||
30 | the last two lines starting with "Signed-off-by" are trailers. | |
dfd66ddf | 31 | |
94f15fe5 LA |
32 | This command reads commit messages from either the |
33 | <file> arguments or the standard input if no <file> is specified. | |
34 | If `--parse` is specified, the output consists of the parsed trailers. | |
5a0d0c03 | 35 | Otherwise, this command applies the arguments passed using the |
94f15fe5 LA |
36 | `--trailer` option, if any, to each input file. The result is emitted on the |
37 | standard output. | |
38 | ||
39 | This command can also operate on the output of linkgit:git-format-patch[1], | |
40 | which is more elaborate than a plain commit message. Namely, such output | |
41 | includes a commit message (as above), a "---" divider line, and a patch part. | |
42 | For these inputs, the divider and patch parts are not modified by | |
43 | this command and are emitted as is on the output, unless | |
44 | `--no-divider` is specified. | |
dfd66ddf CC |
45 | |
46 | Some configuration variables control the way the `--trailer` arguments | |
94f15fe5 LA |
47 | are applied to each input and the way any existing trailer in |
48 | the input is changed. They also make it possible to | |
dfd66ddf CC |
49 | automatically add some trailers. |
50 | ||
51 | By default, a '<token>=<value>' or '<token>:<value>' argument given | |
52 | using `--trailer` will be appended after the existing trailers only if | |
53 | the last trailer has a different (<token>, <value>) pair (or if there | |
54 | is no existing trailer). The <token> and <value> parts will be trimmed | |
55 | to remove starting and trailing whitespace, and the resulting trimmed | |
94f15fe5 | 56 | <token> and <value> will appear in the output like this: |
dfd66ddf CC |
57 | |
58 | ------------------------------------------------ | |
59 | token: value | |
60 | ------------------------------------------------ | |
61 | ||
62 | This means that the trimmed <token> and <value> will be separated by | |
eda2c44c LA |
63 | `': '` (one colon followed by one space). For convenience, the <token> can be a |
64 | shortened string key (e.g., "sign") instead of the full string which should | |
65 | appear before the separator on the output (e.g., "Signed-off-by"). This can be | |
66 | configured using the 'trailer.<token>.key' configuration variable. | |
dfd66ddf CC |
67 | |
68 | By default the new trailer will appear at the end of all the existing | |
69 | trailers. If there is no existing trailer, the new trailer will appear | |
94f15fe5 LA |
70 | at the end of the input. A blank line will be added before the new |
71 | trailer if there isn't one already. | |
dfd66ddf | 72 | |
94f15fe5 | 73 | Existing trailers are extracted from the input by looking for |
760f1ad1 | 74 | a group of one or more lines that (i) is all trailers, or (ii) contains at |
df616b19 JT |
75 | least one Git-generated or user-configured trailer and consists of at |
76 | least 25% trailers. | |
14624506 | 77 | The group must be preceded by one or more empty (or whitespace-only) lines. |
94f15fe5 | 78 | The group must either be at the end of the input or be the last |
c188668e | 79 | non-whitespace lines before a line that starts with '---' (followed by a |
94f15fe5 | 80 | space or the end of the line). |
dfd66ddf | 81 | |
b46dd172 | 82 | When reading trailers, there can be no whitespace before or inside the |
8e80f291 LA |
83 | <token>, but any number of regular space and tab characters are allowed |
84 | between the <token> and the separator. There can be whitespaces before, | |
85 | inside or after the <value>. The <value> may be split over multiple lines | |
b46dd172 | 86 | with each subsequent line starting with at least one whitespace, like |
d57fa7fc LA |
87 | the "folding" in RFC 822. Example: |
88 | ||
89 | ------------------------------------------------ | |
90 | token: This is a very long value, with spaces and | |
91 | newlines in it. | |
92 | ------------------------------------------------ | |
dfd66ddf | 93 | |
74a50fbd LA |
94 | Note that trailers do not follow (nor are they intended to follow) many of the |
95 | rules for RFC 822 headers. For example they do not follow the encoding rule. | |
dfd66ddf CC |
96 | |
97 | OPTIONS | |
98 | ------- | |
e1f89863 TK |
99 | --in-place:: |
100 | Edit the files in place. | |
101 | ||
dfd66ddf CC |
102 | --trim-empty:: |
103 | If the <value> part of any trailer contains only whitespace, | |
229d6ab6 | 104 | the whole trailer will be removed from the output. |
a43eb67e | 105 | This applies to existing trailers as well as new trailers. |
dfd66ddf CC |
106 | |
107 | --trailer <token>[(=|:)<value>]:: | |
108 | Specify a (<token>, <value>) pair that should be applied as a | |
229d6ab6 | 109 | trailer to the inputs. See the description of this |
dfd66ddf CC |
110 | command. |
111 | ||
0ea5292e PB |
112 | --where <placement>:: |
113 | --no-where:: | |
114 | Specify where all new trailers will be added. A setting | |
115 | provided with '--where' overrides all configuration variables | |
116 | and applies to all '--trailer' options until the next occurrence of | |
1e83b9bf SB |
117 | '--where' or '--no-where'. Possible values are `after`, `before`, |
118 | `end` or `start`. | |
0ea5292e PB |
119 | |
120 | --if-exists <action>:: | |
121 | --no-if-exists:: | |
122 | Specify what action will be performed when there is already at | |
229d6ab6 | 123 | least one trailer with the same <token> in the input. A setting |
0ea5292e PB |
124 | provided with '--if-exists' overrides all configuration variables |
125 | and applies to all '--trailer' options until the next occurrence of | |
1e83b9bf SB |
126 | '--if-exists' or '--no-if-exists'. Possible actions are `addIfDifferent`, |
127 | `addIfDifferentNeighbor`, `add`, `replace` and `doNothing`. | |
0ea5292e PB |
128 | |
129 | --if-missing <action>:: | |
130 | --no-if-missing:: | |
131 | Specify what action will be performed when there is no other | |
229d6ab6 | 132 | trailer with the same <token> in the input. A setting |
0ea5292e PB |
133 | provided with '--if-missing' overrides all configuration variables |
134 | and applies to all '--trailer' options until the next occurrence of | |
1e83b9bf SB |
135 | '--if-missing' or '--no-if-missing'. Possible actions are `doNothing` |
136 | or `add`. | |
0ea5292e | 137 | |
56c493ed JK |
138 | --only-trailers:: |
139 | Output only the trailers, not any other parts of the input. | |
140 | ||
fdbdb64f JK |
141 | --only-input:: |
142 | Output only trailers that exist in the input; do not add any | |
143 | from the command-line or by following configured `trailer.*` | |
144 | rules. | |
145 | ||
00002396 JK |
146 | --unfold:: |
147 | Remove any whitespace-continuation in trailers, so that each | |
148 | trailer appears on a line by itself with its full content. | |
149 | ||
99e09daf JK |
150 | --parse:: |
151 | A convenience alias for `--only-trailers --only-input | |
152 | --unfold`. | |
153 | ||
1688c9a4 JK |
154 | --no-divider:: |
155 | Do not treat `---` as the end of the commit message. Use this | |
156 | when you know your input contains just the commit message itself | |
157 | (and not an email or the output of `git format-patch`). | |
158 | ||
dfd66ddf CC |
159 | CONFIGURATION VARIABLES |
160 | ----------------------- | |
161 | ||
162 | trailer.separators:: | |
163 | This option tells which characters are recognized as trailer | |
164 | separators. By default only ':' is recognized as a trailer | |
165 | separator, except that '=' is always accepted on the command | |
166 | line for compatibility with other git commands. | |
167 | + | |
168 | The first character given by this option will be the default character | |
169 | used when another separator is not specified in the config for this | |
170 | trailer. | |
171 | + | |
172 | For example, if the value for this option is "%=$", then only lines | |
173 | using the format '<token><sep><value>' with <sep> containing '%', '=' | |
174 | or '$' and then spaces will be considered trailers. And '%' will be | |
175 | the default separator used, so by default trailers will appear like: | |
176 | '<token>% <value>' (one percent sign and one space will appear between | |
177 | the token and the value). | |
178 | ||
179 | trailer.where:: | |
180 | This option tells where a new trailer will be added. | |
181 | + | |
182 | This can be `end`, which is the default, `start`, `after` or `before`. | |
183 | + | |
184 | If it is `end`, then each new trailer will appear at the end of the | |
185 | existing trailers. | |
186 | + | |
187 | If it is `start`, then each new trailer will appear at the start, | |
188 | instead of the end, of the existing trailers. | |
189 | + | |
190 | If it is `after`, then each new trailer will appear just after the | |
191 | last trailer with the same <token>. | |
192 | + | |
193 | If it is `before`, then each new trailer will appear just before the | |
194 | first trailer with the same <token>. | |
195 | ||
196 | trailer.ifexists:: | |
197 | This option makes it possible to choose what action will be | |
198 | performed when there is already at least one trailer with the | |
229d6ab6 | 199 | same <token> in the input. |
dfd66ddf CC |
200 | + |
201 | The valid values for this option are: `addIfDifferentNeighbor` (this | |
b275da81 | 202 | is the default), `addIfDifferent`, `add`, `replace` or `doNothing`. |
dfd66ddf CC |
203 | + |
204 | With `addIfDifferentNeighbor`, a new trailer will be added only if no | |
205 | trailer with the same (<token>, <value>) pair is above or below the line | |
206 | where the new trailer will be added. | |
207 | + | |
208 | With `addIfDifferent`, a new trailer will be added only if no trailer | |
229d6ab6 | 209 | with the same (<token>, <value>) pair is already in the input. |
dfd66ddf CC |
210 | + |
211 | With `add`, a new trailer will be added, even if some trailers with | |
229d6ab6 | 212 | the same (<token>, <value>) pair are already in the input. |
dfd66ddf CC |
213 | + |
214 | With `replace`, an existing trailer with the same <token> will be | |
215 | deleted and the new trailer will be added. The deleted trailer will be | |
216 | the closest one (with the same <token>) to the place where the new one | |
217 | will be added. | |
218 | + | |
219 | With `doNothing`, nothing will be done; that is no new trailer will be | |
229d6ab6 | 220 | added if there is already one with the same <token> in the input. |
dfd66ddf CC |
221 | |
222 | trailer.ifmissing:: | |
223 | This option makes it possible to choose what action will be | |
224 | performed when there is not yet any trailer with the same | |
229d6ab6 | 225 | <token> in the input. |
dfd66ddf CC |
226 | + |
227 | The valid values for this option are: `add` (this is the default) and | |
228 | `doNothing`. | |
229 | + | |
230 | With `add`, a new trailer will be added. | |
231 | + | |
232 | With `doNothing`, nothing will be done. | |
233 | ||
234 | trailer.<token>.key:: | |
235 | This `key` will be used instead of <token> in the trailer. At | |
236 | the end of this key, a separator can appear and then some | |
237 | space characters. By default the only valid separator is ':', | |
238 | but this can be changed using the `trailer.separators` config | |
239 | variable. | |
240 | + | |
241 | If there is a separator, then the key will be used instead of both the | |
242 | <token> and the default separator when adding the trailer. | |
243 | ||
244 | trailer.<token>.where:: | |
245 | This option takes the same values as the 'trailer.where' | |
246 | configuration variable and it overrides what is specified by | |
247 | that option for trailers with the specified <token>. | |
248 | ||
c88bf543 PB |
249 | trailer.<token>.ifexists:: |
250 | This option takes the same values as the 'trailer.ifexists' | |
dfd66ddf CC |
251 | configuration variable and it overrides what is specified by |
252 | that option for trailers with the specified <token>. | |
253 | ||
254 | trailer.<token>.ifmissing:: | |
255 | This option takes the same values as the 'trailer.ifmissing' | |
256 | configuration variable and it overrides what is specified by | |
257 | that option for trailers with the specified <token>. | |
258 | ||
259 | trailer.<token>.command:: | |
dc8937fb | 260 | Deprecated in favor of 'trailer.<token>.cmd'. |
c364b7ef ZH |
261 | This option behaves in the same way as 'trailer.<token>.cmd', except |
262 | that it doesn't pass anything as argument to the specified command. | |
263 | Instead the first occurrence of substring $ARG is replaced by the | |
8e80f291 | 264 | <value> that would be passed as argument. |
c364b7ef | 265 | + |
dc8937fb | 266 | Note that $ARG in the user's command is |
c364b7ef ZH |
267 | only replaced once and that the original way of replacing $ARG is not safe. |
268 | + | |
269 | When both 'trailer.<token>.cmd' and 'trailer.<token>.command' are given | |
270 | for the same <token>, 'trailer.<token>.cmd' is used and | |
271 | 'trailer.<token>.command' is ignored. | |
272 | ||
273 | trailer.<token>.cmd:: | |
bfb5f57b | 274 | This option can be used to specify a shell command that will be called |
57dcb657 | 275 | once to automatically add a trailer with the specified <token>, and then |
bfb5f57b LA |
276 | called each time a '--trailer <token>=<value>' argument is specified to |
277 | modify the <value> of the trailer that this option would produce. | |
dfd66ddf | 278 | + |
57dcb657 ZH |
279 | When the specified command is first called to add a trailer |
280 | with the specified <token>, the behavior is as if a special | |
281 | '--trailer <token>=<value>' argument was added at the beginning | |
282 | of the "git interpret-trailers" command, where <value> | |
283 | is taken to be the standard output of the command with any | |
284 | leading and trailing whitespace trimmed off. | |
dfd66ddf | 285 | + |
57dcb657 ZH |
286 | If some '--trailer <token>=<value>' arguments are also passed |
287 | on the command line, the command is called again once for each | |
288 | of these arguments with the same <token>. And the <value> part | |
c364b7ef ZH |
289 | of these arguments, if any, will be passed to the command as its |
290 | first argument. This way the command can produce a <value> computed | |
291 | from the <value> passed in the '--trailer <token>=<value>' argument. | |
dfd66ddf CC |
292 | |
293 | EXAMPLES | |
294 | -------- | |
295 | ||
296 | * Configure a 'sign' trailer with a 'Signed-off-by' key, and then | |
229d6ab6 | 297 | add two of these trailers to a commit message file: |
dfd66ddf CC |
298 | + |
299 | ------------ | |
300 | $ git config trailer.sign.key "Signed-off-by" | |
301 | $ cat msg.txt | |
302 | subject | |
303 | ||
229d6ab6 | 304 | body text |
b032a2bf | 305 | $ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt |
dfd66ddf CC |
306 | subject |
307 | ||
229d6ab6 | 308 | body text |
dfd66ddf CC |
309 | |
310 | Signed-off-by: Alice <alice@example.com> | |
311 | Signed-off-by: Bob <bob@example.com> | |
312 | ------------ | |
313 | ||
229d6ab6 | 314 | * Use the `--in-place` option to edit a commit message file in place: |
e1f89863 TK |
315 | + |
316 | ------------ | |
317 | $ cat msg.txt | |
318 | subject | |
319 | ||
229d6ab6 | 320 | body text |
e1f89863 TK |
321 | |
322 | Signed-off-by: Bob <bob@example.com> | |
323 | $ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt | |
324 | $ cat msg.txt | |
325 | subject | |
326 | ||
229d6ab6 | 327 | body text |
e1f89863 TK |
328 | |
329 | Signed-off-by: Bob <bob@example.com> | |
330 | Acked-by: Alice <alice@example.com> | |
331 | ------------ | |
332 | ||
dfd66ddf CC |
333 | * Extract the last commit as a patch, and add a 'Cc' and a |
334 | 'Reviewed-by' trailer to it: | |
335 | + | |
336 | ------------ | |
337 | $ git format-patch -1 | |
338 | 0001-foo.patch | |
339 | $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Reviewed-by: Bob <bob@example.com>' 0001-foo.patch >0001-bar.patch | |
340 | ------------ | |
341 | ||
342 | * Configure a 'sign' trailer with a command to automatically add a | |
343 | 'Signed-off-by: ' with the author information only if there is no | |
344 | 'Signed-off-by: ' already, and show how it works: | |
345 | + | |
346 | ------------ | |
cbb83dae KH |
347 | $ cat msg1.txt |
348 | subject | |
349 | ||
229d6ab6 | 350 | body text |
dfd66ddf CC |
351 | $ git config trailer.sign.key "Signed-off-by: " |
352 | $ git config trailer.sign.ifmissing add | |
353 | $ git config trailer.sign.ifexists doNothing | |
f68c2687 | 354 | $ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"' |
cbb83dae KH |
355 | $ git interpret-trailers --trailer sign <msg1.txt |
356 | subject | |
357 | ||
229d6ab6 | 358 | body text |
dfd66ddf CC |
359 | |
360 | Signed-off-by: Bob <bob@example.com> | |
cbb83dae KH |
361 | $ cat msg2.txt |
362 | subject | |
363 | ||
229d6ab6 | 364 | body text |
cbb83dae | 365 | |
c892bcc9 | 366 | Signed-off-by: Alice <alice@example.com> |
cbb83dae KH |
367 | $ git interpret-trailers --trailer sign <msg2.txt |
368 | subject | |
369 | ||
229d6ab6 | 370 | body text |
dfd66ddf CC |
371 | |
372 | Signed-off-by: Alice <alice@example.com> | |
373 | ------------ | |
374 | ||
375 | * Configure a 'fix' trailer with a key that contains a '#' and no | |
376 | space after this character, and show how it works: | |
377 | + | |
378 | ------------ | |
379 | $ git config trailer.separators ":#" | |
380 | $ git config trailer.fix.key "Fix #" | |
381 | $ echo "subject" | git interpret-trailers --trailer fix=42 | |
382 | subject | |
383 | ||
384 | Fix #42 | |
385 | ------------ | |
386 | ||
c364b7ef ZH |
387 | * Configure a 'help' trailer with a cmd use a script `glog-find-author` |
388 | which search specified author identity from git log in git repository | |
389 | and show how it works: | |
390 | + | |
391 | ------------ | |
392 | $ cat ~/bin/glog-find-author | |
393 | #!/bin/sh | |
394 | test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true | |
c892bcc9 KH |
395 | $ cat msg.txt |
396 | subject | |
397 | ||
229d6ab6 | 398 | body text |
c364b7ef ZH |
399 | $ git config trailer.help.key "Helped-by: " |
400 | $ git config trailer.help.ifExists "addIfDifferentNeighbor" | |
401 | $ git config trailer.help.cmd "~/bin/glog-find-author" | |
c892bcc9 | 402 | $ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt |
c364b7ef ZH |
403 | subject |
404 | ||
229d6ab6 | 405 | body text |
c364b7ef ZH |
406 | |
407 | Helped-by: Junio C Hamano <gitster@pobox.com> | |
408 | Helped-by: Christian Couder <christian.couder@gmail.com> | |
409 | ------------ | |
410 | ||
411 | * Configure a 'ref' trailer with a cmd use a script `glog-grep` | |
412 | to grep last relevant commit from git log in the git repository | |
413 | and show how it works: | |
414 | + | |
415 | ------------ | |
416 | $ cat ~/bin/glog-grep | |
417 | #!/bin/sh | |
418 | test -n "$1" && git log --grep "$1" --pretty=reference -1 || true | |
c892bcc9 KH |
419 | $ cat msg.txt |
420 | subject | |
421 | ||
229d6ab6 | 422 | body text |
c364b7ef ZH |
423 | $ git config trailer.ref.key "Reference-to: " |
424 | $ git config trailer.ref.ifExists "replace" | |
425 | $ git config trailer.ref.cmd "~/bin/glog-grep" | |
c892bcc9 | 426 | $ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt |
c364b7ef ZH |
427 | subject |
428 | ||
229d6ab6 | 429 | body text |
c364b7ef ZH |
430 | |
431 | Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07) | |
432 | ------------ | |
433 | ||
dfd66ddf CC |
434 | * Configure a 'see' trailer with a command to show the subject of a |
435 | commit that is related, and show how it works: | |
436 | + | |
437 | ------------ | |
c892bcc9 KH |
438 | $ cat msg.txt |
439 | subject | |
440 | ||
229d6ab6 | 441 | body text |
c892bcc9 KH |
442 | |
443 | see: HEAD~2 | |
f68c2687 KH |
444 | $ cat ~/bin/glog-ref |
445 | #!/bin/sh | |
446 | git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14 | |
dfd66ddf CC |
447 | $ git config trailer.see.key "See-also: " |
448 | $ git config trailer.see.ifExists "replace" | |
449 | $ git config trailer.see.ifMissing "doNothing" | |
f68c2687 KH |
450 | $ git config trailer.see.cmd "glog-ref" |
451 | $ git interpret-trailers --trailer=see <msg.txt | |
dfd66ddf CC |
452 | subject |
453 | ||
229d6ab6 | 454 | body text |
dfd66ddf CC |
455 | |
456 | See-also: fe3187489d69c4 (subject of related commit) | |
457 | ------------ | |
458 | ||
459 | * Configure a commit template with some trailers with empty values | |
460 | (using sed to show and keep the trailing spaces at the end of the | |
461 | trailers), then configure a commit-msg hook that uses | |
462 | 'git interpret-trailers' to remove trailers with empty values and | |
463 | to add a 'git-version' trailer: | |
464 | + | |
465 | ------------ | |
c892bcc9 KH |
466 | $ cat temp.txt |
467 | ***subject*** | |
468 | ||
469 | ***message*** | |
470 | ||
471 | Fixes: Z | |
472 | Cc: Z | |
473 | Reviewed-by: Z | |
474 | Signed-off-by: Z | |
475 | $ sed -e 's/ Z$/ /' temp.txt > commit_template.txt | |
dfd66ddf | 476 | $ git config commit.template commit_template.txt |
c892bcc9 KH |
477 | $ cat .git/hooks/commit-msg |
478 | #!/bin/sh | |
479 | git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new" | |
480 | mv "\$1.new" "\$1" | |
dfd66ddf CC |
481 | $ chmod +x .git/hooks/commit-msg |
482 | ------------ | |
483 | ||
484 | SEE ALSO | |
485 | -------- | |
486 | linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1] | |
487 | ||
488 | GIT | |
489 | --- | |
490 | Part of the linkgit:git[1] suite |