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

> 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.

> ---
>   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