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

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 25, 2026, 17:23 UTC
Message-ID: <xmqqpl1efs9j.fsf@gitster.g>
In-Reply-To: <20260625-document-log-no-follow-v4-1-9bb233248b8f@gmail.com>

Tamir Duberstein <tamird@gmail.com> writes:

Show 12 quoted lines

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

Show 10 quoted lines

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

Show 15 quoted lines

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