Subject: Re: Command-line interface thoughts

From: Jakub Narebski <[email-masked]>
Date: Sat, 11 Jun 2011 01:05:07 +0200

On Fri, 10 Jun 2011, Junio C Hamano wrote:

I'll be there advocatus diaboli for some things.

> Jeff King <[email-masked]> writes:
> 
> > I think there are actually two questions here:
> >
> >   1. Will it be easier for people to understand "git diff" if we use
> >      tokens to describe non-treeish sources and destinations?
> >
> >   2. Are there better tokens to use to break down parts of the index?
> >
> > I don't have a big problem with (1). Allowing things like:
> >
> >   git diff INDEX WTREE
> >
> > allows one to explain what is going on with the diff syntax in a very
> > clear and verbose manner. I wouldn't want to type that every day, but
> > that's OK; "git diff" will always mean the same thing as it always has,
> > but can now be explained to people who have trouble seeing it in terms
> > of "git diff INDEX WTREE".
> >
> > There's still a bit of magic in that INDEX is _not_ a tree, but I think
> > that's a good thing. When there are no merge conflicts, it will behave
> > identically to the proposed NEXT tree. And when there are conflicts, it
> > will show you something even more useful.
> 
> Thanks. This is exactly why I love to have people like you on the list,
> who can say what I wanted to say in a manner that is a lot easier to
> understand.
> 
> In short, the proposed "NEXT" does not help in a situation with conflicts,
> and makes the user experience worse.

Which proposed NEXT?  I'm asking because there were many proposals from
many people, some contradictory.

One proposal was, if I understand it correctly, to have NEXT actually be
STAGE, i.e. be multi-tree like current index is in the case of merge
conflicts.  This means that NEXT = \Sum stage_0 + (stage_ours + stage_theirs
+ stage_base). 

> In order to get the current power of 
> "git diff" with various options that are specifically designed to help
> users to make progress (either working on their own changes, rebasing them
> on top of others, or merging other's work in), people _COULD_ introduce
> BASE/OURS/THEIRS in addition to "NEXT", throw the existing HEAD and
> MERGE_HEAD to the mix, derive the same information by spending mental
> effort to choose between which pairs of two entities among these six
> possibilities and take pairwise diffs among those pairs,

And find which direction makes more sense "diff A B" or "diff B A".
"git diff" / "git diff --staged" / "git diff HEAD" use direction that
makes most sense.

> and combine the 
> results of these diffs (the message I responded to with "is that a useful
> question" was an example of that---"Could we pile more kludge on top of
> NEXT to have expressiveness equivalent to what the current index-based
> system offers?"). Yes, that may be possible, but is there a point in
> making users go through that kind of mental contortion by introducing
> these new tokens? I find it highly doubtful that it would help new people
> understand the situation during conflicted merges.
> 
> >   git show INDEX:OURS:Makefile
> >
> > which is identical to what I wrote above, but is perhaps easier to
> > explain.
> 
> Why does anybody even want to say :2:Makefile to begin with?
> 
> Presumably, you are dealing with a merge conflict at that path and trying
> to see how pre-merge version of Makefile looked like, and then the next
> thing you may want to do is how pre-merge version of their Makefile looked
> like.
> 
> Wouldn't it be far more natural to ask for these instead?
> 
>     git show HEAD:Makefile
>     git show MERGE_HEAD:Makefile
> 
> I do not think whoever brought that "you can look at individual stages
> with :$n:$path" to this discussion was thinking straight. Yes, it is
> something you _could_ do, I've never found that particularly _useful_
> unless I was debugging git itself.

Actually there are cases when you don't have MERGE_HEAD, namely:

 * "git merge --squash"
 * "git rebase" and "git rebase --interactive", and "git cherry-pick"
 * "git am --3way"

Note that OURS/THEIRS/BASE/WTREE has more power: currently there is no way
as far as I know to compare stages 2 and 3 directly ("git diff :2: :3:"
didn't work, though this might be fiexed in newer git), or stage and base.

Though I am not sure if anybody would want this.
-- 
Jakub Narebski
Poland