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

Steven Grimm [off-list ref] writes:

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.