[PATCH 00/11] docs: interpret-trailers: reword and add examples

[PATCH 00/11] docs: interpret-trailers: reword and add examples

[Linus Arver via GitGitGadget]

This series makes some small improvements to the docs for
git-interpret-trailers. The intent is to make it easier to read for
beginners who have never used this command before.

Linus Arver (11):
  doc: trailer: fix grammar
  doc: trailer: swap verb order
  doc: trailer: --no-divider: more precise language
  doc: trailer: explain "commit mesage part" on first usage
  doc: trailer: remove redundant phrasing
  doc: trailer: trailer.<token>.cmd: add missing verb phrase
  doc: trailer: use angle brackets for <token> and <value>
  doc: trailer.<token>.command: refer to existing example
  doc: trailer.<token>.command: emphasize deprecation
  doc: trailer: mention 'key' in DESCRIPTION
  doc: trailer: add more examples in DESCRIPTION

 Documentation/git-interpret-trailers.txt | 62 +++++++++++++++---------
 1 file changed, 40 insertions(+), 22 deletions(-)


base-commit: 69c786637d7a7fe3b2b8f7d989af095f5f49c3a8
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1506%2Flistx%2Fdoc-trailer-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1506/listx/doc-trailer-v1
Pull-Request: https://github.com/git/git/pull/1506
-- 
gitgitgadget

[PATCH 01/11] doc: trailer: fix grammar

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 22ff3a603e0..e695977fbfa 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -14,7 +14,7 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail
+Parse or add 'trailer' lines, that look similar to RFC 822 e-mail
 headers, at the end of the otherwise free-form part of a commit
 message.
 
-- 
gitgitgadget

Re: [PATCH 01/11] doc: trailer: fix grammar

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Linus Arver <linusa@google.com>
>
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>  Documentation/git-interpret-trailers.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
> index 22ff3a603e0..e695977fbfa 100644
> --- a/Documentation/git-interpret-trailers.txt
> +++ b/Documentation/git-interpret-trailers.txt
> @@ -14,7 +14,7 @@ SYNOPSIS
>  
>  DESCRIPTION
>  -----------
> -Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail
> +Parse or add 'trailer' lines, that look similar to RFC 822 e-mail
>  headers, at the end of the otherwise free-form part of a commit
>  message.

Is that a grammatically incorrect sentence?

The command does help doing these two things, but we can say the
command does these two things without closing clarity, so I do not
have an objection to the updated text (the only "ungrammatical" part
may be that ", that look" should probably be "that look"), but I am
not sure if "fix grammar" is a good explanation for this commit.

Re: [PATCH 01/11] doc: trailer: fix grammar

[Linus Arver]

Junio C Hamano <gitster@pobox.com> writes:

> "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

>> From: Linus Arver <linusa@google.com>

>> Signed-off-by: Linus Arver <linusa@google.com>
>> ---
>>   Documentation/git-interpret-trailers.txt | 2 +-
>>   1 file changed, 1 insertion(+), 1 deletion(-)

>> diff --git a/Documentation/git-interpret-trailers.txt  
>> b/Documentation/git-interpret-trailers.txt
>> index 22ff3a603e0..e695977fbfa 100644
>> --- a/Documentation/git-interpret-trailers.txt
>> +++ b/Documentation/git-interpret-trailers.txt
>> @@ -14,7 +14,7 @@ SYNOPSIS

>>   DESCRIPTION
>>   -----------
>> -Help parsing or adding 'trailers' lines, that look similar to RFC 822  
>> e-mail
>> +Parse or add 'trailer' lines, that look similar to RFC 822 e-mail
>>   headers, at the end of the otherwise free-form part of a commit
>>   message.

> Is that a grammatically incorrect sentence?

I think so. If we remove the dependent clauses starting with "that look
similar ...", we just get

     Help parsing or adding 'trailers' lines

which cannot stand on its own as an independent clause. The correct
version would be

     Help parse or add 'trailers' lines

which is what I first considered. However the auxiliary verb "help" here
doesn't really mean much, because the interpret-trailers builtin already
is _the_ authority for parsing or adding trailer lines, so I opted to
remove it in my patch.

> The command does help doing these two things, but we can say the
> command does these two things without closing clarity, so I do not
> have an objection to the updated text

Exactly (I think you meant s/closing/losing here).

> (the only "ungrammatical" part
> may be that ", that look" should probably be "that look"), but I am
> not sure if "fix grammar" is a good explanation for this commit.

I think punctuation (especially with commas) can be pretty wide-ranging
in terms of what is acceptable or not in terms of grammar. But looking
at it again I like your version with the comma removed. I'll make the
change locally for a v2 series.

Re: [PATCH 01/11] doc: trailer: fix grammar

[Junio C Hamano]

Linus Arver <linusa@google.com> writes:

> which cannot stand on its own as an independent clause. The correct
> version would be
>
>     Help parse or add 'trailers' lines

You're indeed correct.  Thanks.

[PATCH 02/11] doc: trailer: swap verb order

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

This matches the order already used in the NAME section.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index e695977fbfa..593bc1a1f4e 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -14,7 +14,7 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Parse or add 'trailer' lines, that look similar to RFC 822 e-mail
+Add or parse 'trailer' lines, that look similar to RFC 822 e-mail
 headers, at the end of the otherwise free-form part of a commit
 message.
 
-- 
gitgitgadget

Re: [PATCH 02/11] doc: trailer: swap verb order

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Linus Arver <linusa@google.com>
>
> This matches the order already used in the NAME section.

The change makes sense, and the explanation above is also clear.

>
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>  Documentation/git-interpret-trailers.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
> index e695977fbfa..593bc1a1f4e 100644
> --- a/Documentation/git-interpret-trailers.txt
> +++ b/Documentation/git-interpret-trailers.txt
> @@ -14,7 +14,7 @@ SYNOPSIS
>  
>  DESCRIPTION
>  -----------
> -Parse or add 'trailer' lines, that look similar to RFC 822 e-mail
> +Add or parse 'trailer' lines, that look similar to RFC 822 e-mail
>  headers, at the end of the otherwise free-form part of a commit
>  message.

[PATCH 03/11] doc: trailer: --no-divider: more precise language

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

This uses the phrase "commit message part" instead of "commit message".

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 593bc1a1f4e..3e60a6eaabc 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -131,7 +131,7 @@ OPTIONS
 
 --no-divider::
 	Do not treat `---` as the end of the commit message. Use this
-	when you know your input contains just the commit message itself
+	when you know your input contains only the commit message part
 	(and not an email or the output of `git format-patch`).
 
 CONFIGURATION VARIABLES
-- 
gitgitgadget

Re: [PATCH 03/11] doc: trailer: --no-divider: more precise language

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Linus Arver <linusa@google.com>
>
> This uses the phrase "commit message part" instead of "commit message".

That much anybody can see from the patch.  The question is, is the
updated phrasing "more precise"?

To me (a non native English speaker), both the original and the
updated text say mostly the same thing, but the added word "part"
actually made my reading hiccup a bit.

It may be because for the word "part" to sit well, it is not clear
enough what "your input" consists of in the updated text.  If it
were somehow clear to readers that "your input" consists of "commit
message part", "some other message part", and "yet another message
part", divided with a three-dash lines, then "commit message part"
might become a good phrasing.  An email can have any garbage in it,
a format-patfch output has commit message and patch text.  So "only
the commit message" or "just the commit message" without "itself"
may be an improvement in clarity, in the same sense that 01/11 made
a sentence say the same sense with a fewer words, but personally I
do not find the posted patch as-is that much of an improvement.

I dunno.

> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>  Documentation/git-interpret-trailers.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
> index 593bc1a1f4e..3e60a6eaabc 100644
> --- a/Documentation/git-interpret-trailers.txt
> +++ b/Documentation/git-interpret-trailers.txt
> @@ -131,7 +131,7 @@ OPTIONS
>  
>  --no-divider::
>  	Do not treat `---` as the end of the commit message. Use this
> -	when you know your input contains just the commit message itself
> +	when you know your input contains only the commit message part
>  	(and not an email or the output of `git format-patch`).
>  
>  CONFIGURATION VARIABLES

[PATCH 04/11] doc: trailer: explain "commit mesage part" on first usage

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

This phrase is used for the first time here, but it's not explained what
it means. So explain it just in case it's not obvious.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 3e60a6eaabc..7d6e250f37e 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -22,9 +22,9 @@ This command reads some patches or commit messages from either the
 <file> arguments or the standard input if no <file> is specified. If
 `--parse` is specified, the output consists of the parsed trailers.
 
-Otherwise, this command applies the arguments passed using the
-`--trailer` option, if any, to the commit message part of each input
-file. The result is emitted on the standard output.
+Otherwise, this command applies the arguments passed using the `--trailer`
+option, if any, to the commit message part of each input file (as opposed to the
+patch part following a '---' divider). The result is emitted to standard output.
 
 Some configuration variables control the way the `--trailer` arguments
 are applied to each commit message and the way any existing trailer in
-- 
gitgitgadget

Re: [PATCH 04/11] doc: trailer: explain "commit mesage part" on first usage

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Linus Arver <linusa@google.com>
>
> This phrase is used for the first time here, but it's not explained what
> it means. So explain it just in case it's not obvious.

03+04 should be a single patch (as I read more, I may find other
steps should also be in a single step, I dunno); otherwise it would
waste reviewer's time (just like I did thinking and writing about
03/11).

Or just drop "part".  "git cat-file commit HEAD | sed -e '1,/^$/d'"
is a good material to use with "--no-divider" because it only has
the "commit message".  The "part" implies you first had something
that has both "commit message" and something else and you split
that combination into two (or more) parts.  But that does not have
to be the case.  I think that made 03/11 confusing, at least to me.

> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>  Documentation/git-interpret-trailers.txt | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
> index 3e60a6eaabc..7d6e250f37e 100644
> --- a/Documentation/git-interpret-trailers.txt
> +++ b/Documentation/git-interpret-trailers.txt
> @@ -22,9 +22,9 @@ This command reads some patches or commit messages from either the
>  <file> arguments or the standard input if no <file> is specified. If
>  `--parse` is specified, the output consists of the parsed trailers.
>  
> -Otherwise, this command applies the arguments passed using the
> -`--trailer` option, if any, to the commit message part of each input
> -file. The result is emitted on the standard output.
> +Otherwise, this command applies the arguments passed using the `--trailer`
> +option, if any, to the commit message part of each input file (as opposed to the
> +patch part following a '---' divider). The result is emitted to standard output.
>  
>  Some configuration variables control the way the `--trailer` arguments
>  are applied to each commit message and the way any existing trailer in

Re: [PATCH 04/11] doc: trailer: explain "commit mesage part" on first usage

[Linus Arver]

Junio C Hamano <gitster@pobox.com> writes:

> "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

>> From: Linus Arver <linusa@google.com>

>> This phrase is used for the first time here, but it's not explained what
>> it means. So explain it just in case it's not obvious.

> 03+04 should be a single patch

Agreed.

> otherwise it would
> waste reviewer's time (just like I did thinking and writing about
> 03/11).

Thank you for the pointer. I will be more careful about patch order
moving forward.

> Or just drop "part".  "git cat-file commit HEAD | sed -e '1,/^$/d'"
> is a good material to use with "--no-divider" because it only has
> the "commit message".  The "part" implies you first had something
> that has both "commit message" and something else and you split
> that combination into two (or more) parts.  But that does not have
> to be the case.  I think that made 03/11 confusing, at least to me.

Looking back, I don't think I had a good grasp of what "commit message
part" meant. When I wrote this series I thought "commit message part"
meant everything in the output of git-format-patch until hitting the
"---" divider. But as you point out in your

     git cat-file commit HEAD | sed -e '1,/^$/d'

