[PATCH v3] doc: clarify --follow and log.follow for git log
- From
Tamir Duberstein <tamird@gmail.com>
- Date
- May 10, 2026, 22:31 UTC
- 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 <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>