| 1 | git-interpret-trailers(1) |
| 2 | ========================= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-interpret-trailers - Add or parse metadata in commit messages |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | [synopsis] |
| 11 | git interpret-trailers [--in-place] [--trim-empty] |
| 12 | [(--trailer (<key>|<key-alias>)[(=|:)<value>])...] |
| 13 | [--parse] [<file>...] |
| 14 | |
| 15 | DESCRIPTION |
| 16 | ----------- |
| 17 | Add or parse trailer metadata at the end of the otherwise |
| 18 | free-form part of a commit message, or any other kind of text. |
| 19 | |
| 20 | A _trailer_ in its simplest form is a key-value pair with a colon as a |
| 21 | separator. The _key_ consists of ASCII alphanumeric characters and |
| 22 | hyphens (`-`). A _trailer block_ consists of one or more trailers. The |
| 23 | trailer block needs to be preceded by a blank line, where a _blank line_ |
| 24 | is either an empty or a whitespace-only line. For example, in the |
| 25 | following commit message |
| 26 | |
| 27 | ------------------------------------------------ |
| 28 | subject |
| 29 | |
| 30 | Lorem ipsum dolor sit amet, consectetur adipiscing elit. |
| 31 | |
| 32 | Signed-off-by: Alice <alice@example.com> |
| 33 | Signed-off-by: Bob <bob@example.com> |
| 34 | ------------------------------------------------ |
| 35 | |
| 36 | the last two lines starting with `Signed-off-by` are trailers. |
| 37 | |
| 38 | This command reads commit messages from either the |
| 39 | _<file>_ arguments or the standard input if no _<file>_ is specified. |
| 40 | If `--parse` is specified, the output consists of the parsed trailers |
| 41 | coming from the input, without influencing them with any command line |
| 42 | options or configuration variables. |
| 43 | |
| 44 | Otherwise, this command applies `trailer.<key-alias>` configuration |
| 45 | variables (which could potentially add new trailers, as well as |
| 46 | reposition them), as well as any command line arguments that can |
| 47 | override configuration variables (such as `--trailer=...` which could |
| 48 | also add new trailers), to each input file. The result is emitted on the |
| 49 | standard output. |
| 50 | |
| 51 | This command can also operate on the output of linkgit:git-format-patch[1], |
| 52 | which is more elaborate than a plain commit message. Namely, such output |
| 53 | includes a commit message (as above), a `---` divider line, and a patch part. |
| 54 | For these inputs, the divider and patch parts are not modified by |
| 55 | this command and are emitted as is on the output, unless |
| 56 | `--no-divider` is specified. |
| 57 | |
| 58 | Some configuration variables control the way the `--trailer` arguments |
| 59 | are applied to each input and the way any existing trailer in |
| 60 | the input is changed. They also make it possible to |
| 61 | automatically add some trailers. |
| 62 | |
| 63 | Let's consider new trailers added with `--trailer`. |
| 64 | By default, the new trailer will appear at the end of the trailer block. |
| 65 | Also by default, this new trailer will only be added |
| 66 | if the last trailer is different to it. |
| 67 | A trailer block will be created with only that trailer if a trailer |
| 68 | block does not already exist. Recall that a trailer block needs to be |
| 69 | preceded by a blank line, so a blank line will be inserted before the |
| 70 | new trailer block in that case. |
| 71 | |
| 72 | This is how the new trailer is added: a `<key>=<value>` or |
| 73 | `<key>:<value>` argument given using `--trailer` will be appended after |
| 74 | the existing trailers. The _<key>_ and _<value>_ parts will be trimmed |
| 75 | to remove starting and trailing whitespace, and the resulting trimmed |
| 76 | _<key>_ and _<value>_ will appear in the output like this: |
| 77 | |
| 78 | ------------------------------------------------ |
| 79 | key: value |
| 80 | ------------------------------------------------ |
| 81 | |
| 82 | This means that the trimmed _<key>_ and _<value>_ will be separated by |
| 83 | "`:`{nbsp}" (one colon followed by one space). |
| 84 | |
| 85 | Existing trailers are extracted from the input by looking for the |
| 86 | trailer block. A trailer block is a group of one or more lines that (i) |
| 87 | is all trailers, or (ii) contains at least one Git-generated or |
| 88 | user-configured trailer and consists of at |
| 89 | least 25% trailers. |
| 90 | The trailer block is by definition at the end of the commit message. |
| 91 | The message in turn is either (i) at the end of the input, or (ii) the |
| 92 | last non-whitespace lines before a line that starts with `---` (followed |
| 93 | by a space or the end of the line). |
| 94 | |
| 95 | For convenience, a _<key-alias>_ can be configured to make using `--trailer` |
| 96 | shorter to type on the command line. This can be configured using the |
| 97 | `trailer.<key-alias>.key` configuration variable. The _<key-alias>_ must be a prefix |
| 98 | of the full _<key>_ string, although case sensitivity does not matter. For |
| 99 | example, if you have |
| 100 | |
| 101 | ------------------------------------------------ |
| 102 | trailer.sign.key "Signed-off-by: " |
| 103 | ------------------------------------------------ |
| 104 | |
| 105 | in your configuration, you only need to specify `--trailer="sign: foo"` |
| 106 | on the command line instead of `--trailer="Signed-off-by: foo"`. |
| 107 | |
| 108 | When reading trailers, there can be no whitespace before or inside the |
| 109 | _<key>_, but any number of regular space and tab characters are allowed |
| 110 | between the _<key>_ and the separator. There can be whitespaces before, |
| 111 | inside or after the _<value>_. The _<value>_ may be split over multiple lines |
| 112 | with each subsequent line starting with at least one whitespace, like |
| 113 | the "folding" in RFC 822. Example: |
| 114 | |
| 115 | ------------------------------------------------ |
| 116 | key: This is a very long value, with spaces and |
| 117 | newlines in it. |
| 118 | ------------------------------------------------ |
| 119 | |
| 120 | OTHER RULES |
| 121 | ----------- |
| 122 | |
| 123 | What was covered in the previous section are the rules that are relevant |
| 124 | for regular use. The following points are included for completeness. |
| 125 | |
| 126 | -- |
| 127 | * This command ignores comment lines (see `core.commentString` in |
| 128 | linkgit:git-config[1]). This is for use with the `prepare-commit-msg` |
| 129 | and `commit-msg` hooks. |
| 130 | |
| 131 | * Candidate trailer lines that have `:` as the separator, that have no |
| 132 | whitespace before the value part, and that start with `//` are not |
| 133 | recognized as trailers. This is to avoid accidentally interpreting |
| 134 | URLs as trailers (e.g. lines that start with `https://`). |
| 135 | -- |
| 136 | |
| 137 | OPTIONS |
| 138 | ------- |
| 139 | `--in-place`:: |
| 140 | `--no-in-place`:: |
| 141 | Edit the files in place. The default is `--no-in-place`. |
| 142 | |
| 143 | `--trim-empty`:: |
| 144 | `--no-trim-empty`:: |
| 145 | If the _<value>_ part of any trailer contains only whitespace, |
| 146 | the whole trailer will be removed from the output. |
| 147 | This applies to existing trailers as well as new trailers. |
| 148 | + |
| 149 | The default is `--no-trim-empty`. |
| 150 | |
| 151 | `--trailer=<key>[(=|:)<value>]`:: |
| 152 | `--no-trailer`:: |
| 153 | Specify a (_<key>_, _<value>_) pair that should be applied as a |
| 154 | trailer to the inputs. See the description of this command. Can |
| 155 | be given multiple times. |
| 156 | + |
| 157 | Use `--no-trailer` to reset the list. |
| 158 | |
| 159 | `--where=<placement>`:: |
| 160 | `--no-where`:: |
| 161 | Specify where all new trailers will be added. A setting |
| 162 | provided with `--where` overrides the `trailer.where` and any |
| 163 | applicable `trailer.<key-alias>.where` configuration variables |
| 164 | and applies to all `--trailer` options until the next occurrence of |
| 165 | `--where` or `--no-where`. Possible placements are `after`, |
| 166 | `before`, `end` or `start`. |
| 167 | + |
| 168 | Use `--no-where` to clear the effect of any previous use of `--where`, |
| 169 | such that the relevant configuration variables are no longer overridden. |
| 170 | |
| 171 | `--if-exists=<action>`:: |
| 172 | `--no-if-exists`:: |
| 173 | Specify what action will be performed when there is already at |
| 174 | least one trailer with the same _<key>_ in the input. A setting |
| 175 | provided with `--if-exists` overrides the `trailer.ifExists` and any |
| 176 | applicable `trailer.<key-alias>.ifExists` configuration variables |
| 177 | and applies to all `--trailer` options until the next occurrence of |
| 178 | `--if-exists` or `--no-if-exists`. Possible actions are `addIfDifferent`, |
| 179 | `addIfDifferentNeighbor`, `add`, `replace` and `doNothing`. |
| 180 | + |
| 181 | Use `--no-if-exists` to clear the effect of any previous use of |
| 182 | `--if-exists`, such that the relevant configuration variables are no |
| 183 | longer overridden. |
| 184 | |
| 185 | `--if-missing=<action>`:: |
| 186 | `--no-if-missing`:: |
| 187 | Specify what action will be performed when there is no other |
| 188 | trailer with the same _<key>_ in the input. A setting |
| 189 | provided with `--if-missing` overrides the `trailer.ifMissing` and any |
| 190 | applicable `trailer.<key-alias>.ifMissing` configuration variables |
| 191 | and applies to all `--trailer` options until the next occurrence of |
| 192 | `--if-missing` or `--no-if-missing`. Possible actions are |
| 193 | `doNothing` or `add`. |
| 194 | + |
| 195 | Use `--no-if-missing` to clear the effect of any previous use of |
| 196 | `--if-missing`, such that the relevant configuration variables are no |
| 197 | longer overridden. |
| 198 | |
| 199 | `--only-trailers`:: |
| 200 | `--no-only-trailers`:: |
| 201 | Output only the trailers, not any other parts of the |
| 202 | input. The default is `--no-only-trailers`. |
| 203 | |
| 204 | `--only-input`:: |
| 205 | `--no-only-input`:: |
| 206 | Output only trailers that exist in the input; do not add any |
| 207 | from the command-line or by applying `trailer.<key-alias>` configuration |
| 208 | variables. The default is `--no-only-input`. |
| 209 | |
| 210 | `--unfold`:: |
| 211 | `--no-unfold`:: |
| 212 | If a trailer has a value that runs over multiple lines (aka "folded"), |
| 213 | reformat the value into a single line. The default is `--no-unfold`. |
| 214 | |
| 215 | `--parse`:: |
| 216 | A convenience alias for `--only-trailers --only-input |
| 217 | --unfold`. This makes it easier to only see the trailers coming from the |
| 218 | input without influencing them with any command line options or |
| 219 | configuration variables, while also making the output machine-friendly with |
| 220 | `--unfold`. |
| 221 | + |
| 222 | There is no convenience alias to negate this alias. |
| 223 | |
| 224 | `--divider`:: |
| 225 | `--no-divider`:: |
| 226 | Treat `---` as the end of the commit message. This is the default. |
| 227 | Use `--no-divider` when you know your input contains just the |
| 228 | commit message itself (and not an email or the output of |
| 229 | linkgit:git-format-patch[1]). |
| 230 | |
| 231 | CONFIGURATION VARIABLES |
| 232 | ----------------------- |
| 233 | |
| 234 | include::includes/cmd-config-section-all.adoc[] |
| 235 | |
| 236 | include::config/trailer.adoc[] |
| 237 | |
| 238 | EXAMPLES |
| 239 | -------- |
| 240 | |
| 241 | * Configure a `sign` trailer with a `Signed-off-by` key, and then |
| 242 | add two of these trailers to a commit message file: |
| 243 | + |
| 244 | ------------ |
| 245 | $ git config trailer.sign.key "Signed-off-by" |
| 246 | $ cat msg.txt |
| 247 | subject |
| 248 | |
| 249 | body text |
| 250 | $ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt |
| 251 | subject |
| 252 | |
| 253 | body text |
| 254 | |
| 255 | Signed-off-by: Alice <alice@example.com> |
| 256 | Signed-off-by: Bob <bob@example.com> |
| 257 | ------------ |
| 258 | |
| 259 | * Use the `--in-place` option to edit a commit message file in place: |
| 260 | + |
| 261 | ------------ |
| 262 | $ cat msg.txt |
| 263 | subject |
| 264 | |
| 265 | body text |
| 266 | |
| 267 | Signed-off-by: Bob <bob@example.com> |
| 268 | $ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt |
| 269 | $ cat msg.txt |
| 270 | subject |
| 271 | |
| 272 | body text |
| 273 | |
| 274 | Signed-off-by: Bob <bob@example.com> |
| 275 | Acked-by: Alice <alice@example.com> |
| 276 | ------------ |
| 277 | |
| 278 | * Extract the last commit as a patch, and add a `Cc` and a |
| 279 | `Reviewed-by` trailer to it: |
| 280 | + |
| 281 | ------------ |
| 282 | $ git format-patch -1 |
| 283 | 0001-foo.patch |
| 284 | $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Reviewed-by: Bob <bob@example.com>' 0001-foo.patch >0001-bar.patch |
| 285 | ------------ |
| 286 | |
| 287 | * Configure a `sign` trailer with a command to automatically add a |
| 288 | "`Signed-off-by:`{nbsp}" with the author information only if there is no |
| 289 | "`Signed-off-by:`{nbsp}" already, and show how it works: |
| 290 | + |
| 291 | ------------ |
| 292 | $ cat msg1.txt |
| 293 | subject |
| 294 | |
| 295 | body text |
| 296 | $ git config trailer.sign.key "Signed-off-by: " |
| 297 | $ git config trailer.sign.ifmissing add |
| 298 | $ git config trailer.sign.ifexists doNothing |
| 299 | $ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"' |
| 300 | $ git interpret-trailers --trailer sign <msg1.txt |
| 301 | subject |
| 302 | |
| 303 | body text |
| 304 | |
| 305 | Signed-off-by: Bob <bob@example.com> |
| 306 | $ cat msg2.txt |
| 307 | subject |
| 308 | |
| 309 | body text |
| 310 | |
| 311 | Signed-off-by: Alice <alice@example.com> |
| 312 | $ git interpret-trailers --trailer sign <msg2.txt |
| 313 | subject |
| 314 | |
| 315 | body text |
| 316 | |
| 317 | Signed-off-by: Alice <alice@example.com> |
| 318 | ------------ |
| 319 | |
| 320 | * Configure a `fix` trailer with a key that contains a `#` and no |
| 321 | space after this character, and show how it works: |
| 322 | + |
| 323 | ------------ |
| 324 | $ git config trailer.separators ":#" |
| 325 | $ git config trailer.fix.key "Fix #" |
| 326 | $ echo "subject" | git interpret-trailers --trailer fix=42 |
| 327 | subject |
| 328 | |
| 329 | Fix #42 |
| 330 | ------------ |
| 331 | |
| 332 | * Configure a `help` trailer with a cmd use a script `glog-find-author` |
| 333 | which search specified author identity from git log in git repository |
| 334 | and show how it works: |
| 335 | + |
| 336 | ------------ |
| 337 | $ cat ~/bin/glog-find-author |
| 338 | #!/bin/sh |
| 339 | test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true |
| 340 | $ cat msg.txt |
| 341 | subject |
| 342 | |
| 343 | body text |
| 344 | $ git config trailer.help.key "Helped-by: " |
| 345 | $ git config trailer.help.ifExists "addIfDifferentNeighbor" |
| 346 | $ git config trailer.help.cmd "~/bin/glog-find-author" |
| 347 | $ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt |
| 348 | subject |
| 349 | |
| 350 | body text |
| 351 | |
| 352 | Helped-by: Junio C Hamano <gitster@pobox.com> |
| 353 | Helped-by: Christian Couder <christian.couder@gmail.com> |
| 354 | ------------ |
| 355 | |
| 356 | * Configure a `ref` trailer with a cmd use a script `glog-grep` |
| 357 | to grep last relevant commit from git log in the git repository |
| 358 | and show how it works: |
| 359 | + |
| 360 | ------------ |
| 361 | $ cat ~/bin/glog-grep |
| 362 | #!/bin/sh |
| 363 | test -n "$1" && git log --grep "$1" --pretty=reference -1 || true |
| 364 | $ cat msg.txt |
| 365 | subject |
| 366 | |
| 367 | body text |
| 368 | $ git config trailer.ref.key "Reference-to: " |
| 369 | $ git config trailer.ref.ifExists "replace" |
| 370 | $ git config trailer.ref.cmd "~/bin/glog-grep" |
| 371 | $ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt |
| 372 | subject |
| 373 | |
| 374 | body text |
| 375 | |
| 376 | Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07) |
| 377 | ------------ |
| 378 | |
| 379 | * Configure a `see` trailer with a command to show the subject of a |
| 380 | commit that is related, and show how it works: |
| 381 | + |
| 382 | ------------ |
| 383 | $ cat msg.txt |
| 384 | subject |
| 385 | |
| 386 | body text |
| 387 | |
| 388 | see: HEAD~2 |
| 389 | $ cat ~/bin/glog-ref |
| 390 | #!/bin/sh |
| 391 | git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14 |
| 392 | $ git config trailer.see.key "See-also: " |
| 393 | $ git config trailer.see.ifExists "replace" |
| 394 | $ git config trailer.see.ifMissing "doNothing" |
| 395 | $ git config trailer.see.cmd "glog-ref" |
| 396 | $ git interpret-trailers --trailer=see <msg.txt |
| 397 | subject |
| 398 | |
| 399 | body text |
| 400 | |
| 401 | See-also: fe3187489d69c4 (subject of related commit) |
| 402 | ------------ |
| 403 | |
| 404 | * Configure a commit template with some trailers with empty values |
| 405 | (using sed to show and keep the trailing spaces at the end of the |
| 406 | trailers), then configure a commit-msg hook that uses |
| 407 | git-interpret-trailers(1) to remove trailers with empty values and to |
| 408 | add a `git-version` trailer: |
| 409 | + |
| 410 | ------------ |
| 411 | $ cat temp.txt |
| 412 | ***subject*** |
| 413 | |
| 414 | ***message*** |
| 415 | |
| 416 | Fixes: Z |
| 417 | Cc: Z |
| 418 | Reviewed-by: Z |
| 419 | Signed-off-by: Z |
| 420 | $ sed -e 's/ Z$/ /' temp.txt > commit_template.txt |
| 421 | $ git config commit.template commit_template.txt |
| 422 | $ cat .git/hooks/commit-msg |
| 423 | #!/bin/sh |
| 424 | git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new" |
| 425 | mv "\$1.new" "\$1" |
| 426 | $ chmod +x .git/hooks/commit-msg |
| 427 | ------------ |
| 428 | |
| 429 | * Here we try to use three different trailer keys. But it fails because |
| 430 | two of them are not recognized as trailer keys. |
| 431 | + |
| 432 | ---- |
| 433 | $ cat msg.txt |
| 434 | subject |
| 435 | |
| 436 | Skapad-på: some-branch |
| 437 | Hash-in-v6.11: 45c12d3269fe48f22834320c782ffe86c3560f2c |
| 438 | Reviewed-by: Alice <alice@example.com> |
| 439 | $ git interpret-trailers --only-trailers <msg.txt |
| 440 | $ |
| 441 | ---- |
| 442 | + |
| 443 | Recall that a trailer key has to consist of only ASCII alphanumeric |
| 444 | characters and hyphens, and this does not hold for the two first |
| 445 | supposed trailer keys. And now none are recognized as trailers because |
| 446 | the candidate trailer block has at least one non-trailer line, even |
| 447 | though `Reviewed-by` is a valid trailer key. Recall that a trailer block |
| 448 | has to either (i) be all trailers, or (ii) consist of at least one |
| 449 | Git-generated or user-configured trailer (and some other conditions). |
| 450 | And (ii) is not satisfied since we have not configured any trailer keys. |
| 451 | |
| 452 | SEE ALSO |
| 453 | -------- |
| 454 | linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1] |
| 455 | |
| 456 | GIT |
| 457 | --- |
| 458 | Part of the linkgit:git[1] suite |