[Outreachy] Project Proposal : Implement promisor remote fetch ordering

Hi,

This is my proposal for the project "Implement promisor remote fetch ordering" for the December 2026 Outreachy internship.

I would appreciate any feedback from the community.

Personal Information ----------------------------

Full Name: Shashank S Mogaveera Email Address : shashu8660@gmail.com Github : https://github.com/shashu8660 Location : Kundapur, Karnataka, India (IST, UTC+5:30)

About me -------------

I am Shashank, a software engineer with a strong passion for C programming, system architecture, and network protocols. My journey into open-source development began with a desire to understand how massive, distributed systems operate under the hood.

During this Outreachy contribution phase, I initially focused on Git's core libification and option-parsing APIs, which allowed me to get comfortable modifying Git's C structs and internal memory management. However, my true interest lies in network optimization. Diving into Git's GIT_TRACE2 engine to map out how partial clones communicate with promisor remotes convinced me that the "Implement promisor remote fetch ordering" project is exactly where I want to focus my 13-week internship.

Past experience with git --------------------------------

I have been using Git extensively for version control in my personal projects. This contribution period was my first time engaging directly with a mailing list-based open-source community.

Learning to use git send-email and GitGitGadget to format patches, manage versioned rerolls (v1, v2), and incorporate maintainer feedback has been a massive learning curve, but a highly rewarding one. I learned the importance of atomic commits, clean commit messages, and the strict rules around not ignoring Git's exit codes in shell scripts.

Contribution to the git community --------------------------------------------

Microprojects:

1.  t0081: modernize the code testing whether a file exists
     Link: https://lore.kernel.org/git/pull.2254.git.1791962806807.gitgitgadget@gmail.com/
     This patch series was integrated into master via
githttps://github.com/git/git/commit/e1bb515788e48d500c9d4e36f13c66c4daddd3d4

2.  t2403: modernize test for directory existence
      Link: https://lore.kernel.org/git/pull.2259.git.1792125111461.gitgitgadget@gmail.com/
      This patch series was integrated into seen via
https://github.com/git/git/commit/c645a5db002ded161115dc8f6c15a40acfdde2b2

3. prune-packed: remove use_the_repository_variable
    Link :https://lore.kernel.org/git/pull.2266.git.1792341073005.gitgitgadget@gmail.com/
    This patch series was integrated into next via
https://github.com/git/git/commit/936609cfa0a57e1b047c345a91fec79ab255897c

4. test-chmtime: use parse_options() to parse command-line flags
    Link: https://lore.kernel.org/git/pull.2280.git.1793099688076.gitgitgadget@gmail.com/
    This patch series was integrated into seen via
https://github.com/git/git/commit/c6a318cc4b8c6f6ce1a403e497816cd195c57cf7

Project Overview: Promisor Remote Fetch Ordering ---------------------------------------------------------------------- When a Git repository is configured as a partial clone with multiple promisor remotes, there is currently no defined mechanism to specify the order in which these remotes should be queried for missing objects.

Different remotes have vastly different performance characteristics and bandwidth costs. Currently, Git relies on a hardcoded fallback system rather than deterministic priority. This project aims to implement a flexible fetch ordering mechanism by introducing a client-side configuration list (promisor.fetchOrder) and a server-side advertisement extension via Git Protocol v2, allowing servers to broadcast their preferred fetch order.

Phase 0: Baseline & Trace2 Playground Verification ---------------------------------------------------------------------- Before designing the protocol enhancements, I established a verifiable baseline by building a local partial clone playground with multiple dummy promisor remotes (server-A and server-B).

To prove the telemetry, I forced a lazy fetch by requesting a missing object (file2.txt) and captured the transaction using GIT_TRACE2_EVENT.

- Verification: I successfully extracted the
{"key":"fetch_count","value":"1"} data event and the specific
child_start subprocess (["git","fetch","origin"...]) proving which
remote Git communicated with first.

The Current Baseline (Ordering Rules): Git currently lacks a deterministic, user-configurable fetch order for multiple promisor remotes. Based on my trace testing and codebase review, the baseline behavior is:

