Skip to content

Commit dfd66dd

Browse files
chriscoolgitster
chriscool
authored and
gitster
committed
Documentation: add documentation for 'git interpret-trailers'
While at it add git-interpret-trailers to "command-list.txt". Signed-off-by: Christian Couder <[email protected]> Signed-off-by: Junio C Hamano <[email protected]>
1 parent b9384ff commit dfd66dd

File tree

2 files changed

+315
-0
lines changed

2 files changed

+315
-0
lines changed

‎Documentation/git-interpret-trailers.txt

Lines changed: 314 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,314 @@
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 appended after the existing trailers only if
32+
the last trailer has a different (<token>, <value>) pair (or if there
33+
is no existing trailer). The <token> and <value> parts will be trimmed
34+
to remove starting and trailing whitespace, and the resulting trimmed
35+
<token> and <value> will appear 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 the new trailer will appear at the end of all the existing
45+
trailers. If there is no existing trailer, the new trailer will appear
46+
after the commit message part of the ouput, and, if there is no line
47+
with only spaces at the end of the commit message part, one blank line
48+
will be added before the new trailer.
49+
50+
Existing trailers are extracted from the input message by looking for
51+
a group of one or more lines that contain a colon (by default), where
52+
the group is preceded by one or more empty (or whitespace-only) lines.
53+
The group must either be at the end of the message or be the last
54+
non-whitespace lines before a line that starts with '---'. Such three
55+
minus signs start the patch part of the message.
56+
57+
When reading trailers, there can be whitespaces before and after the
58+
token, the separator and the value. There can also be whitespaces
59+
indide the token and the value.
60+
61+
Note that 'trailers' do not follow and are not intended to follow many
62+
rules for RFC 822 headers. For example they do not follow the line
63+
folding rules, the encoding rules and probably many other rules.
64+
65+
OPTIONS
66+
-------
67+
--trim-empty::
68+
If the <value> part of any trailer contains only whitespace,
69+
the whole trailer will be removed from the resulting message.
70+
This apply to existing trailers as well as new trailers.
71+
72+
--trailer <token>[(=|:)<value>]::
73+
Specify a (<token>, <value>) pair that should be applied as a
74+
trailer to the input messages. See the description of this
75+
command.
76+
77+
CONFIGURATION VARIABLES
78+
-----------------------
79+
80+
trailer.separators::
81+
This option tells which characters are recognized as trailer
82+
separators. By default only ':' is recognized as a trailer
83+
separator, except that '=' is always accepted on the command
84+
line for compatibility with other git commands.
85+
+
86+
The first character given by this option will be the default character
87+
used when another separator is not specified in the config for this
88+
trailer.
89+
+
90+
For example, if the value for this option is "%=$", then only lines
91+
using the format '<token><sep><value>' with <sep> containing '%', '='
92+
or '$' and then spaces will be considered trailers. And '%' will be
93+
the default separator used, so by default trailers will appear like:
94+
'<token>% <value>' (one percent sign and one space will appear between
95+
the token and the value).
96+
97+
trailer.where::
98+
This option tells where a new trailer will be added.
99+
+
100+
This can be `end`, which is the default, `start`, `after` or `before`.
101+
+
102+
If it is `end`, then each new trailer will appear at the end of the
103+
existing trailers.
104+
+
105+
If it is `start`, then each new trailer will appear at the start,
106+
instead of the end, of the existing trailers.
107+
+
108+
If it is `after`, then each new trailer will appear just after the
109+
last trailer with the same <token>.
110+
+
111+
If it is `before`, then each new trailer will appear just before the
112+
first trailer with the same <token>.
113+
114+
trailer.ifexists::
115+
This option makes it possible to choose what action will be
116+
performed when there is already at least one trailer with the
117+
same <token> in the message.
118+
+
119+
The valid values for this option are: `addIfDifferentNeighbor` (this
120+
is the default), `addIfDifferent`, `add`, `overwrite` or `doNothing`.
121+
+
122+
With `addIfDifferentNeighbor`, a new trailer will be added only if no
123+
trailer with the same (<token>, <value>) pair is above or below the line
124+
where the new trailer will be added.
125+
+
126+
With `addIfDifferent`, a new trailer will be added only if no trailer
127+
with the same (<token>, <value>) pair is already in the message.
128+
+
129+
With `add`, a new trailer will be added, even if some trailers with
130+
the same (<token>, <value>) pair are already in the message.
131+
+
132+
With `replace`, an existing trailer with the same <token> will be
133+
deleted and the new trailer will be added. The deleted trailer will be
134+
the closest one (with the same <token>) to the place where the new one
135+
will be added.
136+
+
137+
With `doNothing`, nothing will be done; that is no new trailer will be
138+
added if there is already one with the same <token> in the message.
139+
140+
trailer.ifmissing::
141+
This option makes it possible to choose what action will be
142+
performed when there is not yet any trailer with the same
143+
<token> in the message.
144+
+
145+
The valid values for this option are: `add` (this is the default) and
146+
`doNothing`.
147+
+
148+
With `add`, a new trailer will be added.
149+
+
150+
With `doNothing`, nothing will be done.
151+
152+
trailer.<token>.key::
153+
This `key` will be used instead of <token> in the trailer. At
154+
the end of this key, a separator can appear and then some
155+
space characters. By default the only valid separator is ':',
156+
but this can be changed using the `trailer.separators` config
157+
variable.
158+
+
159+
If there is a separator, then the key will be used instead of both the
160+
<token> and the default separator when adding the trailer.
161+
162+
trailer.<token>.where::
163+
This option takes the same values as the 'trailer.where'
164+
configuration variable and it overrides what is specified by
165+
that option for trailers with the specified <token>.
166+
167+
trailer.<token>.ifexist::
168+
This option takes the same values as the 'trailer.ifexist'
169+
configuration variable and it overrides what is specified by
170+
that option for trailers with the specified <token>.
171+
172+
trailer.<token>.ifmissing::
173+
This option takes the same values as the 'trailer.ifmissing'
174+
configuration variable and it overrides what is specified by
175+
that option for trailers with the specified <token>.
176+
177+
trailer.<token>.command::
178+
This option can be used to specify a shell command that will
179+
be called to automatically add or modify a trailer with the
180+
specified <token>.
181+
+
182+
When this option is specified, the behavior is as if a special
183+
'<token>=<value>' argument were added at the beginning of the command
184+
line, where <value> is taken to be the standard output of the
185+
specified command with any leading and trailing whitespace trimmed
186+
off.
187+
+
188+
If the command contains the `$ARG` string, this string will be
189+
replaced with the <value> part of an existing trailer with the same
190+
<token>, if any, before the command is launched.
191+
+
192+
If some '<token>=<value>' arguments are also passed on the command
193+
line, when a 'trailer.<token>.command' is configured, the command will
194+
also be executed for each of these arguments. And the <value> part of
195+
these arguments, if any, will be used to replace the `$ARG` string in
196+
the command.
197+
198+
EXAMPLES
199+
--------
200+
201+
* Configure a 'sign' trailer with a 'Signed-off-by' key, and then
202+
add two of these trailers to a message:
203+
+
204+
------------
205+
$ git config trailer.sign.key "Signed-off-by"
206+
$ cat msg.txt
207+
subject
208+
209+
message
210+
$ cat msg.txt | git interpret-trailers --trailer 'sign: Alice <[email protected]>' --trailer 'sign: Bob <[email protected]>'
211+
subject
212+
213+
message
214+
215+
Signed-off-by: Alice <[email protected]>
216+
Signed-off-by: Bob <[email protected]>
217+
------------
218+
219+
* Extract the last commit as a patch, and add a 'Cc' and a
220+
'Reviewed-by' trailer to it:
221+
+
222+
------------
223+
$ git format-patch -1
224+
0001-foo.patch
225+
$ git interpret-trailers --trailer 'Cc: Alice <[email protected]>' --trailer 'Reviewed-by: Bob <[email protected]>' 0001-foo.patch >0001-bar.patch
226+
------------
227+
228+
* Configure a 'sign' trailer with a command to automatically add a
229+
'Signed-off-by: ' with the author information only if there is no
230+
'Signed-off-by: ' already, and show how it works:
231+
+
232+
------------
233+
$ git config trailer.sign.key "Signed-off-by: "
234+
$ git config trailer.sign.ifmissing add
235+
$ git config trailer.sign.ifexists doNothing
236+
$ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
237+
$ git interpret-trailers <<EOF
238+
> EOF
239+
240+
Signed-off-by: Bob <[email protected]>
241+
$ git interpret-trailers <<EOF
242+
> Signed-off-by: Alice <[email protected]>
243+
> EOF
244+
245+
Signed-off-by: Alice <[email protected]>
246+
------------
247+
248+
* Configure a 'fix' trailer with a key that contains a '#' and no
249+
space after this character, and show how it works:
250+
+
251+
------------
252+
$ git config trailer.separators ":#"
253+
$ git config trailer.fix.key "Fix #"
254+
$ echo "subject" | git interpret-trailers --trailer fix=42
255+
subject
256+
257+
Fix #42
258+
------------
259+
260+
* Configure a 'see' trailer with a command to show the subject of a
261+
commit that is related, and show how it works:
262+
+
263+
------------
264+
$ git config trailer.see.key "See-also: "
265+
$ git config trailer.see.ifExists "replace"
266+
$ git config trailer.see.ifMissing "doNothing"
267+
$ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG"
268+
$ git interpret-trailers <<EOF
269+
> subject
270+
>
271+
> message
272+
>
273+
> see: HEAD~2
274+
> EOF
275+
subject
276+
277+
message
278+
279+
See-also: fe3187489d69c4 (subject of related commit)
280+
------------
281+
282+
* Configure a commit template with some trailers with empty values
283+
(using sed to show and keep the trailing spaces at the end of the
284+
trailers), then configure a commit-msg hook that uses
285+
'git interpret-trailers' to remove trailers with empty values and
286+
to add a 'git-version' trailer:
287+
+
288+
------------
289+
$ sed -e 's/ Z$/ /' >commit_template.txt <<EOF
290+
> ***subject***
291+
>
292+
> ***message***
293+
>
294+
> Fixes: Z
295+
> Cc: Z
296+
> Reviewed-by: Z
297+
> Signed-off-by: Z
298+
> EOF
299+
$ git config commit.template commit_template.txt
300+
$ cat >.git/hooks/commit-msg <<EOF
301+
> #!/bin/sh
302+
> git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new"
303+
> mv "\$1.new" "\$1"
304+
> EOF
305+
$ chmod +x .git/hooks/commit-msg
306+
------------
307+
308+
SEE ALSO
309+
--------
310+
linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1]
311+
312+
GIT
313+
---
314+
Part of the linkgit:git[1] suite

‎command-list.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ git-imap-send foreignscminterface
6262
git-index-pack plumbingmanipulators
6363
git-init mainporcelain common
6464
git-instaweb ancillaryinterrogators
65+
git-interpret-trailers purehelpers
6566
gitk mainporcelain
6667
git-log mainporcelain common
6768
git-ls-files plumbinginterrogators

0 commit comments

Comments
 (0)