example, technically there is never any ambiguity of what the commit
message contains (it only contains a commit message, not a "commit
message part" and a separate "patch part"). And the output of
git-format-patch is a patch (which contains the commit message and also
other things), not a commit message with different subparts. I was
operating under this flawed understanding, oops.

That being said, there are several instances in the DESCRIPTION section
when we use the "commit message part" phrasing (as opposed to just
"commit message"). I am leaning toward just dropping "part" as you
suggested. Also, I think we should add an explanation of how
git-interpret-trailers sees the incoming text, how it gives special
treatment to a "---" divider line, how it uses this line to mark off a
commit message part (and then uses this part as the default location of
adding trailers, unless specifying a "--no-divider" flag), etc. This
could be in a revamped 03+04 patch, or perhaps left out until another
day. I'll see what I can do in v2.

>> Signed-off-by: Linus Arver <linusa@google.com>
>> ---
>>   Documentation/git-interpret-trailers.txt | 6 +++---
>>   1 file changed, 3 insertions(+), 3 deletions(-)

>> diff --git a/Documentation/git-interpret-trailers.txt  
>> b/Documentation/git-interpret-trailers.txt
>> index 3e60a6eaabc..7d6e250f37e 100644
>> --- a/Documentation/git-interpret-trailers.txt
>> +++ b/Documentation/git-interpret-trailers.txt
>> @@ -22,9 +22,9 @@ This command reads some patches or commit messages  
>> from either the
>>   <file> arguments or the standard input if no <file> is specified. If
>>   `--parse` is specified, the output consists of the parsed trailers.

>> -Otherwise, this command applies the arguments passed using the
>> -`--trailer` option, if any, to the commit message part of each input
>> -file. The result is emitted on the standard output.
>> +Otherwise, this command applies the arguments passed using the  
>> `--trailer`
>> +option, if any, to the commit message part of each input file (as  
>> opposed to the
>> +patch part following a '---' divider). The result is emitted to  
>> standard output.

>>   Some configuration variables control the way the `--trailer` arguments
>>   are applied to each commit message and the way any existing trailer in

[PATCH 05/11] doc: trailer: remove redundant phrasing

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

The phrase "many rules" gets essentially repeated again with "many other
rules", so remove this repetition.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 7d6e250f37e..e80a9cd161b 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -68,9 +68,8 @@ 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.
 
-Note that 'trailers' 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.
+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.
 
 OPTIONS
 -------
-- 
gitgitgadget

[PATCH 06/11] doc: trailer: trailer.<token>.cmd: add missing verb phrase

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

The phrase "is specified" is implied. Make it explicit.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index e80a9cd161b..c4675d9d3bb 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -248,10 +248,10 @@ for the same <token>, 'trailer.<token>.cmd' is used and
 'trailer.<token>.command' is ignored.
 
 trailer.<token>.cmd::
-	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 '--trailer <token>=<value>' argument to modify the <value> of
-	the trailer that this option would produce.
+	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 called
+	each time a '--trailer <token>=<value>' argument is specified to modify the
+	<value> of the trailer that this option would produce.
 +
 When the specified command is first called to add a trailer
 with the specified <token>, the behavior is as if a special
-- 
gitgitgadget

Re: [PATCH 06/11] doc: trailer: trailer.<token>.cmd: add missing verb phrase

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Linus Arver <linusa@google.com>
>
> The phrase "is specified" is implied. Make it explicit.

Makes sense.  Calling it "implied" is generous ;-)  Isn't the
original just outright ungrammatical?

>
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>  Documentation/git-interpret-trailers.txt | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
> index e80a9cd161b..c4675d9d3bb 100644
> --- a/Documentation/git-interpret-trailers.txt
> +++ b/Documentation/git-interpret-trailers.txt
> @@ -248,10 +248,10 @@ for the same <token>, 'trailer.<token>.cmd' is used and
>  'trailer.<token>.command' is ignored.
>  
>  trailer.<token>.cmd::
> -	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 '--trailer <token>=<value>' argument to modify the <value> of
> -	the trailer that this option would produce.
> +	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 called
> +	each time a '--trailer <token>=<value>' argument is specified to modify the
> +	<value> of the trailer that this option would produce.
>  +
>  When the specified command is first called to add a trailer
>  with the specified <token>, the behavior is as if a special

Re: [PATCH 06/11] doc: trailer: trailer.<token>.cmd: add missing verb phrase

[Linus Arver]

Junio C Hamano <gitster@pobox.com> writes:

> "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

>> From: Linus Arver <linusa@google.com>

>> The phrase "is specified" is implied. Make it explicit.

> Makes sense.  Calling it "implied" is generous ;-)

Haha yes, I suppose so. I wrote "implied" because supplying the
(missing) phrase "is specified" was the only way I could make sense of
the existing wording.

> Isn't the
> original just outright ungrammatical?

Indeed.

Should I combine 01+06 together?



>> Signed-off-by: Linus Arver <linusa@google.com>
>> ---
>>   Documentation/git-interpret-trailers.txt | 8 ++++----
>>   1 file changed, 4 insertions(+), 4 deletions(-)

>> diff --git a/Documentation/git-interpret-trailers.txt  
>> b/Documentation/git-interpret-trailers.txt
>> index e80a9cd161b..c4675d9d3bb 100644
>> --- a/Documentation/git-interpret-trailers.txt
>> +++ b/Documentation/git-interpret-trailers.txt
>> @@ -248,10 +248,10 @@ for the same <token>, 'trailer.<token>.cmd' is  
>> used and
>>   'trailer.<token>.command' is ignored.

>>   trailer.<token>.cmd::
>> -	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 '--trailer <token>=<value>' argument to modify the <value>  
>> of
>> -	the trailer that this option would produce.
>> +	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  
>> called
>> +	each time a '--trailer <token>=<value>' argument is specified to  
>> modify the
>> +	<value> of the trailer that this option would produce.
>>   +
>>   When the specified command is first called to add a trailer
>>   with the specified <token>, the behavior is as if a special

Re: [PATCH 06/11] doc: trailer: trailer.<token>.cmd: add missing verb phrase

[Junio C Hamano]

Linus Arver <linusa@google.com> writes:

>> Isn't the
>> original just outright ungrammatical?
>
> Indeed.
>
> Should I combine 01+06 together?

Either is fine.  Thanks.

[PATCH 07/11] doc: trailer: use angle brackets for <token> and <value>

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

We already use angle brackets elsewhere, so this makes things more
consistent.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index c4675d9d3bb..ac448fd732e 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -62,9 +62,9 @@ space or the end of the line). Such three minus signs start the patch
 part of the message. See also `--no-divider` below.
 
 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.
 
-- 
gitgitgadget

Re: [PATCH 07/11] doc: trailer: use angle brackets for <token> and <value>

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Linus Arver <linusa@google.com>
>
> We already use angle brackets elsewhere, so this makes things more
> consistent.

Excellent.

>
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>  Documentation/git-interpret-trailers.txt | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
> index c4675d9d3bb..ac448fd732e 100644
> --- a/Documentation/git-interpret-trailers.txt
> +++ b/Documentation/git-interpret-trailers.txt
> @@ -62,9 +62,9 @@ space or the end of the line). Such three minus signs start the patch
>  part of the message. See also `--no-divider` below.
>  
>  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.

[PATCH 08/11] doc: trailer.<token>.command: refer to existing example

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index ac448fd732e..5ca758e363f 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -234,10 +234,11 @@ trailer.<token>.ifmissing::
 	that option for trailers with the specified <token>.
 
 trailer.<token>.command::
-	This option behaves in the same way as 'trailer.<token>.cmd', 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.
+	This option behaves in the
+	same way as 'trailer.<token>.cmd', 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> from the trailer. See the
+	'trailer.see.command' trailer example in the "EXAMPLES" section below.
 +
 The 'trailer.<token>.command' option has been deprecated in favor of
 'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
-- 
gitgitgadget

Re: [PATCH 08/11] doc: trailer.<token>.command: refer to existing example

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Linus Arver <linusa@google.com>
>
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>  Documentation/git-interpret-trailers.txt | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)

This patch has more annoying "just rewrapping the text in a strange
way without changing anything" than the real change which is to
enclose <value> inside the angle brackets (which is good) and adding
a new sentence.

We are discouraging the use of .command and recommending folks to
use .cmd instead, by the way.  At some point we may drop the
example, and adding a reference to the example would mean somebody
needs to remember removing this when it happens.

> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
> index ac448fd732e..5ca758e363f 100644
> --- a/Documentation/git-interpret-trailers.txt
> +++ b/Documentation/git-interpret-trailers.txt
> @@ -234,10 +234,11 @@ trailer.<token>.ifmissing::
>  	that option for trailers with the specified <token>.
>  
>  trailer.<token>.command::
> -	This option behaves in the same way as 'trailer.<token>.cmd', 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.
> +	This option behaves in the
> +	same way as 'trailer.<token>.cmd', 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> from the trailer. See the
> +	'trailer.see.command' trailer example in the "EXAMPLES" section below.
>  +
>  The 'trailer.<token>.command' option has been deprecated in favor of
>  'trailer.<token>.cmd' due to the fact that $ARG in the user's command is

Re: [PATCH 08/11] doc: trailer.<token>.command: refer to existing example

[Linus Arver]

Junio C Hamano <gitster@pobox.com> writes:

> "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

>> From: Linus Arver <linusa@google.com>

>> Signed-off-by: Linus Arver <linusa@google.com>
>> ---
>>   Documentation/git-interpret-trailers.txt | 9 +++++----
>>   1 file changed, 5 insertions(+), 4 deletions(-)

> This patch has more annoying "just rewrapping the text in a strange
> way without changing anything"

Noted. I will remove the whitespace churn in v2.

> than the real change which is to
> enclose <value> inside the angle brackets (which is good) and adding
> a new sentence.

I should probably move the angle bracket changes into 07.

> We are discouraging the use of .command and recommending folks to
> use .cmd instead, by the way.

I was motivated to add the reference to the example because I could not
understand what

     Instead the first occurrence of substring $ARG is replaced by the
     value that would be passed as argument.

meant in the existing language. In hindsight maybe it's not worth adding
the reference, because of the deprecation.

> At some point we may drop the
> example, and adding a reference to the example would mean somebody
> needs to remember removing this when it happens.

Wouldn't we also delete the entire `trailer.<token>.command::` section
(and therefore the reference to the example) also at the same time?

>> diff --git a/Documentation/git-interpret-trailers.txt  
>> b/Documentation/git-interpret-trailers.txt
>> index ac448fd732e..5ca758e363f 100644
>> --- a/Documentation/git-interpret-trailers.txt
>> +++ b/Documentation/git-interpret-trailers.txt
>> @@ -234,10 +234,11 @@ trailer.<token>.ifmissing::
>>   	that option for trailers with the specified <token>.

>>   trailer.<token>.command::
>> -	This option behaves in the same way as 'trailer.<token>.cmd', 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.
>> +	This option behaves in the
>> +	same way as 'trailer.<token>.cmd', 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> from the trailer. See the
>> +	'trailer.see.command' trailer example in the "EXAMPLES" section below.
>>   +
>>   The 'trailer.<token>.command' option has been deprecated in favor of
>>   'trailer.<token>.cmd' due to the fact that $ARG in the user's command is

Re: [PATCH 08/11] doc: trailer.<token>.command: refer to existing example

[Junio C Hamano]

Linus Arver <linusa@google.com> writes:

>> At some point we may drop the
>> example, and adding a reference to the example would mean somebody
>> needs to remember removing this when it happens.
>
> Wouldn't we also delete the entire `trailer.<token>.command::` section
> (and therefore the reference to the example) also at the same time?

We could go that way.

It is likely that we'd remove text that helps for those who newly
use the deprecated construct while keeping what helps for those who
have to read and understand the construct that was written in random
scripts they find on the Internet.  So removing the example can come
before the section itself, though.

In a far enough future, we would be without the example and the
section so it would not be too big a deal, either way.

Thanks.

[PATCH 09/11] doc: trailer.<token>.command: emphasize deprecation

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

This puts the deprecation notice up front, instead of leaving it to the
next paragraph.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 5ca758e363f..c9b82ceba34 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -234,7 +234,7 @@ trailer.<token>.ifmissing::
 	that option for trailers with the specified <token>.
 
 trailer.<token>.command::
-	This option behaves in the
+	Deprecated in favor of 'trailer.<token>.cmd'. This option behaves in the
 	same way as 'trailer.<token>.cmd', 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> from the trailer. See the
-- 
gitgitgadget

