Re: [GSoC] [Proposal v2]: Implement promisor remote fetch ordering

From: Christian Couder <christian.couder@gmail.com>
Date: Mar 24, 2026, 12:29 UTC
Message-ID: <CAP8UFD16pvfP4UYJHCCenK3c1-VNTJPpMBJL_LnHZZZXUC5ULA@mail.gmail.com>
In-Reply-To: <aafga8AjpxagiEJt@Adekunles-MacBook-Air.local>

Hi,

On Wed, Mar 4, 2026 at 8:35 AM Abraham Samuel Adekunle <abrahamadekunle50@gmail.com> wrote:

Show 5 quoted lines

> When a Git repository is configured with multiple promisor remotes,
> there is currently no other 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
> such as characteristics, cost, or reliability which makes the

There is a repetition of "characteristics" above.

> fetching order an important consideration.
> Currently, the promisor remotes are queried in the order in which they
> appear in the local .git/config.

There is the exception of the `extensions.partialClone` config variable.

Also I recently sent a patch series that might change things (see the first patch in the series introduced by https://lore.kernel.org/git/20260323080520.887550-1-christian.couder@gmail.com/), but it's not merged, so don't rewrite your proposal to take it into account.

Show 21 quoted lines

> The project aims to implement a fetch ordering mechanism for multiple
> promisor remotes that allows a client to be able to specify a fetching order,
> a server to advertise an order to the client to ensure performance
> and cost management, and the client to decide to use the server advertised
> order or not, and default to the current order if no order is specified.
>
> Review of Previous Work:
> ========================
> The project is part of the Large Object Promisor "LOP" effort
> documented in Documentation/technical/large-object-promisors.adoc.
>
> In a bid to better handle large objects, the promisor-remote
> capability was added to the Git protocol v2, as documented in
> the promisor-remote section of Documentation/gitprotocol-v2.adoc,
> which enables a protocol negotiation so that the server can advertise
> one or more promisor remotes and so that the client and server can
> discuss if the client could directly use a promisor remote the server
> is advertising and if an agreement is reached, the client would be
> able to get the missing objects directly from the promisor remote without
> the server acting as a relay between the client and the promisor remote when
> fetching missing objects.

You might want to split this very long sentence into a few smaller ones.

Show 32 quoted lines

> The ground work for adding this capability to the v2 protocol was
> started by Christian Couder in [1], where if the "promisor.advertise"
> config is set to true, the server can then propagate its promisor remote
> configurations to the client over the v2 protocol during the negotiation
> in the form
>
>         "promisor-remote=name=prom1,url=url_encoded_value1;name=prom2,url=url_encoded_value2"
>
> The client can then choose to accept some promisor remotes the server
> is advertising using the "All", "None", "KnownName" or "KnownUrl"
> configurations as values for the "promisor.acceptfromServer" config option.
>
> In [2], Christian added the option for a server to advertise more
> fields after the "name" and "url", such as "token" and
> "partialCloneFilter" for the client to use this additional information
> in deciding the remotes to use as its promisor remotes by comparing it
> with its local config information.
>
> This was implemented by adding the "promisor.sendFields" and
> "promisor.checkFields" config values to the server and client respectively.
> For example, if "promisor.sendFields" is set to "partialCloneFilter", and the
> server has the remote configured like so:
> [remote "foo"]
>         url = https://pr.test
>         partialCloneFilter = blob:none
>         token = "fake"
> then
>
>         "name=foo,url=https://pr.test,partialCloneFilter=blob:none,token=fake"
> will be advertised by the server to the client who can then decide,
> using the "promisor.checkFields" setting, to check if the passed field
> matches certain conditions before deciding to use it.

The "promisor.checkFields" config variable is not quite to decide if fields can be used, but more to decide if they should be checked before the remote is accepted.

Using the "promisor.storeFields" config option is better if fields should be used.

Show 10 quoted lines

> This work by Christian is very crucial to this project as I will take
> advantage of this and enable the advertisement of a "priority" field
> that the server can use to communicate with the client in deciding to
> use the server recommended fetch order or not.
>
> in [3] Christian also implemented the option "promisor.storeFields" which
> allowed the value of the configuration to be saved in the client's
> configuration file for use at a later time.
> As above, this option will also prove important when the server advertises
> the "priority" field as it will allow the client decided to store it in its

Maybe: s/decided //

> config settings for that promisor remote, for later use when fetching
> the remaining blobs from the promisor remotes.

Yes.

[...]

Show 7 quoted lines

> High Level Approach to Project Execution:
> =========================================
>
> 1. Introduce the `remote.<name>.priority` config option:
> ======================================================
> As said above, when fetching missing objects, the order in which the remotes
> are queried depends on the order in which they appear in the config file.

Not sure this is worth repeating three times.

> To make this flexible, I will introduce the `remote.<name>.priority` config option,
> which will allow the client to set its preferred fetch order to each promisor remote
> configuration, and then make it fetch based on this "priority" order.
> The value of this option could be an integer between 1 and 65535, where the smallest

Why 65535?

Show 10 quoted lines

> integer indicates highest priority.
>
> This will allow a promisor remote be configured as follows
>
>         [remote "prom1"]
>                 url = https://prom1.com
>                 priority = 10
>
> Therefore when the client is configured with more than one promisor remote
> and the prority is set for each promisor remote as follows,

s/prority/priority/

Show 6 quoted lines

>         [remote "prom1"]
>                 url = https://prom1.com
>                 priority = 20
>         [remote "prom2"]
>                 url = https://prom2.com
>                 priority = 10,

[...]

Show 6 quoted lines

> 2. Community Bonding (May 1 - 14, 2026):
> ----------------------------------------
> - Discuss design details with community and mentors
> - Understand safety, security constraints and design considerations
>   when implementing fetch ordering.
> - Read indepth the Documentations for promisor-remote, gitprotocol-v2,

s/indepth/in depth/

>   and other necessary documentations.

Thanks.