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

From: Christian Couder <christian.couder@gmail.com>
Date: Mar 3, 2026, 09:27 UTC
Message-ID: <CAP8UFD1kzuP8sYKzTJkvf08OazrMzESQ+qZNW8=Qss3DDw=OeA@mail.gmail.com>
In-Reply-To: <aaN5OPgoGANYlabu@Adekunles-MacBook-Air.local>

Hi,

On Sun, Mar 1, 2026 at 12:27 AM Abraham Samuel Adekunle <abrahamadekunle50@gmail.com> wrote:

>
> Hello,
> This is my proposal for the project
> "Implement promisor remote fetch ordering" for the 2026 GSoC programme.

Thanks for being interested in Git and this project in particular.

Show 11 quoted lines

> Personal Bio:
> =============
> Full Name:  Abraham Samuel Adekunle
> Email: abrahamadekunle50@gmail.com
> GitHub: https://github.com/devdekunle
> Pronouns: he/him
>
> About Me:
> =========
> My name is Abraham Samuel Adekunle. I love to code, read and I am a
> harworker. In my free time I love to play games and listen to soothing

I guess: s/harworker/hardworker/

> music and well, also shifting into diffuse thinking to gain a new
> perspective of whatever challenge I am trying to solve.

[...]

Show 7 quoted lines

> Contributions to the Git Community:
> ====================================
> My first contribution to the Git community was during the contribution
> phase of the December 2024 Outreachy contribution phase where I first
> learned to send patches and had my first interactions with the Git code
> base. I did not make it through then but it was an opportunity to try
> again.

Nice that you are trying again.

Show 28 quoted lines

> Contributions to other Communities:
> ===================================
> I have contributed very sparingly to the Systemd project and also
> the Linux Kernel.
>
> Microproject:
> =============
> Link: https://lore.kernel.org/git/aV_IGCld5T_dBxTs@Adekunles-MacBook-Air.local/
> Branch: aa/add-p-previous-decisions
> Status: Merged to master
> Commit ID: 8cafc305e22a59efb92472d4132616e24d3184c6
> Description:  "git add -p" and friends notes what the current status
>                of the hunk being shown is
>
> Other Contributions:
> ====================
> 1.
> Link: https://lore.kernel.org/git/cover.1771066252.git.abrahamadekunle50@gmail.com/
> Branch: aa/add-p-no-auto-advance
> Status: Merged to next
> Description: "git add -p" learned a new mode that allows the user to
>               revisit a file that was already dealt with
>
> 2.
> Link: https://lore.kernel.org/git/aWZkEYHhcIhdAjkh@Adekunles-MacBook-Air.local/
> Status: Stalled
> Description: the patch attempts to remove the use of the_repository
>              global variable in some builtins

It looks like you also have 2 contributions merged from October 2024 (when you applied for Outreachy). You can mention them too.

Show 17 quoted lines

> Project Overview and Objective:
> ===============================
> I have always wondered what happens in the background when I see these
> details on my screen in a "git fetch" process.
>
>         remote: Enumerating objects: 57, done.
>         remote: Counting objects: 100% (57/57), done.
>         remote: Compressing objects: 100% (12/12), done.
>         Receiving objects: 100% (57/57), 48.3 KiB | 512.00 KiB/s, done.
>         Resolving deltas: 100% (21/21), done.
>         remote: Total 57 (delta 21), reused 13 (delta 5), pack-reused 30
>         From https://example.com/me/repo
>         1a2b3c4..5d6e7f8  feature/xyz -> origin/feature/xyz
>
> And when I saw this project from the list of projects listed,
> I was endeared to it as it is an opportunity to work in an area of the
> that Git code base that will satisfy my curiousity while also being

s/curiousity/curiosity/

Show 8 quoted lines

> mentored by very best and most experienced Engineers there is.
>
> When a Git repository is configured with multiple promisor remotes,
> there is 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
> such as characteristics, cost, or reliability which makes the
> fetching order an important consideration.

In which order are they currently queried?

> The project aims to implement a fetch ordering mechanism for multiple
> promisor remotes by designing a flexible system that allows a server
> to dictate their preferred order to the client to ensure performance
> and cost management.

A part of the whole system that allows servers to advertise information already exists and should be reused.

We use "advertise" instead of "dictate" because the client should be able to decide.

> Review of Previous Work:
> ========================
> The project is part of the Large Object Promisor "LOP" effort
> documented in Documentatio/technical/large-object-promisor.adoc.

s/Documentatio/Documentation/ s/large-object-promisor/large-object-promisors/

Show 55 quoted lines

