From: Matt Hunter <m@lfurio.us>
Date: Fri, 12 Jun 2026 14:00:54 GMT
Subject: Re: [PATCH 6/7] fetch: add configuration option fetch.followRemoteHEAD
Message-ID: <DJ74J0G5PUXF.3DVTRHXS0GEG1@lfurio.us>
In-Reply-To: <20260612055947.1499497-7-m@lfurio.us>

On Fri Jun 12, 2026 at 1:55 AM EDT, Matt Hunter wrote:
> diff --git a/Documentation/config/remote.adoc b/Documentation/config/remote.adoc
> index eb9c8a3c4884..761bf4ba7d14 100644
> --- a/Documentation/config/remote.adoc
> +++ b/Documentation/config/remote.adoc
> @@ -157,15 +157,12 @@ Blank values signal to ignore all previous values, allowing a reset of
>  the list from broader config scenarios.
>  
>  remote.<name>.followRemoteHEAD::
> -	How linkgit:git-fetch[1] should handle updates to `remotes/<name>/HEAD`
> -	when fetching using the configured refspecs of a remote.
> -	The default value is "create", which will create `remotes/<name>/HEAD`
> -	if it exists on the remote, but not locally; this will not touch an
> -	already existing local reference. Setting it to "warn" will print
> -	a message if the remote has a different value than the local one;
> -	in case there is no local reference, it behaves like "create".
> -	A variant on "warn" is "warn-if-not-$branch", which behaves like
> -	"warn", but if `HEAD` on the remote is `$branch` it will be silent.
> -	Setting it to "always" will silently update `remotes/<name>/HEAD` to
> -	the value on the remote.  Finally, setting it to "never" will never
> -	change or create the local reference.
> +	When fetching this remote using its default refspec, this option determines
> +	how to handle differences between the remote's `HEAD` and the local
> +	`remotes/<name>/HEAD` symbolic-ref.  Overrides the setting for
> +	`fetch.followRemoteHEAD`.  See `fetch.followRemoteHEAD` for a description of
> +	accepted values.
> ++
> +In addition to the values supported by `fetch.followRemoteHEAD`, this option may
> +also take on the value "warn-if-not-`$branch`", which behaves like "warn", but
> +ignores the warning if the remote's `HEAD` is `remotes/<name>/$branch`.

In hindsight, I'm wondering if $branch ought to be stylized as <branch>
to match the rest of the docs.  Thoughts?