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

[Linus Arver <linusa@google.com>]

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

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

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

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

> 03+04 should be a single patch

Agreed.

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

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

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

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

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

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

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

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

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

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

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