Documentation/git-interpret-trailers.txt

   1 git-interpret-trailers(1)
   2 =========================
   3
   4 NAME
   5 ----
   6 git-interpret-trailers - help add stuctured information into commit messages
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 'git interpret-trailers' [--trim-empty] [(--trailer <token>[(=|:)<value>])...] [<file>...]
  12
  13 DESCRIPTION
  14 -----------
  15 Help adding 'trailers' lines, that look similar to RFC 822 e-mail
  16 headers, at the end of the otherwise free-form part of a commit
  17 message.
  18
  19 This command reads some patches or commit messages from either the
  20 <file> arguments or the standard input if no <file> is specified. Then
  21 this command applies the arguments passed using the `--trailer`
  22 option, if any, to the commit message part of each input file. The
  23 result is emitted on the standard output.
  24
  25 Some configuration variables control the way the `--trailer` arguments
  26 are applied to each commit message and the way any existing trailer in
  27 the commit message is changed. They also make it possible to
  28 automatically add some trailers.
  29
  30 By default, a '<token>=<value>' or '<token>:<value>' argument given
  31 using `--trailer` will be added only if no trailer with the same
  32 (<token>, <value>) pair is already in the message. The <token> and
  33 <value> parts will be trimmed to remove starting and trailing
  34 whitespace, and the resulting trimmed <token> and <value> will appear
  35 in the message like this:
  36
  37 ------------------------------------------------
  38 token: value
  39 ------------------------------------------------
  40
  41 This means that the trimmed <token> and <value> will be separated by
  42 `': '` (one colon followed by one space).
  43
  44 By default, if there are already trailers with the same <token>, the
  45 new trailer will appear just after the last trailer with the same
  46 <token>. Otherwise it will appear at the end of the commit message
  47 part of the ouput.
  48
  49 The trailers are recognized in the input message using the following
  50 rules:
  51
  52 * only lines that contains a ':' (colon) are considered trailers,
  53
  54 * the trailer lines must all be next to each other,
  55
  56 * after them it's only possible to have some lines that contain only
  57   spaces, and then a patch; the patch part is recognized using the
  58   fact that its first line starts with '---' (three minus signs),
  59
  60 * before them there must be at least one line with only spaces.
  61
  62 Note that 'trailers' do not follow and are not intended to follow many
  63 rules for RFC 822 headers. For example they do not follow the line
  64 folding rules, the encoding rules and probably many other rules.
  65
  66 OPTIONS
  67 -------
  68 --trim-empty::
  69         If the <value> part of any trailer contains only whitespace,
  70         the whole trailer will be removed from the resulting message.
  71         This apply to existing trailers as well as new trailers.
  72
  73 --trailer <token>[(=|:)<value>]::
  74         Specify a (<token>, <value>) pair that should be applied as a
  75         trailer to the input messages. See the description of this
  76         command.
  77
  78 CONFIGURATION VARIABLES
  79 -----------------------
  80
  81 trailer.<token>.key::
  82         This `key` will be used instead of <token> in the
  83         trailer. After the last alphanumeric character, this variable
  84         can contain some non alphanumeric characters, like for example
  85         `'%'` (one percent sign), `' = '` (one space followed by one
  86         equal sign and then one space), `' #'` (one space followed by
  87         one number sign) or even just `' '` (one space), that will be
  88         used to separate the <token> from the <value> in the
  89         trailer. The default separator, `': '` (one colon followed by
  90         one space), which is the usual standard, is added only if the
  91         last character in `key` is alphanumeric, so watch out for
  92         unwanted trailing spaces in this variable.
  93
  94 trailer.<token>.where::
  95         This can be either `after`, which is the default, or
  96         `before`. If it is `before`, then a trailer with the specified
  97         <token>, will appear before, instead of after, other trailers
  98         with the same <token>, or otherwise at the beginning, instead
  99         of at the end, of all the trailers.
 100
 101 trailer.<token>.ifexist::
 102         This option makes it possible to choose what action will be
 103         performed when there is already at least one trailer with the
 104         same <token> in the message.
 105 +
 106 The valid values for this option are: `addIfDifferent` (this is the
 107 default), `addIfDifferentNeighbor`, `add`, `overwrite` or `doNothing`.
 108 +
 109 With `addIfDifferent`, a new trailer will be added only if no trailer
 110 with the same (<token>, <value>) pair is already in the message.
 111 +
 112 With `addIfDifferentNeighbor`, a new trailer will be added only if no
 113 trailer with the same (<token>, <value>) pair is above or below the line
 114 where the new trailer will be added.
 115 +
 116 With `add`, a new trailer will be added, even if some trailers with
 117 the same (<token>, <value>) pair are already in the message.
 118 +
 119 With `overwrite`, the new trailer will overwrite an existing trailer
 120 with the same <token>.
 121 +
 122 With `doNothing`, nothing will be done; that is no new trailer will be
 123 added if there is already one with the same <token> in the message.
 124
 125 trailer.<token>.ifmissing::
 126         This option makes it possible to choose what action will be
 127         performed when there is not yet any trailer with the same
 128         <token> in the message.
 129 +
 130 The valid values for this option are: `add` (this is the default) and
 131 `doNothing`.
 132 +
 133 With `add`, a new trailer will be added.
 134 +
 135 With `doNothing`, nothing will be done.
 136
 137 trailer.<token>.command::
 138         This option can be used to specify a shell command that will
 139         be used to automatically add or modify a trailer with the
 140         specified <token>.
 141 +
 142 When this option is specified, the behavior is as if a special
 143 '<token>=<value>' argument were added at the end of the command line,
 144 where <value> is taken to be the standard output of the specified
 145 command with any leading and trailing whitespace trimmed off.
 146 +
 147 If the command contains the `$ARG` string, this string will be
 148 replaced with the <value> part of an existing trailer with the same
 149 <token>, if any, before the command is launched.
 150
 151 EXAMPLES
 152 --------
 153
 154 * Configure a 'sign' trailer with a 'Signed-off-by' key, and then
 155   add two of these trailers to a message:
 156 +
 157 ------------
 158 $ git config trailer.sign.key "Signed-off-by"
 159 $ cat msg.txt
 160 subject
 161
 162 message
 163 $ cat msg.txt | git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>'
 164 subject
 165
 166 message
 167
 168 Signed-off-by: Alice <alice@example.com>
 169 Signed-off-by: Bob <bob@example.com>
 170 ------------
 171
 172 * Extract the last commit as a patch, and add a 'Cc' and a
 173   'Reviewed-by' trailer to it:
 174 +
 175 ------------
 176 $ git format-patch -1
 177 0001-foo.patch
 178 $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Reviewed-by: Bob <bob@example.com>' 0001-foo.patch >0001-bar.patch
 179 ------------
 180
 181 * Configure a 'sign' trailer with a command to automatically add a
 182   'Signed-off-by: ' with the author information only if there is no
 183   'Signed-off-by: ' already, and show how it works:
 184 +
 185 ------------
 186 $ git config trailer.sign.key "Signed-off-by: "
 187 $ git config trailer.sign.ifmissing add
 188 $ git config trailer.sign.ifexists doNothing
 189 $ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
 190 $ git interpret-trailers <<EOF
 191 > EOF
 192
 193 Signed-off-by: Bob <bob@example.com>
 194 $ git interpret-trailers <<EOF
 195 > Signed-off-by: Alice <alice@example.com>
 196 > EOF
 197
 198 Signed-off-by: Alice <alice@example.com>
 199 ------------
 200
 201 * Configure a 'fix' trailer with a key that contains a '#' and no
 202   space after this character, and show how it works:
 203 +
 204 ------------
 205 $ git config trailer.fix.key "Fix #"
 206 $ echo "subject" | git interpret-trailers --trailer fix=42
 207 subject
 208
 209 Fix #42
 210 ------------
 211
 212 * Configure a 'see' trailer with a command to show the subject of a
 213   commit that is related, and show how it works:
 214 +
 215 ------------
 216 $ git config trailer.see.key "See-also: "
 217 $ git config trailer.see.ifExists "overwrite"
 218 $ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG"
 219 $ git interpret-trailers <<EOF
 220 > subject
 221 >
 222 > message
 223 >
 224 > see: HEAD~2
 225 > EOF
 226 subject
 227
 228 message
 229
 230 See-also: fe3187489d69c4 (subject of related commit)
 231 ------------
 232
 233 * Configure a commit template with some trailers with empty values,
 234   then configure a commit-msg hook that uses 'git interpret-trailers'
 235   to remove trailers with empty values and to add a 'git-version'
 236   trailer:
 237 +
 238 ------------
 239 $ cat >commit_template.txt <<EOF
 240 > ***subject***
 241 >
 242 > ***message***
 243 >
 244 > Fixes:
 245 > Cc:
 246 > Reviewed-by:
 247 > Signed-off-by:
 248 > EOF
 249 $ git config commit.template commit_template.txt
 250 $ cat >.git/hooks/commit-msg <<EOF
 251 #!/bin/sh
 252 git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new"
 253 mv "\$1.new" "\$1"
 254 EOF
 255 $ chmod +x .git/hooks/commit-msg
 256 ------------
 257
 258 SEE ALSO
 259 --------
 260 linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1]
 261
 262 GIT
 263 ---
 264 Part of the linkgit:git[1] suite