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

说明与用途

Git 2.56 中的 fetch.followRemoteHEAD 设置会在远程默认分支更改时自动更新远程 HEAD 的符号引用，消除旧引用，无需手动干预。

问题

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

结果

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.

工作流

• 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

证据

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.

来源

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

来源

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.

来源