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

On Sun, Aug 19, 2007 at 23:20:53 -0700, Junio C Hamano wrote:

Steven Grimm [off-list ref] writes:

quoted

Junio C Hamano wrote:

quoted

People should learn this command.  Really.

      $ git cat-file -p :$n:path

where $n == 2 is ours, $n == 1 is common ancestor, and $n == 3
is theirs.

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.

The patch makes sense.  Thanks.

Just to give historical background to new readers, this is
primarily because the really core level of the plumbing started
as not caring between stages 2 and 3 (iow, as far as the merge
is concerned, both heads are equal), and the description in the
manual was written back then.

These days, all the merge strategies and other non-merge
programs such as "git am" that can record conflicts as
multi-stage index entries consistently use stage #2 as our
version, and stages #2 and #3 are not equals anymore.

Pardon me? In what are they not equal?

In merge, the parents *are* equall. They are just recorded in the resulting
commit in particular order and the stages are in that order.

Besides if I prepare a merge locally to push out to a shared repo, I will
probably switch to the mainline and merge my branch in, so it will actually
be my changes in stage #3. That is to say 'ours' and 'theirs' don't really
express what is going on IMHO.

-- 
						 Jan 'Bulb' Hudec [off-list ref]