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

From: Thomas Rast <[email-masked]>
Date: Tue, 6 Mar 2012 21:42:50 +0100

Junio C Hamano <[email-masked]> writes:

> Thomas Rast <[email-masked]> writes:
>
>> Signed-off-by: Thomas Rast <[email-masked]>
>> ---
>>
>> 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