Git 2.56's fetch.followRemoteHEAD setting fixes stale origin/HEAD for every remote

Description and use

The fetch.followRemoteHEAD setting in Git 2.56 automatically updates remote HEAD symbolic refs when the default branch changes, eliminating stale refs without manual intervention.

Problem

Stale origin/HEAD symbolic refs persist after remote default branch changes, causing confusion and potential merge errors.

Outcome

Setting fetch.followRemoteHEAD to always provides a single global switch that keeps all remote HEAD symbolic refs current across all remotes, eliminating stale refs without per-remote configuration.

Workflow

• Clone the repository
• Rename the remote default branch (e.g., main → trunk)
• Run git fetch to pull new branches
• Observe that origin/HEAD remains stale
• Configure git config --global fetch.followRemoteHEAD always
• Add multiple remotes to a fresh repo
• Run git fetch --all and verify each remote’s HEAD tracks correctly
• Rename a remote’s default branch again and fetch to see automatic update
• Compare behavior with older Git versions (e.g., 2.55) to confirm the new global setting is required

Evidence

Git 2.56, released in the past few weeks, adds a config variable called fetch.followRemoteHEAD that is supposed to address this, by giving you one global switch instead of a separate setting per remote.

Source

Setting the per-remote value to warn doesn’t fix it either, it just tells you: hint: Run 'git remote set-head origin trunk' to follow the change...

Source

The real test is what happens later, when a remote I already have changes its default branch again, with no new config written anywhere... That matched the documentation exactly, both ways.

Source