From: Holger Hellmuth <hellmuth@ira.uka.de>
Date: Tue, 07 Jun 2011 19:00:44 GMT
Subject: Re: Command-line interface thoughts
Message-ID: <4DEE755C.8030108@ira.uka.de>
In-Reply-To: <20110607114526.GA9846@elie>

On 07.06.2011 13:45, Jonathan Nieder wrote:
[...]
> 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.

If someone finds the three-way diff completely mystifiying, how do you 
expect him to resolve a merge conflict at all? Or recognize that there 
is one? Or find the command to use after editing out the conflict markers?

A novice user will have no real mental model anyway. He will be looking 
for simple (and easy to remember) commands for (mostly) simple needs.

> 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

if you look at the comments you put behind the commands, they look very 
much like the proposed diff command. How much time would a novice (and 
everyone else) need to remember your comments compared to your commands? 
A lot less.

Holger.