diff options
Diffstat (limited to 'git-interpret-trailers.html')
| -rw-r--r-- | git-interpret-trailers.html | 137 |
1 files changed, 79 insertions, 58 deletions
diff --git a/git-interpret-trailers.html b/git-interpret-trailers.html index 2d00f1a8b..d26868bc5 100644 --- a/git-interpret-trailers.html +++ b/git-interpret-trailers.html @@ -759,54 +759,75 @@ git-interpret-trailers(1) Manual Page <div class="sect1">
<h2 id="_description">DESCRIPTION</h2>
<div class="sectionbody">
-<div class="paragraph"><p>Help parsing or adding <em>trailers</em> lines, that look similar to RFC 822 e-mail
+<div class="paragraph"><p>Add or parse <em>trailer</em> lines that look similar to RFC 822 e-mail
headers, at the end of the otherwise free-form part of a commit
-message.</p></div>
-<div class="paragraph"><p>This command reads some patches or commit messages from either the
-<file> arguments or the standard input if no <file> is specified. If
-<code>--parse</code> is specified, the output consists of the parsed trailers.</p></div>
-<div class="paragraph"><p>Otherwise, this command applies the arguments passed using the
-<code>--trailer</code> option, if any, to the commit message part of each input
-file. The result is emitted on the standard output.</p></div>
+message. For example, in the following commit message</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>subject
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+Signed-off-by: Alice <alice@example.com>
+Signed-off-by: Bob <bob@example.com></code></pre>
+</div></div>
+<div class="paragraph"><p>the last two lines starting with "Signed-off-by" are trailers.</p></div>
+<div class="paragraph"><p>This command reads commit messages from either the
+<file> arguments or the standard input if no <file> is specified.
+If <code>--parse</code> is specified, the output consists of the parsed trailers.
+Otherwise, this command applies the arguments passed using the
+<code>--trailer</code> option, if any, to each input file. The result is emitted on the
+standard output.</p></div>
+<div class="paragraph"><p>This command can also operate on the output of <a href="git-format-patch.html">git-format-patch(1)</a>,
+which is more elaborate than a plain commit message. Namely, such output
+includes a commit message (as above), a "---" divider line, and a patch part.
+For these inputs, the divider and patch parts are not modified by
+this command and are emitted as is on the output, unless
+<code>--no-divider</code> is specified.</p></div>
<div class="paragraph"><p>Some configuration variables control the way the <code>--trailer</code> arguments
-are applied to each commit message and the way any existing trailer in
-the commit message is changed. They also make it possible to
+are applied to each input and the way any existing trailer in
+the input is changed. They also make it possible to
automatically add some trailers.</p></div>
<div class="paragraph"><p>By default, a <em><token>=<value></em> or <em><token>:<value></em> argument given
using <code>--trailer</code> will be appended after the existing trailers only if
the last trailer has a different (<token>, <value>) pair (or if there
is no existing trailer). The <token> and <value> parts will be trimmed
to remove starting and trailing whitespace, and the resulting trimmed
-<token> and <value> will appear in the message like this:</p></div>
+<token> and <value> will appear in the output like this:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>token: value</code></pre>
</div></div>
<div class="paragraph"><p>This means that the trimmed <token> and <value> will be separated by
-<code>': '</code> (one colon followed by one space).</p></div>
+<code>': '</code> (one colon followed by one space). For convenience, the <token> can be a
+shortened string key (e.g., "sign") instead of the full string which should
+appear before the separator on the output (e.g., "Signed-off-by"). This can be
+configured using the <em>trailer.<token>.key</em> configuration variable.</p></div>
<div class="paragraph"><p>By default the new trailer will appear at the end of all the existing
trailers. If there is no existing trailer, the new trailer will appear
-after the commit message part of the output, and, if there is no line
-with only spaces at the end of the commit message part, one blank line
-will be added before the new trailer.</p></div>
-<div class="paragraph"><p>Existing trailers are extracted from the input message by looking for
+at the end of the input. A blank line will be added before the new
+trailer if there isn’t one already.</p></div>
+<div class="paragraph"><p>Existing trailers are extracted from the input by looking for
a group of one or more lines that (i) is all trailers, or (ii) contains at
least one Git-generated or user-configured trailer and consists of at
least 25% trailers.
The group must be preceded by one or more empty (or whitespace-only) lines.
-The group must either be at the end of the message or be the last
+The group must either be at the end of the input or be the last
non-whitespace lines before a line that starts with <em>---</em> (followed by a
-space or the end of the line). Such three minus signs start the patch
-part of the message. See also <code>--no-divider</code> below.</p></div>
+space or the end of the line).</p></div>
<div class="paragraph"><p>When reading trailers, there can be no whitespace before or inside the
-token, but any number of regular space and tab characters are allowed
-between the token and the separator. There can be whitespaces before,
-inside or after the value. The value may be split over multiple lines
+<token>, but any number of regular space and tab characters are allowed
+between the <token> and the separator. There can be whitespaces before,
+inside or after the <value>. The <value> may be split over multiple lines
with each subsequent line starting with at least one whitespace, like
-the "folding" in RFC 822.</p></div>
-<div class="paragraph"><p>Note that <em>trailers</em> do not follow and are not intended to follow many
-rules for RFC 822 headers. For example they do not follow
-the encoding rules and probably many other rules.</p></div>
+the "folding" in RFC 822. Example:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>token: This is a very long value, with spaces and
+ newlines in it.</code></pre>
+</div></div>
+<div class="paragraph"><p>Note that trailers do not follow (nor are they intended to follow) many of the
+rules for RFC 822 headers. For example they do not follow the encoding rule.</p></div>
</div>
</div>
<div class="sect1">
@@ -827,7 +848,7 @@ the encoding rules and probably many other rules.</p></div> <dd>
<p>
If the <value> part of any trailer contains only whitespace,
- the whole trailer will be removed from the resulting message.
+ the whole trailer will be removed from the output.
This applies to existing trailers as well as new trailers.
</p>
</dd>
@@ -837,7 +858,7 @@ the encoding rules and probably many other rules.</p></div> <dd>
<p>
Specify a (<token>, <value>) pair that should be applied as a
- trailer to the input messages. See the description of this
+ trailer to the inputs. See the description of this
command.
</p>
</dd>
@@ -865,7 +886,7 @@ the encoding rules and probably many other rules.</p></div> <dd>
<p>
Specify what action will be performed when there is already at
- least one trailer with the same <token> in the message. A setting
+ least one trailer with the same <token> in the input. A setting
provided with <em>--if-exists</em> overrides all configuration variables
and applies to all <em>--trailer</em> options until the next occurrence of
<em>--if-exists</em> or <em>--no-if-exists</em>. Possible actions are <code>addIfDifferent</code>,
@@ -881,7 +902,7 @@ the encoding rules and probably many other rules.</p></div> <dd>
<p>
Specify what action will be performed when there is no other
- trailer with the same <token> in the message. A setting
+ trailer with the same <token> in the input. A setting
provided with <em>--if-missing</em> overrides all configuration variables
and applies to all <em>--trailer</em> options until the next occurrence of
<em>--if-missing</em> or <em>--no-if-missing</em>. Possible actions are <code>doNothing</code>
@@ -985,7 +1006,7 @@ trailer.ifexists <p>
This option makes it possible to choose what action will be
performed when there is already at least one trailer with the
- same <token> in the message.
+ same <token> in the input.
</p>
<div class="paragraph"><p>The valid values for this option are: <code>addIfDifferentNeighbor</code> (this
is the default), <code>addIfDifferent</code>, <code>add</code>, <code>replace</code> or <code>doNothing</code>.</p></div>
@@ -993,15 +1014,15 @@ is the default), <code>addIfDifferent</code>, <code>add</code>, <code>replace</c trailer with the same (<token>, <value>) pair is above or below the line
where the new trailer will be added.</p></div>
<div class="paragraph"><p>With <code>addIfDifferent</code>, a new trailer will be added only if no trailer
-with the same (<token>, <value>) pair is already in the message.</p></div>
+with the same (<token>, <value>) pair is already in the input.</p></div>
<div class="paragraph"><p>With <code>add</code>, a new trailer will be added, even if some trailers with
-the same (<token>, <value>) pair are already in the message.</p></div>
+the same (<token>, <value>) pair are already in the input.</p></div>
<div class="paragraph"><p>With <code>replace</code>, an existing trailer with the same <token> will be
deleted and the new trailer will be added. The deleted trailer will be
the closest one (with the same <token>) to the place where the new one
will be added.</p></div>
<div class="paragraph"><p>With <code>doNothing</code>, nothing will be done; that is no new trailer will be
-added if there is already one with the same <token> in the message.</p></div>
+added if there is already one with the same <token> in the input.</p></div>
</dd>
<dt class="hdlist1">
trailer.ifmissing
@@ -1010,7 +1031,7 @@ trailer.ifmissing <p>
This option makes it possible to choose what action will be
performed when there is not yet any trailer with the same
- <token> in the message.
+ <token> in the input.
</p>
<div class="paragraph"><p>The valid values for this option are: <code>add</code> (this is the default) and
<code>doNothing</code>.</p></div>
@@ -1066,13 +1087,13 @@ trailer.<token>.command </dt>
<dd>
<p>
+ Deprecated in favor of <em>trailer.<token>.cmd</em>.
This option behaves in the same way as <em>trailer.<token>.cmd</em>, except
that it doesn’t pass anything as argument to the specified command.
Instead the first occurrence of substring $ARG is replaced by the
- value that would be passed as argument.
+ <value> that would be passed as argument.
</p>
-<div class="paragraph"><p>The <em>trailer.<token>.command</em> option has been deprecated in favor of
-<em>trailer.<token>.cmd</em> due to the fact that $ARG in the user’s command is
+<div class="paragraph"><p>Note that $ARG in the user’s command is
only replaced once and that the original way of replacing $ARG is not safe.</p></div>
<div class="paragraph"><p>When both <em>trailer.<token>.cmd</em> and <em>trailer.<token>.command</em> are given
for the same <token>, <em>trailer.<token>.cmd</em> is used and
@@ -1083,10 +1104,10 @@ trailer.<token>.cmd </dt>
<dd>
<p>
- This option can be used to specify a shell command that will be called:
+ This option can be used to specify a shell command that will be called
once to automatically add a trailer with the specified <token>, and then
- each time a <em>--trailer <token>=<value></em> argument to modify the <value> of
- the trailer that this option would produce.
+ called each time a <em>--trailer <token>=<value></em> argument is specified to
+ modify the <value> of the trailer that this option would produce.
</p>
<div class="paragraph"><p>When the specified command is first called to add a trailer
with the specified <token>, the behavior is as if a special
@@ -1111,7 +1132,7 @@ from the <value> passed in the <em>--trailer <token>=<value></ <li>
<p>
Configure a <em>sign</em> trailer with a <em>Signed-off-by</em> key, and then
- add two of these trailers to a message:
+ add two of these trailers to a commit message file:
</p>
<div class="listingblock">
<div class="content">
@@ -1119,11 +1140,11 @@ Configure a <em>sign</em> trailer with a <em>Signed-off-by</em> key, and then $ cat msg.txt
subject
-message
+body text
$ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt
subject
-message
+body text
Signed-off-by: Alice <alice@example.com>
Signed-off-by: Bob <bob@example.com></code></pre>
@@ -1131,21 +1152,21 @@ Signed-off-by: Bob <bob@example.com></code></pre> </li>
<li>
<p>
-Use the <code>--in-place</code> option to edit a message file in place:
+Use the <code>--in-place</code> option to edit a commit message file in place:
</p>
<div class="listingblock">
<div class="content">
<pre><code>$ cat msg.txt
subject
-message
+body text
Signed-off-by: Bob <bob@example.com>
$ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt
$ cat msg.txt
subject
-message
+body text
Signed-off-by: Bob <bob@example.com>
Acked-by: Alice <alice@example.com></code></pre>
@@ -1174,7 +1195,7 @@ Configure a <em>sign</em> trailer with a command to automatically add a <pre><code>$ cat msg1.txt
subject
-message
+body text
$ git config trailer.sign.key "Signed-off-by: "
$ git config trailer.sign.ifmissing add
$ git config trailer.sign.ifexists doNothing
@@ -1182,19 +1203,19 @@ $ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config us $ git interpret-trailers --trailer sign <msg1.txt
subject
-message
+body text
Signed-off-by: Bob <bob@example.com>
$ cat msg2.txt
subject
-message
+body text
Signed-off-by: Alice <alice@example.com>
$ git interpret-trailers --trailer sign <msg2.txt
subject
-message
+body text
Signed-off-by: Alice <alice@example.com></code></pre>
</div></div>
@@ -1228,14 +1249,14 @@ test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || t $ cat msg.txt
subject
-message
+body text
$ git config trailer.help.key "Helped-by: "
$ git config trailer.help.ifExists "addIfDifferentNeighbor"
$ git config trailer.help.cmd "~/bin/glog-find-author"
$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt
subject
-message
+body text
Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Christian Couder <christian.couder@gmail.com></code></pre>
@@ -1255,14 +1276,14 @@ test -n "$1" && git log --grep "$1" --pretty=reference -1 || true $ cat msg.txt
subject
-message
+body text
$ git config trailer.ref.key "Reference-to: "
$ git config trailer.ref.ifExists "replace"
$ git config trailer.ref.cmd "~/bin/glog-grep"
$ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt
subject
-message
+body text
Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)</code></pre>
</div></div>
@@ -1277,7 +1298,7 @@ Configure a <em>see</em> trailer with a command to show the subject of a <pre><code>$ cat msg.txt
subject
-message
+body text
see: HEAD~2
$ cat ~/bin/glog-ref
@@ -1290,7 +1311,7 @@ $ git config trailer.see.cmd "glog-ref" $ git interpret-trailers --trailer=see <msg.txt
subject
-message
+body text
See-also: fe3187489d69c4 (subject of related commit)</code></pre>
</div></div>
@@ -1343,7 +1364,7 @@ $ chmod +x .git/hooks/commit-msg</code></pre> <div id="footer">
<div id="footer-text">
Last updated
- 2023-05-15 16:02:03 PDT
+ 2023-06-23 13:24:09 PDT
</div>
</div>
</body>
|