Re: [PATCH 04/11] doc: trailer: explain "commit mesage part" on first usage
- From
- Linus Arver <linusa@google.com>
- Date
- May 10, 2023, 06:44 UTC
- Message-ID
- <owlymt2cn0rm.fsf@fine.c.googlers.com>
- In-Reply-To
- <xmqqa5yeobrj.fsf@gitster.g>
Junio C Hamano <gitster@pobox.com> writes:
> "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:
>> From: Linus Arver <linusa@google.com>
>> This phrase is used for the first time here, but it's not explained what >> it means. So explain it just in case it's not obvious.
> 03+04 should be a single patch
Agreed.
> otherwise it would > waste reviewer's time (just like I did thinking and writing about > 03/11).
Thank you for the pointer. I will be more careful about patch order moving forward.
Show 6 quoted lines
> Or just drop "part". "git cat-file commit HEAD | sed -e '1,/^$/d'" > is a good material to use with "--no-divider" because it only has > the "commit message". The "part" implies you first had something > that has both "commit message" and something else and you split > that combination into two (or more) parts. But that does not have > to be the case. I think that made 03/11 confusing, at least to me.
Looking back, I don't think I had a good grasp of what "commit message part" meant. When I wrote this series I thought "commit message part" meant everything in the output of git-format-patch until hitting the "---" divider. But as you point out in your
git cat-file commit HEAD | sed -e '1,/^$/d'
example, technically there is never any ambiguity of what the commit message contains (it only contains a commit message, not a "commit message part" and a separate "patch part"). And the output of git-format-patch is a patch (which contains the commit message and also other things), not a commit message with different subparts. I was operating under this flawed understanding, oops.
That being said, there are several instances in the DESCRIPTION section when we use the "commit message part" phrasing (as opposed to just "commit message"). I am leaning toward just dropping "part" as you suggested. Also, I think we should add an explanation of how git-interpret-trailers sees the incoming text, how it gives special treatment to a "---" divider line, how it uses this line to mark off a commit message part (and then uses this part as the default location of adding trailers, unless specifying a "--no-divider" flag), etc. This could be in a revamped 03+04 patch, or perhaps left out until another day. I'll see what I can do in v2.
>> Signed-off-by: Linus Arver <linusa@google.com> >> --- >> Documentation/git-interpret-trailers.txt | 6 +++--- >> 1 file changed, 3 insertions(+), 3 deletions(-)
Show 9 quoted lines
>> diff --git a/Documentation/git-interpret-trailers.txt >> b/Documentation/git-interpret-trailers.txt >> index 3e60a6eaabc..7d6e250f37e 100644 >> --- a/Documentation/git-interpret-trailers.txt >> +++ b/Documentation/git-interpret-trailers.txt >> @@ -22,9 +22,9 @@ This command reads some patches or commit messages >> from either the >> <file> arguments or the standard input if no <file> is specified. If >> `--parse` is specified, the output consists of the parsed trailers.
Show 9 quoted lines
>> -Otherwise, this command applies the arguments passed using the >> -`--trailer` option, if any, to the commit message part of each input >> -file. The result is emitted on the standard output. >> +Otherwise, this command applies the arguments passed using the >> `--trailer` >> +option, if any, to the commit message part of each input file (as >> opposed to the >> +patch part following a '---' divider). The result is emitted to >> standard output.
>> Some configuration variables control the way the `--trailer` arguments >> are applied to each commit message and the way any existing trailer in