threads / discuss / 32389

Incorrect man page for git-diff

Subject: Incorrect man page for git-diff

## tl;dr

4 messages between Dec 18, 2012 and Dec 18, 2012.

replies: 3people: 2as markdown or json

Manlio Perillo· Dec 18, 2012, 17:40 UTC · lore

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi.

Documentation seems to suggest this is supported, but it is not true:

  $ git diff HEAD:git.c HEAD~100:git.c -- git.c
  usage: git diff [<options>] [<commit> [<commit>]] [--] [<path>...]

unless I'm missing something.

Manlio

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAlDQqncACgkQscQJ24LbaUT9XwCfV40P7lGulSWw+dzVo17EhcDQ YFoAnRb46025qYsKWp9mg6ZTRyuuaG3x =0gO1 -----END PGP SIGNATURE-----

Junio C Hamano· Dec 18, 2012, 18:11 UTC · re: Manlio Perillo · lore

Re: Incorrect man page for git-diff

Manlio Perillo <manlio.perillo@gmail.com> writes:

Show 6 quoted lines

> Documentation seems to suggest this is supported, but it is not true:
>
>   $ git diff HEAD:git.c HEAD~100:git.c -- git.c
>   usage: git diff [<options>] [<commit> [<commit>]] [--] [<path>...]
>
> unless I'm missing something.

Neither HEAD:git.c nor HEAD~100:git.c are commits. You are comparing two blob objects in their raw forms without textconv nor filter.

Manlio Perillo· Dec 18, 2012, 19:10 UTC · re: Junio C Hamano · lore

Re: Incorrect man page for git-diff

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Il 18/12/2012 19:11, Junio C Hamano ha scritto:

Show 10 quoted lines

> Manlio Perillo <manlio.perillo@gmail.com> writes:
> 
>> Documentation seems to suggest this is supported, but it is not true:
>>
>>   $ git diff HEAD:git.c HEAD~100:git.c -- git.c
>>   usage: git diff [<options>] [<commit> [<commit>]] [--] [<path>...]
>>
>> unless I'm missing something.
> 
> Neither HEAD:git.c nor HEAD~100:git.c are commits.

Well, the documentation calls these parameter "commit", later saying "For a more complete list of ways to spell <commit>, see "SPECIFYING REVISIONS".

>  You are
> comparing two blob objects in their raw forms without textconv nor
> filter.
>

Note that I was not missing the fact that git diff does not apply texconv and filters.

I'm not sure the man page is wrong and should be changed:

  -- usage: git diff [<options>] [<commit> [<commit>]] [--] [<path>...]
  ++ usage: git diff [<options>] [<commit> [<commit>]]

Regards  Manlio
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAlDQv40ACgkQscQJ24LbaUT+vwCgj0rjaZbc+/x0+jvAGZydbVKB 244An2pWLj7t4nG3lZzx+LGyH3mjTujS =TmVI -----END PGP SIGNATURE-----

Junio C Hamano· Dec 18, 2012, 19:32 UTC · re: Manlio Perillo · lore

Re: Incorrect man page for git-diff

Manlio Perillo <manlio.perillo@gmail.com> writes:

> I'm not sure the man page is wrong and should be changed:
>
>   -- usage: git diff [<options>] [<commit> [<commit>]] [--] [<path>...]
>   ++ usage: git diff [<options>] [<commit> [<commit>]]

Comparison of two blob objects works entirely in different way (it is not even recursively comparing two tree-shaped things).

I do not think this mode is common enough to deserve to be in the short help text, but it should be in the documentation, perhaps like this patch, I think.

 Documentation/git-diff.txt | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git c/Documentation/git-diff.txt w/Documentation/git-diff.txt
index f8d0819..f8c0601 100644
--- c/Documentation/git-diff.txt
+++ w/Documentation/git-diff.txt
@@ -12,6 +12,7 @@ SYNOPSIS
 'git diff' [options] [<commit>] [--] [<path>...]
 'git diff' [options] --cached [<commit>] [--] [<path>...]
 'git diff' [options] <commit> <commit> [--] [<path>...]
+'git diff' [options] <blob> <blob>
 'git diff' [options] [--no-index] [--] <path> <path>
 
 DESCRIPTION
@@ -55,6 +56,11 @@ directories. This behavior can be forced by --no-index.
 	This is to view the changes between two arbitrary
 	<commit>.
 
+'git diff' [options] <blob> <blob>::
+
+	This form is to view the differences between the raw
+	contents of two blob objects.
+
 'git diff' [--options] <commit>..<commit> [--] [<path>...]::
 
 	This is synonymous to the previous form.  If <commit> on
@@ -72,8 +78,7 @@ directories. This behavior can be forced by --no-index.
 Just in case if you are doing something exotic, it should be
 noted that all of the <commit> in the above description, except
 in the last two forms that use ".." notations, can be any
-<tree>.  The third form ('git diff <commit> <commit>') can also
-be used to compare two <blob> objects.
+<tree>.
 
 For a more complete list of ways to spell <commit>, see
 "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].