[PATCH v5] doc: clarify --follow's single-file limitation

[Tamir Duberstein <tamird@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 <tamird@gmail.com>
---
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 <path> 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 <path> 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