[GSoC][Draft Proposal] Refactoring in order to reduce Git's global state

[GSoC][Draft Proposal] Refactoring in order to reduce Git's global state

[Tian Yuchen]

Hi everyone,

I'm Tian Yuchen and I'm planning to apply for GSoC this year!

Instead of pasting a giant wall of text into this email, I have
drafted my proposal in Google Doc. I thought it might be easier for
everyone to leave inline comments and suggestions there. (Of course, if 
you're more accustomed to email replies, you can also quote the content 
from the doc in your response. Thank you.)

Here is the link:

https://docs.google.com/document/d/1t2sznOvnPz-9tOzVMH--pLxzRqYSJCFzqVWBVfL_NP8/edit?tab=t.0#heading=h.c3c40ftj1ilv

Feel free to provide feedback!

Regards,

Yuchen

Re: [GSoC][Draft Proposal] Refactoring in order to reduce Git's global state

[Usman Akinyemi]

On Sun, Feb 22, 2026 at 11:29 PM Tian Yuchen <a3205153416@gmail.com> wrote:
>
> Hi everyone,
>
> I'm Tian Yuchen and I'm planning to apply for GSoC this year!
>
> Instead of pasting a giant wall of text into this email, I have
> drafted my proposal in Google Doc. I thought it might be easier for
> everyone to leave inline comments and suggestions there. (Of course, if
> you're more accustomed to email replies, you can also quote the content
> from the doc in your response. Thank you.)
I believe that a giant wall of text is the appropriate way to send a
proposal to the
Git community. I will advise you to send that giant of text actually.
It is easier for the
community to review and give feedback. Also future gsoc participants
can also learn
from it. By telling the reviewer to go through the link to the docs
and then copy it on the
to the email just to reply is giving them an extra lot of work to do.
So send it through text
and make it easy for people to review.
>
>
Thank you.

Re: [GSoC][Draft Proposal] Refactoring in order to reduce Git's global state

[Tian Yuchen]

On 2/23/26 02:34, Usman Akinyemi wrote:
> On Sun, Feb 22, 2026 at 11:29 PM Tian Yuchen <a3205153416@gmail.com> wrote:
>>
>> Hi everyone,
>>
>> I'm Tian Yuchen and I'm planning to apply for GSoC this year!
>>
>> Instead of pasting a giant wall of text into this email, I have
>> drafted my proposal in Google Doc. I thought it might be easier for
>> everyone to leave inline comments and suggestions there. (Of course, if
>> you're more accustomed to email replies, you can also quote the content
>> from the doc in your response. Thank you.)
> I believe that a giant wall of text is the appropriate way to send a
> proposal to the
> Git community. I will advise you to send that giant of text actually.
> It is easier for the
> community to review and give feedback. Also future gsoc participants
> can also learn
> from it. By telling the reviewer to go through the link to the docs
> and then copy it on the
> to the email just to reply is giving them an extra lot of work to do.
> So send it through text
> and make it easy for people to review.
>>
>>
> Thank you.

Makes sense. I will format the proposal into plain text and send it as 
v2 shortly so it's easier to review inline and properly archived.

Thanks,

Yuchen

[GSoC][Draft Proposal V2] Refactoring in order to reduce Git's global state

[Tian Yuchen]

Hello everyone,

I'm Tian Yuchen and I'm planning to apply for GSoC project this year. I 
hope you can take the time to review my proposal.

Please feel free to leave feedback!

Google Docs link:

https://docs.google.com/document/d/1t2sznOvnPz-9tOzVMH--pLxzRqYSJCFzqVWBVfL_NP8/edit?tab=t.0#heading=h.c3c40ftj1ilv




Refactoring in order to reduce Git's global state
=================================================

PERSONAL INFORMATION
--------------------
Name: Tian Yuchen
E-mail: a3205153416@gmail.com
Phone number: +65 98740318
Time-zone: UTC + 08:00
Github: https://github.com/malon7782

Education: NTU, Singapore
Year: Year 1 semester 2
Degree: Electrical and Electronic Engineering (EEE)


PRE GSOC
--------
I have always held a deep passion for the open-source community. 
Although I wasn't a computer science major, I tinkered with open-source 
projects long before college. I have solid hands-on experience in C 
programming and system-level debugging.

I use Ubuntu 24.04 on a daily basis, so I am proficient in using the 
Linux command line and CLI tools.

I have contributed to the Git community by sending patches. Since my 
first commit (17/1/2026), I have maintained a nearly daily contribution. 
Here is the list of contributions I have made:

* [PATCH v1] t1005: modernize "! test -f" to "test_path_is_missing"
  
https://lore.kernel.org/git/20260117062515.319664-1-a3205153416@gmail.com/
   This patch is my microproject, the first contribution I made to the 
codebase.
   [Graduated to 'master']

* [PATCH v2] t2203: avoid masking exit codes in git status
  
https://lore.kernel.org/git/20260118043537.338769-1-a3205153416@gmail.com/#t

* [PATCH v2] symlinks: use unsigned int for flags
  
https://lore.kernel.org/git/20260120152219.398999-1-a3205153416@gmail.com/
   [Will merge to 'next']

* [PATCH v4] t/perf/p3400: speed up setup using fast-import
  
https://lore.kernel.org/git/20260130170123.642344-1-a3205153416@gmail.com/
   [Will merge to 'master']

* Re: [PATCH] [RFC] attr: use local repository state in read_attr
  
https://lore.kernel.org/git/cc2f400e-49c2-4de0-9c51-9a5c0294735e@gmail.com/
   Code review. To verify the performance loss, I wrote a test script to
   measure the time difference before and after the modification.

* Re: Bug: git add :!x . exits with error when x is in .gitignore
  
https://lore.kernel.org/git/1d560aa1-d452-47f5-aaf2-4cb1ccdab100@gmail.com/
   Code review. Pointed out logical error.

* [PATCH v10] setup: allow cwd/.git to be a symlink to a directory
  
https://lore.kernel.org/git/20260220164512.216901-1-a3205153416@gmail.com/
   In progress.
   After over half a month of discussions, repeated refactoring, and code
   reviews, I delved deep into setup.c. I gained insights into Git's 
design philosophy, and learned the art of striking a balance in 
developer communication. It took me a large amount of time and effort to 
thoroughly understand every line of the code. I often found myself 
poring over the call chain of a single function well into the night.... 
But I persevered until the end, and I believe my patience will see me 
through even larger projects.


ABOUT THE PROJECT
-----------------

-- Synopsis

As far as I know, the Git community is actively working towards 
'libification' - making Git's internal machinery reusable as a C 
library. The extensive reliance on global state is a major roadblock to 
this goal.

Many core functions implicitly read environment variables and store them 
in global static variables. This can cause several issues:

   1. Global variables prevent Git's core functions from being executed 
safely in multi-threaded contexts.
   2. When Git is called multiple times within the same process, global 
states can lead to memory leaks or incorrect behaviors.
   3. Unit testing becomes difficult because the environment must be 
artificially manipulated before calling functions.

Take a look at this example from environment.c:

     206 const char *get_commit_output_encoding(void)
     207 {
     208     return git_commit_encoding ? git_commit_encoding : "UTF-8";
     209 }

If Git is invoked as a C library by a multi-threaded server:
- Thread A formats a commit for Repo A (using GBK);
- Thread B concurrently formats a commit for Repo B (using UTF-8);

Then they will race to read and overwrite the exact same global
`git_commit_encoding` pointer, which is not what we expect. Therefore,
we have to refactor these environment variables by moving them from
global scope into a well-defined and encapsulated context.


-- Approach

The task at hand can be summed up in one sentence: repackage the global
variables into the `struct repository` structure. In other words:

     [ Current ]
     Core functions --------reads-------> Global variables (via getenv)
                                          [Thread unsafe]

     [ Target ]
     Core functions ----passes context--> struct repository
                                                 | owns
                                                 v
                                          struct git_env

Although the principle is simple, the scope of changes is extensive. The
following three-step approach can serve as a guiding principle for it:

   1. Identify isolated environment variables currently residing in the
      global scope. Introduce a dedicated structure to hold these states,
      e.g. `struct git_env` within the `struct repository`.
   2. Modify the function signatures within the call chain to accept the
      context, e.g., `struct repository *repo`, instead of relying on
      implicit globals. External callers of the functions must be
      carefully audited to prevent regressions.
   3. Safely remove the old global variables and macro definitions. Tools
      such as AddressSanitizer can be helpful to ensure that the new
      struct-based lifecycle introduces zero memory leaks.

Additionally, given the anticipated high volume of commits, we must 
ensure each patch is independent and atomic, preventing any 
user-untraceable or unexplainable bugs from occurring in the codebase at 
any state.


AVAILABILITY
------------
Fortunately, my summer vacation coincides with the GSoC work period.
I will treat this project as my primary focus, dedicating a minimum of
35 hours per week. If needed, I can work a 9-to-5 schedule.

I will have a significant head start to draft RFC patches before the
official coding period even begins. Having this buffer period allows me
to go through the rigorous code review process within the Git community
with greater ease.


TIMELINE & MILESTONES
---------------------
Considering the differences between this project and other projects on 
the idea list, rather than hoarding massive changes, I will submit 
3-to-5-patch series frequently to respect reviewers' time and maintain a 
steady velocity.

Below is the tentative schedule I have prepared for myself:

* Community Bonding (May 1 - May 25): Planning & RFC
   - May 1 - May 7: Wrap up university finals. Discuss and finalize the
     prioritized list of subsystems with my mentor.
   - May 8 - May 25: Define the core context container. Draft and submit
     the initial RFC patch series for this new data structure.

* Phase 1 (May 26 - July 10): Foundation
   - Weeks 1-2: Plumb the context pointer (`struct repository *repo`) 
through call chains for simple variables (e.g., boolean flags or integer 
configs).
   - Weeks 3-4: Audit and update external callers to use the new API.
   - Weeks 5-6: Submit the first major refactoring patch series. Address
     mailing list feedback and resolve merge conflicts. (Midterm Evaluation)

* Phase 2 (July 11 - August 18): Complex Migration & Cleanup
   - Weeks 7-8: Refactor higher-complexity variables (e.g., path-related 
globals).
   - Weeks 9-10: Compile the codebase with AddressSanitizer and run the 
full test suite to execute strict memory leak checks.
   - Weeks 11-12: Remove unused global macro definitions and static 
variables. Update internal documentation and write the final GSoC report.

(The above is for reference only. Personally, I always finish tasks 
faster than planned ;)


~$ git checkout HEAD@{postGSoC}
-------------------------------
This past month since joining the Git community has been the most 
enjoyable month of my programming journey. To quote a close friend of 
mine (who is applying for the Neovim GSoC project):

   "Only fools chase trends; open source is the game for the brave."

The words may be blunt, but the logic holds true. This statement surely
resonates with me (and maybe many other GSoC contributors): our passion
for code and open-source drives us forward.

Even if I didn't make the cut, so what? ~$ git reset --hard...
Just kidding. The Git codebase is far too interesting to abandon now.

-------------------------------------------------------------------------
Changes since V1:

  - Transfer the text from Google Docs to here.



Regards,

Yuchen

Re: [GSoC][Draft Proposal v3] Refactoring in order to reduce Git's global state

