Re: Command-line interface thoughts

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

I'll be there advocatus diaboli for some things.

Jeff King [off-list ref] writes:

quoted

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.

quoted

  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