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

[Jan Hudec <bulb@ucw.cz>]

[-- Attachment #1: Type: text/plain, Size: 1732 bytes --]

On Sun, Aug 19, 2007 at 23:20:53 -0700, Junio C Hamano wrote:
> Steven Grimm <koreth@midwinter.com> writes:
> 
> > Junio C Hamano wrote:
> >> 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 <bulb@ucw.cz>

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]