Re: Command-line interface thoughts

From: Jakub Narebski <jnareb@gmail.com>
Date: Jun 10, 2011, 10:19 UTC
Message-ID: <201106101219.18497.jnareb@gmail.com>
In-Reply-To: <4DF150FB.9070304@alum.mit.edu>

On Fri, 10 Jun 2011, Michael Haggerty wrote:

Show 15 quoted lines

> On 06/10/2011 12:04 AM, Jakub Narebski wrote:
>> On Thu, 9 Jan 2011, Michael Haggerty wrote:
>>> On 06/09/2011 10:04 PM, Jeff King wrote:
>>>> I'm less sure about these new tokens, for a few reasons:
>>>>
>>>>   1. You get less useful answers in some situations by treating each
>>>>      stage as a separate tree (e.g., lack of combined diff). So why
>>>>      would I want to use them?
>>>
>>> Wouldn't it be nice to be able to do a combined diff between *any* two
>>> trees?  Then the nonuniform merge behavior of "git diff" would be a
>>> special case of a general concept:
>>>
>>>     git diff3 OURS NEXT THEIRS
>>                ^^^^^^^^^^^^^^^^ -- ???

[...]

Show 12 quoted lines

>> Second, for files with merge conflicts "git diff" is the same as
>> "git diff3 OURS THEIRS WTREE", not "git diff3 OURS NEXT THEIRS".
>> As you can see it is very easy to construct wrong options to git-diff,
>> and end up with nonsense!
> 
> Since there is currently no "git diff3" command, I decided to orient the
> hypothetical "git diff3" command based on diff3(1), which uses
> 
>     diff3 [OPTION]... MYFILE OLDFILE YOURFILE
> 
> By using a new command (diff3) that is somewhat familiar to some users,
> we could reduce the amount of overloading of "git diff".

But here, by using "git diff3" which does not work at all like diff3, and which output is very different from "git diff --cc" combined diff format, you increase confusion, not decrease it. By using somewhat familiar name that behaves differently from said familiar tool, you make user's life unnecessary harder.

Let me explain how "git diff --cc" is diferent from "diff3".

First, "git diff --cc" works differently than "diff3";

 * "git diff --cc" can do combined diff of arbitrary number of 3 things
   or more; "diff3" is limited to 3.

 * "git diff --cc" is about comparing merge results with its sources
   (parents) and the like; "diff3" is about comparing two divergent
   versions with their ancestor (merge base) -- opposite direction of
   following parent links.

 * therefore natural ordering for "git diff --cc" is 'PARENT^1 PARENT^2
   MERGE' (like 'FROM TO'), while "diff3" uses arbitrary ordering of
   'MYFILE OLDFILE YOURFILE'... which I always have to check in docs.

Second, "diff3" output is different from "git diff --cc" output... and as you see above rightly so.

Third, it was still a mistake to write

  git diff3 OURS NEXT THEIRS

In result of combined diff that "git diff" shows in case of merge conflict differences between OURS, THEIRS, and WTREE version; NEXT isn't there, and you didn't mention WTREE though it is here. But see also the next point.

Fourth, with "git diff3 OURS NEXT THEIRS" / "git diff3 OURS THEIRS WTREE" you either introduce interface inefficiency, or UI inconsistency, or UI complication.

In the case of conflict "git diff" shows 3-way combined diff for files with conflict (OURS, THEIRS, WTREE), but it shows ordinary diff from stage '0' (NEXT, WTREE) for files which resolved cleanly; the fact that file resolved cleanly doesn't necessarily mean that it resolved correctly...

So you either make "git diff3 OURS NEXT THEIRS" show only 3-way combined diff part, consistent with 'diff3' name, but making for an *inefficient* user interface -- now you have to use two commands for single piece of information.

Or you make "git diff3 OURS NEXT THEIRS" behave like current "git diff", i.e. show the whole diff from index, be it conflict or a fixup, which is efficient but *inconsistent*.

Or you make "git diff3 OURS NEXT THEIRS" compare stage 0 (NEXT?) with worktree if there is no conflict, and stages 'ours' and 'theirs' with worktree if there is conflict... which is *weird*, especially that you defined OURS as "'ours' or stage 0" (union of stage 'ours' and stage 0), covering all resolved and unresolved files.

> I, for one, 
> was surprised and confused the first few times I typed "git diff" during
> a merge and got a three-way diff rather than what I expected, namely the
> two-way diff that is called "git diff NEXT WTREE" in the proposed notation.

This three way diff is more useful...

Show 15 quoted lines

>> I won't repear the THIRD time simple and around *three times shorter*
>> explanation on _when_ to use which form: "git diff" for your own remaining
>> changes that can be "git add"-ef, "git diff --staged" for which changes
>> are staged i.e. what you have "git add"-ed, and "git diff HEAD" to compare
>> current with last.
> 
> You don't need to repeat for my benefit the existing version of the
> commands; I knew them long before this discussion started.  And
> repeating them does not make them more obvious.
> 
> For a beginner, the main goal is not brevity.  It is discoverability and
> memorability.  Obviously our priorities and tastes differ and we will
> not come to agreement.  I would be very interested what people with a
> fresh memory of struggling to learn the git CLI think would have been
> easier to learn.

You say that user would think something like that:

  "I need to compare staged contents and working area.  To do that I use
   'git diff NEXT WTREE' / have to look up documentation to find that it
   is 'git diff'".

I say that I guess user would think something like that:

  "I want to check if and what remaining changes are.  To do that I use
   'git diff' / have to look up documentation which stages I have to
   compare to find that it is 'git diff NEXT WTREE'".

'git diff' / 'git diff --cached' / 'git diff HEAD' is about use cases (or "user stories"). 'git diff NEXT WTREE' / 'git diff HEAD NEXT' / / 'git diff HEAD WTREE' are about mechanism.

-- 
Jakub Narebski
Poland