Re: [PATCH 09/11] doc: trailer.<token>.command: emphasize deprecation

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Linus Arver <linusa@google.com>
>
> This puts the deprecation notice up front, instead of leaving it to the
> next paragraph.

Shouldn't the opening text of the next paragraph be tweaked in the
same commit to avoid duplication?

> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>  Documentation/git-interpret-trailers.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
> index 5ca758e363f..c9b82ceba34 100644
> --- a/Documentation/git-interpret-trailers.txt
> +++ b/Documentation/git-interpret-trailers.txt
> @@ -234,7 +234,7 @@ trailer.<token>.ifmissing::
>  	that option for trailers with the specified <token>.
>  
>  trailer.<token>.command::
> -	This option behaves in the
> +	Deprecated in favor of 'trailer.<token>.cmd'. This option behaves in the
>  	same way as 'trailer.<token>.cmd', 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> from the trailer. See the

Re: [PATCH 09/11] doc: trailer.<token>.command: emphasize deprecation

[Linus Arver]

Junio C Hamano <gitster@pobox.com> writes:

> "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

>> From: Linus Arver <linusa@google.com>

>> This puts the deprecation notice up front, instead of leaving it to the
>> next paragraph.

> Shouldn't the opening text of the next paragraph be tweaked in the
> same commit to avoid duplication?

Good call; will do in v2.


>> Signed-off-by: Linus Arver <linusa@google.com>
>> ---
>>   Documentation/git-interpret-trailers.txt | 2 +-
>>   1 file changed, 1 insertion(+), 1 deletion(-)

>> diff --git a/Documentation/git-interpret-trailers.txt  
>> b/Documentation/git-interpret-trailers.txt
>> index 5ca758e363f..c9b82ceba34 100644
>> --- a/Documentation/git-interpret-trailers.txt
>> +++ b/Documentation/git-interpret-trailers.txt
>> @@ -234,7 +234,7 @@ trailer.<token>.ifmissing::
>>   	that option for trailers with the specified <token>.

>>   trailer.<token>.command::
>> -	This option behaves in the
>> +	Deprecated in favor of 'trailer.<token>.cmd'. This option behaves in  
>> the
>>   	same way as 'trailer.<token>.cmd', 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> from the trailer. See the

[PATCH 10/11] doc: trailer: mention 'key' in DESCRIPTION

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

The 'key' option is used frequently in the examples at the bottom but
there is no mention of it in the description.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index c9b82ceba34..119dcd64f34 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -43,7 +43,9 @@ token: value
 ------------------------------------------------
 
 This means that the trimmed <token> and <value> will be separated by
-`': '` (one colon followed by one space).
+`': '` (one colon followed by one space). If the <token> should have a different
+string representation than itself, then the 'key' can be configured with
+'trailer.<token>.key'.
 
 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
-- 
gitgitgadget

[PATCH 11/11] doc: trailer: add more examples in DESCRIPTION

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Be more up-front about what trailers are in practice with examples, to
give the reader a visual cue while they go on to read the rest of the
description.

Also add an example for multiline values.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 119dcd64f34..f31b94a6823 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -16,7 +16,18 @@ DESCRIPTION
 -----------
 Add or parse 'trailer' lines, that look similar to RFC 822 e-mail
 headers, at the end of the otherwise free-form part of a commit
-message.
+message. For example, in the following commit message
+
+------------------------------------------------
+subject
+
+message
+
+Signed-off-by: Alice <alice@example.com>
+Signed-off-by: Bob <bob@example.com>
+------------------------------------------------
+
+the last two lines starting with "Signed-off-by" are trailers.
 
 This command reads some patches or commit messages from either the
 <file> arguments or the standard input if no <file> is specified. If
@@ -68,7 +79,12 @@ When reading trailers, there can be no whitespace before or inside the
 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.
+the "folding" in RFC 822. Example:
+
+------------------------------------------------
+token: Lorem ipsum dolor sit amet, consectetur
+  adipiscing elit.
+------------------------------------------------
 
 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.
-- 
gitgitgadget

Re: [PATCH 11/11] doc: trailer: add more examples in DESCRIPTION

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Linus Arver <linusa@google.com>
>
> Be more up-front about what trailers are in practice with examples, to
> give the reader a visual cue while they go on to read the rest of the
> description.
>
> Also add an example for multiline values.
>
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>  Documentation/git-interpret-trailers.txt | 20 ++++++++++++++++++--
>  1 file changed, 18 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
> index 119dcd64f34..f31b94a6823 100644
> --- a/Documentation/git-interpret-trailers.txt
> +++ b/Documentation/git-interpret-trailers.txt
> @@ -16,7 +16,18 @@ DESCRIPTION
>  -----------
>  Add or parse 'trailer' lines, that look similar to RFC 822 e-mail
>  headers, at the end of the otherwise free-form part of a commit
> -message.
> +message. For example, in the following commit message
> +
> +------------------------------------------------
> +subject
> +
> +message
> +
> +Signed-off-by: Alice <alice@example.com>
> +Signed-off-by: Bob <bob@example.com>
> +------------------------------------------------
> +
> +the last two lines starting with "Signed-off-by" are trailers.

Excellent.

> @@ -68,7 +79,12 @@ When reading trailers, there can be no whitespace before or inside the
>  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.
> +the "folding" in RFC 822. Example:
> +
> +------------------------------------------------
> +token: Lorem ipsum dolor sit amet, consectetur
> +  adipiscing elit.
> +------------------------------------------------

Excellent.

Re: [PATCH 00/11] docs: interpret-trailers: reword and add examples

[Junio C Hamano]

[jc: making sure that the area expert is aware of the topic]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> This series makes some small improvements to the docs for
> git-interpret-trailers. The intent is to make it easier to read for
> beginners who have never used this command before.
>
> Linus Arver (11):
>   doc: trailer: fix grammar
>   doc: trailer: swap verb order
>   doc: trailer: --no-divider: more precise language
>   doc: trailer: explain "commit mesage part" on first usage
>   doc: trailer: remove redundant phrasing
>   doc: trailer: trailer.<token>.cmd: add missing verb phrase
>   doc: trailer: use angle brackets for <token> and <value>
>   doc: trailer.<token>.command: refer to existing example
>   doc: trailer.<token>.command: emphasize deprecation
>   doc: trailer: mention 'key' in DESCRIPTION
>   doc: trailer: add more examples in DESCRIPTION
>
>  Documentation/git-interpret-trailers.txt | 62 +++++++++++++++---------
>  1 file changed, 40 insertions(+), 22 deletions(-)
>
>
> base-commit: 69c786637d7a7fe3b2b8f7d989af095f5f49c3a8
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1506%2Flistx%2Fdoc-trailer-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1506/listx/doc-trailer-v1
> Pull-Request: https://github.com/git/git/pull/1506

Re: [PATCH 00/11] docs: interpret-trailers: reword and add examples

[Linus Arver]

Junio C Hamano <gitster@pobox.com> writes:

> [jc: making sure that the area expert is aware of the topic]

Thanks for the assist, Junio! (I will run git-blame next time, sorry
about that.)

But also, what does the `jc: ` in your message stand for?


> "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

>> This series makes some small improvements to the docs for
>> git-interpret-trailers. The intent is to make it easier to read for
>> beginners who have never used this command before.

>> Linus Arver (11):
>>    doc: trailer: fix grammar
>>    doc: trailer: swap verb order
>>    doc: trailer: --no-divider: more precise language
>>    doc: trailer: explain "commit mesage part" on first usage
>>    doc: trailer: remove redundant phrasing
>>    doc: trailer: trailer.<token>.cmd: add missing verb phrase
>>    doc: trailer: use angle brackets for <token> and <value>
>>    doc: trailer.<token>.command: refer to existing example
>>    doc: trailer.<token>.command: emphasize deprecation
>>    doc: trailer: mention 'key' in DESCRIPTION
>>    doc: trailer: add more examples in DESCRIPTION

>>   Documentation/git-interpret-trailers.txt | 62 +++++++++++++++---------
>>   1 file changed, 40 insertions(+), 22 deletions(-)


>> base-commit: 69c786637d7a7fe3b2b8f7d989af095f5f49c3a8
>> Published-As:  
>> https://github.com/gitgitgadget/git/releases/tag/pr-git-1506%2Flistx%2Fdoc-trailer-v1
>> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git  
>> pr-git-1506/listx/doc-trailer-v1
>> Pull-Request: https://github.com/git/git/pull/1506

[PATCH v2 0/9] docs: interpret-trailers: reword and add examples

[Linus Arver via GitGitGadget]

This series makes some small improvements to the docs for
git-interpret-trailers. The intent is to make it easier to read for
beginners who have never used this command before.


Changes from v1
===============

In order of significance:

 * The phrase "commit message part" has been removed.
 * The word "message" is always used as part of the bigger phrase "commit
   message".
 * Deprecation language for trailer.<token>.command has been updated to
   minimize whitespace churn, while also tweaking the 2nd paragraph to
   reduce duplication.
 * The phrase "Lorem ipsum..." is always only used to stand in for the body
   paragraph(s) of a commit message.
 * Grammar fixes have been squashed together (01+06 previously).

Linus Arver (9):
  doc: trailer: fix grammar
  doc: trailer: swap verb order
  doc: trailer: drop "commit message part" phrasing
  doc: trailer: examples: avoid the word "message" by itself
  doc: trailer: remove redundant phrasing
  doc: trailer: use angle brackets for <token> and <value>
  doc: trailer.<token>.command: emphasize deprecation
  doc: trailer: mention 'key' in DESCRIPTION
  doc: trailer: add more examples in DESCRIPTION

 Documentation/git-interpret-trailers.txt | 124 +++++++++++++----------
 1 file changed, 72 insertions(+), 52 deletions(-)


base-commit: 69c786637d7a7fe3b2b8f7d989af095f5f49c3a8
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1506%2Flistx%2Fdoc-trailer-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1506/listx/doc-trailer-v2
Pull-Request: https://github.com/git/git/pull/1506

