followRemoteHEAD management question

followRemoteHEAD management question

[Matt Hunter]

Hello git list,

In the past, I've preferred to run 'git remote set-head <name> -d' when
setting up a new repository, since I generally have an awareness of what
the remote default branch is, and I don't like seeing them in branch
listings or git-log annotations.  They are especially noisy to me if I
have multiple remotes.  It's possible this config is ill-advised - I
would love to be educated if so...

However, since b7f7d16562c3 (fetch: add configuration for set_head
behaviour), these changes are undone by every 'git fetch'.

The topic mentioned above (merged in a1f34d595503) adds a new
configuration key 'remote.<name>.followRemoteHEAD'.  I'm assuming that
the intended use for followRemoteHEAD is really only in local /
per-repository config, since trying to apply it to my personal
.gitconfig has some odd behavior.

The <name> in the key template does not accept a wildcard, so I must
list out each of the common remote names I use across different
repositories.  Since many of my repos don't actually have remotes
established for all of these names, they pick up a kind of half-baked
definition for each of them as git performs its config parsing.  For
instance, a name will appear under 'git remote -v', but it won't
have any actual properties configured.

I'd like to add a line to my config somewhere that can globally restore
the old behavior in this context, eg:

    git config --global remote.*.followRemoteHEAD never

instead of adding individual entries to each project's .git/config.

Is there another solution in place I've missed?  If not, would there be
any opposition to a new key like 'remote.followRemoteHEAD' which serves
to provide a default value for any remote that doesn't have its own
'remote.<name>.followRemoteHEAD' key?

I've started scouting out changes to make for such a patch.  It's not
ready yet, but I figured I would throw this question out in case an easy
answer can save the effort.

Thanks

Re: followRemoteHEAD management question

[Jeff King]

On Fri, Jun 05, 2026 at 12:31:30PM -0400, Matt Hunter wrote:

> In the past, I've preferred to run 'git remote set-head <name> -d' when
> setting up a new repository, since I generally have an awareness of what
> the remote default branch is, and I don't like seeing them in branch
> listings or git-log annotations.  They are especially noisy to me if I
> have multiple remotes.  It's possible this config is ill-advised - I
> would love to be educated if so...

No, it's perfectly reasonable. Being able to refer to "origin" to mean
"origin/HEAD" is sometimes handy, but if you don't use it, there's no
reason to set up the symref in the first place.

> However, since b7f7d16562c3 (fetch: add configuration for set_head
> behaviour), these changes are undone by every 'git fetch'.
> 
> The topic mentioned above (merged in a1f34d595503) adds a new
> configuration key 'remote.<name>.followRemoteHEAD'.  I'm assuming that
> the intended use for followRemoteHEAD is really only in local /
> per-repository config, since trying to apply it to my personal
> .gitconfig has some odd behavior.

I think this is a gap in the new feature's implementation. It added
per-remote config, but there is no global config to fall back to (e.g.,
the way that remote.*.prune falls back to fetch.prune). There should be
a fetch.followRemoteHEAD option (or perhaps remote.followRemoteHEAD).

> The <name> in the key template does not accept a wildcard, so I must
> list out each of the common remote names I use across different
> repositories.  Since many of my repos don't actually have remotes
> established for all of these names, they pick up a kind of half-baked
> definition for each of them as git performs its config parsing.  For
> instance, a name will appear under 'git remote -v', but it won't
> have any actual properties configured.

Yes, this is a common problem with the remote-config namespace. Defining
_any_ key makes the remote "exist", even without a defined url, but that
isn't usually the intent.  But we can't distinguish that from the case
where you really do want to define a remote without a url (in which case
the url is the name of the remote).

> Is there another solution in place I've missed?  If not, would there be
> any opposition to a new key like 'remote.followRemoteHEAD' which serves
> to provide a default value for any remote that doesn't have its own
> 'remote.<name>.followRemoteHEAD' key?
> 
> I've started scouting out changes to make for such a patch.  It's not
> ready yet, but I figured I would throw this question out in case an easy
> answer can save the effort.

I think you are on the right track. I can see arguments for or against
putting it in fetch.* or remote.*, so you'll have to pick one. ;)

-Peff

Re: followRemoteHEAD management question

[Matt Hunter]

On Mon Jun 8, 2026 at 7:49 PM EDT, Jeff King wrote:
>> 
>> The topic mentioned above (merged in a1f34d595503) adds a new
>> configuration key 'remote.<name>.followRemoteHEAD'.  I'm assuming that
>> the intended use for followRemoteHEAD is really only in local /
>> per-repository config, since trying to apply it to my personal
>> .gitconfig has some odd behavior.
>
> I think this is a gap in the new feature's implementation. It added
> per-remote config, but there is no global config to fall back to (e.g.,
> the way that remote.*.prune falls back to fetch.prune). There should be
> a fetch.followRemoteHEAD option (or perhaps remote.followRemoteHEAD).

