Re: [PATCH v2 2/2] Documentation/log: clarify sha1 non-abbreviation in log --raw

From: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Date: May 18, 2015, 21:28 UTC
Message-ID: <vpqd21xpocl.fsf@anie.imag.fr>
In-Reply-To: <xmqq4mn9bobv.fsf@gitster.dls.corp.google.com>

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

Show 24 quoted lines

> Matthieu Moy <Matthieu.Moy@imag.fr> writes:
>
>> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
>> ---
>> This patch is new.
>>
>>  Documentation/pretty-formats.txt | 5 ++++-
>>  1 file changed, 4 insertions(+), 1 deletion(-)
>>
>> diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
>> index dcf7429..c434ecc 100644
>> --- a/Documentation/pretty-formats.txt
>> +++ b/Documentation/pretty-formats.txt
>> @@ -79,7 +79,10 @@ stored in the commit object.  Notably, the SHA-1s are
>>  displayed in full, regardless of whether --abbrev or
>>  --no-abbrev are used, and 'parents' information show the
>>  true parent commits, without taking grafts or history
>> -simplification into account.
>> +simplification into account. Note that this format affects the way
>> +commits are displayed, but not the way the diff is shown e.g. with
>> +`git log --raw`. To get unabbreviated commits in a raw diff format,
>> +use `--no-abbrev`.
>
> s/commits in a raw/object names in a raw/?

Yes, that is better. Let me know if you want me to resend.

Show 6 quoted lines

> I wondered what "this format" was, and had to read the patch with
> "show -U60" to realize that this is about "--pretty=<format>".
> Perhaps the introductory text of the first paratraph in the section
> is not clear enough that not just --pretty=raw but --pretty=anything
> is about how the commit object is shown and has nothing to do with
> how patches are shown, and that is why this new text is necessary?

I would say no, since other formats do not have this "raw log format" Vs "raw diff format" confusion.

I looked for a way to have this disclaimer under 'PRETTY FORMATS' outside the 'raw' subsection, but I found no place where this would not be weird like "oh, BTW, this section has nothing to do with patches" when the user did not have any notion of patch in mind.

The confusion was rather serious here since 1) looking for the string "raw format" was directly pointing to the paragraph I patched, and one may do this search looking for information on raw diff format, and 2) the text was explicitly saying that all sha1s were unabreviated while --format=raw --raw still shows abreviated commits. Neither of the confusion are problematic with other formats.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/