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

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

[Ed Avis]

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>

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

[Matthieu Moy]

Ed Avis <eda@waniasset.com> writes:

> 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,

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 this is not quite true.  Here is an example line from 'git log --raw':
>
>     :100644 100644 9a203c9... daa08a7... M  myfilename

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:

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index ccd4998..0b50717 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -41,8 +41,11 @@ endif::git-format-patch[]
 
 ifndef::git-format-patch[]
 --raw::
-	Generate the raw format.
+	Generate the raw diff format.
 	{git-diff-core? This is the default.}
+ifdef::git-log[]
+	See the "RAW OUTPUT FORMAT" section of linkgit:git-diff[1].
+endif::git-log[]
 endif::git-format-patch[]
 
 ifndef::git-format-patch[]

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

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

[Ed Avis]

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.

-- 
Ed Avis <eda@waniasset.com>

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

[Ed Avis]

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?

-- 
Ed Avis <eda@waniasset.com>

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

[Matthieu Moy]

----- Original Message -----
> 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?

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

> 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'?

I'd rather fix the doc. Patch follows.

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

[PATCH] Documentation/log: clarify what --raw means

[Matthieu Moy]

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

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index ccd4998..163163b 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -41,8 +41,17 @@ endif::git-format-patch[]
 
 ifndef::git-format-patch[]
 --raw::
-	Generate the raw format.
+ifndef::git-log[]
+	Generate the raw diff format.
 	{git-diff-core? This is the default.}
+endif::git-log[]
+ifdef::git-log[]
+	For each commit, show a summary of changes using the raw diff
+	format. See the "RAW OUTPUT FORMAT" section of
+	linkgit:git-diff[1]. This is different from showing the log
+	itself in raw format, which you can achieve with
+	`--format=raw`.
+endif::git-log[]
 endif::git-format-patch[]
 
 ifndef::git-format-patch[]
-- 
2.3.5.2.ge515092.dirty

Re: [PATCH] Documentation/log: clarify what --raw means

[Ed Avis]

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>

Re: [PATCH] Documentation/log: clarify what --raw means

[Junio C Hamano]

Ed Avis <eda@waniasset.com> writes:

> 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'.

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.

Re: [PATCH] Documentation/log: clarify what --raw means

[Eric Sunshine]

On Fri, May 15, 2015 at 11:44 AM, Matthieu Moy <Matthieu.Moy@imag.fr> wrote:
> 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

s/explicitely/explicitly/

> 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>
> ---
> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
> index ccd4998..163163b 100644
> --- a/Documentation/diff-options.txt
> +++ b/Documentation/diff-options.txt
> @@ -41,8 +41,17 @@ endif::git-format-patch[]
>
>  ifndef::git-format-patch[]
>  --raw::
> -       Generate the raw format.
> +ifndef::git-log[]
> +       Generate the raw diff format.
>         {git-diff-core? This is the default.}
> +endif::git-log[]
> +ifdef::git-log[]
> +       For each commit, show a summary of changes using the raw diff
> +       format. See the "RAW OUTPUT FORMAT" section of
> +       linkgit:git-diff[1]. This is different from showing the log
> +       itself in raw format, which you can achieve with
> +       `--format=raw`.
> +endif::git-log[]
>  endif::git-format-patch[]
>
>  ifndef::git-format-patch[]
> --
> 2.3.5.2.ge515092.dirty

Re: [PATCH] Documentation/log: clarify what --raw means

[Junio C Hamano]

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

> 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.

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.

> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
> ---
>  Documentation/diff-options.txt | 11 ++++++++++-
>  1 file changed, 10 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
> index ccd4998..163163b 100644
> --- a/Documentation/diff-options.txt
> +++ b/Documentation/diff-options.txt
> @@ -41,8 +41,17 @@ endif::git-format-patch[]
>  
>  ifndef::git-format-patch[]
>  --raw::
> -	Generate the raw format.
> +ifndef::git-log[]
> +	Generate the raw diff format.
>  	{git-diff-core? This is the default.}
> +endif::git-log[]
> +ifdef::git-log[]
> +	For each commit, show a summary of changes using the raw diff
> +	format. See the "RAW OUTPUT FORMAT" section of
> +	linkgit:git-diff[1]. This is different from showing the log
> +	itself in raw format, which you can achieve with
> +	`--format=raw`.
> +endif::git-log[]
>  endif::git-format-patch[]
>  
>  ifndef::git-format-patch[]

Re: [PATCH] Documentation/log: clarify what --raw means

[Matthieu Moy]

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

> Matthieu Moy <Matthieu.Moy@imag.fr> writes:
>
>> 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.
>
> 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.?

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.}

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

[PATCH v2 1/2] Documentation/log: clarify what --raw means

[Matthieu Moy]

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

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index ccd4998..a1a5868 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -41,8 +41,17 @@ endif::git-format-patch[]
 
 ifndef::git-format-patch[]
 --raw::
-	Generate the raw format.
+ifndef::git-log[]
+	Generate the diff in raw format.
 	{git-diff-core? This is the default.}
+endif::git-log[]
+ifdef::git-log[]
+	For each commit, show a summary of changes using the raw diff
+	format. See the "RAW OUTPUT FORMAT" section of
+	linkgit:git-diff[1]. This is different from showing the log
+	itself in raw format, which you can achieve with
+	`--format=raw`.
+endif::git-log[]
 endif::git-format-patch[]
 
 ifndef::git-format-patch[]
-- 
2.3.5.2.ge515092.dirty

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

[Matthieu Moy]

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`.
 
 * 'format:<string>'
 +
-- 
2.3.5.2.ge515092.dirty

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

[Junio C Hamano]

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/?

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.

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

[Matthieu Moy]

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

> 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.

> 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/

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

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

>>> +`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.
>
>> 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 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.

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 998c7b8..2393f17 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -81,7 +81,7 @@ displayed in full, regardless of whether --abbrev or
 true parent commits, without taking grafts or history
 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,
+`git log --raw`. To get full object names in a raw diff format,
 use `--no-abbrev`.
 
 * 'format:<string>'
-- 
2.4.1-379-g2a6df60