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

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 8, 2017, 01:26 UTC
Message-ID: <xmqqfuby0yll.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <0696f94d-28c2-1f4b-03ee-16553d97f318@gmail.com>

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

Show 5 quoted lines

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

Show 6 quoted lines

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