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

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

[Edson]

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.

The implementation uses a two-pass approach: first try accepted remotes
(those advertised by the server and accepted by the client), then try
all configured promisor remotes. Document this behavior to make the
technical design notes complete.

This patch also clarifies 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 | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/technical/partial-clone.adoc b/Documentation/technical/partial-clone.adoc
index a1104930fb..f80346729b 100644
--- a/Documentation/technical/partial-clone.adoc
+++ b/Documentation/technical/partial-clone.adoc
@@ -199,6 +199,10 @@ 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.
 
-- 
2.46.0.windows.1

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

[Junio C Hamano]

Edson <edsonwasswa54@gmail.com> writes:

> ...
> The implementation uses a two-pass approach: first try accepted remotes
> (those advertised by the server and accepted by the client), then try
> all configured promisor remotes. Document this behavior to make the
> technical design notes complete.
> ...
>  Documentation/technical/partial-clone.adoc | 4 ++++
>  1 file changed, 4 insertions(+)

The log message may accurately describe the motivation and the
behavior being documented, but the patch itself appears to be
malformed or based on an unpublished tree.

> diff --git a/Documentation/technical/partial-clone.adoc b/Documentation/technical/partial-clone.adoc
> index a1104930fb..f80346729b 100644
> --- a/Documentation/technical/partial-clone.adoc
> +++ b/Documentation/technical/partial-clone.adoc
> @@ -199,6 +199,10 @@ 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.

Specifically, the commit message states: "The implementation uses a
two-pass approach ... Document this behavior to make the technical
design notes complete."  But the patch text provides the documentation
of the two-pass approach as context lines (without '+'), and only adds
the security model paragraph:

When sending a new topic that is not anywhere in my tree, please
make sure it applies to either (1) the last published feature
release (currently, Git 2.56.0), or (2) a recent tip of 'master'
branch.  The former is preferred for a topic to fix a bug in the
released version, while the latter is more appropriate for a new
feature and behavior.  A patch that does not apply to either should
be accompanied by a note that explains on what tree it is designed
to be applied (see [*] for an example of how it is communicated).

Thanks.


[Reference]

 * In https://lore.kernel.org/git/20261023-b4-pks-odb-extension-v3-0-b1bb30a006db@pks.im/
   the author explains the base of the topic as:

      The series is built on top of c51408889c (The 6th batch, 2026-10-16)
      with the following dependencies merged into it:

      - ps/odb-files-alternates at 0ba59c8453 (odb/source: drop
        `read_alternates` callback, 2026-10-08) merged into it.

      - ps/setup-enforce-repo-passed-to-create-repository-has-no-state
        (phew, what a mouthful) at 0ba59c8453 (odb/source: drop
        `read_alternates` callback, 2026-10-08).

 * The resulting topic, applying the patches on a synthetic base the
   above instruction describes, looks like this:

   $ git log --first-parent --oneline master..901d6767e6
   901d6767e6 builtin/submodule: propagate "--object-storage-format="
   ed8e104fe6 builtin/clone: introduce "--object-storage-format="
   3545b04fde builtin/init: introduce handling of object storage format
   590e753455 builtin: expose the object storage format
   074bf8b219 setup: allow overriding object storage format via environment
   0538b7b345 setup: introduce object storage extension
   27dfe6b692 loose: drop unused `repo_write_loose_object_map()`
   1cdc1db14b Merge branch 'ps/setup-enforce-repo-passed-to-create-repository-has-no-state' into ps/odb-object-storage-extension
   7464b1a063 Merge branch 'ps/odb-files-alternates' into ps/odb-object-storage-extension

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

[Edson]

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