Re: Command-line interface thoughts

> If there were an unmerged path in the index, this would do a
> three-way diff, just like "git diff" currently does.
>
> That all sounds great, but I do not find it completely satisfactory.
> One problem is that if this is the mental model people have of
> "git diff", the three-way diff for a multiple stages, behavior of
> "git diff<paths>", and so on, however they are spelled, will look
> completely mystifying.  From the point of view of "this command
> explains the changes in the worktree" they make sense, while from the
> point of view of "compare A to B" they don't make much sense at all.
> So this change just defers the learning process.

> I think part of the problem in the current UI is that the
> documentation never spells out the idea of what plain "git diff" is
> for.  Worse, "--cached means to look to the index in place of the
> worktree" doesn't seem to be spelled out anywhere except gitcli(7).  I
> am not sure it is worth the headache of spelling the latter out
> instead of changing the UI to be easier to explain.
>
> Something like "git diff --index-only" would at least set people
> thinking in the right direction --- "index only as opposed to what?".
>
> With an INDEX pseudo-tree,
>
> 	git diff INDEX
>
> is a synonym for "git diff", and to do "git diff --cached" one would
> have to write
>
> 	git diff HEAD INDEX
>
> I like the "rename --cached to --index-only" proposal more but am
> not too satisfied with it, either.  In a way it is tempting to teach
> people
>
> 	git diff-files -p;	# compare worktree to index
> 	git diff-index -p HEAD;	# compare worktree to HEAD
> 	git diff-index -p --cached HEAD;	# compare index to HEAD
> 	git diff-tree -p HEAD HEAD^;	# compare HEAD^ to HEAD