Re: Command-line interface thoughts

[Michael Haggerty <mhagger@alum.mit.edu>]

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
>                 ^^^^^^^^^^^^^^^^ -- ???
> 
> First, it is unnecessary power, unnecessary complication.  WTF. you are
> doing comparing _abitrary_ trees?
> 
> 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".  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.

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

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/