# [PATCH] doc: git-log: document --no-follow 18 messages from 2026-05-07 to 2026-09-28. Participants: Tamir Duberstein, Junio C Hamano, Marat Khalili. Thread: https://gitlist.dev/t/65606 ## Tamir Duberstein, 2026-05-07 14:14 Subject: [PATCH] doc: git-log: document --no-follow Message-ID: <20260507-document-log-no-follow-v1-1-46ce02490eba@gmail.com> ``` 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 --- 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 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 ``` ## Tamir Duberstein, 2026-05-07 18:13 Subject: [PATCH v2] doc: git-log: clarify --follow options Message-ID: <20260507-document-log-no-follow-v2-1-ee7bcbbe612f@gmail.com> In-Reply-To: <20260507-document-log-no-follow-v1-1-46ce02490eba@gmail.com> ``` 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 --- 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 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 ``` ## Junio C Hamano, 2026-05-10 21:31 Subject: Re: [PATCH v2] doc: git-log: clarify --follow options Message-ID: In-Reply-To: <20260507-document-log-no-follow-v2-1-ee7bcbbe612f@gmail.com> ``` Tamir Duberstein 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. ``` ## Tamir Duberstein, 2026-05-10 22:30 Subject: Re: [PATCH v2] doc: git-log: clarify --follow options Message-ID: In-Reply-To: ``` On Sun, May 10, 2026 at 5:31 PM Junio C Hamano wrote: > > Tamir Duberstein 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. ``` ## Tamir Duberstein, 2026-05-10 22:31 Subject: [PATCH v3] doc: clarify --follow and log.follow for git log Message-ID: <20260510-document-log-no-follow-v3-1-d6d3368c64bb@gmail.com> In-Reply-To: <20260507-document-log-no-follow-v2-1-ee7bcbbe612f@gmail.com> ``` 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 --- 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 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 ``` ## Junio C Hamano, 2026-05-10 23:48 Subject: Re: [PATCH v2] doc: git-log: clarify --follow options Message-ID: In-Reply-To: ``` Tamir Duberstein 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. ``` ## Tamir Duberstein, 2026-05-10 23:51 Subject: Re: [PATCH v2] doc: git-log: clarify --follow options Message-ID: In-Reply-To: ``` On Sun, May 10, 2026 at 7:48 PM Junio C Hamano wrote: > > Tamir Duberstein 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. ``` ## Junio C Hamano, 2026-05-10 23:53 Subject: Re: [PATCH v3] doc: clarify --follow and log.follow for git log Message-ID: In-Reply-To: <20260510-document-log-no-follow-v3-1-d6d3368c64bb@gmail.com> ``` Tamir Duberstein 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. ``` ## Tamir Duberstein, 2026-05-11 00:07 Subject: Re: [PATCH v3] doc: clarify --follow and log.follow for git log Message-ID: In-Reply-To: ``` On Sun, May 10, 2026 at 7:53 PM Junio C Hamano wrote: > > Tamir Duberstein 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. ``` ## Junio C Hamano, 2026-05-11 00:13 Subject: Re: [PATCH v3] doc: clarify --follow and log.follow for git log Message-ID: In-Reply-To: ``` Tamir Duberstein 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. ``` ## Tamir Duberstein, 2026-05-11 00:32 Subject: Re: [PATCH v3] doc: clarify --follow and log.follow for git log Message-ID: In-Reply-To: ``` On Sun, May 10, 2026 at 8:13 PM Junio C Hamano wrote: > > Tamir Duberstein 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...? ``` ## Junio C Hamano, 2026-05-11 00:46 Subject: Re: [PATCH v3] doc: clarify --follow and log.follow for git log Message-ID: In-Reply-To: ``` Tamir Duberstein 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 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. ``` ## Tamir Duberstein, 2026-05-11 01:28 Subject: Re: [PATCH v3] doc: clarify --follow and log.follow for git log Message-ID: In-Reply-To: ``` On Sun, May 10, 2026 at 8:46 PM Junio C Hamano wrote: > > Tamir Duberstein 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 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". ``` ## Junio C Hamano, 2026-05-11 02:06 Subject: Re: [PATCH v3] doc: clarify --follow and log.follow for git log Message-ID: In-Reply-To: ``` Tamir Duberstein 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 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. ``` ## Tamir Duberstein, 2026-06-25 16:01 Subject: [PATCH v4] doc: clarify --follow and log.follow for git log Message-ID: <20260625-document-log-no-follow-v4-1-9bb233248b8f@gmail.com> In-Reply-To: <20260510-document-log-no-follow-v3-1-d6d3368c64bb@gmail.com> ``` 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 --- 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(-) 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 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 fb3ac11283..64fbec0f57 100644 --- a/Documentation/git-log.adoc +++ b/Documentation/git-log.adoc @@ -27,9 +27,12 @@ each commit introduces are shown. OPTIONS ------- +`--no-follow`:: `--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: ab776a62a78576513ee121424adb19597fbb7613 change-id: 20260507-document-log-no-follow-72c33dc15017 Best regards, -- Tamir Duberstein ``` ## Junio C Hamano, 2026-06-25 17:23 Subject: Re: [PATCH v4] doc: clarify --follow and log.follow for git log Message-ID: In-Reply-To: <20260625-document-log-no-follow-v4-1-9bb233248b8f@gmail.com> ``` Tamir Duberstein writes: > 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 > --- > 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 OK. > Changes in v3: > - List `--no-follow` before `--follow`. 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. > 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 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`. OK. This is the usual "command line options override configured default" in play. > diff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc > index fb3ac11283..64fbec0f57 100644 > --- a/Documentation/git-log.adoc > +++ b/Documentation/git-log.adoc > @@ -27,9 +27,12 @@ each commit introduces are shown. > OPTIONS > ------- > > +`--no-follow`:: > `--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. 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. ``` ## Tamir Duberstein, 2026-09-26 11:56 Subject: [PATCH v5] doc: clarify --follow's single-file limitation Message-ID: <20260926-document-log-no-follow-v5-1-d04efeca7551@gmail.com> In-Reply-To: <20260625-document-log-no-follow-v4-1-9bb233248b8f@gmail.com> ``` 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 --- 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(-) diff --git a/Documentation/config/log.adoc b/Documentation/config/log.adoc index f7dfce69b5..4efdd4f61b 100644 --- a/Documentation/config/log.adoc +++ b/Documentation/config/log.adoc @@ -51,9 +51,13 @@ This is the same as the `--decorate` option of the `git log`. details. Defaults to `separate`. `log.follow`:: - If `true`, `git log` will act as if the `--follow` option was used when - a single is given. This has the same limitations as `--follow`, - i.e. it cannot be used to follow multiple files. + If `true`, `git log` enables `--follow` when a single is + given. With no paths, multiple paths, or pathspec magic unsupported + by `--follow`, this setting has no effect. ++ +A single directory argument or an accepted wildcard pattern still +enables `--follow`, with unspecified results. Use `--no-follow` to +override this setting. `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 fb3ac11283..a40b3d1c05 100644 --- a/Documentation/git-log.adoc +++ b/Documentation/git-log.adoc @@ -28,8 +28,14 @@ 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 single file beyond renames. + An explicit `--follow` requires exactly one path argument; Git + reports an error if none or more than one is given. ++ +A directory argument is accepted and enables `--follow`, but results +for directories and accepted wildcard patterns are unspecified. +Use `--no-follow` for directory history or wildcard matching. `--no-decorate`:: `--decorate[=(short|full|auto|no)]`:: --- base-commit: 0f8e75abebff0877cae681a3d5ff31ac47f54220 change-id: 20260507-document-log-no-follow-72c33dc15017 ``` ## Marat Khalili, 2026-09-28 17:16 Subject: Re: [PATCH v5] doc: clarify --follow's single-file limitation Message-ID: In-Reply-To: <20260926-document-log-no-follow-v5-1-d04efeca7551@gmail.com> ``` On 26/09/2026 12:56, Tamir Duberstein wrote: > 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. nit: "document --no-follow disabling the mode"? > > Assisted-by: LLM > Signed-off-by: Tamir Duberstein 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 // snip > --- > Documentation/config/log.adoc | 10 +++++++--- > Documentation/git-log.adoc | 10 ++++++++-- > 2 files changed, 15 insertions(+), 5 deletions(-) > > diff --git a/Documentation/config/log.adoc b/Documentation/config/log.adoc > index f7dfce69b5..4efdd4f61b 100644 > --- a/Documentation/config/log.adoc > +++ b/Documentation/config/log.adoc > @@ -51,9 +51,13 @@ This is the same as the `--decorate` option of the `git log`. > details. Defaults to `separate`. > > `log.follow`:: > - If `true`, `git log` will act as if the `--follow` option was used when > - a single is given. This has the same limitations as `--follow`, > - i.e. it cannot be used to follow multiple files. > + If `true`, `git log` enables `--follow` when a single is > + given. With no paths, multiple paths, or pathspec magic unsupported > + by `--follow`, this setting has no effect. > ++ > +A single directory argument or an accepted wildcard pattern still > +enables `--follow`, with unspecified results. Use `--no-follow` to > +override this setting. > > `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 fb3ac11283..a40b3d1c05 100644 > --- a/Documentation/git-log.adoc > +++ b/Documentation/git-log.adoc > @@ -28,8 +28,14 @@ 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 single file beyond renames. > + An explicit `--follow` requires exactly one path argument; Git > + reports an error if none or more than one is given. > ++ > +A directory argument is accepted and enables `--follow`, but results > +for directories and accepted wildcard patterns are unspecified. > +Use `--no-follow` for directory history or wildcard matching. > > `--no-decorate`:: > `--decorate[=(short|full|auto|no)]`:: > > --- > base-commit: 0f8e75abebff0877cae681a3d5ff31ac47f54220 > change-id: 20260507-document-log-no-follow-72c33dc15017 ```