git diff <commit> doesn't quite work as documented?

git diff <commit> doesn't quite work as documented?

[Olaf Klischat]

oklischat@oklischat:/tmp$ mkdir gittest
oklischat@oklischat:/tmp$ cd gittest/
oklischat@oklischat:/tmp/gittest$ git init
Initialized empty Git repository in /private/tmp/gittest/.git/
oklischat@oklischat:/tmp/gittest$ echo foo > foo.txt
oklischat@oklischat:/tmp/gittest$ git add foo.txt
oklischat@oklischat:/tmp/gittest$ git commit -m foo
[master (root-commit) 54d55f2] foo
 1 file changed, 1 insertion(+)
 create mode 100644 foo.txt
oklischat@oklischat:/tmp/gittest$ echo bar > bar.txt
oklischat@oklischat:/tmp/gittest$ git add bar.txt
oklischat@oklischat:/tmp/gittest$ git commit -m bar
[master 83b2e74] bar
 1 file changed, 1 insertion(+)
 create mode 100644 bar.txt
oklischat@oklischat:/tmp/gittest$ git tag bar-added
oklischat@oklischat:/tmp/gittest$ git rm bar.txt
rm 'bar.txt'
oklischat@oklischat:/tmp/gittest$ git commit -m 'rm bar'
[master 3ca4ff9] rm bar
 1 file changed, 1 deletion(-)
 delete mode 100644 bar.txt
oklischat@oklischat:/tmp/gittest$
oklischat@oklischat:/tmp/gittest$ git checkout bar-added -- bar.txt
oklischat@oklischat:/tmp/gittest$ git reset HEAD
oklischat@oklischat:/tmp/gittest$ git status
On branch master
Untracked files:
  (use "git add <file>..." to include in what will be committed)

	bar.txt

nothing added to commit but untracked files present (use "git add" to track)
oklischat@oklischat:/tmp/gittest$ git diff bar-added   # would expect this to show no differences
diff --git a/bar.txt b/bar.txt
deleted file mode 100644
index 5716ca5..0000000
--- a/bar.txt
+++ /dev/null
@@ -1 +0,0 @@
-bar
oklischat@oklischat:/tmp/gittest$ 
oklischat@oklischat:/tmp/gittest$ git diff bar-added  -- bar.txt   # dito
diff --git a/bar.txt b/bar.txt
deleted file mode 100644
index 5716ca5..0000000
--- a/bar.txt
+++ /dev/null
@@ -1 +0,0 @@
-bar
oklischat@oklischat:/tmp/gittest$ 


`git diff --help' says:

git diff [--options] <commit> [--] [<path>...]
           This form is to view the changes you have in your working tree relative to the named <commit>.

If that were entirely true, the last two commands shouldn't have shown
any differences, right?

On closer inspection, it seems that what `git diff <commit>' really
does is take only those paths in the working directory that are also
in <commit> and compare the resulting tree against <commit>.

We should add some option to that git diff form to make it really do
what the docs claim it does.

Or am I missing something?

Re: git diff <commit> doesn't quite work as documented?

[Junio C Hamano]

Olaf Klischat <olaf.klischat@gmail.com> writes:

> `git diff --help' says:
>
> git diff [--options] <commit> [--] [<path>...]
>            This form is to view the changes you have in your
>            working tree relative to the named <commit>.

That help text is poorly phrased.  

When "git diff" talks about files in your working tree, it always
looks them _through_ the index.  As far as the command is concerned,
a cruft left in your working tree that is not in the index does
*not* exist.

So when your index does not have bar.txt, even if you have an
untracked bar.txt in your directory, i.e.

> oklischat@oklischat:/tmp/gittest$ git status
> On branch master
> Untracked files:
>   (use "git add <file>..." to include in what will be committed)
>
> 	bar.txt

and you have a commit that _has_ that file, then the command thinks
<commit> has the path, and your working tree does *not*.  IOW, this
is...

> oklischat@oklischat:/tmp/gittest$ git diff bar-added
> diff --git a/bar.txt b/bar.txt
> deleted file mode 100644

... totally expected and intended output.

Hope the above explanation clarifies.  A documentation update might
be helpful to new users.

Thanks.

Re: git diff <commit> doesn't quite work as documented?

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 08.09.2017 03:26:
> Olaf Klischat <olaf.klischat@gmail.com> writes:
> 
>> `git diff --help' says:
>>
>> git diff [--options] <commit> [--] [<path>...]
>>            This form is to view the changes you have in your
>>            working tree relative to the named <commit>.
> 
> That help text is poorly phrased.  
> 
> When "git diff" talks about files in your working tree, it always
> looks them _through_ the index.  As far as the command is concerned,
> a cruft left in your working tree that is not in the index does
> *not* exist.
> 
> So when your index does not have bar.txt, even if you have an
> untracked bar.txt in your directory, i.e.
> 
>> oklischat@oklischat:/tmp/gittest$ git status
>> On branch master
>> Untracked files:
>>   (use "git add <file>..." to include in what will be committed)
>>
>> 	bar.txt
> 
> and you have a commit that _has_ that file, then the command thinks
> <commit> has the path, and your working tree does *not*.  IOW, this
> is...
> 
>> oklischat@oklischat:/tmp/gittest$ git diff bar-added
>> diff --git a/bar.txt b/bar.txt
>> deleted file mode 100644
> 
> ... totally expected and intended output.
> 
> Hope the above explanation clarifies.  A documentation update might
> be helpful to new users.