Earlier on while working on this, I actually settled on
fetch.followRemoteHEAD instead, taking example from the prune setting.
Thanks for the confirmation.

>> The <name> in the key template does not accept a wildcard, so I must
>> list out each of the common remote names I use across different
>> repositories.  Since many of my repos don't actually have remotes
>> established for all of these names, they pick up a kind of half-baked
>> definition for each of them as git performs its config parsing.  For
>> instance, a name will appear under 'git remote -v', but it won't
>> have any actual properties configured.
>
> Yes, this is a common problem with the remote-config namespace. Defining
> _any_ key makes the remote "exist", even without a defined url, but that
> isn't usually the intent.  But we can't distinguish that from the case
> where you really do want to define a remote without a url (in which case
> the url is the name of the remote).

I had no idea a remote like that was supported.  Interesting.

>> Is there another solution in place I've missed?  If not, would there be
>> any opposition to a new key like 'remote.followRemoteHEAD' which serves
>> to provide a default value for any remote that doesn't have its own
>> 'remote.<name>.followRemoteHEAD' key?
>> 
>> I've started scouting out changes to make for such a patch.  It's not
>> ready yet, but I figured I would throw this question out in case an easy
>> answer can save the effort.
>
> I think you are on the right track. I can see arguments for or against
> putting it in fetch.* or remote.*, so you'll have to pick one. ;)

As stated, I think putting it in fetch.* is more consistent.  I'd be
curious to hear arguments the other way.

As for another design decision: I'm leaning toward omitting support for
the "warn-if-not-$branch" value in fetch.followRemoteHEAD.

My take on that option as-documented is that it serves more as an
acknowledgment from the user that "yes, I understand that origin has
pointed HEAD at foo, please only warn me if it changes" as opposed to the
user expressing that the branch "foo" is in some way special to them.

This interpretation feels very remote-dependent and doesn't make sense in
the context of a default catch-all value to me.

Thanks for the feedback!

Re: followRemoteHEAD management question

[Jeff King]

On Thu, Jun 11, 2026 at 12:12:54AM -0400, Matt Hunter wrote:

> > Yes, this is a common problem with the remote-config namespace. Defining
> > _any_ key makes the remote "exist", even without a defined url, but that
> > isn't usually the intent.  But we can't distinguish that from the case
> > where you really do want to define a remote without a url (in which case
> > the url is the name of the remote).
> 
> I had no idea a remote like that was supported.  Interesting.

I suspect it is more of an emergent property than something that was
carefully designed, but after so many years I'd hesitate to change it
(at least without a big warning and deprecation period).

> > I think you are on the right track. I can see arguments for or against
> > putting it in fetch.* or remote.*, so you'll have to pick one. ;)
> 
> As stated, I think putting it in fetch.* is more consistent.  I'd be
> curious to hear arguments the other way.

My initial thought is that it might affect clone as well as fetch. But I
guess this feature does not kick in for clone, as it has its own logic
for handling the remote-tracking HEAD. Though arguably it should be
possible to configure it not to create one in the first place.

> As for another design decision: I'm leaning toward omitting support for
> the "warn-if-not-$branch" value in fetch.followRemoteHEAD.
> 
> My take on that option as-documented is that it serves more as an
> acknowledgment from the user that "yes, I understand that origin has
> pointed HEAD at foo, please only warn me if it changes" as opposed to the
> user expressing that the branch "foo" is in some way special to them.
> 
> This interpretation feels very remote-dependent and doesn't make sense in
> the context of a default catch-all value to me.

Agreed. I can't think of a reason you'd want it in the global option.
And if we're wrong, it is easy to add support later (versus adding it
now, finding out that it creates awkward corner cases, and then having
the backwards-incompatible change of ripping it out).

-Peff

Re: followRemoteHEAD management question

[Bence Ferdinandy]

On Thu Jun 11, 2026 at 08:01, Jeff King <peff@peff.net> wrote:
>
> My initial thought is that it might affect clone as well as fetch. But I
> guess this feature does not kick in for clone, as it has its own logic
> for handling the remote-tracking HEAD. Though arguably it should be
> possible to configure it not to create one in the first place.

If memory serves well clone has set the remote/HEAD well before this and
I think it indeed uses a different mechanism/logic.

>
>> As for another design decision: I'm leaning toward omitting support for
>> the "warn-if-not-$branch" value in fetch.followRemoteHEAD.
>> 
>> My take on that option as-documented is that it serves more as an
>> acknowledgment from the user that "yes, I understand that origin has
>> pointed HEAD at foo, please only warn me if it changes" as opposed to the
>> user expressing that the branch "foo" is in some way special to them.

Yes, that was the reasoning. So I also agree on not adding it to global. 

Bit late to the party, but happy to review/test patches if they come.

Best,
Bence