{"thread":{"id":"66685","subject":"[PATCH] doc: document two-pass promisor remote fetch order","startedAt":"2026-10-28T09:17:49Z","lastAt":"2026-10-28T09:17:49Z","messageCount":1,"participants":["Edson"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"556624","messageId":"20261028091749.1948-1-edsonwasswa54@gmail.com","threadId":"66685","inReplyTo":null,"subject":"[PATCH] doc: document two-pass promisor remote fetch order","fromName":"Edson","fromEmail":"edsonwasswa54@gmail.com","sentAt":"2026-10-28T09:17:49Z","receivedAt":"2026-10-28T09:17:49Z","isPatch":true,"sender":{"key":"edsonwasswa54@gmail.com","avatar":null},"body":"The \"Using many promisor remotes\" section in the partial-clone design\ndocumentation describes how promisor remotes are configured and the order\nin which they are tried. However, it does not mention that servers can\nadvertise promisor remotes via the protocol v2 \"promisor-remote\"\ncapability, and that such server-accepted remotes are tried before other\nconfigured promisor remotes.\n\nDocument this two-pass fetch order: first try accepted remotes (those\nadvertised by the server and accepted by the client), then try all\nconfigured promisor remotes.\n\nAlso clarify the security model for server-advertised promisor remotes.\nAdvertising a remote does not, by itself, make the client accept or trust\nit. By default, clients reject all server-advertised promisor remotes\n(the promisor.acceptFromServer default is \"none\"). A client only accepts\nan advertised remote when the user explicitly configures an acceptance\npolicy via promisor.acceptFromServer or promisor.acceptFromServerUrl.\nThis prevents servers from arbitrarily directing clients to fetch from\nuntrusted repositories, addressing the concern that a server might inject\na brand-new, untrusted promisor remote configuration.\n\nReference the gitprotocol-v2 documentation for protocol details rather\nthan duplicating the information.\n\nSigned-off-by: Edson <edsonwasswa54@gmail.com>\n---\n Documentation/technical/partial-clone.adoc | 9 +++++++++\n 1 file changed, 9 insertions(+)\n\ndiff --git a/Documentation/technical/partial-clone.adoc b/Documentation/technical/partial-clone.adoc\nindex 18718a3840..f80346729b 100644\n--- a/Documentation/technical/partial-clone.adoc\n+++ b/Documentation/technical/partial-clone.adoc\n@@ -196,6 +196,15 @@ filtered `git-fetch` commands from the central server.\n \n When fetching objects, promisor remotes are tried one after the other\n until all the objects have been fetched.\n+When a server advertises promisor remotes via the protocol v2\n+\"promisor-remote\" capability and the client accepts them (see\n+linkgit:gitprotocol-v2[5]), those accepted remotes are tried first.\n+Note that clients only accept server-advertised promisor remotes when\n+explicitly configured to do so via the `promisor.acceptFromServer` or\n+`promisor.acceptFromServerUrl` options (see linkgit:git-config[1]),\n+which prevents arbitrary injection of untrusted remotes by servers.\n+After trying the accepted remotes, Git then tries the other configured\n+promisor remotes as described below.\n \n Remotes that are considered \"promisor\" remotes are those specified by\n the following configuration variables:\n-- \n2.46.0.windows.1\n\n\n"}]}