Re: [PATCH 2/2] Document the --histogram diff option

[Thomas Rast <trast@inf.ethz.ch>]

Junio C Hamano <gitster@pobox.com> writes:

> Thomas Rast <trast@student.ethz.ch> writes:
>
>> Signed-off-by: Thomas Rast <trast@student.ethz.ch>
>> ---
>>
>> This is only the minimal update.  I think in the long run, we should
>> add a note saying why we support all of them.  But off hand I didn't
>> have any substantial evidence in favour of patience that could be used
>> as an argument.
>
> Isn't the main argument made by proponents of patience diff is more
> readable output, and not performance?  That line of argument relies
> on a fairly subjective test "which one is easier to read?", so it is
> hard to come up with a substantial evidence, unless somebody invests
> in A/B test.

Well, I was just too lazy to look up what I dimly remembered people had
posted at some point: examples where patience beats Myers for
readability.  E.g.,

  http://article.gmane.org/gmane.comp.version-control.git/104316

I don't think you need a blind test to justify that the patience result
is more readable.  So I think in the long run, the docs should say
something like:

--diff-algorithm={histogram|myers|minimal|patience}::
       Choose a diff algorithm.  The variants are as follows:
+
--
histogram::
        This is the fastest algorithm, and thus the default.

myers::
        The classical Myers diff algorithm.  <state a reason why myers
        would be useful>

minimal::
        Like 'myers', but spend extra time making sure that the diff
        is the shortest possible for the set of changes performed.

patience::
        The patience diff algorithm, which first matches unique lines
        with each other.  This sometimes results in more readable (if
        longer) patches than the other algorithms.
--

Or whatever -- magic is required to have a nested list in asciidoc.
I can't be bothered to twiddle with that right now.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch