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

[Junio C Hamano <gitster@pobox.com>]

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.