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

From: Jeff King <peff@peff.net>
Date: Aug 20, 2007, 06:37 UTC
Message-ID: <20070820063733.GA31201@coredump.intra.peff.net>
In-Reply-To: <20070820060522.GA27913@spearce.org>

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