On 08/22, Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> 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.? Agreed, I don't think this would be very helpful for users. > 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. Hmm, it does describe what happens in the code, which is what this patch implements. Maybe we should rephrase the title here? Or are you suggesting dropping this patch (and the next one) completely, as we don't want to try and handle the case where this kind of garbage is thrown at 'rerere'? I don't think it would make sense to drop this documentation without dropping the patch itself, as it does document how rerere handles this case. Without this bit of documentation (but with the code in this patch), the technical 'rerere' documentation feels incomplete to me.