[Tian Yuchen]

Hi mentors and the git community,

Here is the proposal V3.


Refactoring in order to reduce Git's global state
=================================================

PERSONAL INFORMATION
--------------------
Name: Tian Yuchen
E-mail: a3205153416@gmail.com
Phone number: +65 98740318
Time-zone: UTC + 08:00
Github: https://github.com/malon7782

Education: NTU, Singapore
Year: Year 1 semester 2
Degree: Electrical and Electronic Engineering (EEE)


PRE GSOC
--------
I have always held a deep passion for the open-source community. 
Although I wasn't a computer science major, I tinkered with open-source 
projects long before college. I have solid hands-on experience in C 
programming and system-level debugging.

I use Ubuntu 24.04 on a daily basis, so I am proficient in using the 
Linux command line and CLI tools.

I have contributed to the Git community by sending patches. Since my 
first commit (17/1/2026), I have maintained a nearly daily contribution. 
Here is the list of contributions I have made:

* [PATCH v1] t1005: modernize "! test -f" to "test_path_is_missing"

https://lore.kernel.org/git/20260117062515.319664-1-a3205153416@gmail.com/
   This patch is my microproject, the first contribution I made to the 
codebase.
   [Graduated to 'master']

* [PATCH v2] t2203: avoid masking exit codes in git status

https://lore.kernel.org/git/20260118043537.338769-1-a3205153416@gmail.com/#t

* [PATCH v2] symlinks: use unsigned int for flags

https://lore.kernel.org/git/20260120152219.398999-1-a3205153416@gmail.com/
   [Will merge to 'next']

* [PATCH v4] t/perf/p3400: speed up setup using fast-import

https://lore.kernel.org/git/20260130170123.642344-1-a3205153416@gmail.com/
   [Will merge to 'master']

* Re: [PATCH] [RFC] attr: use local repository state in read_attr

https://lore.kernel.org/git/cc2f400e-49c2-4de0-9c51-9a5c0294735e@gmail.com/
   Code review. To verify the performance loss, I wrote a test script to
   measure the time difference before and after the modification.

* Re: Bug: git add :!x . exits with error when x is in .gitignore

https://lore.kernel.org/git/1d560aa1-d452-47f5-aaf2-4cb1ccdab100@gmail.com/
   Code review. Pointed out logical error.

* [PATCH v10] setup: allow cwd/.git to be a symlink to a directory

https://lore.kernel.org/git/20260220164512.216901-1-a3205153416@gmail.com/
   [Under review]
   After over half a month of discussions, repeated refactoring, and code
   reviews, I delved deep into setup.c. I gained insights into Git's 
design philosophy, and learned the art of striking a balance in 
developer communication. It took me a large amount of time and effort to 
thoroughly understand every line of the code. I often found myself 
poring over the call chain of a single function well into the night.... 
But I persevered until the end, and I believe my patience will see me 
through even larger projects.


ABOUT THE PROJECT
-----------------

-- Synopsis

As far as I know, the Git community is actively working towards 
'libification' - making Git's internal machinery reusable as a C 
library. The extensive reliance on global state is a major roadblock to 
this goal.

Many core functions implicitly read environment variables and store them 
in global static variables. This can cause several issues:

   1. Global variables prevent Git's core functions from being executed 
safely in multi-threaded contexts. For example, When unexpected states 
(e.g., a permission denied error when probing a directory), they often 
rely on the global state to decide whether to call die(), which 
internally calls exit(). It’s fine for a standalone CLI tool, but for a 
linked C library used by a long-running multi-threaded server, a single 
die() call will kill the entire host process. Structured status, instead 
of fatal exits, should be returned.
   2. When Git is called multiple times within the same process, global 
states can lead to memory leaks or incorrect behaviors.
   3. Unit testing becomes difficult because the environment must be 
artificially manipulated before calling functions.

Take a look at this example from environment.c:

     206 const char *get_commit_output_encoding(void)
     207 {
     208     return git_commit_encoding ? git_commit_encoding : "UTF-8";
     209 }

If Git is invoked as a C library by a multi-threaded server:
- Thread A formats a commit for Repo A (using GBK);
- Thread B concurrently formats a commit for Repo B (using UTF-8);

Then they will race to read and overwrite the exact same global
`git_commit_encoding` pointer, which is not what we expect. Therefore,
we have to refactor these environment variables by moving them from
global scope into a well-defined and encapsulated context.


-- Approach

The task at hand goes beyond simply repackaging the global variables 
into the struct repository structure. Based on my recent experience 
refactoring setup.c, I realized that libification requires careful 
management of variable lifecycles and api boundaries:

     [ Current ]
     Core functions --------reads-------> Global variables (via getenv)
                                          [Thread unsafe]

     [ Target ]
     Core functions ----passes context--> struct repository
                                                 | owns
                                                 v
                                          struct git_env

Although the principle is simple, the scope of changes is extensive. The
following three-step approach can serve as a guiding principle for it:

   1. Identify isolated environment variables currently residing in the
      global scope. Introduce a dedicated structure to hold these states,
      e.g. `struct git_env` within the `struct repository`.
   2. Instead of blindly passing struct repository *repo down into every
      single low-level library function, bubbling the dependency up is
      the true goal. External callers of the functions must be carefully
      audited to prevent regressions.
   3. Safely remove the old global variables and macro definitions. Tools
      such as AddressSanitizer can be helpful to ensure that the new
      struct-based lifecycle introduces zero memory leaks.
   4. Many globals like are parsed once and remain available globally.
      New data flow might need to be designed to maintain the lazy-
      loading efficiency.

Additionally, given the anticipated high volume of commits, we must 
ensure each patch is independent and atomic, preventing any 
user-untraceable or unexplainable bugs from occurring in the codebase at 
any state.


AVAILABILITY
------------
Fortunately, my summer vacation coincides with the GSoC work period.
I will treat this project as my primary focus, dedicating a minimum of
35 hours per week. If needed, I can work a 9-to-5 schedule.

I will have a significant head start to draft RFC patches before the
official coding period even begins. Having this buffer period allows me
to go through the rigorous code review process within the Git community
with greater ease.


TIMELINE & MILESTONES
---------------------
Considering the differences between this project and other projects on 
the idea list, rather than hoarding massive changes, I will submit 
3-to-5-patch series frequently to respect reviewers' time and maintain a 
steady velocity.

Below is the tentative schedule I have prepared for myself:

* Community Bonding (May 1 - May 25): Planning & RFC
   - May 1 - May 7: Wrap up university finals. Discuss and finalize the
     prioritized list of subsystems with my mentor.
   - May 8 - May 25: Define the core context container. Draft and submit
     the initial RFC patch series for this new data structure.

* Phase 1 (May 26 - July 10): Foundation
   - Weeks 1-2: Plumb the context pointer (`struct repository *repo`) 
through call chains for simple variables (e.g., boolean flags or integer 
configs).
   - Weeks 3-4: Audit and update external callers to use the new API.
   - Weeks 5-6: Submit the first major refactoring patch series. Address
     mailing list feedback and resolve merge conflicts. (Midterm Evaluation)

* Phase 2 (July 11 - August 18): Complex Migration & Cleanup
   - Weeks 7-8: Refactor higher-complexity variables (e.g., path-related 
globals).
   - Weeks 9-10: Compile the codebase with AddressSanitizer and run the 
full test suite to execute strict memory leak checks.
   - Weeks 11-12: Remove unused global macro definitions and static 
variables. Update internal documentation and write the final GSoC report.

(The above is for reference only. Personally, I always finish tasks 
faster than planned 😉)


~$ git checkout HEAD@{postGSoC}
-------------------------------
This past month since joining the Git community has been the most 
enjoyable month of my programming journey. To quote a close friend of 
mine (who is applying for the Neovim GSoC project):

   "Only fools chase trends; open source is the game for the brave."

The words may be blunt, but the logic holds true. This statement surely
resonates with me (and maybe many other GSoC contributors): our passion
for code and open-source drives us forward.

Even if I didn't make the cut, so what? ~$ git reset --hard...
Just kidding. The Git codebase is far too interesting to abandon now.

-------------------------------------------------------------------------
Changes since V3:

  - Based on reviewing last year's contributors' changes and recent 
experience modifying setup.c, additional descriptions have been added to 
the synopsis & approach section.

Re: [GSoC][Draft Proposal v3] Refactoring in order to reduce Git's global state

[Karthik Nayak]

[-- Attachment #1: Type: text/plain, Size: 5926 bytes --]

Tian Yuchen <a3205153416@gmail.com> writes:

Hello Tian,

> Hi mentors and the git community,
>
> Here is the proposal V3.
>

[snip]

>
> -- Approach
>
> The task at hand goes beyond simply repackaging the global variables
> into the struct repository structure. Based on my recent experience
> refactoring setup.c, I realized that libification requires careful
> management of variable lifecycles and api boundaries:
>
>      [ Current ]
>      Core functions --------reads-------> Global variables (via getenv)
>                                           [Thread unsafe]
>
>      [ Target ]
>      Core functions ----passes context--> struct repository
>                                                  | owns
>                                                  v
>                                           struct git_env
>
> Although the principle is simple, the scope of changes is extensive. The
> following three-step approach can serve as a guiding principle for it:
>
>    1. Identify isolated environment variables currently residing in the
>       global scope. Introduce a dedicated structure to hold these states,
>       e.g. `struct git_env` within the `struct repository`.

Well it depends, we already have `struct repo_settings`, and individual
settings within the `struct repository` struct. It would be a very case
by case basis, to understand which variables fit where.

>    2. Instead of blindly passing struct repository *repo down into every
>       single low-level library function, bubbling the dependency up is
>       the true goal. External callers of the functions must be carefully
>       audited to prevent regressions.
>    3. Safely remove the old global variables and macro definitions. Tools
>       such as AddressSanitizer can be helpful to ensure that the new
>       struct-based lifecycle introduces zero memory leaks.

Yes, we also have CI jobs for GitLab and GitHub which do this already,
you can run them locally too, meson makes it very easy to do this too:

  $ meson setup address --fatal-meson-warnings --warnlevel 3 --werror \
  --wrap-mode nofallback -Dfuzzers=true -Db_sanitize=address \
  -Db_lundef=false
  $ cd address
  $ meson test

>    4. Many globals like are parsed once and remain available globally.

I think you're missing a reference in this sentence.

>       New data flow might need to be designed to maintain the lazy-
>       loading efficiency.
>
> Additionally, given the anticipated high volume of commits, we must
> ensure each patch is independent and atomic, preventing any
> user-untraceable or unexplainable bugs from occurring in the codebase at
> any state.
>
>
> AVAILABILITY
> ------------
> Fortunately, my summer vacation coincides with the GSoC work period.
> I will treat this project as my primary focus, dedicating a minimum of
> 35 hours per week. If needed, I can work a 9-to-5 schedule.
>
> I will have a significant head start to draft RFC patches before the
> official coding period even begins. Having this buffer period allows me
> to go through the rigorous code review process within the Git community
> with greater ease.
>
>
> TIMELINE & MILESTONES
> ---------------------
> Considering the differences between this project and other projects on
> the idea list, rather than hoarding massive changes, I will submit
> 3-to-5-patch series frequently to respect reviewers' time and maintain a
> steady velocity.
>
> Below is the tentative schedule I have prepared for myself:
>
> * Community Bonding (May 1 - May 25): Planning & RFC
>    - May 1 - May 7: Wrap up university finals. Discuss and finalize the
>      prioritized list of subsystems with my mentor.
>    - May 8 - May 25: Define the core context container. Draft and submit
>      the initial RFC patch series for this new data structure.
>

What is the 'core context container' here?

> * Phase 1 (May 26 - July 10): Foundation
>    - Weeks 1-2: Plumb the context pointer (`struct repository *repo`)
> through call chains for simple variables (e.g., boolean flags or integer
> configs).
>    - Weeks 3-4: Audit and update external callers to use the new API.
>    - Weeks 5-6: Submit the first major refactoring patch series. Address
>      mailing list feedback and resolve merge conflicts. (Midterm Evaluation)
>
> * Phase 2 (July 11 - August 18): Complex Migration & Cleanup
>    - Weeks 7-8: Refactor higher-complexity variables (e.g., path-related
> globals).
>    - Weeks 9-10: Compile the codebase with AddressSanitizer and run the
> full test suite to execute strict memory leak checks.
>    - Weeks 11-12: Remove unused global macro definitions and static
> variables. Update internal documentation and write the final GSoC report.
>
> (The above is for reference only. Personally, I always finish tasks
> faster than planned 😉)
>
>
> ~$ git checkout HEAD@{postGSoC}
> -------------------------------
> This past month since joining the Git community has been the most
> enjoyable month of my programming journey. To quote a close friend of
> mine (who is applying for the Neovim GSoC project):
>
>    "Only fools chase trends; open source is the game for the brave."
>
> The words may be blunt, but the logic holds true. This statement surely
> resonates with me (and maybe many other GSoC contributors): our passion
> for code and open-source drives us forward.
>
> Even if I didn't make the cut, so what? ~$ git reset --hard...
> Just kidding. The Git codebase is far too interesting to abandon now.
>
> -------------------------------------------------------------------------
> Changes since V3:
>
>   - Based on reviewing last year's contributors' changes and recent
> experience modifying setup.c, additional descriptions have been added to
> the synopsis & approach section.

Thanks for the proposal :)

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]

