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

[Junio C Hamano <gitster@pobox.com>]

Tamir Duberstein <tamird@gmail.com> writes:

> aebbcf5797 (diff: accept --no-follow option, 2012-09-21) added the
> --no-follow option, but git-log(1) only documents --follow.
>
> Document --no-follow alongside --follow, and note that it overrides
> the log.follow configuration.
>
> Signed-off-by: Tamir Duberstein <tamird@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

OK.

> Changes in v3:
> - List `--no-follow` before `--follow`.

Ah, I think I misread the patch and its preimage while reviewing v2
and I didn't notice my mistake when you sent v3.  Sorry.

I somehow thought that the original before the patch was

    --follow::
	... description of follow here ...
    --no-follow::
	... description of no-follow here ..

and I thought the patch was doing

    --follow::
    --no-follow::
	... combined description ...

and commented that it was a good change.  I didn't mean to comment
which between --no-foo and --foo should come first (looking at the
output of "git grep -C1 -E -e '^`?--no-'", I think --foo should come
before --no-foo, especially when --foo does not take any value, but
it seems there are many instances that list the negated form first).

As the existing text has mixture of --foo before and after --no-foo
let's not worry about which one should come first, but if we have a
chance to redo this patch, I would actually prefer to see --follow
comes before --no-follow.

> diff --git a/Documentation/config/log.adoc b/Documentation/config/log.adoc
> index f20cc25cd7..58147dff9b 100644
> --- a/Documentation/config/log.adoc
> +++ b/Documentation/config/log.adoc
> @@ -54,7 +54,7 @@ This is the same as the `--decorate` option of the `git log`.
>  	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.
> +	on non-linear history.  This can be overridden by `--no-follow`.

OK.  This is the usual "command line options override configured
default" in play.

> diff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc
> index fb3ac11283..64fbec0f57 100644
> --- a/Documentation/git-log.adoc
> +++ b/Documentation/git-log.adoc
> @@ -27,9 +27,12 @@ each commit introduces are shown.
>  OPTIONS
>  -------
>  
> +`--no-follow`::
>  `--follow`::
>  	Continue listing the history of a file beyond renames
> -	(works only for a single file).
> +	(works only for a single file).  `--no-follow` disables this
> +	behavior, including when it was enabled by the
> +	`log.follow` configuration variable.

Ditto, but I am not sure if we want to sprinkle the "command line
overrides configured defaults" all over the place.  The description
of --[no-]decorate below says

	default to configuration value of `log.decorate` if
	configured, otherwise `auto`.

which silently assumes that the readers _know_ that command line
--no-decorate overrides that default.  And I think it is a sensible
assumption to make.

So, while the patch may have meant well, I think this part should
actually become a single liner that adds `--no-follow`:: and nothing
else.  The changes to config/log.adoc should probably be kept.

Thanks.