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

From: Michael J Gruber <git@grubix.eu>
Date: Sep 8, 2017, 12:58 UTC
Message-ID: <c08ed84a-6c65-4278-851b-439c63c501ea@grubix.eu>
In-Reply-To: <xmqqfuby0yll.fsf@gitster.mtv.corp.google.com>

Junio C Hamano venit, vidit, dixit 08.09.2017 03:26:

Show 37 quoted lines

> 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