| 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 | This command ignores comment lines (see `core.commentString` in |
| 127 | linkgit:git-config[1]). This is for use with the `prepare-commit-msg` |
| 128 | and `commit-msg` hooks. |
| 129 | |
| 130 | OPTIONS |
| 131 | ------- |
| 132 | `--in-place`:: |
| 133 | `--no-in-place`:: |
| 134 | Edit the files in place. The default is `--no-in-place`. |
| 135 | |
| 136 | `--trim-empty`:: |
| 137 | `--no-trim-empty`:: |
| 138 | If the _<value>_ part of any trailer contains only whitespace, |
| 139 | the whole trailer will be removed from the output. |
| 140 | This applies to existing trailers as well as new trailers. |
| 141 | + |
| 142 | The default is `--no-trim-empty`. |
| 143 | |
| 144 | `--trailer=<key>[(=|:)<value>]`:: |
| 145 | `--no-trailer`:: |
| 146 | Specify a (_<key>_, _<value>_) pair that should be applied as a |
| 147 | trailer to the inputs. See the description of this command. Can |
| 148 | be given multiple times. |
| 149 | + |
| 150 | Use `--no-trailer` to reset the list. |
| 151 | |
| 152 | `--where=<placement>`:: |
| 153 | `--no-where`:: |
| 154 | Specify where all new trailers will be added. A setting |
| 155 | provided with `--where` overrides the `trailer.where` and any |
| 156 | applicable `trailer.<key-alias>.where` configuration variables |
| 157 | and applies to all `--trailer` options until the next occurrence of |
| 158 | `--where` or `--no-where`. Possible placements are `after`, |
| 159 | `before`, `end` or `start`. |
| 160 | + |
| 161 | Use `--no-where` to clear the effect of any previous use of `--where`, |
| 162 | such that the relevant configuration variables are no longer overridden. |
| 163 | |
| 164 | `--if-exists=<action>`:: |
| 165 | `--no-if-exists`:: |
| 166 | Specify what action will be performed when there is already at |
| 167 | least one trailer with the same _<key>_ in the input. A setting |
| 168 | provided with `--if-exists` overrides the `trailer.ifExists` and any |
| 169 | applicable `trailer.<key-alias>.ifExists` configuration variables |
| 170 | and applies to all `--trailer` options until the next occurrence of |
| 171 | `--if-exists` or `--no-if-exists`. Possible actions are `addIfDifferent`, |
| 172 | `addIfDifferentNeighbor`, `add`, `replace` and `doNothing`. |
| 173 | + |
| 174 | Use `--no-if-exists` to clear the effect of any previous use of |
| 175 | `--if-exists`, such that the relevant configuration variables are no |
| 176 | longer overridden. |
| 177 | |
| 178 | `--if-missing=<action>`:: |
| 179 | `--no-if-missing`:: |
| 180 | Specify what action will be performed when there is no other |
| 181 | trailer with the same _<key>_ in the input. A setting |
| 182 | provided with `--if-missing` overrides the `trailer.ifMissing` and any |
| 183 | applicable `trailer.<key-alias>.ifMissing` configuration variables |
| 184 | and applies to all `--trailer` options until the next occurrence of |
| 185 | `--if-missing` or `--no-if-missing`. Possible actions are |
| 186 | `doNothing` or `add`. |
| 187 | + |
| 188 | Use `--no-if-missing` to clear the effect of any previous use of |
| 189 | `--if-missing`, such that the relevant configuration variables are no |
| 190 | longer overridden. |
| 191 | |
| 192 | `--only-trailers`:: |
| 193 | `--no-only-trailers`:: |
| 194 | Output only the trailers, not any other parts of the |
| 195 | input. The default is `--no-only-trailers`. |
| 196 | |
| 197 | `--only-input`:: |
| 198 | `--no-only-input`:: |
| 199 | Output only trailers that exist in the input; do not add any |
| 200 | from the command-line or by applying `trailer.<key-alias>` configuration |
| 201 | variables. The default is `--no-only-input`. |
| 202 | |
| 203 | `--unfold`:: |
| 204 | `--no-unfold`:: |
| 205 | If a trailer has a value that runs over multiple lines (aka "folded"), |
| 206 | reformat the value into a single line. The default is `--no-unfold`. |
| 207 | |
| 208 | `--parse`:: |
| 209 | A convenience alias for `--only-trailers --only-input |
| 210 | --unfold`. This makes it easier to only see the trailers coming from the |
| 211 | input without influencing them with any command line options or |
| 212 | configuration variables, while also making the output machine-friendly with |
| 213 | `--unfold`. |
| 214 | + |
| 215 | There is no convenience alias to negate this alias. |
| 216 | |
| 217 | `--divider`:: |
| 218 | `--no-divider`:: |
| 219 | Treat `---` as the end of the commit message. This is the default. |
| 220 | Use `--no-divider` when you know your input contains just the |
| 221 | commit message itself (and not an email or the output of |
| 222 | linkgit:git-format-patch[1]). |
| 223 | |
| 224 | CONFIGURATION VARIABLES |
| 225 | ----------------------- |
| 226 | |
| 227 | include::includes/cmd-config-section-all.adoc[] |
| 228 | |
| 229 | include::config/trailer.adoc[] |
| 230 | |
| 231 | EXAMPLES |
| 232 | -------- |
| 233 | |
| 234 | * Configure a `sign` trailer with a `Signed-off-by` key, and then |
| 235 | add two of these trailers to a commit message file: |
| 236 | + |
| 237 | ------------ |
| 238 | $ git config trailer.sign.key "Signed-off-by" |
| 239 | $ cat msg.txt |
| 240 | subject |
| 241 | |
| 242 | body text |
| 243 | $ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt |
| 244 | subject |
| 245 | |
| 246 | body text |
| 247 | |
| 248 | Signed-off-by: Alice <alice@example.com> |
| 249 | Signed-off-by: Bob <bob@example.com> |
| 250 | ------------ |
| 251 | |
| 252 | * Use the `--in-place` option to edit a commit message file in place: |
| 253 | + |
| 254 | ------------ |
| 255 | $ cat msg.txt |
| 256 | subject |
| 257 | |
| 258 | body text |
| 259 | |
| 260 | Signed-off-by: Bob <bob@example.com> |
| 261 | $ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt |
| 262 | $ cat msg.txt |
| 263 | subject |
| 264 | |
| 265 | body text |
| 266 | |
| 267 | Signed-off-by: Bob <bob@example.com> |
| 268 | Acked-by: Alice <alice@example.com> |
| 269 | ------------ |
| 270 | |
| 271 | * Extract the last commit as a patch, and add a `Cc` and a |
| 272 | `Reviewed-by` trailer to it: |
| 273 | + |
| 274 | ------------ |
| 275 | $ git format-patch -1 |
| 276 | 0001-foo.patch |
| 277 | $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Reviewed-by: Bob <bob@example.com>' 0001-foo.patch >0001-bar.patch |
| 278 | ------------ |
| 279 | |
| 280 | * Configure a `sign` trailer with a command to automatically add a |
| 281 | "`Signed-off-by:`{nbsp}" with the author information only if there is no |
| 282 | "`Signed-off-by:`{nbsp}" already, and show how it works: |
| 283 | + |
| 284 | ------------ |
| 285 | $ cat msg1.txt |
| 286 | subject |
| 287 | |
| 288 | body text |
| 289 | $ git config trailer.sign.key "Signed-off-by: " |
| 290 | $ git config trailer.sign.ifmissing add |
| 291 | $ git config trailer.sign.ifexists doNothing |
| 292 | $ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"' |
| 293 | $ git interpret-trailers --trailer sign <msg1.txt |
| 294 | subject |
| 295 | |
| 296 | body text |
| 297 | |
| 298 | Signed-off-by: Bob <bob@example.com> |
| 299 | $ cat msg2.txt |
| 300 | subject |
| 301 | |
| 302 | body text |
| 303 | |
| 304 | Signed-off-by: Alice <alice@example.com> |
| 305 | $ git interpret-trailers --trailer sign <msg2.txt |
| 306 | subject |
| 307 | |
| 308 | body text |
| 309 | |
| 310 | Signed-off-by: Alice <alice@example.com> |
| 311 | ------------ |
| 312 | |
| 313 | * Configure a `fix` trailer with a key that contains a `#` and no |
| 314 | space after this character, and show how it works: |
| 315 | + |
| 316 | ------------ |
| 317 | $ git config trailer.separators ":#" |
| 318 | $ git config trailer.fix.key "Fix #" |
| 319 | $ echo "subject" | git interpret-trailers --trailer fix=42 |
| 320 | subject |
| 321 | |
| 322 | Fix #42 |
| 323 | ------------ |
| 324 | |
| 325 | * Configure a `help` trailer with a cmd use a script `glog-find-author` |
| 326 | which search specified author identity from git log in git repository |
| 327 | and show how it works: |
| 328 | + |
| 329 | ------------ |
| 330 | $ cat ~/bin/glog-find-author |
| 331 | #!/bin/sh |
| 332 | test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true |
| 333 | $ cat msg.txt |
| 334 | subject |
| 335 | |
| 336 | body text |
| 337 | $ git config trailer.help.key "Helped-by: " |
| 338 | $ git config trailer.help.ifExists "addIfDifferentNeighbor" |
| 339 | $ git config trailer.help.cmd "~/bin/glog-find-author" |
| 340 | $ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt |
| 341 | subject |
| 342 | |
| 343 | body text |
| 344 | |
| 345 | Helped-by: Junio C Hamano <gitster@pobox.com> |
| 346 | Helped-by: Christian Couder <christian.couder@gmail.com> |
| 347 | ------------ |
| 348 | |
| 349 | * Configure a `ref` trailer with a cmd use a script `glog-grep` |
| 350 | to grep last relevant commit from git log in the git repository |
| 351 | and show how it works: |
| 352 | + |
| 353 | ------------ |
| 354 | $ cat ~/bin/glog-grep |
| 355 | #!/bin/sh |
| 356 | test -n "$1" && git log --grep "$1" --pretty=reference -1 || true |
| 357 | $ cat msg.txt |
| 358 | subject |
| 359 | |
| 360 | body text |
| 361 | $ git config trailer.ref.key "Reference-to: " |
| 362 | $ git config trailer.ref.ifExists "replace" |
| 363 | $ git config trailer.ref.cmd "~/bin/glog-grep" |
| 364 | $ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt |
| 365 | subject |
| 366 | |
| 367 | body text |
| 368 | |
| 369 | Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07) |
| 370 | ------------ |
| 371 | |
| 372 | * Configure a `see` trailer with a command to show the subject of a |
| 373 | commit that is related, and show how it works: |
| 374 | + |
| 375 | ------------ |
| 376 | $ cat msg.txt |
| 377 | subject |
| 378 | |
| 379 | body text |
| 380 | |
| 381 | see: HEAD~2 |
| 382 | $ cat ~/bin/glog-ref |
| 383 | #!/bin/sh |
| 384 | git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14 |
| 385 | $ git config trailer.see.key "See-also: " |
| 386 | $ git config trailer.see.ifExists "replace" |
| 387 | $ git config trailer.see.ifMissing "doNothing" |
| 388 | $ git config trailer.see.cmd "glog-ref" |
| 389 | $ git interpret-trailers --trailer=see <msg.txt |
| 390 | subject |
| 391 | |
| 392 | body text |
| 393 | |
| 394 | See-also: fe3187489d69c4 (subject of related commit) |
| 395 | ------------ |
| 396 | |
| 397 | * Configure a commit template with some trailers with empty values |
| 398 | (using sed to show and keep the trailing spaces at the end of the |
| 399 | trailers), then configure a commit-msg hook that uses |
| 400 | git-interpret-trailers(1) to remove trailers with empty values and to |
| 401 | add a `git-version` trailer: |
| 402 | + |
| 403 | ------------ |
| 404 | $ cat temp.txt |
| 405 | ***subject*** |
| 406 | |
| 407 | ***message*** |
| 408 | |
| 409 | Fixes: Z |
| 410 | Cc: Z |
| 411 | Reviewed-by: Z |
| 412 | Signed-off-by: Z |
| 413 | $ sed -e 's/ Z$/ /' temp.txt > commit_template.txt |
| 414 | $ git config commit.template commit_template.txt |
| 415 | $ cat .git/hooks/commit-msg |
| 416 | #!/bin/sh |
| 417 | git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new" |
| 418 | mv "\$1.new" "\$1" |
| 419 | $ chmod +x .git/hooks/commit-msg |
| 420 | ------------ |
| 421 | |
| 422 | * Here we try to use three different trailer keys. But it fails because |
| 423 | two of them are not recognized as trailer keys. |
| 424 | + |
| 425 | ---- |
| 426 | $ cat msg.txt |
| 427 | subject |
| 428 | |
| 429 | Skapad-på: some-branch |
| 430 | Hash-in-v6.11: 45c12d3269fe48f22834320c782ffe86c3560f2c |
| 431 | Reviewed-by: Alice <alice@example.com> |
| 432 | $ git interpret-trailers --only-trailers <msg.txt |
| 433 | $ |
| 434 | ---- |
| 435 | + |
| 436 | Recall that a trailer key has to consist of only ASCII alphanumeric |
| 437 | characters and hyphens, and this does not hold for the two first |
| 438 | supposed trailer keys. And now none are recognized as trailers because |
| 439 | the candidate trailer block has at least one non-trailer line, even |
| 440 | though `Reviewed-by` is a valid trailer key. Recall that a trailer block |
| 441 | has to either (i) be all trailers, or (ii) consist of at least one |
| 442 | Git-generated or user-configured trailer (and some other conditions). |
| 443 | And (ii) is not satisfied since we have not configured any trailer keys. |
| 444 | |
| 445 | SEE ALSO |
| 446 | -------- |
| 447 | linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1] |
| 448 | |
| 449 | GIT |
| 450 | --- |
| 451 | Part of the linkgit:git[1] suite |