git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH] doc: document two-pass promisor remote fetch order

From
EEdson <edsonwasswa54@gmail.com>
Date
Oct 28, 2026, 09:17 UTC
Message-ID
<20261028091749.1948-1-edsonwasswa54@gmail.com>

The "Using many promisor remotes" section in the partial-clone design documentation describes how promisor remotes are configured and the order in which they are tried. However, it does not mention that servers can advertise promisor remotes via the protocol v2 "promisor-remote" capability, and that such server-accepted remotes are tried before other configured promisor remotes.

Document this two-pass fetch order: first try accepted remotes (those advertised by the server and accepted by the client), then try all configured promisor remotes.

Also clarify the security model for server-advertised promisor remotes. Advertising a remote does not, by itself, make the client accept or trust it. By default, clients reject all server-advertised promisor remotes (the promisor.acceptFromServer default is "none"). A client only accepts an advertised remote when the user explicitly configures an acceptance policy via promisor.acceptFromServer or promisor.acceptFromServerUrl. This prevents servers from arbitrarily directing clients to fetch from untrusted repositories, addressing the concern that a server might inject a brand-new, untrusted promisor remote configuration.

Reference the gitprotocol-v2 documentation for protocol details rather than duplicating the information.

Signed-off-by: Edson <edsonwasswa54@gmail.com>
---
 Documentation/technical/partial-clone.adoc | 9 +++++++++
 1 file changed, 9 insertions(+)
diff --git a/Documentation/technical/partial-clone.adoc b/Documentation/technical/partial-clone.adoc
index 18718a3840..f80346729b 100644
--- a/Documentation/technical/partial-clone.adoc
+++ b/Documentation/technical/partial-clone.adoc
@@ -196,6 +196,15 @@ filtered `git-fetch` commands from the central server.
 
 When fetching objects, promisor remotes are tried one after the other
 until all the objects have been fetched.
+When a server advertises promisor remotes via the protocol v2
+"promisor-remote" capability and the client accepts them (see
+linkgit:gitprotocol-v2[5]), those accepted remotes are tried first.
+Note that clients only accept server-advertised promisor remotes when
+explicitly configured to do so via the `promisor.acceptFromServer` or
+`promisor.acceptFromServerUrl` options (see linkgit:git-config[1]),
+which prevents arbitrary injection of untrusted remotes by servers.
+After trying the accepted remotes, Git then tries the other configured
+promisor remotes as described below.
 
 Remotes that are considered "promisor" remotes are those specified by
 the following configuration variables:
-- 
2.46.0.windows.1
Message 1 of 1 in “doc: document two-pass promisor remote fetch order”
  1. doc: document two-pass promisor remote fetch orderEdson, Oct 28, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.