[PATCH] doc: git-log: document --no-follow

[PATCH] doc: git-log: document --no-follow

[Tamir Duberstein]

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(-)

diff --git a/Documentation/config/log.adoc b/Documentation/config/log.adoc
index f20cc25cd7..58147dff9b 100644
--- a/Documentation/config/log.adoc
+++ b/Documentation/config/log.adoc
@@ -54,7 +54,7 @@ This is the same as the `--decorate` option of the `git log`.
 	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.
+	on non-linear history.  This can be overridden by `--no-follow`.
 
 `log.graphColors`::
 	A list of colors, separated by commas, that can be used to draw
diff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc
index e304739c5e..58a2be60a1 100644
--- a/Documentation/git-log.adoc
+++ b/Documentation/git-log.adoc
@@ -28,8 +28,11 @@ OPTIONS
 -------
 
 `--follow`::
+`--no-follow`::
 	Continue listing the history of a file beyond renames
-	(works only for a single file).
+	(works only for a single file).  `--no-follow` disables this
+	behavior, including when it was enabled by the `log.follow`
+	configuration variable.
 
 `--no-decorate`::
 `--decorate[=(short|full|auto|no)]`::

---
base-commit: 94f057755b7941b321fd11fec1b2e3ca5313a4e0
change-id: 20260507-document-log-no-follow-72c33dc15017

Best regards,
--  
Tamir Duberstein <tamird@gmail.com>

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

[Tamir Duberstein]

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(-)

diff --git a/Documentation/config/log.adoc b/Documentation/config/log.adoc
index f20cc25cd7..1001672dc7 100644
--- a/Documentation/config/log.adoc
+++ b/Documentation/config/log.adoc
@@ -52,9 +52,10 @@ This is the same as the `--decorate` option of the `git log`.
 
 `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.
+	a single pathspec is given.  This has the same limitations as
+	`--follow`, i.e. it cannot be used with multiple pathspecs and does not
+	work well on non-linear history.  This can be overridden by
+	`--no-follow`.
 
 `log.graphColors`::
 	A list of colors, separated by commas, that can be used to draw
diff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc
index e304739c5e..f73031fb71 100644
--- a/Documentation/git-log.adoc
+++ b/Documentation/git-log.adoc
@@ -28,8 +28,11 @@ OPTIONS
 -------
 
 `--follow`::
-	Continue listing the history of a file beyond renames
-	(works only for a single file).
+`--no-follow`::
+	Continue listing the history of a path beyond renames.  This
+	option works only with a single pathspec.  `--no-follow` disables
+	this behavior, including when it was enabled by the `log.follow`
+	configuration variable.
 
 `--no-decorate`::
 `--decorate[=(short|full|auto|no)]`::

---
base-commit: 94f057755b7941b321fd11fec1b2e3ca5313a4e0
change-id: 20260507-document-log-no-follow-72c33dc15017

Best regards,
--  
Tamir Duberstein <tamird@gmail.com>

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

[Junio C Hamano]

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?

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.  

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

[Tamir Duberstein]

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

> 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.

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

[Tamir Duberstein]

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(-)

diff --git a/Documentation/config/log.adoc b/Documentation/config/log.adoc
index f20cc25cd7..ba9872e98a 100644
--- a/Documentation/config/log.adoc
+++ b/Documentation/config/log.adoc
@@ -52,9 +52,12 @@ This is the same as the `--decorate` option of the `git log`.
 
 `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.
+	a single pathspec is given.  This has the same limitations as
+	`--follow`, i.e. it cannot be used with multiple pathspecs and does not
+	work well on non-linear history.  When the pathspec names a directory,
+	Git does not follow directory renames, but it still uses the same
+	traversal mode as for file rename following; see `--follow` in
+	linkgit:git-log[1].  This can be overridden by `--no-follow`.
 
 `log.graphColors`::
 	A list of colors, separated by commas, that can be used to draw
diff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc
index e304739c5e..0fb3279d19 100644
--- a/Documentation/git-log.adoc
+++ b/Documentation/git-log.adoc
@@ -27,9 +27,16 @@ each commit introduces are shown.
 OPTIONS
 -------
 
+`--no-follow`::
 `--follow`::
-	Continue listing the history of a file beyond renames
-	(works only for a single file).
+	Continue listing the history of a single file beyond renames.
+	This option works only when exactly one pathspec is given.  If the
+	pathspec names a directory, Git does not follow directory renames,
+	but it still uses the same traversal mode as for file rename
+	following, which disables the usual pathspec pruning and can change
+	which commits, especially merges, are shown.  `--no-follow`
+	disables this behavior, including when it was enabled by the
+	`log.follow` configuration variable.
 
 `--no-decorate`::
 `--decorate[=(short|full|auto|no)]`::

---
base-commit: 94f057755b7941b321fd11fec1b2e3ca5313a4e0
change-id: 20260507-document-log-no-follow-72c33dc15017

Best regards,
--  
Tamir Duberstein <tamird@gmail.com>

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

[Junio C Hamano]

Tamir Duberstein <tamird@gmail.com> writes:

> 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.

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.

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

[Tamir Duberstein]

On Sun, May 10, 2026 at 7:48 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Tamir Duberstein <tamird@gmail.com> writes:
>
> > 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.
>
> 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.

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.

>
> 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.

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.

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

[Junio C Hamano]

Tamir Duberstein <tamird@gmail.com> writes:

>  `log.follow`::
>  	If `true`, `git log` will act as if the `--follow` option was used when
> +	a single pathspec is given.  This has the same limitations as
> +	`--follow`, i.e. it cannot be used with multiple pathspecs and does not
> +	work well on non-linear history.  When the pathspec names a directory,
> +	Git does not follow directory renames, but it still uses the same
> +	traversal mode as for file rename following; see `--follow` in
> +	linkgit:git-log[1].  This can be overridden by `--no-follow`.

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.

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

[Tamir Duberstein]

On Sun, May 10, 2026 at 7:53 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Tamir Duberstein <tamird@gmail.com> writes:
>
> >  `log.follow`::
> >       If `true`, `git log` will act as if the `--follow` option was used when
> > +     a single pathspec is given.  This has the same limitations as
> > +     `--follow`, i.e. it cannot be used with multiple pathspecs and does not
> > +     work well on non-linear history.  When the pathspec names a directory,
> > +     Git does not follow directory renames, but it still uses the same
> > +     traversal mode as for file rename following; see `--follow` in
> > +     linkgit:git-log[1].  This can be overridden by `--no-follow`.
>
> 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.

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.

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

[Junio C Hamano]

Tamir Duberstein <tamird@gmail.com> writes:

> 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.

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.

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

[Tamir Duberstein]

On Sun, May 10, 2026 at 8:13 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Tamir Duberstein <tamird@gmail.com> writes:
>
> > 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.
>
> 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.

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

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

[Junio C Hamano]

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.

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

[Tamir Duberstein]

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".

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

[Junio C Hamano]

Tamir Duberstein <tamird@gmail.com> writes:

>> 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".

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.