Re: [GSoC][Draft Proposal v3] Refactoring in order to reduce Git's global state

[Tian Yuchen]

Hi karthik,

Thank you so much for the review.

> Well it depends, we already have `struct repo_settings`, and individual
> settings within the `struct repository` struct. It would be a very case
> by case basis, to understand which variables fit where.

That makes sense to me. I will update the approach to emphasize a 
case-to-case analysis & mapping variables to their rightful existing homes.

> Yes, we also have CI jobs for GitLab and GitHub which do this already,
> you can run them locally too, meson makes it very easy to do this too:

Thank you for providing the information above. I have integrated this 
into the V4 proposal. It indeed looks much more robust in terms of 
memory leak auditing and other checks.

> I think you're missing a reference in this sentence.

Sorry that was a typo. While writing the proposal, I went back to the 
source code to confirm the function name here, but I forgot to add it 
back in LOL. I meant 'editor_program' :)

> What is the 'core context container' here?

Emmmm...It was referring to the 'struct git_env' idea (or something like 
that), which is flawed as you mentioned earlier. Will revise the 
timeline: the bonding period will be spent categorizing the targeted 
global variables and determining their appropriate stuctural 
destinations (via RFC patches? I don't know if it's proper behavior).

> Thanks for the proposal :)

Will incorporate all these refinements and send out V4 within ~3 days (I 
have midterm tests these days). Thanks again for your time and patience ;)

Regards,

Yuchen

Re: [GSoC][Draft Proposal v3] Refactoring in order to reduce Git's global state

[Tian Yuchen]

Hi karthink,

One thing I forgot to mention—I plan to practice with a simple target 
following the proposal's process to see if it works in the coming days. 
If you have time to review it and offer some feedback, I'd be most grateful!

Thanks,

Yuchen

Re: [GSoC][Draft Proposal v4] Refactoring in order to reduce Git's global state

[Tian Yuchen]

Hi all,

Here is the V4 patch.

Thanks Karthink Nayak <karthink.188@gamil.com>, for help and guidance.


Refactoring in order to reduce Git's global state
=================================================

PERSONAL INFORMATION
--------------------
Name: Tian Yuchen
E-mail: a3205153416@gmail.com
Phone number: +65 98740318
Time-zone: UTC + 08:00
Github: https://github.com/malon7782

Education: NTU, Singapore
Year: Year 1 semester 2
Degree: Electrical and Electronic Engineering (EEE)


PRE GSOC
--------
I have always held a deep passion for the open-source community. 
Although I wasn't a computer science major, I tinkered with open-source 
projects long before college. I have solid hands-on experience in C 
programming and system-level debugging.

I use Ubuntu 24.04 on a daily basis, so I am proficient in using the 
Linux command line and CLI tools.

I have contributed to the Git community by sending patches. Since my 
first commit (17/1/2026), I have maintained a nearly daily contribution. 
Here is the list of contributions I have made:

* [PATCH v1] t1005: modernize "! test -f" to "test_path_is_missing"

https://lore.kernel.org/git/20260117062515.319664-1-a3205153416@gmail.com/
   This patch is my microproject, the first contribution I made to the 
codebase.
   [Graduated to 'master']

* [PATCH v2] t2203: avoid masking exit codes in git status

https://lore.kernel.org/git/20260118043537.338769-1-a3205153416@gmail.com/#t

* [PATCH v2] symlinks: use unsigned int for flags

https://lore.kernel.org/git/20260120152219.398999-1-a3205153416@gmail.com/
   [Will merge to 'next']

* [PATCH v4] t/perf/p3400: speed up setup using fast-import

https://lore.kernel.org/git/20260130170123.642344-1-a3205153416@gmail.com/
   [Will merge to 'master']

* Re: [PATCH] [RFC] attr: use local repository state in read_attr

https://lore.kernel.org/git/cc2f400e-49c2-4de0-9c51-9a5c0294735e@gmail.com/
   Code review. To verify the performance loss, I wrote a test script to
   measure the time difference before and after the modification.

* Re: Bug: git add :!x . exits with error when x is in .gitignore

https://lore.kernel.org/git/1d560aa1-d452-47f5-aaf2-4cb1ccdab100@gmail.com/
   Code review. Pointed out logical error.

* [PATCH v10] setup: allow cwd/.git to be a symlink to a directory

https://lore.kernel.org/git/20260220164512.216901-1-a3205153416@gmail.com/
   [Under review]
   After over half a month of discussions, repeated refactoring, and code
   reviews, I delved deep into setup.c. I gained insights into Git's 
design philosophy, and learned the art of striking a balance in 
developer communication. It took me a large amount of time and effort to 
thoroughly understand every line of the code. I often found myself 
poring over the call chain of a single function well into the night.... 
But I persevered until the end, and I believe my patience will see me 
through even larger projects.


ABOUT THE PROJECT
-----------------

-- Synopsis

As far as I know, the Git community is actively working towards 
'libification' - making Git's internal machinery reusable as a C 
library. The extensive reliance on global state is a major roadblock to 
this goal.

Many core functions implicitly read environment variables and store them 
in global static variables. This can cause several issues:

   1. Global variables prevent Git's core functions from being executed 
safely in multi-threaded contexts. For example, When unexpected states 
(e.g., a permission denied error when probing a directory), they often 
rely on the global state to decide whether to call die(), which 
internally calls exit(). It’s fine for a standalone CLI tool, but for a 
linked C library used by a long-running multi-threaded server, a single 
die() call will kill the entire host process. Structured status, instead 
of fatal exits, should be returned.
   2. When Git is called multiple times within the same process, global 
states can lead to memory leaks or incorrect behaviors.
   3. Unit testing becomes difficult because the environment must be 
artificially manipulated before calling functions.

Take a look at this example from environment.c:

     206 const char *get_commit_output_encoding(void)
     207 {
     208     return git_commit_encoding ? git_commit_encoding : "UTF-8";
     209 }

If Git is invoked as a C library by a multi-threaded server:
- Thread A formats a commit for Repo A (using GBK);
- Thread B concurrently formats a commit for Repo B (using UTF-8);

Then they will race to read and overwrite the exact same global
`git_commit_encoding` pointer, which is not what we expect. Therefore,
we have to refactor these environment variables by moving them from
global scope into a well-defined and encapsulated context.


-- Approach

The task at hand goes beyond simply repackaging the global variables 
into the struct repository structure. Based on my recent experience 
refactoring setup.c, I realized that libification requires careful 
management of variable lifecycles and api boundaries:

     [ Current ]
     Core functions --------reads-------> Global variables (via getenv)
                                          [Thread unsafe]

     [ Target ]
     Core functions ----passes context--> struct repository
                                                 | owns
                                                 v
                                          struct repo_settings

				         other domain-specific structs

Although the principle is simple, the scope of changes is extensive. The
following three-step approach can serve as a guiding principle for it:

   1. Identify isolated environment variables currently residing in the
      global scope. Conduct a case-by-case analysis to map each variable
      to its most appropriate existing home (e.g., struct repo_settings
      for configuration values, or specific localized structs within
      struct repository).
   2. Instead of blindly passing struct repository *repo down into every
      single low-level library function, bubbling the dependency up is
      the true goal. External callers of the functions must be carefully
      audited to prevent regressions.
   3. Safely remove the old global variables and macro definitions. Make
      full use of Git's existing GitLab/GitHub CI and utilize local
      Meson builds with AddressSanitizer enabled to ensure that the new
      lifecycle introduces zero memory leaks.
   4. Many globals like `editor_program` are parsed once and remain
      available globally. New data flow might need to be designed to
      maintain the lazy-loading efficiency.

Additionally, given the anticipated high volume of commits, we must 
ensure each patch is independent and atomic, preventing any 
user-untraceable or unexplainable bugs from occurring in the codebase at 
any state.


AVAILABILITY
------------
Fortunately, my summer vacation coincides with the GSoC work period.
I will treat this project as my primary focus, dedicating a minimum of
35 hours per week. If needed, I can work a 9-to-5 schedule.

I will have a significant head start to draft RFC patches before the
official coding period even begins. Having this buffer period allows me
to go through the rigorous code review process within the Git community
with greater ease.


TIMELINE & MILESTONES
---------------------
Considering the differences between this project and other projects on 
the idea list, rather than hoarding massive changes, I will submit 
3-to-5-patch series frequently to respect reviewers' time and maintain a 
steady velocity.

Below is the tentative schedule I have prepared for myself:

* Community Bonding (May 1 - May 25): Planning & RFC
   - May 1 - May 7: Wrap up university finals. Discuss and finalize the
     prioritized list of subsystems with my mentor.
   - May 8 - May 25: Categorize the targeted global variables and map out
     their intended destinations (e.g., repo_settings). Draft and submit
     the initial RFC patch series.

* Phase 1 (May 26 - July 10): Foundation
   - Weeks 1-2: Plumb the context pointer (`struct repository *repo`) 
through call chains for simple variables (e.g., boolean flags or integer 
configs).
   - Weeks 3-4: Audit and update external callers to use the new API.
   - Weeks 5-6: Submit the first major refactoring patch series. Address
     mailing list feedback and resolve merge conflicts. (Midterm Evaluation)

