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

["Shawn O. Pearce" <spearce@spearce.org>]

Jeff King <peff@peff.net> wrote:
> On Mon, Aug 20, 2007 at 11:36:38AM +0800, Steven Grimm wrote:
> 
> > The git-rev-parse manpage talks about the :$n:path notation (buried deep in
> > a list of other syntax) but it just says $n is a "stage number" -- someone
> > who is not familiar with the internals of git's merge implementation is
> > never going to be able to figure out that "1", "2", and "3" mean what Junio
> > said.
> 
> I often forget which number corresponds to which source. I seem to
> recall somebody proposing :ours:$path a while ago, but I couldn't find
> any reference in the archive, so perhaps I just dreamed it.
> 
> Am I the only one who messes this up? If not, patch is below.

Maybe.  ;-)

I've memorized it long long ago.  But my coworkers haven't and always
get it wrong, and look at me funny when I tell them "trust me, your
data is in stage 2 and theirs is in stage 3...  because that's the
convention all of the tools you are using follows".

Keywords in that last part: "convention" and "tools you are using".
Someone could redefine what the stages mean and load content into
them using `update index --index-info`.  You might even be able to
load the stages in odd ways yourself from Porcelain.

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.

This is why I've never liked most merge tools.  They get hung up on
what is theirs and what is mine and then at some point they wind up
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
git-merge-recursive, and why they set it up using branch names and
patch subject lines, because it makes the conflict markers easier
to understand.
 
>  	/* sha1:path --> object name of path in ent sha1
>  	 * :path -> object name of path in index
>  	 * :[0-3]:path -> object name of path in index at stage
> +	 * :base|ours|theirs:path -> same as :[1-3]:path
>  	 */

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

-- 
Shawn.