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.

Later, 076c98372e (log: add "log.follow" configuration variable, 2015-07-07) taught git log to act as if --follow were given when log.follow is true and there is a single path, with --no-follow overriding that default. 1e9250b5aa (diff-parseopt: convert --[no-]follow, 2019-03-05) preserved the negated form while moving the option to parse-options.

Document --no-follow alongside --follow, and mention the override in the log.follow documentation.

Signed-off-by: Tamir Duberstein <tamird@gmail.com>
---
 Documentation/config/log.adoc | 2 +-
 Documentation/git-log.adoc    | 5 ++++-
 2 files changed, 5 insertions(+), 2 deletions(-)

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.

Later, 076c98372e (log: add "log.follow" configuration variable, 2015-07-07) taught git log to act as if --follow were given when log.follow is true and there is a single pathspec, with --no-follow overriding that default. 1e9250b5aa (diff-parseopt: convert --[no-]follow, 2019-03-05) preserved the negated form while moving the option to parse-options.

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.

Signed-off-by: Tamir Duberstein <tamird@gmail.com>
---
Changes in v2:
- Document --follow as limited to a single pathspec, not a single file.
- Adjust the log.follow documentation to use the same wording.
- Link to v1: https://patch.msgid.link/20260507-document-log-no-follow-v1-1-46ce02490eba@gmail.com
---
 Documentation/config/log.adoc | 7 ++++---
 Documentation/git-log.adoc    | 7 +++++--
 2 files changed, 9 insertions(+), 5 deletions(-)

Tamir Duberstein <tamird@gmail.com> writes:

The second ':' feels quite funny.  I would have expected

    doc: clarify "--follow" and log.follow for "git log"

or something like that.

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.

"Single file" is more accurate than "single pathspec", isn't it?

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.

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

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.

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.

Later, 076c98372e (log: add "log.follow" configuration variable, 2015-07-07) taught git log to act as if --follow were given when log.follow is true and there is a single pathspec, with --no-follow overriding that default. 1e9250b5aa (diff-parseopt: convert --[no-]follow, 2019-03-05) preserved the negated form while moving the option to parse-options.

Document --no-follow alongside --follow. While here, make explicit that --follow is accepted only with a single pathspec but follows only file renames. A directory pathspec uses the same traversal mode and can show a different set of commits, but directory renames are not followed. Mention the override in the log.follow documentation.

Signed-off-by: Tamir Duberstein <tamird@gmail.com>
---
Changes in v3:
- Retitle the patch to avoid the awkward `doc: git-log:` subject.
- List `--no-follow` before `--follow`.
- Clarify that `--follow` follows a single file across renames, even
  though the option is accepted with exactly one pathspec.
- Document the directory-pathspec case: directory renames are not
  followed, but `--follow` still uses file-follow traversal, disabling
  normal pathspec pruning and possibly changing which commits,
  especially merges, are shown.
- Link to v2: https://patch.msgid.link/20260507-document-log-no-follow-v2-1-ee7bcbbe612f@gmail.com

Changes in v2:
- Document --follow as limited to a single pathspec, not a single file.
- Adjust the log.follow documentation to use the same wording.
- Link to v1: https://patch.msgid.link/20260507-document-log-no-follow-v1-1-46ce02490eba@gmail.com
---
 Documentation/config/log.adoc |  9 ++++++---
 Documentation/git-log.adoc    | 11 +++++++++--
 2 files changed, 15 insertions(+), 5 deletions(-)

Tamir Duberstein <tamird@gmail.com> writes:

To be quite honest, the "--follow" option being what it is (i.e., a checkbox option to claim we do support such an operation, without a serious design and implementation), I'd rather see our documentation being more honest and do not claim it works with pathspec at all. When you use "--follow", you have to give a single filename, and that file is followed across commits that renames it from some other name, and then that file with the old name is followed.

If multiple histories are merged and if the file being followed turns out to have come from different files on these different histories, the "old name" the traversal is currently following is not kept track of per traversal path, so we cannot expect the feature to work with anything but a linear history, either.

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

I certainly agree that being honest is the right thing to do - but the honest truth is that `--follow` changes the behavior when used with *any* pathspec, not just when given a single file. I attempted to capture that nuance in v3.

I'm not sure how to reply to this. The ground truth today is that the option does have an effect when used with not-just-a-single-file, yet the documentation does not mention this at all.

Tamir Duberstein <tamird@gmail.com> writes:

Saying that the feature does "not work well" on non-lenear history is like the behaviour of the feature is "undefined" on such a history. Quite honestly, when you do not give a single filename, the behaviour is "undefined", either, so I do not think we want to say what happens when the pathspec you give matches a directory. The feature only takes a single filename on a linear history. Anything else the feature does is "undefined" random behavour.

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

I observed this "undefined" behavior, which is why I started working on this patch. I think it is not reasonable to deal with undefined behavior by pretending it doesn't exist. The documentation should acknowledge and explain what happens when this option is used for all ways that it can be used.

Tamir Duberstein <tamird@gmail.com> writes:

No, you are misguided.

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.

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

At the very least the documentation should state this...?

Tamir Duberstein <tamird@gmail.com> writes:

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.

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

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

Tamir Duberstein <tamird@gmail.com> writes:

Ah, I see.

I am not sure. This is not the only case where we have left these unspecified things unsaid, is it? I am not sure if it is worth singling out this particular case.

Thanks.

aebbcf5797 (diff: accept --no-follow option, 2012-09-21) added the --no-follow option, but git-log(1) only documents --follow.

Document --no-follow alongside --follow, and note that it overrides the log.follow configuration.

