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