man1/git-interpret-trailers.1

   1 '\" t
   2 .\"     Title: git-interpret-trailers
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2024-02-13
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.44.0.rc1
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-INTERPRET\-TRAILERS" "1" "2024\-02\-13" "Git 2\&.44\&.0\&.rc1" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-interpret-trailers \- Add or parse structured information in commit messages
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIgit interpret\-trailers\fR [\-\-in\-place] [\-\-trim\-empty]
  36                         [(\-\-trailer (<key>|<keyAlias>)[(=|:)<value>])\&...]
  37                         [\-\-parse] [<file>\&...]
  38 .fi
  39 .sp
  40 .SH "DESCRIPTION"
  41 .sp
  42 Add or parse \fItrailer\fR lines that look similar to RFC 822 e\-mail headers, at the end of the otherwise free\-form part of a commit message\&. For example, in the following commit message
  43 .sp
  44 .if n \{\
  45 .RS 4
  46 .\}
  47 .nf
  48 subject
  49
  50 Lorem ipsum dolor sit amet, consectetur adipiscing elit\&.
  51
  52 Signed\-off\-by: Alice <alice@example\&.com>
  53 Signed\-off\-by: Bob <bob@example\&.com>
  54 .fi
  55 .if n \{\
  56 .RE
  57 .\}
  58 .sp
  59 .sp
  60 the last two lines starting with "Signed\-off\-by" are trailers\&.
  61 .sp
  62 This command reads commit messages from either the <file> arguments or the standard input if no <file> is specified\&. If \fB\-\-parse\fR is specified, the output consists of the parsed trailers coming from the input, without influencing them with any command line options or configuration variables\&.
  63 .sp
  64 Otherwise, this command applies \fBtrailer\&.*\fR configuration variables (which could potentially add new trailers, as well as reposition them), as well as any command line arguments that can override configuration variables (such as \fB\-\-trailer=\&.\&.\&.\fR which could also add new trailers), to each input file\&. The result is emitted on the standard output\&.
  65 .sp
  66 This command can also operate on the output of \fBgit-format-patch\fR(1), which is more elaborate than a plain commit message\&. Namely, such output includes a commit message (as above), a "\-\-\-" divider line, and a patch part\&. For these inputs, the divider and patch parts are not modified by this command and are emitted as is on the output, unless \fB\-\-no\-divider\fR is specified\&.
  67 .sp
  68 Some configuration variables control the way the \fB\-\-trailer\fR arguments are applied to each input and the way any existing trailer in the input is changed\&. They also make it possible to automatically add some trailers\&.
  69 .sp
  70 By default, a \fI<key>=<value>\fR or \fI<key>:<value>\fR argument given using \fB\-\-trailer\fR will be appended after the existing trailers only if the last trailer has a different (<key>, <value>) pair (or if there is no existing trailer)\&. The <key> and <value> parts will be trimmed to remove starting and trailing whitespace, and the resulting trimmed <key> and <value> will appear in the output like this:
  71 .sp
  72 .if n \{\
  73 .RS 4
  74 .\}
  75 .nf
  76 key: value
  77 .fi
  78 .if n \{\
  79 .RE
  80 .\}
  81 .sp
  82 .sp
  83 This means that the trimmed <key> and <value> will be separated by \fB\*(Aq: \*(Aq\fR (one colon followed by one space)\&.
  84 .sp
  85 For convenience, a <keyAlias> can be configured to make using \fB\-\-trailer\fR shorter to type on the command line\&. This can be configured using the \fItrailer\&.<keyAlias>\&.key\fR configuration variable\&. The <keyAlias> must be a prefix of the full <key> string, although case sensitivity does not matter\&. For example, if you have
  86 .sp
  87 .if n \{\
  88 .RS 4
  89 .\}
  90 .nf
  91 trailer\&.sign\&.key "Signed\-off\-by: "
  92 .fi
  93 .if n \{\
  94 .RE
  95 .\}
  96 .sp
  97 .sp
  98 in your configuration, you only need to specify \fB\-\-trailer="sign: foo"\fR on the command line instead of \fB\-\-trailer="Signed\-off\-by: foo"\fR\&.
  99 .sp
 100 By default the new trailer will appear at the end of all the existing trailers\&. If there is no existing trailer, the new trailer will appear at the end of the input\&. A blank line will be added before the new trailer if there isn\(cqt one already\&.
 101 .sp
 102 Existing trailers are extracted from the input by looking for a group of one or more lines that (i) is all trailers, or (ii) contains at least one Git\-generated or user\-configured trailer and consists of at least 25% trailers\&. The group must be preceded by one or more empty (or whitespace\-only) lines\&. The group must either be at the end of the input or be the last non\-whitespace lines before a line that starts with \fI\-\-\-\fR (followed by a space or the end of the line)\&.
 103 .sp
 104 When reading trailers, there can be no whitespace before or inside the <key>, but any number of regular space and tab characters are allowed between the <key> and the separator\&. There can be whitespaces before, inside or after the <value>\&. The <value> may be split over multiple lines with each subsequent line starting with at least one whitespace, like the "folding" in RFC 822\&. Example:
 105 .sp
 106 .if n \{\
 107 .RS 4
 108 .\}
 109 .nf
 110 key: This is a very long value, with spaces and
 111   newlines in it\&.
 112 .fi
 113 .if n \{\
 114 .RE
 115 .\}
 116 .sp
 117 .sp
 118 Note that trailers do not follow (nor are they intended to follow) many of the rules for RFC 822 headers\&. For example they do not follow the encoding rule\&.
 119 .SH "OPTIONS"
 120 .PP
 121 \-\-in\-place
 122 .RS 4
 123 Edit the files in place\&.
 124 .RE
 125 .PP
 126 \-\-trim\-empty
 127 .RS 4
 128 If the <value> part of any trailer contains only whitespace, the whole trailer will be removed from the output\&. This applies to existing trailers as well as new trailers\&.
 129 .RE
 130 .PP
 131 \-\-trailer <key>[(=|:)<value>]
 132 .RS 4
 133 Specify a (<key>, <value>) pair that should be applied as a trailer to the inputs\&. See the description of this command\&.
 134 .RE
 135 .PP
 136 \-\-where <placement>, \-\-no\-where
 137 .RS 4
 138 Specify where all new trailers will be added\&. A setting provided with
 139 \fI\-\-where\fR
 140 overrides the
 141 \fBtrailer\&.where\fR
 142 and any applicable
 143 \fBtrailer\&.<keyAlias>\&.where\fR
 144 configuration variables and applies to all
 145 \fI\-\-trailer\fR
 146 options until the next occurrence of
 147 \fI\-\-where\fR
 148 or
 149 \fI\-\-no\-where\fR\&. Upon encountering
 150 \fI\-\-no\-where\fR, clear the effect of any previous use of
 151 \fI\-\-where\fR, such that the relevant configuration variables are no longer overridden\&. Possible placements are
 152 \fBafter\fR,
 153 \fBbefore\fR,
 154 \fBend\fR
 155 or
 156 \fBstart\fR\&.
 157 .RE
 158 .PP
 159 \-\-if\-exists <action>, \-\-no\-if\-exists
 160 .RS 4
 161 Specify what action will be performed when there is already at least one trailer with the same <key> in the input\&. A setting provided with
 162 \fI\-\-if\-exists\fR
 163 overrides the
 164 \fBtrailer\&.ifExists\fR
 165 and any applicable
 166 \fBtrailer\&.<keyAlias>\&.ifExists\fR
 167 configuration variables and applies to all
 168 \fI\-\-trailer\fR
 169 options until the next occurrence of
 170 \fI\-\-if\-exists\fR
 171 or
 172 \fI\-\-no\-if\-exists\fR\&. Upon encountering \*(Aq\-\-no\-if\-exists, clear the effect of any previous use of \*(Aq\-\-if\-exists, such that the relevant configuration variables are no longer overridden\&. Possible actions are
 173 \fBaddIfDifferent\fR,
 174 \fBaddIfDifferentNeighbor\fR,
 175 \fBadd\fR,
 176 \fBreplace\fR
 177 and
 178 \fBdoNothing\fR\&.
 179 .RE
 180 .PP
 181 \-\-if\-missing <action>, \-\-no\-if\-missing
 182 .RS 4
 183 Specify what action will be performed when there is no other trailer with the same <key> in the input\&. A setting provided with
 184 \fI\-\-if\-missing\fR
 185 overrides the
 186 \fBtrailer\&.ifMissing\fR
 187 and any applicable
 188 \fBtrailer\&.<keyAlias>\&.ifMissing\fR
 189 configuration variables and applies to all
 190 \fI\-\-trailer\fR
 191 options until the next occurrence of
 192 \fI\-\-if\-missing\fR
 193 or
 194 \fI\-\-no\-if\-missing\fR\&. Upon encountering \*(Aq\-\-no\-if\-missing, clear the effect of any previous use of \*(Aq\-\-if\-missing, such that the relevant configuration variables are no longer overridden\&. Possible actions are
 195 \fBdoNothing\fR
 196 or
 197 \fBadd\fR\&.
 198 .RE
 199 .PP
 200 \-\-only\-trailers
 201 .RS 4
 202 Output only the trailers, not any other parts of the input\&.
 203 .RE
 204 .PP
 205 \-\-only\-input
 206 .RS 4
 207 Output only trailers that exist in the input; do not add any from the command\-line or by applying
 208 \fBtrailer\&.*\fR
 209 configuration variables\&.
 210 .RE
 211 .PP
 212 \-\-unfold
 213 .RS 4
 214 If a trailer has a value that runs over multiple lines (aka "folded"), reformat the value into a single line\&.
 215 .RE
 216 .PP
 217 \-\-parse
 218 .RS 4
 219 A convenience alias for
 220 \fB\-\-only\-trailers \-\-only\-input \-\-unfold\fR\&. This makes it easier to only see the trailers coming from the input without influencing them with any command line options or configuration variables, while also making the output machine\-friendly with \-\-unfold\&.
 221 .RE
 222 .PP
 223 \-\-no\-divider
 224 .RS 4
 225 Do not treat
 226 \fB\-\-\-\fR
 227 as the end of the commit message\&. Use this when you know your input contains just the commit message itself (and not an email or the output of
 228 \fBgit format\-patch\fR)\&.
 229 .RE
 230 .SH "CONFIGURATION VARIABLES"
 231 .PP
 232 trailer\&.separators
 233 .RS 4
 234 This option tells which characters are recognized as trailer separators\&. By default only
 235 \fI:\fR
 236 is recognized as a trailer separator, except that
 237 \fI=\fR
 238 is always accepted on the command line for compatibility with other git commands\&.
 239 .sp
 240 The first character given by this option will be the default character used when another separator is not specified in the config for this trailer\&.
 241 .sp
 242 For example, if the value for this option is "%=$", then only lines using the format
 243 \fI<key><sep><value>\fR
 244 with <sep> containing
 245 \fI%\fR,
 246 \fI=\fR
 247 or
 248 \fI$\fR
 249 and then spaces will be considered trailers\&. And
 250 \fI%\fR
 251 will be the default separator used, so by default trailers will appear like:
 252 \fI<key>% <value>\fR
 253 (one percent sign and one space will appear between the key and the value)\&.
 254 .RE
 255 .PP
 256 trailer\&.where
 257 .RS 4
 258 This option tells where a new trailer will be added\&.
 259 .sp
 260 This can be
 261 \fBend\fR, which is the default,
 262 \fBstart\fR,
 263 \fBafter\fR
 264 or
 265 \fBbefore\fR\&.
 266 .sp
 267 If it is
 268 \fBend\fR, then each new trailer will appear at the end of the existing trailers\&.
 269 .sp
 270 If it is
 271 \fBstart\fR, then each new trailer will appear at the start, instead of the end, of the existing trailers\&.
 272 .sp
 273 If it is
 274 \fBafter\fR, then each new trailer will appear just after the last trailer with the same <key>\&.
 275 .sp
 276 If it is
 277 \fBbefore\fR, then each new trailer will appear just before the first trailer with the same <key>\&.
 278 .RE
 279 .PP
 280 trailer\&.ifexists
 281 .RS 4
 282 This option makes it possible to choose what action will be performed when there is already at least one trailer with the same <key> in the input\&.
 283 .sp
 284 The valid values for this option are:
 285 \fBaddIfDifferentNeighbor\fR
 286 (this is the default),
 287 \fBaddIfDifferent\fR,
 288 \fBadd\fR,
 289 \fBreplace\fR
 290 or
 291 \fBdoNothing\fR\&.
 292 .sp
 293 With
 294 \fBaddIfDifferentNeighbor\fR, a new trailer will be added only if no trailer with the same (<key>, <value>) pair is above or below the line where the new trailer will be added\&.
 295 .sp
 296 With
 297 \fBaddIfDifferent\fR, a new trailer will be added only if no trailer with the same (<key>, <value>) pair is already in the input\&.
 298 .sp
 299 With
 300 \fBadd\fR, a new trailer will be added, even if some trailers with the same (<key>, <value>) pair are already in the input\&.
 301 .sp
 302 With
 303 \fBreplace\fR, an existing trailer with the same <key> will be deleted and the new trailer will be added\&. The deleted trailer will be the closest one (with the same <key>) to the place where the new one will be added\&.
 304 .sp
 305 With
 306 \fBdoNothing\fR, nothing will be done; that is no new trailer will be added if there is already one with the same <key> in the input\&.
 307 .RE
 308 .PP
 309 trailer\&.ifmissing
 310 .RS 4
 311 This option makes it possible to choose what action will be performed when there is not yet any trailer with the same <key> in the input\&.
 312 .sp
 313 The valid values for this option are:
 314 \fBadd\fR
 315 (this is the default) and
 316 \fBdoNothing\fR\&.
 317 .sp
 318 With
 319 \fBadd\fR, a new trailer will be added\&.
 320 .sp
 321 With
 322 \fBdoNothing\fR, nothing will be done\&.
 323 .RE
 324 .PP
 325 trailer\&.<keyAlias>\&.key
 326 .RS 4
 327 Defines a <keyAlias> for the <key>\&. The <keyAlias> must be a prefix (case does not matter) of the <key>\&. For example, in
 328 \fBgit config trailer\&.ack\&.key "Acked\-by"\fR
 329 the "Acked\-by" is the <key> and the "ack" is the <keyAlias>\&. This configuration allows the shorter
 330 \fB\-\-trailer "ack:\&.\&.\&."\fR
 331 invocation on the command line using the "ack" <keyAlias> instead of the longer
 332 \fB\-\-trailer "Acked\-by:\&.\&.\&."\fR\&.
 333 .sp
 334 At the end of the <key>, a separator can appear and then some space characters\&. By default the only valid separator is
 335 \fI:\fR, but this can be changed using the
 336 \fBtrailer\&.separators\fR
 337 config variable\&.
 338 .sp
 339 If there is a separator in the key, then it overrides the default separator when adding the trailer\&.
 340 .RE
 341 .PP
 342 trailer\&.<keyAlias>\&.where
 343 .RS 4
 344 This option takes the same values as the
 345 \fItrailer\&.where\fR
 346 configuration variable and it overrides what is specified by that option for trailers with the specified <keyAlias>\&.
 347 .RE
 348 .PP
 349 trailer\&.<keyAlias>\&.ifexists
 350 .RS 4
 351 This option takes the same values as the
 352 \fItrailer\&.ifexists\fR
 353 configuration variable and it overrides what is specified by that option for trailers with the specified <keyAlias>\&.
 354 .RE
 355 .PP
 356 trailer\&.<keyAlias>\&.ifmissing
 357 .RS 4
 358 This option takes the same values as the
 359 \fItrailer\&.ifmissing\fR
 360 configuration variable and it overrides what is specified by that option for trailers with the specified <keyAlias>\&.
 361 .RE
 362 .PP
 363 trailer\&.<keyAlias>\&.command
 364 .RS 4
 365 Deprecated in favor of
 366 \fItrailer\&.<keyAlias>\&.cmd\fR\&. This option behaves in the same way as
 367 \fItrailer\&.<keyAlias>\&.cmd\fR, except that it doesn\(cqt pass anything as argument to the specified command\&. Instead the first occurrence of substring $ARG is replaced by the <value> that would be passed as argument\&.
 368 .sp
 369 Note that $ARG in the user\(cqs command is only replaced once and that the original way of replacing $ARG is not safe\&.
 370 .sp
 371 When both
 372 \fItrailer\&.<keyAlias>\&.cmd\fR
 373 and
 374 \fItrailer\&.<keyAlias>\&.command\fR
 375 are given for the same <keyAlias>,
 376 \fItrailer\&.<keyAlias>\&.cmd\fR
 377 is used and
 378 \fItrailer\&.<keyAlias>\&.command\fR
 379 is ignored\&.
 380 .RE
 381 .PP
 382 trailer\&.<keyAlias>\&.cmd
 383 .RS 4
 384 This option can be used to specify a shell command that will be called once to automatically add a trailer with the specified <keyAlias>, and then called each time a
 385 \fI\-\-trailer <keyAlias>=<value>\fR
 386 argument is specified to modify the <value> of the trailer that this option would produce\&.
 387 .sp
 388 When the specified command is first called to add a trailer with the specified <keyAlias>, the behavior is as if a special
 389 \fI\-\-trailer <keyAlias>=<value>\fR
 390 argument was added at the beginning of the "git interpret\-trailers" command, where <value> is taken to be the standard output of the command with any leading and trailing whitespace trimmed off\&.
 391 .sp
 392 If some
 393 \fI\-\-trailer <keyAlias>=<value>\fR
 394 arguments are also passed on the command line, the command is called again once for each of these arguments with the same <keyAlias>\&. And the <value> part of these arguments, if any, will be passed to the command as its first argument\&. This way the command can produce a <value> computed from the <value> passed in the
 395 \fI\-\-trailer <keyAlias>=<value>\fR
 396 argument\&.
 397 .RE
 398 .SH "EXAMPLES"
 399 .sp
 400 .RS 4
 401 .ie n \{\
 402 \h'-04'\(bu\h'+03'\c
 403 .\}
 404 .el \{\
 405 .sp -1
 406 .IP \(bu 2.3
 407 .\}
 408 Configure a
 409 \fIsign\fR
 410 trailer with a
 411 \fISigned\-off\-by\fR
 412 key, and then add two of these trailers to a commit message file:
 413 .sp
 414 .if n \{\
 415 .RS 4
 416 .\}
 417 .nf
 418 $ git config trailer\&.sign\&.key "Signed\-off\-by"
 419 $ cat msg\&.txt
 420 subject
 421
 422 body text
 423 $ git interpret\-trailers \-\-trailer \*(Aqsign: Alice <alice@example\&.com>\*(Aq \-\-trailer \*(Aqsign: Bob <bob@example\&.com>\*(Aq <msg\&.txt
 424 subject
 425
 426 body text
 427
 428 Signed\-off\-by: Alice <alice@example\&.com>
 429 Signed\-off\-by: Bob <bob@example\&.com>
 430 .fi
 431 .if n \{\
 432 .RE
 433 .\}
 434 .sp
 435 .RE
 436 .sp
 437 .RS 4
 438 .ie n \{\
 439 \h'-04'\(bu\h'+03'\c
 440 .\}
 441 .el \{\
 442 .sp -1
 443 .IP \(bu 2.3
 444 .\}
 445 Use the
 446 \fB\-\-in\-place\fR
 447 option to edit a commit message file in place:
 448 .sp
 449 .if n \{\
 450 .RS 4
 451 .\}
 452 .nf
 453 $ cat msg\&.txt
 454 subject
 455
 456 body text
 457
 458 Signed\-off\-by: Bob <bob@example\&.com>
 459 $ git interpret\-trailers \-\-trailer \*(AqAcked\-by: Alice <alice@example\&.com>\*(Aq \-\-in\-place msg\&.txt
 460 $ cat msg\&.txt
 461 subject
 462
 463 body text
 464
 465 Signed\-off\-by: Bob <bob@example\&.com>
 466 Acked\-by: Alice <alice@example\&.com>
 467 .fi
 468 .if n \{\
 469 .RE
 470 .\}
 471 .sp
 472 .RE
 473 .sp
 474 .RS 4
 475 .ie n \{\
 476 \h'-04'\(bu\h'+03'\c
 477 .\}
 478 .el \{\
 479 .sp -1
 480 .IP \(bu 2.3
 481 .\}
 482 Extract the last commit as a patch, and add a
 483 \fICc\fR
 484 and a
 485 \fIReviewed\-by\fR
 486 trailer to it:
 487 .sp
 488 .if n \{\
 489 .RS 4
 490 .\}
 491 .nf
 492 $ git format\-patch \-1
 493 0001\-foo\&.patch
 494 $ git interpret\-trailers \-\-trailer \*(AqCc: Alice <alice@example\&.com>\*(Aq \-\-trailer \*(AqReviewed\-by: Bob <bob@example\&.com>\*(Aq 0001\-foo\&.patch >0001\-bar\&.patch
 495 .fi
 496 .if n \{\
 497 .RE
 498 .\}
 499 .sp
 500 .RE
 501 .sp
 502 .RS 4
 503 .ie n \{\
 504 \h'-04'\(bu\h'+03'\c
 505 .\}
 506 .el \{\
 507 .sp -1
 508 .IP \(bu 2.3
 509 .\}
 510 Configure a
 511 \fIsign\fR
 512 trailer with a command to automatically add a \*(AqSigned\-off\-by: \*(Aq with the author information only if there is no \*(AqSigned\-off\-by: \*(Aq already, and show how it works:
 513 .sp
 514 .if n \{\
 515 .RS 4
 516 .\}
 517 .nf
 518 $ cat msg1\&.txt
 519 subject
 520
 521 body text
 522 $ git config trailer\&.sign\&.key "Signed\-off\-by: "
 523 $ git config trailer\&.sign\&.ifmissing add
 524 $ git config trailer\&.sign\&.ifexists doNothing
 525 $ git config trailer\&.sign\&.cmd \*(Aqecho "$(git config user\&.name) <$(git config user\&.email)>"\*(Aq
 526 $ git interpret\-trailers \-\-trailer sign <msg1\&.txt
 527 subject
 528
 529 body text
 530
 531 Signed\-off\-by: Bob <bob@example\&.com>
 532 $ cat msg2\&.txt
 533 subject
 534
 535 body text
 536
 537 Signed\-off\-by: Alice <alice@example\&.com>
 538 $ git interpret\-trailers \-\-trailer sign <msg2\&.txt
 539 subject
 540
 541 body text
 542
 543 Signed\-off\-by: Alice <alice@example\&.com>
 544 .fi
 545 .if n \{\
 546 .RE
 547 .\}
 548 .sp
 549 .RE
 550 .sp
 551 .RS 4
 552 .ie n \{\
 553 \h'-04'\(bu\h'+03'\c
 554 .\}
 555 .el \{\
 556 .sp -1
 557 .IP \(bu 2.3
 558 .\}
 559 Configure a
 560 \fIfix\fR
 561 trailer with a key that contains a
 562 \fI#\fR
 563 and no space after this character, and show how it works:
 564 .sp
 565 .if n \{\
 566 .RS 4
 567 .\}
 568 .nf
 569 $ git config trailer\&.separators ":#"
 570 $ git config trailer\&.fix\&.key "Fix #"
 571 $ echo "subject" | git interpret\-trailers \-\-trailer fix=42
 572 subject
 573
 574 Fix #42
 575 .fi
 576 .if n \{\
 577 .RE
 578 .\}
 579 .sp
 580 .RE
 581 .sp
 582 .RS 4
 583 .ie n \{\
 584 \h'-04'\(bu\h'+03'\c
 585 .\}
 586 .el \{\
 587 .sp -1
 588 .IP \(bu 2.3
 589 .\}
 590 Configure a
 591 \fIhelp\fR
 592 trailer with a cmd use a script
 593 \fBglog\-find\-author\fR
 594 which search specified author identity from git log in git repository and show how it works:
 595 .sp
 596 .if n \{\
 597 .RS 4
 598 .\}
 599 .nf
 600 $ cat ~/bin/glog\-find\-author
 601 #!/bin/sh
 602 test \-n "$1" && git log \-\-author="$1" \-\-pretty="%an <%ae>" \-1 || true
 603 $ cat msg\&.txt
 604 subject
 605
 606 body text
 607 $ git config trailer\&.help\&.key "Helped\-by: "
 608 $ git config trailer\&.help\&.ifExists "addIfDifferentNeighbor"
 609 $ git config trailer\&.help\&.cmd "~/bin/glog\-find\-author"
 610 $ git interpret\-trailers \-\-trailer="help:Junio" \-\-trailer="help:Couder" <msg\&.txt
 611 subject
 612
 613 body text
 614
 615 Helped\-by: Junio C Hamano <gitster@pobox\&.com>
 616 Helped\-by: Christian Couder <christian\&.couder@gmail\&.com>
 617 .fi
 618 .if n \{\
 619 .RE
 620 .\}
 621 .sp
 622 .RE
 623 .sp
 624 .RS 4
 625 .ie n \{\
 626 \h'-04'\(bu\h'+03'\c
 627 .\}
 628 .el \{\
 629 .sp -1
 630 .IP \(bu 2.3
 631 .\}
 632 Configure a
 633 \fIref\fR
 634 trailer with a cmd use a script
 635 \fBglog\-grep\fR
 636 to grep last relevant commit from git log in the git repository and show how it works:
 637 .sp
 638 .if n \{\
 639 .RS 4
 640 .\}
 641 .nf
 642 $ cat ~/bin/glog\-grep
 643 #!/bin/sh
 644 test \-n "$1" && git log \-\-grep "$1" \-\-pretty=reference \-1 || true
 645 $ cat msg\&.txt
 646 subject
 647
 648 body text
 649 $ git config trailer\&.ref\&.key "Reference\-to: "
 650 $ git config trailer\&.ref\&.ifExists "replace"
 651 $ git config trailer\&.ref\&.cmd "~/bin/glog\-grep"
 652 $ git interpret\-trailers \-\-trailer="ref:Add copyright notices\&." <msg\&.txt
 653 subject
 654
 655 body text
 656
 657 Reference\-to: 8bc9a0c769 (Add copyright notices\&., 2005\-04\-07)
 658 .fi
 659 .if n \{\
 660 .RE
 661 .\}
 662 .sp
 663 .RE
 664 .sp
 665 .RS 4
 666 .ie n \{\
 667 \h'-04'\(bu\h'+03'\c
 668 .\}
 669 .el \{\
 670 .sp -1
 671 .IP \(bu 2.3
 672 .\}
 673 Configure a
 674 \fIsee\fR
 675 trailer with a command to show the subject of a commit that is related, and show how it works:
 676 .sp
 677 .if n \{\
 678 .RS 4
 679 .\}
 680 .nf
 681 $ cat msg\&.txt
 682 subject
 683
 684 body text
 685
 686 see: HEAD~2
 687 $ cat ~/bin/glog\-ref
 688 #!/bin/sh
 689 git log \-1 \-\-oneline \-\-format="%h (%s)" \-\-abbrev\-commit \-\-abbrev=14
 690 $ git config trailer\&.see\&.key "See\-also: "
 691 $ git config trailer\&.see\&.ifExists "replace"
 692 $ git config trailer\&.see\&.ifMissing "doNothing"
 693 $ git config trailer\&.see\&.cmd "glog\-ref"
 694 $ git interpret\-trailers \-\-trailer=see <msg\&.txt
 695 subject
 696
 697 body text
 698
 699 See\-also: fe3187489d69c4 (subject of related commit)
 700 .fi
 701 .if n \{\
 702 .RE
 703 .\}
 704 .sp
 705 .RE
 706 .sp
 707 .RS 4
 708 .ie n \{\
 709 \h'-04'\(bu\h'+03'\c
 710 .\}
 711 .el \{\
 712 .sp -1
 713 .IP \(bu 2.3
 714 .\}
 715 Configure a commit template with some trailers with empty values (using sed to show and keep the trailing spaces at the end of the trailers), then configure a commit\-msg hook that uses
 716 \fIgit interpret\-trailers\fR
 717 to remove trailers with empty values and to add a
 718 \fIgit\-version\fR
 719 trailer:
 720 .sp
 721 .if n \{\
 722 .RS 4
 723 .\}
 724 .nf
 725 $ cat temp\&.txt
 726 ***subject***
 727
 728 ***message***
 729
 730 Fixes: Z
 731 Cc: Z
 732 Reviewed\-by: Z
 733 Signed\-off\-by: Z
 734 $ sed \-e \*(Aqs/ Z$/ /\*(Aq temp\&.txt > commit_template\&.txt
 735 $ git config commit\&.template commit_template\&.txt
 736 $ cat \&.git/hooks/commit\-msg
 737 #!/bin/sh
 738 git interpret\-trailers \-\-trim\-empty \-\-trailer "git\-version: \e$(git describe)" "\e$1" > "\e$1\&.new"
 739 mv "\e$1\&.new" "\e$1"
 740 $ chmod +x \&.git/hooks/commit\-msg
 741 .fi
 742 .if n \{\
 743 .RE
 744 .\}
 745 .sp
 746 .RE
 747 .SH "SEE ALSO"
 748 .sp
 749 \fBgit-commit\fR(1), \fBgit-format-patch\fR(1), \fBgit-config\fR(1)
 750 .SH "GIT"
 751 .sp
 752 Part of the \fBgit\fR(1) suite