Range-diff vs v1:

  1:  12d4850a9ab !  1:  65e6fbdec92 doc: trailer: fix grammar
     @@ Documentation/git-interpret-trailers.txt: SYNOPSIS
       DESCRIPTION
       -----------
      -Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail
     -+Parse or add 'trailer' lines, that look similar to RFC 822 e-mail
     ++Parse or add 'trailer' lines that look similar to RFC 822 e-mail
       headers, at the end of the otherwise free-form part of a commit
       message.
       
     +@@ Documentation/git-interpret-trailers.txt: for the same <token>, 'trailer.<token>.cmd' is used and
     + 'trailer.<token>.command' is ignored.
     + 
     + trailer.<token>.cmd::
     +-	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 '--trailer <token>=<value>' argument to modify the <value> of
     +-	the trailer that this option would produce.
     ++	called each time a '--trailer <token>=<value>' argument is specified to
     ++	modify the <value> of the trailer that this option would produce.
     + +
     + When the specified command is first called to add a trailer
     + with the specified <token>, the behavior is as if a special
  2:  b7717424437 !  2:  82353471831 doc: trailer: swap verb order
     @@ Documentation/git-interpret-trailers.txt: SYNOPSIS
       
       DESCRIPTION
       -----------
     --Parse or add 'trailer' lines, that look similar to RFC 822 e-mail
     -+Add or parse 'trailer' lines, that look similar to RFC 822 e-mail
     +-Parse or add 'trailer' lines that look similar to RFC 822 e-mail
     ++Add or parse 'trailer' lines that look similar to RFC 822 e-mail
       headers, at the end of the otherwise free-form part of a commit
       message.
       
  3:  ad2d669eb0a <  -:  ----------- doc: trailer: --no-divider: more precise language
  4:  0c10e40794d <  -:  ----------- doc: trailer: explain "commit mesage part" on first usage
  -:  ----------- >  3:  5fabe166714 doc: trailer: drop "commit message part" phrasing
  -:  ----------- >  4:  783a0b1e003 doc: trailer: examples: avoid the word "message" by itself
  5:  5bad365c786 =  5:  dd7e29fcc21 doc: trailer: remove redundant phrasing
  6:  8e36d1bd1f0 <  -:  ----------- doc: trailer: trailer.<token>.cmd: add missing verb phrase
  7:  ab11527ca58 !  6:  96cb4ae2965 doc: trailer: use angle brackets for <token> and <value>
     @@ Commit message
          Signed-off-by: Linus Arver <linusa@google.com>
      
       ## Documentation/git-interpret-trailers.txt ##
     -@@ Documentation/git-interpret-trailers.txt: space or the end of the line). Such three minus signs start the patch
     - part of the message. See also `--no-divider` below.
     +@@ Documentation/git-interpret-trailers.txt: non-whitespace lines before a line that starts with '---' (followed by a
     + space or the end of the line).
       
       When reading trailers, there can be no whitespace before or inside the
      -token, but any number of regular space and tab characters are allowed
     @@ Documentation/git-interpret-trailers.txt: space or the end of the line). Such th
       with each subsequent line starting with at least one whitespace, like
       the "folding" in RFC 822.
       
     +@@ Documentation/git-interpret-trailers.txt: trailer.<token>.command::
     + 	This option behaves in the same way as 'trailer.<token>.cmd', 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.
     + +
     + The 'trailer.<token>.command' option has been deprecated in favor of
     + 'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
  8:  59804321793 !  7:  4e234110ffd doc: trailer.<token>.command: refer to existing example
     @@ Metadata
      Author: Linus Arver <linusa@google.com>
      
       ## Commit message ##
     -    doc: trailer.<token>.command: refer to existing example
     +    doc: trailer.<token>.command: emphasize deprecation
     +
     +    This puts the deprecation notice up front, instead of leaving it to the
     +    next paragraph.
      
          Signed-off-by: Linus Arver <linusa@google.com>
      
     @@ Documentation/git-interpret-trailers.txt: trailer.<token>.ifmissing::
       	that option for trailers with the specified <token>.
       
       trailer.<token>.command::
     --	This option behaves in the same way as 'trailer.<token>.cmd', 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.
     -+	This option behaves in the
     -+	same way as 'trailer.<token>.cmd', 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> from the trailer. See the
     -+	'trailer.see.command' trailer example in the "EXAMPLES" section below.
     ++	Deprecated in favor of 'trailer.<token>.cmd'.
     + 	This option behaves in the same way as 'trailer.<token>.cmd', 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.
     + +
     +-The 'trailer.<token>.command' option has been deprecated in favor of
     +-'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
     ++Note that $ARG in the user's command is
     + only replaced once and that the original way of replacing $ARG is not safe.
       +
     - The 'trailer.<token>.command' option has been deprecated in favor of
     - 'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
     + When both 'trailer.<token>.cmd' and 'trailer.<token>.command' are given
  9:  1ac58b0b07c <  -:  ----------- doc: trailer.<token>.command: emphasize deprecation
 10:  2c04a5ba7f0 =  8:  8aaf9e27d98 doc: trailer: mention 'key' in DESCRIPTION
 11:  ea483b364b4 !  9:  7e95198894b doc: trailer: add more examples in DESCRIPTION
     @@ Commit message
       ## Documentation/git-interpret-trailers.txt ##
      @@ Documentation/git-interpret-trailers.txt: DESCRIPTION
       -----------
     - Add or parse 'trailer' lines, that look similar to RFC 822 e-mail
     + Add or parse 'trailer' lines that look similar to RFC 822 e-mail
       headers, at the end of the otherwise free-form part of a commit
      -message.
      +message. For example, in the following commit message
     @@ Documentation/git-interpret-trailers.txt: DESCRIPTION
      +------------------------------------------------
      +subject
      +
     -+message
     ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
      +
      +Signed-off-by: Alice <alice@example.com>
      +Signed-off-by: Bob <bob@example.com>
     @@ Documentation/git-interpret-trailers.txt: DESCRIPTION
      +
      +the last two lines starting with "Signed-off-by" are trailers.
       
     - This command reads some patches or commit messages from either the
     - <file> arguments or the standard input if no <file> is specified. If
     + This command reads commit messages from either the
     + <file> arguments or the standard input if no <file> is specified.
      @@ Documentation/git-interpret-trailers.txt: When reading trailers, there can be no whitespace before or inside the
       between the <token> and the separator. There can be whitespaces before,
       inside or after the <value>. The <value> may be split over multiple lines
     @@ Documentation/git-interpret-trailers.txt: When reading trailers, there can be no
      +the "folding" in RFC 822. Example:
      +
      +------------------------------------------------
     -+token: Lorem ipsum dolor sit amet, consectetur
     -+  adipiscing elit.
     ++token: This is a very long value, with spaces and
     ++  newlines in it.
      +------------------------------------------------
       
       Note that trailers do not follow (nor are they intended to follow) many of the

-- 
gitgitgadget

[PATCH v2 1/9] doc: trailer: fix grammar

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 22ff3a603e0..1a1d6288b17 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -14,7 +14,7 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail
+Parse or add 'trailer' lines that look similar to RFC 822 e-mail
 headers, at the end of the otherwise free-form part of a commit
 message.
 
@@ -249,10 +249,10 @@ for the same <token>, 'trailer.<token>.cmd' is used and
 'trailer.<token>.command' is ignored.
 
 trailer.<token>.cmd::
-	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 '--trailer <token>=<value>' argument to modify the <value> of
-	the trailer that this option would produce.
+	called each time a '--trailer <token>=<value>' argument is specified to
+	modify the <value> of the trailer that this option would produce.
 +
 When the specified command is first called to add a trailer
 with the specified <token>, the behavior is as if a special
-- 
gitgitgadget

[PATCH v2 2/9] doc: trailer: swap verb order

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

This matches the order already used in the NAME section.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 1a1d6288b17..cd4d724a0b7 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -14,7 +14,7 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Parse or add 'trailer' lines that look similar to RFC 822 e-mail
+Add or parse 'trailer' lines that look similar to RFC 822 e-mail
 headers, at the end of the otherwise free-form part of a commit
 message.
 
-- 
gitgitgadget

[PATCH v2 3/9] doc: trailer: drop "commit message part" phrasing

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

The command can take inputs that are either just a commit message, or
an email-like output such as git-format-patch which includes a commit
message, "---" divider, and patch part. The existing explanation blends
these two inputs together in the first sentence

    This command reads some patches or commit messages

which then necessitates using the "commit message part" phrasing (as
opposed to just "commit message") because the input is ambiguous per the
above definition.

This change separates the two input types and explains them separately,
and so there is no longer a need to use the "commit message part"
phrase.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 35 +++++++++++++-----------
 1 file changed, 19 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index cd4d724a0b7..58a7ea24606 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -18,17 +18,22 @@ Add or parse 'trailer' lines that look similar to RFC 822 e-mail
 headers, at the end of the otherwise free-form part of a commit
 message.
 
-This command reads some patches or commit messages from either the
-<file> arguments or the standard input if no <file> is specified. If
-`--parse` is specified, the output consists of the parsed trailers.
-
+This command reads commit messages from either the
+<file> arguments or the standard input if no <file> is specified.
+If `--parse` is specified, the output consists of the parsed trailers.
 Otherwise, this command applies the arguments passed using the
-`--trailer` option, if any, to the commit message part of each input
-file. The result is emitted on the standard output.
+`--trailer` option, if any, to each input file. The result is emitted on the
+standard output.
+
+This command can also operate on the output of linkgit:git-format-patch[1],
+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 ignored, unless `--no-divider`
+is specified.
 
 Some configuration variables control the way the `--trailer` 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.
 
 By default, a '<token>=<value>' or '<token>:<value>' argument given
@@ -36,7 +41,7 @@ using `--trailer` 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:
+<token> and <value> will appear in the output like this:
 
 ------------------------------------------------
 token: value
@@ -47,19 +52,17 @@ This means that the trimmed <token> and <value> will be separated by
 
 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.
+at the end of the input. A blank line will be added before the new
+trailer if there isn't one already.
 
-Existing trailers are extracted from the input message by looking for
+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 '---' (followed by a
-space or the end of the line). Such three minus signs start the patch
-part of the message. See also `--no-divider` below.
+space or the end of the line).
 
 When reading trailers, there can be no whitespace before or inside the
 token, but any number of regular space and tab characters are allowed
-- 
gitgitgadget

[PATCH v2 4/9] doc: trailer: examples: avoid the word "message" by itself

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Previously, "message" could mean the input, output, commit message, or
"internal body text inside the commit message" (in the EXAMPLES
section). Avoid overloading this term by using the appropriate meanings
explicitly.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 42 ++++++++++++------------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 58a7ea24606..8766edbf4dc 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -82,12 +82,12 @@ OPTIONS
 
 --trim-empty::
 	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.
 
 --trailer <token>[(=|:)<value>]::
 	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.
 
 --where <placement>::
@@ -101,7 +101,7 @@ OPTIONS
 --if-exists <action>::
 --no-if-exists::
 	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 '--if-exists' overrides all configuration variables
 	and applies to all '--trailer' options until the next occurrence of
 	'--if-exists' or '--no-if-exists'. Possible actions are `addIfDifferent`,
@@ -110,7 +110,7 @@ OPTIONS
 --if-missing <action>::
 --no-if-missing::
 	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 '--if-missing' overrides all configuration variables
 	and applies to all '--trailer' options until the next occurrence of
 	'--if-missing' or '--no-if-missing'. Possible actions are `doNothing`
@@ -177,7 +177,7 @@ first trailer with the same <token>.
 trailer.ifexists::
 	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.
 +
 The valid values for this option are: `addIfDifferentNeighbor` (this
 is the default), `addIfDifferent`, `add`, `replace` or `doNothing`.
@@ -187,10 +187,10 @@ trailer with the same (<token>, <value>) pair is above or below the line
 where the new trailer will be added.
 +
 With `addIfDifferent`, a new trailer will be added only if no trailer
-with the same (<token>, <value>) pair is already in the message.
+with the same (<token>, <value>) pair is already in the input.
 +
 With `add`, a new trailer will be added, even if some trailers with
-the same (<token>, <value>) pair are already in the message.
+the same (<token>, <value>) pair are already in the input.
 +
 With `replace`, an existing trailer with the same <token> will be
 deleted and the new trailer will be added. The deleted trailer will be
@@ -198,12 +198,12 @@ the closest one (with the same <token>) to the place where the new one
 will be added.
 +
 With `doNothing`, nothing will be done; that is no new trailer will be
-added if there is already one with the same <token> in the message.
+added if there is already one with the same <token> in the input.
 
 trailer.ifmissing::
 	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.
 +
 The valid values for this option are: `add` (this is the default) and
 `doNothing`.
@@ -275,37 +275,37 @@ EXAMPLES
 --------
 
 * Configure a 'sign' trailer with a 'Signed-off-by' key, and then
-  add two of these trailers to a message:
+  add two of these trailers to a commit message file:
 +
 ------------
 $ git config trailer.sign.key "Signed-off-by"
 $ cat msg.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 $ cat msg.txt | git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>'
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Signed-off-by: Alice <alice@example.com>
 Signed-off-by: Bob <bob@example.com>
 ------------
 
-* Use the `--in-place` option to edit a message file in place:
+* Use the `--in-place` option to edit a commit message file in place:
 +
 ------------
 $ cat msg.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 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
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Signed-off-by: Bob <bob@example.com>
 Acked-by: Alice <alice@example.com>
@@ -366,12 +366,12 @@ $ git config trailer.help.cmd "~/bin/glog-find-author"
 $ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <<EOF
 > subject
 >
-> message
+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 >
 > EOF
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Helped-by: Junio C Hamano <gitster@pobox.com>
 Helped-by: Christian Couder <christian.couder@gmail.com>
@@ -391,12 +391,12 @@ $ git config trailer.ref.cmd "~/bin/glog-grep"
 $ git interpret-trailers --trailer="ref:Add copyright notices." <<EOF
 > subject
 >
-> message
+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 >
 > EOF
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
 ------------
@@ -412,13 +412,13 @@ $ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --ab
 $ git interpret-trailers <<EOF
 > subject
 > 
-> message
+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 > 
 > see: HEAD~2
 > EOF
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 See-also: fe3187489d69c4 (subject of related commit)
 ------------
