docs: interpret-trailers: reword and add examples
cover 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.
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
Signature · 1 line
gitgitgadget
PATCH 1/11 doc: trailer: fix grammar
From: Linus Arver <[email protected]>
--- Documentation/git-interpret-trailers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-interpret-trailers.txt +1 -1
@@ -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.
Signature · 1 line
gitgitgadget
Re: [PATCH 01/11] doc: trailer: fix grammar
Quoted 12 lines · Linus Arver via GitGitGadget
From: Linus Arver <[email protected]>
Signed-off-by Linus Arver <[email protected]>--- Documentation/git-interpret-trailers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/git-interpret-trailers.txt +0
-0
Documentation/git-interpret-trailers.txt SYNOPSIS · line 19
Quoted 7 lines
Documentation/git-interpret-trailers.txt +1
-1@@ -14,7 +14,7 @@ SYNOPSIS DESCRIPTION ----------- -Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail +Parse or add 'trailer' lines, that look similar to RFC 822 e-mail headers, at the end of the otherwise free-form part of a commit message.
Is that a grammatically incorrect sentence?
The command does help doing these two things, but we can say the command does these two things without closing clarity, so I do not have an objection to the updated text (the only "ungrammatical" part may be that ", that look" should probably be "that look"), but I am not sure if "fix grammar" is a good explanation for this commit.
Re: [PATCH 01/11] doc: trailer: fix grammar
Quoted 15 lines · Junio C Hamano
Quoted 12 lines · Linus Arver via GitGitGadget
From: Linus Arver <[email protected]>
Signed-off-by Linus Arver <[email protected]>--- Documentation/git-interpret-trailers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/git-interpret-trailers.txt +0
-0@@ -14,7 +14,7 @@ SYNOPSIS
Quoted 9 lines
Quoted 7 lines
Documentation/git-interpret-trailers.txt +0
-1DESCRIPTION ----------- -Help parsing or adding 'trailers' lines, that look similar to RFC 822
+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.
Quoted 3 lines
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).
Quoted 3 lines
(the only "ungrammatical" part
may be that ", that look" should probably be "that look"), but I am not sure if "fix grammar" is a good explanation for this commit.
I think punctuation (especially with commas) can be pretty wide-ranging in terms of what is acceptable or not in terms of grammar. But looking at it again I like your version with the comma removed. I'll make the change locally for a v2 series.
Re: [PATCH 01/11] doc: trailer: fix grammar
Quoted 4 lines · Linus Arver
which cannot stand on its own as an independent clause. The correct version would be
Help parse or add 'trailers' lines
You're indeed correct. Thanks.
PATCH 2/11 doc: trailer: swap verb order
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
This matches the order already used in the NAME section.
--- Documentation/git-interpret-trailers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-interpret-trailers.txt +1 -1
@@ -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.
Signature · 1 line
gitgitgadget
Re: [PATCH 02/11] doc: trailer: swap verb order
Quoted 3 lines · Linus Arver via GitGitGadget
From: Linus Arver <[email protected]>
This matches the order already used in the NAME section.
The change makes sense, and the explanation above is also clear.
Quoted 18 lines
Signed-off-by Linus Arver <[email protected]>--- Documentation/git-interpret-trailers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/git-interpret-trailers.txt +1
-1@@ -14,7 +14,7 @@ SYNOPSIS DESCRIPTION ----------- -Parse or add 'trailer' lines, that look similar to RFC 822 e-mail +Add or parse 'trailer' lines, that look similar to RFC 822 e-mail headers, at the end of the otherwise free-form part of a commit message.
PATCH 3/11 doc: trailer: --no-divider: more precise language
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
This uses the phrase "commit message part" instead of "commit message".
--- Documentation/git-interpret-trailers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-interpret-trailers.txt +1 -1
@@ -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
Signature · 1 line
gitgitgadget
Re: [PATCH 03/11] doc: trailer: --no-divider: more precise language
Quoted 3 lines · Linus Arver via GitGitGadget
From: Linus Arver <[email protected]>
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.
Quoted 18 lines
Signed-off-by Linus Arver <[email protected]>--- Documentation/git-interpret-trailers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/git-interpret-trailers.txt +1
-1@@ -131,7 +131,7 @@ OPTIONS --no-divider:: Do not treat `---` as the end of the commit message. Use this - when you know your input contains just the commit message itself + when you know your input contains only the commit message part (and not an email or the output of `git format-patch`). CONFIGURATION VARIABLES
PATCH 4/11 doc: trailer: explain "commit mesage part" on first usage
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
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.
--- Documentation/git-interpret-trailers.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/git-interpret-trailers.txt +3 -3
@@ -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
Signature · 1 line
gitgitgadget
Re: [PATCH 04/11] doc: trailer: explain "commit mesage part" on first usage
Quoted 4 lines · Linus Arver via GitGitGadget
From: Linus Arver <[email protected]>
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.
Quoted 22 lines
Signed-off-by Linus Arver <[email protected]>--- Documentation/git-interpret-trailers.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)Documentation/git-interpret-trailers.txt +3
-3@@ -22,9 +22,9 @@ This command reads some patches or commit messages from either the <file> arguments or the standard input if no <file> is specified. If `--parse` is specified, the output consists of the parsed trailers. -Otherwise, this command applies the arguments passed using the -`--trailer` option, if any, to the commit message part of each input -file. The result is emitted on the standard output. +Otherwise, this command applies the arguments passed using the `--trailer` +option, if any, to the commit message part of each input file (as opposed to the +patch part following a '---' divider). The result is emitted to standard output. Some configuration variables control the way the `--trailer` arguments are applied to each commit message and the way any existing trailer in
Re: [PATCH 04/11] doc: trailer: explain "commit mesage part" on first usage
Quoted 8 lines · Junio C Hamano
Quoted 4 lines · Linus Arver via GitGitGadget
From: Linus Arver <[email protected]>
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.
Quoted 3 lines
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.
Quoted 6 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.
Quoted 26 lines
Quoted 26 lines
Signed-off-by Linus Arver <[email protected]>--- Documentation/git-interpret-trailers.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)Documentation/git-interpret-trailers.txt +0
-0@@ -22,9 +22,9 @@ This command reads some patches or commit messagesfrom either the
<file> arguments or the standard input if no <file> is specified. If--parseis specified, the output consists of the parsed trailers.Documentation/git-interpret-trailers.txt +1
-3-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
--trailerarguments are applied to each commit message and the way any existing trailer in
PATCH 5/11 doc: trailer: remove redundant phrasing
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
The phrase "many rules" gets essentially repeated again with "many other rules", so remove this repetition.
--- Documentation/git-interpret-trailers.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-)
Documentation/git-interpret-trailers.txt +2 -3
@@ -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 -------
Signature · 1 line
gitgitgadget
PATCH 6/11 doc: trailer: trailer.<token>.cmd: add missing verb phrase
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
The phrase "is specified" is implied. Make it explicit.
--- Documentation/git-interpret-trailers.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/git-interpret-trailers.txt +4 -4
@@ -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
Signature · 1 line
gitgitgadget
Re: [PATCH 06/11] doc: trailer: trailer.<token>.cmd: add missing verb phrase
Quoted 3 lines · Linus Arver via GitGitGadget
From: Linus Arver <[email protected]>
The phrase "is specified" is implied. Make it explicit.
Makes sense. Calling it "implied" is generous ;-) Isn't the original just outright ungrammatical?
Quoted 25 lines
Signed-off-by Linus Arver <[email protected]>--- Documentation/git-interpret-trailers.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)Documentation/git-interpret-trailers.txt +4
-4@@ -248,10 +248,10 @@ for the same <token>, 'trailer.<token>.cmd' is used and 'trailer.<token>.command' is ignored. trailer.<token>.cmd:: - This option can be used to specify a shell command that will be called: - once to automatically add a trailer with the specified <token>, and then - each time a '--trailer <token>=<value>' argument to modify the <value> of - the trailer that this option would produce. + This option can be used to specify a shell command that will be called once + to automatically add a trailer with the specified <token>, and then called + each time a '--trailer <token>=<value>' argument is specified to modify the + <value> of the trailer that this option would produce. + When the specified command is first called to add a trailer with the specified <token>, the behavior is as if a special
Re: [PATCH 06/11] doc: trailer: trailer.<token>.cmd: add missing verb phrase
Quoted 7 lines · Junio C Hamano
Quoted 3 lines · Linus Arver via GitGitGadget
From: Linus Arver <[email protected]>
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.
Quoted 2 lines
Isn't the
original just outright ungrammatical?
Indeed.
Should I combine 01+06 together?
Quoted 30 lines
Quoted 30 lines
Signed-off-by Linus Arver <[email protected]>--- Documentation/git-interpret-trailers.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)Documentation/git-interpret-trailers.txt +0
-0@@ -248,10 +248,10 @@ for the same <token>, 'trailer.<token>.cmd' isused and
'trailer.<token>.command' is ignored.trailer.<token>.cmd::
Documentation/git-interpret-trailers.txt +0
-2- This option can be used to specify a shell command that will be called: - once to automatically add a trailer with the specified <token>, andthen
Documentation/git-interpret-trailers.txt +0
-1- each time a '--trailer <token>=<value>' argument to modify the <value>of
Documentation/git-interpret-trailers.txt +1
-1- the trailer that this option would produce. + This option can be used to specify a shell command that will be calledonce
Documentation/git-interpret-trailers.txt +1
-0+ to automatically add a trailer with the specified <token>, and thencalled
Documentation/git-interpret-trailers.txt +1
-0+ each time a '--trailer <token>=<value>' argument is specified tomodify the
Documentation/git-interpret-trailers.txt +1
-0+ <value> of the trailer that this option would produce. + When the specified command is first called to add a trailer with the specified <token>, the behavior is as if a special
Re: [PATCH 06/11] doc: trailer: trailer.<token>.cmd: add missing verb phrase
Quoted 6 lines · Linus Arver
Quoted 2 lines
Isn't the
original just outright ungrammatical?Indeed.
Should I combine 01+06 together?
Either is fine. Thanks.
PATCH 7/11 doc: trailer: use angle brackets for <token> and <value>
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
We already use angle brackets elsewhere, so this makes things more consistent.
--- Documentation/git-interpret-trailers.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/git-interpret-trailers.txt +3 -3
@@ -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.
Signature · 1 line
gitgitgadget
Re: [PATCH 07/11] doc: trailer: use angle brackets for <token> and <value>
Quoted 4 lines · Linus Arver via GitGitGadget
From: Linus Arver <[email protected]>
We already use angle brackets elsewhere, so this makes things more consistent.
Excellent.
Quoted 22 lines
Signed-off-by Linus Arver <[email protected]>--- Documentation/git-interpret-trailers.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)Documentation/git-interpret-trailers.txt +3
-3@@ -62,9 +62,9 @@ space or the end of the line). Such three minus signs start the patch part of the message. See also `--no-divider` below. When reading trailers, there can be no whitespace before or inside the -token, but any number of regular space and tab characters are allowed -between the token and the separator. There can be whitespaces before, -inside or after the value. The value may be split over multiple lines +<token>, but any number of regular space and tab characters are allowed +between the <token> and the separator. There can be whitespaces before, +inside or after the <value>. The <value> may be split over multiple lines with each subsequent line starting with at least one whitespace, like the "folding" in RFC 822.
PATCH 8/11 doc: trailer.<token>.command: refer to existing example
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
--- Documentation/git-interpret-trailers.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-)
Documentation/git-interpret-trailers.txt +5 -4
@@ -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
Signature · 1 line
gitgitgadget
Re: [PATCH 08/11] doc: trailer.<token>.command: refer to existing example
Quoted 6 lines · Linus Arver via GitGitGadget
From: Linus Arver <[email protected]>
Signed-off-by Linus Arver <[email protected]>--- 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.
Quoted 20 lines
Documentation/git-interpret-trailers.txt +5
-4@@ -234,10 +234,11 @@ trailer.<token>.ifmissing:: that option for trailers with the specified <token>. trailer.<token>.command:: - This option behaves in the same way as 'trailer.<token>.cmd', except - that it doesn't pass anything as argument to the specified command. - Instead the first occurrence of substring $ARG is replaced by the - value that would be passed as argument. + This option behaves in the + same way as 'trailer.<token>.cmd', except that it doesn't pass anything as + argument to the specified command. Instead the first occurrence of substring + $ARG is replaced by the <value> from the trailer. See the + 'trailer.see.command' trailer example in the "EXAMPLES" section below. + The 'trailer.<token>.command' option has been deprecated in favor of 'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
Re: [PATCH 08/11] doc: trailer.<token>.command: refer to existing example
Quoted 11 lines · Junio C Hamano
Quoted 6 lines · Linus Arver via GitGitGadget
From: Linus Arver <[email protected]>
Signed-off-by Linus Arver <[email protected]>--- 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.
Quoted 3 lines
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.
Quoted 2 lines
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.
Quoted 3 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?
Quoted 22 lines
Quoted 22 lines
Documentation/git-interpret-trailers.txt +2
-4@@ -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 passanything as
Documentation/git-interpret-trailers.txt +1
-0+ argument to the specified command. Instead the first occurrence ofsubstring
Documentation/git-interpret-trailers.txt +2
-0+ $ARG is replaced by the <value> from the trailer. See the + 'trailer.see.command' trailer example in the "EXAMPLES" section below. + The 'trailer.<token>.command' option has been deprecated in favor of 'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
Re: [PATCH 08/11] doc: trailer.<token>.command: refer to existing example
Quoted 6 lines · Linus Arver
Quoted 3 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.
PATCH 9/11 doc: trailer.<token>.command: emphasize deprecation
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
This puts the deprecation notice up front, instead of leaving it to the next paragraph.
--- Documentation/git-interpret-trailers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-interpret-trailers.txt +1 -1
@@ -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
Signature · 1 line
gitgitgadget
Re: [PATCH 09/11] doc: trailer.<token>.command: emphasize deprecation
Quoted 4 lines · Linus Arver via GitGitGadget
From: Linus Arver <[email protected]>
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?
Quoted 18 lines
Signed-off-by Linus Arver <[email protected]>--- Documentation/git-interpret-trailers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/git-interpret-trailers.txt +1
-1@@ -234,7 +234,7 @@ trailer.<token>.ifmissing:: that option for trailers with the specified <token>. trailer.<token>.command:: - This option behaves in the + Deprecated in favor of 'trailer.<token>.cmd'. This option behaves in the same way as 'trailer.<token>.cmd', except that it doesn't pass anything as argument to the specified command. Instead the first occurrence of substring $ARG is replaced by the <value> from the trailer. See the
Re: [PATCH 09/11] doc: trailer.<token>.command: emphasize deprecation
Quoted 9 lines · Junio C Hamano
Quoted 4 lines · Linus Arver via GitGitGadget
From: Linus Arver <[email protected]>
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.
Quoted 21 lines
Quoted 21 lines
Signed-off-by Linus Arver <[email protected]>--- Documentation/git-interpret-trailers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/git-interpret-trailers.txt +1
-1@@ -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 inthe
same way as 'trailer.<token>.cmd', except that it doesn't pass
anything as
argument to the specified command. Instead the first occurrence of
substring
$ARG is replaced by the <value> from the trailer. See the
PATCH 10/11 doc: trailer: mention 'key' in DESCRIPTION
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
The 'key' option is used frequently in the examples at the bottom but there is no mention of it in the description.
--- Documentation/git-interpret-trailers.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/git-interpret-trailers.txt +3 -1
@@ -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
Signature · 1 line
gitgitgadget
PATCH 11/11 doc: trailer: add more examples in DESCRIPTION
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
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.
--- Documentation/git-interpret-trailers.txt | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-)
Documentation/git-interpret-trailers.txt +18 -2
@@ -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 <[email protected]> +Signed-off-by: Bob <[email protected]> +------------------------------------------------ + +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.
Signature · 1 line
gitgitgadget
Re: [PATCH 11/11] doc: trailer: add more examples in DESCRIPTION
Quoted 24 lines · Linus Arver via GitGitGadget
From: Linus Arver <[email protected]>
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 <[email protected]>--- Documentation/git-interpret-trailers.txt | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-)Documentation/git-interpret-trailers.txt +2
-1@@ -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 +
Documentation/git-interpret-trailers.txt DESCRIPTION · line 30
Quoted 10 lines
Documentation/git-interpret-trailers.txt +10
-0+------------------------------------------------ +subject + +message + +Signed-off-by: Alice <[email protected]> +Signed-off-by: Bob <[email protected]> +------------------------------------------------ + +the last two lines starting with "Signed-off-by" are trailers.
Excellent.
Documentation/git-interpret-trailers.txt When reading trailers, there can be no whitespace before or inside the · line 87
Quoted 11 lines
Documentation/git-interpret-trailers.txt +6
-1@@ -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.
[jc: making sure that the area expert is aware of the topic]
Quoted 25 lines · Linus Arver via GitGitGadget
This series makes some small improvements to the docs for git-interpret-trailers. The intent is to make it easier to read for beginners who have never used this command before.
Linus Arver (11):
doc: trailer: fix grammar
doc: trailer: swap verb order
doc: trailer: --no-divider: more precise language
doc: trailer: explain "commit mesage part" on first usage
doc: trailer: remove redundant phrasing
doc: trailer: trailer.<token>.cmd: add missing verb phrase
doc: trailer: use angle brackets for <token> and <value>
doc: trailer.<token>.command: refer to existing example
doc: trailer.<token>.command: emphasize deprecation
doc: trailer: mention 'key' in DESCRIPTION
doc: trailer: add more examples in DESCRIPTIONDocumentation/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
Quoted 1 line · Junio C Hamano
[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?
Quoted 27 lines
Quoted 25 lines · Linus Arver via GitGitGadget
This series makes some small improvements to the docs for git-interpret-trailers. The intent is to make it easier to read for beginners who have never used this command before.
Linus Arver (11):
doc: trailer: fix grammar
doc: trailer: swap verb order
doc: trailer: --no-divider: more precise language
doc: trailer: explain "commit mesage part" on first usage
doc: trailer: remove redundant phrasing
doc: trailer: trailer.<token>.cmd: add missing verb phrase
doc: trailer: use angle brackets for <token> and <value>
doc: trailer.<token>.command: refer to existing example
doc: trailer.<token>.command: emphasize deprecation
doc: trailer: mention 'key' in DESCRIPTION
doc: trailer: add more examples in DESCRIPTIONDocumentation/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
v2 cover docs: interpret-trailers: reword and add examples
In reply to Linus Arver via GitGitGadgetThis 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
## 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 <[email protected]>
## 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.
@@ 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 <[email protected]> +Signed-off-by: Bob <[email protected]>
@@ 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
Signature · 1 line
gitgitgadget
PATCH v2 1/9 doc: trailer: fix grammar
From: Linus Arver <[email protected]>
--- Documentation/git-interpret-trailers.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/git-interpret-trailers.txt +4 -4
@@ -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
Signature · 1 line
gitgitgadget
PATCH v2 2/9 doc: trailer: swap verb order
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
This matches the order already used in the NAME section.
--- Documentation/git-interpret-trailers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-interpret-trailers.txt +1 -1
@@ -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.
Signature · 1 line
gitgitgadget
PATCH v2 3/9 doc: trailer: drop "commit message part" phrasing
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
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.
--- Documentation/git-interpret-trailers.txt | 35 +++++++++++++----------- 1 file changed, 19 insertions(+), 16 deletions(-)
Documentation/git-interpret-trailers.txt +19 -16
@@ -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
Signature · 1 line
gitgitgadget
PATCH v2 4/9 doc: trailer: examples: avoid the word "message" by itself
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
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.
--- Documentation/git-interpret-trailers.txt | 42 ++++++++++++------------ 1 file changed, 21 insertions(+), 21 deletions(-)
Documentation/git-interpret-trailers.txt +21 -21
@@ -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 <[email protected]>' --trailer 'sign: Bob <[email protected]>' subject -message +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Signed-off-by: Alice <[email protected]> Signed-off-by: Bob <[email protected]> ------------ -* 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 <[email protected]> $ git interpret-trailers --trailer 'Acked-by: Alice <[email protected]>' --in-place msg.txt $ cat msg.txt subject -message +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Signed-off-by: Bob <[email protected]> Acked-by: Alice <[email protected]>
@@ -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 <[email protected]> Helped-by: Christian Couder <[email protected]>
@@ -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) ------------
Signature · 1 line
gitgitgadget
PATCH v2 5/9 doc: trailer: remove redundant phrasing
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
The phrase "many rules" gets essentially repeated again with "many other rules", so remove this repetition.
--- Documentation/git-interpret-trailers.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-)
Documentation/git-interpret-trailers.txt +2 -3
@@ -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 -------
Signature · 1 line
gitgitgadget
PATCH v2 6/9 doc: trailer: use angle brackets for <token> and <value>
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
We already use angle brackets elsewhere, so this makes things more consistent.
--- Documentation/git-interpret-trailers.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/git-interpret-trailers.txt +4 -4
@@ -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
Signature · 1 line
gitgitgadget
PATCH v2 7/9 doc: trailer.<token>.command: emphasize deprecation
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
This puts the deprecation notice up front, instead of leaving it to the next paragraph.
--- Documentation/git-interpret-trailers.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-interpret-trailers.txt +2 -2
@@ -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
Signature · 1 line
gitgitgadget
PATCH v2 8/9 doc: trailer: mention 'key' in DESCRIPTION
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
The 'key' option is used frequently in the examples at the bottom but there is no mention of it in the description.
--- Documentation/git-interpret-trailers.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/git-interpret-trailers.txt +3 -1
@@ -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
Signature · 1 line
gitgitgadget
PATCH v2 9/9 doc: trailer: add more examples in DESCRIPTION
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
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.
--- Documentation/git-interpret-trailers.txt | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-)
Documentation/git-interpret-trailers.txt +18 -2
@@ -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 <[email protected]> +Signed-off-by: Bob <[email protected]> +------------------------------------------------ + +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.
Signature · 1 line
gitgitgadget
Quoted 10 lines · Linus Arver via GitGitGadget
This series makes some small improvements to the docs for git-interpret-trailers. The intent is to make it easier to read for beginners who have never used this command before.
Changes from v1
===============In order of significance:
Quoted 9 lines
* 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.
Quoted 6 lines · Junio C Hamano
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).
Quoted 4 lines
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.
Quoted 6 lines · Linus Arver
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.
v3 cover docs: interpret-trailers: reword and add examples
In reply to Linus Arver via GitGitGadgetThis 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 <[email protected]>' --trailer 'sign: Bob <[email protected]>'
+ $ git interpret-trailers --trailer 'sign: Alice <[email protected]>' --trailer 'sign: Bob <[email protected]>' <msg.txt subject
-message
@@ Documentation/git-interpret-trailers.txt: EXAMPLES
-@@ 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 <[email protected]>' --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 <[email protected]>
+ $ cat msg2.txt
+ subject
+
+-message
++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+ Signed-off-by: Alice <[email protected]>
+ $ git interpret-trailers --trailer sign <msg2.txt
+ subject
+
+-message
++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+ Signed-off-by: Alice <[email protected]>
+ ------------
+@@ 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
-@@ 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
Signature · 1 line
gitgitgadget
PATCH v3 1/9 doc: trailer: fix grammar
From: Linus Arver <[email protected]>
--- Documentation/git-interpret-trailers.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/git-interpret-trailers.txt +4 -4
@@ -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
Signature · 1 line
gitgitgadget
PATCH v3 2/9 doc: trailer: swap verb order
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
This matches the order already used in the NAME section.
--- Documentation/git-interpret-trailers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-interpret-trailers.txt +1 -1
@@ -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.
Signature · 1 line
gitgitgadget
PATCH v3 3/9 doc: trailer: drop "commit message part" phrasing
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
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.
--- Documentation/git-interpret-trailers.txt | 35 +++++++++++++----------- 1 file changed, 19 insertions(+), 16 deletions(-)
Documentation/git-interpret-trailers.txt +19 -16
@@ -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
Signature · 1 line
gitgitgadget
Re: [PATCH v3 3/9] doc: trailer: drop "commit message part" phrasing
Quoted 39 lines · Linus Arver via GitGitGadget
From: Linus Arver <[email protected]>
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 <[email protected]>--- Documentation/git-interpret-trailers.txt | 35 +++++++++++++----------- 1 file changed, 19 insertions(+), 16 deletions(-)Documentation/git-interpret-trailers.txt +3
-4@@ -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
Documentation/git-interpret-trailers.txt Add or parse 'trailer' lines that look similar to RFC 822 e-mail · line 32
Quoted 10 lines
Documentation/git-interpret-trailers.txt +8
-2-`--trailer` option, if any, to the commit message part of each input -file. The result is emitted on the standard output. +`--trailer` option, if any, to each input file. The result is emitted on the +standard output. + +This command can also operate on the output of linkgit:git-format-patch[1], +which is more elaborate than a plain commit message. Namely, such output +includes a commit message (as above), a "---" divider line, and a patch part. +For these inputs, the divider and patch parts are ignored, unless `--no-divider` +is specified.
I think saying "the divider and patch parts are ignored" is a bit ambiguous. It could mean that when a patch is read by the command only its commit message, possibly modified by the command, is emitted on the standard output.
I would suggest something like:
"For these inputs, the divider and patch parts are not modified by this command and are emitted as is on the output, unless --no-divider is specified."
Re: [PATCH v3 3/9] doc: trailer: drop "commit message part" phrasing
Quoted 5 lines · Christian Couder
Quoted 5 lines
+This command can also operate on the output of
linkgit:git-format-patch[1],(quoted diff) +2
-0+which is more elaborate than a plain commit message. Namely, such output +includes a commit message (as above), a "---" divider line, and a patchpart.
Quoted 8 lines
Quoted 3 lines
+For these inputs, the divider and patch parts are ignored, unless
--no-divider
+is specified.I think saying "the divider and patch parts are ignored" is a bit ambiguous. It could mean that when a patch is read by the command only its commit message, possibly modified by the command, is emitted on the standard output.
Indeed. Updated in v4.
PATCH v3 4/9 doc: trailer: examples: avoid the word "message" by itself
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
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.
--- Documentation/git-interpret-trailers.txt | 50 ++++++++++++------------ 1 file changed, 25 insertions(+), 25 deletions(-)
Documentation/git-interpret-trailers.txt +25 -25
@@ -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 <[email protected]>' --trailer 'sign: Bob <[email protected]>' <msg.txt subject -message +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Signed-off-by: Alice <[email protected]> Signed-off-by: Bob <[email protected]> ------------ -* 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 <[email protected]> $ git interpret-trailers --trailer 'Acked-by: Alice <[email protected]>' --in-place msg.txt $ cat msg.txt subject -message +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Signed-off-by: Bob <[email protected]> Acked-by: Alice <[email protected]>
@@ -328,7 +328,7 @@ $ git interpret-trailers --trailer 'Cc: Alice <[email protected]>' --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 <[email protected]> $ cat msg2.txt subject -message +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Signed-off-by: Alice <[email protected]> $ git interpret-trailers --trailer sign <msg2.txt subject -message +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Signed-off-by: Alice <[email protected]> ------------
@@ -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 <[email protected]> Helped-by: Christian Couder <[email protected]>
@@ -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) ------------
Signature · 1 line
gitgitgadget
Re: [PATCH v3 4/9] doc: trailer: examples: avoid the word "message" by itself
Review
Quoted 6 lines
$ git config trailer.sign.key "Signed-off-by" $ cat msg.txt subject(quoted diff) +1
-1-message +Lorem ipsum dolor sit amet, consectetur adipiscing elit.
I am not sure this change is clarifying anything. If you want something clearer for "internal body text inside the commit message", you could perhaps just use "body" or "body text".
I am not against using such latin words, but then why only in the body and not in the subject too? And if it's used in the subject too, then I am not sure it will make it easy for users to understand that the example is using a simple commit message.
Re: [PATCH v3 4/9] doc: trailer: examples: avoid the word "message" by itself
Quoted 11 lines · Christian Couder
Review
Quoted 6 lines
$ git config trailer.sign.key "Signed-off-by" $ cat msg.txt subject(quoted diff) +1
-1-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".
Quoted 4 lines
I am not against using such latin words, but then why only in the body and not in the subject too? And if it's used in the subject too, then I am not sure it will make it easy for users to understand that the example is using a simple commit message.
I can't remember why I didn't just use "body text", which I agree is better than the (albeit famous) Latin phrase. It's shorter, simpler, and also search-friendly (for cases where the user is not sure of exactly which word they want to search for). Updated in v4 to use "body text".
PATCH v3 5/9 doc: trailer: remove redundant phrasing
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
The phrase "many rules" gets essentially repeated again with "many other rules", so remove this repetition.
--- Documentation/git-interpret-trailers.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-)
Documentation/git-interpret-trailers.txt +2 -3
@@ -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 -------
Signature · 1 line
gitgitgadget
PATCH v3 6/9 doc: trailer: use angle brackets for <token> and <value>
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
We already use angle brackets elsewhere, so this makes things more consistent.
--- Documentation/git-interpret-trailers.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/git-interpret-trailers.txt +4 -4
@@ -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
Signature · 1 line
gitgitgadget
PATCH v3 7/9 doc: trailer.<token>.command: emphasize deprecation
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
This puts the deprecation notice up front, instead of leaving it to the next paragraph.
--- Documentation/git-interpret-trailers.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-interpret-trailers.txt +2 -2
@@ -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
Signature · 1 line
gitgitgadget
PATCH v3 8/9 doc: trailer: mention 'key' in DESCRIPTION
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
The 'key' option is used frequently in the examples at the bottom but there is no mention of it in the description.
--- Documentation/git-interpret-trailers.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/git-interpret-trailers.txt +3 -1
@@ -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
Signature · 1 line
gitgitgadget
Re: [PATCH v3 8/9] doc: trailer: mention 'key' in DESCRIPTION
Quoted 16 lines · Linus Arver via GitGitGadget
From: Linus Arver <[email protected]>
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 <[email protected]>--- Documentation/git-interpret-trailers.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)Documentation/git-interpret-trailers.txt +0
-0
Documentation/git-interpret-trailers.txt token: value · line 53
Quoted 7 lines
Documentation/git-interpret-trailers.txt +3
-1@@ -48,7 +48,9 @@ token: value ------------------------------------------------ This means that the trimmed <token> and <value> will be separated by -`': '` (one colon followed by one space). +`': '` (one colon followed by one space). If the <token> should have a different +string representation than itself, then the 'key' can be configured with +'trailer.<token>.key'.
I would rather say something like:
"A <token> can be a shortcut name, for example "sign", instead of the full string, for example "Signed-off-by", which should appear before the separator on the output. This can be configured using the 'trailer.<token>.key' configuration variable."
Re: [PATCH v3 8/9] doc: trailer: mention 'key' in DESCRIPTION
Quoted 7 lines · Christian Couder
Quoted 6 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'.
Quoted 6 lines
I would rather say something like:
"A <token> can be a shortcut name, for example "sign", instead of the full string, for example "Signed-off-by", which should appear before the separator on the output. This can be configured using the 'trailer.<token>.key' configuration variable."
Updated in v4 with a slightly different wording versus your example.
PATCH v3 9/9 doc: trailer: add more examples in DESCRIPTION
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
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.
--- Documentation/git-interpret-trailers.txt | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-)
Documentation/git-interpret-trailers.txt +18 -2
@@ -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 <[email protected]> +Signed-off-by: Bob <[email protected]> +------------------------------------------------ + +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.
Signature · 1 line
gitgitgadget
Quoted 4 lines · Linus Arver via GitGitGadget
This series makes some small improvements to the docs for git-interpret-trailers. The intent is to make it easier to read for beginners who have never used this command before.
Thanks, and sorry for the late review. I found a few things that I think could be improved, but I like the direction.
Quoted 9 lines · Christian Couder
Quoted 3 lines · Linus Arver via GitGitGadget
This series makes some small improvements to the docs for git-interpret-trailers. The intent is to make it easier to read for beginners who have never used this command before.
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!
Quoted 7 lines · Linus Arver
Quoted 2 lines · Christian Couder
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!
v4 cover docs: interpret-trailers: reword and add examples
In reply to Linus Arver via GitGitGadgetThis 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 <[email protected]>' --trailer 'sign: Bob <[email protected]>' <msg.txt subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit. ++body text
@@ Documentation/git-interpret-trailers.txt: EXAMPLES
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit. ++body text
$ git interpret-trailers --trailer 'Acked-by: Alice <[email protected]>' --in-place msg.txt
@@ Documentation/git-interpret-trailers.txt: EXAMPLES
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit. ++body text
@@ 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
$ cat msg2.txt
subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit. ++body text
$ git interpret-trailers --trailer sign <msg2.txt subject
-message
-+Lorem ipsum dolor sit amet, consectetur adipiscing elit. ++body text
------------
@@ 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
@@ 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
Signature · 1 line
gitgitgadget
PATCH v4 1/9 doc: trailer: fix grammar
From: Linus Arver <[email protected]>
--- Documentation/git-interpret-trailers.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/git-interpret-trailers.txt +4 -4
@@ -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
Signature · 1 line
gitgitgadget
PATCH v4 2/9 doc: trailer: swap verb order
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
This matches the order already used in the NAME section.
--- Documentation/git-interpret-trailers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-interpret-trailers.txt +1 -1
@@ -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.
Signature · 1 line
gitgitgadget
PATCH v4 3/9 doc: trailer: drop "commit message part" phrasing
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
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.
--- Documentation/git-interpret-trailers.txt | 36 +++++++++++++----------- 1 file changed, 20 insertions(+), 16 deletions(-)
Documentation/git-interpret-trailers.txt +20 -16
@@ -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
Signature · 1 line
gitgitgadget
PATCH v4 4/9 doc: trailer: examples: avoid the word "message" by itself
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
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.
--- Documentation/git-interpret-trailers.txt | 50 ++++++++++++------------ 1 file changed, 25 insertions(+), 25 deletions(-)
Documentation/git-interpret-trailers.txt +25 -25
@@ -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 <[email protected]>' --trailer 'sign: Bob <[email protected]>' <msg.txt subject -message +body text Signed-off-by: Alice <[email protected]> Signed-off-by: Bob <[email protected]> ------------ -* 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 <[email protected]> $ git interpret-trailers --trailer 'Acked-by: Alice <[email protected]>' --in-place msg.txt $ cat msg.txt subject -message +body text Signed-off-by: Bob <[email protected]> Acked-by: Alice <[email protected]>
@@ -329,7 +329,7 @@ $ git interpret-trailers --trailer 'Cc: Alice <[email protected]>' --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 <[email protected]> $ cat msg2.txt subject -message +body text Signed-off-by: Alice <[email protected]> $ git interpret-trailers --trailer sign <msg2.txt subject -message +body text Signed-off-by: Alice <[email protected]> ------------
@@ -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 <[email protected]> Helped-by: Christian Couder <[email protected]>
@@ -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) ------------
Signature · 1 line
gitgitgadget
PATCH v4 5/9 doc: trailer: remove redundant phrasing
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
The phrase "many rules" gets essentially repeated again with "many other rules", so remove this repetition.
--- Documentation/git-interpret-trailers.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-)
Documentation/git-interpret-trailers.txt +2 -3
@@ -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 -------
Signature · 1 line
gitgitgadget
PATCH v4 6/9 doc: trailer: use angle brackets for <token> and <value>
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
We already use angle brackets elsewhere, so this makes things more consistent.
--- Documentation/git-interpret-trailers.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/git-interpret-trailers.txt +4 -4
@@ -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
Signature · 1 line
gitgitgadget
PATCH v4 7/9 doc: trailer.<token>.command: emphasize deprecation
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
This puts the deprecation notice up front, instead of leaving it to the next paragraph.
--- Documentation/git-interpret-trailers.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-interpret-trailers.txt +2 -2
@@ -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
Signature · 1 line
gitgitgadget
PATCH v4 8/9 doc: trailer: mention 'key' in DESCRIPTION
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
The 'key' option is used frequently in the examples at the bottom but there is no mention of it in the description.
--- Documentation/git-interpret-trailers.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)
Documentation/git-interpret-trailers.txt +4 -1
@@ -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
Signature · 1 line
gitgitgadget
PATCH v4 9/9 doc: trailer: add more examples in DESCRIPTION
In reply to Linus Arver via GitGitGadgetFrom: Linus Arver <[email protected]>
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.
--- Documentation/git-interpret-trailers.txt | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-)
Documentation/git-interpret-trailers.txt +18 -2
@@ -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 <[email protected]> +Signed-off-by: Bob <[email protected]> +------------------------------------------------ + +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.
Signature · 1 line
gitgitgadget