Re: Consistent terminology: cached/staged/index

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

Miles Bader <miles@gnu.org> writes:

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