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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Nov 17, 2009, 22:00 UTC
Message-ID: <94a0d4530911171400ub3b093ai668fd2404b12272f@mail.gmail.com>
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).

Show 28 quoted lines

> 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