Re: [PATCH v3] doc: clarify --follow and log.follow for git log

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

Tamir Duberstein <tamird@gmail.com> writes:

>> Undefined behaviour can change without notice, and users should be
>> strongly discouraged from using it.  Describing what the current
>> implementation happens to do moves us exactly in the opposite
>> direction.
>>
>> `--follow` is a checkbox feature. You can use it "only with a single
>> filename on a linear history" or all bets are off otherwise.
>>
>> That is what we should describe if we want to be honest.
>
> At the very least the documentation should state this...?

Sure.

Doesn't the current text for the option

        `--follow`::
                Continue listing the history of a file beyond renames
                (works only for a single file).

pretty much cover that, though?  The configuration side is a bit
more verbose but essentially says the same thing, I think.

        `log.follow`::
                If `true`, `git log` will act as if the `--follow` option was used when
                a single <path> is given.  This has the same limitations as `--follow`,
                i.e. it cannot be used to follow multiple files and does not work well
                on non-linear history.

We do not say anything about what the feature happens to do when it
is given a non-linear history whose branches each rename to the same
final name that you start following from in the more recent part of
the history, either, and stop at saying "does not work well".  We
should treat that case the same way as the case where the user gives
a pathspec with multiple pathspec elements or a pathspec that
matches with a directory.