git log --raw abbreviates SHA1s, despite what manual says

The manual page for git-log says:

           The raw format shows the entire commit exactly as stored in the
           commit object. Notably, the SHA-1s are displayed in full,
           regardless of whether --abbrev or --no-abbrev are used,

But this is not quite true.  Here is an example line from 'git log --raw':

    :100644 100644 9a203c9... daa08a7... M  myfilename

If I instead run 'git log --raw --no-abbrev', it prints full SHA-1s instead.

I think it would be more useful for the behaviour to match the documentation, and for --raw to imply --no-abbrev in all cases.

Ed Avis <eda@waniasset.com> writes:

It says "the raw format", not "the --raw option". The paragraph you cite is under the PRETTY FORMAT section, hence documents what you can give as argument to --format.

But

git log --format=raw generates an output format with full sha1.

Actually, the documentation *is* misleading, but not the part you're quoting:

  COMMON DIFF OPTIONS
             [...]
         --raw
             Generate the raw format.

It is not very clear that --raw means to generate _the diff_ in raw format.

Probably this patch to the doc would be an improvement IMHO:

Thanks for the explanation. Plain 'git log' does not print any diffs. Does that mean that the --raw flag is a no-op in that case? Perhaps running 'git log --raw' should print a warning

    --raw given for raw-format diffs, but the output format you have chosen
    does not include diffs.  Did you mean 'git log --format=raw'?

You might even rename the option to --raw-diff-format, with the older one still accepted for backwards compatibility.

Ah, I see that --raw not only specifies the raw format should be used for diffs, but also enables printing diffs even if they wouldn't be otherwise.

Note that --format=raw still prints abbreviated SHA-1s in the diff:

    % git log --format=raw --raw
    ...
    :100644 100644 c30ec14... b87bb8b... M  myfilename

Possibly --format=raw should imply --no-abbrev?

----- Original Message -----

No, it displays the patch, in raw format. But you're right that the doc is unclear.

I'd rather fix the doc. Patch follows.

There are several "raw formats", and describing --raw as "Generate the raw format" in the documentation for git-log seems to imply that it generates the raw *log* format.

Clarify the wording by saying "raw diff format" explicitely, and make a special-case for "git log": "git log --raw" does not just change the format, it shows something which is not shown by default.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/diff-options.txt | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

Thanks, I think that is a bit clearer.

You might also need to clarify the part about --format=raw where it says 'SHA-1s are displayed in full, regardless of whether --abbrev or --no-abbrev'. That does not currently apply to the diffs, where --no-abbrev still needs to be explicitly given.

Ed Avis <eda@waniasset.com> writes:

This part of the description being "--format" option, the "SHA-1s" the description refers to are the ones that appear in the commit object itself, something like:

    tree 2b5bfdf7798569e0b59b16eb9602d5fa572d6038
    author Linus Torvalds <torvalds@ppc970.osdl.org> 1112911993 -0700
    committer Linus Torvalds <torvalds@ppc970.osdl.org> 1112911993 -0700

    Initial revision of "git", the information manager from hell

And the commit object itself does not have any "diff", as you are not comparing anything with any other thing. It is about recording one single state in time.

I think that is what the reader needs to be made aware of, and the current documentation is not doing a good job at it.

On Fri, May 15, 2015 at 11:44 AM, Matthieu Moy <Matthieu.Moy@imag.fr> wrote:

s/explicitely/explicitly/

Matthieu Moy <Matthieu.Moy@imag.fr> writes:

Being a pedant, I find "generate the raw diff format" somewhat a strange wording. Aren't we generating a diff in the raw format (as opposed to in other format like the textual patch format), generating a diff using the raw format, etc.?

In any case, this is an improvement.  Thanks.  Will queue.

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

I think I chose this wording because I didn't want to say "raw format" for git-log(1), but then I added more special-cases for git-log.

I changed it to

ifndef::git-log[]
	Generate the diff in raw format.
	{git-diff-core? This is the default.}

There are several "raw formats", and describing --raw as "Generate the raw format" in the documentation for git-log seems to imply that it generates the raw *log* format.

Clarify the wording by saying "raw diff format" explicitly, and make a special-case for "git log": "git log --raw" does not just change the format, it shows something which is not shown by default.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
Since v1: Reworded after Junio's remark, typo fix thanks to Eric Sunshine.

 Documentation/diff-options.txt | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

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(-)

Matthieu Moy <Matthieu.Moy@imag.fr> writes:

s/commits in a raw/object names in a raw/?

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? It somehow looks out of place to have this description only for 'raw'. I think it is OK because it is hard to imagine how other formats would affect patch output ("git log --pretty=<any>" would not give any patch, "git log --pretty=<any> -p" would always give textual patch and not diff-tree raw patch), but it is possible to confuse between '--pretty=raw' and '--raw'.

Thanks.

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

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

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 <Matthieu.Moy@grenoble-inp.fr> writes:

I think we are in agrement, then.

I have this queued with the usual "SQUASH" label on top, so there is no need to resend.

Thanks.