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

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

[Matthias Goergens]

`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

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

[Junio C Hamano]

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.

>  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

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

[Matthias Goergens]

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

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

[Junio C Hamano]

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

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