{"thread":{"id":"66397","subject":"[PATCH] doc: clarify that set-head does not change the remote's HEAD","startedAt":"2026-09-27T05:50:45Z","lastAt":"2026-09-29T16:28:29Z","messageCount":4,"participants":["Matthias Goergens","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"553368","messageId":"20260927055040.2441925-1-matthias.goergens@gmail.com","threadId":"66397","inReplyTo":null,"subject":"[PATCH] doc: clarify that set-head does not change the remote's HEAD","fromName":"Matthias Goergens","fromEmail":"matthias.goergens@gmail.com","sentAt":"2026-09-27T05:50:40Z","receivedAt":"2026-09-27T05:50:45Z","isPatch":true,"body":"`git remote set-head ` never changes the remote\nrepository's own `HEAD`, i.e. the branch that a fresh `git clone` of\nthat remote checks out; every change it makes is local.\n\nThe current wording, \"Set or delete the default branch ... for the\nnamed remote\", reads as though the command changes the remote itself.\nIt was recently misread that way in a discussion on another project's\nmailing list, until a test showed the remote's `HEAD` unchanged.\n\nSay that the change is local and that Git offers no client-side way to\nchange a remote's own default branch.\n\nSigned-off-by: Matthias Goergens \n---\nThe misreading is in this sub-thread of a Linux MAINTAINERS patch:\nhttps://lore.kernel.org/all/arfrW8NmQ4tsCF2I@ryzen/\n\nOn a gitolite server, the remote's HEAD can be changed with gitolite's\nsymbolic-ref command, if the site enables it. On kernel.org, for\nexample:\n\n ssh git@gitolite.kernel.org symbolic-ref pub/scm/ HEAD refs/heads/\n\n(https://korg.docs.kernel.org/gitolite/index.html#symbolic-ref). If a\nclient-side way would be welcome, e.g. a push option that receive-pack\nhonours, I could look into it.\n\n Documentation/git-remote.adoc | 6 ++++++\n 1 file changed, 6 insertions(+)\n\ndiff --git a/Documentation/git-remote.adoc b/Documentation/git-remote.adoc\nindex eaae30aa88..c9cf17e7bd 100644\n--- a/Documentation/git-remote.adoc\n+++ b/Documentation/git-remote.adoc\n@@ -107,6 +107,12 @@ branch. For example, if the default branch for `origin` is set to\n `master`, then `origin` may be specified wherever you would normally\n specify `origin/master`.\n +\n+This command does not change the remote repository's own `HEAD`, i.e.\n+the branch that a fresh `git clone` of that remote will check out;\n+every change it makes is local. Git provides no way to change a\n+remote's own default branch from the client; how that is done depends\n+on how the remote is hosted.\n++\n With `-d` or `--delete`, the symbolic ref `refs/remotes//HEAD` is deleted.\n +\n With `-a` or `--auto`, the remote is queried to determine its `HEAD`, then the\n-- \n2.55.0\n\n"},{"id":"553515","messageId":"xmqq4if9mc82.fsf@gitster.g","threadId":"66397","inReplyTo":"20260927055040.2441925-1-matthias.goergens@gmail.com","subject":"Re: [PATCH] doc: clarify that set-head does not change the remote's HEAD","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-28T19:01:49Z","receivedAt":"2026-09-28T19:01:52Z","isPatch":true,"body":"Matthias Goergens writes:\n\n> `git remote set-head ` never changes the remote\n> repository's own `HEAD`, i.e. the branch that a fresh `git clone` of\n> that remote checks out; every change it makes is local.\n\nThis is true, but the local nature of the command is not limited to\nset-head.\n\nAdding a new 5 line paragraph specifically to the description of the\n`set-head` command may be an improvement, but I wonder if we should\ntell the readers that anything and everything done via \"git remote\"\naffects the local repository, not the remote one, as the very first\nthing in the manual page. That way, we do not have to say that\n'remote prune' only prunes remote-tracking branches and does not run\nany pruning command on the remote repository, for example.\n\nThanks.\n\n> Documentation/git-remote.adoc | 6 ++++++\n> 1 file changed, 6 insertions(+)\n>\n> diff --git a/Documentation/git-remote.adoc b/Documentation/git-remote.adoc\n> index eaae30aa88..c9cf17e7bd 100644\n> --- a/Documentation/git-remote.adoc\n> +++ b/Documentation/git-remote.adoc\n> @@ -107,6 +107,12 @@ branch. For example, if the default branch for `origin` is set to\n> `master`, then `origin` may be specified wherever you would normally\n> specify `origin/master`.\n> +\n> +This command does not change the remote repository's own `HEAD`, i.e.\n> +the branch that a fresh `git clone` of that remote will check out;\n> +every change it makes is local. Git provides no way to change a\n> +remote's own default branch from the client; how that is done depends\n> +on how the remote is hosted.\n> ++\n> With `-d` or `--delete`, the symbolic ref `refs/remotes//HEAD` is deleted.\n> +\n> With `-a` or `--auto`, the remote is queried to determine its `HEAD`, then the\n"},{"id":"553592","messageId":"20260929120010.840402-1-matthias.goergens@gmail.com","threadId":"66397","inReplyTo":"20260927055040.2441925-1-matthias.goergens@gmail.com","subject":"[PATCH v2] doc: remote: say that it only affects the local repository","fromName":"Matthias Goergens","fromEmail":"matthias.goergens@gmail.com","sentAt":"2026-09-29T12:00:10Z","receivedAt":"2026-09-29T12:00:18Z","isPatch":true,"body":"Nothing that \"git remote\" does changes a remote repository. \"set-head\"\nupdates the local refs/remotes//HEAD, not the remote's own HEAD;\n\"prune\" deletes stale remote-tracking branches, not branches on the\nremote; and so on. The manual page never says so, and wording such as\n\"Set or delete the default branch ... for the named remote\" can be read\nas acting on the remote itself. It was recently misread that way in a\ndiscussion on another project's mailing list.\n\nSay it once, near the top of the DESCRIPTION, rather than in the\ndescription of each subcommand.\n\nSigned-off-by: Matthias Goergens \n---\nChanges since v1, following Junio's suggestion:\n\n - Say once, near the top of the DESCRIPTION, that \"git remote\" only\n changes the local repository, instead of adding a paragraph to the\n \"set-head\" entry. The \"set-head\" paragraph is dropped, as the\n general statement covers it.\n\n - Drop the remark that Git offers no client-side way to change a\n remote's default branch; it only made sense next to \"set-head\".\n\nThe misreading mentioned above is in this sub-thread of a Linux\nMAINTAINERS patch:\nhttps://lore.kernel.org/all/arfrW8NmQ4tsCF2I@ryzen/\n\n Documentation/git-remote.adoc | 5 +++++\n 1 file changed, 5 insertions(+)\n\ndiff --git a/Documentation/git-remote.adoc b/Documentation/git-remote.adoc\nindex eaae30aa88..315100409d 100644\n--- a/Documentation/git-remote.adoc\n+++ b/Documentation/git-remote.adoc\n@@ -28,6 +28,11 @@ DESCRIPTION\n \n Manage the set of repositories (\"remotes\") whose branches you track.\n \n+`git remote` changes only the local repository, i.e. its configuration\n+and its refs, and never modifies a remote repository. Some subcommands,\n+such as `show`, `prune`, `update` and `set-head --auto`, contact a\n+remote repository to read from it.\n+\n \n OPTIONS\n -------\n\nRange-diff against v1:\n1: fc517f8ddd ! 1: b20a2e51ab doc: clarify that set-head does not change the remote's HEAD\n @@ Metadata\n Author: Matthias Goergens \n \n ## Commit message ##\n - doc: clarify that set-head does not change the remote's HEAD\n + doc: remote: say that it only affects the local repository\n \n - `git remote set-head ` never changes the remote\n - repository's own `HEAD`, i.e. the branch that a fresh `git clone` of\n - that remote checks out; every change it makes is local.\n + Nothing that \"git remote\" does changes a remote repository. \"set-head\"\n + updates the local refs/remotes//HEAD, not the remote's own HEAD;\n + \"prune\" deletes stale remote-tracking branches, not branches on the\n + remote; and so on. The manual page never says so, and wording such as\n + \"Set or delete the default branch ... for the named remote\" can be read\n + as acting on the remote itself. It was recently misread that way in a\n + discussion on another project's mailing list.\n \n - The current wording, \"Set or delete the default branch ... for the\n - named remote\", reads as though the command changes the remote itself.\n - It was recently misread that way in a discussion on another project's\n - mailing list, until a test showed the remote's `HEAD` unchanged.\n -\n - Say that the change is local and that Git offers no client-side way to\n - change a remote's own default branch.\n + Say it once, near the top of the DESCRIPTION, rather than in the\n + description of each subcommand.\n \n Signed-off-by: Matthias Goergens \n \n ## Documentation/git-remote.adoc ##\n -@@ Documentation/git-remote.adoc: branch. For example, if the default branch for `origin` is set to\n - `master`, then `origin` may be specified wherever you would normally\n - specify `origin/master`.\n - +\n -+This command does not change the remote repository's own `HEAD`, i.e.\n -+the branch that a fresh `git clone` of that remote will check out;\n -+every change it makes is local. Git provides no way to change a\n -+remote's own default branch from the client; how that is done depends\n -+on how the remote is hosted.\n -++\n - With `-d` or `--delete`, the symbolic ref `refs/remotes//HEAD` is deleted.\n - +\n - With `-a` or `--auto`, the remote is queried to determine its `HEAD`, then the\n +@@ Documentation/git-remote.adoc: DESCRIPTION\n + \n + Manage the set of repositories (\"remotes\") whose branches you track.\n + \n ++`git remote` changes only the local repository, i.e. its configuration\n ++and its refs, and never modifies a remote repository. Some subcommands,\n ++such as `show`, `prune`, `update` and `set-head --auto`, contact a\n ++remote repository to read from it.\n ++\n + \n + OPTIONS\n + -------\n-- \n2.55.0\n\n"},{"id":"553614","messageId":"xmqqld8khviu.fsf@gitster.g","threadId":"66397","inReplyTo":"20260929120010.840402-1-matthias.goergens@gmail.com","subject":"Re: [PATCH v2] doc: remote: say that it only affects the local repository","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-29T16:28:25Z","receivedAt":"2026-09-29T16:28:29Z","isPatch":true,"body":"Matthias Goergens writes:\n\n> diff --git a/Documentation/git-remote.adoc b/Documentation/git-remote.adoc\n> index eaae30aa88..315100409d 100644\n> --- a/Documentation/git-remote.adoc\n> +++ b/Documentation/git-remote.adoc\n> @@ -28,6 +28,11 @@ DESCRIPTION\n> \n> Manage the set of repositories (\"remotes\") whose branches you track.\n> \n> +`git remote` changes only the local repository, i.e. its configuration\n> +and its refs, and never modifies a remote repository. Some subcommands,\n> +such as `show`, `prune`, `update` and `set-head --auto`, contact a\n> +remote repository to read from it.\n> +\n\nI would not have minded having additional text in descriptions for\nindividual operations like 'set-head' and 'prune' that might be misread\nto work on the other side, but the description above is very clear and\nwe may not need anything extra.\n\nI also like the second sentence, mentioning that some commands read\nfrom the remote. It implicitly stresses that nobody writes to the\nremote.\n\nThanks.\n"}]}