Re: Consistent terminology: cached/staged/index

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 15, 2011, 00:12 UTC
Message-ID: <7vaahyqhor.fsf@alter.siamese.dyndns.org>
In-Reply-To: <AANLkTikyc5QEou8Em-3HkLSHWHQyx+MnYMQ9OSN33_QS@mail.gmail.com>

Miles Bader <miles@gnu.org> writes:

Show 6 quoted lines

> [BTW, isn't the name "--index-only" something of a misnomer?  If
> something is called "--XXX-only", that implies that the default
> operation uses "XXX + something else" instead of XXX, but that
> otherwise they are the same.  However in fact the difference in
> behavior resulting from --cached is more subtle: it changes _both_
> sides of the diff (default: worktree<->index; --cached: index<->HEAD).

Not really.

There are three entities involved: a tree-ish, the index, and the working tree. Because the index is a singleton, when you say "compare the index with...", you only have two choices, either compare it against a tree-ish, or compare it with the working tree. If you want to do the latter, you just use the command without --cached nor tree-ish.

The --cached form defaults to HEAD only because --cached mode is about comparing the index against a tree-ish (think about "diff --cached HEAD^").

The same thing for --index-only. The moment you said "compare the index with...", there are only two other things to compare it against and that is the only reason why you do not have to write HEAD.

This is a tangent, but the natural patch-flow is for you to prepare your change in the working tree, add the changes to the index, and then build a tree out of the index into a commit.

That is why "diff" shows changes in the working tree relative to what is in the index, "diff --cached [<tree-ish>]" shows changes in the index relative to the tree-ish (defaulting to HEAD). The natural flow of the development determines the natural direction of comparison between these entities.

It does not make sense to compare in the other direction (i.e. how is the index different compared to the working tree) _unless_ you are contemplating to revert some changes you have made, and -R is there exactly for that reason (here I am responding to the idea some people had in an earlier incarnation of this thread of saying "diff INDEX HEAD", "diff HEAD WORKTREE" etc., using pseudo <ref> syntax, and explaining why it is not such a good idea---and why this is a tangent).