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

From: Matthias Goergens <matthias.goergens@gmail.com>
Date: Sep 29, 2026, 12:00 UTC
Message-ID: <20260929120010.840402-1-matthias.goergens@gmail.com>
In-Reply-To: <20260927055040.2441925-1-matthias.goergens@gmail.com>

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

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