threads / patch / 59712

patch, 11 partsdocs: interpret-trailers: reword and add examples

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

## tl;dr

73 messages between May 8, 2023 and Jun 15, 2023. Diffs are folded; open one to read it.

replies: 72people: 3as markdown or json

Linus Arver via GitGitGadget· May 8, 2023, 17:27 UTC · lore

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
Linus Arver via GitGitGadget· May 8, 2023, 17:27 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +1 −1
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
Junio C Hamano· May 8, 2023, 19:19 UTC · re: Linus Arver via GitGitGadget · lore

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

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 19 quoted lines
> 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.

Linus Arver· May 8, 2023, 19:33 UTC · re: Junio C Hamano · lore

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

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(-)
Show 6 quoted lines
>> 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
Show 7 quoted lines
>>   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.

Junio C Hamano· May 8, 2023, 21:35 UTC · re: Linus Arver · lore

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

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.
Linus Arver via GitGitGadget· May 8, 2023, 17:27 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +1 −1
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
Junio C Hamano· May 8, 2023, 19:20 UTC · re: Linus Arver via GitGitGadget · lore

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

"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.
Show 18 quoted lines
>
> 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.
Linus Arver via GitGitGadget· May 8, 2023, 17:27 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +1 −1
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
Junio C Hamano· May 8, 2023, 19:32 UTC · re: Linus Arver via GitGitGadget · lore

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

"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.
Show 18 quoted lines
> 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
Linus Arver via GitGitGadget· May 8, 2023, 17:27 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +2 −3
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
Linus Arver via GitGitGadget· May 8, 2023, 17:27 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +3 −3
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
Junio C Hamano· May 8, 2023, 19:37 UTC · re: Linus Arver via GitGitGadget · lore

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

"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.

Show 22 quoted lines
> 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
Linus Arver· May 10, 2023, 06:44 UTC · re: Junio C Hamano · lore

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

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.

Show 6 quoted lines
> 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(-)
Show 9 quoted lines
>> 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.
Show 9 quoted lines
>> -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
Linus Arver via GitGitGadget· May 8, 2023, 17:27 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +3 −3
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
Junio C Hamano· May 8, 2023, 19:38 UTC · re: Linus Arver via GitGitGadget · lore

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

"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.
Show 22 quoted lines
>
> 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.
Linus Arver via GitGitGadget· May 8, 2023, 17:27 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +4 −4
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
Junio C Hamano· May 8, 2023, 19:41 UTC · re: Linus Arver via GitGitGadget · lore

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

"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?

Show 25 quoted lines
>
> 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
Linus Arver· May 10, 2023, 06:52 UTC · re: Junio C Hamano · lore

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

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(-)
Show 8 quoted lines
>> 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.
Show 17 quoted lines
>>   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
Junio C Hamano· May 10, 2023, 16:37 UTC · re: Linus Arver · lore

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

Linus Arver <linusa@google.com> writes:
Show 6 quoted lines
>> Isn't the
>> original just outright ungrammatical?
>
> Indeed.
>
> Should I combine 01+06 together?
Either is fine.  Thanks.
Linus Arver via GitGitGadget· May 8, 2023, 17:27 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +5 −4
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
Junio C Hamano· May 8, 2023, 19:47 UTC · re: Linus Arver via GitGitGadget · lore

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

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 6 quoted lines
> 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.

Show 20 quoted lines
> 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
Linus Arver· May 10, 2023, 07:08 UTC · re: Junio C Hamano · lore

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

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?

Show 7 quoted lines
>> 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>.
Show 15 quoted lines
>>   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
Junio C Hamano· May 10, 2023, 16:42 UTC · re: Linus Arver · lore

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

Linus Arver <linusa@google.com> writes:
Show 6 quoted lines
>> 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.
Linus Arver via GitGitGadget· May 8, 2023, 17:27 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +1 −1
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
Junio C Hamano· May 8, 2023, 19:48 UTC · re: Linus Arver via GitGitGadget · lore

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

"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?

Show 18 quoted lines
> 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
Linus Arver· May 10, 2023, 07:10 UTC · re: Junio C Hamano · lore

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

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(-)
Show 7 quoted lines
>> 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>.
Show 9 quoted lines
>>   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
Linus Arver via GitGitGadget· May 8, 2023, 17:27 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +3 −1
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
Linus Arver via GitGitGadget· May 8, 2023, 17:27 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +18 −2
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
Junio C Hamano· May 8, 2023, 19:50 UTC · re: Linus Arver via GitGitGadget · lore

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

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 34 quoted lines
> 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.
Show 11 quoted lines
> @@ -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.
Junio C Hamano· May 8, 2023, 17:49 UTC · re: Linus Arver via GitGitGadget · lore

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