Well, there's a difference between "working tree" and  "working dir".
The wt is "the tree of actual checked out files" per our glossary. So
maybe the doc could point to the glossary (see the glossary for the
difference to the work dir).

But really, this type of misunderstandings comes up often: people try to
understand the doc based on common language terms (which is okay, of
course) and are unaware of the defined meanings of technical terms.
Explaining them in every place where they are used simply does not scale.

Maybe we should make more use of our glossary (extend it, enhance it,
promote it) and somehow mark all technical terms as such when they are
used (say, italics in HTML), or at least when the exact meaning is
relevant like in the case above, and possibly link to the glossary (-item).

Michael

Re: git diff <commit> doesn't quite work as documented?

[Yubin Ruan]

2017-09-08 0:31 GMT+08:00 Olaf Klischat <olaf.klischat@gmail.com>:
> oklischat@oklischat:/tmp$ mkdir gittest
> oklischat@oklischat:/tmp$ cd gittest/
> oklischat@oklischat:/tmp/gittest$ git init
> Initialized empty Git repository in /private/tmp/gittest/.git/
> oklischat@oklischat:/tmp/gittest$ echo foo > foo.txt
> oklischat@oklischat:/tmp/gittest$ git add foo.txt
> oklischat@oklischat:/tmp/gittest$ git commit -m foo
> [master (root-commit) 54d55f2] foo
>  1 file changed, 1 insertion(+)
>  create mode 100644 foo.txt
> oklischat@oklischat:/tmp/gittest$ echo bar > bar.txt
> oklischat@oklischat:/tmp/gittest$ git add bar.txt
> oklischat@oklischat:/tmp/gittest$ git commit -m bar
> [master 83b2e74] bar
>  1 file changed, 1 insertion(+)
>  create mode 100644 bar.txt
> oklischat@oklischat:/tmp/gittest$ git tag bar-added
> oklischat@oklischat:/tmp/gittest$ git rm bar.txt
> rm 'bar.txt'
> oklischat@oklischat:/tmp/gittest$ git commit -m 'rm bar'
> [master 3ca4ff9] rm bar
>  1 file changed, 1 deletion(-)
>  delete mode 100644 bar.txt
> oklischat@oklischat:/tmp/gittest$
> oklischat@oklischat:/tmp/gittest$ git checkout bar-added -- bar.txt
> oklischat@oklischat:/tmp/gittest$ git reset HEAD
> oklischat@oklischat:/tmp/gittest$ git status
> On branch master
> Untracked files:
>   (use "git add <file>..." to include in what will be committed)
>
>         bar.txt
>
> nothing added to commit but untracked files present (use "git add" to track)
> oklischat@oklischat:/tmp/gittest$ git diff bar-added   # would expect this to show no differences
> diff --git a/bar.txt b/bar.txt
> deleted file mode 100644
> index 5716ca5..0000000
> --- a/bar.txt
> +++ /dev/null
> @@ -1 +0,0 @@
> -bar
> oklischat@oklischat:/tmp/gittest$
> oklischat@oklischat:/tmp/gittest$ git diff bar-added  -- bar.txt   # dito
> diff --git a/bar.txt b/bar.txt
> deleted file mode 100644
> index 5716ca5..0000000
> --- a/bar.txt
> +++ /dev/null
> @@ -1 +0,0 @@
> -bar

Michael J Gruber is correct about the working-dir/working-tree things.
A quick example: add a new file with

    $ echo bzz > bzz.txt

then do "git diff bar-added".

The result is the same, because "bzz.txt" is not in the working-tree.

Yubin

> oklischat@oklischat:/tmp/gittest$
>
>
> `git diff --help' says:
>
> git diff [--options] <commit> [--] [<path>...]
>            This form is to view the changes you have in your working tree relative to the named <commit>.
>
> If that were entirely true, the last two commands shouldn't have shown
> any differences, right?
>
> On closer inspection, it seems that what `git diff <commit>' really
> does is take only those paths in the working directory that are also
> in <commit> and compare the resulting tree against <commit>.
>
> We should add some option to that git diff form to make it really do
> what the docs claim it does.
>
> Or am I missing something?