-- 
gitgitgadget

[PATCH v2 5/9] doc: trailer: remove redundant phrasing

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

The phrase "many rules" gets essentially repeated again with "many other
rules", so remove this repetition.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 8766edbf4dc..495d5c9bcf1 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -71,9 +71,8 @@ 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.
 
-Note that 'trailers' 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.
+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.
 
 OPTIONS
 -------
-- 
gitgitgadget

[PATCH v2 6/9] doc: trailer: use angle brackets for <token> and <value>

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

We already use angle brackets elsewhere, so this makes things more
consistent.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 495d5c9bcf1..576f5987b0d 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -65,9 +65,9 @@ non-whitespace lines before a line that starts with '---' (followed by a
 space or the end of the line).
 
 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.
 
@@ -240,7 +240,7 @@ trailer.<token>.command::
 	This option behaves in the same way as 'trailer.<token>.cmd', 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.
 +
 The 'trailer.<token>.command' option has been deprecated in favor of
 'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
-- 
gitgitgadget

[PATCH v2 7/9] doc: trailer.<token>.command: emphasize deprecation

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

This puts the deprecation notice up front, instead of leaving it to the
next paragraph.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 576f5987b0d..32a26c59f8a 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -237,13 +237,13 @@ trailer.<token>.ifmissing::
 	that option for trailers with the specified <token>.
 
 trailer.<token>.command::
+	Deprecated in favor of 'trailer.<token>.cmd'.
 	This option behaves in the same way as 'trailer.<token>.cmd', 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.
 +
-The 'trailer.<token>.command' option has been deprecated in favor of
-'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
+Note that $ARG in the user's command is
 only replaced once and that the original way of replacing $ARG is not safe.
 +
 When both 'trailer.<token>.cmd' and 'trailer.<token>.command' are given
-- 
gitgitgadget

[PATCH v2 8/9] doc: trailer: mention 'key' in DESCRIPTION

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

The 'key' option is used frequently in the examples at the bottom but
there is no mention of it in the description.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 32a26c59f8a..245a66a7a85 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -48,7 +48,9 @@ token: value
 ------------------------------------------------
 
 This means that the trimmed <token> and <value> will be separated by
-`': '` (one colon followed by one space).
+`': '` (one colon followed by one space). If the <token> should have a different
+string representation than itself, then the 'key' can be configured with
+'trailer.<token>.key'.
 
 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
-- 
gitgitgadget

[PATCH v2 9/9] doc: trailer: add more examples in DESCRIPTION

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Be more up-front about what trailers are in practice with examples, to
give the reader a visual cue while they go on to read the rest of the
description.

Also add an example for multiline values.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 245a66a7a85..e13a5ec6943 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -16,7 +16,18 @@ DESCRIPTION
 -----------
 Add or parse 'trailer' lines that look similar to RFC 822 e-mail
 headers, at the end of the otherwise free-form part of a commit
-message.
+message. For example, in the following commit message
+
+------------------------------------------------
+subject
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+Signed-off-by: Alice <alice@example.com>
+Signed-off-by: Bob <bob@example.com>
+------------------------------------------------
+
+the last two lines starting with "Signed-off-by" are trailers.
 
 This command reads commit messages from either the
 <file> arguments or the standard input if no <file> is specified.
@@ -71,7 +82,12 @@ When reading trailers, there can be no whitespace before or inside the
 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.
+the "folding" in RFC 822. Example:
+
+------------------------------------------------
+token: This is a very long value, with spaces and
+  newlines in it.
+------------------------------------------------
 
 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.
-- 
gitgitgadget

Re: [PATCH v2 0/9] docs: interpret-trailers: reword and add examples

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> This series makes some small improvements to the docs for
> git-interpret-trailers. The intent is to make it easier to read for
> beginners who have never used this command before.
>
>
> Changes from v1
> ===============
>
> In order of significance:
>
>  * The phrase "commit message part" has been removed.
>  * The word "message" is always used as part of the bigger phrase "commit
>    message".
>  * Deprecation language for trailer.<token>.command has been updated to
>    minimize whitespace churn, while also tweaking the 2nd paragraph to
>    reduce duplication.
>  * The phrase "Lorem ipsum..." is always only used to stand in for the body
>    paragraph(s) of a commit message.
>  * Grammar fixes have been squashed together (01+06 previously).

Looking very good.

Unfortunately some of the updates to examples overlap moderately
with what the kh/doc-interpret-trailers-updates topic wanted to do.
I think I resolved them correctly, but please double check what
appears in 'seen'.

As the other topic is slated to graduate in a day or two (topics
usually cook for a week in 'next' before merged to 'master'), it
may be a good idea to wait for more review comments and then rebase
these patches on top of 'master' when that happens.

Thanks.

Re: [PATCH v2 0/9] docs: interpret-trailers: reword and add examples

[Linus Arver]

Junio C Hamano <gitster@pobox.com> writes:

> Looking very good.

> Unfortunately some of the updates to examples overlap moderately
> with what the kh/doc-interpret-trailers-updates topic wanted to do.
> I think I resolved them correctly, but please double check what
> appears in 'seen'.

I don't think I can double-check 'seen' in a timely manner (see "FYI"
below).

> As the other topic is slated to graduate in a day or two (topics
> usually cook for a week in 'next' before merged to 'master'), it
> may be a good idea to wait for more review comments and then rebase
> these patches on top of 'master' when that happens.

Will do. Thanks for the tip!

FYI: I am currently on vacation (in hindsight I should have mentioned
this ahead of time) and won't be back until June 5. Still, I am highly
interested in seeing how my topic branch evolves (along with the
interactions with 'seen', 'next', etc) so I will at least have a look
time to time before my official @work return date to see if I can rebase
this topic on master when it (master) moves.

Re: [PATCH v2 0/9] docs: interpret-trailers: reword and add examples

[Junio C Hamano]

Linus Arver <linusa@google.com> writes:

> FYI: I am currently on vacation (in hindsight I should have mentioned
> this ahead of time) and won't be back until June 5. Still, I am highly
> interested in seeing how my topic branch evolves (along with the
> interactions with 'seen', 'next', etc) so I will at least have a look
> time to time before my official @work return date to see if I can rebase
> this topic on master when it (master) moves.

Thanks.

FYI, we will go into a pre-release feature freeze when no new
"features" or "fixes" will graduate to the 'master' branch, unless
it is a regression fix to the change that happened between 2.40 and
'master'.  As the next release is planned for the beginning of June,
your vacation would coincide well with back-burnering the topic ;-)

Have fun.

[PATCH v3 0/9] docs: interpret-trailers: reword and add examples

[Linus Arver via GitGitGadget]

This series makes some small improvements to the docs for
git-interpret-trailers. The intent is to make it easier to read for
beginners who have never used this command before.


Changes from v2 to v3
=====================

 * Rebased on top of "master" at fe86abd751 (Git 2.41, 2023-06-01). The only
   conflict was in Patch v2 4/9
   (https://lore.kernel.org/git/783a0b1e00309e9bcf13494908d99317df72f0d6.1683839975.git.gitgitgadget@gmail.com/),
   because cbb83daeaf (doc: interpret-trailers: fix example, 2023-05-01)
   added the "subject/message" style for the examples that did not have any
   message text in them. These examples' additional message lines have been
   replaced with Lorem ipsum... like the others in Patch v2 4/9.


Changes from v1 to v2
=====================

In order of significance:

 * The phrase "commit message part" has been removed.
 * The word "message" is always used as part of the bigger phrase "commit
   message".
 * Deprecation language for trailer.<token>.command has been updated to
   minimize whitespace churn, while also tweaking the 2nd paragraph to
   reduce duplication.
 * The phrase "Lorem ipsum..." is always only used to stand in for the body
   paragraph(s) of a commit message.
 * Grammar fixes have been squashed together (01+06 previously).

Linus Arver (9):
  doc: trailer: fix grammar
  doc: trailer: swap verb order
  doc: trailer: drop "commit message part" phrasing
  doc: trailer: examples: avoid the word "message" by itself
  doc: trailer: remove redundant phrasing
  doc: trailer: use angle brackets for <token> and <value>
  doc: trailer.<token>.command: emphasize deprecation
  doc: trailer: mention 'key' in DESCRIPTION
  doc: trailer: add more examples in DESCRIPTION

 Documentation/git-interpret-trailers.txt | 132 +++++++++++++----------
 1 file changed, 76 insertions(+), 56 deletions(-)


base-commit: fe86abd7511a9a6862d5706c6fa1d9b57a63ba09
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1506%2Flistx%2Fdoc-trailer-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1506/listx/doc-trailer-v3
Pull-Request: https://github.com/git/git/pull/1506

Range-diff vs v2:

  1:  65e6fbdec92 =  1:  7d504700b91 doc: trailer: fix grammar
  2:  82353471831 =  2:  65386432ca4 doc: trailer: swap verb order
  3:  5fabe166714 =  3:  e0a56c8e61d doc: trailer: drop "commit message part" phrasing
  4:  783a0b1e003 !  4:  52f7d29f509 doc: trailer: examples: avoid the word "message" by itself
     @@ Documentation/git-interpret-trailers.txt: EXAMPLES
       
      -message
      +Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     - $ cat msg.txt | git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>'
     + $ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt
       subject
       
      -message
     @@ Documentation/git-interpret-trailers.txt: EXAMPLES
       
       Signed-off-by: Bob <bob@example.com>
       Acked-by: Alice <alice@example.com>
     -@@ Documentation/git-interpret-trailers.txt: $ git config trailer.help.cmd "~/bin/glog-find-author"
     - $ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <<EOF
     - > subject
     - >
     --> message
     -+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     - >
     - > EOF
     +@@ Documentation/git-interpret-trailers.txt: $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re
     + $ cat msg1.txt
     + subject
     + 
     +-message
     ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     + $ git config trailer.sign.key "Signed-off-by: "
     + $ git config trailer.sign.ifmissing add
     + $ git config trailer.sign.ifexists doNothing
     +@@ Documentation/git-interpret-trailers.txt: $ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.
     + $ git interpret-trailers --trailer sign <msg1.txt
     + subject
     + 
     +-message
     ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     + 
     + Signed-off-by: Bob <bob@example.com>
     + $ cat msg2.txt
     + subject
     + 
     +-message
     ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     + 
     + Signed-off-by: Alice <alice@example.com>
     + $ git interpret-trailers --trailer sign <msg2.txt
     + subject
     + 
     +-message
     ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     + 
     + Signed-off-by: Alice <alice@example.com>
     + ------------
     +@@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true
     + $ cat msg.txt
     + subject
     + 
     +-message
     ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     + $ 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
     @@ Documentation/git-interpret-trailers.txt: $ git config trailer.help.cmd "~/bin/g
       
       Helped-by: Junio C Hamano <gitster@pobox.com>
       Helped-by: Christian Couder <christian.couder@gmail.com>
     -@@ Documentation/git-interpret-trailers.txt: $ git config trailer.ref.cmd "~/bin/glog-grep"
     - $ git interpret-trailers --trailer="ref:Add copyright notices." <<EOF
     - > subject
     - >
     --> message
     -+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     - >
     - > EOF
     +@@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --grep "$1" --pretty=reference -1 || true
     + $ cat msg.txt
     + subject
     + 
     +-message
     ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     + $ 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
     @@ Documentation/git-interpret-trailers.txt: $ git config trailer.ref.cmd "~/bin/gl
       
       Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
       ------------
     -@@ Documentation/git-interpret-trailers.txt: $ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --ab
     - $ git interpret-trailers <<EOF
     - > subject
     - > 
     --> message
     -+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     - > 
     - > see: HEAD~2
     - > EOF
     +@@ Documentation/git-interpret-trailers.txt: Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
     + $ cat msg.txt
     + subject
     + 
     +-message
     ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     + 
     + see: HEAD~2
     + $ cat ~/bin/glog-ref
     +@@ Documentation/git-interpret-trailers.txt: $ git config trailer.see.cmd "glog-ref"
     + $ git interpret-trailers --trailer=see <msg.txt
       subject
       
      -message
  5:  dd7e29fcc21 =  5:  4a2a0e41e4a doc: trailer: remove redundant phrasing
  6:  96cb4ae2965 =  6:  f99545409dc doc: trailer: use angle brackets for <token> and <value>
  7:  4e234110ffd =  7:  6aba774489a doc: trailer.<token>.command: emphasize deprecation
  8:  8aaf9e27d98 =  8:  b13bd73d248 doc: trailer: mention 'key' in DESCRIPTION
  9:  7e95198894b =  9:  ec43e192d6e doc: trailer: add more examples in DESCRIPTION

-- 
gitgitgadget

[PATCH v3 1/9] doc: trailer: fix grammar

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 4b97f812be8..35faf837892 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -14,7 +14,7 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail
+Parse or add 'trailer' lines that look similar to RFC 822 e-mail
 headers, at the end of the otherwise free-form part of a commit
 message.
 
@@ -249,10 +249,10 @@ for the same <token>, 'trailer.<token>.cmd' is used and
 'trailer.<token>.command' is ignored.
 
 trailer.<token>.cmd::
-	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 '--trailer <token>=<value>' argument to modify the <value> of
-	the trailer that this option would produce.
+	called each time a '--trailer <token>=<value>' argument is specified to
+	modify the <value> of the trailer that this option would produce.
 +
 When the specified command is first called to add a trailer
 with the specified <token>, the behavior is as if a special
-- 
gitgitgadget

[PATCH v3 2/9] doc: trailer: swap verb order

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

This matches the order already used in the NAME section.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 35faf837892..da8fec7d5fe 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -14,7 +14,7 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Parse or add 'trailer' lines that look similar to RFC 822 e-mail
+Add or parse 'trailer' lines that look similar to RFC 822 e-mail
 headers, at the end of the otherwise free-form part of a commit
 message.
 
-- 
gitgitgadget

[PATCH v3 3/9] doc: trailer: drop "commit message part" phrasing

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

The command can take inputs that are either just a commit message, or
an email-like output such as git-format-patch which includes a commit
message, "---" divider, and patch part. The existing explanation blends
these two inputs together in the first sentence

    This command reads some patches or commit messages

which then necessitates using the "commit message part" phrasing (as
opposed to just "commit message") because the input is ambiguous per the
above definition.

This change separates the two input types and explains them separately,
and so there is no longer a need to use the "commit message part"
phrase.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 35 +++++++++++++-----------
 1 file changed, 19 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index da8fec7d5fe..ffde97a6c3d 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -18,17 +18,22 @@ Add or parse 'trailer' lines that look similar to RFC 822 e-mail
 headers, at the end of the otherwise free-form part of a commit
 message.
 
-This command reads some patches or commit messages from either the
-<file> arguments or the standard input if no <file> is specified. If
-`--parse` is specified, the output consists of the parsed trailers.
-
+This command reads commit messages from either the
+<file> arguments or the standard input if no <file> is specified.
+If `--parse` is specified, the output consists of the parsed trailers.
 Otherwise, this command applies the arguments passed using the
-`--trailer` option, if any, to the commit message part of each input
-file. The result is emitted on the standard output.
+`--trailer` option, if any, to each input file. The result is emitted on the
+standard output.
+
+This command can also operate on the output of linkgit:git-format-patch[1],
+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 ignored, unless `--no-divider`
+is specified.
 
 Some configuration variables control the way the `--trailer` 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.
 
 By default, a '<token>=<value>' or '<token>:<value>' argument given
@@ -36,7 +41,7 @@ using `--trailer` 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:
+<token> and <value> will appear in the output like this:
 
 ------------------------------------------------
 token: value
@@ -47,19 +52,17 @@ This means that the trimmed <token> and <value> will be separated by
 
 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.
+at the end of the input. A blank line will be added before the new
+trailer if there isn't one already.
 
-Existing trailers are extracted from the input message by looking for
+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 '---' (followed by a
-space or the end of the line). Such three minus signs start the patch
-part of the message. See also `--no-divider` below.
+space or the end of the line).
 
 When reading trailers, there can be no whitespace before or inside the
 token, but any number of regular space and tab characters are allowed