[jc: making sure that the area expert is aware of the topic]
"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 25 quoted lines
> 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
Linus Arver· May 8, 2023, 19:07 UTC · re: Junio C Hamano · lore

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

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.
Show 12 quoted lines
>> 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(-)
Show 6 quoted lines
>> 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
Linus Arver via GitGitGadget· May 11, 2023, 21:19 UTC · re: Linus Arver via GitGitGadget · lore

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

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
Linus Arver via GitGitGadget· May 11, 2023, 21:19 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +4 −4
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
Linus Arver via GitGitGadget· May 11, 2023, 21:19 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +1 −1
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
Linus Arver via GitGitGadget· May 11, 2023, 21:19 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +19 −16
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
Linus Arver via GitGitGadget· May 11, 2023, 21:19 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +2 −3
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
Linus Arver via GitGitGadget· May 11, 2023, 21:19 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +4 −4
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
Linus Arver via GitGitGadget· May 11, 2023, 21:19 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +21 −21
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
Linus Arver via GitGitGadget· May 11, 2023, 21:19 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +18 −2
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
Linus Arver via GitGitGadget· May 11, 2023, 21:19 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +2 −2
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
Linus Arver via GitGitGadget· May 11, 2023, 21:19 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +3 −1
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
Junio C Hamano· May 12, 2023, 23:24 UTC · re: Linus Arver via GitGitGadget · lore

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

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 19 quoted lines
> 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.
Linus Arver· May 16, 2023, 22:57 UTC · re: Junio C Hamano · lore

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

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.
Junio C Hamano· May 16, 2023, 23:18 UTC · re: Linus Arver · lore

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

Linus Arver <linusa@google.com> writes:
Show 6 quoted lines
> 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.
Linus Arver via GitGitGadget· Jun 6, 2023, 02:08 UTC · re: Linus Arver via GitGitGadget · lore

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

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
Linus Arver via GitGitGadget· Jun 6, 2023, 02:08 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +4 −4
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
Linus Arver via GitGitGadget· Jun 6, 2023, 02:08 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +1 −1
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
Linus Arver via GitGitGadget· Jun 6, 2023, 02:08 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +19 −16
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
Christian Couder· Jun 14, 2023, 15:00 UTC · re: Linus Arver via GitGitGadget · lore

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

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

Show 49 quoted lines
>
> 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."

Linus Arver· Jun 15, 2023, 02:57 UTC · re: Christian Couder · lore

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

Christian Couder <christian.couder@gmail.com> writes:
Show 8 quoted lines
>> +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.
Linus Arver via GitGitGadget· Jun 6, 2023, 02:08 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +25 −25
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
Christian Couder· Jun 14, 2023, 15:12 UTC · re: Linus Arver via GitGitGadget · lore

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

Show 6 quoted lines
>  $ 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.

Linus Arver· Jun 15, 2023, 03:03 UTC · re: Christian Couder · lore

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

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".

Linus Arver via GitGitGadget· Jun 6, 2023, 02:08 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +2 −3
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
Linus Arver via GitGitGadget· Jun 6, 2023, 02:08 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +4 −4
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
Linus Arver via GitGitGadget· Jun 6, 2023, 02:08 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +2 −2
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
Linus Arver via GitGitGadget· Jun 6, 2023, 02:08 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +3 −1
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
Christian Couder· Jun 14, 2023, 15:27 UTC · re: Linus Arver via GitGitGadget · lore

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

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

Show 23 quoted lines
>
> 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."

Linus Arver· Jun 15, 2023, 03:04 UTC · re: Christian Couder · lore

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

Christian Couder <christian.couder@gmail.com> writes:
Show 6 quoted lines
>>   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.
Linus Arver via GitGitGadget· Jun 6, 2023, 02:08 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +18 −2
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
Christian Couder· Jun 14, 2023, 15:36 UTC · re: Linus Arver via GitGitGadget · lore

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

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.

Linus Arver· Jun 15, 2023, 03:06 UTC · re: Christian Couder · lore

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

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!
Christian Couder· Jun 15, 2023, 07:47 UTC · re: Linus Arver · lore

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

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!
Linus Arver via GitGitGadget· Jun 15, 2023, 02:53 UTC · re: Linus Arver via GitGitGadget · lore

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

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
Linus Arver via GitGitGadget· Jun 15, 2023, 02:53 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +4 −4
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
Linus Arver via GitGitGadget· Jun 15, 2023, 02:53 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +1 −1
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
Linus Arver via GitGitGadget· Jun 15, 2023, 02:53 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +20 −16
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
Linus Arver via GitGitGadget· Jun 15, 2023, 02:53 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +2 −3
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
Linus Arver via GitGitGadget· Jun 15, 2023, 02:53 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +25 −25
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
Linus Arver via GitGitGadget· Jun 15, 2023, 02:53 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +4 −4
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
Linus Arver via GitGitGadget· Jun 15, 2023, 02:53 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +2 −2
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
Linus Arver via GitGitGadget· Jun 15, 2023, 02:53 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +4 −1
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
Linus Arver via GitGitGadget· Jun 15, 2023, 02:53 UTC · re: Linus Arver via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-interpret-trailers.txt +18 −2
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

← back to recent threads