Re: [PATCH] Documentation/diff-options: explain different diff algorithms

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 24, 2018, 20:06 UTC
Message-ID: <xmqq4lgoxusr.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <CAGZ79kap9TovN2ia4pEgz33dh=9y89cVYZWnB_1e6iHpR=kDOQ@mail.gmail.com>

Stefan Beller <sbeller@google.com> writes:

Show 31 quoted lines

> On Mon, Jul 23, 2018 at 9:41 PM Jonathan Nieder <jrnieder@gmail.com> wrote:
>>
>> Hi,
>>
>> Stefan Beller wrote:
>>
>> > As a user I wondered what the diff algorithms are about. Offer at least
>> > a basic explanation on the differences of the diff algorithms.
>>
>> Interesting.  Let's see.
>>
>> [...]
>> > --- a/Documentation/diff-options.txt
>> > +++ b/Documentation/diff-options.txt
>> > @@ -94,16 +94,34 @@ diff" algorithm internally.
>> >       Choose a diff algorithm. The variants are as follows:
>> >  +
>> >  --
>> > -`default`, `myers`;;
>> > -     The basic greedy diff algorithm. Currently, this is the default.
>> >  `minimal`;;
>> > +     A diff as produced by the basic greedy algorithm described in
>>
>> Why this reordering?
>
> because Myers (below) is constructed from minimal + heuristic.
> ...
> So the "minimal" algorithm is the basic myers algorithm,
> and the "myers" algorithm is the extended version (extended
> with a heuristic to be fast in corner cases, still producing good
> enough diffs).

I am not sure that is a good reason for the target readers of this document to move the default from the beginning to somewhere in the middle. For a textbook that explains different algorithms and gives overview of how they work, that order may be appropriate, though.

Show 8 quoted lines

>> > -     Spend extra time to make sure the smallest possible diff is
>> > -     produced.
>> > +`default`, `myers`;;
>> > +     The same algorithm as `minimal`, extended with a heuristic to
>> > +     reduce extensive searches. Currently, this is the default.
>>
>> Amusing --- this means that the Myers diff is spelled as "minimal"
>> instead of "myers".

Yeah, I had the same thought---for an end-user documentation update, this change and the reordering does not feel like an improvement.

>> I wonder if these details (about all the algorithms) should go in a
>> separate Diff Algorithms section and this section could focus on
>> what use cases warrant using each, referring to that section for
>> details.  What do you think?

Good suggestion.