> 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 large blobs directly from the promisor remote without
> the server acting as a relay between the client and the promisor remote when
> fetching missing large blobs.
>
> 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.
>
> 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
> config settings for that promisor remote, for later use when fetching
> the remaining blobs from the promisor remotes.

Yeah, this is about allowing the server to advertise priority information, and the client to accept it or not, but this doesn't talk much about how this information will be used to actually change the fetch order.

It would be nice if this could talk about which order is currently used. You might want to take a look at Documentation/technical/partial-clone.adoc, especially the "Using many promisor remotes" section.

Show 6 quoted lines

> High Level Approach to Project Execution:
> =========================================
> 1. Server Side Advertisement:
> -----------------------------
> As the server knows about the promisor remotes which hold the
> large object blobs,

First I would say "large blob objects" or just "large blobs" instead of "large object blobs" if I wanted to talk about them.

Then it's true that the "promisor-remote" capability in protocol v2 was developed especially to help with large blobs and the LOP effort, but this GSoC project could be useful for any partial clone that uses multiple promisor remotes. So you could talk about "objects", not just "large blobs".

Show 24 quoted lines

> it could recommend the order in which these remotes
> could be queried by the client using a "priority=<value>" field of the
> promisor-remote capability in the Git v2 protocol, where <value> could
> be an integer between 1 and 65535, where the smallest integer indicates
> highest priority.
>
> This will be an optional feature which will be enabled by the server
> if it wants to recommend ordered fetching to the client via
> the "promisor.sendFields=priority" config option.
>
> Hence if the server advertises promisor remotes prom1 and prom2,
> it could be of the form
>         "promisor-remote=name=prom1,url=https://prom1.com,priority=10;name=prom2,url=https://prom2.com,priority=20",
> if the server is configured as:
> [remote "prom1"]
>          url = https://prom1.com
>          priority = 10
> [remote "prom2"]
>         url = https://prom2.com
>         priority = 20
>
> If the "promisor.sendFields" values does not include the "priority"
> field in its comma or space separated options, the field will not be
> advertised in the promisor-remote capability.

The issue is that right now "priority = 10" or "priority = 20" if they were configured would change nothing in the order used to fetch from promisor remotes. So the first thing to do (before having the server send that and the client use it or not) is to actually introduce the `remote.<name>.priority` config option and make it change the fetch order. When that works, it makes sense to allow the server to advertise it, and the client to accept it or not from the server.

Show 6 quoted lines

> 2. Client Side Parsing:
> -----------------------
> The client can already use the "promisor.acceptFromServer" option to
> decide which promisor remotes it will accept, so this new field
> "priority" might not be significant at all in the deciding phase but when
> fetching missing blobs from the accepted promisor remotes.

If that's what you mean, I agree that the priority advertised by a server for a promisor remote is not likely to be a (good) criteria on the client side to help decide if the client accepts to use the promisor remote or not. You might want to reword the above paragraph though as it's not easy to understand.

> Instead, if the client wants to use the server recommended "priority"
> later when fetching the missing blob from the accepted promisor remotes,
> the "priority" field will be added to the "promisor.storeFields" config
> options so that the passed value can be saved to the client config.

Yeah, that's the most likely way the client would use it.

> If the client does not enable this option in the config, the "priority"
> field will not be saved in the local config and the fetching order will
> default to the local config order.

Right.

> A new config "promisor.honorServerFetchOrder" will be implemented
> on the client side to determine if the client will use the recommended
> server advertised promisor remote fetching order or not.

I don't think this is necessary. If the client doesn't want to use the priority advertised by the server, it just needs to not add "priority" to the "promisor.storeFields" config variable.

Show 12 quoted lines

> This config can only be enabled if "promsior.acceptFromServer" is not
> "None".
>
> The options for this config value will be [true|false|local-first] where
> "false" (default) ignores server priority and will rely on the current
> config order.
> "true" sorts candidate advertised remotes by priority in ascending
> order (smallest tried first).
> "local-first" will try remotes in local .git/config first in the order
> the promisors are placed in the config file  and then
> server advertised ones ordered by priority, if the object has not been
> found by now. This last values makes me feel somehow as all objects

s/values/value/

> could have been fetched already but I am just stating my thought process.

I think we will likely not need something like this. The 3 different possibilities could be configured this way:

- to rely on the order advertised by the server: just add "priority"
to "promisor.storeFields"
- to rely on local "priority" config: just add "priority = XXX" to
some/all "remote.<name>"
- to rely on the default order: add nothing

> Proposed Project Execution Timeline:
> ====================================

This needs to take into account that the first step should be to actually introduce the `remote.<name>.priority` config option and make it change the fetch order.

Thanks.