@matheusbsbs / matheus-bagliano / commits / dfd66ddf5a

Documentation: add documentation for 'git interpret-trailers'

While at it add git-interpret-trailers to "command-list.txt". Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Christian Couder committed Oct 13, 2014 at 20:16 UTC dfd66ddf5aa9aacc06ed38a9ee2cc15a4f2d4896
2 files changed +315
Documentation/git-interpret-trailers.txt new
+314
@@ -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 <alice@example.com>' --trailer 'sign: Bob <bob@example.com>'
211 +subject
212 +
213 +message
214 +
215 +Signed-off-by: Alice <alice@example.com>
216 +Signed-off-by: Bob <bob@example.com>
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 <alice@example.com>' --trailer 'Reviewed-by: Bob <bob@example.com>' 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 <bob@example.com>
241 +$ git interpret-trailers <<EOF
242 +> Signed-off-by: Alice <alice@example.com>
243 +> EOF
244 +
245 +Signed-off-by: Alice <alice@example.com>
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
+1
@@ -62,6 +62,7 @@ git-imap-send foreignscminterface
62 git-index-pack plumbingmanipulators
63 git-init mainporcelain common
64 git-instaweb ancillaryinterrogators
65 +git-interpret-trailers purehelpers
66 gitk mainporcelain
67 git-log mainporcelain common
68 git-ls-files plumbinginterrogators