Signed-off-by: Tamir Duberstein <tamird@gmail.com>
---
Changes in v4:
- Limit the patch to `--no-follow` and its `log.follow` override; leave
  the existing `--follow` limitations unchanged.
- Link to v3: https://patch.msgid.link/20260510-document-log-no-follow-v3-1-d6d3368c64bb@gmail.com

This conflicts textually with `mv/log-follow-mergy` in `next`. Keep that topic's shorter limitation text and append the `--no-follow` override.

Changes in v3:
- Retitle the patch to avoid the awkward `doc: git-log:` subject.
- List `--no-follow` before `--follow`.
- Clarify that `--follow` follows a single file across renames, even
  though the option is accepted with exactly one pathspec.
- Document the directory-pathspec case: directory renames are not
  followed, but `--follow` still uses file-follow traversal, disabling
  normal pathspec pruning and possibly changing which commits,
  especially merges, are shown.
- Link to v2: https://patch.msgid.link/20260507-document-log-no-follow-v2-1-ee7bcbbe612f@gmail.com

Changes in v2:
- Document --follow as limited to a single pathspec, not a single file.
- Adjust the log.follow documentation to use the same wording.
- Link to v1: https://patch.msgid.link/20260507-document-log-no-follow-v1-1-46ce02490eba@gmail.com
---
 Documentation/config/log.adoc | 2 +-
 Documentation/git-log.adoc    | 5 ++++-
 2 files changed, 5 insertions(+), 2 deletions(-)

Tamir Duberstein <tamird@gmail.com> writes:

OK.

Ah, I think I misread the patch and its preimage while reviewing v2 and I didn't notice my mistake when you sent v3. Sorry.

I somehow thought that the original before the patch was

    --follow::
	... description of follow here ...
    --no-follow::
	... description of no-follow here ..

and I thought the patch was doing

    --follow::
    --no-follow::
	... combined description ...

and commented that it was a good change. I didn't mean to comment which between --no-foo and --foo should come first (looking at the output of "git grep -C1 -E -e '^`?--no-'", I think --foo should come before --no-foo, especially when --foo does not take any value, but it seems there are many instances that list the negated form first).

As the existing text has mixture of --foo before and after --no-foo let's not worry about which one should come first, but if we have a chance to redo this patch, I would actually prefer to see --follow comes before --no-follow.

OK. This is the usual "command line options override configured default" in play.

Ditto, but I am not sure if we want to sprinkle the "command line overrides configured defaults" all over the place. The description of --[no-]decorate below says

	default to configuration value of `log.decorate` if
	configured, otherwise `auto`.

which silently assumes that the readers _know_ that command line --no-decorate overrides that default. And I think it is a sensible assumption to make.

So, while the patch may have meant well, I think this part should actually become a single liner that adds `--no-follow`:: and nothing else. The changes to config/log.adoc should probably be kept.

Thanks.

Saying that --follow works only for a single file leaves open whether other inputs are rejected or ignored. In particular, log.follow enables following for a directory argument, although that use is unsupported.

Distinguish errors for an explicit --follow with no paths or multiple paths from the configured default, which has no effect in those cases. State that results for directory arguments and accepted wildcard patterns are unspecified, and document --no-follow to disable the mode.

Assisted-by: LLM
Signed-off-by: Tamir Duberstein <tamird@gmail.com>
---
Changes in v5:
- Distinguish explicit --follow errors from cases where log.follow
  leaves the command unchanged.
- State that results for directory arguments and accepted wildcard
  patterns are unspecified, and explain how to disable following.
- List --follow before --no-follow.
- Rebase onto current master, which includes mv/log-follow-mergy.
- Link to v4: https://patch.msgid.link/20260625-document-log-no-follow-v4-1-9bb233248b8f@gmail.com

Changes in v4:
- Limit the patch to `--no-follow` and its `log.follow` override; leave
  the existing `--follow` limitations unchanged.
- Link to v3: https://patch.msgid.link/20260510-document-log-no-follow-v3-1-d6d3368c64bb@gmail.com

Changes in v3:
- Retitle the patch to avoid the awkward `doc: git-log:` subject.
- List `--no-follow` before `--follow`.
- Clarify that `--follow` follows a single file across renames, even
  though the option is accepted with exactly one pathspec.
- Document the directory-pathspec case: directory renames are not
  followed, but `--follow` still uses file-follow traversal, disabling
  normal pathspec pruning and possibly changing which commits,
  especially merges, are shown.
- Link to v2: https://patch.msgid.link/20260507-document-log-no-follow-v2-1-ee7bcbbe612f@gmail.com

Changes in v2:
- Document --follow as limited to a single pathspec, not a single file.
- Adjust the log.follow documentation to use the same wording.
- Link to v1: https://patch.msgid.link/20260507-document-log-no-follow-v1-1-46ce02490eba@gmail.com
---
Range-diff versus v4:

1:  ee9e9a1817 < -:  ---------- doc: clarify --follow and log.follow for git log
-:  ---------- > 1:  993a2ed91c doc: clarify --follow's single-file limitation
---
 Documentation/config/log.adoc | 10 +++++++---
 Documentation/git-log.adoc    | 10 ++++++++--
 2 files changed, 15 insertions(+), 5 deletions(-)

On 26/09/2026 12:56, Tamir Duberstein wrote:

nit: "document --no-follow disabling the mode"?

LGTM FWIW (looking at this part of the code right now considering possible improvements). Handing of --follow has a few more other limitations that can be documented, but fixing them is probably more interesting. Disclaimer: I just joined and did not follow this thread from the beginning.

Acked-by: Marat Khalili <qm2k21@gmail.com>

// snip