From: Felipe Contreras Date: Tue, 17 Nov 2009 22:00:46 GMT Subject: Re: [PATCH v2 0/2] user-manual: new "getting started" section 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 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