{"thread":{"id":"65167","subject":"[GSoC Draft Proposal] Refactoring in order to reduce Git's global state","startedAt":"2026-03-08T11:40:41Z","lastAt":"2026-03-15T09:53:01Z","messageCount":4,"participants":["Burak Kaan Karaçay","Christian Couder"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"538195","messageId":"aa1cn0_ATfh-uRE4@gmail.com","threadId":"65167","inReplyTo":null,"subject":"[GSoC Draft Proposal] Refactoring in order to reduce Git's global state","fromName":"Burak Kaan Karaçay","fromEmail":"bkkaracay@gmail.com","sentAt":"2026-03-08T11:40:35Z","receivedAt":"2026-03-08T11:40:41Z","isPatch":false,"sender":{"key":"bkkaracay@gmail.com","avatar":"https://avatars.githubusercontent.com/u/29117336?v=4"},"body":"=================================================\nRefactoring in order to reduce Git’s global state\n=================================================\n\nPersonal Info:\n--------------\n\nName: Burak Kaan Karaçay (he/him)\nEmail: bkkaracay@gmail.com \nEducation: UG Sophomore, Marmara University\nGitHub: https://github.com/bkkaracay\nTimezone: UTC+3 (Istanbul, Turkey)\n\n\nMy Patches:\n-----------\n\n+ (Microproject) t2003: modernize path existence checks using test\nhelpers\n - Thread:\n https://lore.kernel.org/git/20260208202809.270523-1-bkkaracay@gmail.com/T/\n - Thread v2:\n https://lore.kernel.org/git/20260209112444.1268765-1-bkkaracay@gmail.com/T/\n - Status: Merged to master\n - Commit Hash: 168d575719d944759964e004d17a3282b0f883d5\n\n+ [PATCH 0/2] mailmap: reduce global state\n - Thread:\n https://lore.kernel.org/git/20260219125954.3539324-1-bkkaracay@gmail.com/T/\n - Status: Merged to master\n - Commit Hash: 2d843a2d3d6c2d5e7861e6aa99743d15d36746b9\n\n\nRelevant Experience:\n--------------------\n\nI am currently developing my own programming language as a hobby\nproject, writing a zero-dependency interpreter for it in C. While it is\nstill a work in progress, I have completed the core front-end pipeline.\nBuilding this project has given me practical experience with C\nprogramming, data structures and modular software architecture.\n\n+ To support potential future multithreading, I avoided global variables\nin my own project. Instead, I pass state via local contexts.\n\n+ I implemented an arena allocator (memory pool) to reduce malloc system\ncall overhead, prevent memory fragmentation and ensure cache locality.\n\n+ I used techniques like string interning and Pratt parsing.\n\nMy project is available on my GitHub profile [1]. If you would like to\ntake a look at the code, 'src/main.c' is a good starting point.\n\n\nProject Abstract:\n-----------------\n\nGit was originally designed as a short-lived CLI tool, where relying on\nglobal variables was highly practical. Over time, the need to embed Git\ninto other projects and applications emerged. Today, these global\nvariables are a huge roadblock to the libification of git, as they make\nit impossible to properly handle multiple repositories within a single\nprocess or safely support multi-threading.\n\nThis project aims to reduce this reliance by migrating global variables\nfrom 'environment.c' into appropriate locations. This effort will\nsupport the libification goal and modernize Git's internal structure.\n\n\nTechnical Approach:\n-------------------\n\nThe core challenge of this project is choosing the correct parsing\nstrategy more than relocating globals. The codebase currently offers two\nmigration strategies for global state removal.\n\nCurrently, globals are loaded eagerly via 'repo_config()'. The modern\n'repo_config_values()' API provides a safe and straightforward way to\neagerly load variables and reduce global count. However, eager-loading\nparses all configurations upfront, including unnecessary ones. Users may\nencounter fatal configuration errors that are entirely unrelated to the\ncommand they are executing [2].\n\nOn the contrary, lazy-loading postpones the parsing process until the\nvariable is strictly required, preventing unrelated configuration\nerrors. However, it is significantly trickier to migrate. If a\nmisformatted configuration triggers a 'die()' in the middle of the\nexecution, it risks causing data corruption. Moreover, lazy-loading\nchanges the timing of error reporting and struggles to replicate\neager-loading behavior when multiple configuration keys affect a single\nvariable [3].\n\nIf lazy-loading is considered safe for variable, git provides two APIs\ndepending on the performance requirements:\n\n * The 'repo_config_get*' function set is suitable for variables\n * accessed infrequently because of underlying string hashing costs. It\n * is important to use this API to not bloat the 'struct repo_settings'\n * [2].\n \n * For frequently accessed variables, caching them within 'struct\n * repo_settings' is preferred, as it amortizes hash costs and provides\n * direct memory access speed.\n\nThere is no silver bullet solution for migrating globals. Because\ntransitioning these variables require a deep understanding about the\ncodebase, communication with mentors and the community is essential.\n\n\nAbout Gentle Reading:\n---------------------\n\nCurrent config readers rely on 'die()' to handle error cases. While\npragmatic for cli-tools, fatal exits are unacceptable for a library, as\nthey will crash the host process. Building upon Derrick Stolee's recent\nintroduction of gentle parsing functions [4], I propose implementing\n'_maybe' variants for core configuration readers. Since removing all\n'die()' calls is inevitable for libification, sooner or later config\nreaders will be purged from 'die()' calls. Utilizing the gentle\nfunctions for newly migrated global variables will reduce the future\namount of work.\n\nApplying this gentle API to widely used functions risks creating\nunreviewable patches and merge conflicts. To solve this, I plan to use a\nfunction wrapper approach, similar to the strategy used in early\nthe_repository migrations [5]. However, the_repository changes are more\nmechanical work compared to the gentle transition. In complex call\nstacks, a gentle transition risks causing a regression or a scope creep.\nUtilizing the \"normal\" config helpers will be helpful in these\nconditions.\n\nAnother possible roadblock in the transition is the magic numbers in\nerror reporting. Some of the functions in Git use -1 and 1 to inform\ncallers about two different error cases or situations. Introducing a\nthird hard-coded number to tell callers to stop the Git process for a\nmisformatted config would be a poor design choice. Furthermore, adopting\na standardized error structure like enum git_error_code is a step toward\ngit's ongoing libification efforts, as it enables external callers\nconsuming the API to handle errors programmatically.\n\n\nAvailability:\n-------------\n\nI plan to dedicate 40+ hours per week to this project during my active\ncoding period. However, I want to be completely transparent about my\nuniversity's academic calendar to set realistic expectations.\n\nIn Turkey, the university summer break begins in July and ends in late\nSeptember. During May and June, my schedule will be heavily occupied by\nfinal exams and major group project deadlines. For this reason, my\navailability during these two months will be limited to around 10-15\nhours per week. I will use this time to stay active on the mailing list,\nparticipate in architectural discussions and submit smaller, preparatory\npatches.\n\nTo ensure the highest quality of work, I propose utilizing GSoC's\nofficially supported flexible timeline. I am completely free during\nJuly, August, and September (with no summer school or internships).\nDuring these three months, I will dedicate 40+ hours per week entirely\nto git.\n\n\nCommunity Bonding (May 1 - May 24):\n- Analyze environment.c and create a detailed mitigation plan for each\n variable.\n- Discuss the plan with mentors to identify potential roadblocks or edge\n cases.\n- Submit a patch about 'enum git_error_code' to start community\n discussion.\n- Set up a blog to share bi-weekly updates throughout the project.\n\nPhase 1 (May 25 - June 28):\n- Introduce the '_maybe' versions of the config readers and write tests\n for them.\n- Begin mitigating \"low-hanging\" globals. To avoid wasting time while\n waiting for reviews, start drafting subsequent patches concurrently.\n- Publish the first progress reports on the blog.\n\nPhase 2 (June 29 - September 15):\n- Discuss globals with mentors where mitigations might cause behavioral\n changes.\n- Shift focus to the more complex cases, specifically those involving\n eager-lazy or '_maybe' transitions.\n- Continue publishing regular blog updates.\n\nPhase 3 (September 16 - September 30):\n- Act as a buffer period to respond to final feedback on patches\n currently under review.\n- Complete the final project report and publish it on the blog.\n\nReferences:\n-----------\n\n[1] https://github.com/bkkaracay/caret\n[2] https://lore.kernel.org/git/xmqq1pk3lmu3.fsf@gitster.g/\n[3] https://lore.kernel.org/git/23428022-ab13-4a3e-90ed-ff91ef93f051@gmail.com/\n[4] https://lore.kernel.org/all/pull.2044.v3.git.1771849615.gitgitgadget@gmail.com/\n[5] https://lore.kernel.org/git/20260109213021.2546-2-l.s.r@web.de/\n\n---\n\nThanks to everyone for their time and guidance. I'm really excited about\nthe possibility of working on this project, and any feedback to make\nthis proposal better is deeply appreciated.\n"},{"id":"538288","messageId":"CAP8UFD391QPtk3Mtt5z17ivdVMk9EEWZuKhVtt7X9Twm7WTpRg@mail.gmail.com","threadId":"65167","inReplyTo":"aa1cn0_ATfh-uRE4@gmail.com","subject":"Re: [GSoC Draft Proposal] Refactoring in order to reduce Git's global state","fromName":"Christian Couder","fromEmail":"christian.couder@gmail.com","sentAt":"2026-03-09T15:17:20Z","receivedAt":"2026-03-09T15:17:34Z","isPatch":false,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"On Sun, Mar 8, 2026 at 12:40 PM Burak Kaan Karaçay wrote:\n\n[...]\n\n> My Patches:\n> -----------\n>\n> + (Microproject) t2003: modernize path existence checks using test\n> helpers\n> - Thread:\n> https://lore.kernel.org/git/20260208202809.270523-1-bkkaracay@gmail.com/T/\n> - Thread v2:\n> https://lore.kernel.org/git/20260209112444.1268765-1-bkkaracay@gmail.com/T/\n> - Status: Merged to master\n> - Commit Hash: 168d575719d944759964e004d17a3282b0f883d5\n\nHere you gave the commit that was merged.\n\n> + [PATCH 0/2] mailmap: reduce global state\n> - Thread:\n> https://lore.kernel.org/git/20260219125954.3539324-1-bkkaracay@gmail.com/T/\n> - Status: Merged to master\n> - Commit Hash: 2d843a2d3d6c2d5e7861e6aa99743d15d36746b9\n\nHere this is the merge commit. Two commits were actually merged.\n\n[...]\n\n> Technical Approach:\n> -------------------\n\nBefore discussing that I think you might want to summarize what has\nalready been done for this project, especially the recent work by\nOlamide Bello.\n\n[...]\n\n> Availability:\n> -------------\n>\n> I plan to dedicate 40+ hours per week to this project during my active\n> coding period. However, I want to be completely transparent about my\n> university's academic calendar to set realistic expectations.\n>\n> In Turkey, the university summer break begins in July and ends in late\n> September. During May and June, my schedule will be heavily occupied by\n> final exams and major group project deadlines. For this reason, my\n> availability during these two months will be limited to around 10-15\n> hours per week. I will use this time to stay active on the mailing list,\n> participate in architectural discussions and submit smaller, preparatory\n> patches.\n>\n> To ensure the highest quality of work, I propose utilizing GSoC's\n> officially supported flexible timeline. I am completely free during\n> July, August, and September (with no summer school or internships).\n> During these three months, I will dedicate 40+ hours per week entirely\n> to git.\n\nYeah, I think it could work. Thanks for suggesting this.\n\n> Community Bonding (May 1 - May 24):\n> - Analyze environment.c and create a detailed mitigation plan for each\n> variable.\n> - Discuss the plan with mentors to identify potential roadblocks or edge\n> cases.\n> - Submit a patch about 'enum git_error_code' to start community\n> discussion.\n\nI didn't talk about it earlier, but I am not sure using 'enum\ngit_error_code' all over the codebase would be a good idea. Perhaps a\nfew functions would benefit from that, but then the enum could be\nspecific for these functions.\n\nThanks.\n"},{"id":"538655","messageId":"abGhquQz_mxK_Ow8@gmail.com","threadId":"65167","inReplyTo":"CAP8UFD391QPtk3Mtt5z17ivdVMk9EEWZuKhVtt7X9Twm7WTpRg@mail.gmail.com","subject":"Re: [GSoC Draft Proposal] Refactoring in order to reduce Git's global state","fromName":"Burak Kaan Karaçay","fromEmail":"bkkaracay@gmail.com","sentAt":"2026-03-11T18:34:14Z","receivedAt":"2026-03-11T18:34:23Z","isPatch":false,"sender":{"key":"bkkaracay@gmail.com","avatar":"https://avatars.githubusercontent.com/u/29117336?v=4"},"body":"On Mon, Mar 09, 2026 at 04:17:20PM +0100, Christian Couder wrote:\n>I didn't talk about it earlier, but I am not sure using 'enum\n>git_error_code' all over the codebase would be a good idea. Perhaps a\n>few functions would benefit from that, but then the enum could be\n>specific for these functions.\n\nI understand your point. I have also noticed the use of\nfunction-specific enums for error returns in the codebase, which makes a\nlot of sense. Because of this, I plan to remove the part about\nintroducing a global git_error_code from the proposal. Thanks for\npointing this out.\n\nI have also noted your other suggestions regarding Olamide's work and\nthe commit hashes. I will apply them in the next version of the\nproposal.\n\nThanks for your time and guidance, it is really helpful.\n"},{"id":"539021","messageId":"DH39IOSGA9U9.K4GIHJXAPHX7@gmail.com","threadId":"65167","inReplyTo":"aa1cn0_ATfh-uRE4@gmail.com","subject":"[GSoC Draft Proposal v2] Refactoring in order to reduce Git's global state","fromName":"Burak Kaan Karaçay","fromEmail":"bkkaracay@gmail.com","sentAt":"2026-03-15T09:52:57Z","receivedAt":"2026-03-15T09:53:01Z","isPatch":false,"sender":{"key":"bkkaracay@gmail.com","avatar":"https://avatars.githubusercontent.com/u/29117336?v=4"},"body":"Changes in v2:\n- Clarified merge commit - commit hash difference.\n- Added 'Project Background' section.\n- Refined the part about Olamide's API in 'Technical Approach'.\n- Removed 'enum git_error_code' proposal.\n\nThanks for time and guidance.\n\n---\n\n=================================================\nRefactoring in order to reduce Git’s global state\n=================================================\n\nPersonal Info:\n--------------\n\nName: Burak Kaan Karaçay (he/him)\nEmail: bkkaracay@gmail.com \nEducation: UG Sophomore, Marmara University\nGitHub: https://github.com/bkkaracay\nTimezone: UTC+3 (Istanbul, Turkey)\n\n\nMy Patches:\n-----------\n\n+ (Microproject) t2003: modernize path existence checks using test\nhelpers\n - Thread:\n https://lore.kernel.org/git/20260208202809.270523-1-bkkaracay@gmail.com/T/\n - Thread v2:\n https://lore.kernel.org/git/20260209112444.1268765-1-bkkaracay@gmail.com/T/\n - Status: Merged to master\n - Merge Commit Hash: 70d3916a7db5233ce01f2f3f36ee04d57c0f9252\n\n+ [PATCH v2 0/2] mailmap: reduce global state\n - Thread:\n https://lore.kernel.org/git/20260219125954.3539324-1-bkkaracay@gmail.com/T/\n - Status: Merged to master\n - Merge Commit Hash: 2d843a2d3d6c2d5e7861e6aa99743d15d36746b9\n \n+ [PATCH v3 0/2] run-command: stop using the_repository\n - Thread:\n https://lore.kernel.org/git/20260311151923.4178655-1-bkkaracay@gmail.com/T/\n - Status: Will merge to master\n - Merge Commit Hash (next): 61ffe62b75cf89af469af53b15f3fdc6639d217a\n\n\nRelevant Experience:\n--------------------\n\nI am currently developing my own programming language as a hobby\nproject, writing a zero-dependency interpreter for it in C. While it is\nstill a work in progress, I have completed the core front-end pipeline.\nBuilding this project has given me practical experience with C\nprogramming, data structures and modular software architecture.\n\n+ To support potential future multithreading, I avoided global variables\nin my own project. Instead, I pass state via local contexts.\n\n+ I implemented an arena allocator (memory pool) to reduce malloc system\ncall overhead, prevent memory fragmentation and ensure cache locality.\n\n+ I used techniques like string interning and Pratt parsing.\n\nMy project is available on my GitHub profile [1]. If you would like to\ntake a look at the code, 'src/main.c' is a good starting point.\n\n\nProject Abstract:\n-----------------\n\nGit was originally designed as a short-lived CLI tool, where relying on\nglobal variables was highly practical. Over time, the need to embed Git\ninto other projects and applications emerged. Today, these global\nvariables are a huge roadblock to the libification of git, as they make\nit impossible to properly handle multiple repositories within a single\nprocess or safely support multi-threading.\n\nThis project aims to reduce this reliance by migrating global variables\nfrom 'environment.c' into appropriate locations. This effort will\nsupport the libification goal and modernize Git's internal structure.\n\n\nProject Background:\n-------------------\n\nDiscussions surrounding the \"libification\" of git date back as early as\n2005 [2]. However, efforts to isolate global state in environment.c\naccelerated following Patrick Steinhardt's groundwork in 2024.\n\nOnce the environment.c cleanup became an official GSoC project, the\npatch series from the first intern in this area, Ayush Chandekar,\nprovided valuable lessons on best practices and potential pitfalls.\nDuring the later stages of Ayush's internship, the limitations and\nsafety risks of lazy-parsing became apparent. To solve this bottleneck,\nPhillip Wood proposed a new eager-loading API, which was successfully\nimplemented by Outreachy intern Olamide Caleb Bello. Although this API\nis currently functional, to avoid invasive changes across the codebase,\nit can currently only read config values from 'the_repository' [3].\n\n\nTechnical Approach:\n-------------------\n\nThe core challenge of this project is choosing the correct parsing\nstrategy more than relocating globals. The codebase currently offers two\nmigration strategies for global state removal.\n\nCurrently, globals are loaded eagerly via 'repo_config()'. Olamide's\n'struct config_values' API provides a modern way to load these globals\neagerly by parsing them into fields in 'repo->cfg_values'. However,\neager-loading parses all configurations upfront, including unnecessary\nones. Users may encounter fatal configuration errors that are entirely\nunrelated to the command they are executing [4].\n\nOn the contrary, lazy-loading postpones the parsing process until the\nvariable is strictly required, preventing unrelated configuration\nerrors. However, it is significantly trickier to migrate. If a\nmisformatted configuration triggers a 'die()' in the middle of the\nexecution, it risks causing data corruption. Moreover, lazy-loading\nchanges the timing of error reporting and struggles to replicate\neager-loading behavior when multiple configuration keys affect a single\nvariable [5].\n\nIf lazy-loading is considered safe for variable, git provides two APIs\ndepending on the performance requirements:\n\n * The 'repo_config_get*' function set is suitable for variables\n accessed infrequently because of underlying string hashing costs. It\n is important to use this API to not bloat the 'struct repo_settings'\n [4].\n \n * For frequently accessed variables, caching them within 'struct\n repo_settings' is preferred, as it amortizes hash costs and provides\n direct memory access speed.\n\nThere is no silver bullet solution for migrating globals. Because\ntransitioning these variables require a deep understanding about the\ncodebase, communication with mentors and the community is essential.\n\n\nAbout Gentle Reading:\n---------------------\n\nCurrent config readers rely on 'die()' to handle error cases. While\npragmatic for cli-tools, fatal exits are unacceptable for a library, as\nthey will crash the host process. Building upon Derrick Stolee's recent\nintroduction of gentle parsing functions [6], I propose implementing\n'_maybe' variants for core configuration readers. Since removing all\n'die()' calls is inevitable for libification, sooner or later config\nreaders will be purged from 'die()' calls. Utilizing the gentle\nfunctions for newly migrated global variables will reduce the future\namount of work.\n\nApplying this gentle API to widely used functions risks creating\nunreviewable patches and merge conflicts. To solve this, I plan to use a\nfunction wrapper approach, similar to the strategy used in early\nthe_repository migrations [7]. However, the_repository changes are more\nmechanical work compared to the gentle transition. In complex call\nstacks, a gentle transition risks causing a regression or a scope creep.\nUtilizing the \"normal\" config helpers will be helpful in these\nconditions.\n\n\nAvailability:\n-------------\n\nI plan to dedicate 40+ hours per week to this project during my active\ncoding period. However, I want to be completely transparent about my\nuniversity's academic calendar to set realistic expectations.\n\nIn Turkey, the university summer break begins in July and ends in late\nSeptember. During May and June, my schedule will be heavily occupied by\nfinal exams and major group project deadlines. For this reason, my\navailability during these two months will be limited to around 10-15\nhours per week. I will use this time to stay active on the mailing list,\nparticipate in architectural discussions and submit smaller, preparatory\npatches.\n\nTo ensure the highest quality of work, I propose utilizing GSoC's\nofficially supported flexible timeline. I am completely free during\nJuly, August, and September (with no summer school or internships).\nDuring these three months, I will dedicate 40+ hours per week entirely\nto git.\n\n\nCommunity Bonding (May 1 - May 24):\n- Analyze environment.c and create a detailed mitigation plan for each\n variable.\n- Discuss the plan with mentors to identify potential roadblocks or edge\n cases.\n- Set up a blog to share bi-weekly updates throughout the project.\n\nPhase 1 (May 25 - June 28):\n- Introduce the '_maybe' versions of the config readers and write tests\n for them.\n- Begin mitigating \"low-hanging\" globals. To avoid wasting time while\n waiting for reviews, start drafting next patches.\n- Publish the first progress reports on the blog.\n\nPhase 2 (June 29 - September 15):\n- Discuss globals with mentors where mitigations might cause behavioral\n changes.\n- Shift focus to the more complex cases, specifically those involving\n eager-lazy or '_maybe' transitions.\n- Continue publishing regular blog updates.\n\nPhase 3 (September 16 - September 30):\n- Act as a buffer period to respond to final feedback on patches\n currently under review.\n- Complete the final project report and publish it on the blog.\n\nReferences:\n-----------\n\n[1] https://github.com/bkkaracay/caret\n[2] https://lore.kernel.org/git/7vpsr6ymg3.fsf_-_@assigned-by-dhcp.cox.net/\n[3] https://cloobtech.hashnode.dev/week-5-and-6-design-reviews-rfcs-and-refining-the-path-forward\n[4] https://lore.kernel.org/git/xmqq1pk3lmu3.fsf@gitster.g/\n[5] https://lore.kernel.org/git/23428022-ab13-4a3e-90ed-ff91ef93f051@gmail.com/\n[6] https://lore.kernel.org/all/pull.2044.v3.git.1771849615.gitgitgadget@gmail.com/\n[7] https://lore.kernel.org/git/20260109213021.2546-2-l.s.r@web.de/\n"}]}