# [Outreachy][Proposal]: Reduce Git's global state to enable Git's libification

1 messages from 2026-11-05 to 2026-11-05. Participants: Srujith Poojary.
Thread: https://gitlist.dev/t/66783

## Srujith Poojary, 2026-11-05 12:03

Subject: [Outreachy][Proposal]: Reduce Git's global state to enable Git's libification
Message-ID: <CABh_KWjbEGaf33n-qKJDC+-cipfMvzUm6=mwDuV5s7yEYBL5dg@mail.gmail.com>
URL: https://gitlist.dev/e/CABh_KWjbEGaf33n-qKJDC%2B-cipfMvzUm6%3DmwDuV5s7yEYBL5dg%40mail.gmail.com

```
Hello Git community,

I am sharing my draft proposal for the December 2026 Outreachy
internship. I would appreciate your feedback and suggestions.

# About Myself

I am from Karnataka India [UTC+05:30 (IST)]. As a BCA(Bachelor of
Computer  Application) Graduate.I have a good foundation of
programming and have worked with some programming languages.I have
practical knowledge developing own software projects and contributing
to open source projects.while learning how to use Git and GitHub for
version control and managing changes in my projects it became
interested in using different publicly available open source
repositories. This led me to become curious about how Git works
internally, How its source code is structured, and how its developers
keep such a huge project going.

This pushed me to look into the source code of Git. I learned about
the C concepts that are needed to understand the code such as
pointers, structures, functions and looking at how the different parts
code communicates with itself. I looked into the Git code related to
repositories and learned about concepts such as the_repository, struct
repository \*repo, global state and explicit dependencies. This taught
me that when contributing to a well established open source project
there is more to it than just writing code. You need to understand the
existing functionality, look at past changes and ensure that the code
is tested properly.

I made some contributions while preparing for this project. I made
changes to test scripts, test-path and safe integer arithmetic in
diff-delta. I worked on a submodule-related change involving
repository-specific commit abbreviations and made an updated patch
series for review. I gained practical experience of looking at
existing code, creating patches, testing and getting my code reviewed.

When i got to know about this project is while watching videos on
YouTube about Git and contributing to open source projects I
discovered Outreachy. I submitted my initial application and looked
through the list of projects available. I found the Git project,
'Reduce Git's global state to enable Git's libification'. As I was
already interested in Git and GitHub and had begun learning about C
programming, I decided to choose this project as it fit my interests.
I began preparing for this project by completing the microproject,
looking at Git's source code, looking into past changes and
researching potential areas to contribute to for my main project.

I am interested to involved with this Outreachy internship project for
December 2026 as it will give me the opportunity to understand and
contribute to a key part of Git's internal design. I am interested in
understanding how to replace implicit dependencies on global state by
passing the required repository or index information explicitly. I
would like to learn how this can help make the code more testable,
maintainable and reusable.

I hope to boost my C programming and problem solving skills during
this internship. I hope to make useful and thoroughly tested changes
to Git. I am happy to look into the existing implementation, talk to
maintainers, learn from code reviews and improve my work using
technical feedback and collaboration with community.

## 2. My understanding about Project

### 2.1 What is Git's global state?

while looking  Gits source code,I learnt that global state is
information that different parts of program can acces without
receiving it directly as an argument.This can be useful,But it can
also hide what a function depends on so.

ex: In Git is `the_repository`.It is a global pointer to `struct
repository` object.Code can use it to access information about the
current repository. For example, `the_repository->index` gives access
to that repository's index.

The problem came here is a function may appear to need only the
arguments shown in its definition, while it also gets important
information from a global variable. That makes the dependency less
obvious. It can also make it harder to test the function with a
different kind of repository or index. This is the kind of dependency
I am interested in understanding and reducing in the pathspec code.

### 2.2 What does libification mean?

I understood libification makes Gits internal code easier for other
programs to use as a software library,rather than only using it
through Git's command-line programs.

One problem is that some Git functions rely on global information like
`the_repository`. A function that gets information this way may be
harder to use when another program needs to work on a particular
repository or when more than one repository is involved.

One way to reduce this hidden dependency is to pass the information
the function needs as an argument. ex: a function can receive a
`struct repository \*repo` to work with a particular repository, or a
`struct index_state \*istate` to work with a particular index.

This helps the function's dependencies clearer and can make it easy to
test and reuse. I understand that passing repository or index
information explicitly is only one part of libification; other parts
of Git may need further changes as well.

### 2.3 What has already been done?

I discovered while looking at source code Git developers have been
working to reduce global state. Two important structures used to store
repository-specific information are repo_config_values and
repo_settings.

ex: I looked at was `core.attributesFile`. Previously this was stored
in a global variable called `git_attributes_file`. When multiple
repositories are used in the same process, one repository's
configuration could overwrite the value used for another repository.
This was refactored so that the value could be stored in the
attributes_file member of repo_config_values.

Another ex:I looked at was `core.hooksPath`. Previously this was
stored in a global variable called `git_hooks_path`. This could cause
problems when multiple repositories used different paths for their
hooks in the same process. This was then refactored to store the value
in struct repo_settings. A function called
repo_settings_get_hooks_path() was also introduced to load and cache
the value for the required repository. These research helped me to
understand how Git uses various repository specific structures to
reduce global state.

In Google Summer of Code 2026 there was a project called "Refactoring
in order to reduce Git's global state". This aimed to reduce global
dependencies by refactoring Git's environment handling and moving
selected values into appropriate repository-specific structures,
including repo_config_values. Some examples of these values include
`protect_hfs`, `protect_ntfs`, `trust_executable_bit`, `ignore_case`,
`excludes_file` and various program settings.

This work provides useful context for the current Outreachy project.
The earlier refactoring focused on reducing global state in Git's
environment and configuration handling. The current project takes the
broader goal further by looking at how parts of Git can become
suitable for use as a library. My proposed pathspec investigation is a
possible contribution to that ongoing effort, rather than a claim that
pathspec work was assigned or approved by the earlier GSoC mentors.

In the v2.56 release notes for Git there are several examples of
changes made to reduce global dependencies. These include functions in
`copy.c` being modified to take a repository argument, the use of
repository aware versions of the tempfile and lockfile APIs. Parts of
the refspec API were changed to remove their dependency on the global
the_repository by passing the hash algorithm explicitly. And
repository pointers are passed in ref and worktree related functions.

Overall from looking at these changes, it seems(i'm assuming not sure)
that reducing global state is a continuous process. As developers need
to understand what each value is used for, and find the correct
repository/structure to store them in. Some of the information will
need to be made explicit. The December 2026 Outreachy project
continues this larger effort by making Git's internal code more
suitable for libification while maintaining its existing behaviour.

## 3. Previous Contributions and Preparation

### 3.1 Contributions to Git

While preparing for this project, I contributed to Git. I became
familiar with reading code, finding issues, and making and testing
changes based on feedback from maintainers.

| Contribution | Pull Request and mailing-list discussion | Status as
of 5 November 2026 |
|---|---|---|
| Avoid pipes in the `t0001-init.sh` test script | [PR
#2260](https://github.com/gitgitgadget/git/pull/2260); [v2
mailing-list discussion](https://lore.kernel.org/git/pull.2260.v2.git.1792666211685.gitgitgadget@gmail.com)
| Integrated into `next`. A later mailing-list status update says it
will merge to `master`. The GitHub PR remains open and is not marked
as merged. |
| Modernize test path checks in `t2030` | [PR
#2256](https://github.com/gitgitgadget/git/pull/2256); [v3
mailing-list discussion](https://lore.kernel.org/git/pull.2256.v3.git.1792299943380.gitgitgadget@gmail.com)
| Integrated into `seen`. The GitHub PR remains open; the latest
recorded status update says it needs review. |
| Use safe integer arithmetic in `diff-delta` | [PR
#2276](https://github.com/gitgitgadget/git/pull/2276); [v9
mailing-list discussion](https://lore.kernel.org/git/pull.2276.v9.git.1793120160248.gitgitgadget@gmail.com)
| Integrated into `seen`. The GitHub PR remains open; the latest
recorded status update says it needs review. |
| Use the submodule repository for commit abbreviations | [PR
#2288](https://github.com/gitgitgadget/git/pull/2288); [v6
mailing-list submission](https://lore.kernel.org/git/pull.2288.v6.git.1793821554097.gitgitgadget@gmail.com);
[v6 commit](https://github.com/git/git/commit/01c3cc25738c43d61aff153805e02db872ff21de)
| v6 was submitted on 4 November 2026. The GitHub PR remains open. The
latest status information available for v6 does not show maintainer
acceptance or integration. The focused
`t4041-diff-submodule-option.sh` tests passed 48/48 with both SHA-1
and SHA-256. |

Integration into `next` or `seen` is part of Git's review process and
does not mean that a GitHub PR has been merged into `master`. All four
GitHub PRs remain open and are not marked as merged as of 5 November
2026.

### 3.2 Source-code preparation

I looked at different area of Git source code, which includes
including `repository.c`, `repository.h`, `environment.c`, `alias.c`,
`alias.h` and `builtin/help.c`. I also read the Git v2.56.0 release
notes to see what had changed recently in the effort to reduce global
state.

I investigated how `the_repository` is used as a global pointer to the
main repository structure. I also looked at how functions receive
repository pointers (`struct repository \*repo`) as arguments to
access repository-specific information.

I looked at `alias_lookup()` in `alias.c` and examined how it uses
`the_repository`. This helped me understand that a function can
receive some information through its arguments while still relying on
global state for other information.

I also investigated `is_bare_repository()` and the changes made in
commit `7ff3a5895b`. The change separated the initial `--bare`
command-line option from the repository-specific bare configuration.
This helped me understand why these different types of information
need to be stored separately.

I became more familiar with commands such as `git grep`, `sed`, `git
log`, `git show` and `git diff`. I used them to locate functions,
follow the flow of code and understand changes between commits. This
made me more comfortable investigating the codebase and understanding
how global dependencies can be reduced.

I also checked `init_pathspec_item()` in `pathspec.c`. This is a
separate area from the skip-worktree matching helper: it uses
`the_repository` for repository-dependent path-prefix handling and
error reporting. This showed me that there may be other repository
dependencies in pathspec processing, but they need to be assessed
individually. I have kept this as possible follow-up investigation
rather than including it in the initial implementation scope.

### 3.3 My knowledge about the project through case studies

I Looked at two examples in Git to understand how global state has been reduced.

For `core.attributesFile`, I found that the value was previously
stored in the global variable `git_attributes_file`. It was later
moved into the `attributes_file` member of `struct
repo_config_values`.

For `core.hooksPath`, the value was previously stored in the global
variable `git_hooks_path`. It was moved into `struct repo_settings`. A
function called `repo_settings_get_hooks_path()` was also introduced
to load and cache the value for the relevant repository.

By seeing at these changes helped me understand that reducing global
state involves deciding where information should be stored and how the
correct repository should access it.

I also looked at a more recent pathspec change, commit `dd674df326`
("pathspec: use match for sparse-index expansion checks"). This change
addressed a heap-buffer-overflow involving prefixed wildcard pathspecs
with a sparse index. It changed the checks to use `item.match`, which
includes the path prefix, consistently instead of using
`item.original`. This is relevant prior work because it shows that
pathspec changes involving prefixes and sparse indexes need careful
compatibility and memory-safety testing. My proposed helper
investigation is separate from that change, and I will check for
overlap rather than assume the work is related or already covered.

## 4. Problem Identification and Proposed Contribution

### 4.1 Why investigate pathspec?

A pathspec can be used by Git commands to tells which files or paths
to target. It can be used to find a specific file, directory or group
of files using patterns.

Pathspecs are used by several Git commands such as `git add`, `git
rm`, `git grep` and `git diff`.

While watching how pathspecs are implemented in Git, I noticed that
some of the pathspec-processing functions use the global pointer
`the_repository` to get information about the current repository. This
creates an implicit dependency.

Pathspec processing seems like a useful area to look for. Making
dependencies on specific repositories or indexes explicit can help
reduce global state and make the code more reusable in different
repository contexts.

### 4.2 Current technical observation

In my examination on `pathspec.c`, I found that there is a function
called `find_pathspecs_matching_skip_worktree()` that checks which
pathspecs match index entries marked with the skip-worktree flag or
located outside the sparse-checkout area.

The function accesses the index via `the_repository->index`, but does
not accept it as a parameter. Instead, it uses the global pointer
`the_repository`. This has created an implicit dependency on the
global repository.

One possible improvement would be to pass a `struct index_state
\*istate` argument to the function. This would make the required index
explicit and allow the function to use the index supplied by its
caller.

I investigated the inline wrapper for this function in `pathspec.h`.
This function is called `matches_skip_worktree()`, and calls
`find_pathspecs_matching_skip_worktree()`. The wrapper also caches the
matching results so they can be reused on subsequent calls.

Any change to the helper will also require reviewing and updating the
wrapper and its callers.

### 4.3 Current call-site investigation

I checked the source code and found four call sites for
`matches_skip_worktree()`: one in `pathspec.c`, two in
`builtin/add.c`, and one in `builtin/rm.c`.

Each of these callers will need to be considered when changing the
helper and wrapper interface. The caller must provide the appropriate
index state so that the function works with the intended repository.

Interestingly, in `builtin/rm.c`, the `cmd_rm()` function has a
`struct repository \*repo` argument already. However, the variable is
marked as UNUSED. The surrounding code still refers to
`the_repository` to get the index. Therefore this caller will need
further investigation to determine how to pass the correct index.

The changes should only be made to the relevant helper, wrapper and
callers. We should not make any assumptions that by updating these
call sites it will mean that the `git add` or `git rm` command is now
free from global state.

### 4.4 Proposed project objective

I want to look into reducing a specific global repository/index
dependency in Git's pathspec code.

My initial investigation focuses on
`find_pathspecs_matching_skip_worktree()`, which currently obtains the
index through `the_repository->index` instead of receiving the index
it should use as an argument.

I will look to examine two possible API approaches:

1\. Keep the specialised helper and add an explicit `struct
index_state \*istate` parameter. I would then review how this
parameter should pass through the inline `matches_skip_worktree()`
wrapper and its callers.

2\. Investigate whether the existing
`find_pathspecs_matching_against_index()` API could be extended with
another `ps_skip_worktree_action` option to support the required
matching behaviour.

I will compare these approaches by looking at the existing API design,
the effect on callers, whether the required matching behaviour can be
represented clearly, and the amount of change each approach
introduces. I will discuss the findings with mentors and maintainers
before selecting the implementation.

I will also review the four identified call sites and determine which
index state each one should use. If the selected design and Git's test
infrastructure allow it, I will add a targeted regression test to
check that the helper uses the index supplied by its caller and that
existing sparse-checkout behaviour is preserved.

After this initial investigation and focused change, I may look into
whether other pathspec functions could also receive repository or
index information explicitly. Any further work will depend on the
technical findings and feedback from Git maintainers.

The aim is to reduce the reliance of selected parts of Git's pathspec
code on global state while preserving existing behaviour.

### 4.5 Scope boundaries

I intend to keep my initial work focused on the identified global
index dependency in `find_pathspecs_matching_skip_worktree()` and the
API changes needed to address it.

**What I will do initially:**

- Investigate the helper's reliance on `the_repository->index`.

- Compare the two API approaches described in Section 4.4 before
selecting an implementation.

- Review the inline wrapper and the four identified call sites, and
determine the correct index state for each caller.

- Investigate and, if feasible, add a focused regression test for the
selected implementation.

- Test the changes to ensure existing skip-worktree and
sparse-checkout behaviour is preserved.

**What I may investigate as follow-up work:**

- Depending on the initial findings and feedback from Git maintainers,
investigate `init_pathspec_item()` and selected parsing functions.

- Look into other pathspec functions only where there is a clear
repository/index dependency and a technically justified benefit to
making it explicit.

- Discuss any wider changes with mentors and maintainers before
expanding the scope.

**What I will not promise as part of the initial contribution:**

- Rewrite the whole pathspec subsystem.

- Remove all global variables from Git.

- Guarantee that `the_repository` will be completely removed from
pathspec functions.

- Claim that Git will become fully thread-safe as a result of this change.

- Make unrelated changes outside the agreed pathspec scope.

I will aim to make a focused and well-tested contribution while
preserving existing functionality. Any follow-up work will depend on
technical justification and maintainer guidance.

### 4.6 Feedback from Usman Akinyemi

During proposal preparation, I received technical feedback from Usman
Akinyemi about making the project objective and expected contribution
clearer. His feedback emphasized that the goal should not be described
simply as passing a `struct repository \*repo` argument. The important
point is to reduce hidden reliance on the global `the_repository` by
using the appropriate repository context and, where the function works
with an index, making the required `struct index_state \*istate`
explicit.

He also asked me to clarify what I expect to contribute and how the
work will be carried out over the internship timeline. I have used
this feedback to keep the proposed work focused on a specific
dependency, explain why the helper needs index state, identify the
callers that need investigation, and make the implementation and
testing plan conditional on the technical findings and
mentor/maintainer guidance.

This feedback helped me improve the proposal's technical explanation
and planning. It should not be read as approval of the specific
`find_pathspecs_matching_skip_worktree()` contribution or of either
API approach. I will confirm the suitability and final scope with the
mentors and Git community before treating it as agreed work.

---

## 5. Technical Implementation Plan

I will approach the work in stages. The first priority is to confirm
that the identified pathspec dependency is a suitable contribution and
that it does not overlap with existing upstream work. I will then
establish the current behaviour, compare the possible API designs, and
agree on a focused change with mentors and maintainers before
implementing it. The initial contribution will remain the main
deliverable. Further pathspec work will only be considered if the
initial change is completed, there is a clear technical reason, and
mentors agree that it is useful.

### Phase 1: Understand the Current Implementation

- Review the relevant implementation in `pathspec.c` and the
declaration/wrapper in `pathspec.h`.

- Understand the responsibilities of
`find_pathspecs_matching_skip_worktree()` and how it identifies
entries marked with `CE_SKIP_WORKTREE` or located outside the
sparse-checkout area.

- Understand how the relevant index is represented by `struct index_state`.

- Trace the helper, wrapper and callers, and record how each caller
currently obtains repository and index state.

- Review the wrapper's cached matching results and determine whether
the cache remains correct if the helper receives an explicit index. In
particular, check whether cached results are associated with the
correct index context.

- Investigate the lifetime and ownership of each index pointer that
could be passed to the helper. Do not assume that a repository pointer
or index pointer is interchangeable across callers.

- Pay particular attention to `cmd_rm()` and its currently unused
`struct repository \*repo` parameter; determine the correct index
context from the surrounding code.

- Review relevant existing tests and record the current behaviour
before changing anything.

### Phase 2: Compare the API Approaches and Agree on a Design

- Investigate adding an explicit `struct index_state \*istate`
parameter to the specialised helper and passing it through the
`matches_skip_worktree()` wrapper.

- Investigate whether `find_pathspecs_matching_against_index()` could
be extended with an additional `ps_skip_worktree_action` option that
expresses the required matching behaviour clearly.

- Compare the approaches for API clarity, semantics, caller impact,
cache correctness, maintainability and size of change.

- Confirm that any proposed action has a precise meaning. Do not
assume that the existing `PS_IGNORE_SKIP_WORKTREE` option provides the
inverse matching behaviour needed by the specialised helper.

- Discuss the findings with mentors and maintainers and select a
design only after the behaviour and trade-offs are understood.

- If the pathspec candidate is unsuitable, overlaps with upstream
work, or is not the right priority, discuss a different focused
contribution with mentors rather than forcing this design.

### Phase 3: Implement the Agreed Initial Change

- Make the smallest change that removes the identified implicit index
dependency, following the agreed API design.

- Update the helper declaration and definition, the inline wrapper and
only the callers affected by the selected design.

- Determine the correct index state at each affected call site; do not
mechanically pass a repository's index without checking its ownership
and intended use.

- Review the wrapper cache so that cached results cannot be
incorrectly reused for a different index context.

- Keep the change limited to the agreed helper/API and necessary
callers. Do not treat it as a complete removal of global state from
pathspec or from `git add`/`git rm`.

- Build Git and run the initial focused checks before preparing a
patch for review.

### Phase 4: Add Focused Tests and Validate Behaviour

- Check whether Git's C unit-test infrastructure can construct two
independent `struct index_state` instances for the proposed regression
scenario.

- If feasible and agreed, add a focused test that uses the same
pathspec with different index states and verifies that the result
follows the index supplied to the helper.

- Include the relevant skip-worktree and outside-sparse-checkout
behaviour in the test design where the infrastructure permits.

- If a two-index unit test is impractical, discuss and use an
alternative regression test that demonstrates the bug and protects the
intended behaviour.

- Run the existing tests relevant to the selected change, then expand
testing only where the implementation could affect additional cases.

### Phase 5: Review, Refine and Consider Any Follow-up

- Submit a small, clearly explained patch and provide the exact test results.

- Respond to maintainer feedback, revise the patch and rerun affected
tests after each meaningful change.

- Investigate any compatibility issue revealed during review and keep
the fix within the agreed scope.

- Treat investigation of `init_pathspec_item()`, `parse_pathspec()` or
`parse_pathspec_file()` as optional research, not as a promised second
implementation.

- Only propose a follow-up change if the initial contribution is in a
reviewable state, the additional dependency is technically justified,
and mentors agree that it should be pursued.

- If no follow-up is appropriate, use the remaining time to improve
tests, documentation, review responses and handover for the initial
contribution.

The primary aim is one focused, technically justified and tested
contribution. Acceptance or merging is determined by the Git
maintainers and is not something I can promise in advance.

---

## 6. Testing and Validation Strategy

Testing will be guided by the final design and by the parts of Git
that the change can affect. I will first establish the current
behaviour, then add a focused regression test if the test
infrastructure supports it, and finally run the relevant existing
tests. I will not treat every pathspec edge case as part of the
initial test scope unless the selected change could affect it.

### 1. Establish the Existing Behaviour

- Record how `find_pathspecs_matching_skip_worktree()` currently
obtains and uses `the_repository->index`.

- Check how the helper handles entries marked with `CE_SKIP_WORKTREE`
and paths outside the sparse-checkout area.

- Review how `matches_skip_worktree()` caches and returns matching results.

- Trace the relevant callers and record the expected behaviour for each one.

- Use this baseline to identify what the regression test needs to demonstrate.

### 2. Investigate a Focused Regression Test

- First check Git's existing C unit-test conventions and whether
separate `struct index_state` objects can be constructed safely in a
test.

- If feasible, prepare two index states with different skip-worktree
information and run the same pathspec against both.

- Check that the result follows the index explicitly supplied to the
helper, rather than silently using the global repository index.

- Consider the helper's outside-sparse-checkout behaviour as part of
the test design where appropriate.

- Check that test setup and cleanup respect the ownership and lifetime
of index entries and related data.

- If this exact two-index test is not practical, discuss an
alternative focused regression test with mentors and maintainers.

### 3. Build and Run the Focused Test

- Build Git after the implementation changes.

- Compile and run the focused test if one is added.

- Where practical, verify that the test exposes the old behaviour and
passes with the corrected implementation.

- Follow the existing test conventions for setup, registration and cleanup.

- Investigate and fix compilation errors, test failures or
memory/lifetime problems introduced by the change.

### 4. Run Relevant Existing Tests

For the initial helper/API change, I expect to begin with:

- The relevant pathspec tests.

- `t/t3705-add-sparse-checkout.sh` for relevant `git add`
sparse-checkout behaviour.

- `t/t3602-rm-sparse-checkout.sh` for relevant `git rm`
sparse-checkout behaviour.

- Any additional focused test identified during source investigation
or requested during review.

I will investigate sparse-index, prefixed pathspec and wildcard
pathspec cases where the selected change could affect them. I will
extend the test set if the implementation or review identifies a
concrete risk. Cases such as `PATHSPEC_NO_REPOSITORY`, `git diff
--no-index` and path-prefix handling will be included if a follow-up
change reaches pathspec initialization or parsing; they are not
blanket requirements for the initial helper change.

### 5. Retest After Review

- Rerun the focused test and affected existing tests after making
review-driven changes.

- Record the commands run and their results accurately, including
failures and limitations.

- Investigate failures before attributing them to the patch.

- Use sanitizers or broader test runs if a concrete memory-safety or
compatibility concern makes them relevant, and where the environment
supports them.

- Report what was tested and what was not tested in the patch
discussion and final handover.

---

## 7. Thirteen-Week Work Plan

The internship is scheduled for 7 December 2026 to 8 March 2027. I
plan to dedicate around 30 hours per week. This is a provisional work
plan; the final technical scope and priorities will be agreed with the
mentors. The plan prioritises completing and reviewing one focused
contribution rather than promising a second refactor before the first
one is stable.

### Weeks 1–2: Onboarding, Confirm Scope and Complete the Design

- Confirm the development environment, Git contribution workflow,
communication rhythm and test commands with mentors.

- Review the current upstream state and check for overlapping work.

- Revisit the helper, wrapper and callers, including the wrapper cache
and index pointer lifetime/ownership.

- Compare the two API approaches described in Section 4.4.

- Present the technical findings, risks and test options to mentors
and maintainers.

- Agree on the initial contribution and its acceptance criteria.

- If the pathspec candidate is unsuitable or overlaps with ongoing
work, discuss an alternative focused task with mentors.

**Output:** An agreed initial scope and design direction, or a
documented alternative task. No implementation will be started on an
uncertain design simply to meet a pre-set milestone.

### Weeks 3–4: Implement the Agreed Focused Change

- Implement the smallest agreed change to make the required index
dependency explicit.

- Update the relevant declaration, definition, wrapper and affected callers.

- Check the wrapper cache and ensure it does not reuse results for the
wrong index context.

- Verify the index state used at each affected call site, including
the `cmd_rm()` path.

- Build Git and run initial focused checks.

- Prepare a small patch with a clear explanation of the problem and design.

**Output:** An initial implementation and patch ready for focused
testing and review.

### Week 5: Develop the Regression Test

- Investigate and, if feasible, implement the two-index regression
test described in Section 6.

- Check setup, cleanup, index ownership and the expected behaviour for
both index states.

- If that test design is not practical, discuss and implement an
appropriate alternative test.

- Build and run the test and record the result.

**Output:** A focused regression test or an agreed alternative, with
test results recorded.

### Weeks 6–7: Run Compatibility Tests and Submit for Review

- Run the relevant pathspec and sparse-checkout tests.

- Check the affected `git add` and `git rm` behaviour.

- Investigate sparse-index, prefixed and wildcard cases where they are
relevant to the selected change.

- Submit the focused patch to the Git community and provide test results.

- Respond to initial review comments and revise the patch where needed.

- Publish the required progress update and describe the work accurately.

**Output:** The initial contribution submitted for review, with
relevant test coverage and review feedback being addressed.

### Weeks 8–10: Review, Refine and Validate the Initial Contribution

- Prioritise maintainer feedback on the initial contribution.

- Revisit design decisions if reviewers identify a simpler or safer approach.

- Fix issues, update tests and rerun affected test suites after changes.

- Investigate any newly identified compatibility or lifetime concerns.

- Keep communication clear by explaining changes and reporting test results.

- Only if the initial contribution is in a stable, reviewable state,
discuss whether a small follow-up investigation is useful. Do not
assume a second implementation is required.

- If no follow-up is appropriate, use this period for further review,
testing and refinement of the initial patch.

**Output:** A more complete and carefully reviewed initial
contribution. A follow-up is optional and depends on mentor agreement
and available time.

### Week 11: Final Technical Review

- Review the complete patch and its rationale.

- Confirm that the tests cover the behaviour changed by the implementation.

- Address remaining review comments where possible.

- Run the relevant tests again after the final code changes.

- Record any unresolved issues or limitations honestly.

**Output:** A final refined patch or patch series, with its review and
testing status clearly recorded.

### Weeks 12–13: Final Validation, Documentation and Handover

- Run the final focused tests and any additional tests agreed with mentors.

- Review the final implementation, test results and outstanding review points.

- Document the design choice, changes made, test commands/results and
known limitations.

- Prepare a handover summary describing what was completed, what was
submitted, what was accepted or integrated if applicable, and what
remains.

- Complete the required Outreachy blog reports and final report.

**Output:** A tested and documented contribution, together with an
accurate handover and final report. The final status may be submitted,
under review, accepted or merged depending on the maintainers'
decisions; merging is not a guaranteed deliverable.

---

## Work-plan Flexibility

The above plan is a suggested timeline. I may need to make changes
based on technical issues, mentor guidance, or feedback from the
community. The aim is to create a small, useful, and well-tested
change. Any further changes to pathspec or its parser will only be
considered if there is a clear technical reason and mentors agree. The
first two weeks include a decision point: if the pathspec candidate is
unsuitable, overlaps with existing work, or cannot be given a clear
and testable design, I will discuss an alternative focused
contribution with mentors rather than force the proposed change. If
the two-index test is not practical, I will agree on an alternative
test strategy. If review takes longer than expected, I will prioritise
improving and validating the initial contribution rather than starting
a second refactor.

The aim is not to remove all global dependencies in Git. The aim is to
make a meaningful contribution by improving how repository and index
state are handled explicitly. If the initial pathspec change overlaps
with existing work or is not considered appropriate, I will discuss
alternative approaches with mentors and adjust the scope accordingly.

## Blogging and Progress Reports

During the internship, I will follow Outreachy's blogging
requirements. I understand that interns are expected to publish at
least three reports and to blog every two weeks about their
internship. I will use the introduction, midpoint and final report
prompts provided by Outreachy, and write shorter progress updates
between those reports when required.

My reports will cover:

- **Introduction:** Introduce myself, the Git community and the
project; explain why I applied, what I learned during the contribution
period, the contributions I am proud of, and what I hope to learn
during the internship.

- **Mid-point progress:** Describe the work completed so far, link to
contributions, explain technical challenges and what I learned from
mentors and the community, and mention any changes to the project
scope or timeline.

- **Final report:** Describe the results of my work and link to
contributions, explain what I learned, identify any remaining work or
ways the community could continue the work, and discuss my plans after
the internship.

I will also share shorter updates about my progress, implementation
decisions, testing results and challenges every two weeks. I will
follow the instructions and deadlines sent by Outreachy and make sure
that my reports accurately describe the work I have completed.

---

---

## 8. Risks and Mitigation

### Risk 1: Existing global dependencies are more widespread than expected

The pathspec implementation may contain additional dependencies on
`the_repository` or other repository-related global variables beyond
the helper identified during the preliminary investigation.

**Mitigation:**

- I will review the relevant functions and their callers before making
API changes.

- I will check how repository and index state are accessed and used.

- I will make changes incrementally, starting with the selected
skip-worktree helper.

- I will investigate any further dependencies before increasing the
scope of the change.

- I will not assume that a focused change has removed all global dependencies.

### Risk 2: Existing Git behavior may change accidentally

Changes to how the helper accesses index state may cause unwanted
changes to current pathspec matching and skip-worktree behavior.

**Mitigation:**

- I will analyse the current behaviour and document it.

- I will investigate and, if feasible, write a focused regression test
using two separate index states.

- I will check that the outcome depends on the index passed to the
helper, rather than the default global index.

- I will run focused tests covering relevant pathspec, `git add` and
`git rm` operations.

- I will check that existing behaviour, compatibility and error
handling are preserved.

### Risk 3: Sparse-checkout and sparse-index edge cases

The change may interact with current sparse-checkout behavior,
skip-worktree entries, or sparse-index behavior.

**Mitigation:**

- I will test relevant skip-worktree entries and check that they
behave as expected.

- I will test relevant pathspec forms, including prefixed and wildcard
pathspecs.

- I will run the relevant sparse-checkout tests.

- I will investigate sparse-index compatibility and look for possible
regressions.

- I will use sanitizers where appropriate.

### Risk 4: API changes may affect multiple callers

The helper may require changes to multiple callers. Some callers may
access repository or index state in different ways.

**Mitigation:**

- I will identify and review all known callers.

- I will check which repository or index context each caller uses.

- I will pay particular attention to `cmd_rm()` and how its repository
context should be used.

- I will compare the API options and discuss the most suitable
approach with maintainers.

- I will keep the resulting changes focused.

### Risk 5: Maintainer feedback or existing upstream work may change
the proposed scope

The pathspec change is still open for feedback. There may be other
changes by maintainers or contributors that affect its suitability or
scope.

**Mitigation:**

- Share the initial investigation and focused change early.

- Ask for feedback before making wider changes to pathspec.

- Check for upstream changes and possible overlap throughout the work.

- Adjust the implementation based on feedback from maintainers.

- If the scope is unsuitable or overlaps with existing work, discuss
an alternative contribution with my mentors.

### Risk 6: The proposed regression-test approach may not fit Git's
test infrastructure

The two-index regression test may require a different setup or
location based on Git's existing C unit-test conventions.

**Mitigation:**

- I will look at the existing C unit tests in Git.

- I will study how index states, cache entries and `CE_SKIP_WORKTREE`
are set up.

- I will make sure the test is placed in the appropriate location,
registered and cleaned up correctly.

- I will discuss the testing approach with maintainers if necessary.

- I will build Git, compile the test and run it to verify the implementation.

### Risk 7: Wrapper caching or index lifetime is handled incorrectly

Making the index explicit may expose issues if cached pathspec matches
are reused for a different index, or if a caller passes an index whose
lifetime or ownership is not appropriate.

**Mitigation:**

- I will inspect how the wrapper cache is keyed, populated and reused
before changing the API.

- I will verify whether the cache must be tied to the supplied index
or invalidated when the index context changes.

- I will trace the lifetime and ownership of each index pointer at the
affected callers.

- I will avoid retaining an index pointer beyond the lifetime
guaranteed by its owner.

- I will include these findings in the design discussion and add
focused tests for any cache behaviour that the selected change could
affect.

---

## 9. Communication and Review Strategy

Throughout the internship, I will keep in communication with the Git community.

My strategy will include:

- Using the public Git mailing list to communicate.

- Asking clear and specific technical questions.

- Submitting small, focused patches early to receive feedback.

- Carefully reviewing feedback from maintainers and contributors and
providing responses.

- Making necessary changes and resubmitting updated versions of the patches.

- Explaining the technical reasoning behind the implementation and API choices.

- Keeping patches concise, well-tested, and easy to review.

- Clearly stating test results, including any failures or limitations.

- Discussing any major changes to the proposal scope with my mentors.

During my initial research, I emailed the Git community on 2 November
2026 to ask whether my proposed pathspec contribution would be
suitable and to discuss the possible implementation approaches.

The discussion can be found here:

https://gitlist.dev/t/66745

I will use feedback from the Git community and my mentors to improve
my implementation approach. As the pathspec contribution has not yet
been approved, I will not consider it confirmed until I receive
guidance from maintainers.

---

## 10. Expected Outcomes and Deliverables

My primary goal is to complete one focused, technically justified
contribution that reduces the identified hidden index dependency in
the agreed part of Git's pathspec code, while preserving existing
behaviour.

The expected work and deliverables are:

- A documented analysis of the helper, wrapper, relevant callers,
cache behaviour and index ownership/lifetime.

- A comparison of the two API approaches: adding an explicit `struct
index_state \*istate` parameter to
`find_pathspecs_matching_skip_worktree()`, or extending
`find_pathspecs_matching_against_index()` with a clearly defined
`ps_skip_worktree_action` option.

- A design selected after technical investigation and discussion with
mentors and maintainers.

- One focused implementation of the agreed design, including only the
necessary changes to the helper/API, wrapper and affected callers.

- A focused regression test if Git's test infrastructure supports the
proposed approach, or an alternative test agreed during the
investigation.

- Relevant build and test results, including sparse-checkout and `git
add`/`git rm` checks where affected by the change.

- A patch explanation, review responses and revisions based on
maintainer feedback.

- A final summary of the implementation, tests performed, review
status and any remaining limitations.

Investigation of other pathspec functions, such as
`init_pathspec_item()`, `parse_pathspec()` or `parse_pathspec_file()`,
is optional follow-up work. It will only be pursued if the initial
contribution is in a stable state, there is a clear technical reason,
and mentors agree that it is appropriate.

The exact implementation and test deliverables will depend on the
technical findings and the design agreed with the Git community. I can
commit to careful investigation, focused implementation, testing and
review; I cannot promise that a patch will be accepted or merged
within the internship period.

---

## 11. Relevant Experience and Skills

During my preparation for this project, I have learned C programming
fundamentals, explored Git's source code, and gained practical
experience contributing to Git.

I have worked on the following:

- Learning C programming, including functions, structures, pointers,
function arguments, return values, and accessing structure members.

- Understanding global variables, global state, and explicit
dependencies, including how repository context can be passed to
functions.

- Exploring Git's source code, including `repository.c`,
`repository.h`, `environment.c`, `alias.c`, and `pathspec.c`.

- Understanding `the_repository` and `struct repository \*repo`, and
investigating how repository-specific state is accessed.

- Studying previous refactoring work, including how
`is_bare_repository_cfg` was split into separate responsibilities.

- Exploring repository configuration and state management, including
`core.attributesFile` and `core.hooksPath`.

- Using commands such as `git grep`, `git log`, `git show`, `git
diff`, and `sed` to explore Git's source code, understand its history,
and examine changes.

- Contributing to Git through changes involving test scripts,
test-path checks, safe integer arithmetic, and repository-aware commit
abbreviations for submodules.

- Creating and revising patches, responding to review feedback, and
learning how contributions are discussed within the Git community.

- Exploring Git's testing framework and understanding how tests help
verify existing behaviour.

This preparation has helped me understand the importance of repository
context, ownership of state, and careful refactoring in Git. Although
I am still developing my C programming and Git internals knowledge, I
have gained practical experience exploring Git's codebase and
contributing changes. I would like to build on this foundation by
making a focused contribution with appropriate testing during the
internship.

## 12. Availability and Commitment

I am available for this internship between 7 December 2026 and 8 March 2027.

I can dedicate around 30 hours per week to the internship.

During this period, I will:

- Consistently dedicate time to the project.

- Implement changes using an incremental approach.

- Take time to understand the existing codebase.

- Write tests and run them.

- Participate in discussions and communicate with my mentors and the
Git community.

- Take feedback into account and improve patches where needed.

- Keep track of my progress and communicate any issues.

I understand that contributing to an open-source project requires
continuous learning, patience, and teamwork. I will work consistently
on my contributions, learn from feedback, and aim to make a useful
contribution to the Git project.

## 13. References / Useful Links

The following links provide additional information about the Git
project and how to get involved. They also include examples of work I
have done previously and research I have carried out into the
technical side of my proposed contribution.

### Official Git Information

- Outreachy Project Selection for December 2026:
https://www.outreachy.org/apply/project-selection/

- Git Source Code: https://github.com/git/git

- Git Documentation: https://git-scm.com/docs

- Git Contribution Guidelines:
https://github.com/git/git/blob/master/Documentation/SubmittingPatches

- Git Coding Guidelines:
https://github.com/git/git/blob/master/Documentation/CodingGuidelines

- Git Mailing List: https://lore.kernel.org/git/

- Git General Application Information:
https://git.github.io/General-Application-Information/

- Git Microproject Information:
https://git.github.io/General-Microproject-Information/

### Previous Contributions

These are examples of contributions I have made to the Git project,
including work involving source code, test files, and preparing and
revising patches based on review feedback.

- PR #2260 – t0001: avoid pipes in test scripts:
https://github.com/gitgitgadget/git/pull/2260
  This was my microproject contribution. I updated the `t0001-init.sh`
test script to avoid using pipes.

- PR #2256 – t2030: modernize test path checks:
https://github.com/gitgitgadget/git/pull/2256
  This contribution modernizes the path checks in the `t2030` test.

- PR #2276 – diff-delta: use safe integer arithmetic:
https://github.com/gitgitgadget/git/pull/2276
  This contribution updates the integer arithmetic used in
`diff-delta` to use safer operations.

- PR #2288 – t4041: use submodule repository for commit abbreviations:
https://github.com/gitgitgadget/git/pull/2288
  This contribution uses the submodule's repository context when
determining commit abbreviations.

Mailing-list versions of these contributions:

- PR #2260 v2: https://lore.kernel.org/git/pull.2260.v2.git.1792666211685.gitgitgadget@gmail.com

- PR #2256 v3: https://lore.kernel.org/git/pull.2256.v3.git.1792299943380.gitgitgadget@gmail.com

- PR #2276 v9: https://lore.kernel.org/git/pull.2276.v9.git.1793120160248.gitgitgadget@gmail.com

### Relevant Source Code and Tests

- `pathspec.c`: https://github.com/git/git/blob/master/pathspec.c

- `pathspec.h`: https://github.com/git/git/blob/master/pathspec.h

- `builtin/add.c`: https://github.com/git/git/blob/master/builtin/add.c

- `builtin/rm.c`: https://github.com/git/git/blob/master/builtin/rm.c

- Sparse-checkout tests for `git add`:
https://github.com/git/git/blob/master/t/t3705-add-sparse-checkout.sh

- Sparse-checkout tests for `git rm`:
https://github.com/git/git/blob/master/t/t3602-rm-sparse-checkout.sh

### Research into the Project

Discussion about the scope of the proposed pathspec contribution,
including possible API approaches and whether related work is already
planned.

https://gitlist.dev/t/66745 (2 November 2026)

Background on previous changes involving repository state and global
dependencies:

- Git v2.56.0 release notes:
https://github.com/git/git/blob/master/Documentation/RelNotes/2.56.0.adoc

- Commit `7ff3a5895b`, which split the concerns of
`is_bare_repository_cfg`: https://github.com/git/git/commit/7ff3a5895b

- Commit `dd674df326`, which uses `item.match` consistently for
sparse-index expansion checks and adds coverage for prefixed wildcard
pathspecs: https://github.com/git/git/commit/dd674df326

- Git's official 2026 GSoC ideas page, including the project
'Refactoring in order to reduce Git's global state':
https://git.github.io/SoC-2026-Ideas/

## Acknowledgements

I would like to thank Usman Akinyemi, Junio C Hamano, Patrick
Steinhardt, Harald Nordgren, Phillip Wood, Pablo Sabater, Okhuomon
Ajayi, my mentors, maintainers, and members of the Git community for
taking the time to review my contributions, answer my questions, and
share their technical feedback. Their guidance and effort have helped
me understand the codebase better, improve my patches, and learn from
the contribution and review process. I sincerely appreciate their time
and support.

## 14. Conclusion

Reducing global state makes dependencies clearer and helps Git move
towards being usable as a library. During my preparation, I explored
Git's source code, read about earlier refactoring work, and
investigated how repository and index information are used in pathspec
processing.

My initial area of interest is
`find_pathspecs_matching_skip_worktree()`, which currently gets the
index through `the_repository->index`. I want to investigate how this
dependency could be made explicit. I will compare adding a `struct
index_state \*istate` parameter to the specialised helper with
extending the existing `find_pathspecs_matching_against_index()` API.
I will discuss the options with mentors and maintainers before
deciding which approach is most suitable.

I also want to investigate a regression test using two separate index
states, if Git's test infrastructure supports that approach. The test
should help check that the helper uses the index supplied by its
caller and that existing pathspec and skip-worktree behaviour is
preserved. Any further pathspec changes will depend on what I find and
on feedback from mentors and maintainers.

I know that this work will involve learning more about Git's code,
testing carefully and responding to review feedback. I hope to build
on the preparation I have already done and make a focused contribution
to the Git project.


```