* Phase 2 (July 11 - August 18): Complex Migration & Cleanup
   - Weeks 7-8: Refactor higher-complexity variables (e.g., path-related 
globals).
   - Weeks 9-10: Compile the codebase with AddressSanitizer and run the 
full test suite to execute strict memory leak checks.
   - Weeks 11-12: Remove unused global macro definitions and static 
variables. Update internal documentation and write the final GSoC report.

(The above is for reference only. Personally, I always finish tasks 
faster than planned 😉)


~$ git checkout HEAD@{postGSoC}
-------------------------------
This past month since joining the Git community has been the most 
enjoyable month of my programming journey. To quote a close friend of 
mine (who is applying for the Neovim GSoC project):

   "Only fools chase trends; open source is the game for the brave."

The words may be blunt, but the logic holds true. This statement surely
resonates with me (and maybe many other GSoC contributors): our passion
for code and open-source drives us forward.

Even if I didn't make the cut, so what? ~$ git reset --hard...
Just kidding. The Git codebase is far too interesting to abandon now.

-------------------------------------------------------------------------
Changes since V3:

  - The idea of introducing a new container is abandoned now. Therefore, 
In approach section, the diagram and corresponding 
descriptions/"guidelines" are modified;
  - Emphasize on Meson and GitLab/GitHub which can be used for necessary 
safety checks;
  - Refined timeline section (community bonding).

  ** I wrote "Changes since v3" as well in last patch (V3). Sorry for 
