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

From: Felipe Contreras <felipe.contreras@gmail.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: "J. Bruce Fields" <bfields@fieldses.org>,
	Nanako Shiraishi <nanako3@lavabit.com>,
	Michael J Gruber <git@drmicha.warpmail.net>,
	Jonathan Nieder <jrnieder@gmail.com>,
	git@vger.kernel.org, Hannu Koivisto <azure@iki.fi>,
	Jeff King <peff@peff.net>, Wincent Colaiuta <win@wincent.com>,
	Matthias Lederhofer <matled@gmx.net>
Subject: Re: [PATCH v2 0/2] user-manual: new "getting started" section
Date: Wed, 18 Nov 2009 00:00:46 +0200	[thread overview]
Message-ID: <94a0d4530911171400ub3b093ai668fd2404b12272f@mail.gmail.com> (raw)
In-Reply-To: <7vocn1dn5d.fsf@alter.siamese.dyndns.org>

On Tue, Nov 17, 2009 at 8:25 PM, Junio C Hamano <gitster@pobox.com> wrote:
> But we do not have to support commit-ish operations, such as "git log".

Right, and actuallly don't have to support WORKTREE/STAGE on all the
commands that work with the stage. For example I think 'git apply'
behaves completely different than 'git diff', since you cannot apply a
patch on top of a commit, therefore it doesn't make sense to stage
stuff as pseudo-refs; it makes sense to keep the --foo options
(although I would prefer something like --stage and --stage-only).

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

That could be easily fixed by making explicit in the syntax that these
are not typical refs: i.e. @stage and @work.

-- 
Felipe Contreras