patchdoc: clarify that set-head does not change the remote's HEAD

4 messages between Sep 27, 2026 and Sep 29, 2026, from Matthias Goergens, Junio C Hamano.

Plain Markdown or JSON for tools and agents. Diffs are folded; open one to read it.

Matthias GoergensSep 27, 2026, 05:50 UTC on lore

`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(+)

Show changes to Documentation/git-remote.adoc +6 −0

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

Junio C HamanoSep 28, 2026, 19:01 UTC in reply to Matthias Goergens on lore

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

Matthias Goergens <matthias.goergens@gmail.com> writes:

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

This is true, but the local nature of the command is not limited to set-head.

Adding a new 5 line paragraph specifically to the description of the `set-head` command may be an improvement, but I wonder if we should tell the readers that anything and everything done via "git remote" affects the local repository, not the remote one, as the very first thing in the manual page. That way, we do not have to say that 'remote prune' only prunes remote-tracking branches and does not run any pruning command on the remote repository, for example.

Thanks.

Show 20 quoted lines

>  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

Matthias GoergensSep 29, 2026, 12:00 UTC in reply to Matthias Goergens on lore

[PATCH v2] doc: remote: say that it only affects the local repository

Nothing that "git remote" does changes a remote repository. "set-head" updates the local refs/remotes/<name>/HEAD, not the remote's own HEAD; "prune" deletes stale remote-tracking branches, not branches on the remote; and so on. The manual page never says so, and wording such as "Set or delete the default branch ... for the named remote" can be read as acting on the remote itself. It was recently misread that way in a discussion on another project's mailing list.

Say it once, near the top of the DESCRIPTION, rather than in the description of each subcommand.

Signed-off-by: Matthias Goergens <matthias.goergens@gmail.com>
---
Changes since v1, following Junio's suggestion:

 - Say once, near the top of the DESCRIPTION, that "git remote" only
   changes the local repository, instead of adding a paragraph to the
   "set-head" entry.  The "set-head" paragraph is dropped, as the
   general statement covers it.

 - Drop the remark that Git offers no client-side way to change a
   remote's default branch; it only made sense next to "set-head".

The misreading mentioned above is in this sub-thread of a Linux MAINTAINERS patch: https://lore.kernel.org/all/arfrW8NmQ4tsCF2I@ryzen/

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

Show changes to Documentation/git-remote.adoc +5 −0

diff --git a/Documentation/git-remote.adoc b/Documentation/git-remote.adoc
index eaae30aa88..315100409d 100644
--- a/Documentation/git-remote.adoc
+++ b/Documentation/git-remote.adoc
@@ -28,6 +28,11 @@ DESCRIPTION
 
 Manage the set of repositories ("remotes") whose branches you track.
 
+`git remote` changes only the local repository, i.e. its configuration
+and its refs, and never modifies a remote repository.  Some subcommands,
+such as `show`, `prune`, `update` and `set-head --auto`, contact a
+remote repository to read from it.
+
 
 OPTIONS
 -------

Range-diff against v1:
1:  fc517f8ddd ! 1:  b20a2e51ab doc: clarify that set-head does not change the remote's HEAD
    @@ Metadata
     Author: Matthias Goergens <matthias.goergens@gmail.com>
     
      ## Commit message ##
    -    doc: clarify that set-head does not change the remote's HEAD
    +    doc: remote: say that it only affects the local repository
     
    -    `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.
    +    Nothing that "git remote" does changes a remote repository.  "set-head"
    +    updates the local refs/remotes/<name>/HEAD, not the remote's own HEAD;
    +    "prune" deletes stale remote-tracking branches, not branches on the
    +    remote; and so on.  The manual page never says so, and wording such as
    +    "Set or delete the default branch ... for the named remote" can be read
    +    as acting on the remote itself.  It was recently misread that way in a
    +    discussion on another project's mailing list.
     
    -    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.
    +    Say it once, near the top of the DESCRIPTION, rather than in the
    +    description of each subcommand.
     
         Signed-off-by: Matthias Goergens <matthias.goergens@gmail.com>
     
      ## Documentation/git-remote.adoc ##
    -@@ Documentation/git-remote.adoc: 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
    +@@ Documentation/git-remote.adoc: DESCRIPTION
    + 
    + Manage the set of repositories ("remotes") whose branches you track.
    + 
    ++`git remote` changes only the local repository, i.e. its configuration
    ++and its refs, and never modifies a remote repository.  Some subcommands,
    ++such as `show`, `prune`, `update` and `set-head --auto`, contact a
    ++remote repository to read from it.
    ++
    + 
    + OPTIONS
    + -------

-- 
2.55.0

Junio C HamanoSep 29, 2026, 16:28 UTC in reply to Matthias Goergens on lore

Re: [PATCH v2] doc: remote: say that it only affects the local repository

Matthias Goergens <matthias.goergens@gmail.com> writes:

Show 13 quoted lines

> diff --git a/Documentation/git-remote.adoc b/Documentation/git-remote.adoc
> index eaae30aa88..315100409d 100644
> --- a/Documentation/git-remote.adoc
> +++ b/Documentation/git-remote.adoc
> @@ -28,6 +28,11 @@ DESCRIPTION
>  
>  Manage the set of repositories ("remotes") whose branches you track.
>  
> +`git remote` changes only the local repository, i.e. its configuration
> +and its refs, and never modifies a remote repository.  Some subcommands,
> +such as `show`, `prune`, `update` and `set-head --auto`, contact a
> +remote repository to read from it.
> +

I would not have minded having additional text in descriptions for individual operations like 'set-head' and 'prune' that might be misread to work on the other side, but the description above is very clear and we may not need anything extra.

I also like the second sentence, mentioning that some commands read from the remote. It implicitly stresses that nobody writes to the remote.

Thanks.