{"thread":{"id":"65606","subject":"[PATCH] doc: git-log: document --no-follow","startedAt":"2026-05-07T14:14:44Z","lastAt":"2026-09-28T17:16:42Z","messageCount":18,"participants":["Tamir Duberstein","Junio C Hamano","Marat Khalili"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"542847","messageId":"20260507-document-log-no-follow-v1-1-46ce02490eba@gmail.com","threadId":"65606","inReplyTo":null,"subject":"[PATCH] doc: git-log: document --no-follow","fromName":"Tamir Duberstein","fromEmail":"tamird@gmail.com","sentAt":"2026-05-07T14:14:39Z","receivedAt":"2026-05-07T14:14:44Z","isPatch":true,"body":"The --no-follow option was added by aebbcf5797 (diff: accept --no-follow\noption, 2012-09-21), but git-log(1) only documents the positive --follow\nform.\n\nLater, 076c98372e (log: add \"log.follow\" configuration variable,\n2015-07-07) taught git log to act as if --follow were given when\nlog.follow is true and there is a single path, with --no-follow\noverriding that default. 1e9250b5aa (diff-parseopt: convert\n--[no-]follow, 2019-03-05) preserved the negated form while moving the\noption to parse-options.\n\nDocument --no-follow alongside --follow, and mention the override in the\nlog.follow documentation.\n\nSigned-off-by: Tamir Duberstein \n---\n Documentation/config/log.adoc | 2 +-\n Documentation/git-log.adoc | 5 ++++-\n 2 files changed, 5 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/config/log.adoc b/Documentation/config/log.adoc\nindex f20cc25cd7..58147dff9b 100644\n--- a/Documentation/config/log.adoc\n+++ b/Documentation/config/log.adoc\n@@ -54,7 +54,7 @@ This is the same as the `--decorate` option of the `git log`.\n \tIf `true`, `git log` will act as if the `--follow` option was used when\n \ta single is given. This has the same limitations as `--follow`,\n \ti.e. it cannot be used to follow multiple files and does not work well\n-\ton non-linear history.\n+\ton non-linear history. This can be overridden by `--no-follow`.\n \n `log.graphColors`::\n \tA list of colors, separated by commas, that can be used to draw\ndiff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc\nindex e304739c5e..58a2be60a1 100644\n--- a/Documentation/git-log.adoc\n+++ b/Documentation/git-log.adoc\n@@ -28,8 +28,11 @@ OPTIONS\n -------\n \n `--follow`::\n+`--no-follow`::\n \tContinue listing the history of a file beyond renames\n-\t(works only for a single file).\n+\t(works only for a single file). `--no-follow` disables this\n+\tbehavior, including when it was enabled by the `log.follow`\n+\tconfiguration variable.\n \n `--no-decorate`::\n `--decorate[=(short|full|auto|no)]`::\n\n---\nbase-commit: 94f057755b7941b321fd11fec1b2e3ca5313a4e0\nchange-id: 20260507-document-log-no-follow-72c33dc15017\n\nBest regards,\n-- \nTamir Duberstein \n\n"},{"id":"542864","messageId":"20260507-document-log-no-follow-v2-1-ee7bcbbe612f@gmail.com","threadId":"65606","inReplyTo":"20260507-document-log-no-follow-v1-1-46ce02490eba@gmail.com","subject":"[PATCH v2] doc: git-log: clarify --follow options","fromName":"Tamir Duberstein","fromEmail":"tamird@gmail.com","sentAt":"2026-05-07T18:13:33Z","receivedAt":"2026-05-07T18:13:39Z","isPatch":true,"body":"The --no-follow option was added by aebbcf5797 (diff: accept --no-follow\noption, 2012-09-21), but git-log(1) only documents the positive --follow\nform.\n\nLater, 076c98372e (log: add \"log.follow\" configuration variable,\n2015-07-07) taught git log to act as if --follow were given when\nlog.follow is true and there is a single pathspec, with --no-follow\noverriding that default. 1e9250b5aa (diff-parseopt: convert\n--[no-]follow, 2019-03-05) preserved the negated form while moving the\noption to parse-options.\n\nDocument --no-follow alongside --follow. While here, describe --follow\nas limited to a single pathspec, rather than a single file, and mention\nthe override in the log.follow documentation.\n\nSigned-off-by: Tamir Duberstein \n---\nChanges in v2:\n- Document --follow as limited to a single pathspec, not a single file.\n- Adjust the log.follow documentation to use the same wording.\n- Link to v1: https://patch.msgid.link/20260507-document-log-no-follow-v1-1-46ce02490eba@gmail.com\n---\n Documentation/config/log.adoc | 7 ++++---\n Documentation/git-log.adoc | 7 +++++--\n 2 files changed, 9 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/config/log.adoc b/Documentation/config/log.adoc\nindex f20cc25cd7..1001672dc7 100644\n--- a/Documentation/config/log.adoc\n+++ b/Documentation/config/log.adoc\n@@ -52,9 +52,10 @@ This is the same as the `--decorate` option of the `git log`.\n \n `log.follow`::\n \tIf `true`, `git log` will act as if the `--follow` option was used when\n-\ta single is given. This has the same limitations as `--follow`,\n-\ti.e. it cannot be used to follow multiple files and does not work well\n-\ton non-linear history.\n+\ta single pathspec is given. This has the same limitations as\n+\t`--follow`, i.e. it cannot be used with multiple pathspecs and does not\n+\twork well on non-linear history. This can be overridden by\n+\t`--no-follow`.\n \n `log.graphColors`::\n \tA list of colors, separated by commas, that can be used to draw\ndiff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc\nindex e304739c5e..f73031fb71 100644\n--- a/Documentation/git-log.adoc\n+++ b/Documentation/git-log.adoc\n@@ -28,8 +28,11 @@ OPTIONS\n -------\n \n `--follow`::\n-\tContinue listing the history of a file beyond renames\n-\t(works only for a single file).\n+`--no-follow`::\n+\tContinue listing the history of a path beyond renames. This\n+\toption works only with a single pathspec. `--no-follow` disables\n+\tthis behavior, including when it was enabled by the `log.follow`\n+\tconfiguration variable.\n \n `--no-decorate`::\n `--decorate[=(short|full|auto|no)]`::\n\n---\nbase-commit: 94f057755b7941b321fd11fec1b2e3ca5313a4e0\nchange-id: 20260507-document-log-no-follow-72c33dc15017\n\nBest regards,\n-- \nTamir Duberstein \n\n"},{"id":"542973","messageId":"xmqqecjj9ckc.fsf@gitster.g","threadId":"65606","inReplyTo":"20260507-document-log-no-follow-v2-1-ee7bcbbe612f@gmail.com","subject":"Re: [PATCH v2] doc: git-log: clarify --follow options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-05-10T21:31:15Z","receivedAt":"2026-05-10T21:31:22Z","isPatch":true,"body":"Tamir Duberstein writes:\n\n> Subject: Re: [PATCH v2] doc: git-log: clarify --follow options\n\nThe second ':' feels quite funny. I would have expected\n\n doc: clarify \"--follow\" and log.follow for \"git log\"\n\nor something like that.\n\n> The --no-follow option was added by aebbcf5797 (diff: accept --no-follow\n> option, 2012-09-21), but git-log(1) only documents the positive --follow\n> form.\n\nOK. Usually we document\n\n\t--no-foo::\n\t--foo::\n\t\tdescribe '--foo' and '--no-foo' here ...\n\nbut we do not do so here, which is a good thng to fix.\n\n> Document --no-follow alongside --follow. While here, describe --follow\n> as limited to a single pathspec, rather than a single file, and mention\n> the override in the log.follow documentation.\n\n\"Single file\" is more accurate than \"single pathspec\", isn't it?\n\nIt is not like \"git log --follow builtin\" follows only changes to\nthe paths for builtin commands across \"builtin-foo.c ->\nbuiltin/foo.c\" transition that happened at 81b50f3c (Move\n'builtin-*' into a 'builtin/' subdirectory, 2010-02-22).\n\nAnd the way the machinery for this checkbox feature works is to notice\nwhen the file it was given disappears and then find the other file\nthat the file we have been following came from, and start following\nthat old file. \n"},{"id":"542976","messageId":"CAJ-ks9nb1pebMLqZ+GunkXLSMYRb_RmpDuBDrDsgJ+6m7nbzMg@mail.gmail.com","threadId":"65606","inReplyTo":"xmqqecjj9ckc.fsf@gitster.g","subject":"Re: [PATCH v2] doc: git-log: clarify --follow options","fromName":"Tamir Duberstein","fromEmail":"tamird@gmail.com","sentAt":"2026-05-10T22:30:06Z","receivedAt":"2026-05-10T22:30:44Z","isPatch":true,"body":"On Sun, May 10, 2026 at 5:31 PM Junio C Hamano wrote:\n>\n> Tamir Duberstein writes:\n>\n> > Subject: Re: [PATCH v2] doc: git-log: clarify --follow options\n>\n> The second ':' feels quite funny. I would have expected\n>\n> doc: clarify \"--follow\" and log.follow for \"git log\"\n>\n> or something like that.\n>\n> > The --no-follow option was added by aebbcf5797 (diff: accept --no-follow\n> > option, 2012-09-21), but git-log(1) only documents the positive --follow\n> > form.\n>\n> OK. Usually we document\n>\n> --no-foo::\n> --foo::\n> describe '--foo' and '--no-foo' here ...\n>\n> but we do not do so here, which is a good thng to fix.\n>\n> > Document --no-follow alongside --follow. While here, describe --follow\n> > as limited to a single pathspec, rather than a single file, and mention\n> > the override in the log.follow documentation.\n>\n> \"Single file\" is more accurate than \"single pathspec\", isn't it?\n\nYes, for the rename-following behavior.\n\nThe part that confused me is that `--follow` is not a no-op for a directory\npathspec. `git log --follow -- builtin` gives different output from `git log --\nbuiltin`. But that is not because Git follows `builtin/` across the 81b50f3c\nmove to the old `builtin-*.c` paths.\n\nThe difference comes from the traversal mode. Setting `follow_renames` makes the\nrevision machinery run diffs and skip the usual pathspec pruning, because a\nfollowed path may change. That can change which commits are shown for a\ndirectory pathspec, especially merges. But the actual path rewrite in\n`try_to_follow_renames()` only happens when a rename or copy destination exactly\nmatches the single pathspec, so a directory pathspec is not rewritten to earlier\nfile names.\n\nI will reroll to say that `--follow` follows a single file beyond renames, works\nonly with exactly one pathspec, and that directory pathspecs do not follow\ndirectory renames even though they still use the same traversal mode and can\ntherefore show a different set of commits. I will also fix the subject and\noption ordering as suggested.\n\n> It is not like \"git log --follow builtin\" follows only changes to\n> the paths for builtin commands across \"builtin-foo.c ->\n> builtin/foo.c\" transition that happened at 81b50f3c (Move\n> 'builtin-*' into a 'builtin/' subdirectory, 2010-02-22).\n>\n> And the way the machinery for this checkbox feature works is to notice\n> when the file it was given disappears and then find the other file\n> that the file we have been following came from, and start following\n> that old file.\n"},{"id":"542977","messageId":"20260510-document-log-no-follow-v3-1-d6d3368c64bb@gmail.com","threadId":"65606","inReplyTo":"20260507-document-log-no-follow-v2-1-ee7bcbbe612f@gmail.com","subject":"[PATCH v3] doc: clarify --follow and log.follow for git log","fromName":"Tamir Duberstein","fromEmail":"tamird@gmail.com","sentAt":"2026-05-10T22:31:14Z","receivedAt":"2026-05-10T22:31:19Z","isPatch":true,"body":"The --no-follow option was added by aebbcf5797 (diff: accept --no-follow\noption, 2012-09-21), but git-log(1) only documents the positive --follow\nform.\n\nLater, 076c98372e (log: add \"log.follow\" configuration variable,\n2015-07-07) taught git log to act as if --follow were given when\nlog.follow is true and there is a single pathspec, with --no-follow\noverriding that default. 1e9250b5aa (diff-parseopt: convert\n--[no-]follow, 2019-03-05) preserved the negated form while moving the\noption to parse-options.\n\nDocument --no-follow alongside --follow. While here, make explicit that\n--follow is accepted only with a single pathspec but follows only file\nrenames. A directory pathspec uses the same traversal mode and can show\na different set of commits, but directory renames are not followed.\nMention the override in the log.follow documentation.\n\nSigned-off-by: Tamir Duberstein \n---\nChanges in v3:\n- Retitle the patch to avoid the awkward `doc: git-log:` subject.\n- List `--no-follow` before `--follow`.\n- Clarify that `--follow` follows a single file across renames, even\n though the option is accepted with exactly one pathspec.\n- Document the directory-pathspec case: directory renames are not\n followed, but `--follow` still uses file-follow traversal, disabling\n normal pathspec pruning and possibly changing which commits,\n especially merges, are shown.\n- Link to v2: https://patch.msgid.link/20260507-document-log-no-follow-v2-1-ee7bcbbe612f@gmail.com\n\nChanges in v2:\n- Document --follow as limited to a single pathspec, not a single file.\n- Adjust the log.follow documentation to use the same wording.\n- Link to v1: https://patch.msgid.link/20260507-document-log-no-follow-v1-1-46ce02490eba@gmail.com\n---\n Documentation/config/log.adoc | 9 ++++++---\n Documentation/git-log.adoc | 11 +++++++++--\n 2 files changed, 15 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/config/log.adoc b/Documentation/config/log.adoc\nindex f20cc25cd7..ba9872e98a 100644\n--- a/Documentation/config/log.adoc\n+++ b/Documentation/config/log.adoc\n@@ -52,9 +52,12 @@ This is the same as the `--decorate` option of the `git log`.\n \n `log.follow`::\n \tIf `true`, `git log` will act as if the `--follow` option was used when\n-\ta single is given. This has the same limitations as `--follow`,\n-\ti.e. it cannot be used to follow multiple files and does not work well\n-\ton non-linear history.\n+\ta single pathspec is given. This has the same limitations as\n+\t`--follow`, i.e. it cannot be used with multiple pathspecs and does not\n+\twork well on non-linear history. When the pathspec names a directory,\n+\tGit does not follow directory renames, but it still uses the same\n+\ttraversal mode as for file rename following; see `--follow` in\n+\tlinkgit:git-log[1]. This can be overridden by `--no-follow`.\n \n `log.graphColors`::\n \tA list of colors, separated by commas, that can be used to draw\ndiff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc\nindex e304739c5e..0fb3279d19 100644\n--- a/Documentation/git-log.adoc\n+++ b/Documentation/git-log.adoc\n@@ -27,9 +27,16 @@ each commit introduces are shown.\n OPTIONS\n -------\n \n+`--no-follow`::\n `--follow`::\n-\tContinue listing the history of a file beyond renames\n-\t(works only for a single file).\n+\tContinue listing the history of a single file beyond renames.\n+\tThis option works only when exactly one pathspec is given. If the\n+\tpathspec names a directory, Git does not follow directory renames,\n+\tbut it still uses the same traversal mode as for file rename\n+\tfollowing, which disables the usual pathspec pruning and can change\n+\twhich commits, especially merges, are shown. `--no-follow`\n+\tdisables this behavior, including when it was enabled by the\n+\t`log.follow` configuration variable.\n \n `--no-decorate`::\n `--decorate[=(short|full|auto|no)]`::\n\n---\nbase-commit: 94f057755b7941b321fd11fec1b2e3ca5313a4e0\nchange-id: 20260507-document-log-no-follow-72c33dc15017\n\nBest regards,\n-- \nTamir Duberstein \n\n"},{"id":"542982","messageId":"xmqqqzni967o.fsf@gitster.g","threadId":"65606","inReplyTo":"CAJ-ks9nb1pebMLqZ+GunkXLSMYRb_RmpDuBDrDsgJ+6m7nbzMg@mail.gmail.com","subject":"Re: [PATCH v2] doc: git-log: clarify --follow options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-05-10T23:48:27Z","receivedAt":"2026-05-10T23:48:29Z","isPatch":true,"body":"Tamir Duberstein writes:\n\n> I will reroll to say that `--follow` follows a single file beyond renames, works\n> only with exactly one pathspec, and that directory pathspecs do not follow\n> directory renames even though they still use the same traversal mode and can\n> therefore show a different set of commits. I will also fix the subject and\n> option ordering as suggested.\n\nTo be quite honest, the \"--follow\" option being what it is (i.e., a\ncheckbox option to claim we do support such an operation, without a\nserious design and implementation), I'd rather see our documentation\nbeing more honest and do not claim it works with pathspec at all.\nWhen you use \"--follow\", you have to give a single filename, and\nthat file is followed across commits that renames it from some other\nname, and then that file with the old name is followed.\n\nIf multiple histories are merged and if the file being followed\nturns out to have come from different files on these different\nhistories, the \"old name\" the traversal is currently following is\nnot kept track of per traversal path, so we cannot expect the\nfeature to work with anything but a linear history, either.\n"},{"id":"542984","messageId":"CAJ-ks9nVaq-hMC1MoiiUTxnP6_TZLteL+Ri4x-OKsx4FXkq4hA@mail.gmail.com","threadId":"65606","inReplyTo":"xmqqqzni967o.fsf@gitster.g","subject":"Re: [PATCH v2] doc: git-log: clarify --follow options","fromName":"Tamir Duberstein","fromEmail":"tamird@gmail.com","sentAt":"2026-05-10T23:51:19Z","receivedAt":"2026-05-10T23:51:56Z","isPatch":true,"body":"On Sun, May 10, 2026 at 7:48 PM Junio C Hamano wrote:\n>\n> Tamir Duberstein writes:\n>\n> > I will reroll to say that `--follow` follows a single file beyond renames, works\n> > only with exactly one pathspec, and that directory pathspecs do not follow\n> > directory renames even though they still use the same traversal mode and can\n> > therefore show a different set of commits. I will also fix the subject and\n> > option ordering as suggested.\n>\n> To be quite honest, the \"--follow\" option being what it is (i.e., a\n> checkbox option to claim we do support such an operation, without a\n> serious design and implementation), I'd rather see our documentation\n> being more honest and do not claim it works with pathspec at all.\n> When you use \"--follow\", you have to give a single filename, and\n> that file is followed across commits that renames it from some other\n> name, and then that file with the old name is followed.\n\nI certainly agree that being honest is the right thing to do - but the\nhonest truth is that `--follow` changes the behavior when used with\n*any* pathspec, not just when given a single file. I attempted to\ncapture that nuance in v3.\n\n>\n> If multiple histories are merged and if the file being followed\n> turns out to have come from different files on these different\n> histories, the \"old name\" the traversal is currently following is\n> not kept track of per traversal path, so we cannot expect the\n> feature to work with anything but a linear history, either.\n\nI'm not sure how to reply to this. The ground truth today is that the\noption does have an effect when used with not-just-a-single-file, yet\nthe documentation does not mention this at all.\n"},{"id":"542985","messageId":"xmqqik8u95yn.fsf@gitster.g","threadId":"65606","inReplyTo":"20260510-document-log-no-follow-v3-1-d6d3368c64bb@gmail.com","subject":"Re: [PATCH v3] doc: clarify --follow and log.follow for git log","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-05-10T23:53:52Z","receivedAt":"2026-05-10T23:53:54Z","isPatch":true,"body":"Tamir Duberstein writes:\n\n> `log.follow`::\n> \tIf `true`, `git log` will act as if the `--follow` option was used when\n> +\ta single pathspec is given. This has the same limitations as\n> +\t`--follow`, i.e. it cannot be used with multiple pathspecs and does not\n> +\twork well on non-linear history. When the pathspec names a directory,\n> +\tGit does not follow directory renames, but it still uses the same\n> +\ttraversal mode as for file rename following; see `--follow` in\n> +\tlinkgit:git-log[1]. This can be overridden by `--no-follow`.\n\nSaying that the feature does \"not work well\" on non-lenear history\nis like the behaviour of the feature is \"undefined\" on such a\nhistory. Quite honestly, when you do not give a single filename,\nthe behaviour is \"undefined\", either, so I do not think we want to\nsay what happens when the pathspec you give matches a directory.\nThe feature only takes a single filename on a linear history.\nAnything else the feature does is \"undefined\" random behavour.\n"},{"id":"542986","messageId":"CAJ-ks9mPzCr3obAw5cE071GNjzy_ZLzF4mQdnUbQY5H4WPw3sA@mail.gmail.com","threadId":"65606","inReplyTo":"xmqqik8u95yn.fsf@gitster.g","subject":"Re: [PATCH v3] doc: clarify --follow and log.follow for git log","fromName":"Tamir Duberstein","fromEmail":"tamird@gmail.com","sentAt":"2026-05-11T00:07:43Z","receivedAt":"2026-05-11T00:08:21Z","isPatch":true,"body":"On Sun, May 10, 2026 at 7:53 PM Junio C Hamano wrote:\n>\n> Tamir Duberstein writes:\n>\n> > `log.follow`::\n> > If `true`, `git log` will act as if the `--follow` option was used when\n> > + a single pathspec is given. This has the same limitations as\n> > + `--follow`, i.e. it cannot be used with multiple pathspecs and does not\n> > + work well on non-linear history. When the pathspec names a directory,\n> > + Git does not follow directory renames, but it still uses the same\n> > + traversal mode as for file rename following; see `--follow` in\n> > + linkgit:git-log[1]. This can be overridden by `--no-follow`.\n>\n> Saying that the feature does \"not work well\" on non-lenear history\n> is like the behaviour of the feature is \"undefined\" on such a\n> history. Quite honestly, when you do not give a single filename,\n> the behaviour is \"undefined\", either, so I do not think we want to\n> say what happens when the pathspec you give matches a directory.\n> The feature only takes a single filename on a linear history.\n> Anything else the feature does is \"undefined\" random behavour.\n\nI observed this \"undefined\" behavior, which is why I started working\non this patch. I think it is not reasonable to deal with undefined\nbehavior by pretending it doesn't exist. The documentation should\nacknowledge and explain what happens when this option is used for all\nways that it can be used.\n"},{"id":"542988","messageId":"xmqqv7cux0q7.fsf@gitster.g","threadId":"65606","inReplyTo":"CAJ-ks9mPzCr3obAw5cE071GNjzy_ZLzF4mQdnUbQY5H4WPw3sA@mail.gmail.com","subject":"Re: [PATCH v3] doc: clarify --follow and log.follow for git log","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-05-11T00:13:04Z","receivedAt":"2026-05-11T00:13:07Z","isPatch":true,"body":"Tamir Duberstein writes:\n\n> I observed this \"undefined\" behavior, which is why I started working\n> on this patch. I think it is not reasonable to deal with undefined\n> behavior by pretending it doesn't exist. The documentation should\n> acknowledge and explain what happens when this option is used for all\n> ways that it can be used.\n\nNo, you are misguided.\n\nUndefined behaviour can change without notice, and users should be\nstrongly discouraged from using it. Describing what the current\nimplementation happens to do moves us exactly in the opposite\ndirection.\n\n`--follow` is a checkbox feature. You can use it \"only with a single\nfilename on a linear history\" or all bets are off otherwise.\n\nThat is what we should describe if we want to be honest.\n"},{"id":"542992","messageId":"CAJ-ks9krzLO_+O74omAfeVByUBh=rDGSVSarf5PGwkdWepzubw@mail.gmail.com","threadId":"65606","inReplyTo":"xmqqv7cux0q7.fsf@gitster.g","subject":"Re: [PATCH v3] doc: clarify --follow and log.follow for git log","fromName":"Tamir Duberstein","fromEmail":"tamird@gmail.com","sentAt":"2026-05-11T00:32:29Z","receivedAt":"2026-05-11T00:33:08Z","isPatch":true,"body":"On Sun, May 10, 2026 at 8:13 PM Junio C Hamano wrote:\n>\n> Tamir Duberstein writes:\n>\n> > I observed this \"undefined\" behavior, which is why I started working\n> > on this patch. I think it is not reasonable to deal with undefined\n> > behavior by pretending it doesn't exist. The documentation should\n> > acknowledge and explain what happens when this option is used for all\n> > ways that it can be used.\n>\n> No, you are misguided.\n>\n> Undefined behaviour can change without notice, and users should be\n> strongly discouraged from using it. Describing what the current\n> implementation happens to do moves us exactly in the opposite\n> direction.\n>\n> `--follow` is a checkbox feature. You can use it \"only with a single\n> filename on a linear history\" or all bets are off otherwise.\n>\n> That is what we should describe if we want to be honest.\n\nAt the very least the documentation should state this...?\n"},{"id":"542994","messageId":"xmqqh5oewz6c.fsf@gitster.g","threadId":"65606","inReplyTo":"CAJ-ks9krzLO_+O74omAfeVByUBh=rDGSVSarf5PGwkdWepzubw@mail.gmail.com","subject":"Re: [PATCH v3] doc: clarify --follow and log.follow for git log","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-05-11T00:46:35Z","receivedAt":"2026-05-11T00:46:38Z","isPatch":true,"body":"Tamir Duberstein writes:\n\n>> Undefined behaviour can change without notice, and users should be\n>> strongly discouraged from using it. Describing what the current\n>> implementation happens to do moves us exactly in the opposite\n>> direction.\n>>\n>> `--follow` is a checkbox feature. You can use it \"only with a single\n>> filename on a linear history\" or all bets are off otherwise.\n>>\n>> That is what we should describe if we want to be honest.\n>\n> At the very least the documentation should state this...?\n\nSure.\n\nDoesn't the current text for the option\n\n `--follow`::\n Continue listing the history of a file beyond renames\n (works only for a single file).\n\npretty much cover that, though? The configuration side is a bit\nmore verbose but essentially says the same thing, I think.\n\n `log.follow`::\n If `true`, `git log` will act as if the `--follow` option was used when\n a single is given. This has the same limitations as `--follow`,\n i.e. it cannot be used to follow multiple files and does not work well\n on non-linear history.\n\nWe do not say anything about what the feature happens to do when it\nis given a non-linear history whose branches each rename to the same\nfinal name that you start following from in the more recent part of\nthe history, either, and stop at saying \"does not work well\". We\nshould treat that case the same way as the case where the user gives\na pathspec with multiple pathspec elements or a pathspec that\nmatches with a directory.\n"},{"id":"542996","messageId":"CAJ-ks9n=DcwqyP7K_q0Ki6_3_+o5=558FK1DKr0+VyiM7q69EA@mail.gmail.com","threadId":"65606","inReplyTo":"xmqqh5oewz6c.fsf@gitster.g","subject":"Re: [PATCH v3] doc: clarify --follow and log.follow for git log","fromName":"Tamir Duberstein","fromEmail":"tamird@gmail.com","sentAt":"2026-05-11T01:28:48Z","receivedAt":"2026-05-11T01:29:26Z","isPatch":true,"body":"On Sun, May 10, 2026 at 8:46 PM Junio C Hamano wrote:\n>\n> Tamir Duberstein writes:\n>\n> >> Undefined behaviour can change without notice, and users should be\n> >> strongly discouraged from using it. Describing what the current\n> >> implementation happens to do moves us exactly in the opposite\n> >> direction.\n> >>\n> >> `--follow` is a checkbox feature. You can use it \"only with a single\n> >> filename on a linear history\" or all bets are off otherwise.\n> >>\n> >> That is what we should describe if we want to be honest.\n> >\n> > At the very least the documentation should state this...?\n>\n> Sure.\n>\n> Doesn't the current text for the option\n>\n> `--follow`::\n> Continue listing the history of a file beyond renames\n> (works only for a single file).\n>\n> pretty much cover that, though? The configuration side is a bit\n> more verbose but essentially says the same thing, I think.\n>\n> `log.follow`::\n> If `true`, `git log` will act as if the `--follow` option was used when\n> a single is given. This has the same limitations as `--follow`,\n> i.e. it cannot be used to follow multiple files and does not work well\n> on non-linear history.\n>\n> We do not say anything about what the feature happens to do when it\n> is given a non-linear history whose branches each rename to the same\n> final name that you start following from in the more recent part of\n> the history, either, and stop at saying \"does not work well\". We\n> should treat that case the same way as the case where the user gives\n> a pathspec with multiple pathspec elements or a pathspec that\n> matches with a directory.\n\nSorry, I was unclear. I was saying that the documentation should be\nexplicit about the cases that constitute \"undefined behavior\".\n"},{"id":"542997","messageId":"xmqqwlxavgwv.fsf@gitster.g","threadId":"65606","inReplyTo":"CAJ-ks9n=DcwqyP7K_q0Ki6_3_+o5=558FK1DKr0+VyiM7q69EA@mail.gmail.com","subject":"Re: [PATCH v3] doc: clarify --follow and log.follow for git log","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-05-11T02:06:24Z","receivedAt":"2026-05-11T02:06:27Z","isPatch":true,"body":"Tamir Duberstein writes:\n\n>> Doesn't the current text for the option\n>>\n>> `--follow`::\n>> Continue listing the history of a file beyond renames\n>> (works only for a single file).\n>>\n>> pretty much cover that, though? The configuration side is a bit\n>> more verbose but essentially says the same thing, I think.\n>>\n>> `log.follow`::\n>> If `true`, `git log` will act as if the `--follow` option was used when\n>> a single is given. This has the same limitations as `--follow`,\n>> i.e. it cannot be used to follow multiple files and does not work well\n>> on non-linear history.\n>>\n>> We do not say anything about what the feature happens to do when it\n>> is given a non-linear history whose branches each rename to the same\n>> final name that you start following from in the more recent part of\n>> the history, either, and stop at saying \"does not work well\". We\n>> should treat that case the same way as the case where the user gives\n>> a pathspec with multiple pathspec elements or a pathspec that\n>> matches with a directory.\n>\n> Sorry, I was unclear. I was saying that the documentation should be\n> explicit about the cases that constitute \"undefined behavior\".\n\nAh, I see.\n\nI am not sure. This is not the only case where we have left these\nunspecified things unsaid, is it? I am not sure if it is worth\nsingling out this particular case.\n\nThanks.\n"},{"id":"546420","messageId":"20260625-document-log-no-follow-v4-1-9bb233248b8f@gmail.com","threadId":"65606","inReplyTo":"20260510-document-log-no-follow-v3-1-d6d3368c64bb@gmail.com","subject":"[PATCH v4] doc: clarify --follow and log.follow for git log","fromName":"Tamir Duberstein","fromEmail":"tamird@gmail.com","sentAt":"2026-06-25T16:01:18Z","receivedAt":"2026-06-25T16:01:32Z","isPatch":true,"body":"aebbcf5797 (diff: accept --no-follow option, 2012-09-21) added the\n--no-follow option, but git-log(1) only documents --follow.\n\nDocument --no-follow alongside --follow, and note that it overrides\nthe log.follow configuration.\n\nSigned-off-by: Tamir Duberstein \n---\nChanges in v4:\n- Limit the patch to `--no-follow` and its `log.follow` override; leave\n the existing `--follow` limitations unchanged.\n- Link to v3: https://patch.msgid.link/20260510-document-log-no-follow-v3-1-d6d3368c64bb@gmail.com\n\nThis conflicts textually with `mv/log-follow-mergy` in `next`. Keep that\ntopic's shorter limitation text and append the `--no-follow` override.\n\nChanges in v3:\n- Retitle the patch to avoid the awkward `doc: git-log:` subject.\n- List `--no-follow` before `--follow`.\n- Clarify that `--follow` follows a single file across renames, even\n though the option is accepted with exactly one pathspec.\n- Document the directory-pathspec case: directory renames are not\n followed, but `--follow` still uses file-follow traversal, disabling\n normal pathspec pruning and possibly changing which commits,\n especially merges, are shown.\n- Link to v2: https://patch.msgid.link/20260507-document-log-no-follow-v2-1-ee7bcbbe612f@gmail.com\n\nChanges in v2:\n- Document --follow as limited to a single pathspec, not a single file.\n- Adjust the log.follow documentation to use the same wording.\n- Link to v1: https://patch.msgid.link/20260507-document-log-no-follow-v1-1-46ce02490eba@gmail.com\n---\n Documentation/config/log.adoc | 2 +-\n Documentation/git-log.adoc | 5 ++++-\n 2 files changed, 5 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/config/log.adoc b/Documentation/config/log.adoc\nindex f20cc25cd7..58147dff9b 100644\n--- a/Documentation/config/log.adoc\n+++ b/Documentation/config/log.adoc\n@@ -54,7 +54,7 @@ This is the same as the `--decorate` option of the `git log`.\n \tIf `true`, `git log` will act as if the `--follow` option was used when\n \ta single is given. This has the same limitations as `--follow`,\n \ti.e. it cannot be used to follow multiple files and does not work well\n-\ton non-linear history.\n+\ton non-linear history. This can be overridden by `--no-follow`.\n \n `log.graphColors`::\n \tA list of colors, separated by commas, that can be used to draw\ndiff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc\nindex fb3ac11283..64fbec0f57 100644\n--- a/Documentation/git-log.adoc\n+++ b/Documentation/git-log.adoc\n@@ -27,9 +27,12 @@ each commit introduces are shown.\n OPTIONS\n -------\n \n+`--no-follow`::\n `--follow`::\n \tContinue listing the history of a file beyond renames\n-\t(works only for a single file).\n+\t(works only for a single file). `--no-follow` disables this\n+\tbehavior, including when it was enabled by the\n+\t`log.follow` configuration variable.\n \n `--no-decorate`::\n `--decorate[=(short|full|auto|no)]`::\n\n---\nbase-commit: ab776a62a78576513ee121424adb19597fbb7613\nchange-id: 20260507-document-log-no-follow-72c33dc15017\n\nBest regards,\n-- \nTamir Duberstein \n\n"},{"id":"546424","messageId":"xmqqpl1efs9j.fsf@gitster.g","threadId":"65606","inReplyTo":"20260625-document-log-no-follow-v4-1-9bb233248b8f@gmail.com","subject":"Re: [PATCH v4] doc: clarify --follow and log.follow for git log","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-25T17:23:52Z","receivedAt":"2026-06-25T17:23:55Z","isPatch":true,"body":"Tamir Duberstein writes:\n\n> aebbcf5797 (diff: accept --no-follow option, 2012-09-21) added the\n> --no-follow option, but git-log(1) only documents --follow.\n>\n> Document --no-follow alongside --follow, and note that it overrides\n> the log.follow configuration.\n>\n> Signed-off-by: Tamir Duberstein \n> ---\n> Changes in v4:\n> - Limit the patch to `--no-follow` and its `log.follow` override; leave\n> the existing `--follow` limitations unchanged.\n> - Link to v3: https://patch.msgid.link/20260510-document-log-no-follow-v3-1-d6d3368c64bb@gmail.com\n\nOK.\n\n> Changes in v3:\n> - List `--no-follow` before `--follow`.\n\nAh, I think I misread the patch and its preimage while reviewing v2\nand I didn't notice my mistake when you sent v3. Sorry.\n\nI somehow thought that the original before the patch was\n\n --follow::\n\t... description of follow here ...\n --no-follow::\n\t... description of no-follow here ..\n\nand I thought the patch was doing\n\n --follow::\n --no-follow::\n\t... combined description ...\n\nand commented that it was a good change. I didn't mean to comment\nwhich between --no-foo and --foo should come first (looking at the\noutput of \"git grep -C1 -E -e '^`?--no-'\", I think --foo should come\nbefore --no-foo, especially when --foo does not take any value, but\nit seems there are many instances that list the negated form first).\n\nAs the existing text has mixture of --foo before and after --no-foo\nlet's not worry about which one should come first, but if we have a\nchance to redo this patch, I would actually prefer to see --follow\ncomes before --no-follow.\n\n> diff --git a/Documentation/config/log.adoc b/Documentation/config/log.adoc\n> index f20cc25cd7..58147dff9b 100644\n> --- a/Documentation/config/log.adoc\n> +++ b/Documentation/config/log.adoc\n> @@ -54,7 +54,7 @@ This is the same as the `--decorate` option of the `git log`.\n> \tIf `true`, `git log` will act as if the `--follow` option was used when\n> \ta single is given. This has the same limitations as `--follow`,\n> \ti.e. it cannot be used to follow multiple files and does not work well\n> -\ton non-linear history.\n> +\ton non-linear history. This can be overridden by `--no-follow`.\n\nOK. This is the usual \"command line options override configured\ndefault\" in play.\n\n> diff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc\n> index fb3ac11283..64fbec0f57 100644\n> --- a/Documentation/git-log.adoc\n> +++ b/Documentation/git-log.adoc\n> @@ -27,9 +27,12 @@ each commit introduces are shown.\n> OPTIONS\n> -------\n> \n> +`--no-follow`::\n> `--follow`::\n> \tContinue listing the history of a file beyond renames\n> -\t(works only for a single file).\n> +\t(works only for a single file). `--no-follow` disables this\n> +\tbehavior, including when it was enabled by the\n> +\t`log.follow` configuration variable.\n\nDitto, but I am not sure if we want to sprinkle the \"command line\noverrides configured defaults\" all over the place. The description\nof --[no-]decorate below says\n\n\tdefault to configuration value of `log.decorate` if\n\tconfigured, otherwise `auto`.\n\nwhich silently assumes that the readers _know_ that command line\n--no-decorate overrides that default. And I think it is a sensible\nassumption to make.\n\nSo, while the patch may have meant well, I think this part should\nactually become a single liner that adds `--no-follow`:: and nothing\nelse. The changes to config/log.adoc should probably be kept.\n\nThanks.\n"},{"id":"553347","messageId":"20260926-document-log-no-follow-v5-1-d04efeca7551@gmail.com","threadId":"65606","inReplyTo":"20260625-document-log-no-follow-v4-1-9bb233248b8f@gmail.com","subject":"[PATCH v5] doc: clarify --follow's single-file limitation","fromName":"Tamir Duberstein","fromEmail":"tamird@gmail.com","sentAt":"2026-09-26T11:56:21Z","receivedAt":"2026-09-26T11:56:38Z","isPatch":true,"body":"Saying that --follow works only for a single file leaves open whether\nother inputs are rejected or ignored. In particular, log.follow enables\nfollowing for a directory argument, although that use is unsupported.\n\nDistinguish errors for an explicit --follow with no paths or multiple\npaths from the configured default, which has no effect in those cases.\nState that results for directory arguments and accepted wildcard\npatterns are unspecified, and document --no-follow to disable the mode.\n\nAssisted-by: LLM\nSigned-off-by: Tamir Duberstein \n---\nChanges in v5:\n- Distinguish explicit --follow errors from cases where log.follow\n leaves the command unchanged.\n- State that results for directory arguments and accepted wildcard\n patterns are unspecified, and explain how to disable following.\n- List --follow before --no-follow.\n- Rebase onto current master, which includes mv/log-follow-mergy.\n- Link to v4: https://patch.msgid.link/20260625-document-log-no-follow-v4-1-9bb233248b8f@gmail.com\n\nChanges in v4:\n- Limit the patch to `--no-follow` and its `log.follow` override; leave\n the existing `--follow` limitations unchanged.\n- Link to v3: https://patch.msgid.link/20260510-document-log-no-follow-v3-1-d6d3368c64bb@gmail.com\n\nChanges in v3:\n- Retitle the patch to avoid the awkward `doc: git-log:` subject.\n- List `--no-follow` before `--follow`.\n- Clarify that `--follow` follows a single file across renames, even\n though the option is accepted with exactly one pathspec.\n- Document the directory-pathspec case: directory renames are not\n followed, but `--follow` still uses file-follow traversal, disabling\n normal pathspec pruning and possibly changing which commits,\n especially merges, are shown.\n- Link to v2: https://patch.msgid.link/20260507-document-log-no-follow-v2-1-ee7bcbbe612f@gmail.com\n\nChanges in v2:\n- Document --follow as limited to a single pathspec, not a single file.\n- Adjust the log.follow documentation to use the same wording.\n- Link to v1: https://patch.msgid.link/20260507-document-log-no-follow-v1-1-46ce02490eba@gmail.com\n---\nRange-diff versus v4:\n\n1: ee9e9a1817 < -: ---------- doc: clarify --follow and log.follow for git log\n-: ---------- > 1: 993a2ed91c doc: clarify --follow's single-file limitation\n---\n Documentation/config/log.adoc | 10 +++++++---\n Documentation/git-log.adoc | 10 ++++++++--\n 2 files changed, 15 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/config/log.adoc b/Documentation/config/log.adoc\nindex f7dfce69b5..4efdd4f61b 100644\n--- a/Documentation/config/log.adoc\n+++ b/Documentation/config/log.adoc\n@@ -51,9 +51,13 @@ This is the same as the `--decorate` option of the `git log`.\n \tdetails. Defaults to `separate`.\n \n `log.follow`::\n-\tIf `true`, `git log` will act as if the `--follow` option was used when\n-\ta single is given. This has the same limitations as `--follow`,\n-\ti.e. it cannot be used to follow multiple files.\n+\tIf `true`, `git log` enables `--follow` when a single is\n+\tgiven. With no paths, multiple paths, or pathspec magic unsupported\n+\tby `--follow`, this setting has no effect.\n++\n+A single directory argument or an accepted wildcard pattern still\n+enables `--follow`, with unspecified results. Use `--no-follow` to\n+override this setting.\n \n `log.graphColors`::\n \tA list of colors, separated by commas, that can be used to draw\ndiff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc\nindex fb3ac11283..a40b3d1c05 100644\n--- a/Documentation/git-log.adoc\n+++ b/Documentation/git-log.adoc\n@@ -28,8 +28,14 @@ OPTIONS\n -------\n \n `--follow`::\n-\tContinue listing the history of a file beyond renames\n-\t(works only for a single file).\n+`--no-follow`::\n+\tContinue listing the history of a single file beyond renames.\n+\tAn explicit `--follow` requires exactly one path argument; Git\n+\treports an error if none or more than one is given.\n++\n+A directory argument is accepted and enables `--follow`, but results\n+for directories and accepted wildcard patterns are unspecified.\n+Use `--no-follow` for directory history or wildcard matching.\n \n `--no-decorate`::\n `--decorate[=(short|full|auto|no)]`::\n\n---\nbase-commit: 0f8e75abebff0877cae681a3d5ff31ac47f54220\nchange-id: 20260507-document-log-no-follow-72c33dc15017\n\n"},{"id":"553506","messageId":"a745126c-7e40-47e9-afa4-7ebea0640bf6@gmail.com","threadId":"65606","inReplyTo":"20260926-document-log-no-follow-v5-1-d04efeca7551@gmail.com","subject":"Re: [PATCH v5] doc: clarify --follow's single-file limitation","fromName":"Marat Khalili","fromEmail":"qm2k21@gmail.com","sentAt":"2026-09-28T17:16:38Z","receivedAt":"2026-09-28T17:16:42Z","isPatch":true,"body":"On 26/09/2026 12:56, Tamir Duberstein wrote:\n> Saying that --follow works only for a single file leaves open whether\n> other inputs are rejected or ignored. In particular, log.follow enables\n> following for a directory argument, although that use is unsupported.\n>\n> Distinguish errors for an explicit --follow with no paths or multiple\n> paths from the configured default, which has no effect in those cases.\n> State that results for directory arguments and accepted wildcard\n> patterns are unspecified, and document --no-follow to disable the mode.\nnit: \"document --no-follow disabling the mode\"?\n>\n> Assisted-by: LLM\n> Signed-off-by: Tamir Duberstein \n\nLGTM FWIW (looking at this part of the code right now considering \npossible improvements). Handing of --follow has a few more other \nlimitations that can be documented, but fixing them is probably more \ninteresting. Disclaimer: I just joined and did not follow this thread \nfrom the beginning.\n\nAcked-by: Marat Khalili \n\n// snip\n\n> ---\n> Documentation/config/log.adoc | 10 +++++++---\n> Documentation/git-log.adoc | 10 ++++++++--\n> 2 files changed, 15 insertions(+), 5 deletions(-)\n>\n> diff --git a/Documentation/config/log.adoc b/Documentation/config/log.adoc\n> index f7dfce69b5..4efdd4f61b 100644\n> --- a/Documentation/config/log.adoc\n> +++ b/Documentation/config/log.adoc\n> @@ -51,9 +51,13 @@ This is the same as the `--decorate` option of the `git log`.\n> \tdetails. Defaults to `separate`.\n> \n> `log.follow`::\n> -\tIf `true`, `git log` will act as if the `--follow` option was used when\n> -\ta single is given. This has the same limitations as `--follow`,\n> -\ti.e. it cannot be used to follow multiple files.\n> +\tIf `true`, `git log` enables `--follow` when a single is\n> +\tgiven. With no paths, multiple paths, or pathspec magic unsupported\n> +\tby `--follow`, this setting has no effect.\n> ++\n> +A single directory argument or an accepted wildcard pattern still\n> +enables `--follow`, with unspecified results. Use `--no-follow` to\n> +override this setting.\n> \n> `log.graphColors`::\n> \tA list of colors, separated by commas, that can be used to draw\n> diff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc\n> index fb3ac11283..a40b3d1c05 100644\n> --- a/Documentation/git-log.adoc\n> +++ b/Documentation/git-log.adoc\n> @@ -28,8 +28,14 @@ OPTIONS\n> -------\n> \n> `--follow`::\n> -\tContinue listing the history of a file beyond renames\n> -\t(works only for a single file).\n> +`--no-follow`::\n> +\tContinue listing the history of a single file beyond renames.\n> +\tAn explicit `--follow` requires exactly one path argument; Git\n> +\treports an error if none or more than one is given.\n> ++\n> +A directory argument is accepted and enables `--follow`, but results\n> +for directories and accepted wildcard patterns are unspecified.\n> +Use `--no-follow` for directory history or wildcard matching.\n> \n> `--no-decorate`::\n> `--decorate[=(short|full|auto|no)]`::\n>\n> ---\n> base-commit: 0f8e75abebff0877cae681a3d5ff31ac47f54220\n> change-id: 20260507-document-log-no-follow-72c33dc15017\n"}]}