[PATCH] doc: clarify that set-head does not change the remote's HEAD

From: Matthias Goergens <matthias.goergens@gmail.com>
Date: Sep 27, 2026, 05:50 UTC
Message-ID: <20260927055040.2441925-1-matthias.goergens@gmail.com>

`git remote set-head <name> <branch>` never changes the remote repository's own `HEAD`, i.e. the branch that a fresh `git clone` of that remote checks out; every change it makes is local.

The current wording, "Set or delete the default branch ... for the named remote", reads as though the command changes the remote itself. It was recently misread that way in a discussion on another project's mailing list, until a test showed the remote's `HEAD` unchanged.

Say that the change is local and that Git offers no client-side way to change a remote's own default branch.

Signed-off-by: Matthias Goergens <matthias.goergens@gmail.com>
---
The misreading is in this sub-thread of a Linux MAINTAINERS patch:
https://lore.kernel.org/all/arfrW8NmQ4tsCF2I@ryzen/

On a gitolite server, the remote's HEAD can be changed with gitolite's symbolic-ref command, if the site enables it. On kernel.org, for example:

  ssh git@gitolite.kernel.org symbolic-ref pub/scm/<repo> HEAD refs/heads/<branch>

(https://korg.docs.kernel.org/gitolite/index.html#symbolic-ref). If a client-side way would be welcome, e.g. a push option that receive-pack honours, I could look into it.

 Documentation/git-remote.adoc | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/git-remote.adoc b/Documentation/git-remote.adoc
index eaae30aa88..c9cf17e7bd 100644
--- a/Documentation/git-remote.adoc
+++ b/Documentation/git-remote.adoc
@@ -107,6 +107,12 @@ branch. For example, if the default branch for `origin` is set to
 `master`, then `origin` may be specified wherever you would normally
 specify `origin/master`.
 +
+This command does not change the remote repository's own `HEAD`, i.e.
+the branch that a fresh `git clone` of that remote will check out;
+every change it makes is local. Git provides no way to change a
+remote's own default branch from the client; how that is done depends
+on how the remote is hosted.
++
 With `-d` or `--delete`, the symbolic ref `refs/remotes/<name>/HEAD` is deleted.
 +
 With `-a` or `--auto`, the remote is queried to determine its `HEAD`, then the

-- 
2.55.0