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

>
> Hi,
>
> On Wed, Mar 4, 2026 at 8:35 AM Abraham Samuel Adekunle
> <abrahamadekunle50@gmail.com> wrote:
>
> > 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.

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

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

>
> > 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.
>
> [...]
>
> > 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?

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

>
> >         [remote "prom1"]
> >                 url = https://prom1.com
> >                 priority = 20
> >         [remote "prom2"]
> >                 url = https://prom2.com
> >                 priority = 10,
>
> [...]
>
> > 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/