- By default, Git iterates through configured remotes in the order
they are stored/parsed when attempting to fetch missing objects.

- The remote configured via core.partialClone (usually origin) is
treated strictly as a fallback and is checked last.

- If a remote fails, Git moves to the next available promisor remote
until the missing object is found or all remotes are exhausted.

Internship Plan and 13-Week Timeline ---------------------------------------------------

Pre-Internship (Now – Dec 6) ----------------------------------------- Finish resolving feedback on my test-chmtime.c (v2) and prune-packed.c patches.Study the promisor-remote.c sorting algorithms and Git Protocol v2 documentation.

Weeks 1–2 (Dec 7 – Dec 20): Phase 1 - Visibility and Baseline
-------------------------------------------------------------------------------------
Goal: Document and lock in Git's current behavior to act as a safety net.

Tasks: Submit a docs-only upstream patch defining the current fallback
rules (accepted before configured, partialClone last, fallback on
failure). Develop automated tests utilizing GIT_TRACE2 to definitively
lock in and prove the current sequential fetch order.

Weeks 3–5 (Dec 21 – Jan 10): Phase 2 - Client-Side Ordering
------------------------------------------------------------------------------------
Goal: Implement local configuration for promisor remote priorities.

Tasks: Introduce the promisor.fetchOrder configuration list. A list is
preferred over per-remote integers as it composes cleanly across
config files. Refactor internal sorting logic in promisor-remote.c to
reorder remotes based on this list before initiating lazy fetches.
Implement edge-case handling for unlisted remotes and preserve the
partialClone-last fallback rule.

Weeks 6–9 (Jan 11 – Feb 7): Phase 3 - Server-Advertised Order
--------------------------------------------------------------------------------------
Goal: Extend Protocol v2 to allow servers to broadcast their preferred priority.

Tasks: Draft an RFC proposing the protocol v2 explicit priority=<n>
fields. Implement server-side advertisement gated by a new
promisor.sendFields configuration. Implement the client-side parser,
strictly adhering to the "ignore unknown fields" rule to maintain
backward compatibility.

Weeks 10–12 (Feb 8 – Feb 28): Phase 4 - Upstreaming & Precedence
-----------------------------------------------------------------------------------------------
Goal: Secure mailing list approval and resolve precedence rules.

Tasks: Settle precedence conflicts (Recommendation: local client
config maintains absolute authority, while the server's advertised
order sorts unranked remotes). Split Phase 2 and Phase 3 into a clean,
reviewable patch series. Route through at least two rounds of mailing
list review.

Week 13 (Mar 1 – Mar 8): Polish & Stretch Goals
-------------------------------------------------------------------
Goal: Finalize documentation and explore dynamic caching.

Tasks: Write final release notes and user-facing documentation.
Stretch Goal: Implement runtime memory of failed remotes within a
single process to skip them on subsequent lazy fetches to reduce
latency. Submit final Outreachy report.

Availability ------------------ I can commit 40 hours a week to the project during the internship. I am based in India (IST, UTC+5:30) and can adjust my hours for synchronous calls, pair programming, and mailing list reviews to overlap with my mentors' timezones.

Blogging ------------- I will document my technical journey, posting weekly updates on the C-level challenges I face, how I navigate network tracing, and the feedback I receive from the Git community. I will share each post on the mailing list.

After the Internship --------------------------- After the internship, I intend to remain an active contributor to the Git core project. Having touched the libification, option parsing, and network protocol subsystems during my application, I want to continue bridging these areas—specifically helping remove the remaining USE_THE_REPOSITORY_VARIABLE macros from network-facing C files like promisor-remote.c.

Appreciation ------------------- I want to express my gratitude to Usman Akinyemi, Junio C Hamano, Kaartic Sivaraam, Patrick Steinhardt and Cynthia Uche. Your patience in reviewing my early patches and helping me understand the git send-email workflow has been incredible. Thank you for making this community so welcoming.

Thank you .

On Wed, 4 Nov 2026 at 15:56, Shashank S <shashu8660@gmail.com> wrote:

