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