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

[Tamir Duberstein <tamird@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>