[Outreachy] Project Proposal [v3]: Implement promisor remote fetch ordering
- From
- Shashank S <shashu8660@gmail.com>
- Date
- Nov 6, 2026, 13:18 UTC
- Message-ID
- <CANHmUQQvN0xQuXqTE2imochXyQuU_ag3KHb0gkGEZ-cPLFbBYg@mail.gmail.com>
Hello mentors and Git community,
This is my revised proposal for the “Implement promisor remote fetch ordering” project for the December 2026 Outreachy internship.
Changes since v2:
- Corrected my description of the current behavior: it is deterministic, but it has no separately user-configurable ordering mechanism.
- Reduced the focused Phase 1 implementation work to three days, with review continuing asynchronously while the RFC discussion begins.
- Removed my pre-selected commitment to promisor.fetchOrder; the configuration shape will be decided through an early mailing-list RFC.
- Corrected my description of promisor.sendFields: it already exists. The project may extend the existing optional-field mechanism with an ordering-related field, subject to RFC consensus.
-Added technical risks, design criteria, and explicit coordination with active upstream work.
- Updated contribution status and restored mailing-list links.
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 a software developer interested in C programming, distributed systems and network-facing infrastructure.
During the Outreachy contribution period, I contributed to Git’s test, option-parsing, and repository-libification work. Studying partial clones,the promisor-remote protocol, and Trace2 traces of lazy fetching showed me how a missing object travels from object lookup to a git fetch subprocess. That made promisor remote fetch ordering the project I most want to pursue.
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
Mailing-list thread:
https://lore.kernel.org/git/pull.2254.git.1791962806807.gitgitgadget@gmail.com/
Status: Merged to master.
Commit:
https://github.com/gitgitgadget/git/commit/e1bb515788e48d500c9d4e36f13c66c4daddd3d42. t2403: modernize test for directory existence
Mailing-list thread:
https://lore.kernel.org/git/pull.2259.git.1792125111461.gitgitgadget@gmail.com/
Status: Merged into the seen integration branch.
Commit:
https://github.com/git/git/commit/c645a5db002ded161115dc8f6c15a40acfdde2b23. prune-packed: remove USE_THE_REPOSITORY_VARIABLE
Mailing list thread:
https://lore.kernel.org/git/pull.2266.git.1792341073005.gitgitgadget@gmail.com/
Status: “Will merge to master” according to “What’s cooking”.
Commit :
https://github.com/git/git/commit/936609cfa0a57e1b047c345a91fec79ab255897c4. test-chmtime: use parse_options() to parse command-line flags
Mailing list thread:
https://lore.kernel.org/git/pull.2280.git.1793099688076.gitgitgadget@gmail.com/
Status: Merged into the seen integration branch.
Commit :
https://github.com/git/git/commit/c6a318cc4b8c6f6ce1a403e497816cd195c57cf7Project Overview: Promisor Remote Fetch Ordering ----------------------------------------------------------------------
Git can lazily fetch missing objects from multiple promisor remotes in a partial clone. Today, Git uses a deterministic baseline order: accepted server-advertised remotes are tried first, other configured promisor remotes follow configuration order, and the `extensions.partialClone` remote is tried last. However, users cannot explicitly configure that order, and servers cannot provide a separate ordering preference for clients to combine with local policy.
This project will design and implement a configurable ordering mechanism for promisor remotes. The client-side configuration shape and any protocol-v2 advertisement format will be decided through mailing-list RFC discussion, with attention to backward compatibility, local-versus-server precedence, and safe handling of invalid data.
Phase 0 Progress: -------------------------
I completed the relevant onboarding work before the internship.
Build and test verification:
I built Git from source on macOS. The resulting binary reports: [git version 2.56.GIT]
I ran the two relevant test scripts:
- t5710-promisor-remote-capability.sh reported all 33 tests passed. - t0410-partial-clone.sh reported all 39 tests passed. Its loca Apache-based web-server setup was skipped because Apache could not access its configuration path on my macOS setup.
Multi-promisor-remote playground:
I created local origin, cache-a, and cache-b repositories, configured them as promisor remotes, and created a blob:none partial clone with no-checkout. This ensured that the commit and tree were present locally while the content of bar remained absent.
I then accessed HEAD:bar with GIT_TRACE2_EVENT enabled.
With extensions.partialClone=origin, the Trace2 child_start event showed:
- git fetch cache-a ...
This demonstrated that Git tried cache-a before origin.
In a second fresh clone, I configured cache-a with an unavailable URL.
Trace2 showed:
- git fetch cache-a ... - git fetch cache-b ..
Git then fetched the missing blob successfully from cache-b; it did not need to contact origin.
The Trace2 event promisor.fetch_count records the number of object IDs passed to each promisor-fetch subprocess. It does not identify the selected remote. I therefore used child_start events to establish remote order.
Current behavior and code understanding:
I studied - 1. [https://git-scm.com/docs/partial-clone] 2. [https://git-scm.com/docs/gitprotocol-v2] 3. t/t5710-promisor-remote-capability.sh 4. t/t0410-partial-clone.sh 5. promisor-remote.c.
The current behavior is deterministic but has no separately configurable priority mechanism:
1. lazy_fetch_objects() first calls try_promisor_remotes() for remotes accepted through the promisor-remote protocol exchange. 2. It then calls the same helper for remaining configured promisor remotes, whose order comes from configuration parsing order. 3. promisor_remote_init() moves the remote named by extensions.partialClone to the tail of the list 4. If a fetch fails, Git continues with another eligible promisor remote until all requested objects are present or no remotes remain.
My manual Trace2 experiment verifies configured-remote order and fallback. I will not claim it independently proves accepted-remotes-first behavior that rule is covered by the protocol test and code path above.
Design Questions and Initial Reasoning: -----------------------------------------------------
I do not consider the design settled before mailing-list discussion. My initial analysis identifies the following questions.
Client configuration shape:
The RFC will compare:
- an ordered list, such as promisor.fetchOrder; and - a per-remote numeric value, such as remote <name>.promisorPriority.
A list makes the intended sequence easy to read in one place, but must define how values from system, global, and repository configuration compose. A numeric value can change one remote without naming every other remote, but requires tie-breaking and a clear convention for unranked remotes.
The RFC will evaluate both approaches using the same criteria:
- configuration layering and overrides; - duplicate entries or equal priorities; - unlisted remotes; - nonexistent or non-promisor remote names; - interaction with accepted remotes; and - interaction with extensions.partialClone.
I will not select an implementation representation until consensus on these semantics is reached.
Server-advertised ordering
promisor.sendFields already exists. It controls optional fields sent in a promisor-remote advertisement; currently supported fields include partialCloneFilter and token.
The protocol RFC will compare two possible designs:
1. advertisement order itself expresses server preference or 2. the server advertises an explicit ordering-related field, such as a numeric priority.
An explicit field may preserve the server’s intent even if a client later reorders remotes, but it adds parsing, validation, and documentation work. Advertisement order is simpler on the wire, but may be less explicit once a client combines local and server information.
If the RFC selects a new field, the implementation will extend the existing promisor.sendFields machinery, the promisor-remote parser, protocol documentation, and tests. Older clients must safely ignore the unknown field.
Precedence and persistence:
My starting principle for discussion is that an explicit local client policy should not be silently overridden by a server, because clients may have their own cost, reliability, or privacy constraints. One possible policy is for server preference to order only remotes that have no explicit local ranking.
This is a proposal for discussion, not a fixed decision. The RFC must settle:
- whether local order applies across the accepted/unaccepted two-pass split or only within each group; - whether extensions.partialClone remains last even when explicitly ranked; - whether server-provided ordering is stored through the existing promisor.storeFields mechanism; and - whether a stored ordering value remains valid after later local configuration changes.
Implementation Risks:
The remote list is a singly linked list, and current lazy fetching makes two passes over it: accepted remotes, then remaining configured remotes. A refactor must preserve this behavior until a reviewed semantic decision changes it.
Configuration parsing is also part of the feature design . A change must not make effective order depend accidentally on an implementation details of config file loading, or make invalid remote names fatal during lazy fetching.
If the protocol RFC chooses a numeric field , parsing must reject malformed and overflowing values safely . If it chooses advertisement order , tests must still define exactly how the client combines that order with local policy.
Finally, active patches may land before or during the internship. I will inspect active threads and current branches before beginning each patch, avoid duplicating work, and adapt the plan with mentor guidance.
13-Week Internship Plan:
Week 1: Baseline visibility and safety net
The focused baseline implementation work should take approximately three days, not two weeks. Review can continue in parallel after patches are sent.
Days 1–3:
- Audit current master, next, seen, and active mailing-list threads. - Confirm which documentation and test coverage has already landed or is in review; do not duplicate another contributor’s work. - Where a baseline gap remains, prepare a small docs or test patch that documents or asserts existing behavior only accepted remotes first, configured remotes in configuration order, extensions.partialClone last, and fallback after failure. - Send the patch early and respond to review.
Days 4–7:
- Begin the client-configuration RFC preparation. - Refine examples and edge cases from the local playground. - Continue responding to any Week 1 patch review.
Week 2: Client-ordering RFC
- Send an RFC to the mailing list comparing list and numeric-priority designs. - Ask for agreement on configuration layering, invalid entries, unranked remotes, accepted-remotes interaction, and extensions.partialClone. - Revise the proposed semantics from reviewer feedback before beginning a behavior-changing implementation.
Weeks 3–4: Client-side implementation
After agreement on the RFC direction:
- Separate any behavior-preserving list-management refactor from the configuration behavior change. - Implement the agreed local configuration parser and ordering logic. - Preserve existing behavior for users without the new configuration. - Add tests for empty configuration, duplicate values, unknown names, unranked remotes, accepted-remotes interaction, and the agreed extensions.partialClone behavior. - Update the appropriate configuration documentation: Documentation/config/promisor.adoc Documentation/config/remote.adoc - Send the first coherent client-side patch series no later than the end of Week 4, and preferably earlier if it is ready.
Week 5: Client-side review and protocol RFC preparation
- Respond to review and send rerolls of the client-side series. - Write protocol specification wording before implementation. - Prepare examples demonstrating both explicit-field and advertisement-order designs. - Identify exactly what must change in promisor.sendFields, promisor.checkFields, and promisor.storeFields if a new field is selected.
Week 6: Protocol RFC and discussion
- Send the protocol RFC to the mailing list. - Discuss the field format or advertisement-order semantics, client/server precedence, malformed data handling, backward compatibility, and persistence. - Incorporate review before writing server or client protocol code.
Weeks 7–8: Server advertisement and client parsing
After protocol agreement:
- Extend the server-side optional-field support to advertise the agreed ordering information. - Extend the client parser to recognize and validate that information. - Keep old-client behavior safe through the existing unknown-field rule. - Implement the agreed precedence rule between local configuration and server information. - Implement persistence through promisor.storeFields only if that behavior is approved in the RFC.
Week 9: Protocol tests and first server-side series
- Add protocol-v2 tests covering valid advertisements, absent fields, malformed values, ignored unknown fields, client-versus-server precedence, and old-client compatibility. - Extend the relevant tests in t5710-promisor-remote-capability.sh. - Send the first coherent protocol/server-side patch series for review.
Weeks 10–11: Review and rerolls
- Respond promptly to review on both series. - Keep rerolls small and explain changes with range-diffs where useful. - Run focused tests after each revision and wider test coverage before resubmission. - Run leak-sanitizer testing where supported by the development environment. - Keep documentation and tests synchronized with reviewer-approved semantics.
Week 12: Stabilization and integration readiness
- Recheck all configuration, protocol, and partial-clone documentation. - Run the relevant test scripts and broader regression tests. - Reproduce the key Trace2 scenarios manually to confirm the tested behavior. - Address remaining review comments and prepare patches for maintainer integration. The decision to advance a topic through seen, next, or master remains with maintainers.
Week 13: Final polish and wrap-up
- Finalize release-note and user-facing documentation updates, if appropriate. - Publish the final internship report and a concise technical summary. - Use any remaining time only for follow-up fixes or review; dynamic latency-based reordering and in-process failure memory remain stretch work, not commitments.
Availability
I can commit 40 hours per week exclusively to this project throughout the internship period. I have no university exams, classes, other jobs, or planned vacations that conflict with 7 December 2026 through 8 March 2027.
I am based in IST (UTC+5:30) and can adjust my hours for synchronous discussion, pair programming, and timely mailing-list replies.
Communication and Long-Term Contribution
I will publish concise weekly updates covering experiments, RFC decisions, patches, review feedback, and next steps. I will remain active on the mailing list and will communicate early if a schedule or technical risk affects the plan.
After the internship, I intend to continue contributing to Git, especially in promisor-remote and repository-libification work, including reducing remaining unnecessary reliance on global repository state.
Thank you
Shashank S Mogaveera