threads / patch / 66801

patchpartial-clone: document promisor remote fetch ordering

Subject: [PATCH] partial-clone: document promisor remote fetch ordering

## tl;dr

7 messages between Nov 7, 2026 and Nov 14, 2026. Diffs are folded; open one to read it.

replies: 6people: 3as markdown or json

Hussain Sitamouwala· Nov 7, 2026, 15:04 UTC · lore
Document that accepted promisor remotes are tried before other promisor remotes, and that Git falls back to the next remote when a fetch fails.
Signed-off-by: Hussain Sitamouwala <husainsitamuwala21@gmail.com>
---
 Documentation/technical/partial-clone.adoc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Show changes to Documentation/technical/partial-clone.adoc +3 −1
diff --git a/Documentation/technical/partial-clone.adoc b/Documentation/technical/partial-clone.adoc
index 18718a3840..9720b856ce 100644
--- a/Documentation/technical/partial-clone.adoc
+++ b/Documentation/technical/partial-clone.adoc
@@ -195,7 +195,9 @@ cache servers for fetching missing blobs while continuing to do
 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.
+until all the objects have been fetched. Promisor remotes accepted from a
+server are tried before other promisor remotes. If a fetch from a remote fails,
+Git tries the remaining objects from the next remote.
 
 Remotes that are considered "promisor" remotes are those specified by
 the following configuration variables:
-- 
2.53.0
Junio C Hamano· Nov 7, 2026, 22:55 UTC · re: Hussain Sitamouwala · lore

Re: [PATCH] partial-clone: document promisor remote fetch ordering

Hussain Sitamouwala <husainsitamuwala21@gmail.com> writes:
> Document that accepted promisor remotes are tried before other promisor remotes, and that Git falls back to the next remote when a fetch fails.

Hussain, the above line is overly long. Usual line-length limitation rules for this mailing list applies (~70 columns).

Hussain, where did this documentation update come from? What prompted you to make this update? Is this documenting a long-standing existing behaviour? Is this trying to fill documentation gap left by more recent behaviour change? Something else?

Christian, does the behaviour this patch documents the current one? How does it relate to 8808e61fd3 (promisor-remote: try accepted remotes before others in get_direct(), 2026-04-07) which you did?

It seems there are multiple people sending messages with words like "promisor", "fetch", "order", and "Outreachy" on their "Subject:" fairly recently, but are you in charge of herding these folks, or is somebody else helping them? Without knowing if there is somebody central coordinating these that I can ask about, it is hard to tell if these people are making coherent effort to achieve something worthwhile, or if they are just randomly banging the door.

Thanks.
Show 20 quoted lines
> Signed-off-by: Hussain Sitamouwala <husainsitamuwala21@gmail.com>
> ---
>  Documentation/technical/partial-clone.adoc | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/technical/partial-clone.adoc b/Documentation/technical/partial-clone.adoc
> index 18718a3840..9720b856ce 100644
> --- a/Documentation/technical/partial-clone.adoc
> +++ b/Documentation/technical/partial-clone.adoc
> @@ -195,7 +195,9 @@ cache servers for fetching missing blobs while continuing to do
>  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.
> +until all the objects have been fetched. Promisor remotes accepted from a
> +server are tried before other promisor remotes. If a fetch from a remote fails,
> +Git tries the remaining objects from the next remote.
>  
>  Remotes that are considered "promisor" remotes are those specified by
>  the following configuration variables:
Kaartic Sivaraam· Nov 13, 2026, 13:53 UTC · re: Junio C Hamano · lore

Re: [PATCH] partial-clone: document promisor remote fetch ordering

