Re: Command-line interface thoughts

From: Jakub Narebski <jnareb@gmail.com>
Date: Jun 9, 2011, 22:04 UTC
Message-ID: <201106100004.58040.jnareb@gmail.com>
In-Reply-To: <4DF13D00.2060000@alum.mit.edu>

On Thu, 9 Jan 2011, Michael Haggerty wrote:

Show 12 quoted lines

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

Third, "git diff" is not "git diff3 OURS THEIRS WTREE" in general, because for resolved files it is "git diff NEXT WTREE", which is very useful.

I could agree with STAGE being possibly multi-stage thingy, so that "git diff STAGE WTREE" in case of merge conflict is _exactly the same_ as "git diff".

Show 36 quoted lines

> >   4. They're supposed to be simpler to understand than index stages. But
> >      are they? The latest definitions seem to be:
> > 
> >        OURS is a tree of each path in the index, either from stage 2 if
> >        it exists, or from NEXT otherwise.
> > 
> >        NEXT is a tree of each path in the index, either from stage 0 if
> >        it exists, or from HEAD otherwise.
> > 
> >      But that doesn't seem any simpler to me than just saying "the index
> >      has numbered stages, and they correspond to resolved, base, ours,
> >      and theirs".
> 
> There is no need to explain the pseudotrees in terms of the index
> stages; the pseudotrees are easier to understand and should therefore
> become the primary way to describe the index.  Let me give it a try, at
> tutorial level.  Assume that the concepts HEAD and WTREE have already
> been introduced:
> 
>   The "index" is a special area that can hold one or more temporary
>   snapshots of your version-controlled content.  Each snapshot is
>   called a "tree" because it is analogous to a filesystem tree such
>   as the working tree [1].
> 
>   Usually the index holds a single tree called "NEXT".  NEXT is a
>   snapshot of the state of the working tree that is ready to be
>   committed.  This usually consists of the contents from the commit
>   that was last checked out (HEAD), plus any changes that have been
>   staged for commit using "git stage".
> 
>   It is possible to use "git diff" to view the difference between any
>   two trees, whether they be trees in the index, trees in commits, or
>   the working tree.  For example, to see the difference between the
>   last commit and the working tree, use
> 
>       git diff HEAD WTREE

[cut very long explanation]
 
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.

Those pseudo-trees might be useful if you know what you want to compare, but are not useful if you know what you want to see (you have to remember what to compare with which). Never mind they are longer to write...

-- 
Jakub Narebski
Poland