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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 17, 2009, 18:25 UTC
Message-ID: <7vocn1dn5d.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20091117172815.GH31767@fieldses.org>

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

Show 24 quoted lines

> 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".