-- 
gitgitgadget

Re: [PATCH v3 3/9] doc: trailer: drop "commit message part" phrasing

[Christian Couder]

On Tue, Jun 6, 2023 at 4:08 AM Linus Arver via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Linus Arver <linusa@google.com>
>
> The command can take inputs that are either just a commit message, or
> an email-like output such as git-format-patch which includes a commit
> message, "---" divider, and patch part. The existing explanation blends
> these two inputs together in the first sentence
>
>     This command reads some patches or commit messages
>
> which then necessitates using the "commit message part" phrasing (as
> opposed to just "commit message") because the input is ambiguous per the
> above definition.
>
> This change separates the two input types and explains them separately,
> and so there is no longer a need to use the "commit message part"
> phrase.
>
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>  Documentation/git-interpret-trailers.txt | 35 +++++++++++++-----------
>  1 file changed, 19 insertions(+), 16 deletions(-)
>
> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
> index da8fec7d5fe..ffde97a6c3d 100644
> --- a/Documentation/git-interpret-trailers.txt
> +++ b/Documentation/git-interpret-trailers.txt
> @@ -18,17 +18,22 @@ Add or parse 'trailer' lines that look similar to RFC 822 e-mail
>  headers, at the end of the otherwise free-form part of a commit
>  message.
>
> -This command reads some patches or commit messages from either the
> -<file> arguments or the standard input if no <file> is specified. If
> -`--parse` is specified, the output consists of the parsed trailers.
> -
> +This command reads commit messages from either the
> +<file> arguments or the standard input if no <file> is specified.
> +If `--parse` is specified, the output consists of the parsed trailers.
>  Otherwise, this command applies the arguments passed using the
> -`--trailer` option, if any, to the commit message part of each input
> -file. The result is emitted on the standard output.
> +`--trailer` option, if any, to each input file. The result is emitted on the
> +standard output.
> +
> +This command can also operate on the output of linkgit:git-format-patch[1],
> +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 ignored, unless `--no-divider`
> +is specified.

I think saying "the divider and patch parts are ignored" is a bit
ambiguous. It could mean that when a patch is read by the command only
its commit message, possibly modified by the command, is emitted on
the standard output.

I would suggest something like:

"For these inputs, the divider and patch parts are not modified by
this command and are emitted as is on the output, unless
`--no-divider` is specified."

Re: [PATCH v3 3/9] doc: trailer: drop "commit message part" phrasing

[Linus Arver]

Christian Couder <christian.couder@gmail.com> writes:

>> +This command can also operate on the output of  
>> linkgit:git-format-patch[1],
>> +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 ignored, unless  
>> `--no-divider`
>> +is specified.

> I think saying "the divider and patch parts are ignored" is a bit
> ambiguous. It could mean that when a patch is read by the command only
> its commit message, possibly modified by the command, is emitted on
> the standard output.

Indeed. Updated in v4.

[PATCH v3 4/9] doc: trailer: examples: avoid the word "message" by itself

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Previously, "message" could mean the input, output, commit message, or
"internal body text inside the commit message" (in the EXAMPLES
section). Avoid overloading this term by using the appropriate meanings
explicitly.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 50 ++++++++++++------------
 1 file changed, 25 insertions(+), 25 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index ffde97a6c3d..011ed0c3590 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -82,12 +82,12 @@ OPTIONS
 
 --trim-empty::
 	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.
 
 --trailer <token>[(=|:)<value>]::
 	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.
 
 --where <placement>::
@@ -101,7 +101,7 @@ OPTIONS
 --if-exists <action>::
 --no-if-exists::
 	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 '--if-exists' overrides all configuration variables
 	and applies to all '--trailer' options until the next occurrence of
 	'--if-exists' or '--no-if-exists'. Possible actions are `addIfDifferent`,
@@ -110,7 +110,7 @@ OPTIONS
 --if-missing <action>::
 --no-if-missing::
 	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 '--if-missing' overrides all configuration variables
 	and applies to all '--trailer' options until the next occurrence of
 	'--if-missing' or '--no-if-missing'. Possible actions are `doNothing`
@@ -177,7 +177,7 @@ first trailer with the same <token>.
 trailer.ifexists::
 	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.
 +
 The valid values for this option are: `addIfDifferentNeighbor` (this
 is the default), `addIfDifferent`, `add`, `replace` or `doNothing`.
@@ -187,10 +187,10 @@ trailer with the same (<token>, <value>) pair is above or below the line
 where the new trailer will be added.
 +
 With `addIfDifferent`, a new trailer will be added only if no trailer
-with the same (<token>, <value>) pair is already in the message.
+with the same (<token>, <value>) pair is already in the input.
 +
 With `add`, a new trailer will be added, even if some trailers with
-the same (<token>, <value>) pair are already in the message.
+the same (<token>, <value>) pair are already in the input.
 +
 With `replace`, an existing trailer with the same <token> will be
 deleted and the new trailer will be added. The deleted trailer will be
@@ -198,12 +198,12 @@ the closest one (with the same <token>) to the place where the new one
 will be added.
 +
 With `doNothing`, nothing will be done; that is no new trailer will be
-added if there is already one with the same <token> in the message.
+added if there is already one with the same <token> in the input.
 
 trailer.ifmissing::
 	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.
 +
 The valid values for this option are: `add` (this is the default) and
 `doNothing`.
@@ -275,37 +275,37 @@ EXAMPLES
 --------
 
 * Configure a 'sign' trailer with a 'Signed-off-by' key, and then
-  add two of these trailers to a message:
+  add two of these trailers to a commit message file:
 +
 ------------
 $ git config trailer.sign.key "Signed-off-by"
 $ cat msg.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 $ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Signed-off-by: Alice <alice@example.com>
 Signed-off-by: Bob <bob@example.com>
 ------------
 
-* Use the `--in-place` option to edit a message file in place:
+* Use the `--in-place` option to edit a commit message file in place:
 +
 ------------
 $ cat msg.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 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
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Signed-off-by: Bob <bob@example.com>
 Acked-by: Alice <alice@example.com>
@@ -328,7 +328,7 @@ $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re
 $ cat msg1.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 $ git config trailer.sign.key "Signed-off-by: "
 $ git config trailer.sign.ifmissing add
 $ git config trailer.sign.ifexists doNothing
@@ -336,19 +336,19 @@ $ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.
 $ git interpret-trailers --trailer sign <msg1.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Signed-off-by: Bob <bob@example.com>
 $ cat msg2.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Signed-off-by: Alice <alice@example.com>
 $ git interpret-trailers --trailer sign <msg2.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Signed-off-by: Alice <alice@example.com>
 ------------
@@ -376,14 +376,14 @@ test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true
 $ cat msg.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 $ 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
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Helped-by: Junio C Hamano <gitster@pobox.com>
 Helped-by: Christian Couder <christian.couder@gmail.com>
@@ -400,14 +400,14 @@ test -n "$1" && git log --grep "$1" --pretty=reference -1 || true
 $ cat msg.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 $ 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
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
 ------------
@@ -419,7 +419,7 @@ Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
 $ cat msg.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 see: HEAD~2
 $ cat ~/bin/glog-ref
@@ -432,7 +432,7 @@ $ git config trailer.see.cmd "glog-ref"
 $ git interpret-trailers --trailer=see <msg.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 See-also: fe3187489d69c4 (subject of related commit)
 ------------
-- 
gitgitgadget

Re: [PATCH v3 4/9] doc: trailer: examples: avoid the word "message" by itself

[Christian Couder]

>  $ git config trailer.sign.key "Signed-off-by"
>  $ cat msg.txt
>  subject
>
> -message
> +Lorem ipsum dolor sit amet, consectetur adipiscing elit.

I am not sure this change is clarifying anything. If you want
something clearer for "internal body text inside the commit message",
you could perhaps just use "body" or "body text".

I am not against using such latin words, but then why only in the body
and not in the subject too? And if it's used in the subject too, then
I am not sure it will make it easy for users to understand that the
example is using a simple commit message.

Re: [PATCH v3 4/9] doc: trailer: examples: avoid the word "message" by itself

[Linus Arver]

Christian Couder <christian.couder@gmail.com> writes:

>>   $ git config trailer.sign.key "Signed-off-by"
>>   $ cat msg.txt
>>   subject

