Re: Command-line interface thoughts

[Michael Nahas <mike.nahas@gmail.com>]

Thanks for all the interest!

Before getting into the contentious topics:

Is there general agreement on my item #4 that "git branch <name>"
should be replaced by "git checkout -b <name>" in the tutorial?

Concerning the semi-formal notation for describing commands, do people
thing it is useful?  Is this better covered at revctrl.org?


Okay, back to NEXT/WTREE:

I think Junio is right: The best way to think about NEXT and WTREE are
_not_ as commits.  They are "snapshots of the project".  A commit
object is a snaphot + parent commit SHAs + author + message + other
things.  Think of NEXT and WTREE as equivalent to the tree object
pointed to by a commit object.

[Perhaps "next commit" is a bad name for a snapshot]

These concepts of NEXT and WTREE are use by visual tools.  My favorite
Git documentation, Visual Git Reference, uses them.  Even "git stash
save" stores the "state of the index" and "state of the working tree"
in two commits.

My initial desire for NEXT/WTREE was to make "git diff" usage easier
for me to remember.  It ends up that this is _exactly_ the same usage
that inspired the previous emails that Jakub referenced.  I understand
that NEXT and WTREE may not have as many uses elsewhere, but I think
they have a lot of value for "git diff".

I don't think users will have trouble realizing that NEXT and WTREE
are _not_ commits.  They're writable.  Commits are not.  I do think
that NEXT has some value that users will realize that "git add
foo.txt" adds a particular version of foo.txt to the index and that
further edits to foo.txt will not make it into the next commit, unless
"git add foo.txt" is run again.

In reference as to how to report "git show NEXT", I would suggest that
the usual case would be to treat NEXT like a tree object.  I'm new to
Git and I know enough to know that I don't know all the states of the
index nor even all the commands that use it.  I will read up on the
format of the index and try to come up with some answers for the more
complex situations, but I'm also okay with saying the alias NEXT
doesn't work while in a merge conflict (where "git write-tree" would
return an error.)  Perhaps other alias do work then?
MERGE_HEAD/FETCH_HEAD come and go, right?

Mike


On Mon, Jun 6, 2011 at 3:34 AM, Michael J Gruber
<git@drmicha.warpmail.net> 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!
>
> As for WTREE: git diff against work tree does not look at non-tracked
> ignored files, so why should WTREE?
>
> 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).
>
> 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.
>
> Michael
>