From: Tamir Duberstein <tamird@gmail.com>
Date: Mon, 11 May 2026 01:28:48 GMT
Subject: Re: [PATCH v3] doc: clarify --follow and log.follow for git log
Message-ID: <CAJ-ks9n=DcwqyP7K_q0Ki6_3_+o5=558FK1DKr0+VyiM7q69EA@mail.gmail.com>
In-Reply-To: <xmqqh5oewz6c.fsf@gitster.g>

On Sun, May 10, 2026 at 8:46 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> 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.

Sorry, I was unclear. I was saying that the documentation should be
explicit about the cases that constitute "undefined behavior".