{"thread":{"id":"66792","subject":"[Outreachy][Proposal]: Reduce Git's global state to enable Git's libification","startedAt":"2026-11-06T16:44:06Z","lastAt":"2026-11-06T16:44:06Z","messageCount":1,"participants":["Srujith Poojary"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"557712","messageId":"CABh_KWhErO+npX+etVTzyf-ercYjR=dM=tmhiBLbvQWM2FooEQ@mail.gmail.com","threadId":"66792","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-06T16:44:06Z","receivedAt":"2026-11-06T16:44:06Z","isPatch":false,"sender":{"key":"poojarysrujith@gmail.com","avatar":null},"body":"Hi,\n\nI have prepared an updated and complete version of my Outreachy proposal.\n\nI am sharing the full proposal below for your review. Could you please\nlet me know if there are any mistakes, missing details, or areas that\nneed improvement?\n\nYour feedback will help me improve it before submitting my final application.\n\nThank you for your time and guidance.\n\n---\n\n# Outreachy December 2026 Proposal\n\n## Project 3: Reduce Git's Global State to Enable Git's Libification\n\n**Project Title:** Reducing Global State in Git's Pathspec Skip-Worktree\nMatching\n\n**Organization:** Git\n\n**Mentors:** Christian Couder, Usman Akinyemi\n\n## Project Summary: Reducing Global State in Git's Pathspec\nSkip-Worktree Matching\n\nMy project focuses on reducing a hidden global dependency in Git's\npathspec skip-worktree matching. Currently, the helper function\n`find_pathspecs_matching_skip_worktree()` gets index information through\nthe global variable `the_repository->index` instead of receiving that\ninformation directly. The function checks which pathspecs match index\nentries that are marked with skip-worktree or are outside the\nsparse-checkout area. Because it depends on a global variable, its\nrequired information is not clearly provided through its function\narguments. My goal is to investigate how this dependency can be reduced.\nI will study how the helper and its wrapper function work, examine all\ntheir callers, and understand how each caller gets its index\ninformation. I will compare possible solutions and discuss the suitable\napproach with Git maintainers before making changes. Once an approach is\nagreed upon, I will update the necessary functions and callers, add or\nupdate tests, build Git, and run relevant tests, especially those\nrelated to sparse checkout, `git add`, and `git rm`. I will check that\nthe existing behaviour remains correct. This work aims to make the\ncode's dependencies clearer and potentially improve its testability,\nreuse, and maintainability. It will contribute one focused improvement\nto Git's larger effort to reduce global state and make its code easier\nto use as a library. My work is limited to this specific area and its\nrelated code; I am not aiming to remove all global state from Git or\nredesign the entire pathspec system.\n\n## Personal Information\n\n-   **Email:** poojarysrujith@gmail.com\n-   **GitHub:**poojarysrujith\n-   **All PR Links:**https://github.com/gitgitgadget/git/pulls?q=is%3Apr+state%3Aopen+author%3Apoojarysrujith\n-   **Location:**Karnataka,India\n-   **Year of Study:**June 2026\n-   **Time Zone:**GMT+5:30\n\n## 1. About Me\n\nI am a recent BCA (Bachelor of Computer Applications) graduate from\nKarnataka, India, with a foundation in programming and some experience\nin C. I have practical experience developing software projects and\ncontributing to open-source projects. I have also participated in\nseveral coding competitions and have been strengthening my\nproblem-solving skills through Data Structures and Algorithms (DSA).\nCurrently, I am independently learning .NET Full Stack Development and\nbuilding projects to develop my technical skills and prepare for a\ncareer in software development.\n\nMy journey into open source began while I was learning how to use Git\nand GitHub for version control and managing changes in my projects. This\nexperience made me interested in exploring publicly available\nopen-source repositories. It also made me curious about how Git works\ninternally, how its source code is organised, and how Git developers\nmaintain such a large project.\n\n### How I Learned About Outreachy and Chose the Project\n\nWhile watching videos on YouTube, I came across the Outreachy website. I\napplied for the initial application and was selected to continue in the\nprocess. When I explored the listed projects, I chose **Reduce Git's\nglobal state to enable Git's libification** because I was already\nfamiliar with C, Git and GitHub. I then started learning more about the\nproject and exploring the Git codebase.\n\nDuring my contribution period, I learned C concepts needed to understand\nthe codebase, such as pointers, structures and functions. I also\nexplored how different parts of the code communicate with one another. I\nlooked at Git code related to repositories, `struct repository *repo`,\nglobal state and explicit dependencies. This taught me that contributing\nto Git is not only about writing code. It is also important to\nunderstand existing functionality, study previous changes and make sure\nthat code is tested properly.\n\nI made contributions while preparing for this project. I worked on test\nscripts and test-path checks, safe integer arithmetic in `diff-delta`,\nand a submodule-related change involving repository-specific commit\nabbreviations. I also prepared updated patch series for review and\ncommunicated with the Git community through email, GitGitGadget and the\nGit mailing list. These experiences helped me understand the\ncontribution process and gain experience collaborating with the\ncommunity.\n\nI am interested in this Outreachy internship project for December 2026\nbecause it will give me an opportunity to understand and contribute to\nan important part of Git's internal design. I want to learn how implicit\ndependencies on global state can be replaced by passing the required\nrepository or index information explicitly, and how this can help make\ncode easier to test, maintain and reuse.\n\n## 2. Contributions to Git and Project Preparation\n\n### 2.1 Contributions to Git\n\nWhile preparing for this project, I made several contributions to Git:\n\n-   **Avoid pipes in the `t0001-init.sh` test script**\n    -   Description: Changed the test script to avoid using pipes in its\n        commands.\n    -   Pull request: [PR\n        #2260](https://github.com/gitgitgadget/git/pull/2260)\n    -   [Mailing-list\n        discussion](https://lore.kernel.org/git/pull.2260.v2.git.1792666211685.gitgitgadget@gmail.com)\n    -   Status: Integrated into `next`. A later mailing-list update\n        indicated that it was expected to move to `master`. The PR\n        remains open.\n-   **Modernize test path checks in `t2030`**\n    -   Description: Updated how the test script checks file paths.\n    -   Pull request: [PR\n        #2256](https://github.com/gitgitgadget/git/pull/2256)\n    -   [Mailing-list\n        discussion](https://lore.kernel.org/git/pull.2256.v3.git.1792299943380.gitgitgadget@gmail.com)\n    -   Status: Included in `seen`. The PR remains open.\n-   **Use safe integer arithmetic in `diff-delta`**\n    -   Description: Improved integer arithmetic to avoid unsafe\n        calculations.\n    -   Pull request: [PR\n        #2276](https://github.com/gitgitgadget/git/pull/2276)\n    -   [Mailing-list\n        discussion](https://lore.kernel.org/git/pull.2276.v9.git.1793120160248.gitgitgadget@gmail.com)\n    -   Status: Included in `seen`. The PR remains open.\n-   **Use the submodule repository for commit abbreviations**\n    -   Description: Updated submodule commit abbreviation handling to\n        use the submodule's own repository.\n    -   Pull request: [PR\n        #2288](https://github.com/gitgitgadget/git/pull/2288)\n    -   [v6 mailing-list\n        submission](https://lore.kernel.org/git/pull.2288.v6.git.1793821554097.gitgitgadget@gmail.com)\n    -   Status: v6 was submitted on 4 November 2026. The PR remains\n        open; it has not been confirmed as accepted or merged.\n\n### What I Learned from My Contributions\n\nThrough this work, I became familiar with reading existing code,\nunderstanding test failures, preparing patches, running tests and\nresponding to review feedback.\n\n### 2.2 Learning C, Exploring Git's Source Code and Understanding Global State\n\nAlong with making contributions, I spent time learning the C programming\nconcepts needed to understand Git's source code, such as pointers,\nstructures, functions, function arguments, and how information is shared\nbetween different parts of a program.\n\nI explored different Git source files, including `repository.c`,\n`repository.h`, `environment.c`, `alias.c`, `alias.h`, and\n`builtin/help.c`. I focused on understanding how Git uses the global\npointer `the_repository` to access repository information and how\nfunctions can receive repository information explicitly through\n`struct repository *repo`.\n\nI examined `alias_lookup()` in `alias.c` to understand how functions use\ntheir arguments while also depending on global repository information. I\nalso investigated `is_bare_repository()` and commit `7ff3a5895b`, which\nseparated the initial `--bare` command-line option from the\nrepository-specific bare configuration. This helped me understand how\nglobal state can hide a function's dependencies.\n\nTo understand how Git developers address these dependencies, I studied\nprevious refactoring changes. These included moving\n`core.attributesFile` from the global variable `git_attributes_file`\ninto `repo_config_values`, and moving `core.hooksPath` from the global\nvariable `git_hooks_path` into `struct repo_settings`, along with the\nintroduction of `repo_settings_get_hooks_path()` to load and cache the\nvalue for the relevant repository.\n\nThrough this exploration, I understood that global state refers to\ninformation that different parts of a program can access without\nreceiving it directly as an argument. Although this can be convenient,\nit can make a function's actual dependencies less obvious and harder to\nreuse or test with a different repository or index.\n\nI also learned about libification, which means making Git's internal\ncode easier for other programs to use as a software library rather than\nrelying only on Git's command-line programs. Reducing hidden\ndependencies by explicitly passing the required information, such as\n`struct repository *repo` or `struct index_state *istate`, is one part\nof this effort.\n\nGit developers have been working towards this goal by moving\nrepository-specific information into appropriate structures and updating\nfunctions to receive their dependencies explicitly. My understanding of\nthese changes helped me see how reducing global state contributes to the\nbroader goal of libification.\n\nThis preparation helped me build the technical background needed to\ninvestigate pathspec processing as a possible contribution area. It led\nme to examine the relevant implementation, understand its dependencies,\nand identify a specific opportunity for further investigation, which I\nwill explain in the next section.\n\n## 3. Project Overview\n\n### 3.1 Proposed Project: Reducing Global State in Pathspec\nSkip-Worktree Matching\n\nMy project focuses on one part of Git's pathspec implementation.\n\nA **pathspec** tells Git which files or paths a command should work\nwith. For example, it can select a particular file, directory or group\nof files. Pathspecs are used by commands such as `git add`, `git rm`,\n`git grep` and `git diff`.\n\nWhile exploring Git's source code, I found that some pathspec-processing\nfunctions use the global pointer `the_repository` to access repository\ninformation. This means they get information from a global variable\ninstead of receiving everything they need through their function\narguments.\n\nIn `pathspec.c`, I identified the helper function\n`find_pathspecs_matching_skip_worktree()`. It checks which pathspecs\nmatch index entries marked with the skip-worktree flag or entries\nlocated outside the sparse-checkout area.\n\nCurrently, this helper accesses the index through\n`the_repository->index` instead of receiving the index directly as an\nargument. This creates a hidden dependency on the global repository.\n\nI also examined the inline wrapper `matches_skip_worktree()` in\n`pathspec.h`. This wrapper calls the helper and caches the matching\nresults so they can be reused. Because of this caching behaviour,\nchanging only the helper may not be enough. The wrapper and its callers\nalso need to be examined.\n\nI identified four call sites for `matches_skip_worktree()`:\n\n-   One in `pathspec.c`.\n-   Two in `builtin/add.c`.\n-   One in `builtin/rm.c`.\n\nEach caller needs to be checked to understand which index state it\nshould provide.\n\nOne important point is in `builtin/rm.c`. The `cmd_rm()` function\nalready receives a `struct repository *repo` argument, but it is marked\nas `UNUSED`. I need to investigate this further to understand which\nindex should be used rather than assuming that the existing repository\nargument is the correct one.\n\n### 3.2 Possible Approaches\n\nI have identified two approaches to investigate:\n\n-   **Approach 1: Pass the index directly**\n    -   Add a `struct index_state *istate` parameter to\n        `find_pathspecs_matching_skip_worktree()`.\n    -   Update the wrapper if needed.\n    -   Update the callers to provide the correct index state.\n-   **Approach 2: Extend the existing index-matching function**\n    -   Investigate whether `find_pathspecs_matching_against_index()`\n        can support this matching behaviour through an additional\n        `ps_skip_worktree_action` option.\n    -   Check the existing matching logic and whether it can support the\n        required behaviour.\n\nI have not decided which approach is better. I will study both, compare\nthe changes required and discuss the suitable approach with Git\nmaintainers before implementation.\n\n### 3.3 Main Source Files and Tests\n\nI will mainly work with the following files:\n\n-   [`pathspec.c`](https://github.com/git/git/blob/master/pathspec.c)\n    --- contains the helper function being investigated.\n-   [`pathspec.h`](https://github.com/git/git/blob/master/pathspec.h)\n    --- contains the wrapper function.\n-   [`builtin/add.c`](https://github.com/git/git/blob/master/builtin/add.c)\n    --- contains two identified call sites.\n-   [`builtin/rm.c`](https://github.com/git/git/blob/master/builtin/rm.c)\n    --- contains one identified call site.\n-   [`t/t3705-add-sparse-checkout.sh`](https://github.com/git/git/blob/master/t/t3705-add-sparse-checkout.sh)\n    --- tests sparse-checkout behaviour for `git add`.\n-   [`t/t3602-rm-sparse-checkout.sh`](https://github.com/git/git/blob/master/t/t3602-rm-sparse-checkout.sh)\n    --- tests sparse-checkout behaviour for `git rm`.\n\nThese files and tests will help me understand the current implementation\nand check that the existing behaviour is preserved.\n\n## 4. Technical Implementation Plan\n\nI plan to complete the work in the following stages.\n\n### Phase 1: Understand the Existing Code\n\n-   Study `find_pathspecs_matching_skip_worktree()` in `pathspec.c`.\n-   Understand how it checks pathspecs against skip-worktree index\n    entries.\n-   Study the `matches_skip_worktree()` wrapper and how it caches\n    results.\n-   Understand how the helper currently uses `the_repository->index`.\n-   Trace all four callers and check which index state is available at\n    each location.\n-   Review the existing sparse-checkout tests and record the current\n    behaviour.\n\n### Phase 2: Compare Possible Approaches\n\n-   Investigate passing `struct index_state *istate` directly to the\n    helper.\n-   Check how this would affect the wrapper and its callers.\n-   Investigate extending `find_pathspecs_matching_against_index()` with\n    another skip-worktree action.\n-   Compare both approaches based on code clarity, existing Git patterns\n    and the changes required.\n-   Discuss the findings with Git maintainers before choosing an\n    approach.\n\n### Phase 3: Make the Agreed Changes\n\n-   Update the helper or existing index-matching function based on the\n    selected approach.\n-   Update the wrapper if required.\n-   Update the affected callers to provide the correct index state.\n-   Pay particular attention to the index used by `cmd_rm()` in\n    `builtin/rm.c`.\n-   Review the changes to make sure the operation no longer depends on\n    the global index for this matching task.\n\n### Phase 4: Test the Changes\n\n-   Run `t/t3705-add-sparse-checkout.sh`.\n-   Run `t/t3602-rm-sparse-checkout.sh`.\n-   Check whether additional regression tests are needed.\n-   Investigate whether a test using different index states can verify\n    that the helper uses the index supplied to it.\n-   Check relevant pathspec and sparse-checkout behaviour.\n-   Build Git and run the appropriate tests.\n\n### Phase 5: Review and Improve\n\n-   Review the complete changes for correctness and unnecessary\n    modifications.\n-   Address feedback from maintainers and reviewers.\n-   Make further changes where needed.\n-   Run the relevant tests again after changes.\n-   Document the final implementation and test results.\n\nIf the main contribution is completed and time permits, I may\ninvestigate related pathspec functions such as `init_pathspec_item()`\nfor similar dependencies. This will depend on the findings and\ndiscussion with the Git community.\n\n## 5. Thirteen-Week Internship Work Plan\n\nI have divided the internship into thirteen weeks, from 7 December 2026\nto 8 March 2027. I can dedicate 40 hours per week. The plan covers\nunderstanding the existing code, discussing the approach,\nimplementation, testing, code review and final documentation. The\nschedule may be adjusted depending on implementation complexity and\nfeedback from the Git community.\n\n### Weeks 1 to 2: Code Understanding and Planning\n\n-   Study `find_pathspecs_matching_skip_worktree()` and its inline\n    wrapper.\n-   Understand skip-worktree entries and sparse-checkout behaviour.\n-   Trace all four callers and identify the available index state.\n-   Review existing tests and current behaviour.\n-   Compare the two possible API approaches.\n-   Discuss the proposed approach with mentors and the Git community.\n-   Consider an alternative contribution if the pathspec candidate is\n    unsuitable.\n\n**Expected outcome:** Understand the existing implementation and agree\non the contribution approach.\n\n### Weeks 3 to 4: Implementation\n\n-   Implement the agreed approach.\n-   Update the helper or existing index-matching function as\n    appropriate.\n-   Update the inline wrapper if required.\n-   Update affected callers to pass the correct index state.\n-   Pay particular attention to `builtin/add.c` and `builtin/rm.c`.\n-   Review the changes and run focused tests.\n\n**Expected outcome:** Initial implementation with explicit index-state\nhandling.\n\n### Week 5: Testing\n\n-   Review existing sparse-checkout tests.\n-   Run `t/t3705-add-sparse-checkout.sh` and\n    `t/t3602-rm-sparse-checkout.sh`.\n-   Identify additional regression tests if needed.\n-   Check whether different index states are handled correctly.\n-   Fix any issues found.\n\n**Expected outcome:** Initial regression coverage and validation of\nexisting behaviour.\n\n### Weeks 6 to 7: Code Review and Refinement\n\n-   Submit the implementation through the Git contribution process.\n-   Collect feedback from mentors and contributors.\n-   Make changes based on review comments.\n-   Review the helper, wrapper and callers.\n-   Run relevant tests again.\n-   Discuss any unresolved design questions.\n\n**Expected outcome:** Refined implementation addressing review feedback.\n\n### Weeks 8 to 10: Follow-up Investigation\n\n-   Investigate related pathspec functions for similar global-state\n    dependencies.\n-   Consider `init_pathspec_item()` as a possible follow-up.\n-   Evaluate whether additional changes are useful.\n-   Discuss any scope expansion with mentors.\n-   Continue testing and addressing feedback on the main contribution.\n\n**Expected outcome:** Continue the main contribution and investigate\nrelated opportunities where appropriate.\n\n### Week 11: Final Testing and Documentation\n\n-   Review the complete implementation and diff.\n-   Run focused tests and broader tests where practical.\n-   Check for unintended changes in pathspec and sparse-checkout\n    behaviour.\n-   Update comments or documentation if necessary.\n-   Address remaining review feedback.\n\n**Expected outcome:** Thoroughly reviewed and tested contribution.\n\n### Weeks 12 to 13: Final Review and Summary\n\n-   Complete remaining changes based on feedback.\n-   Run relevant tests after final changes.\n-   Review the final code and contribution history.\n-   Document implementation decisions and testing performed.\n-   Summarize completed work, challenges and possible follow-up\n    improvements.\n\n**Expected outcome:** Completed internship work summary with the\ncontribution's final review or integration status documented.\n\nI will use this as a working schedule and adjust it based on\nimplementation complexity, test results and feedback from the Git\ncommunity. My main priority throughout the internship will be completing\nand validating the pathspec contribution rather than expanding into\nunrelated areas.\n\n## 6. Expected Outcomes and Conclusion\n\n### Expected Outcomes\n\nThrough this project, I aim to make a focused contribution to Git's\nongoing effort to reduce global state and make its internal code easier\nto reuse.\n\nThe intended outcomes are:\n\n-   A clear understanding of the existing\n    `find_pathspecs_matching_skip_worktree()` helper, its wrapper and\n    its callers.\n-   A technically suitable change that makes the required index\n    dependency explicit, if the investigation and review support this\n    direction.\n-   Updates to the wrapper and affected callers where required by the\n    selected design.\n-   Focused regression coverage, if the test infrastructure supports it,\n    together with relevant existing pathspec and sparse-checkout tests.\n-   A focused patch submitted for review, with its review status\n    reported accurately. Acceptance or merging will depend on the Git\n    maintainers.\n-   A record of the implementation decisions, tests performed and any\n    remaining limitations.\n\nI also expect to improve my understanding of Git's internal\narchitecture, repository and index handling, and the process of\ncontributing changes to a large open-source project.\n\n## 7. Blogging and Progress Reports\n\nI will follow Outreachy's blogging and reporting requirements throughout\nthe internship. I will use my reports to describe the work completed,\ntechnical challenges, feedback received, what I have learned and any\nchanges to the plan. I will also share progress updates with my mentors\nat least every two weeks, including completed tasks, test results,\ncurrent blockers and next steps.\n\n## 8. Availability and Work Planning\n\nI can dedicate 40 hours per week to the Outreachy internship throughout\nthe 13-week period. I understand that the programme requires at least 30\nhours per week for at least 12 of the 13 weeks, and I am prepared to\nmake the internship project my primary focus during this period.\n\nI will divide my working time between understanding the existing code,\nimplementation, testing, communicating with mentors and responding to\nreview feedback. I will share progress and draft milestones with the\nmentors and Git community regularly, at least every two weeks.\n\nIf I face a temporary interruption or a situation that affects my\navailability, I will inform my mentor as early as possible and discuss\nhow to manage the work. My priority will be to maintain consistent\nprogress and complete the agreed contribution within the internship\nperiod.\n\n## 9. Acknowledgements\n\nI sincerely thank my mentors, Usman Akinyemi and Christian Couder, and\nthe Git community for their guidance, feedback and support. I appreciate\nthe opportunity to learn, contribute and improve through this project.\n\nRegards,\nSrujith\n\n"}]}