From: Samuel Abraham Date: Tue, 03 Mar 2026 12:08:57 GMT Subject: Re: [GSoC] [Proposal]: Implement promisor remote fetch ordering Message-ID: In-Reply-To: On Tue, Mar 3, 2026 at 10:27 AM Christian Couder wrote: > > Hi, > > On Sun, Mar 1, 2026 at 12:27 AM Abraham Samuel Adekunle > 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. Thank you. > > > 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/ Okay I will fix it > > > music and well, also shifting into diffuse thinking to gain a new > > perspective of whatever challenge I am trying to solve. > > [...] > > > 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. Thank you :) > > > 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. Okay I will do that. > > > 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/ Thanks > > > 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? In the order they appear in the config file, with promisor remote configured with the extensions.partialClone (most likely "origin") bring the last one tried. > > > 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. I will reword it. Thanks > > > 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/ Thank you > > > 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. Okay thank you. I will add that to the v2. > > > 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. Okay thank you > > 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". Okay Noted > > > it could recommend the order in which these remotes > > could be queried by the client using a "priority=" field of the > > promisor-remote capability in the Git v2 protocol, where 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..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. Yes thank you. I will fix this in the v2 > > > 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. Okay > > > 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. Okay thank you > > > 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." > - to rely on the default order: add nothing Thank you for the guidance. I will fix all the changes in the v2 > > > Proposed Project Execution Timeline: > > ==================================== > > This needs to take into account that the first step should be to > actually introduce the `remote..priority` config option and make > it change the fetch order. Yes Thank you for the review. Abraham