Re: Command-line interface thoughts

From: Michael J Gruber <git@drmicha.warpmail.net>
Date: Jun 6, 2011, 13:20 UTC
Message-ID: <4DECD406.2010009@drmicha.warpmail.net>
In-Reply-To: <201106061419.34599.jnareb@gmail.com>

Jakub Narebski venit, vidit, dixit 06.06.2011 14:19:

Show 60 quoted lines

> On Mon, 6 June 2011, Michael J Gruber wrote:
>> Junio C Hamano venit, vidit, dixit 06.06.2011 08:16:
>>> Scott Chacon <schacon@gmail.com> writes:
>>>
>>>> For example, implementation details aside, I think having something
>>>> like WTREE and NEXT available would help users understand that there
>>>> are these 3 trees that are important and useful in Git and re-inforce
>>>> a very non-SVN style workflow in that manner.
>>>
>>> That's a funny thing to say. Working tree may almost always (to put it
>>> another way, "you could make it to") act like a tree, but the index does
>>> not act like a tree at all in more important situations.
>>>
>>> For example, how would you design the user experience of "git show NEXT"?
>>> Try to write a transcript (i.e. "The user starts from this state, runs
>>> these commands, and then says 'git show NEXT'. The user will see this."),
>>> covering various corner cases exhaustively, including what would happen
>>> before the first commit, and during a conflicted "pull" or "rebase -i".
>>>
>>> It's not just the matter of "internally pretend to run write-tree with
>>> 'not committed yet' as a fake commit log message and show it as if it is
>>> an existing commit.
>>>
>>> I wouldn't demand "implement 'git show NEXT'" here, nor "implement it
>>> efficiently" here; just designing the user experience is a good first step
>>> to realize that the index does not act like a tree, and I do not think you
>>> should spread such a misconception to the end users.
>>
>> That is why the other Michael suggested "NEXT" as opposed to "INDEX":
>> The index has many aspects, only one of which is "the contents of the
>> next commit if I would issue 'git commit' right now". (I would even go
>> so far as using "STAGE".) Now, it's hard to argue that "the result of a
>> commit" is not tree-like, isn't it? And there's no question what "git
>> show NEXT" would do. Yes, if you repeat that command, you get a
>> different sha1 each time (because of the time field).
>>
>> I don't think anyone is seriously suggesting to replace the index by a
>> pseudo commit; but the one aspect which people use most could be well
>> represented like that, and this might even help emphasizing the
>> different aspects of the index. Give the index an identity as an
>> "object" (no, no new type, not in the object db, but as a ui object),
>> not something mysterious behind the scenes!
> 
> So what you suggest would make
> 
>   $ git diff NEXT WTREE
> 
> behave differently from
> 
>   $ git diff
> 
> and
> 
>   $ git diff HEAD NEXT
> 
> behave differently from
> 
>   $ git diff --cached
> 
> Do you really think that it is good idea?

I don't know where you're getting from that someone is suggesting to make them different. (And even if, it's new UI, not changed.) Everyone's been suggesting to make these more accessible.

>> As for WTREE: git diff against work tree does not look at non-tracked
>> ignored files, so why should WTREE?
> 
> So we tailor WTREE do diff behavior?

There is no WTREE and nothing to tailer. We create it so that it is most useful and consistent, whatever that may be.

...

> Besides, isn't this exercise a bit academic?  New to git wouldn't use
> index, and would use 'git commit -a' and 'git diff'... and that would
> be enough... well, perhaps except 'git add' + 'git diff'...

But we want them to grasp and use the git concepts! That is why some of us want to make them more accessible.

Show 10 quoted lines

>> Full disclosure: I love the index but hate the way we make it difficult
>> to use sometimes, and even have to lookup myself what command and option
>> to actually use if all I want to do is diff A against B, or take the
>> version of a file from A and write it to B, when A and B are a commit,
>> the index or the worktree (with a commit being the nonwritable, of course).
> 
> Note that in case of saving to worktree you can always use
> 
>   $ git show HEAD:./foo  >foo
>   $ git show :0:./foo    >foo     # or just :./foo

Exactly, yet another command to add to the list below, and it's not even all git (because of the shell redirection).

Show 5 quoted lines

>> I mean, this is really crazy: We have 4 commands ("add", "rm
>> [--cached]", "checkout [<commit>] --", "reset [<commit>] --") which you
>> need to be aware of if all you want to do is moving file contents
>> (content at a path) between a commit, the index and the worktree! And
>> this is actually worse than having 6 for the 6 cases.

Add to this craziness the fact that "checkout -- <path>" reads from index and writes to worktree, but "checkout <commit> -- path" does not read from commit and write to worktree - it reads from commit and writes to index+worktree.

Note that I'm not suggesting to change any of the beloved reset/checkout/whatever variants.

But the more I look at the commit - index - worktree triangle and the commands we have the more I realize how messed up the ui is, simply because it is determined by the underlying mechanics (e.g.: checkout writes the index to the worktree, possibly after updating the index from a commit) rather than by the concepts.

And the bad thing is that even when you look at a single command like reset or checkout, you can get confused easily because of the multiple different functions they overload (e.g. checkout can change HEAD, the index and/or the worktree), and also because of some different defaults (HEAD vs. index). I think we lost consistency here because over time "useful defaults" grew in the wild.

That is why I'm suggesting concept based variants (move this content from A to B, show me the difference between A and B).

Michael