Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Junio C Hamano <gitster@pobox.com>]

"J. Bruce Fields" <bfields@fieldses.org> writes:

> On Tue, Nov 17, 2009 at 09:06:25PM +0900, Nanako Shiraishi wrote:
>> David's proposal introduced two magic tokens STAGE and WORKTREE.
>> 
>>   git diff STAGE WORKTREE   (like "git diff" today)
>>   git diff HEAD WORKTREE    (like "git diff HEAD" today)
>>   git diff WORKTREE HEAD    (like "git diff -R HEAD" today)
>>   git diff HEAD STAGE       (like "git diff --cached" today)
>>   git diff commit STAGE     (like "git diff --cached commit" today)
>> 
>> This looks nice on surface, but I think the apparent niceness 
>> is shallow. If of course has a small problem of introducing an 
>> obvious backward incompatibility. You can't use a branch whose 
>> name is STAGE anymore, but a deeper problem is that these two 
>> magic tokens pretend to be refs. But they do so only to the diff 
>> command. I don't see how you can make them sanely be usable to 
>> other commands like "git log v1.0.0..WORKTREE".
>
> Doesn't appear that refs have to point to commits; e.g., on the linux
> project:
>
> 	git log v2.6.11-tree..v2.6.32-rc7
> 	error: Object 5dc01c595e6c6ec9ccda4f6f69c131c0dd945f8c is a tree, not a
> 	commit
> 	fatal: Invalid revision range v2.6.11-tree..v2.6.32-rc7

True.  A ref can even point to a blob.

I think "diff" always takes two (pseudo-)tree-ish in David's world, and
you should be able to use these magic topens anywhere that expects a
tree-ish.  For example:

    $ git checkout STAGE Makefile

would be a way to say "please check out the version of Makefile in the
staging area".  And

    $ git archive WORKTREE
    $ git archive STAGE

would be a version of tar that is index-aware.

But we do not have to support commit-ish operations, such as "git log".

It is a different story if these pseudo-refs that denote tree-ish are
useful outside the context of "diff".  I do not think of many commands
that take arbitrary tree-ish other than the ones I mentioned above.  Even
though they take arbitrary tree-ish, people almost always use commit-ish
with them.

Which points to another issue with the approach.

The original intention of these magic tokens are to make things easier,
but they actually may make things _harder_ to teach, because you have to
explain why "git log WORKTREE" does not work but "git archive WORKTREE"
does.  Admittedly, you already have to explain your example to people
saying "it does not work because v2.6.11 is a tree and a tree by itself
does not have a point in history", but the thing is, v2.6.11-tree and
v2.6.11 are oddballs, and you do not have to give that explanation very
often, simply because the users are not exposed to a raw tree.

But WORKTREE and STAGE tokens are _meant_ to be exposed to them much more
prominently.  That's the whole point of the "git diff STAGE WORKTREE"
proposal.

People would become aware that they are very different from ordinary
commits, and then eventually they will realize that they are not even
trees [*1*].  

At that point, I suspect that these magic tokens become larger UI warts
themselves; they behave differently from everything else that is spelled
in all caps (e.g. HEAD, ORIG_HEAD, MERGE_HEAD).

As to --tree-vs-index counterproposal (was it a counterproposal?), except
for that I think they are too long to type in practice and need to be
shortened to be useful, I do not have a fundamental objection against it.


[Footnote]

*1* For example, I would not expect that we will make "git show WORKTREE"
to build a tree on the fly by running "git add -A && git write-tree" with
a temporary index and then running "git show" on the resulting tree
object, because there would be a better response than that if a user asks
"please show my worktree".