I am sending a quick follow-up to correct a typo in the CC line for Kaartic, and to fix the links to my microprojects from my proposal (the URLs were accidentally joined with the text in my previous email).

https://github.com/git/git/commit/e1bb515788e48d500c9d4e36f13c66c4daddd3d4

Hello mentors and Git community,

This is version 2 of my 13-week project proposal for the "Implement promisor remote fetch ordering" project for the December 2026 Outreachy internship.

Changes since v1:
- Fixed a typo in Kaartic Sivaraam's email address in the CC line.
- Fixed broken/merged URLs in the "Contributions to the Git Community" section.
- Included the full text of the proposal inline below for easier
reading on the mailing list.

I would appreciate any feedback from the community.

Personal Information
====================
Full Name: Shashank S Mogaveera
Email: shashu8660@gmail.com
GitHub: https://github.com/shashu8660
Location: Kundapur, Karnataka, India (IST, UTC+5:30)

About Me ======== I am Shashank, a software developer with a strong passion for C programming, system architecture, and network protocols. My journey into open-source development began with a desire to understand how massive, distributed systems operate under the hood.

During this Outreachy contribution phase, I initially focused on Git's core libification and option-parsing APIs. However, my true interest lies in network optimization. Diving into Git's GIT_TRACE2 engine to map out how partial clones communicate with promisor remotes convinced me that the "Implement promisor remote fetch ordering" project is exactly where I want to focus my 13-week internship.

Past Experience with Git ======================== I have been using Git extensively for version control in my personal projects. This contribution period was my first time engaging directly with a mailing list-based open-source community.

Learning to use git send-email and GitGitGadget to format patches, manage versioned rerolls, and incorporate maintainer feedback has been a massive learning curve, but a highly rewarding one. I learned the importance of atomic commits, clean commit messages, and the strict rules around not ignoring Git's exit codes in shell scripts.

Contributions to the Git Community ==================================

1. t0081: modernize the code testing whether a file exists
   Link: https://lore.kernel.org/git/pull.2254.git.1791962806807.gitgitgadget@gmail.com/
   Status: Merged to master.
   Commit: https://github.com/git/git/commit/e1bb515788e48d500c9d4e36f13c66c4daddd3d4

2. t2403: modernize test for directory existence
   Link: https://lore.kernel.org/git/pull.2259.git.1792125111461.gitgitgadget@gmail.com/
   Status: Merged to seen.
   Commit: https://github.com/git/git/commit/c645a5db002ded161115dc8f6c15a40acfdde2b2

3.  prune-packed: remove USE_THE_REPOSITORY_VARIABLE
   Status: Reviewed and marked ready for integration by Patrick Steinhardt.
   Description: I refactored the C file to pass a struct repository *r
pointer through a void *cb_data callback API, successfully removing
the reliance on Git's global state variables.

4.  test-chmtime: use parse_options() to parse command-line flags
   Status: v2 submitted.
   Description: I ported ad-hoc command-line argument scanning to
Git's official C-level parse_options() API, handling edge cases for
relative time offsets, and added t0082-test-chmtime.sh.

Project Overview: Promisor Remote Fetch Ordering ================================================ When a Git repository is configured as a partial clone with multiple promisor remotes, there is currently no defined mechanism to specify the order in which these remotes should be queried for missing objects.

Different remotes have vastly different performance characteristics and bandwidth costs. Currently, Git relies on a hardcoded fallback system rather than deterministic priority. This project aims to implement a flexible fetch ordering mechanism by introducing a client-side configuration list (promisor.fetchOrder) and a server-side advertisement extension via Git Protocol v2, allowing servers to broadcast their preferred fetch order.

Phase 0: Baseline & Trace2 Playground Verification ================================================== Before designing the protocol enhancements, I established a verifiable baseline by building a local partial clone playground with multiple dummy promisor remotes (server-A and server-B).

To prove the telemetry, I forced a lazy fetch by requesting a missing
object and captured the transaction using GIT_TRACE2_EVENT.
* Verification: While the promisor.fetch_count=1 data event simply
confirmed a lazy fetch was triggered, extracting the sequential
child_start subprocess events (e.g., ["git","fetch","cache-a"...])
provided the definitive proof of Git's remote routing order.

