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

["J. Bruce Fields" <bfields@fieldses.org>]

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


You might be able to add some extra syntax to prevent conflicts with
branch names.  Uh, :STAGE, :WORKTREE ??  But I think that conflicts with
something else.  And the "magic tokens" get a little uglier and harder
to remember.  Bah.

--b.