{"thread":{"id":"65276","subject":"[RFC Proposal v2] [GSoC 2026] Improve the new repo command","startedAt":"2026-03-17T14:42:40Z","lastAt":"2026-03-17T14:42:40Z","messageCount":1,"participants":["K Jayatheerth"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"539221","messageId":"CA+rGoLd4ho5AmB3gWYP=yUUKJO=YqthxKX8R_rvN7V7exArn6Q@mail.gmail.com","threadId":"65276","inReplyTo":null,"subject":"[RFC Proposal v2] [GSoC 2026] Improve the new repo command","fromName":"K Jayatheerth","fromEmail":"jayatheerthkulkarni2005@gmail.com","sentAt":"2026-03-17T14:42:27Z","receivedAt":"2026-03-17T14:42:40Z","isPatch":false,"sender":{"key":"jayatheerthkulkarni2005@gmail.com","avatar":"https://avatars.githubusercontent.com/u/148841023?v=4"},"body":"Hi,\n\nThis is version 2 of my proposal\nThe reason why I post this in a new thread is because the\nstructure has entirely changed since the last time.\n\nI have also edited a latex doc\ncan be viewed at [1]\n\nI have also attached a link to the previous thread here [2]\n\nBelow is the inline text format:\n\n--- Start of proposal ---\n\nGSoC 2026 Proposal: Improve the new git repo command\n====================================================\nAuthor:  K Jayatheerth <jayatheerthkulkarni2005@gmail.com>\n\n1. About Me\n-----------\nI am a junior Computer Science undergraduate at Geethanjali College of\nEngineering and Technology with a focus on systems programming.\n\nMy interest in the Git project stems from a desire to\nunderstand the internals of version control and contribute\nto a tool that is fundamental to the global software\ndevelopment ecosystem.\n\nI am applying to this project specifically because I have followed the\ndevelopment of `builtin/repo.c` since its beginning in GSoC 2025. I have\nclosely tracked its evolution through Lucas Oshiro's development blogs\n(https://lucasoshiro.github.io/gsoc-en/) and have studied the\nmailing list discussions.\n\n2. Contact Information\n----------------------\n* Email:      jayatheerthkulkarni2005@gmail.com\n* GitHub:     https://github.com/jayatheerthkulkarni\n* Website:    https://jayatheerth.com/\n* LinkedIn:   https://www.linkedin.com/in/jayatheerth/\n* Timezone:   UTC+05:30 (IST)\n* Tech Stack: C, Shell, Rust, Go\n\n3. Previous Experience with Git\n-------------------------------\nI have been an active contributor to the Git mailing list since February\n2025. I have navigated the full patch lifecycle that includes submission and\nreview to integration into `seen`, `next` and `master`.\n\nMy work has focused on areas directly relevant to this proposal:\npath matching, submodule interactions, and safe memory handling.\n\nI have ensured to not pick any micro-project that would directly affect other\nGSoC applicants.\n\n3.1 Selected Contributions (By Relevance)\n-----------------------------------------\n\n(1) [PATCH v3] dir.c: literal match with wildcard in pathspec should still glob\n    Date:   April 22, 2025\n    Status: Merged into master\n    Link:   https://lore.kernel.org/git/xmqqecxk3u5l.fsf@gitster.g/T/#t\n    Impact: Fixed a logic error in `dir.c` where wildcard pattern matching\n            terminated prematurely.\n\n(2) [PATCH v3] stash: fix incorrect branch name in stash message\n    Date:   June 30, 2025 (Featured in Git Rev News #124)\n    Status: Merged into master\n    Link:   https://git.github.io/rev_news/2025/06/30/edition-124/\n    Impact: Fixed a memory safety issue (static buffer reuse) in\n            `refs_resolve_ref_unsafe` that corrupted stash messages in\n            submodule environments.\n\n(3) [PATCH v3 0/3] clean up a few things\n         ` [PATCH v3 1/3] path: remove unused header\n         ` [PATCH v3 2/3] path: use size_t for dir_prefix length\n         ` [PATCH v3 3/3] path: remove redundant function calls\n    Date:   March 2, 2026\n    Status: Merged into master\n    Link:   https://lore.kernel.org/git/20260302142138.712273-1-jayatheerthkulkarni2005@gmail.com/T/#t\n    Impact: Improves readability and type safety in `path.c`.\n\n(4) [PATCH v8 0/2] Avoid submodule overwritten and skip redundant active entries\n         ` [PATCH v8 1/2] submodule: prevent overwriting .gitmodules\nentry on path reuse\n         ` [PATCH v8 2/2] submodule: skip redundant active entries\nwhen pattern covers path\n    Date:   July 25, 2025\n    Status: Merged into master\n    Link:   https://lore.kernel.org/git/E4F5EF8F-4146-46BA-A498-8493706238A7@gmail.com/T/#t\n    Impact: Prevented accidental overwrites of `.gitmodules` configuration\n            when paths are reused.\n\n(5) [PATCH] repo: Remove unnecessary variable shadow\n    Date:   Febuary 23, 2026\n    Status: Merged into master\n    Link:   https://lore.kernel.org/git/CA+rGoLeppg4Xaoqg6+SZ=ET=ze6rXUbmjLm5UvmitmRGm9u6ag@mail.gmail.com/T/#t\n    Impact: A targeted cleanup in `builtin/repo.c`.\n\n(6) [PATCH v4 0/3] Update MyFirstContribution.adoc to follow modern practices\n         ` [PATCH v4 1/3] docs: remove unused mentoring mailing list reference\n         ` [PATCH v4 2/3] docs: clarify cmd_psuh signature and explain\nUNUSED macro\n         ` [PATCH v4 3/3] docs: replace git_config to repo_config\n    Date:   May 18, 2025\n    Status: Merged into master\n    Link:   https://lore.kernel.org/git/20250518074317.73367-1-jayatheerthkulkarni2005@gmail.com/T/#t\n    Impact: Modernized documentation to reflect current API usage\n(e.g., `repo_config`).\n\n(7) [GSoC] t7101: modernize test path checks (Microproject)\n    Date:   January 09, 2026\n    Status: Merged into master\n    Link:   https://lore.kernel.org/git/CALE2CrS0Q2NS1DbFv4pyRQsuypu=KH6Kurs=m4yWrFbR9QosoA@mail.gmail.com/T/#t\n    Impact: Modernized legacy `test -f` checks to `test_path_is_file`.\n\n3.2 Community Engagement & Design Discussions\n---------------------------------------------\nBeyond my own patch series, I actively participate in technical\ndiscussions to shape the future of the codebase.\n\n(1) [Discussion] Regarding 'repo info' architecture\n    Link: https://lore.kernel.org/git/CA+rGoLfbzXqP1Tw+94jMmWcSGPoefMv5E_fvwriad-O5CUeKHQ@mail.gmail.com/T/#t\n    Context: Participated in discussions regarding the path normalization\n             strategies for the new command.\n\n(2) [Review] Reviewing other contributors' patches\n    Link 1: https://lore.kernel.org/git/20260301165051.90762-1-jayatheerthkulkarni2005@gmail.com/\n    Link 2: https://lore.kernel.org/git/20260224204047.8452-1-valusoutrik@gmail.com/T/#m01db41a20a30efb0d891163f2c3a70c7e0496b51\n    Link 3: https://lore.kernel.org/git/xmqqcy1cz8hw.fsf@gitster.g/T/#mdfe3c15ca5a44f59f44b660dd9690f464d1df676\n    Link 4: https://lore.kernel.org/git/20260310133435.42995-1-jayatheerthkulkarni2005@gmail.com/T/#md1a6f6ef1826c3c17e3ceb1b9e6e5140c9fe688d\n    Context: I review patches from time to time of other contributors\n             to help reduce the burden on maintainers and ensure code quality.\n\n(3) [Discussion] Regarding 'git pull --rebase' fork-point behavior\n    Link: https://lore.kernel.org/git/177a25f0-7292-4ee7-8a02-9c90a5979313@gmail.com/T/#ma5cc64a2a62cb622ab4d6afbc45e9d48733a748c\n    Context: Wanted clarification on the fork-point heuristic\n             and identified the core internal functions\n             (get_rebase_fork_point() and\nget_rebase_newbase_and_upstream()) responsible for the behavior to\nbegin exploring potential\n             approaches for a fix.\n\n4. Project Proposal\n-------------------\nTaken from the ideas page of the GSoC 2026 projects list, the goal of this\nproject is to improve the existing git repo command. To specify the\nobjectives in detail, this proposal covers three main goals:\n\na. Add path.* keys into the repo info command.\nb. Remove the USE_THE_REPOSITORY_VARIABLE.\nc. Form categories for the keys for the git repo command.\n\nI had a hard time picking which of these to keep out of scope,\nas I equally liked all the ideas in the proposal.\nHowever, taking timeline into consideration, I have moved Goal d to\na stretch goal/post-GSoC commitment to ensure the core deliverables\nare highly stable.\n\nd. Study and collaborate with Justin Tobler for git structure work.\n\nGoal a: Add path.* keys into the repo info command\n--------------------------------------------------\nThis is currently a high-activity area on the mailing list. To avoid\nredundant effort or conflicting patches, my strategy will be adaptive\nbased on the state of the tree during the Community Bonding period.\n\nI have reviewed the overlapping patch series submitted by Lucas Oshiro\nand Eslam Reda. Since discussions are already ongoing, my goal is to\nbuild upon their foundation rather than reinventing it. I am already\nactively participating in the core design discussions on the mailing list\n(https://lore.kernel.org/git/20260228224252.72788-1-lucasseikioshiro@gmail.com/T/#u)\nregarding how to handle relative versus absolute path outputs. We are\ncurrently weighing several approaches: global `--path-format` flags,\nstateless virtual keys (e.g., `path.absolute.toplevel`), and `ref-filter`\nstyle format modifiers. I will prioritize finalizing this design consensus\nduring the bonding period, and then focus on implementing the remaining\ncore keys and cross-platform edge cases.\n\nI will ensure the following keys are fully supported and tested by the\nend of the GSoC timeline:\n\n  * path.git-dir\n  * path.common-dir\n  * path.worktree\n  * path.objects\n  * path.hooks\n  * path.index\n  * path.grafts\n\nIf these keys are already added by the time I am selected, I would happily\nfocus on the other goals or the stretch goals.\n\nGoal b: Remove USE_THE_REPOSITORY_VARIABLE\n---------------------------------------------------------------------------\nRemoving this macro is a priority to ensure the new command is library-safe.\nI have identified that `get_layout_bare(struct repository *repo UNUSED, ...)`\nis the primary inhibitor in `builtin/repo.c`.\n\nCurrently, this function ignores its argument and uses the global\n`is_bare_repository()` macro.\n\nMy implementation plan is as follows:\n1.  Refactor `get_layout_bare` to drop the `UNUSED` tag and explicitly use\n    its `repo` argument.\n2.  Replace the global macro call with a check against `repo->worktree`.\n    As defined in `repository.h`, a `NULL` value for `repo->worktree`\n    indicates the absence of a working directory (i.e., a bare repository).\n3.  This removes the dependency on global state without requiring changes to\n    the `struct repository` definition itself.\n\nThis change allows `builtin/repo.c` to drop the global state macro entirely,\nmaking the command fully reentrant and library-safe.\n\nGoal c: Implement Category-Based Querying (Structured Discovery)\n----------------------------------------------------------------\nThe current implementation of `repo info` suffers from an \"all-or-nothing\"\nusability problem. Users must either know the exact key name or dump the\nentire configuration.\n\nMy proposal is to implement Prefix-Based Querying.\n\nThe internal `repo_info_fields` array is already structured for this:\n\n    static const struct field repo_info_fields[] = {\n        { \"layout.bare\", get_layout_bare },\n        { \"layout.shallow\", get_layout_shallow },\n        ...\n    };\n\nSince this array is lexicographically sorted, I can implement efficient\nlookup without new data structures:\n\n1.  Use `bsearch` to find the first key matching the requested prefix\n    (e.g., `git repo info layout`).\n2.  Iterate linearly from that point, printing keys as long as the prefix\n    matches.\n3.  Stop immediately when the prefix no longer matches.\n\nNote: the next goal is a stretch goal. I have only added these goals\nsince I had already done the research and had to cut it off only\nbecause of timeline.\n\nGoal d: Repository Health Diagnostics and Metric Distributions\n--------------------------------------------------------------\nWhile 'git repo structure' recently gained the ability to surface basic\nobject counts and maximum sizes through Justin Tobler's recent patch\nseries (now in 'next'), the command still presents data as raw, isolated\nextremes.\n\nMy goal is to evolve 'git repo structure' into a comprehensive diagnostic\ntool by introducing metric distributions, packfile analysis, and actionable\nhealth thresholds.\n\n1. Object Size and Entry Distributions (Histograms):\n   As discussed recently on the mailing list by Patrick Steinhardt and\n   Junio C Hamano, extreme maximums are useful, but distributions provide\n   the real picture of repository health. I will implement a streaming\n   bucketing system during the object walk to track size distributions\n   (e.g., blob sizes) and entry distributions (e.g., tree entry counts).\n   These will be formatted into an optional ASCII bar chart output to\n   visualize repository shape.\n\n2. Packfile and Pathological Path Metrics:\n   I will expand the traversal to capture metrics that directly impact\n   performance and cross-platform compatibility:\n     * Longest Delta Chains: Excessively long delta chains degrade packfile\n       performance and clone times.\n     * Maximum Path Depth & Length: Critical for identifying paths that\n       silently break checkouts on systems with path-length limits\n(e.g., Windows).\n\n3. Threshold and Concern Levels:\n   Currently, the command dumps data agnostically. Inspired by the 'level of\n   concern' logic in tools like 'git-sizer', I will introduce a mechanism\n   to visually flag metrics that exceed typical Git \"sweet spots\"\n   (e.g., flagging trees with >1000 entries, or >10 octopus merge parents).\n   This transforms the command into an actionable CI/CD health-check tool.\n\n4. Integration into the Query Architecture:\n   I will ensure that both these new diagnostic metrics and the recently\n   introduced ODB extremes (max parents, max tree entries) are seamlessly\n   integrated into the prefix-based querying system proposed in Goal c,\n   respecting the context-aware libification from Goal b.\n\nApproach\n--------\nI understand the review cycle of Git cannot always be quick, therefore\nmy timeline is designed to buffer patch series and pivot between tasks\nwhile waiting for reviews.\n\nTo maximize productivity while respecting Git's review cycles and\npreventing merge conflicts, I am splitting the core work into two tracks:\n\ni. Track - a (The Foundation): This will include Goal a (path.* keys)\n   and Goal b (Libification). Completing path resolution and safely\n   removing global state provides the clean foundation required for\n   building a new querying API.\nii. Track - b (The API): This will include Goal c (Query Architecture).\n   Development here will fully spin up once Track a is stabilized.\n\n5. Timeline\n-----------\nI will dedicate 35-40 hours per week to this project. Because Git uses an\nasynchronous mailing list review process, my timeline is designed to build\npatch series with ample buffer room for design iterations.\n\nCommunity Bonding Period (May 1 - May 24, 2026)\n* Synchronize with Lucas Oshiro and mentors on the current state of 'path.*'\n  architecture in the master branch.\n* Finalize the exact list of remaining path keys needed.\n* Publish my introductory GSoC blog post on jayatheerth.com/blogs.\n* Pick up a small RFC question if we need globs in querying keys.\n\n\nPhase 1: Track a Execution (May 25 – July 10, 2026)\nThis phase focuses strictly on stabilizing Track a: Goal a (path.* keys)\nand Goal b (Libification).\n\n* Weeks 1 - 4 (May 25 – June 21):\n  - Work concurrently on Track a deliverables to build the command's foundation.\n  - Implement the core missing `path.*` keys locally (git-dir, common-dir,\n    worktree, objects, hooks) and write comprehensive, OS-agnostic tests in t/.\n  - Refactor `get_layout_bare` to drop the UNUSED macro and completely remove\n    `USE_THE_REPOSITORY_VARIABLE` from `builtin/repo.c`.\n  - Milestone: Submit [PATCH v1] series for both Goal a (Paths) and Goal b\n    (Libification).\n\n* Weeks 5 - 7 (June 22 – July 10):\n  - Buffer time for asynchronous review cycles. Address mailing list feedback\n    for Track a patches and submit subsequent versions ([PATCH v2], etc.).\n  - Midterm Evaluation: Ensure Track a patch series are stabilized and\n    queued in `next`.\n  - Publish a detailed halfway-point blog post.\n\nPhase 2: Track b Execution (July 11 – August 21, 2026)\nWith Track a stabilizing, development shifts entirely to Goal c\n(Query Architecture).\n\n* Weeks 8 - 9 (July 11 – July 24):\n  - Using the feedback from the community bonding RFC, implement the\n    query system.\n\n* Weeks 10 - 11 (July 25 – August 7):\n  - Run the full test suite and ensure querying handles all edge cases.\n  - Milestone: Submit [PATCH v1] encompassing the Goal c query architecture.\n\n* Weeks 12 - 13 (August 8 – August 21) [Buffer & Review Weeks]:\n  - Dedicated time for addressing potentially complex architectural reviews for\n    the querying patch series.\n  - Submit subsequent patch versions ([PATCH v2], [PATCH v3]).\n  - Catch up on any unforeseen edge cases from previous weeks.\n\nPhase 3: Final Handoff (August 22 – August 31, 2026)\n* Write the final project report and publish the concluding blog post.\n* Submit the Final GSoC Evaluation.\n\n5.1 Stretch Goals: Repository Structure Diagnostics\n---------------------------------------------------\nIf the core `repo info` deliverables (Paths, Libification, and Querying)\nare completed and merged ahead of schedule, I will pivot to extending the\n`git repo structure` command (Goal d). I will prioritize implementing the\nstreaming bucketing system during the object walk to output ASCII histograms\nfor Object Size and Tree Entry distributions.\n\n6. Availability\n---------------\nThis timeline aligns perfectly with my schedule. The project kicks off in May\nand June during which I will be on summer vacation and can dedicate 35-50\nhours a week. During July, I will transition into my final year of university.\nMy academic schedule during this period is highly flexible.\n\n7. Blogging\n-----------\nI have a domain setup at jayatheerth.com. As patches flow and the\nproject progresses,\nI will host a dedicated endpoint at `/blogs` to provide comprehensive,\nweekly and a phase wise coverage of my project.\n\n8. Post GSoC\n------------\nI actively follow the mailing list and intend to continue contributing\nbug fixes and enhancements. I would absolutely complete Goal d\nin case no one has any reservations.\nI have been a part of the Git community since 2025 and\nhopefully will continue to be one for a long time.\n\nProbably mentoring the next year GSoC applicants if that is a possibility.\n\n--- End of Proposal ---\n\n\n\nRegards,\n- Jayatheerth\n\n\n1 - https://jayatheerth.com/blogs/gsoc/jayatheerth_kulkarni_gsoc.pdf\n2 - https://lore.kernel.org/git/CAOLa=ZS6HtJrWd0kfsFASCbP2S9-MQq5Da3feA0WqY8ykZ0WTw@mail.gmail.com/T/#me6d18e613cdc75b1a0181252ae261e578a80bde9\n"}]}