>> -message
>> +Lorem ipsum dolor sit amet, consectetur adipiscing elit.

> I am not sure this change is clarifying anything. If you want
> something clearer for "internal body text inside the commit message",
> you could perhaps just use "body" or "body text".

> I am not against using such latin words, but then why only in the body
> and not in the subject too? And if it's used in the subject too, then
> I am not sure it will make it easy for users to understand that the
> example is using a simple commit message.

I can't remember why I didn't just use "body text", which I agree is
better than the (albeit famous) Latin phrase. It's shorter, simpler, and
also search-friendly (for cases where the user is not sure of exactly
which word they want to search for). Updated in v4 to use "body
text".

[PATCH v3 5/9] doc: trailer: remove redundant phrasing

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

The phrase "many rules" gets essentially repeated again with "many other
rules", so remove this repetition.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 011ed0c3590..d1d3e50bde7 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -71,9 +71,8 @@ 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.
 
-Note that 'trailers' 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.
+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.
 
 OPTIONS
 -------
-- 
gitgitgadget

[PATCH v3 6/9] doc: trailer: use angle brackets for <token> and <value>

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

We already use angle brackets elsewhere, so this makes things more
consistent.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index d1d3e50bde7..d69851dd367 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -65,9 +65,9 @@ non-whitespace lines before a line that starts with '---' (followed by a
 space or the end of the line).
 
 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.
 
@@ -240,7 +240,7 @@ trailer.<token>.command::
 	This option behaves in the same way as 'trailer.<token>.cmd', 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.
 +
 The 'trailer.<token>.command' option has been deprecated in favor of
 'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
-- 
gitgitgadget

[PATCH v3 7/9] doc: trailer.<token>.command: emphasize deprecation

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

This puts the deprecation notice up front, instead of leaving it to the
next paragraph.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index d69851dd367..b034784e1d8 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -237,13 +237,13 @@ trailer.<token>.ifmissing::
 	that option for trailers with the specified <token>.
 
 trailer.<token>.command::
+	Deprecated in favor of 'trailer.<token>.cmd'.
 	This option behaves in the same way as 'trailer.<token>.cmd', 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.
 +
-The 'trailer.<token>.command' option has been deprecated in favor of
-'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
+Note that $ARG in the user's command is
 only replaced once and that the original way of replacing $ARG is not safe.
 +
 When both 'trailer.<token>.cmd' and 'trailer.<token>.command' are given
-- 
gitgitgadget

[PATCH v3 8/9] doc: trailer: mention 'key' in DESCRIPTION

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

The 'key' option is used frequently in the examples at the bottom but
there is no mention of it in the description.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index b034784e1d8..2e92640543c 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -48,7 +48,9 @@ token: value
 ------------------------------------------------
 
 This means that the trimmed <token> and <value> will be separated by
-`': '` (one colon followed by one space).
+`': '` (one colon followed by one space). If the <token> should have a different
+string representation than itself, then the 'key' can be configured with
+'trailer.<token>.key'.
 
 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
-- 
gitgitgadget

Re: [PATCH v3 8/9] doc: trailer: mention 'key' in DESCRIPTION

[Christian Couder]

On Tue, Jun 6, 2023 at 4:08 AM Linus Arver via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Linus Arver <linusa@google.com>
>
> The 'key' option is used frequently in the examples at the bottom but
> there is no mention of it in the description.
>
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>  Documentation/git-interpret-trailers.txt | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
> index b034784e1d8..2e92640543c 100644
> --- a/Documentation/git-interpret-trailers.txt
> +++ b/Documentation/git-interpret-trailers.txt
> @@ -48,7 +48,9 @@ token: value
>  ------------------------------------------------
>
>  This means that the trimmed <token> and <value> will be separated by
> -`': '` (one colon followed by one space).
> +`': '` (one colon followed by one space). If the <token> should have a different
> +string representation than itself, then the 'key' can be configured with
> +'trailer.<token>.key'.

I would rather say something like:

"A <token> can be a shortcut name, for example "sign", instead of the
full string, for example "Signed-off-by", which should appear before
the separator on the output. This can be configured using the
'trailer.<token>.key' configuration variable."

Re: [PATCH v3 8/9] doc: trailer: mention 'key' in DESCRIPTION

[Linus Arver]

Christian Couder <christian.couder@gmail.com> writes:

>>   This means that the trimmed <token> and <value> will be separated by
>> -`': '` (one colon followed by one space).
>> +`': '` (one colon followed by one space). If the <token> should have a  
>> different
>> +string representation than itself, then the 'key' can be configured with
>> +'trailer.<token>.key'.

> I would rather say something like:

> "A <token> can be a shortcut name, for example "sign", instead of the
> full string, for example "Signed-off-by", which should appear before
> the separator on the output. This can be configured using the
> 'trailer.<token>.key' configuration variable."

Updated in v4 with a slightly different wording versus your example.

[PATCH v3 9/9] doc: trailer: add more examples in DESCRIPTION

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Be more up-front about what trailers are in practice with examples, to
give the reader a visual cue while they go on to read the rest of the
description.

Also add an example for multiline values.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 2e92640543c..2e999320ec6 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -16,7 +16,18 @@ DESCRIPTION
 -----------
 Add or parse 'trailer' lines that look similar to RFC 822 e-mail
 headers, at the end of the otherwise free-form part of a commit
-message.
+message. For example, in the following commit message
+
+------------------------------------------------
+subject
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+Signed-off-by: Alice <alice@example.com>
+Signed-off-by: Bob <bob@example.com>
+------------------------------------------------
+
+the last two lines starting with "Signed-off-by" are trailers.
 
 This command reads commit messages from either the
 <file> arguments or the standard input if no <file> is specified.
@@ -71,7 +82,12 @@ When reading trailers, there can be no whitespace before or inside the
 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.
+the "folding" in RFC 822. Example:
+
+------------------------------------------------
+token: This is a very long value, with spaces and
+  newlines in it.
+------------------------------------------------
 
 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.
-- 
gitgitgadget

Re: [PATCH v3 0/9] docs: interpret-trailers: reword and add examples

[Christian Couder]

On Tue, Jun 6, 2023 at 4:08 AM Linus Arver via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> This series makes some small improvements to the docs for
> git-interpret-trailers. The intent is to make it easier to read for
> beginners who have never used this command before.

Thanks, and sorry for the late review. I found a few things that I
think could be improved, but I like the direction.

Re: [PATCH v3 0/9] docs: interpret-trailers: reword and add examples

[Linus Arver]

Christian Couder <christian.couder@gmail.com> writes:

> On Tue, Jun 6, 2023 at 4:08 AM Linus Arver via GitGitGadget
> <gitgitgadget@gmail.com> wrote:

>> This series makes some small improvements to the docs for
>> git-interpret-trailers. The intent is to make it easier to read for
>> beginners who have never used this command before.

> Thanks, and sorry for the late review. I found a few things that I
> think could be improved, but I like the direction.

No worries. Thank you for your review comments!

Re: [PATCH v3 0/9] docs: interpret-trailers: reword and add examples

[Christian Couder]

On Thu, Jun 15, 2023 at 5:06 AM Linus Arver <linusa@google.com> wrote:
>
> Christian Couder <christian.couder@gmail.com> writes:

> > Thanks, and sorry for the late review. I found a few things that I
> > think could be improved, but I like the direction.
>
> No worries. Thank you for your review comments!

The version 4 looks good to me now. Thanks!

[PATCH v4 0/9] docs: interpret-trailers: reword and add examples

[Linus Arver via GitGitGadget]

This series makes some small improvements to the docs for
git-interpret-trailers. The intent is to make it easier to read for
beginners who have never used this command before.


Updates in v4
=============

 * vs Patch v3 3/9: Reworded a sentence to avoid ambiguity with the word
   "ignored".
 * vs Patch v3 4/9: Replaced "Lorem ipsum..." in favor of "body text" which
   is shorter and more obvious (and search-friendly).
 * vs Patch v3 8/9: Expanded the explanation about 'trailer..key' and its
   convenience, instead of only stating how to use this option.