On 11/8/26 04:25, Junio C Hamano wrote:
Show 9 quoted lines
> Hussain Sitamouwala <husainsitamuwala21@gmail.com> writes:
>  > It seems there are multiple people sending messages with words like
> "promisor", "fetch", "order", and "Outreachy" on their "Subject:"
> fairly recently, but are you in charge of herding these folks, or is
> somebody else helping them?  Without knowing if there is somebody
> central coordinating these that I can ask about, it is hard to tell
> if these people are making coherent effort to achieve something
> worthwhile, or if they are just randomly banging the door.
> The patches surrounding promisor-remote are coming through because we had proposed the following project for this year's Outreachy round.
  Implement promisor remote fetch ordering
  When a Git repository is configured with multiple promisor remotes,
  there’s currently no mechanism to specify or optimize the order in
  which these remotes should be queried when fetching missing objects.
  Different remotes may have different performance characteristics,
  costs, or reliability, making fetch order an important consideration.
  This project aims to implement a fetch ordering mechanism for multiple
  promisor remotes. The order could be:
    - Configured locally by the client
    - Advertised by servers through the promisor-remote protocol
  The key challenge is designing a flexible system that allows servers
  to communicate their preferred fetch order to clients (to ensure
  optimal performance and cost management).
See also: https://lore.kernel.org/git/CAP8UFD3kd=6QHp2oB+t+g-2D8bY-Oe5+_Vk+RJeaCa_xhxGrsA@mail.gmail.com/
I have volunteered to mentor the same and Chrisitian has mentioned that he'll help with the project. Feel free to ping me too in case you see anything around this you need some help with.
Sorry for the late response. I just thought I'll fill in with the context in case it helps.
-- 
Sivaraam
Hussain Sitamouwala· Nov 13, 2026, 14:23 UTC · re: Kaartic Sivaraam · lore

Re: [PATCH] partial-clone: document promisor remote fetch ordering

Hi Kaartic,

Thank you for the context on the project and for the offer to help, I appreciate it.

For the record, the discussion on this patch continued in the v2 thread, and the final version (v3) has been queued as hs/doc-promisor-fetch-order. The commit message explains that it documents the ordering introduced by 8808e61fd3.

Thanks, Hussain

Hussain Sitamouwala· Nov 13, 2026, 14:37 UTC · re: Hussain Sitamouwala · lore

Re: [PATCH] partial-clone: document promisor remote fetch ordering

Hi Kaartic, Junio,

Junio, thank you for the review and for queueing v3. The comments on the redundant sentence and on threading were useful.

Reading promisor_remote_get_direct() and try_promisor_remotes() for this patch made me want to keep working on "Implement promisor remote fetch ordering".

Kaartic, a question: from the project description I see two parts, a client-side way to configure the order and the server advertising its preferred order. My understanding is that the client-side part is the smaller first step, since it does not change the protocol, but I may be missing context. Would you suggest starting there?

Before writing any code, I will read the earlier list discussion around 8808e61fd3 and the promisor-remote capability, so I do not ask about things that were already settled.

Thanks, Hussain

Kaartic Sivaraam· Nov 14, 2026, 15:35 UTC · re: Hussain Sitamouwala · lore

Re: [PATCH] partial-clone: document promisor remote fetch ordering

On 11/13/26 20:07, Hussain Sitamouwala wrote:
Show 6 quoted lines
> > Kaartic, a question: from the project description I see two parts,
> a client-side way to configure the order and the server advertising
> its preferred order. My understanding is that the client-side part is
> the smaller first step, since it does not change the protocol, but I
> may be missing context. Would you suggest starting there?
>
It is indeed good to start with client-side but considering also that the server-side part needs to be introduced later.
In any case, this is something to be discussed post the Outreachy results are out, I think.
-- 
Sivaraam
Kaartic Sivaraam· Nov 14, 2026, 15:32 UTC · re: Hussain Sitamouwala · lore

Re: [PATCH] partial-clone: document promisor remote fetch ordering

On 11/13/26 19:53, Hussain Sitamouwala wrote:
Show 8 quoted lines
> Hi Kaartic,
> > Thank you for the context on the project and for the offer to help,
> I appreciate it.
> > For the record, the discussion on this patch continued in the v2
> thread, and the final version (v3) has been queued as
> hs/doc-promisor-fetch-order. The commit message explains that it
> documents the ordering introduced by 8808e61fd3.
> Sorry if it wasn't clear. I actually intended that reply to Junio.
I am aware that v3 has been queued. Thank you for the context, though. Kudos on getting it queued!
-- 
Sivaraam

← back to recent threads