The Current Baseline (Ordering Rules): Git currently lacks a
deterministic, user-configurable fetch priority system. Based on my
trace testing, t5710, and the logic in promisor-remote.c, the current
hardcoded fallback hierarchy is:
1. Git first tries "accepted" remotes (server-advertised remotes that
were provided to the client during a previous operation).
2. It then iterates through ordinary configured remotes in the order
they are stored/parsed.
3. The remote configured via extensions.partialClone (usually origin)
is treated strictly as a fallback and checked last.

If a remote fails, Git moves to the next available promisor remote in this hierarchy until the missing object is found or all remotes are exhausted.

Internship Plan and 13-Week Timeline ==================================== The internship runs from 7 December 2026 to 8 March 2027.

Weeks 1–2 (Dec 7 – Dec 20): Phase 1 - Visibility and Baseline
- Goal: Document and lock in Git's current behavior to act as a safety net.
- Tasks: Submit a docs-only upstream patch defining the current
fallback rules (accepted before configured, extensions.partialClone
last, fallback on failure). Develop automated tests utilizing
GIT_TRACE2 to definitively lock in and prove the current sequential
fetch order.

Weeks 3–5 (Dec 21 – Jan 10): Phase 2 - Client-Side Ordering
- Goal: Implement local configuration for promisor remote priorities.
- Tasks: Introduce the promisor.fetchOrder configuration list. A list
is preferred over per-remote integers as it composes cleanly across
config files. Refactor internal sorting logic in promisor-remote.c to
reorder remotes based on this list before initiating lazy fetches.
Implement edge-case handling for unlisted remotes and preserve the
extensions.partialClone-last fallback rule.

Weeks 6–9 (Jan 11 – Feb 7): Phase 3 - Server-Advertised Order
- Goal: Extend Protocol v2 to allow servers to broadcast their
preferred priority.
- Tasks: Draft an RFC proposing the protocol v2 explicit priority=<n>
fields. Implement server-side advertisement gated by a new
promisor.sendFields configuration. Implement the client-side parser,
strictly adhering to the "ignore unknown fields" rule to maintain
backward compatibility.

Weeks 10–12 (Feb 8 – Feb 28): Phase 4 - Upstreaming & Precedence
- Goal: Secure mailing list approval and resolve precedence rules.
- Tasks: Settle precedence conflicts (Recommendation: local client
config maintains absolute authority, while the server's advertised
order sorts unranked remotes). Split Phase 2 and Phase 3 into a clean,
reviewable patch series. Route through at least two rounds of mailing
list review.

Week 13 (Mar 1 – Mar 8): Polish & Stretch Goals
- Goal: Finalize documentation and explore dynamic caching.
- Tasks: Write final release notes and user-facing documentation.
Stretch Goal: Implement runtime memory of failed remotes within a
single process to skip them on subsequent lazy fetches to reduce
latency. Submit final Outreachy report.

Availability ============ I can commit 40 hours a week to the project during the internship. I am based in India (IST, UTC+5:30) and can adjust my hours for synchronous calls, pair programming, and mailing list reviews to overlap with my mentors' timezones.

Blogging ======== I will document my technical journey , posting weekly updates on the C-level challenges I face, how I navigate network tracing, and the feedback I receive from the Git community. I will share each post on the mailing list.

After the Internship ==================== After the internship, I intend to remain an active contributor to the Git core project. Having touched the libification, option parsing, and network protocol subsystems during my application, I want to continue bridging these areas—specifically helping remove the remaining USE_THE_REPOSITORY_VARIABLE macros from network-facing C files like promisor-remote.c.

Appreciation ============ I want to express my gratitude to Christian Couder, Usman Akinyemi, Siddharth Asthana, Kaartic Sivaraam, Patrick Steinhardt, and Junio C Hamano. Your patience in reviewing my early patches and helping me understand the git send-email workflow has been incredible. Thank you for making this community so welcoming.

Thank you

Shashank S Mogaveera

Thanks for your proposal, do not forget to submit your application on the Outreachy website.

Thanks.