the typo :( **

Regards,

Yuchen

Re: [GSoC][Draft Proposal v4] Refactoring in order to reduce Git's global state

[Phillip Wood]

Hi Tian

On 26/02/2026 17:02, Tian Yuchen wrote:
> [...]
> Although the principle is simple, the scope of changes is extensive. The
> following three-step approach can serve as a guiding principle for it:

There are four steps below

>    1. Identify isolated environment variables currently residing in the
>       global scope. Conduct a case-by-case analysis to map each variable
>       to its most appropriate existing home (e.g., struct repo_settings
>       for configuration values, or specific localized structs within
>       struct repository).

Note that as settings in struct repo_settings are lazily parsed, it is 
only suitable for settings that are already lazily parsed. That means it 
is not a suitable home for any settings that are parsed at startup by 
git_default_config().

>    2. Instead of blindly passing struct repository *repo down into every
>       single low-level library function, bubbling the dependency up is
>       the true goal. External callers of the functions must be carefully
>       audited to prevent regressions.

Where a function only needs one piece of information from struct 
repository that sounds like a good strategy.

>    3. Safely remove the old global variables and macro definitions. Make
>       full use of Git's existing GitLab/GitHub CI and utilize local
>       Meson builds with AddressSanitizer enabled to ensure that the new
>       lifecycle introduces zero memory leaks.
>    4. Many globals like `editor_program` are parsed once and remain
>       available globally. New data flow might need to be designed to
>       maintain the lazy-loading efficiency.

Although `editor_program` is parsed once, that happens in 
git_default_config() so it is not lazily loaded and making it lazily 
loaded would be a regression as if the config value is invalid we want 
to exit with an error early in the process, not just before we prompt 
the user to edit a file.

Thanks

Phillip

Re: [GSoC][Draft Proposal v4] Refactoring in order to reduce Git's global state

[Tian Yuchen]

Hi Phillip,

Wow, your reply is very detailed. Appreciate.

> There are four steps below...

Yup, a typo.

> Note that as settings in struct repo_settings are lazily parsed, it is 
> only suitable for settings that are already lazily parsed. That means it 
> is not a suitable home for any settings that are parsed at startup by 
> git_default_config().

This makes sense to me. So for variables in like 'git_default_config()', 
their startup parsing nature must be preserved. Will update the proposal 
to explicitly distinguish between these different lifecycles.


> Where a function only needs one piece of information from struct 
> repository that sounds like a good strategy.

It's much better to pass just that value down rather than passing the 
entire 'struct repository', right?

> Although `editor_program` is parsed once, that happens in 
> git_default_config() so it is not lazily loaded and making it lazily 
> loaded would be a regression as if the config value is invalid we want 
> to exit with an error early in the process, not just before we prompt 
> the user to edit a file.

Oh, I thought it was lazy-loaded. I completely overlooked the user 
experience in terms of a delayed fatal config error also. Will double 
check the source code and rewrite this part.

I'm delighted to see more people reviewing my proposal. I've truly 
gained valuable insights into Git's design philosophy. My sincere 
gratitude to you.

Regards,

Yuchen

Re: [GSoC][Draft Proposal v4] Refactoring in order to reduce Git's global state

[Tian Yuchen]

Hi all,

Here is the V5 patch.

Thanks Phillip Wood, for help and guidance.


Refactoring in order to reduce Git's global state
=================================================

PERSONAL INFORMATION
--------------------
Name: Tian Yuchen
E-mail: a3205153416@gmail.com
Phone number: +65 98740318
Time-zone: UTC + 08:00
Github: https://github.com/malon7782

Education: NTU, Singapore
Year: Year 1 semester 2
Degree: Electrical and Electronic Engineering (EEE)


PRE GSOC
--------
I have always held a deep passion for the open-source community. 
Although I wasn't a computer science major, I tinkered with open-source 
projects long before college. I have solid hands-on experience in C 
programming and system-level debugging.

I use Ubuntu 24.04 on a daily basis, so I am proficient in using the 
Linux command line and CLI tools.

I have contributed to the Git community by sending patches. Since my 
first commit (17/1/2026), I have maintained a nearly daily contribution. 
Here is the list of contributions I have made:

* [PATCH v1] t1005: modernize "! test -f" to "test_path_is_missing"

https://lore.kernel.org/git/20260117062515.319664-1-a3205153416@gmail.com/
   This patch is my microproject, the first contribution I made to the 
codebase.
   [Graduated to 'master']

* [PATCH v2] t2203: avoid masking exit codes in git status

https://lore.kernel.org/git/20260118043537.338769-1-a3205153416@gmail.com/#t

* [PATCH v2] symlinks: use unsigned int for flags

https://lore.kernel.org/git/20260120152219.398999-1-a3205153416@gmail.com/
   [Will merge to 'next']

* [PATCH v4] t/perf/p3400: speed up setup using fast-import

https://lore.kernel.org/git/20260130170123.642344-1-a3205153416@gmail.com/
   [Will merge to 'master']

* Re: [PATCH] [RFC] attr: use local repository state in read_attr

https://lore.kernel.org/git/cc2f400e-49c2-4de0-9c51-9a5c0294735e@gmail.com/
   Code review. To verify the performance loss, I wrote a test script to
   measure the time difference before and after the modification.

* Re: Bug: git add :!x . exits with error when x is in .gitignore

https://lore.kernel.org/git/1d560aa1-d452-47f5-aaf2-4cb1ccdab100@gmail.com/
   Code review. Pointed out logical error.

* [PATCH v10] setup: allow cwd/.git to be a symlink to a directory

https://lore.kernel.org/git/20260220164512.216901-1-a3205153416@gmail.com/
   [Under review]
   After over half a month of discussions, repeated refactoring, and code
   reviews, I delved deep into setup.c. I gained insights into Git's 
design philosophy, and learned the art of striking a balance in 
developer communication. It took me a large amount of time and effort to 
thoroughly understand every line of the code. I often found myself 
poring over the call chain of a single function well into the night.... 
But I persevered until the end, and I believe my patience will see me 
through even larger projects.


ABOUT THE PROJECT
-----------------

-- Synopsis

As far as I know, the Git community is actively working towards 
'libification' - making Git's internal machinery reusable as a C 
library. The extensive reliance on global state is a major roadblock to 
this goal.

Many core functions implicitly read environment variables and store them 
in global static variables. This can cause several issues:

   1. Global variables prevent Git's core functions from being executed 
safely in multi-threaded contexts. For example, When unexpected states 
(e.g., a permission denied error when probing a directory), they often 
rely on the global state to decide whether to call die(), which 
internally calls exit(). It’s fine for a standalone CLI tool, but for a 
linked C library used by a long-running multi-threaded server, a single 
die() call will kill the entire host process. Structured status, instead 
of fatal exits, should be returned.

   2. When Git is called multiple times within the same process, global 
states can lead to memory leaks or incorrect behaviors.

   3. Unit testing becomes difficult because the environment must be 
artificially manipulated before calling functions.

Take a look at this example from environment.c:

     206 const char *get_commit_output_encoding(void)
     207 {
     208     return git_commit_encoding ? git_commit_encoding : "UTF-8";
     209 }

If Git is invoked as a C library by a multi-threaded server:
- Thread A formats a commit for Repo A (using GBK);
- Thread B concurrently formats a commit for Repo B (using UTF-8);

Then they will race to read and overwrite the exact same global
`git_commit_encoding` pointer, which is not what we expect. Therefore,
we have to refactor these environment variables by moving them from
global scope into a well-defined and encapsulated context.


-- Approach

The task at hand goes beyond simply repackaging the global variables 
into the struct repository structure. Based on my recent experience 
refactoring setup.c, I realized that libification requires careful 
management of variable lifecycles and api boundaries:

     [ Current ]
     Core functions --------reads-------> Global variables (via getenv)
                                          [Thread unsafe]

     [ Target ]
     Core functions ----passes context--> struct repository
                                                 | owns
                                                 v
                                          struct repo_settings

                    	                 other domain-specific structs

Although the principle is simple, the scope of changes is extensive. The 
following insights can serve as a guiding principle for it:

   1. Identify isolated environment variables currently residing in the
      global scope. Conduct a case-by-case analysis to map each variable
      to its most appropriate existing home based on their lifecycles:

	Variables that are only parsed when needed will be safely mapped
	to struct repo_settings.

	Variables parsed at startup (e.g., editor_program)
	must not be moved to lazily parsed structs to ensure that
	invalid configurations can trigger early failures before
	execution proceeds too far, which is also for the sake of user
         experience.

   2. Instead of blindly passing struct repository *repo down into every
      single low-level library function, bubbling the dependency up is
      the true goal. External callers of the functions must be carefully
      audited to prevent regressions.

   3. Safely remove the old global variables and macro definitions. Make
      full use of Git's existing GitLab/GitHub CI and utilize local
      Meson builds with AddressSanitizer enabled to ensure that the new
      lifecycle introduces zero memory leaks.


Additionally, given the anticipated high volume of commits, we must 
ensure each patch is independent and atomic, preventing any 
user-untraceable or unexplainable bugs from occurring in the codebase at 
any state.


AVAILABILITY
------------
Fortunately, my summer vacation coincides with the GSoC work period.
I will treat this project as my primary focus, dedicating a minimum of
35 hours per week. If needed, I can work a 9-to-5 schedule.

I will have a significant head start to draft RFC patches before the
official coding period even begins. Having this buffer period allows me
to go through the rigorous code review process within the Git community
with greater ease.


TIMELINE & MILESTONES
---------------------
Considering the differences between this project and other projects on 
the idea list, rather than hoarding massive changes, I will submit 
3-to-5-patch series frequently to respect reviewers' time and maintain a 
steady velocity.

Below is the tentative schedule I have prepared for myself:

* Community Bonding (May 1 - May 25): Planning & RFC
   - May 1 - May 7: Wrap up university finals. Discuss and finalize the
     prioritized list of subsystems with my mentor.
   - May 8 - May 25: Categorize the targeted global variables and map out
     their intended destinations (e.g., repo_settings). Draft and submit
     the initial RFC patch series.

* Phase 1 (May 26 - July 10): Foundation
   - Weeks 1-2: Plumb the context pointer ('struct repository *repo') 
through call chains for simple variables (e.g., boolean flags or integer 
configs).
   - Weeks 3-4: Audit and update external callers to use the new API.
   - Weeks 5-6: Submit the first major refactoring patch series. Address
     mailing list feedback and resolve merge conflicts. (Midterm Evaluation)

* Phase 2 (July 11 - August 18): Complex Migration & Cleanup
   - Weeks 7-8: Refactor higher-complexity variables (e.g., path-related 
globals).
   - Weeks 9-10: Compile the codebase with AddressSanitizer and run the 
full test suite to execute strict memory leak checks.
   - Weeks 11-12: Remove unused global macro definitions and static 
variables. Update internal documentation and write the final GSoC report.

(The above is for reference only. Personally, I always finish tasks 
faster than planned 😉)


~$ git checkout HEAD@{postGSoC}
-------------------------------
This past month since joining the Git community has been the most 
enjoyable month of my programming journey. To quote a close friend of 
mine (who is applying for the Neovim GSoC project):

   "Only fools chase trends; open source is the game for the brave."

The words may be blunt, but the logic holds true. This statement surely
resonates with me (and maybe many other GSoC contributors): our passion
for code and open-source drives us forward.

Even if I didn't make the cut, so what? ~$ git reset --hard...
Just kidding. The Git codebase is far too interesting to abandon now.

-------------------------------------------------------------------------
Changes since V4:

  - “Treating variables or functions differently based on their 
lifecycle” has been added to the Approach section.

  - Fixed a typo below the diagram.

Regards,

Yuchen

Re: [GSoC][Draft Proposal v4] Refactoring in order to reduce Git's global state

[Phillip Wood]

Hi Tian

On 27/02/2026 16:58, Tian Yuchen wrote:
> 
> 
>    3. Unit testing becomes difficult because the environment must be 
> artificially manipulated before calling functions.
> 
> Take a look at this example from environment.c:
> 
>      206 const char *get_commit_output_encoding(void)
>      207 {
>      208     return git_commit_encoding ? git_commit_encoding : "UTF-8";
>      209 }
> 
> If Git is invoked as a C library by a multi-threaded server:
> - Thread A formats a commit for Repo A (using GBK);
> - Thread B concurrently formats a commit for Repo B (using UTF-8);

The encoding config is really a user preference that lets the user 
compose commit messages in their preferred encoding while allowing git 
to store the message encoded as UTF-8. I'm struggling to see why two 
threads would be using different encodings as it implies that the user 
is using different encodings in different repositories.

Below you say

 >      Variables parsed at startup (e.g., editor_program)
 >      must not be moved to lazily parsed structs to ensure that
 >      invalid configurations can trigger early failures before
 >      execution proceeds too far, which is also for the sake of user
 >          experience.

i18n.commitEncoding is another such setting as it is currently eagerly 
parsed so I'm surprised to see it being converted to lazy parsing in 
https://lore.kernel.org/20260228190201.3684705-1-a3205153416@gmail.com

I'm afraid that the suggestion on the project webpage is not very 
helpful. Most config variables are unsuited to a conversion based on 
repository_settings, it would be better to look at the approach 
implemented in 
https://lore.kernel.org/48821a3848bef25c13038be8377ad73e7c17a924.1771258573.git.belkid98@gmail.com 
that is discussed in https://lore.kernel.org/xmqqwm1vk83a.fsf@gitster.g

Thanks

Phillip

> Then they will race to read and overwrite the exact same global
> `git_commit_encoding` pointer, which is not what we expect. Therefore,
> we have to refactor these environment variables by moving them from
> global scope into a well-defined and encapsulated context.
> 
> 
> -- Approach
> 
> The task at hand goes beyond simply repackaging the global variables 
> into the struct repository structure. Based on my recent experience 
> refactoring setup.c, I realized that libification requires careful 
> management of variable lifecycles and api boundaries:
> 
>      [ Current ]
>      Core functions --------reads-------> Global variables (via getenv)
>                                           [Thread unsafe]
> 
>      [ Target ]
>      Core functions ----passes context--> struct repository
>                                                  | owns
>                                                  v
>                                           struct repo_settings
> 
>                                          other domain-specific structs
> 
> Although the principle is simple, the scope of changes is extensive. The 
> following insights can serve as a guiding principle for it:
> 
>    1. Identify isolated environment variables currently residing in the
>       global scope. Conduct a case-by-case analysis to map each variable
>       to its most appropriate existing home based on their lifecycles:
> 
>      Variables that are only parsed when needed will be safely mapped
>      to struct repo_settings.
> 
>      Variables parsed at startup (e.g., editor_program)
>      must not be moved to lazily parsed structs to ensure that
>      invalid configurations can trigger early failures before
>      execution proceeds too far, which is also for the sake of user
>          experience.
> 
>    2. Instead of blindly passing struct repository *repo down into every
>       single low-level library function, bubbling the dependency up is
>       the true goal. External callers of the functions must be carefully
>       audited to prevent regressions.
> 
>    3. Safely remove the old global variables and macro definitions. Make
>       full use of Git's existing GitLab/GitHub CI and utilize local
>       Meson builds with AddressSanitizer enabled to ensure that the new
>       lifecycle introduces zero memory leaks.
> 
> 
> Additionally, given the anticipated high volume of commits, we must 
> ensure each patch is independent and atomic, preventing any user- 
> untraceable or unexplainable bugs from occurring in the codebase at any 
> state.
> 
> 
> AVAILABILITY
> ------------
> Fortunately, my summer vacation coincides with the GSoC work period.
> I will treat this project as my primary focus, dedicating a minimum of
> 35 hours per week. If needed, I can work a 9-to-5 schedule.
> 
> I will have a significant head start to draft RFC patches before the
> official coding period even begins. Having this buffer period allows me
> to go through the rigorous code review process within the Git community
> with greater ease.
> 
> 
> TIMELINE & MILESTONES
> ---------------------
> Considering the differences between this project and other projects on 
> the idea list, rather than hoarding massive changes, I will submit 3- 
> to-5-patch series frequently to respect reviewers' time and maintain a 
> steady velocity.
> 
> Below is the tentative schedule I have prepared for myself:
> 
> * Community Bonding (May 1 - May 25): Planning & RFC
>    - May 1 - May 7: Wrap up university finals. Discuss and finalize the
>      prioritized list of subsystems with my mentor.
>    - May 8 - May 25: Categorize the targeted global variables and map out
>      their intended destinations (e.g., repo_settings). Draft and submit
>      the initial RFC patch series.
> 
> * Phase 1 (May 26 - July 10): Foundation
>    - Weeks 1-2: Plumb the context pointer ('struct repository *repo') 
> through call chains for simple variables (e.g., boolean flags or integer 
> configs).
>    - Weeks 3-4: Audit and update external callers to use the new API.
>    - Weeks 5-6: Submit the first major refactoring patch series. Address
>      mailing list feedback and resolve merge conflicts. (Midterm 
> Evaluation)
> 
> * Phase 2 (July 11 - August 18): Complex Migration & Cleanup
>    - Weeks 7-8: Refactor higher-complexity variables (e.g., path-related 
> globals).
>    - Weeks 9-10: Compile the codebase with AddressSanitizer and run the 
> full test suite to execute strict memory leak checks.
>    - Weeks 11-12: Remove unused global macro definitions and static 
> variables. Update internal documentation and write the final GSoC report.
> 
> (The above is for reference only. Personally, I always finish tasks 
> faster than planned 😉)
> 
> 
> ~$ git checkout HEAD@{postGSoC}
> -------------------------------
> This past month since joining the Git community has been the most 
> enjoyable month of my programming journey. To quote a close friend of 
> mine (who is applying for the Neovim GSoC project):
> 
>    "Only fools chase trends; open source is the game for the brave."
> 
> The words may be blunt, but the logic holds true. This statement surely
> resonates with me (and maybe many other GSoC contributors): our passion
> for code and open-source drives us forward.
> 
> Even if I didn't make the cut, so what? ~$ git reset --hard...
> Just kidding. The Git codebase is far too interesting to abandon now.
> 
> -------------------------------------------------------------------------
> Changes since V4:
> 
>   - “Treating variables or functions differently based on their 
> lifecycle” has been added to the Approach section.
> 
>   - Fixed a typo below the diagram.
> 
> Regards,
> 
> Yuchen
> 

Re: [GSoC][Draft Proposal v4] Refactoring in order to reduce Git's global state

[Tian Yuchen]

Hi Phillip,

Thank you so much for taking the time to review both my patch and my 
GSoC proposal draft.

You are right on all points:

1. I now agree that commit encoding being a user/environment preference 
rather than a repository-specific attribution. My example was indeed a 
flawed assumption.

2. Thank you for catching the contradiction between my patch and my 
proposal's guiding principles. However, I changed it to lazy-loading not 
because I didn't follow the workflow I wrote, but because I thought the 
original eagerly parsing behavior was *incorrect*. But since I now 
understand point 1 above, this is no longer an issue to me anymore.

3. I deeply appreciate you pointing out that the GSoC ideas page might 
be misleading. I will study through the link you provide.

Thank you again for steering me in the right direction!

Regards,

Yuchen

Re: [GSoC][Draft Proposal v4] Refactoring in order to reduce Git's global state

[Junio C Hamano]

Phillip Wood <phillip.wood123@gmail.com> writes:

> i18n.commitEncoding is another such setting as it is currently eagerly 
> parsed so I'm surprised to see it being converted to lazy parsing in 
> https://lore.kernel.org/20260228190201.3684705-1-a3205153416@gmail.com
>
> I'm afraid that the suggestion on the project webpage is not very 
> helpful. Most config variables are unsuited to a conversion based on 
> repository_settings,...

Thanks for a dose of sanity here.  Very much appreciated.

[GSoC][Draft Proposal v6] Refactoring in order to reduce Git's global state

[Tian Yuchen]

Hi all,

Here is the V6 Draft. Looking forward to hearing your feedback (ゝ∀･)

Refactoring in order to reduce Git's global state
=================================================

PERSONAL INFORMATION
--------------------
Name: Tian Yuchen
E-mail: a3205153416@gmail.com
Phone number: +65 98740318
Time-zone: UTC + 08:00
Github: https://github.com/malon7782

Education: NTU, Singapore
Year: Year 1 semester 2
Degree: Electrical and Electronic Engineering (EEE)


PRE GSOC
--------
I have always held a deep passion for the open-source community. 
Although I'm not a computer science major, I tinkered with open-source 
projects long before college. I have solid hands-on experience in C 
programming and system-level debugging.

I use Ubuntu 24.04 on a daily basis, so I am proficient in using the 
Linux command line and CLI tools.

I have contributed to the Git community by sending patches. Since my 
first commit (17/1/2026), I have maintained a nearly daily contribution. 
Here is the list of contributions I have made:

* [PATCH v1] t1005: modernize "! test -f" to "test_path_is_missing"

https://lore.kernel.org/git/20260117062515.319664-1-a3205153416@gmail.com/
   This patch is my microproject, the first contribution I made to the 
codebase.
   [Graduated to 'master']

* [PATCH v2] t2203: avoid masking exit codes in git status

https://lore.kernel.org/git/20260118043537.338769-1-a3205153416@gmail.com/#t

* [PATCH v2] symlinks: use unsigned int for flags

https://lore.kernel.org/git/20260120152219.398999-1-a3205153416@gmail.com/
   [Merged to 'next']

* [PATCH v4] t/perf/p3400: speed up setup using fast-import

https://lore.kernel.org/git/20260130170123.642344-1-a3205153416@gmail.com/
   [Will merge to 'master']

* Re: [PATCH] [RFC] attr: use local repository state in read_attr

https://lore.kernel.org/git/cc2f400e-49c2-4de0-9c51-9a5c0294735e@gmail.com/
   Code review. To verify the performance loss, I wrote a test script to
   measure the time difference before and after the modification.

* Re: Bug: git add :!x . exits with error when x is in .gitignore

https://lore.kernel.org/git/1d560aa1-d452-47f5-aaf2-4cb1ccdab100@gmail.com/
   Code review. Pointed out logical error.

* [PATCH v11] setup: allow cwd/.git to be a symlink to a directory

https://lore.kernel.org/git/20260220164512.216901-1-a3205153416@gmail.com/
   [Under review]
   After over half a month of discussions, repeated refactoring, and code
   reviews, I delved deep into setup.c. I gained insights into Git's 
design philosophy, and learned the art of striking a balance in 
developer communication. It took me a large amount of time and effort to 
thoroughly understand every line of the code. I often found myself 
poring over the call chain of a single function well into the night.... 
But I persevered until the end, and I believe my patience will see me 
through even larger projects.

* [PATCH v4 0/3] move encoding configs to repo_config_values()

https://lore.kernel.org/git/20260228190201.3684705-1-a3205153416@gmail.com/
   [In progress]
   A practice patch for working according to the workflow described in 
this proposal.

* Re: [PATCH 4/4] repo: add the field path.toplevel

https://lore.kernel.org/git/e6e7e272-4aec-461e-aebd-33ec0a324770@gmail.com/
   Code review. Question unreasonable designs.



ABOUT THE PROJECT
-----------------

-- Synopsis

As far as I know, the Git community is actively working towards 
'libification' - making Git's internal machinery reusable as a C 
library. The extensive reliance on global state is a major roadblock to 
this goal.

Many core functions implicitly read environment variables and store them 
in global static variables. This can cause several issues:

   1. When Git is called multiple times within the same process, global 
states can lead to memory leaks or incorrect behaviors.

   2. Unit testing becomes difficult because the environment must be 
artificially manipulated before calling functions.

   3. Global variables prevent Git's core functions from being executed 
safely in multi-threaded contexts. For example, When unexpected states 
(e.g., a permission denied error when probing a directory), they often 
rely on the global state to decide whether to call die(), which 
internally calls exit(). It’s fine for a standalone CLI tool, but for a 
linked C library used by a long-running multi-threaded server, a single 
die() call will kill the entire host process. Structured status, instead 
of fatal exits, should be returned.

Take a look at this example from environment.c:

     206 const char *get_commit_output_encoding(void)
     207 {
     208     return git_commit_encoding ? git_commit_encoding : "UTF-8";
     209 }

If Git is invoked as a C library by a multi-threaded server:
- Thread A formats a commit for Repo A (using GBK);
- Thread B concurrently formats a commit for Repo B (using UTF-8);

Then they will race to read and overwrite the exact same global
`git_commit_encoding` pointer, which is not what we expect. Therefore,
we have to refactor these environment variables by moving them from
global scope into a well-defined and encapsulated context.


-- Approach

The task at hand goes beyond simply repackaging the global variables 
into the struct repository structure. Based on my recent experience 
refactoring setup.c, I realized that libification requires careful 
management of variable lifecycles and api boundaries:

     [ Current ]
     Core functions --------reads-------> Global variables (via getenv)
                                          [Thread unsafe]

     [ Target ]
     Core functions ----passes context--> struct repository
                                                 | owns
                                                 v
                                      struct repo_settings(lazy)

		  	          struct repo_config_values (eager) [1]

                                      other domain-specific structs

Although the principle is simple, the scope of changes is extensive. The 
following insights can serve as a guiding principle for it:

   1. Identify isolated environment variables currently residing in the
      global scope. Conduct a case-by-case analysis to map each variable
      to its most appropriate existing home based on their lifecycles:

     	Variables that are only parsed when needed will be safely mapped
	to struct repo_settings.

     	Variables parsed at startup (e.g., editor_program) must not be
	moved to lazily parsed structs to ensure that invalid
	configurations can trigger early failures before execution
	proceeds too far, which is also for the sake of user experience.
	(Phillip Wood points out that the struct repo_config_values()
	can serve as a good home to these variables, though this
	approach remains in its early stages and has not yet been fully
	confirmed and implemented. [2])

   2. Instead of blindly passing struct repository *repo down into every
      single low-level library function, bubbling the dependency up is
      the true goal. External callers of the functions must be carefully
      audited to prevent regressions.

   3. Safely remove the old global variables and macro definitions. Make
      full use of Git's existing GitLab/GitHub CI and utilize local
      Meson builds with AddressSanitizer enabled to ensure that the new
      lifecycle introduces zero memory leaks. [3]


Additionally, given the anticipated high volume of commits, we must 
ensure each patch is independent and atomic [4], preventing any 
user-untraceable or unexplainable bugs from occurring in the codebase at 
any state.


AVAILABILITY
------------
Fortunately, my summer vacation perfectly coincides with the GSoC work 
period. I will treat this project as my primary focus, dedicating a 
minimum of 35 hours per week. If needed, I can work a 9-to-5 schedule.

I will have a significant head start to draft RFC patches before the
official coding period even begins. Having this buffer period allows me
to go through the rigorous code review process within the Git community
with greater ease.


TIMELINE & MILESTONES
---------------------
Considering the differences between this project and other projects on 
the idea list, rather than hoarding massive changes, I will submit 
3-to-5-patch series frequently to respect reviewers' time and maintain a 
steady velocity.

Below is the tentative schedule I have prepared for myself:

* Community Bonding (May 1 - May 25): Planning & RFC
   - May 1 - May 7: Wrap up university finals. Discuss and finalize the
     prioritized list of subsystems with my mentor.
   - May 8 - May 25: Categorize the targeted global variables and map out
     their intended destinations (e.g., repo_settings vs 
repo_config_values). Draft and submit
     the initial RFC patch series.

* Phase 1 (May 26 - July 10): Foundation
   - Weeks 1-2: Plumb the context pointer ('struct repository *repo') 
through call chains for simple variables (e.g., boolean flags or integer 
configs).
   - Weeks 3-4: Audit and update external callers to use the new API.
   - Weeks 5-6: Submit the first major refactoring patch series. Address
     mailing list feedback and resolve merge conflicts. (Midterm Evaluation)

* Phase 2 (July 11 - August 18): Complex Migration & Cleanup
   - Weeks 7-8: Refactor higher-complexity variables (e.g., path-related 
globals).
   - Weeks 9-10: Compile the codebase with AddressSanitizer and run the 
full test suite to execute strict memory leak checks.
   - Weeks 11-12: Remove unused global macro definitions and static 
variables. Update internal documentation and write the final GSoC report.

(The above is for reference only. Personally, I always finish tasks 
faster than planned 😉)


~$ git checkout HEAD@{postGSoC}
-------------------------------
This past month since joining the Git community has been the most 
enjoyable month of my programming journey. To quote a close friend of 
mine (who is applying for the Neovim GSoC project):

   "Only fools chase trends; open source is the game for the brave."

The words may be blunt, but the logic holds true. This statement surely
resonates with me (and maybe many other GSoC contributors): our passion
for code and open-source drives us forward.

Even if I didn't make the cut, so what? ~$ git reset --hard...
Just kidding. The Git codebase is far too interesting to abandon now.


REFERENCE
-------------------------------
[1]

https://lore.kernel.org/all/48821a3848bef25c13038be8377ad73e7c17a924.1771258573.git.belkid98@gmail.com/

[2]

https://lore.kernel.org/git/CAP8UFD2Q7gctwzGOe+rbgdXZSbDbV0dmM-cx4qt_d8nKi88=HA@mail.gmail.com/T/#t

[3]

https://lore.kernel.org/all/CAOLa=ZR=2B7yH+vtyiAPcCyU17yd2GZwonaj=JRo1f+LzSCoTg@mail.gmail.com/

[4]

https://lore.kernel.org/all/xmqqy0kp7wai.fsf@gitster.g/





-------------------------------------------------------------------------
Changes since V5:

  - Once again, the diagram and approach sections emphasize 
distinguishing variables across different life cycles.

  - Modified the --Synopsis section. (issues with global variables)

  - Included recent contributions and updated progress.

  - Reference links has been added at the end to clarify the source of 
my viewpoint/plan.

Regards,

Yuchen

Re: [GSoC][Draft Proposal v7] Refactoring in order to reduce Git's global state

[Tian Yuchen]

Hi all,

Here is the V7 Draft. Looking forward to hearing your feedback (ゝ∀･)

Refactoring in order to reduce Git's global state
=================================================

PERSONAL INFORMATION
--------------------
Name: Tian Yuchen
E-mail: a3205153416@gmail.com
Phone number: +65 98740318
Time-zone: UTC + 08:00
Github: https://github.com/malon7782

Education: NTU, Singapore
Year: Year 1 semester 2
Degree: Electrical and Electronic Engineering (EEE)


PRE GSOC
--------
I have always held a deep passion for the open-source community. 
Although I'm not a computer science major, I tinkered with open-source 
projects long before college. I have solid hands-on experience in C 
programming and system-level debugging.

I use Ubuntu 24.04 on a daily basis, so I am proficient in using the 
Linux command line and CLI tools.

I have contributed to the Git community by sending patches. Since my 
first commit (17/1/2026), I have maintained a nearly daily contribution. 
Here is the list of contributions I have made:

* [PATCH v1] t1005: modernize "! test -f" to "test_path_is_missing"

https://lore.kernel.org/git/20260117062515.319664-1-a3205153416@gmail.com/
   This patch is my microproject, the first contribution I made to the 
codebase.
   [Graduated to 'master']

* [PATCH v2] t2203: avoid masking exit codes in git status

https://lore.kernel.org/git/20260118043537.338769-1-a3205153416@gmail.com/#t

* [PATCH v2] symlinks: use unsigned int for flags

https://lore.kernel.org/git/20260120152219.398999-1-a3205153416@gmail.com/
   [Merged to 'next']

* [PATCH v4] t/perf/p3400: speed up setup using fast-import

https://lore.kernel.org/git/20260130170123.642344-1-a3205153416@gmail.com/
   [Will merge to 'master']

* Re: [PATCH] [RFC] attr: use local repository state in read_attr

https://lore.kernel.org/git/cc2f400e-49c2-4de0-9c51-9a5c0294735e@gmail.com/
   Code review. To verify the performance loss, I wrote a test script to
   measure the time difference before and after the modification.

* Re: Bug: git add :!x . exits with error when x is in .gitignore

https://lore.kernel.org/git/1d560aa1-d452-47f5-aaf2-4cb1ccdab100@gmail.com/
   Code review. Pointed out logical error.

* [PATCH v11] setup: allow cwd/.git to be a symlink to a directory

https://lore.kernel.org/git/20260220164512.216901-1-a3205153416@gmail.com/
   [Under review]
   After over half a month of discussions, repeated refactoring, and code
   reviews, I delved deep into setup.c. I gained insights into Git's 
design philosophy, and learned the art of striking a balance in 
developer communication. It took me a large amount of time and effort to 
thoroughly understand every line of the code. Throughout this process, I 
meticulously examined portions of the call chain in setup.c, the timing 
of die() usage, expected lookup/error handling behavior, external 
callers, and ran several full CI tests. I managed to correct my initial 
assumptions and it taught me why die() cannot be casually bypassed in 
libification without rigorous error propagation, as well as how to 
handle cross-platform CI edge cases.

* [PATCH v4 0/3] move encoding configs to repo_config_values()

https://lore.kernel.org/git/20260228190201.3684705-1-a3205153416@gmail.com/
   [In progress]
   A practice patch for working according to the workflow described in 
this proposal.

* Re: [PATCH 4/4] repo: add the field path.toplevel

https://lore.kernel.org/git/e6e7e272-4aec-461e-aebd-33ec0a324770@gmail.com/
   Code review. Questioned unreasonable designs.

* Re: [PATCH] Refactor 'trust_executable_bit' to repository-scoped setting

https://lore.kernel.org/git/24f40e5a-a5fd-49ec-86e7-921b44e4abd9@gmail.com/
   Code review. Clarify lazy-loading and eager-loading. Pointed out 
problems with the patch.

* [PATCH] patch-ids: achieve const correctness in patch_id_neq()
   https://lore.kernel.org/git/xmqqseaasuph.fsf@gitster.g/T/#t
   [In progress]
   Discuss and modify the items marked NEEDSWORK in patch-ids.c

To date, developing diverse patches across various domains has been a 
thoroughly enjoyable experience for me. I relish exploring different 
fields while maintaining the discipline to delve deeply into them. I 
never settle for superficial patches.


ABOUT THE PROJECT
-----------------

-- Synopsis

As far as I know, the Git community is actively working towards 
'libification' (laid by Patrick Steinhardt's config/path refactoring, 
and Olamide Bello's recent introduction of repo_config_values) - making 
Git's internal machinery reusable as a C library. The extensive reliance 
on global state is a major roadblock to this goal.

Many core functions implicitly read environment variables and store them 
in global static variables. This can cause several issues:

   1. When Git is called multiple times within the same process, global 
states can lead to memory leaks or incorrect behaviors.

   2. Unit testing becomes difficult because the environment must be 
artificially manipulated before calling functions.

   3. Global variables prevent Git's core functions from being executed 
safely in multi-threaded contexts. For example, when encountering 
unexpected states (e.g., a permission denied error when probing a 
directory), core functions often rely on the global state to decide 
whether to call die(), which internally calls exit(). It’s fine for a 
standalone CLI tool, but for a linked C library used by a long-running 
multi-threaded server, a single die() call will kill the entire host 
process. Structured status, instead of fatal exits, should be returned.

Take a look at this example from environment.c:

     206 const char *get_commit_output_encoding(void)
     207 {
     208     return git_commit_encoding ? git_commit_encoding : "UTF-8";
     209 }

If Git is invoked as a C library by a multi-threaded server:
- Thread A formats a commit for Repo A (using GBK);
- Thread B concurrently formats a commit for Repo B (using UTF-8);

Then they will race to read and overwrite the exact same global
`git_commit_encoding` pointer, which is not what we expect. Therefore,
we have to refactor these environment variables by moving them from
global scope into a well-defined and encapsulated context.

-- Trade-off?

A naive approach to achieve this is blindly moving every global variable 
into struct repository. For the previous encoding case, this approach 
does not seem entirely unfeasible. However, it is easy to cite another 
example:

“What if some variables are accessed before setup_git_directory() 
successfully initializes the repo struct?”

For instance, early discovery flags like is_bare_repository_cfg are 
assigned during the .git directory probe, long before a struct 
repository object can be safely instantiated. We create a 
chicken-and-egg initialization paradox if we force these early-startup 
variables into repo_settings. How can a variable dictate the discovery 
of a repository if it lives inside the repository it is trying to discover?

I believe the key point to note for this case is the boundary between 
Repository State and Process/Startup State. Encapsulating it within the 
early-boot context might be a viable option... but more importantly, 
this example illustrates that eliminating global variables is never a 
matter of blindly “moving … to …” Instead, it requires careful, 
multifaceted consideration and a thorough weighing of the trade-offs.


-- Approach

Therefore, the task at hand goes beyond simply repackaging the global 
variables into the struct repository structure. Based on my recent 
experience refactoring setup.c, I realized that libification requires 
careful management of variable lifecycles and api boundaries:

     [ Current ]
     Core functions --------reads-------> Global variables (via getenv)
                                          [Thread unsafe]

     [ Target ]
     Core functions ----passes context--> struct repository
                                                 | owns
                                                 v
                                      struct repo_settings(lazy)

                                 struct repo_config_values (eager) [1]

                                      other domain-specific structs

Although the principle is simple, the scope of changes is extensive. The 
following insights can serve a guiding principles (but not the absolute 
rules to obey):

   1. Identify isolated environment variables currently residing in the
      global scope. Conduct a case-by-case analysis to map each variable
      to its most appropriate existing home based on their lifecycles:

         Variables that are only parsed when needed will be safely mapped
     to struct repo_settings.

         Variables parsed at startup (e.g., editor_program) must not be
     moved to lazily parsed structs to ensure that invalid
     configurations can trigger early failures before execution
     proceeds too far, which is also for the sake of user experience.
     (Phillip Wood points out that the struct repo_config_values
     can serve as a good home to these variables, though this
     approach remains in its early stages and has not yet been fully
     confirmed and implemented. [2])

   2. Instead of blindly passing struct repository *repo down into every
      single low-level library function, bubbling the dependency up is
      the true goal. External callers of the functions must be carefully
      audited to prevent regressions.

   3. Safely remove the old global variables and macro definitions. Make
      full use of Git's existing GitLab/GitHub CI and utilize local
      Meson builds with AddressSanitizer enabled to ensure that the new
      lifecycle introduces zero memory leaks. [3]


Additionally, given the anticipated high volume of commits, we must 
ensure each patch is independent and atomic [4], preventing any 
user-untraceable or unexplainable bugs from occurring in the codebase at 
any state.


AVAILABILITY
------------
Fortunately, my summer vacation perfectly coincides with the GSoC work 
period. I will treat this project as my primary focus, dedicating a 
minimum of 35 hours per week. If needed, I can work a 9-to-5 schedule.

I will have a significant head start to draft RFC patches before the
official coding period even begins. Having this buffer period allows me
to go through the rigorous code review process within the Git community
with greater ease.

I've always kept up the habit of blogging (though previously it was 
mostly literary essays and musings). For this GSoC project, I'll provide 
regular progress updates (every week or every other week). I'll also 
occasionally share technical insights.


TIMELINE & MILESTONES
---------------------
I believe that outlining a rigid, day-by-day schedule months in advance 
is unrealistic for a breathing codebase like Git. I will employ a 
pipeline-driven workflow:

   1. Small refactoring every 3-5 days, major refactoring every 2-3 
weeks, alternating between the two.
   2. After gathering sufficient, well-directed review suggestions, 
revisit and modify the previous refactoring.
   3. Ensure these patches do not depend on one another to prevent a 
domino effect.


Below is the tentative schedule I have prepared for myself:

* Community Bonding (May 1 - May 25): Planning & RFC
   - May 1 - May 7: Wrap up university finals. Discuss and finalize the
     prioritized list of subsystems with my mentor.
   - May 8 - May 25: Categorize the targeted global variables and map out
     their intended destinations (e.g., repo_settings vs 
repo_config_values). Draft and submit
     the initial RFC patch series.

* Phase 1 (May 26 - July 10): Foundation

   - Weeks 1-3: Target straightforward boolean flags and integer configs 
in environment.c (e.g., is_bare_repository_cfg). Plumb the context 
pointer, adapt callers, and dispatch the first 2-3 patch series.
   - Weeks 4-6: Process mailing list feedback and iterate (v2/v3). 
Concurrently begin migrating the next batch of variables. By the midterm 
evaluation, a steady rhythm of proposing, reviewing, and merging should 
be established.

* Phase 2 (July 11 - August 18): Complex Migration & Cleanup

   - Weeks 7-8: Shift focus to higher-complexity variables and string 
configurations (e.g., editor_program, comment_line_str). Apply the 
repo_config_values API where eager loading is strictly required.
   - Weeks 9-10: Finalize the remaining targeted globals. Conduct a 
global audit for any dangling macro definitions (like 
USE_THE_REPOSITORY_VARIABLE in fully refactored subsystems) and 
eliminate them.
   - Weeks 11-12: Update internal documentation 
(Documentation/technical/), ensure all patch series are either merged or 
in a stable state on the next branch, and write the final GSoC report.


~$ git checkout HEAD@{postGSoC}
-------------------------------
I plan to stay active in the community long after the summer ends — 
reviewing related patches, mentoring future newcomers, and seeing the 
libification effort through to the end.

This past month since joining the Git community has been the most 
enjoyable month of my programming journey. To quote a close friend of 
mine (who is applying for the Neovim GSoC project):

   "Only fools chase trends; open source is the game for the brave."

The words may be blunt, but the logic holds true. This statement surely 
resonates with me (and maybe many other GSoC contributors): our passion 
for code and open-source drives us forward.

Even if I didn't make the cut, so what? ~$ git reset --hard…

Jokes aside, diving into Git's codebase this past month has been 
immensely rewarding. Win or lose, I'm here to stay and help.


REFERENCE
-------------------------------
[1]

https://lore.kernel.org/all/48821a3848bef25c13038be8377ad73e7c17a924.1771258573.git.belkid98@gmail.com/

[2]

https://lore.kernel.org/git/CAP8UFD2Q7gctwzGOe+rbgdXZSbDbV0dmM-cx4qt_d8nKi88=HA@mail.gmail.com/T/#t

[3]

https://lore.kernel.org/all/CAOLa=ZR=2B7yH+vtyiAPcCyU17yd2GZwonaj=JRo1f+LzSCoTg@mail.gmail.com/

[4]

https://lore.kernel.org/all/xmqqy0kp7wai.fsf@gitster.g/





-------------------------------------------------------------------------
Changes since V6:

  - Update recent contributions. Rewrite descriptions for some of the 
contributions.

  - Add a section on trade-offs, discussing insights gained from 
challenging scenarios I may encounter.

  - Completely rewrite the schedule.

  - Some expressions have been modified.

Regards,

Yuchen

Re: [GSoC][Draft Proposal v7] Refactoring in order to reduce Git's global state

[Tian Yuchen]

I really hope someone can offer some advice!  After all, the deadline is 
fast approaching...

By the way, I was wondering how the mentors review proposals. Can we 
revise and resubmit them multiple times? Is it better to submit the 
proposal as early as possible?

I’ve made some final (and quite significant) adjustments. Compared to 
v7, it incorporates more personal insights and methodologies. Here’s a 
link to the Google Doc.

https://docs.google.com/document/d/1t2sznOvnPz-9tOzVMH--pLxzRqYSJCFzqVWBVfL_NP8/edit?tab=t.0#heading=h.c3c40ftj1ilv

Regards,

Yuchen

[GSoC Draft Proposal] Refactoring in order to reduce Git's global state

[Burak Kaan Karaçay]

=================================================
Refactoring in order to reduce Git’s global state
=================================================

Personal Info:
--------------

Name: Burak Kaan Karaçay (he/him)
Email: bkkaracay@gmail.com 
Education: UG Sophomore, Marmara University
GitHub: https://github.com/bkkaracay
Timezone: UTC+3 (Istanbul, Turkey)


My Patches:
-----------

+ (Microproject) t2003: modernize path existence checks using test
helpers
   - Thread:
     https://lore.kernel.org/git/20260208202809.270523-1-bkkaracay@gmail.com/T/
   - Thread v2:
     https://lore.kernel.org/git/20260209112444.1268765-1-bkkaracay@gmail.com/T/
   - Status: Merged to master
   - Commit Hash: 168d575719d944759964e004d17a3282b0f883d5

+ [PATCH 0/2] mailmap: reduce global state
   - Thread:
     https://lore.kernel.org/git/20260219125954.3539324-1-bkkaracay@gmail.com/T/
   - Status: Merged to master
   - Commit Hash: 2d843a2d3d6c2d5e7861e6aa99743d15d36746b9


Relevant Experience:
--------------------

I am currently developing my own programming language as a hobby
project, writing a zero-dependency interpreter for it in C. While it is
still a work in progress, I have completed the core front-end pipeline.
Building this project has given me practical experience with C
programming, data structures and modular software architecture.

+ To support potential future multithreading, I avoided global variables
in my own project. Instead, I pass state via local contexts.

+ I implemented an arena allocator (memory pool) to reduce malloc system
call overhead, prevent memory fragmentation and ensure cache locality.

+ I used techniques like string interning and Pratt parsing.

My project is available on my GitHub profile [1]. If you would like to
take a look at the code, 'src/main.c' is a good starting point.


Project Abstract:
-----------------

Git was originally designed as a short-lived CLI tool, where relying on
global variables was highly practical. Over time, the need to embed Git
into other projects and applications emerged. Today, these global
variables are a huge roadblock to the libification of git, as they make
it impossible to properly handle multiple repositories within a single
process or safely support multi-threading.

This project aims to reduce this reliance by migrating global variables
from 'environment.c' into appropriate locations. This effort will
support the libification goal and modernize Git's internal structure.


Technical Approach:
-------------------

The core challenge of this project is choosing the correct parsing
strategy more than relocating globals. The codebase currently offers two
migration strategies for global state removal.

Currently, globals are loaded eagerly via 'repo_config()'. The modern
'repo_config_values()' API provides a safe and straightforward way to
eagerly load variables and reduce global count. However, eager-loading
parses all configurations upfront, including unnecessary ones. Users may
encounter fatal configuration errors that are entirely unrelated to the
command they are executing [2].

On the contrary, lazy-loading postpones the parsing process until the
variable is strictly required, preventing unrelated configuration
errors. However, it is significantly trickier to migrate. If a
misformatted configuration triggers a 'die()' in the middle of the
execution, it risks causing data corruption. Moreover, lazy-loading
changes the timing of error reporting and struggles to replicate
eager-loading behavior when multiple configuration keys affect a single
variable [3].

If lazy-loading is considered safe for variable, git provides two APIs
depending on the performance requirements:

   * The 'repo_config_get*' function set is suitable for variables
   * accessed infrequently because of underlying string hashing costs. It
   * is important to use this API to not bloat the 'struct repo_settings'
   * [2].
   
   * For frequently accessed variables, caching them within 'struct
   * repo_settings' is preferred, as it amortizes hash costs and provides
   * direct memory access speed.

There is no silver bullet solution for migrating globals. Because
transitioning these variables require a deep understanding about the
codebase, communication with mentors and the community is essential.


About Gentle Reading:
---------------------

Current config readers rely on 'die()' to handle error cases. While
pragmatic for cli-tools, fatal exits are unacceptable for a library, as
they will crash the host process. Building upon Derrick Stolee's recent
introduction of gentle parsing functions [4], I propose implementing
'_maybe' variants for core configuration readers. Since removing all
'die()' calls is inevitable for libification, sooner or later config
readers will be purged from 'die()' calls. Utilizing the gentle
functions for newly migrated global variables will reduce the future
amount of work.

Applying this gentle API to widely used functions risks creating
unreviewable patches and merge conflicts. To solve this, I plan to use a
function wrapper approach, similar to the strategy used in early
the_repository migrations [5]. However, the_repository changes are more
mechanical work compared to the gentle transition. In complex call
stacks, a gentle transition risks causing a regression or a scope creep.
Utilizing the "normal" config helpers will be helpful in these
conditions.

Another possible roadblock in the transition is the magic numbers in
error reporting. Some of the functions in Git use -1 and 1 to inform
callers about two different error cases or situations. Introducing a
third hard-coded number to tell callers to stop the Git process for a
misformatted config would be a poor design choice. Furthermore, adopting
a standardized error structure like enum git_error_code is a step toward
git's ongoing libification efforts, as it enables external callers
consuming the API to handle errors programmatically.


Availability:
-------------

I plan to dedicate 40+ hours per week to this project during my active
coding period. However, I want to be completely transparent about my
university's academic calendar to set realistic expectations.

In Turkey, the university summer break begins in July and ends in late
September. During May and June, my schedule will be heavily occupied by
final exams and major group project deadlines. For this reason, my
availability during these two months will be limited to around 10-15
hours per week. I will use this time to stay active on the mailing list,
participate in architectural discussions and submit smaller, preparatory
patches.

To ensure the highest quality of work, I propose utilizing GSoC's
officially supported flexible timeline. I am completely free during
July, August, and September (with no summer school or internships).
During these three months, I will dedicate 40+ hours per week entirely
to git.


Community Bonding (May 1 - May 24):
- Analyze environment.c and create a detailed mitigation plan for each
   variable.
- Discuss the plan with mentors to identify potential roadblocks or edge
   cases.
- Submit a patch about 'enum git_error_code' to start community
   discussion.
- Set up a blog to share bi-weekly updates throughout the project.

Phase 1 (May 25 - June 28):
- Introduce the '_maybe' versions of the config readers and write tests
   for them.
- Begin mitigating "low-hanging" globals. To avoid wasting time while
   waiting for reviews, start drafting subsequent patches concurrently.
- Publish the first progress reports on the blog.

Phase 2 (June 29 - September 15):
- Discuss globals with mentors where mitigations might cause behavioral
   changes.
- Shift focus to the more complex cases, specifically those involving
   eager-lazy or '_maybe' transitions.
- Continue publishing regular blog updates.

Phase 3 (September 16 - September 30):
- Act as a buffer period to respond to final feedback on patches
   currently under review.
- Complete the final project report and publish it on the blog.

References:
-----------

[1] https://github.com/bkkaracay/caret
[2] https://lore.kernel.org/git/xmqq1pk3lmu3.fsf@gitster.g/
[3] https://lore.kernel.org/git/23428022-ab13-4a3e-90ed-ff91ef93f051@gmail.com/
[4] https://lore.kernel.org/all/pull.2044.v3.git.1771849615.gitgitgadget@gmail.com/
[5] https://lore.kernel.org/git/20260109213021.2546-2-l.s.r@web.de/

---

Thanks to everyone for their time and guidance. I'm really excited about
the possibility of working on this project, and any feedback to make
this proposal better is deeply appreciated.

Re: [GSoC Draft Proposal] Refactoring in order to reduce Git's global state

[Christian Couder]

On Sun, Mar 8, 2026 at 12:40 PM Burak Kaan Karaçay <bkkaracay@gmail.com> wrote:

[...]

> My Patches:
> -----------
>
> + (Microproject) t2003: modernize path existence checks using test
> helpers
>    - Thread:
>      https://lore.kernel.org/git/20260208202809.270523-1-bkkaracay@gmail.com/T/
>    - Thread v2:
>      https://lore.kernel.org/git/20260209112444.1268765-1-bkkaracay@gmail.com/T/
>    - Status: Merged to master
>    - Commit Hash: 168d575719d944759964e004d17a3282b0f883d5

Here you gave the commit that was merged.

> + [PATCH 0/2] mailmap: reduce global state
>    - Thread:
>      https://lore.kernel.org/git/20260219125954.3539324-1-bkkaracay@gmail.com/T/
>    - Status: Merged to master
>    - Commit Hash: 2d843a2d3d6c2d5e7861e6aa99743d15d36746b9

Here this is the merge commit. Two commits were actually merged.

[...]

> Technical Approach:
> -------------------

Before discussing that I think you might want to summarize what has
already been done for this project, especially the recent work by
Olamide Bello.

[...]

> Availability:
> -------------
>
> I plan to dedicate 40+ hours per week to this project during my active
> coding period. However, I want to be completely transparent about my
> university's academic calendar to set realistic expectations.
>
> In Turkey, the university summer break begins in July and ends in late
> September. During May and June, my schedule will be heavily occupied by
> final exams and major group project deadlines. For this reason, my
> availability during these two months will be limited to around 10-15
> hours per week. I will use this time to stay active on the mailing list,
> participate in architectural discussions and submit smaller, preparatory
> patches.
>
> To ensure the highest quality of work, I propose utilizing GSoC's
> officially supported flexible timeline. I am completely free during
> July, August, and September (with no summer school or internships).
> During these three months, I will dedicate 40+ hours per week entirely
> to git.

Yeah, I think it could work. Thanks for suggesting this.

> Community Bonding (May 1 - May 24):
> - Analyze environment.c and create a detailed mitigation plan for each
>    variable.
> - Discuss the plan with mentors to identify potential roadblocks or edge
>    cases.
> - Submit a patch about 'enum git_error_code' to start community
>    discussion.

I didn't talk about it earlier, but I am not sure using 'enum
git_error_code' all over the codebase would be a good idea. Perhaps a
few functions would benefit from that, but then the enum could be
specific for these functions.

Thanks.

Re: [GSoC Draft Proposal] Refactoring in order to reduce Git's global state

[Burak Kaan Karaçay]

On Mon, Mar 09, 2026 at 04:17:20PM +0100, Christian Couder wrote:
>I didn't talk about it earlier, but I am not sure using 'enum
>git_error_code' all over the codebase would be a good idea. Perhaps a
>few functions would benefit from that, but then the enum could be
>specific for these functions.

I understand your point. I have also noticed the use of
function-specific enums for error returns in the codebase, which makes a
lot of sense. Because of this, I plan to remove the part about
introducing a global git_error_code from the proposal. Thanks for
pointing this out.

I have also noted your other suggestions regarding Olamide's work and
the commit hashes. I will apply them in the next version of the
proposal.

Thanks for your time and guidance, it is really helpful.