Re: [PATCH] Document what the stage numbers in the :$n:path syntax mean.

[Jeff King <peff@peff.net>]

On Mon, Aug 20, 2007 at 02:05:22AM -0400, Shawn O. Pearce wrote:

> Oh, like say git-rebase.  During a rebase "theirs" (stage 3) is
> your file and "ours" (stage 2) is the upstream.  Confusing now,
> ain't it?  Mine is theirs and ours is theirs?  Huh?  Yeeaaaah.

Ugh, I hadn't even thought of that. git-diff _does_ respect "--base",
"--ours", and "--theirs" to mean the same thing, but I am now wondering
if that is a bit of a mistake.

However, as the intent of my patch was to _increase_ usability, I think
a gotcha like that is probably counterproductive. OTOH, users of
git-rebase already have to make the switch mentally.

> confusing the stages and getting them inverted.  And this is exactly
> why git-merge.sh/git-rebase.sh/git-am.sh try to setup GITHEAD_* for

Yes, I agree that the GITHEAD markers are much more sensible.
Unfortunately, I'm not sure of the best way to translate them into
stage names. The MERGE_HEAD/HEAD suggestion you made is a nice way of
avoiding the whole issue, though it doesn't easily provide the "base"
version.

> At least document the new syntax in git-rev-parse documentation?

I was about to, but your message has convinced me that this is perhaps
not a very good idea.

-Peff