From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 11 Aug 2011 04:49:57 GMT
Subject: Re: About git-diff
Message-ID: <7vr54sr1qi.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1313024025.97405.YahooMailClassic@web121818.mail.ne1.yahoo.com>

Luiz Ramos <luizzramos@yahoo.com.br> writes:

> Given this, I'd suggest to change the inline documentation of git-diff (git help diff). In the version of my machine (1.7.4.4), it's like that:
>
> (snip)
> ...
>        git diff [--options] <commit> [--] [<path>...]
>            This form is to view the changes you have in your working tree
>            relative to the named <commit>. You can use HEAD to compare it with
>            the latest commit, or a branch name to compare with the tip of a
>            different branch.
> ...

Strictly speaking, "the changes you have in your working tree" may be what
is confusing. Your working tree does _not_ have "changes"; it only has
"contents". Changes are perceived only if you compare it with something
else, as their _difference_.

This operation compares "the contents of tracked files in your working
tree" with "the contents recorded in the named <commit>"---the result of
this comparison comparison matches what humans perceive as "changes".

So perhaps updating the first sentence with:

	Compare the contents of tracked files in your working tree with
	what is recorded in the named <commit>.

would be all that is necessary. I didn't bother to look but I suspect we
have a simlar description for "git diff [--options] [--] [<path>...]"
form, and it should be updated in a similar way (the only difference is
that it compares "with what is recorded in the index").