Updates in v3
=============

 * Rebased on top of "master" at fe86abd751 (Git 2.41, 2023-06-01). The only
   conflict was in Patch v2 4/9
   (https://lore.kernel.org/git/783a0b1e00309e9bcf13494908d99317df72f0d6.1683839975.git.gitgitgadget@gmail.com/),
   because cbb83daeaf (doc: interpret-trailers: fix example, 2023-05-01)
   added the "subject/message" style for the examples that did not have any
   message text in them. These examples' additional message lines have been
   replaced with Lorem ipsum... like the others in Patch v2 4/9.


Updates in v2
=============

In order of significance:

 * The phrase "commit message part" has been removed.
 * The word "message" is always used as part of the bigger phrase "commit
   message".
 * Deprecation language for trailer.<token>.command has been updated to
   minimize whitespace churn, while also tweaking the 2nd paragraph to
   reduce duplication.
 * The phrase "Lorem ipsum..." is always only used to stand in for the body
   paragraph(s) of a commit message.
 * Grammar fixes have been squashed together (01+06 previously).

Linus Arver (9):
  doc: trailer: fix grammar
  doc: trailer: swap verb order
  doc: trailer: drop "commit message part" phrasing
  doc: trailer: examples: avoid the word "message" by itself
  doc: trailer: remove redundant phrasing
  doc: trailer: use angle brackets for <token> and <value>
  doc: trailer.<token>.command: emphasize deprecation
  doc: trailer: mention 'key' in DESCRIPTION
  doc: trailer: add more examples in DESCRIPTION

 Documentation/git-interpret-trailers.txt | 134 +++++++++++++----------
 1 file changed, 78 insertions(+), 56 deletions(-)


base-commit: fe86abd7511a9a6862d5706c6fa1d9b57a63ba09
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1506%2Flistx%2Fdoc-trailer-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1506/listx/doc-trailer-v4
Pull-Request: https://github.com/git/git/pull/1506

Range-diff vs v3:

  1:  7d504700b91 =  1:  7d504700b91 doc: trailer: fix grammar
  2:  65386432ca4 =  2:  65386432ca4 doc: trailer: swap verb order
  3:  e0a56c8e61d !  3:  3c85477d791 doc: trailer: drop "commit message part" phrasing
     @@ Documentation/git-interpret-trailers.txt: Add or parse 'trailer' lines that look
      +This command can also operate on the output of linkgit:git-format-patch[1],
      +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 ignored, unless `--no-divider`
     -+is specified.
     ++For these inputs, the divider and patch parts are not modified by
     ++this command and are emitted as is on the output, unless
     ++`--no-divider` is specified.
       
       Some configuration variables control the way the `--trailer` arguments
      -are applied to each commit message and the way any existing trailer in
  4:  52f7d29f509 !  4:  6b4cb31b170 doc: trailer: examples: avoid the word "message" by itself
     @@ Documentation/git-interpret-trailers.txt: EXAMPLES
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       $ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       Signed-off-by: Alice <alice@example.com>
       Signed-off-by: Bob <bob@example.com>
     @@ Documentation/git-interpret-trailers.txt: EXAMPLES
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       Signed-off-by: Bob <bob@example.com>
       $ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt
     @@ Documentation/git-interpret-trailers.txt: EXAMPLES
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       Signed-off-by: Bob <bob@example.com>
       Acked-by: Alice <alice@example.com>
     @@ Documentation/git-interpret-trailers.txt: $ git interpret-trailers --trailer 'Cc
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       $ git config trailer.sign.key "Signed-off-by: "
       $ git config trailer.sign.ifmissing add
       $ git config trailer.sign.ifexists doNothing
     @@ Documentation/git-interpret-trailers.txt: $ git config trailer.sign.cmd 'echo "$
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       Signed-off-by: Bob <bob@example.com>
       $ cat msg2.txt
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       Signed-off-by: Alice <alice@example.com>
       $ git interpret-trailers --trailer sign <msg2.txt
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       Signed-off-by: Alice <alice@example.com>
       ------------
     @@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --author="$1"
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       $ git config trailer.help.key "Helped-by: "
       $ git config trailer.help.ifExists "addIfDifferentNeighbor"
       $ git config trailer.help.cmd "~/bin/glog-find-author"
     @@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --author="$1"
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       Helped-by: Junio C Hamano <gitster@pobox.com>
       Helped-by: Christian Couder <christian.couder@gmail.com>
     @@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --grep "$1" --
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       $ git config trailer.ref.key "Reference-to: "
       $ git config trailer.ref.ifExists "replace"
       $ git config trailer.ref.cmd "~/bin/glog-grep"
     @@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --grep "$1" --
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
       ------------
     @@ Documentation/git-interpret-trailers.txt: Reference-to: 8bc9a0c769 (Add copyrigh
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       see: HEAD~2
       $ cat ~/bin/glog-ref
     @@ Documentation/git-interpret-trailers.txt: $ git config trailer.see.cmd "glog-ref
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       See-also: fe3187489d69c4 (subject of related commit)
       ------------
  5:  4a2a0e41e4a =  5:  a4a2ed16dcc doc: trailer: remove redundant phrasing
  6:  f99545409dc =  6:  7a96d0705b9 doc: trailer: use angle brackets for <token> and <value>
  7:  6aba774489a =  7:  f67458a3660 doc: trailer.<token>.command: emphasize deprecation
  8:  b13bd73d248 !  8:  604265c54df doc: trailer: mention 'key' in DESCRIPTION
     @@ Documentation/git-interpret-trailers.txt: token: value
       
       This means that the trimmed <token> and <value> will be separated by
      -`': '` (one colon followed by one space).
     -+`': '` (one colon followed by one space). If the <token> should have a different
     -+string representation than itself, then the 'key' can be configured with
     -+'trailer.<token>.key'.
     ++`': '` (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 'trailer.<token>.key' configuration variable.
       
       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
  9:  ec43e192d6e =  9:  1a3755eacbe doc: trailer: add more examples in DESCRIPTION

-- 
gitgitgadget

[PATCH v4 1/9] doc: trailer: fix grammar

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 4b97f812be8..35faf837892 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -14,7 +14,7 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail
+Parse or add 'trailer' lines that look similar to RFC 822 e-mail
 headers, at the end of the otherwise free-form part of a commit
 message.
 
@@ -249,10 +249,10 @@ for the same <token>, 'trailer.<token>.cmd' is used and
 'trailer.<token>.command' is ignored.
 
 trailer.<token>.cmd::
-	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 '--trailer <token>=<value>' argument to modify the <value> of
-	the trailer that this option would produce.
+	called each time a '--trailer <token>=<value>' argument is specified to
+	modify the <value> of the trailer that this option would produce.
 +
 When the specified command is first called to add a trailer
 with the specified <token>, the behavior is as if a special
-- 
gitgitgadget

[PATCH v4 2/9] doc: trailer: swap verb order

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

This matches the order already used in the NAME section.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 35faf837892..da8fec7d5fe 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -14,7 +14,7 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Parse or add 'trailer' lines that look similar to RFC 822 e-mail
+Add or parse 'trailer' lines that look similar to RFC 822 e-mail
 headers, at the end of the otherwise free-form part of a commit
 message.
 
-- 
gitgitgadget

[PATCH v4 3/9] doc: trailer: drop "commit message part" phrasing

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

The command can take inputs that are either just a commit message, or
an email-like output such as git-format-patch which includes a commit
message, "---" divider, and patch part. The existing explanation blends
these two inputs together in the first sentence

    This command reads some patches or commit messages

which then necessitates using the "commit message part" phrasing (as
opposed to just "commit message") because the input is ambiguous per the
above definition.

This change separates the two input types and explains them separately,
and so there is no longer a need to use the "commit message part"
phrase.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 36 +++++++++++++-----------
 1 file changed, 20 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index da8fec7d5fe..d0a0b303880 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -18,17 +18,23 @@ Add or parse 'trailer' lines that look similar to RFC 822 e-mail
 headers, at the end of the otherwise free-form part of a commit
 message.
 
-This command reads some patches or commit messages from either the
-<file> arguments or the standard input if no <file> is specified. If
-`--parse` is specified, the output consists of the parsed trailers.
-
+This command reads commit messages from either the
+<file> arguments or the standard input if no <file> is specified.
+If `--parse` is specified, the output consists of the parsed trailers.
 Otherwise, this command applies the arguments passed using the
-`--trailer` option, if any, to the commit message part of each input
-file. The result is emitted on the standard output.
+`--trailer` option, if any, to each input file. The result is emitted on the
+standard output.
+
+This command can also operate on the output of linkgit:git-format-patch[1],
+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
+`--no-divider` is specified.
 
 Some configuration variables control the way the `--trailer` 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.
 
 By default, a '<token>=<value>' or '<token>:<value>' argument given
@@ -36,7 +42,7 @@ using `--trailer` 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:
+<token> and <value> will appear in the output like this:
 
 ------------------------------------------------
 token: value
@@ -47,19 +53,17 @@ This means that the trimmed <token> and <value> will be separated by
 
 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.
+at the end of the input. A blank line will be added before the new
+trailer if there isn't one already.
 
-Existing trailers are extracted from the input message by looking for
+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 '---' (followed by a
-space or the end of the line). Such three minus signs start the patch
-part of the message. See also `--no-divider` below.
+space or the end of the line).
 
 When reading trailers, there can be no whitespace before or inside the
 token, but any number of regular space and tab characters are allowed
-- 
gitgitgadget

[PATCH v4 4/9] doc: trailer: examples: avoid the word "message" by itself

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Previously, "message" could mean the input, output, commit message, or
"internal body text inside the commit message" (in the EXAMPLES
section). Avoid overloading this term by using the appropriate meanings
explicitly.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 50 ++++++++++++------------
 1 file changed, 25 insertions(+), 25 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index d0a0b303880..58a9c691492 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -83,12 +83,12 @@ OPTIONS
 
 --trim-empty::
 	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.
 
 --trailer <token>[(=|:)<value>]::
 	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.
 
 --where <placement>::
@@ -102,7 +102,7 @@ OPTIONS
 --if-exists <action>::
 --no-if-exists::
 	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 '--if-exists' overrides all configuration variables
 	and applies to all '--trailer' options until the next occurrence of
 	'--if-exists' or '--no-if-exists'. Possible actions are `addIfDifferent`,
@@ -111,7 +111,7 @@ OPTIONS
 --if-missing <action>::
 --no-if-missing::
 	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 '--if-missing' overrides all configuration variables
 	and applies to all '--trailer' options until the next occurrence of
 	'--if-missing' or '--no-if-missing'. Possible actions are `doNothing`
@@ -178,7 +178,7 @@ first trailer with the same <token>.
 trailer.ifexists::
 	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.
 +
 The valid values for this option are: `addIfDifferentNeighbor` (this
 is the default), `addIfDifferent`, `add`, `replace` or `doNothing`.
@@ -188,10 +188,10 @@ trailer with the same (<token>, <value>) pair is above or below the line
 where the new trailer will be added.
 +
 With `addIfDifferent`, a new trailer will be added only if no trailer
-with the same (<token>, <value>) pair is already in the message.
+with the same (<token>, <value>) pair is already in the input.
 +
 With `add`, a new trailer will be added, even if some trailers with
-the same (<token>, <value>) pair are already in the message.
+the same (<token>, <value>) pair are already in the input.
 +
 With `replace`, an existing trailer with the same <token> will be
 deleted and the new trailer will be added. The deleted trailer will be
@@ -199,12 +199,12 @@ the closest one (with the same <token>) to the place where the new one
 will be added.
 +
 With `doNothing`, nothing will be done; that is no new trailer will be
-added if there is already one with the same <token> in the message.
+added if there is already one with the same <token> in the input.
 
 trailer.ifmissing::
 	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.
 +
 The valid values for this option are: `add` (this is the default) and
 `doNothing`.
@@ -276,37 +276,37 @@ EXAMPLES
 --------
 
 * Configure a 'sign' trailer with a 'Signed-off-by' key, and then
-  add two of these trailers to a message:
+  add two of these trailers to a commit message file:
 +
 ------------
 $ git config trailer.sign.key "Signed-off-by"
 $ 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>
 ------------
 
-* Use the `--in-place` option to edit a message file in place:
+* Use the `--in-place` option to edit a commit message file in place:
 +
 ------------
 $ 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>
@@ -329,7 +329,7 @@ $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re
 $ 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
@@ -337,19 +337,19 @@ $ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.
 $ 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>
 ------------
@@ -377,14 +377,14 @@ test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true
 $ 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>
@@ -401,14 +401,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)
 ------------
@@ -420,7 +420,7 @@ Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
 $ cat msg.txt
 subject
 
-message
+body text
 
 see: HEAD~2
 $ cat ~/bin/glog-ref
@@ -433,7 +433,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)
 ------------
-- 
gitgitgadget

[PATCH v4 5/9] doc: trailer: remove redundant phrasing

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

The phrase "many rules" gets essentially repeated again with "many other
rules", so remove this repetition.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 58a9c691492..7516593c470 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -72,9 +72,8 @@ 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.
 
-Note that 'trailers' 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.
+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.
 
 OPTIONS
 -------
-- 
gitgitgadget

[PATCH v4 6/9] doc: trailer: use angle brackets for <token> and <value>

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

We already use angle brackets elsewhere, so this makes things more
consistent.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 7516593c470..97dc1c8c95d 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -66,9 +66,9 @@ non-whitespace lines before a line that starts with '---' (followed by a
 space or the end of the line).
 
 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.
 
@@ -241,7 +241,7 @@ trailer.<token>.command::
 	This option behaves in the same way as 'trailer.<token>.cmd', 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.
 +
 The 'trailer.<token>.command' option has been deprecated in favor of
 'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
-- 
gitgitgadget

[PATCH v4 7/9] doc: trailer.<token>.command: emphasize deprecation

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

This puts the deprecation notice up front, instead of leaving it to the
next paragraph.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 97dc1c8c95d..6016af5c203 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -238,13 +238,13 @@ trailer.<token>.ifmissing::
 	that option for trailers with the specified <token>.
 
 trailer.<token>.command::
+	Deprecated in favor of 'trailer.<token>.cmd'.
 	This option behaves in the same way as 'trailer.<token>.cmd', 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.
 +
-The 'trailer.<token>.command' option has been deprecated in favor of
-'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
+Note that $ARG in the user's command is
 only replaced once and that the original way of replacing $ARG is not safe.
 +
 When both 'trailer.<token>.cmd' and 'trailer.<token>.command' are given
-- 
gitgitgadget

[PATCH v4 8/9] doc: trailer: mention 'key' in DESCRIPTION

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

The 'key' option is used frequently in the examples at the bottom but
there is no mention of it in the description.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 6016af5c203..7e77cbb1cad 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -49,7 +49,10 @@ token: value
 ------------------------------------------------
 
 This means that the trimmed <token> and <value> will be separated by
-`': '` (one colon followed by one space).
+`': '` (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 'trailer.<token>.key' configuration variable.
 
 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
-- 
gitgitgadget

[PATCH v4 9/9] doc: trailer: add more examples in DESCRIPTION

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Be more up-front about what trailers are in practice with examples, to
give the reader a visual cue while they go on to read the rest of the
description.

Also add an example for multiline values.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/git-interpret-trailers.txt | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index 7e77cbb1cad..55d89614661 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -16,7 +16,18 @@ DESCRIPTION
 -----------
 Add or parse 'trailer' lines that look similar to RFC 822 e-mail
 headers, at the end of the otherwise free-form part of a commit
-message.
+message. For example, in the following commit message
+
+------------------------------------------------
+subject
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+Signed-off-by: Alice <alice@example.com>
+Signed-off-by: Bob <bob@example.com>
+------------------------------------------------
+
+the last two lines starting with "Signed-off-by" are trailers.
 
 This command reads commit messages from either the
 <file> arguments or the standard input if no <file> is specified.
@@ -73,7 +84,12 @@ When reading trailers, there can be no whitespace before or inside the
 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.
+the "folding" in RFC 822. Example:
+
+------------------------------------------------
+token: This is a very long value, with spaces and
+  newlines in it.
+------------------------------------------------
 
 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.
-- 
gitgitgadget