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