Re: [PATCH v2] doc: git-log: clarify --follow options

From: Tamir Duberstein <tamird@gmail.com>
Date: May 10, 2026, 22:30 UTC
Message-ID: <CAJ-ks9nb1pebMLqZ+GunkXLSMYRb_RmpDuBDrDsgJ+6m7nbzMg@mail.gmail.com>
In-Reply-To: <xmqqecjj9ckc.fsf@gitster.g>

On Sun, May 10, 2026 at 5:31 PM Junio C Hamano <gitster@pobox.com> wrote:

Show 28 quoted lines

>
> Tamir Duberstein <tamird@gmail.com> writes:
>
> > Subject: Re: [PATCH v2] doc: git-log: clarify --follow options
>
> The second ':' feels quite funny.  I would have expected
>
>     doc: clarify "--follow" and log.follow for "git log"
>
> or something like that.
>
> > The --no-follow option was added by aebbcf5797 (diff: accept --no-follow
> > option, 2012-09-21), but git-log(1) only documents the positive --follow
> > form.
>
> OK.  Usually we document
>
>         --no-foo::
>         --foo::
>                 describe '--foo' and '--no-foo' here ...
>
> but we do not do so here, which is a good thng to fix.
>
> > Document --no-follow alongside --follow. While here, describe --follow
> > as limited to a single pathspec, rather than a single file, and mention
> > the override in the log.follow documentation.
>
> "Single file" is more accurate than "single pathspec", isn't it?

Yes, for the rename-following behavior.

The part that confused me is that `--follow` is not a no-op for a directory pathspec. `git log --follow -- builtin` gives different output from `git log -- builtin`. But that is not because Git follows `builtin/` across the 81b50f3c move to the old `builtin-*.c` paths.

The difference comes from the traversal mode. Setting `follow_renames` makes the revision machinery run diffs and skip the usual pathspec pruning, because a followed path may change. That can change which commits are shown for a directory pathspec, especially merges. But the actual path rewrite in `try_to_follow_renames()` only happens when a rename or copy destination exactly matches the single pathspec, so a directory pathspec is not rewritten to earlier file names.

I will reroll to say that `--follow` follows a single file beyond renames, works only with exactly one pathspec, and that directory pathspecs do not follow directory renames even though they still use the same traversal mode and can therefore show a different set of commits. I will also fix the subject and option ordering as suggested.

Show 9 quoted lines

> It is not like "git log --follow builtin" follows only changes to
> the paths for builtin commands across "builtin-foo.c ->
> builtin/foo.c" transition that happened at 81b50f3c (Move
> 'builtin-*' into a 'builtin/' subdirectory, 2010-02-22).
>
> And the way the machinery for this checkbox feature works is to notice
> when the file it was given disappears and then find the other file
> that the file we have been following came from, and start following
> that old file.