{"thread":{"id":"66783","subject":"[Outreachy][Proposal]: Reduce Git's global state to enable Git's libification","startedAt":"2026-11-05T12:03:59Z","lastAt":"2026-11-05T12:03:59Z","messageCount":1,"participants":["Srujith Poojary"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"557538","messageId":"CABh_KWjbEGaf33n-qKJDC+-cipfMvzUm6=mwDuV5s7yEYBL5dg@mail.gmail.com","threadId":"66783","inReplyTo":null,"subject":"[Outreachy][Proposal]: Reduce Git's global state to enable Git's libification","fromName":"Srujith Poojary","fromEmail":"poojarysrujith@gmail.com","sentAt":"2026-11-05T12:03:59Z","receivedAt":"2026-11-05T12:03:59Z","isPatch":false,"sender":{"key":"poojarysrujith@gmail.com","avatar":null},"body":"Hello Git community,\n\nI am sharing my draft proposal for the December 2026 Outreachy\ninternship. I would appreciate your feedback and suggestions.\n\n# About Myself\n\nI am from Karnataka India [UTC+05:30 (IST)]. As a BCA(Bachelor of\nComputer  Application) Graduate.I have a good foundation of\nprogramming and have worked with some programming languages.I have\npractical knowledge developing own software projects and contributing\nto open source projects.while learning how to use Git and GitHub for\nversion control and managing changes in my projects it became\ninterested in using different publicly available open source\nrepositories. This led me to become curious about how Git works\ninternally, How its source code is structured, and how its developers\nkeep such a huge project going.\n\nThis pushed me to look into the source code of Git. I learned about\nthe C concepts that are needed to understand the code such as\npointers, structures, functions and looking at how the different parts\ncode communicates with itself. I looked into the Git code related to\nrepositories and learned about concepts such as the_repository, struct\nrepository \\*repo, global state and explicit dependencies. This taught\nme that when contributing to a well established open source project\nthere is more to it than just writing code. You need to understand the\nexisting functionality, look at past changes and ensure that the code\nis tested properly.\n\nI made some contributions while preparing for this project. I made\nchanges to test scripts, test-path and safe integer arithmetic in\ndiff-delta. I worked on a submodule-related change involving\nrepository-specific commit abbreviations and made an updated patch\nseries for review. I gained practical experience of looking at\nexisting code, creating patches, testing and getting my code reviewed.\n\nWhen i got to know about this project is while watching videos on\nYouTube about Git and contributing to open source projects I\ndiscovered Outreachy. I submitted my initial application and looked\nthrough the list of projects available. I found the Git project,\n'Reduce Git's global state to enable Git's libification'. As I was\nalready interested in Git and GitHub and had begun learning about C\nprogramming, I decided to choose this project as it fit my interests.\nI began preparing for this project by completing the microproject,\nlooking at Git's source code, looking into past changes and\nresearching potential areas to contribute to for my main project.\n\nI am interested to involved with this Outreachy internship project for\nDecember 2026 as it will give me the opportunity to understand and\ncontribute to a key part of Git's internal design. I am interested in\nunderstanding how to replace implicit dependencies on global state by\npassing the required repository or index information explicitly. I\nwould like to learn how this can help make the code more testable,\nmaintainable and reusable.\n\nI hope to boost my C programming and problem solving skills during\nthis internship. I hope to make useful and thoroughly tested changes\nto Git. I am happy to look into the existing implementation, talk to\nmaintainers, learn from code reviews and improve my work using\ntechnical feedback and collaboration with community.\n\n## 2. My understanding about Project\n\n### 2.1 What is Git's global state?\n\nwhile looking  Gits source code,I learnt that global state is\ninformation that different parts of program can acces without\nreceiving it directly as an argument.This can be useful,But it can\nalso hide what a function depends on so.\n\nex: In Git is `the_repository`.It is a global pointer to `struct\nrepository` object.Code can use it to access information about the\ncurrent repository. For example, `the_repository->index` gives access\nto that repository's index.\n\nThe problem came here is a function may appear to need only the\narguments shown in its definition, while it also gets important\ninformation from a global variable. That makes the dependency less\nobvious. It can also make it harder to test the function with a\ndifferent kind of repository or index. This is the kind of dependency\nI am interested in understanding and reducing in the pathspec code.\n\n### 2.2 What does libification mean?\n\nI understood libification makes Gits internal code easier for other\nprograms to use as a software library,rather than only using it\nthrough Git's command-line programs.\n\nOne problem is that some Git functions rely on global information like\n`the_repository`. A function that gets information this way may be\nharder to use when another program needs to work on a particular\nrepository or when more than one repository is involved.\n\nOne way to reduce this hidden dependency is to pass the information\nthe function needs as an argument. ex: a function can receive a\n`struct repository \\*repo` to work with a particular repository, or a\n`struct index_state \\*istate` to work with a particular index.\n\nThis helps the function's dependencies clearer and can make it easy to\ntest and reuse. I understand that passing repository or index\ninformation explicitly is only one part of libification; other parts\nof Git may need further changes as well.\n\n### 2.3 What has already been done?\n\nI discovered while looking at source code Git developers have been\nworking to reduce global state. Two important structures used to store\nrepository-specific information are repo_config_values and\nrepo_settings.\n\nex: I looked at was `core.attributesFile`. Previously this was stored\nin a global variable called `git_attributes_file`. When multiple\nrepositories are used in the same process, one repository's\nconfiguration could overwrite the value used for another repository.\nThis was refactored so that the value could be stored in the\nattributes_file member of repo_config_values.\n\nAnother ex:I looked at was `core.hooksPath`. Previously this was\nstored in a global variable called `git_hooks_path`. This could cause\nproblems when multiple repositories used different paths for their\nhooks in the same process. This was then refactored to store the value\nin struct repo_settings. A function called\nrepo_settings_get_hooks_path() was also introduced to load and cache\nthe value for the required repository. These research helped me to\nunderstand how Git uses various repository specific structures to\nreduce global state.\n\nIn Google Summer of Code 2026 there was a project called \"Refactoring\nin order to reduce Git's global state\". This aimed to reduce global\ndependencies by refactoring Git's environment handling and moving\nselected values into appropriate repository-specific structures,\nincluding repo_config_values. Some examples of these values include\n`protect_hfs`, `protect_ntfs`, `trust_executable_bit`, `ignore_case`,\n`excludes_file` and various program settings.\n\nThis work provides useful context for the current Outreachy project.\nThe earlier refactoring focused on reducing global state in Git's\nenvironment and configuration handling. The current project takes the\nbroader goal further by looking at how parts of Git can become\nsuitable for use as a library. My proposed pathspec investigation is a\npossible contribution to that ongoing effort, rather than a claim that\npathspec work was assigned or approved by the earlier GSoC mentors.\n\nIn the v2.56 release notes for Git there are several examples of\nchanges made to reduce global dependencies. These include functions in\n`copy.c` being modified to take a repository argument, the use of\nrepository aware versions of the tempfile and lockfile APIs. Parts of\nthe refspec API were changed to remove their dependency on the global\nthe_repository by passing the hash algorithm explicitly. And\nrepository pointers are passed in ref and worktree related functions.\n\nOverall from looking at these changes, it seems(i'm assuming not sure)\nthat reducing global state is a continuous process. As developers need\nto understand what each value is used for, and find the correct\nrepository/structure to store them in. Some of the information will\nneed to be made explicit. The December 2026 Outreachy project\ncontinues this larger effort by making Git's internal code more\nsuitable for libification while maintaining its existing behaviour.\n\n## 3. Previous Contributions and Preparation\n\n### 3.1 Contributions to Git\n\nWhile preparing for this project, I contributed to Git. I became\nfamiliar with reading code, finding issues, and making and testing\nchanges based on feedback from maintainers.\n\n| Contribution | Pull Request and mailing-list discussion | Status as\nof 5 November 2026 |\n|---|---|---|\n| Avoid pipes in the `t0001-init.sh` test script | [PR\n#2260](https://github.com/gitgitgadget/git/pull/2260); [v2\nmailing-list discussion](https://lore.kernel.org/git/pull.2260.v2.git.1792666211685.gitgitgadget@gmail.com)\n| Integrated into `next`. A later mailing-list status update says it\nwill merge to `master`. The GitHub PR remains open and is not marked\nas merged. |\n| Modernize test path checks in `t2030` | [PR\n#2256](https://github.com/gitgitgadget/git/pull/2256); [v3\nmailing-list discussion](https://lore.kernel.org/git/pull.2256.v3.git.1792299943380.gitgitgadget@gmail.com)\n| Integrated into `seen`. The GitHub PR remains open; the latest\nrecorded status update says it needs review. |\n| Use safe integer arithmetic in `diff-delta` | [PR\n#2276](https://github.com/gitgitgadget/git/pull/2276); [v9\nmailing-list discussion](https://lore.kernel.org/git/pull.2276.v9.git.1793120160248.gitgitgadget@gmail.com)\n| Integrated into `seen`. The GitHub PR remains open; the latest\nrecorded status update says it needs review. |\n| Use the submodule repository for commit abbreviations | [PR\n#2288](https://github.com/gitgitgadget/git/pull/2288); [v6\nmailing-list submission](https://lore.kernel.org/git/pull.2288.v6.git.1793821554097.gitgitgadget@gmail.com);\n[v6 commit](https://github.com/git/git/commit/01c3cc25738c43d61aff153805e02db872ff21de)\n| v6 was submitted on 4 November 2026. The GitHub PR remains open. The\nlatest status information available for v6 does not show maintainer\nacceptance or integration. The focused\n`t4041-diff-submodule-option.sh` tests passed 48/48 with both SHA-1\nand SHA-256. |\n\nIntegration into `next` or `seen` is part of Git's review process and\ndoes not mean that a GitHub PR has been merged into `master`. All four\nGitHub PRs remain open and are not marked as merged as of 5 November\n2026.\n\n### 3.2 Source-code preparation\n\nI looked at different area of Git source code, which includes\nincluding `repository.c`, `repository.h`, `environment.c`, `alias.c`,\n`alias.h` and `builtin/help.c`. I also read the Git v2.56.0 release\nnotes to see what had changed recently in the effort to reduce global\nstate.\n\nI investigated how `the_repository` is used as a global pointer to the\nmain repository structure. I also looked at how functions receive\nrepository pointers (`struct repository \\*repo`) as arguments to\naccess repository-specific information.\n\nI looked at `alias_lookup()` in `alias.c` and examined how it uses\n`the_repository`. This helped me understand that a function can\nreceive some information through its arguments while still relying on\nglobal state for other information.\n\nI also investigated `is_bare_repository()` and the changes made in\ncommit `7ff3a5895b`. The change separated the initial `--bare`\ncommand-line option from the repository-specific bare configuration.\nThis helped me understand why these different types of information\nneed to be stored separately.\n\nI became more familiar with commands such as `git grep`, `sed`, `git\nlog`, `git show` and `git diff`. I used them to locate functions,\nfollow the flow of code and understand changes between commits. This\nmade me more comfortable investigating the codebase and understanding\nhow global dependencies can be reduced.\n\nI also checked `init_pathspec_item()` in `pathspec.c`. This is a\nseparate area from the skip-worktree matching helper: it uses\n`the_repository` for repository-dependent path-prefix handling and\nerror reporting. This showed me that there may be other repository\ndependencies in pathspec processing, but they need to be assessed\nindividually. I have kept this as possible follow-up investigation\nrather than including it in the initial implementation scope.\n\n### 3.3 My knowledge about the project through case studies\n\nI Looked at two examples in Git to understand how global state has been reduced.\n\nFor `core.attributesFile`, I found that the value was previously\nstored in the global variable `git_attributes_file`. It was later\nmoved into the `attributes_file` member of `struct\nrepo_config_values`.\n\nFor `core.hooksPath`, the value was previously stored in the global\nvariable `git_hooks_path`. It was moved into `struct repo_settings`. A\nfunction called `repo_settings_get_hooks_path()` was also introduced\nto load and cache the value for the relevant repository.\n\nBy seeing at these changes helped me understand that reducing global\nstate involves deciding where information should be stored and how the\ncorrect repository should access it.\n\nI also looked at a more recent pathspec change, commit `dd674df326`\n(\"pathspec: use match for sparse-index expansion checks\"). This change\naddressed a heap-buffer-overflow involving prefixed wildcard pathspecs\nwith a sparse index. It changed the checks to use `item.match`, which\nincludes the path prefix, consistently instead of using\n`item.original`. This is relevant prior work because it shows that\npathspec changes involving prefixes and sparse indexes need careful\ncompatibility and memory-safety testing. My proposed helper\ninvestigation is separate from that change, and I will check for\noverlap rather than assume the work is related or already covered.\n\n## 4. Problem Identification and Proposed Contribution\n\n### 4.1 Why investigate pathspec?\n\nA pathspec can be used by Git commands to tells which files or paths\nto target. It can be used to find a specific file, directory or group\nof files using patterns.\n\nPathspecs are used by several Git commands such as `git add`, `git\nrm`, `git grep` and `git diff`.\n\nWhile watching how pathspecs are implemented in Git, I noticed that\nsome of the pathspec-processing functions use the global pointer\n`the_repository` to get information about the current repository. This\ncreates an implicit dependency.\n\nPathspec processing seems like a useful area to look for. Making\ndependencies on specific repositories or indexes explicit can help\nreduce global state and make the code more reusable in different\nrepository contexts.\n\n### 4.2 Current technical observation\n\nIn my examination on `pathspec.c`, I found that there is a function\ncalled `find_pathspecs_matching_skip_worktree()` that checks which\npathspecs match index entries marked with the skip-worktree flag or\nlocated outside the sparse-checkout area.\n\nThe function accesses the index via `the_repository->index`, but does\nnot accept it as a parameter. Instead, it uses the global pointer\n`the_repository`. This has created an implicit dependency on the\nglobal repository.\n\nOne possible improvement would be to pass a `struct index_state\n\\*istate` argument to the function. This would make the required index\nexplicit and allow the function to use the index supplied by its\ncaller.\n\nI investigated the inline wrapper for this function in `pathspec.h`.\nThis function is called `matches_skip_worktree()`, and calls\n`find_pathspecs_matching_skip_worktree()`. The wrapper also caches the\nmatching results so they can be reused on subsequent calls.\n\nAny change to the helper will also require reviewing and updating the\nwrapper and its callers.\n\n### 4.3 Current call-site investigation\n\nI checked the source code and found four call sites for\n`matches_skip_worktree()`: one in `pathspec.c`, two in\n`builtin/add.c`, and one in `builtin/rm.c`.\n\nEach of these callers will need to be considered when changing the\nhelper and wrapper interface. The caller must provide the appropriate\nindex state so that the function works with the intended repository.\n\nInterestingly, in `builtin/rm.c`, the `cmd_rm()` function has a\n`struct repository \\*repo` argument already. However, the variable is\nmarked as UNUSED. The surrounding code still refers to\n`the_repository` to get the index. Therefore this caller will need\nfurther investigation to determine how to pass the correct index.\n\nThe changes should only be made to the relevant helper, wrapper and\ncallers. We should not make any assumptions that by updating these\ncall sites it will mean that the `git add` or `git rm` command is now\nfree from global state.\n\n### 4.4 Proposed project objective\n\nI want to look into reducing a specific global repository/index\ndependency in Git's pathspec code.\n\nMy initial investigation focuses on\n`find_pathspecs_matching_skip_worktree()`, which currently obtains the\nindex through `the_repository->index` instead of receiving the index\nit should use as an argument.\n\nI will look to examine two possible API approaches:\n\n1\\. Keep the specialised helper and add an explicit `struct\nindex_state \\*istate` parameter. I would then review how this\nparameter should pass through the inline `matches_skip_worktree()`\nwrapper and its callers.\n\n2\\. Investigate whether the existing\n`find_pathspecs_matching_against_index()` API could be extended with\nanother `ps_skip_worktree_action` option to support the required\nmatching behaviour.\n\nI will compare these approaches by looking at the existing API design,\nthe effect on callers, whether the required matching behaviour can be\nrepresented clearly, and the amount of change each approach\nintroduces. I will discuss the findings with mentors and maintainers\nbefore selecting the implementation.\n\nI will also review the four identified call sites and determine which\nindex state each one should use. If the selected design and Git's test\ninfrastructure allow it, I will add a targeted regression test to\ncheck that the helper uses the index supplied by its caller and that\nexisting sparse-checkout behaviour is preserved.\n\nAfter this initial investigation and focused change, I may look into\nwhether other pathspec functions could also receive repository or\nindex information explicitly. Any further work will depend on the\ntechnical findings and feedback from Git maintainers.\n\nThe aim is to reduce the reliance of selected parts of Git's pathspec\ncode on global state while preserving existing behaviour.\n\n### 4.5 Scope boundaries\n\nI intend to keep my initial work focused on the identified global\nindex dependency in `find_pathspecs_matching_skip_worktree()` and the\nAPI changes needed to address it.\n\n**What I will do initially:**\n\n- Investigate the helper's reliance on `the_repository->index`.\n\n- Compare the two API approaches described in Section 4.4 before\nselecting an implementation.\n\n- Review the inline wrapper and the four identified call sites, and\ndetermine the correct index state for each caller.\n\n- Investigate and, if feasible, add a focused regression test for the\nselected implementation.\n\n- Test the changes to ensure existing skip-worktree and\nsparse-checkout behaviour is preserved.\n\n**What I may investigate as follow-up work:**\n\n- Depending on the initial findings and feedback from Git maintainers,\ninvestigate `init_pathspec_item()` and selected parsing functions.\n\n- Look into other pathspec functions only where there is a clear\nrepository/index dependency and a technically justified benefit to\nmaking it explicit.\n\n- Discuss any wider changes with mentors and maintainers before\nexpanding the scope.\n\n**What I will not promise as part of the initial contribution:**\n\n- Rewrite the whole pathspec subsystem.\n\n- Remove all global variables from Git.\n\n- Guarantee that `the_repository` will be completely removed from\npathspec functions.\n\n- Claim that Git will become fully thread-safe as a result of this change.\n\n- Make unrelated changes outside the agreed pathspec scope.\n\nI will aim to make a focused and well-tested contribution while\npreserving existing functionality. Any follow-up work will depend on\ntechnical justification and maintainer guidance.\n\n### 4.6 Feedback from Usman Akinyemi\n\nDuring proposal preparation, I received technical feedback from Usman\nAkinyemi about making the project objective and expected contribution\nclearer. His feedback emphasized that the goal should not be described\nsimply as passing a `struct repository \\*repo` argument. The important\npoint is to reduce hidden reliance on the global `the_repository` by\nusing the appropriate repository context and, where the function works\nwith an index, making the required `struct index_state \\*istate`\nexplicit.\n\nHe also asked me to clarify what I expect to contribute and how the\nwork will be carried out over the internship timeline. I have used\nthis feedback to keep the proposed work focused on a specific\ndependency, explain why the helper needs index state, identify the\ncallers that need investigation, and make the implementation and\ntesting plan conditional on the technical findings and\nmentor/maintainer guidance.\n\nThis feedback helped me improve the proposal's technical explanation\nand planning. It should not be read as approval of the specific\n`find_pathspecs_matching_skip_worktree()` contribution or of either\nAPI approach. I will confirm the suitability and final scope with the\nmentors and Git community before treating it as agreed work.\n\n---\n\n## 5. Technical Implementation Plan\n\nI will approach the work in stages. The first priority is to confirm\nthat the identified pathspec dependency is a suitable contribution and\nthat it does not overlap with existing upstream work. I will then\nestablish the current behaviour, compare the possible API designs, and\nagree on a focused change with mentors and maintainers before\nimplementing it. The initial contribution will remain the main\ndeliverable. Further pathspec work will only be considered if the\ninitial change is completed, there is a clear technical reason, and\nmentors agree that it is useful.\n\n### Phase 1: Understand the Current Implementation\n\n- Review the relevant implementation in `pathspec.c` and the\ndeclaration/wrapper in `pathspec.h`.\n\n- Understand the responsibilities of\n`find_pathspecs_matching_skip_worktree()` and how it identifies\nentries marked with `CE_SKIP_WORKTREE` or located outside the\nsparse-checkout area.\n\n- Understand how the relevant index is represented by `struct index_state`.\n\n- Trace the helper, wrapper and callers, and record how each caller\ncurrently obtains repository and index state.\n\n- Review the wrapper's cached matching results and determine whether\nthe cache remains correct if the helper receives an explicit index. In\nparticular, check whether cached results are associated with the\ncorrect index context.\n\n- Investigate the lifetime and ownership of each index pointer that\ncould be passed to the helper. Do not assume that a repository pointer\nor index pointer is interchangeable across callers.\n\n- Pay particular attention to `cmd_rm()` and its currently unused\n`struct repository \\*repo` parameter; determine the correct index\ncontext from the surrounding code.\n\n- Review relevant existing tests and record the current behaviour\nbefore changing anything.\n\n### Phase 2: Compare the API Approaches and Agree on a Design\n\n- Investigate adding an explicit `struct index_state \\*istate`\nparameter to the specialised helper and passing it through the\n`matches_skip_worktree()` wrapper.\n\n- Investigate whether `find_pathspecs_matching_against_index()` could\nbe extended with an additional `ps_skip_worktree_action` option that\nexpresses the required matching behaviour clearly.\n\n- Compare the approaches for API clarity, semantics, caller impact,\ncache correctness, maintainability and size of change.\n\n- Confirm that any proposed action has a precise meaning. Do not\nassume that the existing `PS_IGNORE_SKIP_WORKTREE` option provides the\ninverse matching behaviour needed by the specialised helper.\n\n- Discuss the findings with mentors and maintainers and select a\ndesign only after the behaviour and trade-offs are understood.\n\n- If the pathspec candidate is unsuitable, overlaps with upstream\nwork, or is not the right priority, discuss a different focused\ncontribution with mentors rather than forcing this design.\n\n### Phase 3: Implement the Agreed Initial Change\n\n- Make the smallest change that removes the identified implicit index\ndependency, following the agreed API design.\n\n- Update the helper declaration and definition, the inline wrapper and\nonly the callers affected by the selected design.\n\n- Determine the correct index state at each affected call site; do not\nmechanically pass a repository's index without checking its ownership\nand intended use.\n\n- Review the wrapper cache so that cached results cannot be\nincorrectly reused for a different index context.\n\n- Keep the change limited to the agreed helper/API and necessary\ncallers. Do not treat it as a complete removal of global state from\npathspec or from `git add`/`git rm`.\n\n- Build Git and run the initial focused checks before preparing a\npatch for review.\n\n### Phase 4: Add Focused Tests and Validate Behaviour\n\n- Check whether Git's C unit-test infrastructure can construct two\nindependent `struct index_state` instances for the proposed regression\nscenario.\n\n- If feasible and agreed, add a focused test that uses the same\npathspec with different index states and verifies that the result\nfollows the index supplied to the helper.\n\n- Include the relevant skip-worktree and outside-sparse-checkout\nbehaviour in the test design where the infrastructure permits.\n\n- If a two-index unit test is impractical, discuss and use an\nalternative regression test that demonstrates the bug and protects the\nintended behaviour.\n\n- Run the existing tests relevant to the selected change, then expand\ntesting only where the implementation could affect additional cases.\n\n### Phase 5: Review, Refine and Consider Any Follow-up\n\n- Submit a small, clearly explained patch and provide the exact test results.\n\n- Respond to maintainer feedback, revise the patch and rerun affected\ntests after each meaningful change.\n\n- Investigate any compatibility issue revealed during review and keep\nthe fix within the agreed scope.\n\n- Treat investigation of `init_pathspec_item()`, `parse_pathspec()` or\n`parse_pathspec_file()` as optional research, not as a promised second\nimplementation.\n\n- Only propose a follow-up change if the initial contribution is in a\nreviewable state, the additional dependency is technically justified,\nand mentors agree that it should be pursued.\n\n- If no follow-up is appropriate, use the remaining time to improve\ntests, documentation, review responses and handover for the initial\ncontribution.\n\nThe primary aim is one focused, technically justified and tested\ncontribution. Acceptance or merging is determined by the Git\nmaintainers and is not something I can promise in advance.\n\n---\n\n## 6. Testing and Validation Strategy\n\nTesting will be guided by the final design and by the parts of Git\nthat the change can affect. I will first establish the current\nbehaviour, then add a focused regression test if the test\ninfrastructure supports it, and finally run the relevant existing\ntests. I will not treat every pathspec edge case as part of the\ninitial test scope unless the selected change could affect it.\n\n### 1. Establish the Existing Behaviour\n\n- Record how `find_pathspecs_matching_skip_worktree()` currently\nobtains and uses `the_repository->index`.\n\n- Check how the helper handles entries marked with `CE_SKIP_WORKTREE`\nand paths outside the sparse-checkout area.\n\n- Review how `matches_skip_worktree()` caches and returns matching results.\n\n- Trace the relevant callers and record the expected behaviour for each one.\n\n- Use this baseline to identify what the regression test needs to demonstrate.\n\n### 2. Investigate a Focused Regression Test\n\n- First check Git's existing C unit-test conventions and whether\nseparate `struct index_state` objects can be constructed safely in a\ntest.\n\n- If feasible, prepare two index states with different skip-worktree\ninformation and run the same pathspec against both.\n\n- Check that the result follows the index explicitly supplied to the\nhelper, rather than silently using the global repository index.\n\n- Consider the helper's outside-sparse-checkout behaviour as part of\nthe test design where appropriate.\n\n- Check that test setup and cleanup respect the ownership and lifetime\nof index entries and related data.\n\n- If this exact two-index test is not practical, discuss an\nalternative focused regression test with mentors and maintainers.\n\n### 3. Build and Run the Focused Test\n\n- Build Git after the implementation changes.\n\n- Compile and run the focused test if one is added.\n\n- Where practical, verify that the test exposes the old behaviour and\npasses with the corrected implementation.\n\n- Follow the existing test conventions for setup, registration and cleanup.\n\n- Investigate and fix compilation errors, test failures or\nmemory/lifetime problems introduced by the change.\n\n### 4. Run Relevant Existing Tests\n\nFor the initial helper/API change, I expect to begin with:\n\n- The relevant pathspec tests.\n\n- `t/t3705-add-sparse-checkout.sh` for relevant `git add`\nsparse-checkout behaviour.\n\n- `t/t3602-rm-sparse-checkout.sh` for relevant `git rm`\nsparse-checkout behaviour.\n\n- Any additional focused test identified during source investigation\nor requested during review.\n\nI will investigate sparse-index, prefixed pathspec and wildcard\npathspec cases where the selected change could affect them. I will\nextend the test set if the implementation or review identifies a\nconcrete risk. Cases such as `PATHSPEC_NO_REPOSITORY`, `git diff\n--no-index` and path-prefix handling will be included if a follow-up\nchange reaches pathspec initialization or parsing; they are not\nblanket requirements for the initial helper change.\n\n### 5. Retest After Review\n\n- Rerun the focused test and affected existing tests after making\nreview-driven changes.\n\n- Record the commands run and their results accurately, including\nfailures and limitations.\n\n- Investigate failures before attributing them to the patch.\n\n- Use sanitizers or broader test runs if a concrete memory-safety or\ncompatibility concern makes them relevant, and where the environment\nsupports them.\n\n- Report what was tested and what was not tested in the patch\ndiscussion and final handover.\n\n---\n\n## 7. Thirteen-Week Work Plan\n\nThe internship is scheduled for 7 December 2026 to 8 March 2027. I\nplan to dedicate around 30 hours per week. This is a provisional work\nplan; the final technical scope and priorities will be agreed with the\nmentors. The plan prioritises completing and reviewing one focused\ncontribution rather than promising a second refactor before the first\none is stable.\n\n### Weeks 1–2: Onboarding, Confirm Scope and Complete the Design\n\n- Confirm the development environment, Git contribution workflow,\ncommunication rhythm and test commands with mentors.\n\n- Review the current upstream state and check for overlapping work.\n\n- Revisit the helper, wrapper and callers, including the wrapper cache\nand index pointer lifetime/ownership.\n\n- Compare the two API approaches described in Section 4.4.\n\n- Present the technical findings, risks and test options to mentors\nand maintainers.\n\n- Agree on the initial contribution and its acceptance criteria.\n\n- If the pathspec candidate is unsuitable or overlaps with ongoing\nwork, discuss an alternative focused task with mentors.\n\n**Output:** An agreed initial scope and design direction, or a\ndocumented alternative task. No implementation will be started on an\nuncertain design simply to meet a pre-set milestone.\n\n### Weeks 3–4: Implement the Agreed Focused Change\n\n- Implement the smallest agreed change to make the required index\ndependency explicit.\n\n- Update the relevant declaration, definition, wrapper and affected callers.\n\n- Check the wrapper cache and ensure it does not reuse results for the\nwrong index context.\n\n- Verify the index state used at each affected call site, including\nthe `cmd_rm()` path.\n\n- Build Git and run initial focused checks.\n\n- Prepare a small patch with a clear explanation of the problem and design.\n\n**Output:** An initial implementation and patch ready for focused\ntesting and review.\n\n### Week 5: Develop the Regression Test\n\n- Investigate and, if feasible, implement the two-index regression\ntest described in Section 6.\n\n- Check setup, cleanup, index ownership and the expected behaviour for\nboth index states.\n\n- If that test design is not practical, discuss and implement an\nappropriate alternative test.\n\n- Build and run the test and record the result.\n\n**Output:** A focused regression test or an agreed alternative, with\ntest results recorded.\n\n### Weeks 6–7: Run Compatibility Tests and Submit for Review\n\n- Run the relevant pathspec and sparse-checkout tests.\n\n- Check the affected `git add` and `git rm` behaviour.\n\n- Investigate sparse-index, prefixed and wildcard cases where they are\nrelevant to the selected change.\n\n- Submit the focused patch to the Git community and provide test results.\n\n- Respond to initial review comments and revise the patch where needed.\n\n- Publish the required progress update and describe the work accurately.\n\n**Output:** The initial contribution submitted for review, with\nrelevant test coverage and review feedback being addressed.\n\n### Weeks 8–10: Review, Refine and Validate the Initial Contribution\n\n- Prioritise maintainer feedback on the initial contribution.\n\n- Revisit design decisions if reviewers identify a simpler or safer approach.\n\n- Fix issues, update tests and rerun affected test suites after changes.\n\n- Investigate any newly identified compatibility or lifetime concerns.\n\n- Keep communication clear by explaining changes and reporting test results.\n\n- Only if the initial contribution is in a stable, reviewable state,\ndiscuss whether a small follow-up investigation is useful. Do not\nassume a second implementation is required.\n\n- If no follow-up is appropriate, use this period for further review,\ntesting and refinement of the initial patch.\n\n**Output:** A more complete and carefully reviewed initial\ncontribution. A follow-up is optional and depends on mentor agreement\nand available time.\n\n### Week 11: Final Technical Review\n\n- Review the complete patch and its rationale.\n\n- Confirm that the tests cover the behaviour changed by the implementation.\n\n- Address remaining review comments where possible.\n\n- Run the relevant tests again after the final code changes.\n\n- Record any unresolved issues or limitations honestly.\n\n**Output:** A final refined patch or patch series, with its review and\ntesting status clearly recorded.\n\n### Weeks 12–13: Final Validation, Documentation and Handover\n\n- Run the final focused tests and any additional tests agreed with mentors.\n\n- Review the final implementation, test results and outstanding review points.\n\n- Document the design choice, changes made, test commands/results and\nknown limitations.\n\n- Prepare a handover summary describing what was completed, what was\nsubmitted, what was accepted or integrated if applicable, and what\nremains.\n\n- Complete the required Outreachy blog reports and final report.\n\n**Output:** A tested and documented contribution, together with an\naccurate handover and final report. The final status may be submitted,\nunder review, accepted or merged depending on the maintainers'\ndecisions; merging is not a guaranteed deliverable.\n\n---\n\n## Work-plan Flexibility\n\nThe above plan is a suggested timeline. I may need to make changes\nbased on technical issues, mentor guidance, or feedback from the\ncommunity. The aim is to create a small, useful, and well-tested\nchange. Any further changes to pathspec or its parser will only be\nconsidered if there is a clear technical reason and mentors agree. The\nfirst two weeks include a decision point: if the pathspec candidate is\nunsuitable, overlaps with existing work, or cannot be given a clear\nand testable design, I will discuss an alternative focused\ncontribution with mentors rather than force the proposed change. If\nthe two-index test is not practical, I will agree on an alternative\ntest strategy. If review takes longer than expected, I will prioritise\nimproving and validating the initial contribution rather than starting\na second refactor.\n\nThe aim is not to remove all global dependencies in Git. The aim is to\nmake a meaningful contribution by improving how repository and index\nstate are handled explicitly. If the initial pathspec change overlaps\nwith existing work or is not considered appropriate, I will discuss\nalternative approaches with mentors and adjust the scope accordingly.\n\n## Blogging and Progress Reports\n\nDuring the internship, I will follow Outreachy's blogging\nrequirements. I understand that interns are expected to publish at\nleast three reports and to blog every two weeks about their\ninternship. I will use the introduction, midpoint and final report\nprompts provided by Outreachy, and write shorter progress updates\nbetween those reports when required.\n\nMy reports will cover:\n\n- **Introduction:** Introduce myself, the Git community and the\nproject; explain why I applied, what I learned during the contribution\nperiod, the contributions I am proud of, and what I hope to learn\nduring the internship.\n\n- **Mid-point progress:** Describe the work completed so far, link to\ncontributions, explain technical challenges and what I learned from\nmentors and the community, and mention any changes to the project\nscope or timeline.\n\n- **Final report:** Describe the results of my work and link to\ncontributions, explain what I learned, identify any remaining work or\nways the community could continue the work, and discuss my plans after\nthe internship.\n\nI will also share shorter updates about my progress, implementation\ndecisions, testing results and challenges every two weeks. I will\nfollow the instructions and deadlines sent by Outreachy and make sure\nthat my reports accurately describe the work I have completed.\n\n---\n\n---\n\n## 8. Risks and Mitigation\n\n### Risk 1: Existing global dependencies are more widespread than expected\n\nThe pathspec implementation may contain additional dependencies on\n`the_repository` or other repository-related global variables beyond\nthe helper identified during the preliminary investigation.\n\n**Mitigation:**\n\n- I will review the relevant functions and their callers before making\nAPI changes.\n\n- I will check how repository and index state are accessed and used.\n\n- I will make changes incrementally, starting with the selected\nskip-worktree helper.\n\n- I will investigate any further dependencies before increasing the\nscope of the change.\n\n- I will not assume that a focused change has removed all global dependencies.\n\n### Risk 2: Existing Git behavior may change accidentally\n\nChanges to how the helper accesses index state may cause unwanted\nchanges to current pathspec matching and skip-worktree behavior.\n\n**Mitigation:**\n\n- I will analyse the current behaviour and document it.\n\n- I will investigate and, if feasible, write a focused regression test\nusing two separate index states.\n\n- I will check that the outcome depends on the index passed to the\nhelper, rather than the default global index.\n\n- I will run focused tests covering relevant pathspec, `git add` and\n`git rm` operations.\n\n- I will check that existing behaviour, compatibility and error\nhandling are preserved.\n\n### Risk 3: Sparse-checkout and sparse-index edge cases\n\nThe change may interact with current sparse-checkout behavior,\nskip-worktree entries, or sparse-index behavior.\n\n**Mitigation:**\n\n- I will test relevant skip-worktree entries and check that they\nbehave as expected.\n\n- I will test relevant pathspec forms, including prefixed and wildcard\npathspecs.\n\n- I will run the relevant sparse-checkout tests.\n\n- I will investigate sparse-index compatibility and look for possible\nregressions.\n\n- I will use sanitizers where appropriate.\n\n### Risk 4: API changes may affect multiple callers\n\nThe helper may require changes to multiple callers. Some callers may\naccess repository or index state in different ways.\n\n**Mitigation:**\n\n- I will identify and review all known callers.\n\n- I will check which repository or index context each caller uses.\n\n- I will pay particular attention to `cmd_rm()` and how its repository\ncontext should be used.\n\n- I will compare the API options and discuss the most suitable\napproach with maintainers.\n\n- I will keep the resulting changes focused.\n\n### Risk 5: Maintainer feedback or existing upstream work may change\nthe proposed scope\n\nThe pathspec change is still open for feedback. There may be other\nchanges by maintainers or contributors that affect its suitability or\nscope.\n\n**Mitigation:**\n\n- Share the initial investigation and focused change early.\n\n- Ask for feedback before making wider changes to pathspec.\n\n- Check for upstream changes and possible overlap throughout the work.\n\n- Adjust the implementation based on feedback from maintainers.\n\n- If the scope is unsuitable or overlaps with existing work, discuss\nan alternative contribution with my mentors.\n\n### Risk 6: The proposed regression-test approach may not fit Git's\ntest infrastructure\n\nThe two-index regression test may require a different setup or\nlocation based on Git's existing C unit-test conventions.\n\n**Mitigation:**\n\n- I will look at the existing C unit tests in Git.\n\n- I will study how index states, cache entries and `CE_SKIP_WORKTREE`\nare set up.\n\n- I will make sure the test is placed in the appropriate location,\nregistered and cleaned up correctly.\n\n- I will discuss the testing approach with maintainers if necessary.\n\n- I will build Git, compile the test and run it to verify the implementation.\n\n### Risk 7: Wrapper caching or index lifetime is handled incorrectly\n\nMaking the index explicit may expose issues if cached pathspec matches\nare reused for a different index, or if a caller passes an index whose\nlifetime or ownership is not appropriate.\n\n**Mitigation:**\n\n- I will inspect how the wrapper cache is keyed, populated and reused\nbefore changing the API.\n\n- I will verify whether the cache must be tied to the supplied index\nor invalidated when the index context changes.\n\n- I will trace the lifetime and ownership of each index pointer at the\naffected callers.\n\n- I will avoid retaining an index pointer beyond the lifetime\nguaranteed by its owner.\n\n- I will include these findings in the design discussion and add\nfocused tests for any cache behaviour that the selected change could\naffect.\n\n---\n\n## 9. Communication and Review Strategy\n\nThroughout the internship, I will keep in communication with the Git community.\n\nMy strategy will include:\n\n- Using the public Git mailing list to communicate.\n\n- Asking clear and specific technical questions.\n\n- Submitting small, focused patches early to receive feedback.\n\n- Carefully reviewing feedback from maintainers and contributors and\nproviding responses.\n\n- Making necessary changes and resubmitting updated versions of the patches.\n\n- Explaining the technical reasoning behind the implementation and API choices.\n\n- Keeping patches concise, well-tested, and easy to review.\n\n- Clearly stating test results, including any failures or limitations.\n\n- Discussing any major changes to the proposal scope with my mentors.\n\nDuring my initial research, I emailed the Git community on 2 November\n2026 to ask whether my proposed pathspec contribution would be\nsuitable and to discuss the possible implementation approaches.\n\nThe discussion can be found here:\n\nhttps://gitlist.dev/t/66745\n\nI will use feedback from the Git community and my mentors to improve\nmy implementation approach. As the pathspec contribution has not yet\nbeen approved, I will not consider it confirmed until I receive\nguidance from maintainers.\n\n---\n\n## 10. Expected Outcomes and Deliverables\n\nMy primary goal is to complete one focused, technically justified\ncontribution that reduces the identified hidden index dependency in\nthe agreed part of Git's pathspec code, while preserving existing\nbehaviour.\n\nThe expected work and deliverables are:\n\n- A documented analysis of the helper, wrapper, relevant callers,\ncache behaviour and index ownership/lifetime.\n\n- A comparison of the two API approaches: adding an explicit `struct\nindex_state \\*istate` parameter to\n`find_pathspecs_matching_skip_worktree()`, or extending\n`find_pathspecs_matching_against_index()` with a clearly defined\n`ps_skip_worktree_action` option.\n\n- A design selected after technical investigation and discussion with\nmentors and maintainers.\n\n- One focused implementation of the agreed design, including only the\nnecessary changes to the helper/API, wrapper and affected callers.\n\n- A focused regression test if Git's test infrastructure supports the\nproposed approach, or an alternative test agreed during the\ninvestigation.\n\n- Relevant build and test results, including sparse-checkout and `git\nadd`/`git rm` checks where affected by the change.\n\n- A patch explanation, review responses and revisions based on\nmaintainer feedback.\n\n- A final summary of the implementation, tests performed, review\nstatus and any remaining limitations.\n\nInvestigation of other pathspec functions, such as\n`init_pathspec_item()`, `parse_pathspec()` or `parse_pathspec_file()`,\nis optional follow-up work. It will only be pursued if the initial\ncontribution is in a stable state, there is a clear technical reason,\nand mentors agree that it is appropriate.\n\nThe exact implementation and test deliverables will depend on the\ntechnical findings and the design agreed with the Git community. I can\ncommit to careful investigation, focused implementation, testing and\nreview; I cannot promise that a patch will be accepted or merged\nwithin the internship period.\n\n---\n\n## 11. Relevant Experience and Skills\n\nDuring my preparation for this project, I have learned C programming\nfundamentals, explored Git's source code, and gained practical\nexperience contributing to Git.\n\nI have worked on the following:\n\n- Learning C programming, including functions, structures, pointers,\nfunction arguments, return values, and accessing structure members.\n\n- Understanding global variables, global state, and explicit\ndependencies, including how repository context can be passed to\nfunctions.\n\n- Exploring Git's source code, including `repository.c`,\n`repository.h`, `environment.c`, `alias.c`, and `pathspec.c`.\n\n- Understanding `the_repository` and `struct repository \\*repo`, and\ninvestigating how repository-specific state is accessed.\n\n- Studying previous refactoring work, including how\n`is_bare_repository_cfg` was split into separate responsibilities.\n\n- Exploring repository configuration and state management, including\n`core.attributesFile` and `core.hooksPath`.\n\n- Using commands such as `git grep`, `git log`, `git show`, `git\ndiff`, and `sed` to explore Git's source code, understand its history,\nand examine changes.\n\n- Contributing to Git through changes involving test scripts,\ntest-path checks, safe integer arithmetic, and repository-aware commit\nabbreviations for submodules.\n\n- Creating and revising patches, responding to review feedback, and\nlearning how contributions are discussed within the Git community.\n\n- Exploring Git's testing framework and understanding how tests help\nverify existing behaviour.\n\nThis preparation has helped me understand the importance of repository\ncontext, ownership of state, and careful refactoring in Git. Although\nI am still developing my C programming and Git internals knowledge, I\nhave gained practical experience exploring Git's codebase and\ncontributing changes. I would like to build on this foundation by\nmaking a focused contribution with appropriate testing during the\ninternship.\n\n## 12. Availability and Commitment\n\nI am available for this internship between 7 December 2026 and 8 March 2027.\n\nI can dedicate around 30 hours per week to the internship.\n\nDuring this period, I will:\n\n- Consistently dedicate time to the project.\n\n- Implement changes using an incremental approach.\n\n- Take time to understand the existing codebase.\n\n- Write tests and run them.\n\n- Participate in discussions and communicate with my mentors and the\nGit community.\n\n- Take feedback into account and improve patches where needed.\n\n- Keep track of my progress and communicate any issues.\n\nI understand that contributing to an open-source project requires\ncontinuous learning, patience, and teamwork. I will work consistently\non my contributions, learn from feedback, and aim to make a useful\ncontribution to the Git project.\n\n## 13. References / Useful Links\n\nThe following links provide additional information about the Git\nproject and how to get involved. They also include examples of work I\nhave done previously and research I have carried out into the\ntechnical side of my proposed contribution.\n\n### Official Git Information\n\n- Outreachy Project Selection for December 2026:\nhttps://www.outreachy.org/apply/project-selection/\n\n- Git Source Code: https://github.com/git/git\n\n- Git Documentation: https://git-scm.com/docs\n\n- Git Contribution Guidelines:\nhttps://github.com/git/git/blob/master/Documentation/SubmittingPatches\n\n- Git Coding Guidelines:\nhttps://github.com/git/git/blob/master/Documentation/CodingGuidelines\n\n- Git Mailing List: https://lore.kernel.org/git/\n\n- Git General Application Information:\nhttps://git.github.io/General-Application-Information/\n\n- Git Microproject Information:\nhttps://git.github.io/General-Microproject-Information/\n\n### Previous Contributions\n\nThese are examples of contributions I have made to the Git project,\nincluding work involving source code, test files, and preparing and\nrevising patches based on review feedback.\n\n- PR #2260 – t0001: avoid pipes in test scripts:\nhttps://github.com/gitgitgadget/git/pull/2260\n  This was my microproject contribution. I updated the `t0001-init.sh`\ntest script to avoid using pipes.\n\n- PR #2256 – t2030: modernize test path checks:\nhttps://github.com/gitgitgadget/git/pull/2256\n  This contribution modernizes the path checks in the `t2030` test.\n\n- PR #2276 – diff-delta: use safe integer arithmetic:\nhttps://github.com/gitgitgadget/git/pull/2276\n  This contribution updates the integer arithmetic used in\n`diff-delta` to use safer operations.\n\n- PR #2288 – t4041: use submodule repository for commit abbreviations:\nhttps://github.com/gitgitgadget/git/pull/2288\n  This contribution uses the submodule's repository context when\ndetermining commit abbreviations.\n\nMailing-list versions of these contributions:\n\n- PR #2260 v2: https://lore.kernel.org/git/pull.2260.v2.git.1792666211685.gitgitgadget@gmail.com\n\n- PR #2256 v3: https://lore.kernel.org/git/pull.2256.v3.git.1792299943380.gitgitgadget@gmail.com\n\n- PR #2276 v9: https://lore.kernel.org/git/pull.2276.v9.git.1793120160248.gitgitgadget@gmail.com\n\n### Relevant Source Code and Tests\n\n- `pathspec.c`: https://github.com/git/git/blob/master/pathspec.c\n\n- `pathspec.h`: https://github.com/git/git/blob/master/pathspec.h\n\n- `builtin/add.c`: https://github.com/git/git/blob/master/builtin/add.c\n\n- `builtin/rm.c`: https://github.com/git/git/blob/master/builtin/rm.c\n\n- Sparse-checkout tests for `git add`:\nhttps://github.com/git/git/blob/master/t/t3705-add-sparse-checkout.sh\n\n- Sparse-checkout tests for `git rm`:\nhttps://github.com/git/git/blob/master/t/t3602-rm-sparse-checkout.sh\n\n### Research into the Project\n\nDiscussion about the scope of the proposed pathspec contribution,\nincluding possible API approaches and whether related work is already\nplanned.\n\nhttps://gitlist.dev/t/66745 (2 November 2026)\n\nBackground on previous changes involving repository state and global\ndependencies:\n\n- Git v2.56.0 release notes:\nhttps://github.com/git/git/blob/master/Documentation/RelNotes/2.56.0.adoc\n\n- Commit `7ff3a5895b`, which split the concerns of\n`is_bare_repository_cfg`: https://github.com/git/git/commit/7ff3a5895b\n\n- Commit `dd674df326`, which uses `item.match` consistently for\nsparse-index expansion checks and adds coverage for prefixed wildcard\npathspecs: https://github.com/git/git/commit/dd674df326\n\n- Git's official 2026 GSoC ideas page, including the project\n'Refactoring in order to reduce Git's global state':\nhttps://git.github.io/SoC-2026-Ideas/\n\n## Acknowledgements\n\nI would like to thank Usman Akinyemi, Junio C Hamano, Patrick\nSteinhardt, Harald Nordgren, Phillip Wood, Pablo Sabater, Okhuomon\nAjayi, my mentors, maintainers, and members of the Git community for\ntaking the time to review my contributions, answer my questions, and\nshare their technical feedback. Their guidance and effort have helped\nme understand the codebase better, improve my patches, and learn from\nthe contribution and review process. I sincerely appreciate their time\nand support.\n\n## 14. Conclusion\n\nReducing global state makes dependencies clearer and helps Git move\ntowards being usable as a library. During my preparation, I explored\nGit's source code, read about earlier refactoring work, and\ninvestigated how repository and index information are used in pathspec\nprocessing.\n\nMy initial area of interest is\n`find_pathspecs_matching_skip_worktree()`, which currently gets the\nindex through `the_repository->index`. I want to investigate how this\ndependency could be made explicit. I will compare adding a `struct\nindex_state \\*istate` parameter to the specialised helper with\nextending the existing `find_pathspecs_matching_against_index()` API.\nI will discuss the options with mentors and maintainers before\ndeciding which approach is most suitable.\n\nI also want to investigate a regression test using two separate index\nstates, if Git's test infrastructure supports that approach. The test\nshould help check that the helper uses the index supplied by its\ncaller and that existing pathspec and skip-worktree behaviour is\npreserved. Any further pathspec changes will depend on what I find and\non feedback from mentors and maintainers.\n\nI know that this work will involve learning more about Git's code,\ntesting carefully and responding to review feedback. I hope to build\non the preparation I have already done and make a focused contribution\nto the Git project.\n\n"}]}