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

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

[Hussain Sitamouwala]

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(-)

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

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

[Junio C Hamano]

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.

> 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:

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

[Kaartic Sivaraam]

On 11/8/26 04:25, Junio C Hamano wrote:
> 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

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

[Hussain Sitamouwala]

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

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

[Hussain Sitamouwala]

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

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

[Kaartic Sivaraam]

On 11/13/26 19:53, Hussain Sitamouwala wrote:
> 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

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

[Kaartic Sivaraam]

On 11/13/26 20:07, Hussain Sitamouwala wrote:
> 
> 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