Re: [PATCH v4 10/11] rerere: teach rerere to handle nested conflicts

[Junio C Hamano <gitster@pobox.com>]

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> But why not add this to the git-rerere manpage? These technical docs
> get way less exposure, and in this case we're not describing some
> interna implementation detail, which the technical docs are for, but
> something that's user-visible, let's put that in  the user-visiblee
> docs.

I actually consider that the documentation describes low-level
internal implementation detail, which the end users do not care nor
need to know in order to make use of "rerere".  How would it help
the end-users to know that the common ancestor portion of diff3
style conflict does not participate in conflict identification,
sides of conflicts sometimes get swapped for easier indexing of
conflicts, or conflict shapes are hashed via SHA-1 to determine
which subdirectory of $GIT_DIR/rr-cache/ to use to store it, etc.?

By the way, I just noticed that what the last section (i.e. nested
conflicts) says is completely bogus.  Nested conflicts are handled
by lengthening markers for conflict in inner-merge and paying
attention only to the outermost merge.  The only case where the
conflict markers can appear in the way depicted in the section is
when the contents from branches being merged had these conflict
marker looking strings from the beginning---that's "doctor it hurts
when I do this---don't do it then" situation.  The section may
describe correctly what the code happens to do when it gets thrown
such a garbage at, but I do not think it is a useful piece of
information about a designed behaviour.