{"thread":{"id":"63224","subject":"[GSOC] [Proposal v1] Machine-Readable Repository Information Query Tool","startedAt":"2025-03-31T14:51:39Z","lastAt":"2025-04-07T02:32:38Z","messageCount":12,"participants":["JAYATHEERTH K","Patrick Steinhardt","Karthik Nayak","Kaartic Sivaraam"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"515365","messageId":"CA+rGoLfxZHdns=7FwQuYS=JANrR9zDP-dOpV2AxM1hC1Lc9wiw@mail.gmail.com","threadId":"63224","inReplyTo":null,"subject":"[GSOC] [Proposal v1] Machine-Readable Repository Information Query Tool","fromName":"JAYATHEERTH K","fromEmail":"jayatheerthkulkarni2005@gmail.com","sentAt":"2025-03-31T14:51:27Z","receivedAt":"2025-03-31T14:51:39Z","isPatch":false,"sender":{"key":"jayatheerthkulkarni2005@gmail.com","avatar":"https://avatars.githubusercontent.com/u/148841023?v=4"},"body":"# Proposal for GSOC 2025 to Git\n**Machine-Readable Repository Information Query Tool**\n\n## Contact Details\n* **Name**: K Jayatheerth\n* **Email**: jayatheerthkulkarni2005@gmail.com\n* **Blog**: [Blog](https://jayatheerthkulkarni.github.io/gsoc_blog/index.html)\n* **GitHub**: [GitHub](https://github.com/jayatheerthkulkarni)\n\n## **Synopsis**\nThis project aims to develop a dedicated Git command that interfaces\nwith Git’s internal APIs to produce structured JSON output,\nparticularly for repository metadata. By offering a clean,\nmachine-readable format, this tool will improve automation, scripting,\nand integration with other developer tools.\n\n## **Benefits to the Community**\n### **1. Simplifies Automation and Scripting**\n- Many Git commands output **human-readable text**, making automation\n**error-prone** and **dependent on fragile parsing**.\n- This project introduces **structured JSON output**, allowing scripts\nand tools to consume repository metadata **directly and reliably**.\n- No more **awkward text parsing**, `grep` hacks, or brittle `awk/sed`\npipelines—just **clean, structured data**.\n\n### **2. Eliminates the Overuse of `git rev-parse`**\n- `git rev-parse` is widely misused for extracting metadata, despite\nbeing intended primarily for **parsing revisions**.\n- Developers often **repurpose** it because there’s **no dedicated\nalternative** for metadata queries.\n- This project **corrects that gap** by introducing a **purpose-built\ncommand** that is **cleaner, more intuitive, and extensible**.\n\n### **3. Optimizes CI/CD Pipelines**\n- CI/CD systems currently need **multiple Git commands** and\nassociated parsing logic to fetch basic metadata:\n\n```bash\n# Example: Gathering just a few common pieces of info\nBRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo \"DETACHED\")\nCOMMIT=$(git rev-parse HEAD)\nREMOTE_URL=$(git remote get-url origin 2>/dev/null || echo \"no-origin\")\n# ... often requiring more commands and error handling logic.\n```\n- The proposed command aims to **replace these multiple calls** with a\n**single, efficient query** returning comprehensive, structured JSON\ndata.\n- This **simplifies pipeline scripts**, reduces process overhead, and\nmakes CI/CD configurations **cleaner and more robust**.\n\n## Deliverables\n\nThis project will introduce a new Git command, tentatively named `git\nmetadata`, to provide reliable, machine-readable repository\ninformation.\n\nThe key deliverables for this GSoC project include:\n\n1. **Core `git metadata` Command:**\n* A new `builtin/metadata.c` command integrated into the Git source code.\n* Implementation primarily in C, utilizing existing internal Git APIs\nfor retrieving repository information efficiently and accurately.\n\n2. **Default JSON Output:**\n* The command will output a structured JSON object by default.\n* **Initial Core Fields:**\n* `repository`: Path to `.git` directory, worktree root, `is_bare` status.\n* `head`: Current commit SHA (full), current reference\n(`refs/heads/main`, `refs/tags/v1.0`, or detached HEAD commit), short\nsymbolic name (`main`, `v1.0`, or `DETACHED`).\n* `remotes`: A map of remote names to their fetch and push URLs.\n* *(Stretch Goal):* Basic `is_dirty` flag based on a quick index/HEAD\ncheck (not full worktree scan).\n\n3. **Basic Output Control:**\n* *(If time permits / Stretch Goal)* Implement simple flags to control\noutput, e.g.:\n* `--remotes-only`: Output only the `remotes` section of the JSON.\n* `--head-only`: Output only the `head` section.\n* `--json-errors`: Ensure that errors encountered during execution\n(e.g., not in a Git repository) are reported in a structured JSON\nformat.\n\n4. **Extensible Design:**\n* The internal structure and JSON schema will be designed with future\nextensions in mind (e.g., adding submodule info, specific config\nvalues, tags later).\n\n5. **Comprehensive Documentation:**\n* A clear man page (`git-metadata.txt`) explaining the command's\npurpose, usage, options, and JSON output format.\n* Comments within the code explaining implementation details.\n\n6. **Robust Test Suite:**\n* A new test script (`t/tXXXX-metadata.sh`) using Git's test framework.\n* Tests covering various repository states: standard repo, bare repo,\ndetached HEAD, unborn branch, repo with no remotes, etc.\n* Tests validating the JSON output structure and content.\n\n**Out of Scope for GSoC (Potential Future Work):**\n* Complex status reporting (full `git status` equivalent, detailed\nsubmodule status).\n* Real-time monitoring (`--watch`).\n* Comparing metadata between revisions (`--diff`).\n* Alternative output formats (`--format=shell`).\n* Querying arbitrary configuration values or extensive commit details\nbeyond HEAD.\n\n## Technical Details\n\nThis section outlines the proposed technical approach for implementing\nthe core deliverables:\n\n1. **Core `git metadata` Command & Default JSON Output:**\n* **Entry Point:** Implement the command logic within a new\n`builtin/metadata.c` file, defining the `cmd_metadata(...)` function\nas the entry point, following Git's builtin command structure.\n* **Repository Access:** The `cmd_metadata` function will operate on\nthe `struct repository*` provided by the command invocation\ninfrastructure.\n* **Repository Info:**\n* Retrieve the path to the `.git` directory using `repo->gitdir` (or\n`get_git_dir()` if needed).\n* Determine if the repository is bare using `repo->is_bare`.\n* **HEAD Info:**\n* Resolve the `HEAD` reference using `refs_resolve_ref_unsafe(\"HEAD\",\nRESOLVE_REF_READING, &head_oid, &head_ref_name, &head_flags)`. This\nwill provide the full commit OID (`head_oid`) and the full reference\nname (`head_ref_name`, e.g., `\"refs/heads/main\"`).\n* Determine the conventional short symbolic name (e.g., `\"main\"`,\n`\"v1.0\"`, or `\"(HEAD detached at <sha>)\"`) by investigating and\nutilizing existing Git functions like `refs_shorten_unambiguous_ref()`\nor similar logic found in commands like `git status` or `git branch`.\nUsing low-level string functions like `strchr` will be avoided for\nrobustness.\n* **Remotes Info:**\n* Utilize functions from `remote.h`/`remote.c` (e.g., `remote_get`,\niterate through configured remotes) to get the list of remote names.\n* For each remote, query its fetch and push URLs using Git's\nconfiguration API (e.g., `git_config_get_string` for keys like\n`remote.<name>.url` and `remote.<name>.pushurl`). Handle cases where\npush URL is not explicitly set.\n* **JSON Generation:**\n* *(Primary Strategy):* Investigate integrating a minimal,\ndependency-free, GPLv2-compatible C JSON library (e.g., cJSON, subject\nto community approval) for robust JSON construction and escaping.\n* *(Fallback Strategy):* If a library is not feasible, manually\nconstruct the JSON string using Git's `strbuf` API (`strbuf_addf`,\n`strbuf_addch`, `strbuf_add_json_string`, etc.), paying careful\nattention to correct JSON syntax and proper escaping of string values.\n\n2. **Documentation:**\n* Create `Documentation/git-metadata.txt` following the structure and\nstyle of existing Git man pages (e.g., `git-rev-parse.txt`,\n`git-branch.txt`).\n* Clearly document the command's purpose, all options (including\nstretch goals if implemented), and provide a detailed description of\nthe default JSON output schema with examples.\n\n3. **Testing:**\n* Create a new test script `t/tXXXX-metadata.sh` using Git's\nshell-based test framework (`test-lib.sh`).\n* Include test cases covering:\n* Standard repositories.\n* Bare repositories.\n* Repositories with detached HEAD state.\n* Repositories on an unborn branch.\n* Repositories with no remotes, one remote, multiple remotes.\n* Remotes with different fetch/push URL configurations.\n* Validation of the JSON output structure and specific field values\nusing tools like `jq` or simple `grep` checks within the tests.\n* Testing of error conditions and the `--json-errors` flag output (if\nimplemented).\n\n## Detailed Project Timeline\n\n\n**Phase 0: Pre-Acceptance Preparation (April 9 - May 7, 2025)**\n\n* **Focus:** Demonstrate continued interest and deepen understanding\nwhile awaiting results.\n* **Official GSoC Milestone:** April 8, 2025 - Proposal Deadline.\n* **Activities:**\n* **(April 9 - April 21):** Deep dive into Git's source code\nstructure, focusing specifically on areas identified in the proposal's\nTechnical Details:\n* `builtin/` directory structure and command handling.\n* `repository.h`, `refs.h`, `remote.h`, `config.c`, `strbuf.h`.\n* How existing commands like `git status`, `git branch`, `git\nrev-parse`, `git remote -v` access underlying data.\n* **(April 22 - May 7):**\n* Monitor the Git mailing list for discussions related to repository\ninformation, command output formats, or JSON usage.\n* Refine understanding of Git's testing framework as I've not done a\ndeep dive into tests(`t/test-lib.sh`). Try running and understanding\nexisting tests relevant to refs, remotes, or configuration.\n* Review Git's contribution guidelines (`SubmittingPatches`, coding\nstyle) again since most of my microproject time was related to\ndocumentation.\n* Try to start some more microprojects or actively converse in other patches.\n\n**Phase 1: Finalize the requirements (May 8 - May 26, 2025 Approx.)**\n\n* **Focus:** Finalize plans with mentors, setup, deep dive into specifics.\n* **Official GSoC Milestone:** May 8, 2025 - Accepted Projects Announced.\n* **Activities:**\n* **(Week 1: May 8 - May 12):**\n* Discuss the project proposal in detail, clarifying scope,\npriorities, and mentor expectations.\n* Finalize the decision on the JSON generation strategy (library vs.\n`strbuf`) based on mentor feedback and feasibility assessment.\n* Confirm the initial target JSON schema.\n* **(Week 2: May 13 - May 19):**\n* Perform a deep dive into the *specific* functions identified for use\n(e.g., `resolve_ref_unsafe`, `shorten_unambiguous_ref`, remote access\nfunctions, config API, chosen JSON method).\n* Start outlining the structure of `builtin/metadata.c`.\n* **(Week 3: May 20 - May 26):**\n* Begin writing the basic skeleton of `builtin/metadata.c` and the\ninitial test file `t/tXXXX-metadata.sh`.\n* Post first blog update summarizing Initial plan.\n\n**Phase 2: Core Implementation & Setup (Coding Weeks 1-4: May 27 -\nJune 23, 2025 Approx.)**\n\n* **Focus:** Implement the basic command structure and retrieve core\nrepository/HEAD information.\n* **Activities:**\n* **(Week 1: May 27 - June 2):** Implement `cmd_metadata` skeleton,\nargument parsing (if any initially), repository struct access.\nImplement retrieval of `.git` path and `is_bare` status. Integrate\nchosen JSON generation approach (setup library or `strbuf` helpers).\n* **(Week 2: June 3 - June 9):** Implement HEAD resolution (commit\nSHA, full ref name). Implement logic for determining the short\nsymbolic name using appropriate Git functions. Integrate HEAD info\ninto JSON output.\n* **(Week 3: June 10 - June 16):** Write initial test cases in\n`t/tXXXX-metadata.sh` covering basic invocation, bare repos, and\ndetached HEAD states. Refine JSON output structure.\n* **(Week 4: June 17 - June 23):** Prepare and submit the first set of\npatches covering core repo/HEAD functionality to the mailing list.\nAddress initial feedback. Write blog post update.\n\n**Phase 3: Adding Remotes & Refinement (Coding Weeks 5-8: June 24 -\nJuly 21, 2025 Approx.)**\n\n* **Focus:** Add remote information retrieval and expand testing\nsignificantly. Aim for demonstrable core functionality by Midterm.\n* **GSoC Milestone:** Midterm Evaluations.\n* **Activities:**\n* **(Week 5: June 24 - June 30):** Research and implement logic to\nlist remote names. Implement logic to query fetch/push URLs for each\nremote using the config API.\n* **(Week 6: July 1 - July 7):** Integrate remote information into the\nJSON output structure. Handle edge cases (no remotes, missing push\nURL).\n* **(Week 7: July 8 - July 14):** Significantly expand the test suite:\nadd tests for various remote configurations, unborn branches. Refine\nexisting tests based on feedback. Start drafting the man page\n(`Documentation/git-metadata.txt`).\n* **(Week 8: July 15 - July 21):** Prepare and submit patches for\nremote functionality. Ensure core command (`repo`, `head`, `remotes`\ninfo) is stable and well-tested for Midterm Evaluation. Code cleanup\nbased on reviews. Write blog post update and prepare Midterm\nEvaluation submission.\n\n**Phase 4: Documentation, Polish & Stretch Goals (Coding Weeks 9-12:\nJuly 22 - Aug 18, 2025 Approx.)**\n\n* **Focus:** Finalize documentation, implement error handling, address\nfeedback, attempt stretch goals if feasible.\n* **Activities:**\n* **(Week 9: July 22 - July 28):** Complete the first draft of the man\npage, detailing usage, JSON schema, and options. Implement the\n`--json-errors` functionality for structured error reporting. Add\ntests for error cases.\n* **(Week 10: July 29 - Aug 4):** *Begin Stretch Goals (Conditional):*\nIf core work is stable and time permits, start implementing\n`--head-only` / `--remotes-only` flags or the basic `is_dirty` check.\nAdd tests for any implemented stretch goals.\n* **(Week 11: Aug 5 - Aug 11):** Thorough code cleanup, address all\noutstanding review comments on submitted patches. Ensure documentation\nis comprehensive and accurate. Final pass on test suite coverage.\n* **(Week 12: Aug 12 - Aug 18):** Prepare and submit final patches\nincorporating documentation, error handling, and any completed stretch\ngoals. Final code freeze for GSoC evaluation purposes. Write blog post\nupdate summarizing final phase.\n\n**Phase 5: Final Evaluation & Wrap-up (Aug 19 - Nov 19, 2025)**\n\n* **Focus:** Final submissions, respond to late feedback, ensure\nproject completion.\n* **GSoC Milestone:** Final Evaluations likely occur early in this period.\n* **Official GSoC Milestone:** November 19, 2025 - Program End Date.\n* **Activities:**\n* **(Late Aug - Sept):** continue for any incompletions and follow up\nfor next set of projects(Stretch goals)\n* **(Oct - Nov 19):** Monitor mailing list for patch status. Write\nfinal GSoC project summary blog post. Continue engaging with the\ncommunity if interested in further contributions beyond GSoC.\n\n## Past Communication and Microproject\n* **Blog**: [Blog](https://jayatheerthkulkarni.github.io/gsoc_blog/index.html)\nThis blog contains a detailed communication description and blog of my\nmicroproject experience.\n* First Introduction to the Git Mailing list: [first\nMail](https://lore.kernel.org/git/CA+rGoLc69R8qgbkYQiKoc2uweDwD10mxZXYFSY8xFs5eKSRVkA@mail.gmail.com/t/#u)\n* First patch to the git mailing list: [First\nPatch](https://lore.kernel.org/git/20250312081534.75536-1-jayatheerthkulkarni2005@gmail.com/t/#u)\n* Most recent series of patches and back and forth with feedbacks:\n[Main mail thread](https://lore.kernel.org/git/xmqqa59evffd.fsf@gitster.g/T/#t)\n\nI've been maintaing the blog and will maintain the blogs of all the\ncommunication of mine to the git mailing list.\n\n\nThank You,\nJayatheerth\n"},{"id":"515368","messageId":"CA+rGoLff+i8oxm5yfzxWbRe99M3CvBOw7BgaxWEZrib0rnL-AQ@mail.gmail.com","threadId":"63224","inReplyTo":"CA+rGoLfxZHdns=7FwQuYS=JANrR9zDP-dOpV2AxM1hC1Lc9wiw@mail.gmail.com","subject":"Re: [GSOC] [Proposal v1] Machine-Readable Repository Information Query Tool","fromName":"JAYATHEERTH K","fromEmail":"jayatheerthkulkarni2005@gmail.com","sentAt":"2025-03-31T14:59:37Z","receivedAt":"2025-03-31T14:59:50Z","isPatch":false,"sender":{"key":"jayatheerthkulkarni2005@gmail.com","avatar":"https://avatars.githubusercontent.com/u/148841023?v=4"},"body":"Here is a doc version of the above proposal [1]\nLooking forward to any feedback!!\n\n1- https://docs.google.com/document/d/1q06OHRo0fQluoZuSN5j_wgezT74JgMWYOk8O21ixyUY/edit?usp=sharing\n\nThank you,\nJay\n"},{"id":"515575","messageId":"Z-5hlL1Gk0oi4fX2@pks.im","threadId":"63224","inReplyTo":"CA+rGoLfxZHdns=7FwQuYS=JANrR9zDP-dOpV2AxM1hC1Lc9wiw@mail.gmail.com","subject":"Re: [GSOC] [Proposal v1] Machine-Readable Repository Information Query Tool","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-04-03T10:23:16Z","receivedAt":"2025-04-03T10:23:21Z","isPatch":false,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Mar 31, 2025 at 08:21:27PM +0530, JAYATHEERTH K wrote:\n> ## **Synopsis**\n> This project aims to develop a dedicated Git command that interfaces\n> with Git’s internal APIs to produce structured JSON output,\n> particularly for repository metadata. By offering a clean,\n> machine-readable format, this tool will improve automation, scripting,\n> and integration with other developer tools.\n> \n> ## **Benefits to the Community**\n> ### **1. Simplifies Automation and Scripting**\n> - Many Git commands output **human-readable text**, making automation\n> **error-prone** and **dependent on fragile parsing**.\n> - This project introduces **structured JSON output**, allowing scripts\n> and tools to consume repository metadata **directly and reliably**.\n> - No more **awkward text parsing**, `grep` hacks, or brittle `awk/sed`\n> pipelines—just **clean, structured data**.\n> \n> ### **2. Eliminates the Overuse of `git rev-parse`**\n> - `git rev-parse` is widely misused for extracting metadata, despite\n> being intended primarily for **parsing revisions**.\n> - Developers often **repurpose** it because there’s **no dedicated\n> alternative** for metadata queries.\n> - This project **corrects that gap** by introducing a **purpose-built\n> command** that is **cleaner, more intuitive, and extensible**.\n> \n> ### **3. Optimizes CI/CD Pipelines**\n> - CI/CD systems currently need **multiple Git commands** and\n> associated parsing logic to fetch basic metadata:\n> \n> ```bash\n> # Example: Gathering just a few common pieces of info\n> BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo \"DETACHED\")\n> COMMIT=$(git rev-parse HEAD)\n> REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo \"no-origin\")\n> # ... often requiring more commands and error handling logic.\n> ```\n> - The proposed command aims to **replace these multiple calls** with a\n> **single, efficient query** returning comprehensive, structured JSON\n> data.\n> - This **simplifies pipeline scripts**, reduces process overhead, and\n> makes CI/CD configurations **cleaner and more robust**.\n\nI already saw this in another proposal, which indicates that the project\nidea might be a bit underspecced. In any case, the goal of the project\nisn't to write a single tool that is able to surface _all_ information\nfor a Git repository. It's rather that we want to surface low-level\ninformation around the repository itself.\n\nThe basic intent is to give the options listed in git-rev-list(1) under\nthe section \"Options for Files\" a better home. We have a bunch of\ncommand line options there that allow us to parse environment variables,\npaths, repository formats and other low-level stuff. But these aren't\nreally a good fit for git-rev-parse(1) itself because that tool was\nintended to be about parsing revisions. So this is one of those\norganically grown commands that has started to accumulate all kinds of\nunrelated options that didn't have a better home elswhere.\n\nSo the scope of the project is somewhat more limited compared to what\nyou propose here. As that impacts a lot of the implementation details as\nwell as the project timeline I'm not going to comment on these now.\n\n> ## Detailed Project Timeline\n> \n> \n> **Phase 0: Pre-Acceptance Preparation (April 9 - May 7, 2025)**\n> \n> * **Focus:** Demonstrate continued interest and deepen understanding\n> while awaiting results.\n> * **Official GSoC Milestone:** April 8, 2025 - Proposal Deadline.\n> * **Activities:**\n> * **(April 9 - April 21):** Deep dive into Git's source code\n> structure, focusing specifically on areas identified in the proposal's\n> Technical Details:\n> * `builtin/` directory structure and command handling.\n> * `repository.h`, `refs.h`, `remote.h`, `config.c`, `strbuf.h`.\n> * How existing commands like `git status`, `git branch`, `git\n> rev-parse`, `git remote -v` access underlying data.\n> * **(April 22 - May 7):**\n> * Monitor the Git mailing list for discussions related to repository\n> information, command output formats, or JSON usage.\n> * Refine understanding of Git's testing framework as I've not done a\n> deep dive into tests(`t/test-lib.sh`). Try running and understanding\n> existing tests relevant to refs, remotes, or configuration.\n> * Review Git's contribution guidelines (`SubmittingPatches`, coding\n> style) again since most of my microproject time was related to\n> documentation.\n> * Try to start some more microprojects or actively converse in other patches.\n\nNote that microprojects are supposed to be finished before submitting\nyour proposal. They are used for us mentors to figure out whether\ncandidates would be a good fit or not. So ideally, you would prominently\nlink to one or more of your finished microprojects in the proposal\nitself already.\n\n> **Phase 4: Documentation, Polish & Stretch Goals (Coding Weeks 9-12:\n> July 22 - Aug 18, 2025 Approx.)**\n> \n> * **Focus:** Finalize documentation, implement error handling, address\n> feedback, attempt stretch goals if feasible.\n> * **Activities:**\n> * **(Week 9: July 22 - July 28):** Complete the first draft of the man\n> page, detailing usage, JSON schema, and options. Implement the\n> `--json-errors` functionality for structured error reporting. Add\n> tests for error cases.\n> * **(Week 10: July 29 - Aug 4):** *Begin Stretch Goals (Conditional):*\n> If core work is stable and time permits, start implementing\n> `--head-only` / `--remotes-only` flags or the basic `is_dirty` check.\n> Add tests for any implemented stretch goals.\n> * **(Week 11: Aug 5 - Aug 11):** Thorough code cleanup, address all\n> outstanding review comments on submitted patches. Ensure documentation\n> is comprehensive and accurate. Final pass on test suite coverage.\n> * **(Week 12: Aug 12 - Aug 18):** Prepare and submit final patches\n> incorporating documentation, error handling, and any completed stretch\n> goals. Final code freeze for GSoC evaluation purposes. Write blog post\n> update summarizing final phase.\n\nOne thing that I also mentioned to others: instead of planning for one\nbig batch of load, I would strongly recommend to plan your work in\nsmaller batches. You should ideally have multiple self-contained batches\nof work that you can submit as early as possible while still bringing\nsome value to the project. This ensures that you can get feedback from\nthe bigger community early on.\n\n> ## Past Communication and Microproject\n> * **Blog**: [Blog](https://jayatheerthkulkarni.github.io/gsoc_blog/index.html)\n> This blog contains a detailed communication description and blog of my\n> microproject experience.\n> * First Introduction to the Git Mailing list: [first\n> Mail](https://lore.kernel.org/git/CA+rGoLc69R8qgbkYQiKoc2uweDwD10mxZXYFSY8xFs5eKSRVkA@mail.gmail.com/t/#u)\n> * First patch to the git mailing list: [First\n> Patch](https://lore.kernel.org/git/20250312081534.75536-1-jayatheerthkulkarni2005@gmail.com/t/#u)\n> * Most recent series of patches and back and forth with feedbacks:\n> [Main mail thread](https://lore.kernel.org/git/xmqqa59evffd.fsf@gitster.g/T/#t)\n> \n> I've been maintaing the blog and will maintain the blogs of all the\n> communication of mine to the git mailing list.\n\nah, you do have a microproject. As this is part of the prerequisites I\nwould like to propose to have this more prominently visible.\n\nThanks!\n\nPatrick\n"},{"id":"515586","messageId":"CA+rGoLfCTzNTcGXG5py6oHQazeE8Vj0fLsR4KUTJ6rSRFnT_Vw@mail.gmail.com","threadId":"63224","inReplyTo":"Z-5hlL1Gk0oi4fX2@pks.im","subject":"Re: [GSOC] [Proposal v1] Machine-Readable Repository Information Query Tool","fromName":"JAYATHEERTH K","fromEmail":"jayatheerthkulkarni2005@gmail.com","sentAt":"2025-04-03T14:10:33Z","receivedAt":"2025-04-03T14:10:46Z","isPatch":false,"sender":{"key":"jayatheerthkulkarni2005@gmail.com","avatar":"https://avatars.githubusercontent.com/u/148841023?v=4"},"body":"On Thu, Apr 3, 2025 at 3:53 PM Patrick Steinhardt <ps@pks.im> wrote:\n>\n> On Mon, Mar 31, 2025 at 08:21:27PM +0530, JAYATHEERTH K wrote:\n> > ## **Synopsis**\n> > This project aims to develop a dedicated Git command that interfaces\n> > with Git’s internal APIs to produce structured JSON output,\n> > particularly for repository metadata. By offering a clean,\n> > machine-readable format, this tool will improve automation, scripting,\n> > and integration with other developer tools.\n> >\n> > ## **Benefits to the Community**\n> > ### **1. Simplifies Automation and Scripting**\n> > - Many Git commands output **human-readable text**, making automation\n> > **error-prone** and **dependent on fragile parsing**.\n> > - This project introduces **structured JSON output**, allowing scripts\n> > and tools to consume repository metadata **directly and reliably**.\n> > - No more **awkward text parsing**, `grep` hacks, or brittle `awk/sed`\n> > pipelines—just **clean, structured data**.\n> >\n> > ### **2. Eliminates the Overuse of `git rev-parse`**\n> > - `git rev-parse` is widely misused for extracting metadata, despite\n> > being intended primarily for **parsing revisions**.\n> > - Developers often **repurpose** it because there’s **no dedicated\n> > alternative** for metadata queries.\n> > - This project **corrects that gap** by introducing a **purpose-built\n> > command** that is **cleaner, more intuitive, and extensible**.\n> >\n> > ### **3. Optimizes CI/CD Pipelines**\n> > - CI/CD systems currently need **multiple Git commands** and\n> > associated parsing logic to fetch basic metadata:\n> >\n> > ```bash\n> > # Example: Gathering just a few common pieces of info\n> > BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo \"DETACHED\")\n> > COMMIT=$(git rev-parse HEAD)\n> > REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo \"no-origin\")\n> > # ... often requiring more commands and error handling logic.\n> > ```\n> > - The proposed command aims to **replace these multiple calls** with a\n> > **single, efficient query** returning comprehensive, structured JSON\n> > data.\n> > - This **simplifies pipeline scripts**, reduces process overhead, and\n> > makes CI/CD configurations **cleaner and more robust**.\n>\n> I already saw this in another proposal, which indicates that the project\n> idea might be a bit underspecced. In any case, the goal of the project\n\nHey Patrick, thank you for letting me know\nI actually have been working on this proposal for a while now.\nI also sent an e-mail regarding this specific project right before\nGSOC proposals started. As far as I can see this project was not\npreviously discussed therefore I picked this.\n\nhttps://lore.kernel.org/git/CA+rGoLdvY+JdgdzgE04EJoF9KGUpd39+2S_AgpFyucP38mdFgA@mail.gmail.com/\n\nI'm not sure how to proceed in this situation. I think I need some\nadvice from your side on this.\n\n> isn't to write a single tool that is able to surface _all_ information\n> for a Git repository. It's rather that we want to surface low-level\n> information around the repository itself.\n>\n> The basic intent is to give the options listed in git-rev-list(1) under\n> the section \"Options for Files\" a better home. We have a bunch of\n> command line options there that allow us to parse environment variables,\n> paths, repository formats and other low-level stuff. But these aren't\n> really a good fit for git-rev-parse(1) itself because that tool was\n> intended to be about parsing revisions. So this is one of those\n> organically grown commands that has started to accumulate all kinds of\n> unrelated options that didn't have a better home elswhere.\n>\n\nOk that clears a lot of things.\n\n> So the scope of the project is somewhat more limited compared to what\n> you propose here. As that impacts a lot of the implementation details as\n> well as the project timeline I'm not going to comment on these now.\n>\n\nI think some parts of this proposal still hold scope like the CJSON\ndiscussion part, repository details etc, into this revised plan, but I\nthink I will send a revised proposal covering the changes in detail.\n\n> > ## Detailed Project Timeline\n> >\n> >\n> > **Phase 0: Pre-Acceptance Preparation (April 9 - May 7, 2025)**\n> >\n> > * **Focus:** Demonstrate continued interest and deepen understanding\n> > while awaiting results.\n> > * **Official GSoC Milestone:** April 8, 2025 - Proposal Deadline.\n> > * **Activities:**\n> > * **(April 9 - April 21):** Deep dive into Git's source code\n> > structure, focusing specifically on areas identified in the proposal's\n> > Technical Details:\n> > * `builtin/` directory structure and command handling.\n> > * `repository.h`, `refs.h`, `remote.h`, `config.c`, `strbuf.h`.\n> > * How existing commands like `git status`, `git branch`, `git\n> > rev-parse`, `git remote -v` access underlying data.\n> > * **(April 22 - May 7):**\n> > * Monitor the Git mailing list for discussions related to repository\n> > information, command output formats, or JSON usage.\n> > * Refine understanding of Git's testing framework as I've not done a\n> > deep dive into tests(`t/test-lib.sh`). Try running and understanding\n> > existing tests relevant to refs, remotes, or configuration.\n> > * Review Git's contribution guidelines (`SubmittingPatches`, coding\n> > style) again since most of my microproject time was related to\n> > documentation.\n> > * Try to start some more microprojects or actively converse in other patches.\n>\n> Note that microprojects are supposed to be finished before submitting\n> your proposal. They are used for us mentors to figure out whether\n> candidates would be a good fit or not. So ideally, you would prominently\n> link to one or more of your finished microprojects in the proposal\n> itself already.\n>\n\nI see you've noticed below that I've been active in a microproject. I\nwill move it up and make it more noticable thank you for pointing it\nout!!\n\n> > **Phase 4: Documentation, Polish & Stretch Goals (Coding Weeks 9-12:\n> > July 22 - Aug 18, 2025 Approx.)**\n> >\n> > * **Focus:** Finalize documentation, implement error handling, address\n> > feedback, attempt stretch goals if feasible.\n> > * **Activities:**\n> > * **(Week 9: July 22 - July 28):** Complete the first draft of the man\n> > page, detailing usage, JSON schema, and options. Implement the\n> > `--json-errors` functionality for structured error reporting. Add\n> > tests for error cases.\n> > * **(Week 10: July 29 - Aug 4):** *Begin Stretch Goals (Conditional):*\n> > If core work is stable and time permits, start implementing\n> > `--head-only` / `--remotes-only` flags or the basic `is_dirty` check.\n> > Add tests for any implemented stretch goals.\n> > * **(Week 11: Aug 5 - Aug 11):** Thorough code cleanup, address all\n> > outstanding review comments on submitted patches. Ensure documentation\n> > is comprehensive and accurate. Final pass on test suite coverage.\n> > * **(Week 12: Aug 12 - Aug 18):** Prepare and submit final patches\n> > incorporating documentation, error handling, and any completed stretch\n> > goals. Final code freeze for GSoC evaluation purposes. Write blog post\n> > update summarizing final phase.\n>\n> One thing that I also mentioned to others: instead of planning for one\n> big batch of load, I would strongly recommend to plan your work in\n> smaller batches. You should ideally have multiple self-contained batches\n> of work that you can submit as early as possible while still bringing\n> some value to the project. This ensures that you can get feedback from\n> the bigger community early on.\n>\n\nOk, so I will reshape my timeline in a way where I specify my patches\nwhile converging them to a bigger project at the end.\n\n> > ## Past Communication and Microproject\n> > * **Blog**: [Blog](https://jayatheerthkulkarni.github.io/gsoc_blog/index.html)\n> > This blog contains a detailed communication description and blog of my\n> > microproject experience.\n> > * First Introduction to the Git Mailing list: [first\n> > Mail](https://lore.kernel.org/git/CA+rGoLc69R8qgbkYQiKoc2uweDwD10mxZXYFSY8xFs5eKSRVkA@mail.gmail.com/t/#u)\n> > * First patch to the git mailing list: [First\n> > Patch](https://lore.kernel.org/git/20250312081534.75536-1-jayatheerthkulkarni2005@gmail.com/t/#u)\n> > * Most recent series of patches and back and forth with feedbacks:\n> > [Main mail thread](https://lore.kernel.org/git/xmqqa59evffd.fsf@gitster.g/T/#t)\n> >\n> > I've been maintaing the blog and will maintain the blogs of all the\n> > communication of mine to the git mailing list.\n>\n> ah, you do have a microproject. As this is part of the prerequisites I\n> would like to propose to have this more prominently visible.\n>\n> Thanks!\n>\n\nThanks again this helps a lot.\n\n> Patrick\n\nThank you,\nJay\n"},{"id":"515587","messageId":"CA+rGoLeRXUQu8ZbDtaLp2_YbVGA5D1DeA2vSEcLf74qXjB5U2A@mail.gmail.com","threadId":"63224","inReplyTo":"CA+rGoLfCTzNTcGXG5py6oHQazeE8Vj0fLsR4KUTJ6rSRFnT_Vw@mail.gmail.com","subject":"Re: [GSOC] [Proposal v1] Machine-Readable Repository Information Query Tool","fromName":"JAYATHEERTH K","fromEmail":"jayatheerthkulkarni2005@gmail.com","sentAt":"2025-04-03T14:35:45Z","receivedAt":"2025-04-03T14:35:57Z","isPatch":false,"sender":{"key":"jayatheerthkulkarni2005@gmail.com","avatar":"https://avatars.githubusercontent.com/u/148841023?v=4"},"body":"# Proposal for GSOC 2025 to Git\n**Refactoring `git rev-parse`: A Dedicated Command for Repository Information**\n\n## Contact Details\n* **Name**: K Jayatheerth\n* **Email**: jayatheerthkulkarni2005@gmail.com\n* **Blog**: [Blog](https://jayatheerthkulkarni.github.io/gsoc_blog/index.html)\n* **GitHub**: [GitHub](https://github.com/jayatheerthkulkarni)\n\n## Prerequisites & Experience\n\n\nAs part of the GSoC application prerequisites, I have engaged with the\nGit community with a microproject involving documentation changes.\nThis provided valuable experience with Git's codebase, contribution\nworkflow (patch submission, feedback cycles), and communication via\nthe mailing list.\n\n* **Microproject Patch Series:** [Main mail\nthread](https://lore.kernel.org/git/xmqqa59evffd.fsf@gitster.g/T/#t)\n(Link to the most relevant thread demonstrating interaction and\nsuccessful patch refinement)\n* **Initial Patch:** [First\nPatch](https://lore.kernel.org/git/20250312081534.75536-1-jayatheerthkulkarni2005@gmail.com/t/#u)\n* **Mailing List Introduction:** [First\nMail](https://lore.kernel.org/git/CA+rGoLc69R8qgbkYQiKoc2uweDwD10mxZXYFSY8xFs5eKSRVkA@mail.gmail.com/t/#u)\n* **Blog:** My GSoC blog details these interactions:\n[Blog](https://jayatheerthkulkarni.github.io/gsoc_blog/index.html)\n\n## **Synopsis**\n\nThis project focuses on **refactoring Git by creating a dedicated\ncommand (tentatively named `git repo-info`) to house the low-level\nrepository, path, and format-related query options currently misplaced\nunder the \"OPTIONS FOR FILES\" section of `git-rev-parse(1)`**. This\nnew command will provide a more logical and maintainable location for\nthis functionality, allowing `git rev-parse` to better focus on its\ncore purpose of parsing revisions, thus improving Git's internal\norganization and command structure clarity.\n\n## **Benefits to the Community**\n\n### **1. Improves `git rev-parse` Clarity and Maintainability**\n- `git rev-parse` has accumulated various options unrelated to its\nprimary purpose of parsing revisions, particularly those for querying\nlow-level repository state and paths.\n- This project **directly addresses this issue** by migrating these\noptions to a dedicated command, making `git rev-parse` cleaner and\neasier to understand and maintain.\n- Provides a **clearer separation of concerns** within Git's command suite.\n\n### **2. Provides Reliable Access for Automation and Scripting**\n- Scripts often need fundamental repository information like the\ntop-level directory path (`--show-toplevel`), the `.git` directory\nlocation (`--git-dir`), or repository state (`--is-bare-repository`).\n- Currently, scripts rely on `git rev-parse` for this, mixing\nlow-level repo queries with revision parsing calls.\n- The new `git repo-info` command will offer a **stable, dedicated\ninterface** for retrieving this specific low-level information, making\nscripts **cleaner and more robust** by calling the command designed\nexplicitly for these tasks.\n- The default output will mimic the **existing, simple text format**\nof the `rev-parse` options, ensuring compatibility for scripts\nmigrating to the new command.\n\n### **3. Enhances CI/CD Pipeline Foundations**\n- CI/CD pipelines frequently need to establish context by determining\nthe repository root or `.git` directory location early in their\nexecution.\n- Using the dedicated `git repo-info` command for these foundational\nqueries **simplifies the initial setup steps** in pipeline scripts\ncompared to using the overloaded `git rev-parse`.\n\n## Deliverables\n\nAcknowledging the needs that the project scope is focused on\nrefactoring `git rev-parse`, this project will introduce a new Git\ncommand, tentatively named `git repo-info`, serving as the designated\nhome for specific low-level query options.\n\nThe key deliverables for this GSoC project include:\n\n1. **New Core Command: `git repo-info`**\n* A new `builtin/repo-info.c` command integrated into the Git source code.\n* Implementation primarily in C, leveraging existing internal Git APIs\nand logic currently within `rev-parse.c` to implement the relocated\noptions.\n\n2. **Relocated `rev-parse` Options:**\n* Implementation of the core functionality behind the following\noptions from `git-rev-parse(1)`'s \"OPTIONS FOR FILES\" section within\nthe new `git repo-info` command:\n* **Path Queries:** `--show-cdup`, `--show-prefix`, `--show-toplevel`,\n`--show-superproject-working-tree`\n* **Directory Queries:** `--git-dir`, `--git-common-dir`,\n`--resolve-git-dir <path>`\n* **State/Format Queries:** `--is-inside-git-dir`,\n`--is-inside-work-tree`, `--is-bare-repository`,\n`--is-shallow-repository`\n* **Index File Query:** `--shared-index-path`\n\n3. **Default Output Format (Text-Based):**\n* The command's default output for each implemented option will\n**match the current plain text output** produced by `git rev-parse`\nfor that same option, ensuring backward compatibility for scripts\nmigrating to the new command. Output will primarily be via standard C\nfunctions like `printf` or `puts`.\n\n4. **Comprehensive Documentation:**\n* A clear man page (`git-repo-info.adoc`) explaining the new command's\npurpose and detailing the usage and output of each implemented option.\n* Updates to `git-rev-parse.adoc` to clearly **deprecate** the\nrelocated options (or mark them as aliases for compatibility) and\npoint users to the new `git repo-info` command.\n\n5. **Robust Test Suite:**\n* A new test script (`t/tXXXX-repo-info.sh`) using Git's test\nframework (`test-lib.sh`).\n* Tests specifically validating the output of `git repo-info --option`\nagainst the output of `git rev-parse --option` across various\nrepository states (standard repo, bare repo, inside `.git`, inside\nworktree, submodules, shallow clone etc.) to ensure functional parity.\n\n6. **(Stretch Goal / Potential Future Work): Structured Output**\n* If time permits after successfully implementing, documenting, and\ntesting the core text-based functionality, investigate adding a\n`--format=json` option to provide a structured JSON output containing\nthe results of the requested queries. This is explicitly a secondary\ngoal, contingent on completing the primary refactoring task.\n\n**Out of Scope for GSoC (Based on Refined Goal):**\n* Querying high-level metadata like current branch name, HEAD commit\ndetails (beyond `--is-shallow-repository`), remote URLs, tags, or\narbitrary configuration values.\n* Complex status reporting (worktree dirtiness).\n* Real-time monitoring or comparing metadata between revisions.\n* Implementing JSON output as the *primary* feature.\n\n## Technical Details\n\nThis section outlines the proposed technical approach for implementing\nthe `git repo-info` command and relocating the specified options:\n\n1. **Core `git repo-info` Command Implementation:**\n* **Entry Point:** Create `builtin/repo-info.c` with\n`cmd_repo_info(...)` function. Parse options using Git's\n`parse-options` API.\n* **Repository Context:** Utilize the standard `repo` structure and\n`startup_info` provided by Git's infrastructure. Setup the repository\ncontext similar to how `cmd_rev_parse` does it if needed (e.g., using\n`setup_git_directory_gently`).\n* **Reusing Logic:** Analyze the implementation of the target options\nwithin `builtin/rev-parse.c`. Extract and adapt the relevant C\nfunctions and logic (related to path manipulation using `prefix_path`,\n`real_pathcmp`; repository state checks using\n`is_bare_repository_cfg`, `is_inside_git_dir`, `is_inside_work_tree`;\naccessing `startup_info`, `git_path`, etc.) into `builtin/repo-info.c`\nor potentially shared helper functions if appropriate.\n* **Specific Option Implementation:**\n* `--show-toplevel`, `--show-cdup`, `--show-prefix`: Rely on the\n`prefix` calculated during setup and path manipulation functions.\n* `--git-dir`, `--git-common-dir`: Access `repo->gitdir`,\n`repo->commondir` or use functions like `get_git_dir()`,\n`get_common_dir()`. `--resolve-git-dir` will involve path resolution\nrelative to the provided argument.\n* `--is-*` flags: Call existing helper functions like\n`is_bare_repository_cfg()`, `is_inside_git_dir()`,\n`is_inside_work_tree()`. `--is-shallow-repository` involves checking\n`repo->is_shallow`.\n* `--shared-index-path`: Access path information related to split\nindexes if enabled.\n* **Output Generation:** Use standard C `printf(\"%s\\n\", ...)` or\n`puts(...)` to print the resulting string (path, \"true\"/\"false\", etc.)\nto standard output, matching `rev-parse`'s current behavior. Boolean\nflags typically exit `0` for true and `1` for false without output,\nthis behavior should be preserved.\n\n2. **Documentation:**\n* Create `Documentation/git-repo-info.adoc` using AsciiDoc format,\nmodeling it after existing man pages. Detail each option, its purpose,\nand expected output.\n* Modify `Documentation/git-rev-parse.adoc`, adding notes to the\nrelevant options indicating they are better handled by `git repo-info`\nand potentially marking them for deprecation in a future Git version.\n\n3. **Testing:**\n* Create `t/tXXXX-repo-info.sh` using `test-lib.sh`.\n* Structure tests using `test_expect_success` blocks.\n* Utilize helper functions like `test_create_repo`, `cd repo`,\n`test_cmp` to compare the output of `git repo-info --option` directly\nagainst `git rev-parse --option` (for options producing output) or\nagainst expected exit codes (for boolean flags).\n* Cover edge cases like running outside a repository, in a bare\nrepository, deep within a worktree, within the `.git` directory, and\nin repositories with submodules or worktrees.\n\n4. **(Stretch Goal) JSON Output Implementation:**\n* If attempted, add a `--format=json` option using `parse-options`.\n* Collect results from the requested options internally.\n* Use either an approved embedded C JSON library or Git's `strbuf` API\n(with helpers like `strbuf_add_json_string`) to construct a JSON\nobject mapping option names (or descriptive keys) to their\ncorresponding values. Print the final JSON string to standard output.\nAdd specific tests for JSON output validation.\n\n## Detailed Project Timeline\n\n**Phase 0: Pre-Acceptance Preparation (April 9 - May 7, 2025)**\n\n* **Focus:** Demonstrate continued interest and deepen understanding\n*specifically of `rev-parse`'s internals* while awaiting results.\n* **Activities:**\n* **(April 9 - April 21):** Deep dive into `builtin/rev-parse.c`,\nidentifying the exact code blocks implementing the \"OPTIONS FOR\nFILES\". Trace how they use `startup_info`, `prefix`, path functions,\nand repository flags.\n* **(April 22 - May 7):** Continue monitoring the mailing list. Refine\nunderstanding of Git's testing framework, specifically focusing on\ntests for `rev-parse` options (e.g., `t1006-cat-file.sh`,\n`t5601-clone.sh` might use some flags). Review contribution\nguidelines.\n\n**Phase 1: Final Planning (May 8 - May 26, 2025 Approx.)**\n\n* **Focus:** Formal introductions, confirm final scope & plan, setup.\n* **Activities:**\n* **(Week 1: May 8 - May 12):** Introduction with mentor(s). Confirm\nthe exact list of `rev-parse` options to be migrated. Discuss the\npreferred approach for handling deprecation in `rev-parse` docs/code.\nDiscuss potential for shared helper functions vs. direct code\nmigration.\n* **(Week 2: May 13 - May 19):** Set up dev environment. Deep dive\ninto the agreed-upon functions/code blocks within `rev-parse.c`.\nOutline the basic structure for `builtin/repo-info.c` and the test\nscript `t/tXXXX-repo-info.sh`.\n* **(Week 3: May 20 - May 26):** Implement the basic `cmd_repo_info`\nskeleton, option parsing setup, and repository setup boilerplate.\nWrite initial \"no-op\" tests. Post first blog update.\n\n**Phase 2: Implementation in Batches (Coding Weeks 1-8: May 27 - July\n21, 2025 Approx.)**\n\n* **Focus:** Implement options in logical groups, test thoroughly,\nsubmit patches early and often.\n* **GSoC Milestone:** Midterm Evaluations occur around Week 8.\n* **Activities:**\n* **(Batch 1 / Weeks 1-2: May 27 - June 9):** Implement basic path\nqueries: `--show-toplevel`, `--show-prefix`, `--show-cdup`. Add tests\ncomparing output with `rev-parse`. **Submit Patch Series 1**.\n* **(Batch 2 / Weeks 3-4: June 10 - June 23):** Implement directory\nqueries: `--git-dir`, `--git-common-dir`, `--resolve-git-dir <path>`.\nAdd tests. **Submit Patch Series 2**. Write blog post update.\n* **(Batch 3 / Weeks 5-6: June 24 - July 7):** Implement boolean state\nqueries: `--is-bare-repository`, `--is-inside-git-dir`,\n`--is-inside-work-tree`. Add tests checking exit codes and behavior in\nvarious locations. **Submit Patch Series 3**.\n* **(Batch 4 / Weeks 7-8: July 8 - July 21):** Implement remaining\nqueries: `--is-shallow-repository`, `--shared-index-path`,\n`--show-superproject-working-tree`. Add comprehensive tests covering\ninteractions (e.g., in submodules, shallow clones). **Submit Patch\nSeries 4**. Prepare for Midterm evaluation; ensure submitted batches\ndemonstrate core progress. Write blog post update.\n\n**Phase 3: Documentation & Final Polish (Coding Weeks 9-12: July 22 -\nAug 18, 2025 Approx.)**\n\n* **Focus:** Create documentation, address feedback on all patches,\nrefine implementation, potentially attempt stretch goal.\n* **Activities:**\n* **(Week 9: July 22 - July 28):** Write the first complete draft of\nthe man page for `git-repo-info`. Draft the necessary updates for\n`git-rev-parse.adoc` (deprecation notices). **Submit Patch Series 5\n(Documentation)**.\n* **(Week 10: July 29 - Aug 4):** Focus on addressing review comments\non **all** previous patch series. Refactor code based on feedback.\nEnsure test suite is robust and covers feedback points.\n* **(Week 11: Aug 5 - Aug 11):** *Stretch Goal (Conditional):* If core\nfunctionality and docs are stable and reviewed positively, begin\ninvestigating/implementing `--format=json`. Add specific JSON tests if\nimplemented. Otherwise, focus on further code cleanup and test\nhardening.\n* **(Week 12: Aug 12 - Aug 18):** Prepare and submit final versions of\nall patch series, incorporating all feedback. Final testing pass.\nWrite blog post update summarizing progress and final state. Code\nfreeze for final evaluation.\n\n**Phase 4: Final Evaluation & Wrap-up (Aug 19 - Nov 19, 2025)**\n\n* **Focus:** Final submissions, respond to late feedback, ensure\nproject completion.\n* **Official GSoC Milestone:** November 19, 2025 - Program End Date.\n* **Activities:**\n* **(Late Aug - Sept):** Submit final GSoC evaluations. Actively\nrespond to any further comments on submitted patches from the\ncommunity/maintainers, aiming for merge readiness.\n* **(Oct - Nov 19):** Monitor mailing list for patch status. Write\nfinal GSoC project summary blog post. Continue engaging with the\ncommunity if interested in further contributions beyond GSoC.\n\n\n\nThank You,\nJayatheerth\n"},{"id":"515645","messageId":"Z--ivMYyD63JkTyH@pks.im","threadId":"63224","inReplyTo":"CA+rGoLfCTzNTcGXG5py6oHQazeE8Vj0fLsR4KUTJ6rSRFnT_Vw@mail.gmail.com","subject":"Re: [GSOC] [Proposal v1] Machine-Readable Repository Information Query Tool","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-04-04T09:13:32Z","receivedAt":"2025-04-04T09:13:36Z","isPatch":false,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Thu, Apr 03, 2025 at 07:40:33PM +0530, JAYATHEERTH K wrote:\n> On Thu, Apr 3, 2025 at 3:53 PM Patrick Steinhardt <ps@pks.im> wrote:\n> > On Mon, Mar 31, 2025 at 08:21:27PM +0530, JAYATHEERTH K wrote:\n> > I already saw this in another proposal, which indicates that the project\n> > idea might be a bit underspecced. In any case, the goal of the project\n> \n> Hey Patrick, thank you for letting me know\n> I actually have been working on this proposal for a while now.\n> I also sent an e-mail regarding this specific project right before\n> GSOC proposals started. As far as I can see this project was not\n> previously discussed therefore I picked this.\n> \n> https://lore.kernel.org/git/CA+rGoLdvY+JdgdzgE04EJoF9KGUpd39+2S_AgpFyucP38mdFgA@mail.gmail.com/\n> \n> I'm not sure how to proceed in this situation. I think I need some\n> advice from your side on this.\n\nI think I don't quite understand what \"this situation\" refers to. Do you\nmean that there are multiple proposals for this project now? If so, that\nis perfectly fine and expected. There's only a finite number of projects\nand a larger number of students, so some of the projects will have\nmutliple applicants.\n\nIn the end we will pick the student who seems to be the best match based\non both the proposal, the microproject and any other interactions with\nthe community.\n\nPatrick\n"},{"id":"515666","messageId":"CA+rGoLdH=zQy6A9draoZgoDO=Ok7OgaX+mRFarLTLEm2jwhE4w@mail.gmail.com","threadId":"63224","inReplyTo":"Z--ivMYyD63JkTyH@pks.im","subject":"Re: [GSOC] [Proposal v1] Machine-Readable Repository Information Query Tool","fromName":"JAYATHEERTH K","fromEmail":"jayatheerthkulkarni2005@gmail.com","sentAt":"2025-04-04T13:22:54Z","receivedAt":"2025-04-04T13:23:06Z","isPatch":false,"sender":{"key":"jayatheerthkulkarni2005@gmail.com","avatar":"https://avatars.githubusercontent.com/u/148841023?v=4"},"body":"On Fri, Apr 4, 2025 at 2:43 PM Patrick Steinhardt <ps@pks.im> wrote:\n>\n> On Thu, Apr 03, 2025 at 07:40:33PM +0530, JAYATHEERTH K wrote:\n> > On Thu, Apr 3, 2025 at 3:53 PM Patrick Steinhardt <ps@pks.im> wrote:\n> > > On Mon, Mar 31, 2025 at 08:21:27PM +0530, JAYATHEERTH K wrote:\n> > > I already saw this in another proposal, which indicates that the project\n> > > idea might be a bit underspecced. In any case, the goal of the project\n> >\n> > Hey Patrick, thank you for letting me know\n> > I actually have been working on this proposal for a while now.\n> > I also sent an e-mail regarding this specific project right before\n> > GSOC proposals started. As far as I can see this project was not\n> > previously discussed therefore I picked this.\n> >\n> > https://lore.kernel.org/git/CA+rGoLdvY+JdgdzgE04EJoF9KGUpd39+2S_AgpFyucP38mdFgA@mail.gmail.com/\n> >\n> > I'm not sure how to proceed in this situation. I think I need some\n> > advice from your side on this.\n>\n> I think I don't quite understand what \"this situation\" refers to. Do you\n> mean that there are multiple proposals for this project now? If so, that\n> is perfectly fine and expected. There's only a finite number of projects\n> and a larger number of students, so some of the projects will have\n> mutliple applicants.\n>\n> In the end we will pick the student who seems to be the best match based\n> on both the proposal, the microproject and any other interactions with\n> the community.\n>\nUnderstood, I will carry on as is.\nI've sent the updated proposal above in this thread with the revised\nscope of the project.\n\n> Patrick\n\n- Jayatheerth\n"},{"id":"515703","messageId":"CAOLa=ZQCTJLSWV-y-=nKf9J4xKr5miAo+35RktmbGmHPL4Sp-w@mail.gmail.com","threadId":"63224","inReplyTo":"CA+rGoLeRXUQu8ZbDtaLp2_YbVGA5D1DeA2vSEcLf74qXjB5U2A@mail.gmail.com","subject":"Re: [GSOC] [Proposal v1] Machine-Readable Repository Information Query Tool","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-04-05T19:42:22Z","receivedAt":"2025-04-05T19:42:24Z","isPatch":false,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"JAYATHEERTH K <jayatheerthkulkarni2005@gmail.com> writes:\n\n> # Proposal for GSOC 2025 to Git\n> **Refactoring `git rev-parse`: A Dedicated Command for Repository Information**\n>\n> ## Contact Details\n> * **Name**: K Jayatheerth\n> * **Email**: jayatheerthkulkarni2005@gmail.com\n> * **Blog**: [Blog](https://jayatheerthkulkarni.github.io/gsoc_blog/index.html)\n> * **GitHub**: [GitHub](https://github.com/jayatheerthkulkarni)\n>\n> ## Prerequisites & Experience\n>\n>\n> As part of the GSoC application prerequisites, I have engaged with the\n> Git community with a microproject involving documentation changes.\n> This provided valuable experience with Git's codebase, contribution\n> workflow (patch submission, feedback cycles), and communication via\n> the mailing list.\n>\n> * **Microproject Patch Series:** [Main mail\n> thread](https://lore.kernel.org/git/xmqqa59evffd.fsf@gitster.g/T/#t)\n> (Link to the most relevant thread demonstrating interaction and\n> successful patch refinement)\n> * **Initial Patch:** [First\n> Patch](https://lore.kernel.org/git/20250312081534.75536-1-jayatheerthkulkarni2005@gmail.com/t/#u)\n> * **Mailing List Introduction:** [First\n> Mail](https://lore.kernel.org/git/CA+rGoLc69R8qgbkYQiKoc2uweDwD10mxZXYFSY8xFs5eKSRVkA@mail.gmail.com/t/#u)\n> * **Blog:** My GSoC blog details these interactions:\n> [Blog](https://jayatheerthkulkarni.github.io/gsoc_blog/index.html)\n>\n\nIt would be nice to give a small brief about your microproject here and\nperhaps its current status.\n\n> ## **Synopsis**\n>\n> This project focuses on **refactoring Git by creating a dedicated\n> command (tentatively named `git repo-info`) to house the low-level\n\nI wonder if 'git info' itself would be a good name, we could default the\ncommand to list all prominent information about a repository. This would\nbe useful instead of scripts invoking 'git rev-parse\n--is-bare-repository' followed by a 'git rev-parse --is-inside-git-dir'\nand so on. But we can discuss this later.\n\n> repository, path, and format-related query options currently misplaced\n> under the \"OPTIONS FOR FILES\" section of `git-rev-parse(1)`**. This\n> new command will provide a more logical and maintainable location for\n> this functionality, allowing `git rev-parse` to better focus on its\n> core purpose of parsing revisions, thus improving Git's internal\n> organization and command structure clarity.\n>\n> ## **Benefits to the Community**\n>\n> ### **1. Improves `git rev-parse` Clarity and Maintainability**\n> - `git rev-parse` has accumulated various options unrelated to its\n> primary purpose of parsing revisions, particularly those for querying\n> low-level repository state and paths.\n> - This project **directly addresses this issue** by migrating these\n> options to a dedicated command, making `git rev-parse` cleaner and\n> easier to understand and maintain.\n> - Provides a **clearer separation of concerns** within Git's command suite.\n>\n> ### **2. Provides Reliable Access for Automation and Scripting**\n> - Scripts often need fundamental repository information like the\n> top-level directory path (`--show-toplevel`), the `.git` directory\n> location (`--git-dir`), or repository state (`--is-bare-repository`).\n> - Currently, scripts rely on `git rev-parse` for this, mixing\n> low-level repo queries with revision parsing calls.\n> - The new `git repo-info` command will offer a **stable, dedicated\n> interface** for retrieving this specific low-level information, making\n> scripts **cleaner and more robust** by calling the command designed\n> explicitly for these tasks.\n> - The default output will mimic the **existing, simple text format**\n> of the `rev-parse` options, ensuring compatibility for scripts\n> migrating to the new command.\n>\n> ### **3. Enhances CI/CD Pipeline Foundations**\n> - CI/CD pipelines frequently need to establish context by determining\n> the repository root or `.git` directory location early in their\n> execution.\n> - Using the dedicated `git repo-info` command for these foundational\n> queries **simplifies the initial setup steps** in pipeline scripts\n> compared to using the overloaded `git rev-parse`.\n>\n\nWe must note that using 'git rev-parse' isn't sub-optimal. Matter of\nfact, if you look at 'builtin/rev-parse.c', you'll see that each of\nthese flags are under an if..else clause. The goal of this project is\nmore to provide a clean interface and a home for such information\nqueries.\n\nAs such the main goals of the project, are very design oriented, as\nyou've also mentioned, I would say:\n1. What should the command be called?\n2. What sub-commands should it support?\n3. What options from 'git-rev-parse(1)' do we need to port, do they need\n   to be renamed?\n4. What other options can we possibly provide?\n\n> ## Deliverables\n>\n> Acknowledging the needs that the project scope is focused on\n> refactoring `git rev-parse`, this project will introduce a new Git\n> command, tentatively named `git repo-info`, serving as the designated\n> home for specific low-level query options.\n>\n> The key deliverables for this GSoC project include:\n>\n> 1. **New Core Command: `git repo-info`**\n> * A new `builtin/repo-info.c` command integrated into the Git source code.\n> * Implementation primarily in C, leveraging existing internal Git APIs\n> and logic currently within `rev-parse.c` to implement the relocated\n> options.\n>\n> 2. **Relocated `rev-parse` Options:**\n> * Implementation of the core functionality behind the following\n> options from `git-rev-parse(1)`'s \"OPTIONS FOR FILES\" section within\n> the new `git repo-info` command:\n> * **Path Queries:** `--show-cdup`, `--show-prefix`, `--show-toplevel`,\n> `--show-superproject-working-tree`\n> * **Directory Queries:** `--git-dir`, `--git-common-dir`,\n> `--resolve-git-dir <path>`\n> * **State/Format Queries:** `--is-inside-git-dir`,\n> `--is-inside-work-tree`, `--is-bare-repository`,\n> `--is-shallow-repository`\n> * **Index File Query:** `--shared-index-path`\n>\n\nPerhaps we want to breakdown so we can have:\n\ngit info path [--cdup | --prefix | --toplevel ... ]\ngit info repo [--is-bare | --is-shallow]\n\nand so on...\n\n> 3. **Default Output Format (Text-Based):**\n> * The command's default output for each implemented option will\n> **match the current plain text output** produced by `git rev-parse`\n> for that same option, ensuring backward compatibility for scripts\n> migrating to the new command. Output will primarily be via standard C\n> functions like `printf` or `puts`.\n\nSince we'll keep the existing options within 'git-rev-parse(1)', we'll\nstay backwards compatible. Scripts which want to move to the new\ncommand, would anyway need to change the command, so there is no\nbackward compatibility there. But, having the default to be human\nreadable like the current implementation does make sense.\n\n>\n> 4. **Comprehensive Documentation:**\n> * A clear man page (`git-repo-info.adoc`) explaining the new command's\n> purpose and detailing the usage and output of each implemented option.\n> * Updates to `git-rev-parse.adoc` to clearly **deprecate** the\n> relocated options (or mark them as aliases for compatibility) and\n> point users to the new `git repo-info` command.\n>\n> 5. **Robust Test Suite:**\n> * A new test script (`t/tXXXX-repo-info.sh`) using Git's test\n> framework (`test-lib.sh`).\n> * Tests specifically validating the output of `git repo-info --option`\n> against the output of `git rev-parse --option` across various\n> repository states (standard repo, bare repo, inside `.git`, inside\n> worktree, submodules, shallow clone etc.) to ensure functional parity.\n>\n> 6. **(Stretch Goal / Potential Future Work): Structured Output**\n> * If time permits after successfully implementing, documenting, and\n> testing the core text-based functionality, investigate adding a\n> `--format=json` option to provide a structured JSON output containing\n> the results of the requested queries. This is explicitly a secondary\n> goal, contingent on completing the primary refactoring task.\n\nMany of the plumbing commands in Git provide NUL-terminated output, I'm\ncurious whether we should consider that over JSON.\n\n> **Out of Scope for GSoC (Based on Refined Goal):**\n> * Querying high-level metadata like current branch name, HEAD commit\n> details (beyond `--is-shallow-repository`), remote URLs, tags, or\n> arbitrary configuration values.\n\nWe should make sure that we don't overload this new command too.\n\n> * Complex status reporting (worktree dirtiness).\n> * Real-time monitoring or comparing metadata between revisions.\n> * Implementing JSON output as the *primary* feature.\n>\n> ## Technical Details\n>\n> This section outlines the proposed technical approach for implementing\n> the `git repo-info` command and relocating the specified options:\n>\n> 1. **Core `git repo-info` Command Implementation:**\n> * **Entry Point:** Create `builtin/repo-info.c` with\n> `cmd_repo_info(...)` function. Parse options using Git's\n> `parse-options` API.\n> * **Repository Context:** Utilize the standard `repo` structure and\n> `startup_info` provided by Git's infrastructure. Setup the repository\n> context similar to how `cmd_rev_parse` does it if needed (e.g., using\n> `setup_git_directory_gently`).\n> * **Reusing Logic:** Analyze the implementation of the target options\n> within `builtin/rev-parse.c`. Extract and adapt the relevant C\n> functions and logic (related to path manipulation using `prefix_path`,\n> `real_pathcmp`; repository state checks using\n> `is_bare_repository_cfg`, `is_inside_git_dir`, `is_inside_work_tree`;\n> accessing `startup_info`, `git_path`, etc.) into `builtin/repo-info.c`\n> or potentially shared helper functions if appropriate.\n> * **Specific Option Implementation:**\n> * `--show-toplevel`, `--show-cdup`, `--show-prefix`: Rely on the\n> `prefix` calculated during setup and path manipulation functions.\n> * `--git-dir`, `--git-common-dir`: Access `repo->gitdir`,\n> `repo->commondir` or use functions like `get_git_dir()`,\n> `get_common_dir()`. `--resolve-git-dir` will involve path resolution\n> relative to the provided argument.\n> * `--is-*` flags: Call existing helper functions like\n> `is_bare_repository_cfg()`, `is_inside_git_dir()`,\n> `is_inside_work_tree()`. `--is-shallow-repository` involves checking\n> `repo->is_shallow`.\n> * `--shared-index-path`: Access path information related to split\n> indexes if enabled.\n> * **Output Generation:** Use standard C `printf(\"%s\\n\", ...)` or\n> `puts(...)` to print the resulting string (path, \"true\"/\"false\", etc.)\n> to standard output, matching `rev-parse`'s current behavior. Boolean\n> flags typically exit `0` for true and `1` for false without output,\n> this behavior should be preserved.\n>\n> 2. **Documentation:**\n> * Create `Documentation/git-repo-info.adoc` using AsciiDoc format,\n> modeling it after existing man pages. Detail each option, its purpose,\n> and expected output.\n> * Modify `Documentation/git-rev-parse.adoc`, adding notes to the\n> relevant options indicating they are better handled by `git repo-info`\n> and potentially marking them for deprecation in a future Git version.\n>\n> 3. **Testing:**\n> * Create `t/tXXXX-repo-info.sh` using `test-lib.sh`.\n> * Structure tests using `test_expect_success` blocks.\n> * Utilize helper functions like `test_create_repo`, `cd repo`,\n> `test_cmp` to compare the output of `git repo-info --option` directly\n> against `git rev-parse --option` (for options producing output) or\n> against expected exit codes (for boolean flags).\n> * Cover edge cases like running outside a repository, in a bare\n> repository, deep within a worktree, within the `.git` directory, and\n> in repositories with submodules or worktrees.\n>\n> 4. **(Stretch Goal) JSON Output Implementation:**\n> * If attempted, add a `--format=json` option using `parse-options`.\n> * Collect results from the requested options internally.\n> * Use either an approved embedded C JSON library or Git's `strbuf` API\n> (with helpers like `strbuf_add_json_string`) to construct a JSON\n> object mapping option names (or descriptive keys) to their\n> corresponding values. Print the final JSON string to standard output.\n> Add specific tests for JSON output validation.\n>\n> ## Detailed Project Timeline\n>\n> **Phase 0: Pre-Acceptance Preparation (April 9 - May 7, 2025)**\n>\n> * **Focus:** Demonstrate continued interest and deepen understanding\n> *specifically of `rev-parse`'s internals* while awaiting results.\n> * **Activities:**\n> * **(April 9 - April 21):** Deep dive into `builtin/rev-parse.c`,\n> identifying the exact code blocks implementing the \"OPTIONS FOR\n> FILES\". Trace how they use `startup_info`, `prefix`, path functions,\n> and repository flags.\n> * **(April 22 - May 7):** Continue monitoring the mailing list. Refine\n> understanding of Git's testing framework, specifically focusing on\n> tests for `rev-parse` options (e.g., `t1006-cat-file.sh`,\n> `t5601-clone.sh` might use some flags). Review contribution\n> guidelines.\n>\n> **Phase 1: Final Planning (May 8 - May 26, 2025 Approx.)**\n>\n> * **Focus:** Formal introductions, confirm final scope & plan, setup.\n> * **Activities:**\n> * **(Week 1: May 8 - May 12):** Introduction with mentor(s). Confirm\n> the exact list of `rev-parse` options to be migrated. Discuss the\n> preferred approach for handling deprecation in `rev-parse` docs/code.\n> Discuss potential for shared helper functions vs. direct code\n> migration.\n> * **(Week 2: May 13 - May 19):** Set up dev environment. Deep dive\n> into the agreed-upon functions/code blocks within `rev-parse.c`.\n> Outline the basic structure for `builtin/repo-info.c` and the test\n> script `t/tXXXX-repo-info.sh`.\n> * **(Week 3: May 20 - May 26):** Implement the basic `cmd_repo_info`\n> skeleton, option parsing setup, and repository setup boilerplate.\n> Write initial \"no-op\" tests. Post first blog update.\n>\n> **Phase 2: Implementation in Batches (Coding Weeks 1-8: May 27 - July\n> 21, 2025 Approx.)**\n>\n> * **Focus:** Implement options in logical groups, test thoroughly,\n> submit patches early and often.\n> * **GSoC Milestone:** Midterm Evaluations occur around Week 8.\n> * **Activities:**\n> * **(Batch 1 / Weeks 1-2: May 27 - June 9):** Implement basic path\n> queries: `--show-toplevel`, `--show-prefix`, `--show-cdup`. Add tests\n> comparing output with `rev-parse`. **Submit Patch Series 1**.\n> * **(Batch 2 / Weeks 3-4: June 10 - June 23):** Implement directory\n> queries: `--git-dir`, `--git-common-dir`, `--resolve-git-dir <path>`.\n> Add tests. **Submit Patch Series 2**. Write blog post update.\n> * **(Batch 3 / Weeks 5-6: June 24 - July 7):** Implement boolean state\n> queries: `--is-bare-repository`, `--is-inside-git-dir`,\n> `--is-inside-work-tree`. Add tests checking exit codes and behavior in\n> various locations. **Submit Patch Series 3**.\n> * **(Batch 4 / Weeks 7-8: July 8 - July 21):** Implement remaining\n> queries: `--is-shallow-repository`, `--shared-index-path`,\n> `--show-superproject-working-tree`. Add comprehensive tests covering\n> interactions (e.g., in submodules, shallow clones). **Submit Patch\n> Series 4**. Prepare for Midterm evaluation; ensure submitted batches\n> demonstrate core progress. Write blog post update.\n>\n\nIt is nice to see breakdown in batches.\n\n> **Phase 3: Documentation & Final Polish (Coding Weeks 9-12: July 22 -\n> Aug 18, 2025 Approx.)**\n>\n> * **Focus:** Create documentation, address feedback on all patches,\n> refine implementation, potentially attempt stretch goal.\n\nI would say documentation should go hand-in-hand with each patch series\nthat you send. Ideally every patch series should leave the code base in\na usable state. Pushing documentation to the end, would mean that if the\nproject is stopped midway, we'd have a running command in Git with no\ndocumentation about what it does.\n\n> * **Activities:**\n> * **(Week 9: July 22 - July 28):** Write the first complete draft of\n> the man page for `git-repo-info`. Draft the necessary updates for\n> `git-rev-parse.adoc` (deprecation notices). **Submit Patch Series 5\n> (Documentation)**.\n> * **(Week 10: July 29 - Aug 4):** Focus on addressing review comments\n> on **all** previous patch series. Refactor code based on feedback.\n> Ensure test suite is robust and covers feedback points.\n> * **(Week 11: Aug 5 - Aug 11):** *Stretch Goal (Conditional):* If core\n> functionality and docs are stable and reviewed positively, begin\n> investigating/implementing `--format=json`. Add specific JSON tests if\n> implemented. Otherwise, focus on further code cleanup and test\n> hardening.\n> * **(Week 12: Aug 12 - Aug 18):** Prepare and submit final versions of\n> all patch series, incorporating all feedback. Final testing pass.\n> Write blog post update summarizing progress and final state. Code\n> freeze for final evaluation.\n>\n> **Phase 4: Final Evaluation & Wrap-up (Aug 19 - Nov 19, 2025)**\n>\n> * **Focus:** Final submissions, respond to late feedback, ensure\n> project completion.\n> * **Official GSoC Milestone:** November 19, 2025 - Program End Date.\n> * **Activities:**\n> * **(Late Aug - Sept):** Submit final GSoC evaluations. Actively\n> respond to any further comments on submitted patches from the\n> community/maintainers, aiming for merge readiness.\n> * **(Oct - Nov 19):** Monitor mailing list for patch status. Write\n> final GSoC project summary blog post. Continue engaging with the\n> community if interested in further contributions beyond GSoC.\n>\n>\n>\n> Thank You,\n> Jayatheerth\n\nThanks for your proposal!\n\n- Karthik\n"},{"id":"515714","messageId":"CA+rGoLcDt0r0mDBk44SY0NcnG3mNBy5vSNBLzeggsGwJ4d-Cwg@mail.gmail.com","threadId":"63224","inReplyTo":"CAOLa=ZQCTJLSWV-y-=nKf9J4xKr5miAo+35RktmbGmHPL4Sp-w@mail.gmail.com","subject":"Re: [GSOC] [Proposal v1] Machine-Readable Repository Information Query Tool","fromName":"JAYATHEERTH K","fromEmail":"jayatheerthkulkarni2005@gmail.com","sentAt":"2025-04-06T05:40:33Z","receivedAt":"2025-04-06T05:40:46Z","isPatch":false,"sender":{"key":"jayatheerthkulkarni2005@gmail.com","avatar":"https://avatars.githubusercontent.com/u/148841023?v=4"},"body":"On Sun, Apr 6, 2025 at 1:12 AM Karthik Nayak <karthik.188@gmail.com> wrote:\n>\n> JAYATHEERTH K <jayatheerthkulkarni2005@gmail.com> writes:\n>\n> > # Proposal for GSOC 2025 to Git\n> > **Refactoring `git rev-parse`: A Dedicated Command for Repository Information**\n> >\n> > ## Contact Details\n> > * **Name**: K Jayatheerth\n> > * **Email**: jayatheerthkulkarni2005@gmail.com\n> > * **Blog**: [Blog](https://jayatheerthkulkarni.github.io/gsoc_blog/index.html)\n> > * **GitHub**: [GitHub](https://github.com/jayatheerthkulkarni)\n> >\n> > ## Prerequisites & Experience\n> >\n> >\n> > As part of the GSoC application prerequisites, I have engaged with the\n> > Git community with a microproject involving documentation changes.\n> > This provided valuable experience with Git's codebase, contribution\n> > workflow (patch submission, feedback cycles), and communication via\n> > the mailing list.\n> >\n> > * **Microproject Patch Series:** [Main mail\n> > thread](https://lore.kernel.org/git/xmqqa59evffd.fsf@gitster.g/T/#t)\n> > (Link to the most relevant thread demonstrating interaction and\n> > successful patch refinement)\n> > * **Initial Patch:** [First\n> > Patch](https://lore.kernel.org/git/20250312081534.75536-1-jayatheerthkulkarni2005@gmail.com/t/#u)\n> > * **Mailing List Introduction:** [First\n> > Mail](https://lore.kernel.org/git/CA+rGoLc69R8qgbkYQiKoc2uweDwD10mxZXYFSY8xFs5eKSRVkA@mail.gmail.com/t/#u)\n> > * **Blog:** My GSoC blog details these interactions:\n> > [Blog](https://jayatheerthkulkarni.github.io/gsoc_blog/index.html)\n> >\n>\n> It would be nice to give a small brief about your microproject here and\n> perhaps its current status.\n>\n\nSure I will add that.\n\n> > ## **Synopsis**\n> >\n> > This project focuses on **refactoring Git by creating a dedicated\n> > command (tentatively named `git repo-info`) to house the low-level\n>\n> I wonder if 'git info' itself would be a good name, we could default the\n> command to list all prominent information about a repository. This would\n> be useful instead of scripts invoking 'git rev-parse\n\nYeah even git info doesn't overlap with any builtin/third\nparty(popular commands) as far as I can search.\n\n> --is-bare-repository' followed by a 'git rev-parse --is-inside-git-dir'\n> and so on. But we can discuss this later.\n>\n\nTrue, but for the proposal I listed some commands in detail and\ntechnical details with batch wise division of timeline as required.\n\n> > repository, path, and format-related query options currently misplaced\n> > under the \"OPTIONS FOR FILES\" section of `git-rev-parse(1)`**. This\n> > new command will provide a more logical and maintainable location for\n> > this functionality, allowing `git rev-parse` to better focus on its\n> > core purpose of parsing revisions, thus improving Git's internal\n> > organization and command structure clarity.\n> >\n> > ## **Benefits to the Community**\n> >\n> > ### **1. Improves `git rev-parse` Clarity and Maintainability**\n> > - `git rev-parse` has accumulated various options unrelated to its\n> > primary purpose of parsing revisions, particularly those for querying\n> > low-level repository state and paths.\n> > - This project **directly addresses this issue** by migrating these\n> > options to a dedicated command, making `git rev-parse` cleaner and\n> > easier to understand and maintain.\n> > - Provides a **clearer separation of concerns** within Git's command suite.\n> >\n> > ### **2. Provides Reliable Access for Automation and Scripting**\n> > - Scripts often need fundamental repository information like the\n> > top-level directory path (`--show-toplevel`), the `.git` directory\n> > location (`--git-dir`), or repository state (`--is-bare-repository`).\n> > - Currently, scripts rely on `git rev-parse` for this, mixing\n> > low-level repo queries with revision parsing calls.\n> > - The new `git repo-info` command will offer a **stable, dedicated\n> > interface** for retrieving this specific low-level information, making\n> > scripts **cleaner and more robust** by calling the command designed\n> > explicitly for these tasks.\n> > - The default output will mimic the **existing, simple text format**\n> > of the `rev-parse` options, ensuring compatibility for scripts\n> > migrating to the new command.\n> >\n> > ### **3. Enhances CI/CD Pipeline Foundations**\n> > - CI/CD pipelines frequently need to establish context by determining\n> > the repository root or `.git` directory location early in their\n> > execution.\n> > - Using the dedicated `git repo-info` command for these foundational\n> > queries **simplifies the initial setup steps** in pipeline scripts\n> > compared to using the overloaded `git rev-parse`.\n> >\n>\n> We must note that using 'git rev-parse' isn't sub-optimal. Matter of\n> fact, if you look at 'builtin/rev-parse.c', you'll see that each of\n> these flags are under an if..else clause. The goal of this project is\n> more to provide a clean interface and a home for such information\n> queries.\n>\n\nI've gone through the code in rev-parse.c and yes I found the if blocks,\nI'm taking that you mean that git rev-parse is not meant to do these\ntasks, but it is good at what it does.\nIf this is the case I think it makes the project easier, because we\nhave to port similar code and test and document it carefully.\n\n> As such the main goals of the project, are very design oriented, as\n> you've also mentioned, I would say:\n> 1. What should the command be called?\n> 2. What sub-commands should it support?\n> 3. What options from 'git-rev-parse(1)' do we need to port, do they need\n>    to be renamed?\n> 4. What other options can we possibly provide?\n>\n\nYup, I think I've not explored the 3 -> do they need to be renamed?\nMaybe, that's also because the list of commands to port is still a bit\nambiguous, we can discuss the internal names once we create a detailed\nlist of commands that we need to port into the `git info` command.\n\n> > ## Deliverables\n> >\n> > Acknowledging the needs that the project scope is focused on\n> > refactoring `git rev-parse`, this project will introduce a new Git\n> > command, tentatively named `git repo-info`, serving as the designated\n> > home for specific low-level query options.\n> >\n> > The key deliverables for this GSoC project include:\n> >\n> > 1. **New Core Command: `git repo-info`**\n> > * A new `builtin/repo-info.c` command integrated into the Git source code.\n> > * Implementation primarily in C, leveraging existing internal Git APIs\n> > and logic currently within `rev-parse.c` to implement the relocated\n> > options.\n> >\n> > 2. **Relocated `rev-parse` Options:**\n> > * Implementation of the core functionality behind the following\n> > options from `git-rev-parse(1)`'s \"OPTIONS FOR FILES\" section within\n> > the new `git repo-info` command:\n> > * **Path Queries:** `--show-cdup`, `--show-prefix`, `--show-toplevel`,\n> > `--show-superproject-working-tree`\n> > * **Directory Queries:** `--git-dir`, `--git-common-dir`,\n> > `--resolve-git-dir <path>`\n> > * **State/Format Queries:** `--is-inside-git-dir`,\n> > `--is-inside-work-tree`, `--is-bare-repository`,\n> > `--is-shallow-repository`\n> > * **Index File Query:** `--shared-index-path`\n> >\n>\n> Perhaps we want to breakdown so we can have:\n>\n> git info path [--cdup | --prefix | --toplevel ... ]\n> git info repo [--is-bare | --is-shallow]\n>\n> and so on...\n\nOk I will separate these with respect to their usage.\n\n>\n> > 3. **Default Output Format (Text-Based):**\n> > * The command's default output for each implemented option will\n> > **match the current plain text output** produced by `git rev-parse`\n> > for that same option, ensuring backward compatibility for scripts\n> > migrating to the new command. Output will primarily be via standard C\n> > functions like `printf` or `puts`.\n>\n> Since we'll keep the existing options within 'git-rev-parse(1)', we'll\n> stay backwards compatible. Scripts which want to move to the new\n> command, would anyway need to change the command, so there is no\n> backward compatibility there. But, having the default to be human\n> readable like the current implementation does make sense.\n>\n\nOk this raises a new question, if we are not looking towards backward\ncompatibility and also looking towards machine readability, I think\nusing JSON from the start would make things flexible, do correct me on\nthis.\n\nBecause once people start to make things compatible with human\nreadable text they probably won't use JSON again, and JSON might\nmitigate some errors. So I think I need some feedback on this.\n\n> >\n> > 4. **Comprehensive Documentation:**\n> > * A clear man page (`git-repo-info.adoc`) explaining the new command's\n> > purpose and detailing the usage and output of each implemented option.\n> > * Updates to `git-rev-parse.adoc` to clearly **deprecate** the\n> > relocated options (or mark them as aliases for compatibility) and\n> > point users to the new `git repo-info` command.\n> >\n> > 5. **Robust Test Suite:**\n> > * A new test script (`t/tXXXX-repo-info.sh`) using Git's test\n> > framework (`test-lib.sh`).\n> > * Tests specifically validating the output of `git repo-info --option`\n> > against the output of `git rev-parse --option` across various\n> > repository states (standard repo, bare repo, inside `.git`, inside\n> > worktree, submodules, shallow clone etc.) to ensure functional parity.\n> >\n> > 6. **(Stretch Goal / Potential Future Work): Structured Output**\n> > * If time permits after successfully implementing, documenting, and\n> > testing the core text-based functionality, investigate adding a\n> > `--format=json` option to provide a structured JSON output containing\n> > the results of the requested queries. This is explicitly a secondary\n> > goal, contingent on completing the primary refactoring task.\n>\n> Many of the plumbing commands in Git provide NUL-terminated output, I'm\n> curious whether we should consider that over JSON.\n>\n\nI think we can use a flag to define what type of output we want in the\nlong term.\nI think both of these have their own pros and cons. As I said I think\nI need some feedback on the format.\n\n> > **Out of Scope for GSoC (Based on Refined Goal):**\n> > * Querying high-level metadata like current branch name, HEAD commit\n> > details (beyond `--is-shallow-repository`), remote URLs, tags, or\n> > arbitrary configuration values.\n>\n> We should make sure that we don't overload this new command too.\n>\n\nAgreed, I think for this GSOC I will largely focus on porting existing\nflags in rev-parse to a new command.\n\n> > * Complex status reporting (worktree dirtiness).\n> > * Real-time monitoring or comparing metadata between revisions.\n> > * Implementing JSON output as the *primary* feature.\n> >\n\nEven with revisioning, I think the above part comes up, I think I will\nremove this from the proposal too, I think even this make the command\ncluttered.\n\n> > ## Technical Details\n> >\n> > This section outlines the proposed technical approach for implementing\n> > the `git repo-info` command and relocating the specified options:\n> >\n> > 1. **Core `git repo-info` Command Implementation:**\n> > * **Entry Point:** Create `builtin/repo-info.c` with\n> > `cmd_repo_info(...)` function. Parse options using Git's\n> > `parse-options` API.\n> > * **Repository Context:** Utilize the standard `repo` structure and\n> > `startup_info` provided by Git's infrastructure. Setup the repository\n> > context similar to how `cmd_rev_parse` does it if needed (e.g., using\n> > `setup_git_directory_gently`).\n> > * **Reusing Logic:** Analyze the implementation of the target options\n> > within `builtin/rev-parse.c`. Extract and adapt the relevant C\n> > functions and logic (related to path manipulation using `prefix_path`,\n> > `real_pathcmp`; repository state checks using\n> > `is_bare_repository_cfg`, `is_inside_git_dir`, `is_inside_work_tree`;\n> > accessing `startup_info`, `git_path`, etc.) into `builtin/repo-info.c`\n> > or potentially shared helper functions if appropriate.\n> > * **Specific Option Implementation:**\n> > * `--show-toplevel`, `--show-cdup`, `--show-prefix`: Rely on the\n> > `prefix` calculated during setup and path manipulation functions.\n> > * `--git-dir`, `--git-common-dir`: Access `repo->gitdir`,\n> > `repo->commondir` or use functions like `get_git_dir()`,\n> > `get_common_dir()`. `--resolve-git-dir` will involve path resolution\n> > relative to the provided argument.\n> > * `--is-*` flags: Call existing helper functions like\n> > `is_bare_repository_cfg()`, `is_inside_git_dir()`,\n> > `is_inside_work_tree()`. `--is-shallow-repository` involves checking\n> > `repo->is_shallow`.\n> > * `--shared-index-path`: Access path information related to split\n> > indexes if enabled.\n> > * **Output Generation:** Use standard C `printf(\"%s\\n\", ...)` or\n> > `puts(...)` to print the resulting string (path, \"true\"/\"false\", etc.)\n> > to standard output, matching `rev-parse`'s current behavior. Boolean\n> > flags typically exit `0` for true and `1` for false without output,\n> > this behavior should be preserved.\n> >\n> > 2. **Documentation:**\n> > * Create `Documentation/git-repo-info.adoc` using AsciiDoc format,\n> > modeling it after existing man pages. Detail each option, its purpose,\n> > and expected output.\n> > * Modify `Documentation/git-rev-parse.adoc`, adding notes to the\n> > relevant options indicating they are better handled by `git repo-info`\n> > and potentially marking them for deprecation in a future Git version.\n> >\n> > 3. **Testing:**\n> > * Create `t/tXXXX-repo-info.sh` using `test-lib.sh`.\n> > * Structure tests using `test_expect_success` blocks.\n> > * Utilize helper functions like `test_create_repo`, `cd repo`,\n> > `test_cmp` to compare the output of `git repo-info --option` directly\n> > against `git rev-parse --option` (for options producing output) or\n> > against expected exit codes (for boolean flags).\n> > * Cover edge cases like running outside a repository, in a bare\n> > repository, deep within a worktree, within the `.git` directory, and\n> > in repositories with submodules or worktrees.\n> >\n> > 4. **(Stretch Goal) JSON Output Implementation:**\n> > * If attempted, add a `--format=json` option using `parse-options`.\n> > * Collect results from the requested options internally.\n> > * Use either an approved embedded C JSON library or Git's `strbuf` API\n> > (with helpers like `strbuf_add_json_string`) to construct a JSON\n> > object mapping option names (or descriptive keys) to their\n> > corresponding values. Print the final JSON string to standard output.\n> > Add specific tests for JSON output validation.\n> >\n> > ## Detailed Project Timeline\n> >\n> > **Phase 0: Pre-Acceptance Preparation (April 9 - May 7, 2025)**\n> >\n> > * **Focus:** Demonstrate continued interest and deepen understanding\n> > *specifically of `rev-parse`'s internals* while awaiting results.\n> > * **Activities:**\n> > * **(April 9 - April 21):** Deep dive into `builtin/rev-parse.c`,\n> > identifying the exact code blocks implementing the \"OPTIONS FOR\n> > FILES\". Trace how they use `startup_info`, `prefix`, path functions,\n> > and repository flags.\n> > * **(April 22 - May 7):** Continue monitoring the mailing list. Refine\n> > understanding of Git's testing framework, specifically focusing on\n> > tests for `rev-parse` options (e.g., `t1006-cat-file.sh`,\n> > `t5601-clone.sh` might use some flags). Review contribution\n> > guidelines.\n> >\n> > **Phase 1: Final Planning (May 8 - May 26, 2025 Approx.)**\n> >\n> > * **Focus:** Formal introductions, confirm final scope & plan, setup.\n> > * **Activities:**\n> > * **(Week 1: May 8 - May 12):** Introduction with mentor(s). Confirm\n> > the exact list of `rev-parse` options to be migrated. Discuss the\n> > preferred approach for handling deprecation in `rev-parse` docs/code.\n> > Discuss potential for shared helper functions vs. direct code\n> > migration.\n> > * **(Week 2: May 13 - May 19):** Set up dev environment. Deep dive\n> > into the agreed-upon functions/code blocks within `rev-parse.c`.\n> > Outline the basic structure for `builtin/repo-info.c` and the test\n> > script `t/tXXXX-repo-info.sh`.\n> > * **(Week 3: May 20 - May 26):** Implement the basic `cmd_repo_info`\n> > skeleton, option parsing setup, and repository setup boilerplate.\n> > Write initial \"no-op\" tests. Post first blog update.\n> >\n> > **Phase 2: Implementation in Batches (Coding Weeks 1-8: May 27 - July\n> > 21, 2025 Approx.)**\n> >\n> > * **Focus:** Implement options in logical groups, test thoroughly,\n> > submit patches early and often.\n> > * **GSoC Milestone:** Midterm Evaluations occur around Week 8.\n> > * **Activities:**\n> > * **(Batch 1 / Weeks 1-2: May 27 - June 9):** Implement basic path\n> > queries: `--show-toplevel`, `--show-prefix`, `--show-cdup`. Add tests\n> > comparing output with `rev-parse`. **Submit Patch Series 1**.\n> > * **(Batch 2 / Weeks 3-4: June 10 - June 23):** Implement directory\n> > queries: `--git-dir`, `--git-common-dir`, `--resolve-git-dir <path>`.\n> > Add tests. **Submit Patch Series 2**. Write blog post update.\n> > * **(Batch 3 / Weeks 5-6: June 24 - July 7):** Implement boolean state\n> > queries: `--is-bare-repository`, `--is-inside-git-dir`,\n> > `--is-inside-work-tree`. Add tests checking exit codes and behavior in\n> > various locations. **Submit Patch Series 3**.\n> > * **(Batch 4 / Weeks 7-8: July 8 - July 21):** Implement remaining\n> > queries: `--is-shallow-repository`, `--shared-index-path`,\n> > `--show-superproject-working-tree`. Add comprehensive tests covering\n> > interactions (e.g., in submodules, shallow clones). **Submit Patch\n> > Series 4**. Prepare for Midterm evaluation; ensure submitted batches\n> > demonstrate core progress. Write blog post update.\n> >\n>\n> It is nice to see breakdown in batches.\n>\n\nThank you.\n\n> > **Phase 3: Documentation & Final Polish (Coding Weeks 9-12: July 22 -\n> > Aug 18, 2025 Approx.)**\n> >\n> > * **Focus:** Create documentation, address feedback on all patches,\n> > refine implementation, potentially attempt stretch goal.\n>\n> I would say documentation should go hand-in-hand with each patch series\n> that you send. Ideally every patch series should leave the code base in\n> a usable state. Pushing documentation to the end, would mean that if the\n> project is stopped midway, we'd have a running command in Git with no\n> documentation about what it does.\n>\n\nOk I think I will add them parallel to the batches above, nice point.\n\n> > * **Activities:**\n> > * **(Week 9: July 22 - July 28):** Write the first complete draft of\n> > the man page for `git-repo-info`. Draft the necessary updates for\n> > `git-rev-parse.adoc` (deprecation notices). **Submit Patch Series 5\n> > (Documentation)**.\n> > * **(Week 10: July 29 - Aug 4):** Focus on addressing review comments\n> > on **all** previous patch series. Refactor code based on feedback.\n> > Ensure test suite is robust and covers feedback points.\n> > * **(Week 11: Aug 5 - Aug 11):** *Stretch Goal (Conditional):* If core\n> > functionality and docs are stable and reviewed positively, begin\n> > investigating/implementing `--format=json`. Add specific JSON tests if\n> > implemented. Otherwise, focus on further code cleanup and test\n> > hardening.\n> > * **(Week 12: Aug 12 - Aug 18):** Prepare and submit final versions of\n> > all patch series, incorporating all feedback. Final testing pass.\n> > Write blog post update summarizing progress and final state. Code\n> > freeze for final evaluation.\n> >\n> > **Phase 4: Final Evaluation & Wrap-up (Aug 19 - Nov 19, 2025)**\n> >\n> > * **Focus:** Final submissions, respond to late feedback, ensure\n> > project completion.\n> > * **Official GSoC Milestone:** November 19, 2025 - Program End Date.\n> > * **Activities:**\n> > * **(Late Aug - Sept):** Submit final GSoC evaluations. Actively\n> > respond to any further comments on submitted patches from the\n> > community/maintainers, aiming for merge readiness.\n> > * **(Oct - Nov 19):** Monitor mailing list for patch status. Write\n> > final GSoC project summary blog post. Continue engaging with the\n> > community if interested in further contributions beyond GSoC.\n> >\n> >\n> >\n> > Thank You,\n> > Jayatheerth\n>\n> Thanks for your proposal!\n>\n> - Karthik\n\nThank you again Karthik, will send the updated proposal in this thread soon.\n\n-Jayatheerth\n"},{"id":"515716","messageId":"CA+rGoLc9g4werz-k4_ZzfNLLGHjzHoOcFYSmV5V-Krq04drgZA@mail.gmail.com","threadId":"63224","inReplyTo":"CA+rGoLcDt0r0mDBk44SY0NcnG3mNBy5vSNBLzeggsGwJ4d-Cwg@mail.gmail.com","subject":"Re: [GSOC] [Proposal v1] Machine-Readable Repository Information Query Tool","fromName":"JAYATHEERTH K","fromEmail":"jayatheerthkulkarni2005@gmail.com","sentAt":"2025-04-06T06:09:32Z","receivedAt":"2025-04-06T06:09:44Z","isPatch":false,"sender":{"key":"jayatheerthkulkarni2005@gmail.com","avatar":"https://avatars.githubusercontent.com/u/148841023?v=4"},"body":"# Proposal for GSOC 2025 to Git\n**Machine-Readable Repository Information Query Tool**\n\n## Contact Details\n* **Name**: K Jayatheerth\n* **Email**: jayatheerthkulkarni2005@gmail.com\n* **Blog**: [Blog](https://jayatheerthkulkarni.github.io/gsoc_blog/index.html)\n* **GitHub**: [GitHub](https://github.com/jayatheerthkulkarni)\n\n## Prerequisites & Experience\n\n\nAs part of the GSoC application prerequisites, I have engaged with the\nGit community and initiated a microproject. This involved **updating\ndocumentation for `MyFirstContribution.adoc` and update it with modern\ncodebase**, providing valuable experience with Git's codebase\nstructure (documentation files), the contribution workflow (patch\nsubmission using `git send-email`, addressing feedback across\nversions), and communication via the mailing list.\n\n* **Microproject Status:** v4 submitted, incorporating feedback,\nawaiting further review.\n* **Microproject Patch Series:** [Main mail\nthread](https://lore.kernel.org/git/xmqqa59evffd.fsf@gitster.g/T/#t)\n(Link to the most relevant thread demonstrating interaction and\nsuccessful patch refinement)\n* **Initial Patch:** [First\nPatch](https://lore.kernel.org/git/20250312081534.75536-1-jayatheerthkulkarni2005@gmail.com/t/#u)\n* **Mailing List Introduction:** [First\nMail](https://lore.kernel.org/git/CA+rGoLc69R8qgbkYQiKoc2uweDwD10mxZXYFSY8xFs5eKSRVkA@mail.gmail.com/t/#u)\n* **Blog:** My GSoC blog details these interactions:\n[Blog](https://jayatheerthkulkarni.github.io/gsoc_blog/index.html)\n\n## **Synopsis**\n\nThis project focuses on **refactoring Git by creating a dedicated\ncommand (tentatively named `git info`, subject to further discussion)\nto house the low-level repository, path, and format-related query\noptions currently misplaced under the \"OPTIONS FOR FILES\" section of\n`git-rev-parse(1)`**. This new command, potentially using a subcommand\nstructure (e.g., `git info path`, `git info repo`), will provide a\nmore logical and maintainable location for this functionality. This\nallows `git rev-parse` to better focus on its core purpose of parsing\nrevisions, ultimately improving Git's internal organization and\ncommand structure clarity by offering a **cleaner interface** for\nthese specific queries.\n\n## **Benefits to the Community**\n\n### **1. Improves `git rev-parse` Clarity and Maintainability**\n- `git rev-parse` has accumulated various options unrelated to its\nprimary purpose of parsing revisions, particularly those for querying\nlow-level repository state and paths.\n- This project **directly addresses this issue** by migrating these\noptions to a dedicated, purpose-built command, making `git rev-parse`\ncleaner and easier to understand and maintain.\n- Provides a **clearer separation of concerns** within Git's command suite.\n\n### **2. Provides Reliable Access for Automation and Scripting**\n- Scripts often need fundamental repository information like the\ntop-level directory path, the `.git` directory location, or repository\nstate.\n- Currently, scripts rely on `git rev-parse` for this, invoking it for\ntasks outside its core revision-parsing role.\n- The new `git info` command will offer a **stable, dedicated, and\ncleaner interface** for retrieving this specific low-level\ninformation, making scripts **more robust and readable** by calling\nthe command designed explicitly for these tasks.\n\n\n\n## Deliverables\n\nThis project will introduce a new Git command, **tentatively named\n`git info`**, serving as the designated home for specific low-level\nquery options migrated from `git rev-parse`. The implementation will\nlikely adopt a **subcommand structure**.\n\nThe key deliverables for this GSoC project include:\n\n1. **New Core Command: `git info` with Subcommands**\n* A new `builtin/info.c` command integrated into the Git source code.\n* Implementation primarily in C, using `parse-options` to handle\n**subcommands** (e.g., `path`, `repo`, `misc`) and their specific\noptions.\n* Leverages existing internal Git APIs and logic currently within `rev-parse.c`.\n\n2. **Relocated `rev-parse` Options under Subcommands:**\n* Implementation of the core functionality behind selected options\nfrom `git-rev-parse(1)`'s \"OPTIONS FOR FILES\" section, organized under\nappropriate subcommands within `git info`. *(Specific options and\nsubcommand grouping subject to final confirmation with mentor)*:\n* **`git info path ...` (Example Grouping):**\n* `--show-cdup` -> `git info path --cdup` (or similar)\n* `--show-prefix` -> `git info path --prefix`\n* `--show-toplevel` -> `git info path --toplevel`\n* `--show-superproject-working-tree` -> `git info path --superproject-worktree`\n* **`git info repo ...` (Example Grouping):**\n* `--git-dir` -> `git info repo --git-dir`\n* `--git-common-dir` -> `git info repo --common-dir`\n* `--resolve-git-dir <path>` -> `git info repo --resolve-dir <path>`\n* `--is-bare-repository` -> `git info repo --is-bare`\n* `--is-shallow-repository` -> `git info repo --is-shallow`\n* **`git info misc ...` (Example Grouping for others):**\n* `--is-inside-git-dir` -> `git info misc --inside-gitdir`\n* `--is-inside-work-tree` -> `git info misc --inside-worktree`\n* `--shared-index-path` -> `git info misc --shared-index-path`\n* *(Design Consideration):* Option names within subcommands might be\nslightly adjusted for clarity/consistency (e.g., dropping \"show-\").\n\n3. **Multiple Output Formats:**\n* **Default Text Output:** The default output for each implemented\noption will be simple, human-readable text, **matching the semantics\nand format** produced by the corresponding `git rev-parse` option\n(e.g., printing a path string, \"true\"/\"false\", or exiting with status\n0/1 for boolean checks).\n* **NUL Termination (`-z`):** Implement a `-z` option (standard across\nmany Git plumbing commands) for unambiguous, newline-safe output\nsuitable for scripting, particularly for path-related options.\n* **JSON Output (`--json`):** Implement a `--json` option to provide\nstructured output, mapping query keys (derived from options) to their\nvalues. This offers maximum flexibility for tools consuming the\ninformation. *(The relative priority and implementation details of\n`-z` vs `--json` to be discussed with mentor, but both are considered\ncore deliverables)*.\n\n4. **Comprehensive Documentation (Incremental):**\n* A clear man page (`git-info.adoc`) explaining the new command's\npurpose, the subcommand structure, and detailing the usage, options\n(including `-z`, `--json`), and output formats for each implemented\nfeature. **Relevant sections of the man page will be added or updated\nwithin each patch series submitted.**\n* Updates to `git-rev-parse.adoc` to clearly **document the\nrelationship** with `git info` for the migrated options (e.g., noting\nthat `git info` is the preferred command) and potentially marking them\nfor deprecation. **These updates will also be included incrementally\nwith relevant patch series.**\n\n5. **Robust Test Suite (Incremental):**\n* A new test script (`t/tXXXX-info.sh`) using Git's test framework\n(`test-lib.sh`).\n* Tests covering the subcommand structure, each implemented option,\nand **all output formats** (`text`, `-z`, `--json`).\n* Tests validating behavior across various repository states\n(standard, bare, inside `.git`, inside worktree, submodules, shallow\nclone etc.). **New tests will be added within each patch series for\nthe features implemented.**\n\n\n## Technical Details\n\n\n1. **Core `git info` Command Implementation:**\n* **Entry Point:** Create `builtin/info.c` with `cmd_info(...)`. Use\n`parse-options` to parse the **subcommand** first. Based on the\nsubcommand, invoke a specific helper function (e.g.,\n`cmd_info_path()`, `cmd_info_repo()`) which then uses `parse-options`\nagain to handle the options specific to that subcommand.\n* **Repository Context:** Standard setup using `repo` structure,\n`startup_info`, and potentially `setup_git_directory_gently`.\n* **Reusing Logic:** Adapt logic from `builtin/rev-parse.c` for the\ncore functionality of each option. This might involve direct code\nmigration or creating shared helper functions where appropriate.\n* **Subcommand Implementation:** Implement helper functions for each\nsubcommand (`path`, `repo`, `misc`) containing the `parse_options`\ncalls and logic for the options within that group.\n* **Output Generation:**\n* **Text (Default):** Use `printf(\"%s\\n\", ...)` / `puts(...)` for\nstring output; print \"true\"/\"false\" or use `exit(0)` / `exit(1)` for\nboolean checks, mimicking `rev-parse`.\n* **NUL (`-z`):** Use `putchar('\\0')` or `fwrite(..., 1, 1, stdout)`\ninstead of newline for string output when `-z` is active. Boolean\nchecks likely remain exit-code based.\n* **JSON (`--json`):** Collect results internally. Use Git's `strbuf`\nAPI (with `strbuf_add_json_string` etc.) or potentially an approved C\nJSON library to construct and print a JSON object mapping keys to\nvalues. All requested info within a single invocation should ideally\nbe combined into one JSON object.\n\n2. **Documentation:**\n* Create `Documentation/git-info.adoc`. Structure based on\nsubcommands. Detail each subcommand and its options, including `-z`\nand `--json` behavior.\n* Modify `Documentation/git-rev-parse.adoc` to add cross-references\nfor relevant options.\n* **Documentation updates will accompany the code changes in each\npatch series.**\n\n3. **Testing:**\n* Create `t/tXXXX-info.sh`.\n* Use `test_expect_success` with helpers like `test_create_repo`,\n`test_cmp`, `test_must_fail`.\n* Add tests for:\n* Correct subcommand parsing and error handling.\n* Each option under its subcommand, comparing **text output** against\n`rev-parse` (where applicable) or expected values/exit codes.\n* **`-z` output** using appropriate comparison methods (e.g., piping\nto `tr '\\\\0' '\\\\n'`).\n* **`--json` output** using tools like `jq` (if available in test env)\nor careful `grep`/`sed` checks for structure and values.\n* **Tests will be added incrementally with the features in each patch series.**\n\n## Detailed Project Timeline\n\n\n**Phase 0: Pre-Acceptance Preparation (April 9 - May 7, 2025)**\n*\n\n**Phase 1: Community Bonding & Final Planning (May 8 - May 26, 2025 Approx.)**\n* **Focus:** Formal introductions, finalize scope, agree on command\nstructure, setup.\n* **Activities:**\n* **(Week 1: May 8 - May 12):** Discuss proposal with mentor(s). Finalize:\n* Command name (`git info` or alternative).\n* Subcommand structure and grouping of options.\n* Exact list of options to port, and any necessary renaming within subcommands.\n* Approach for handling relationship with `rev-parse` (deprecation vs.\naliasing vs. simple documentation cross-link).\n* Prioritization/approach for implementing `-z` and `--json`.\n* **(Week 2: May 13 - May 19):** Set up dev environment. Deep dive\ninto agreed-upon code blocks in `rev-parse.c`. Outline\n`builtin/info.c` structure including subcommand handlers. Outline\ninitial test script `t/tXXXX-info.sh`.\n* **(Week 3: May 20 - May 26):** Implement basic `cmd_info` skeleton,\ntop-level subcommand parsing, repository setup. Implement one simple\nsubcommand handler (e.g., `cmd_info_path`) with basic option parsing\nstructure. Write initial \"no-op\" / basic structure tests. Post first\nblog update.\n\n**Phase 2: Implementation in Batches (Coding Weeks 1-8: May 27 - July\n21, 2025 Approx.)**\n* **Focus:** Implement options within subcommands, including\ndocumentation and tests for text output first, then potentially add\nmachine-readable formats. Submit patches early and often.\n* **GSoC Milestone:** Midterm Evaluations occur around Week 8.\n* **Activities:** *(Structure assumes implementing text output first,\nthen `-z`/`--json` later in the phase)*\n* **(Batch 1 / Weeks 1-2: May 27 - June 9):** Implement `path`\nsubcommand options (`--toplevel`, `--prefix`, `--cdup`). Implement\n**text output**. Add corresponding **tests** and **documentation**\nsnippets (for `git-info.adoc` and `git-rev-parse.adoc`). **Submit\nPatch Series 1**.\n* **(Batch 2 / Weeks 3-4: June 10 - June 23):** Implement `repo`\nsubcommand options (`--git-dir`, `--common-dir`, `--resolve-dir`,\n`--is-bare`). Implement **text output**. Add **tests** and\n**documentation** snippets. **Submit Patch Series 2**. Write blog post\nupdate.\n* **(Batch 3 / Weeks 5-6: June 24 - July 7):** Implement remaining\n`repo` (`--is-shallow`) and `misc` subcommand options\n(`--inside-gitdir`, `--inside-worktree`, `--shared-index-path`,\n`--superproject-worktree` - *adjust subcommand grouping based on final\nplan*). Implement **text output**. Add **tests** and\n**documentation**. **Submit Patch Series 3**.\n* **(Batch 4 / Weeks 7-8: July 8 - July 21):** Implement **`-z` and\n`--json` output formats** for all options added in Batches 1-3. Add\ncomprehensive **tests** for these formats. Update **documentation** to\nfully describe `-z` and `--json` behavior. **Submit Patch Series 4**.\nPrepare for Midterm evaluation; ensure submitted batches show\nsubstantial progress on core functionality and formats. Write blog\npost update.\n\n**Phase 3: Refinement & Final Polish (Coding Weeks 9-12: July 22 - Aug\n18, 2025 Approx.)**\n* **Focus:** Address feedback on all patches, ensure robustness,\nfinalize documentation consistency.\n* **Activities:**\n* **(Week 9: July 22 - July 28):** Focus on addressing review comments\non **all** previous patch series (Code, Tests, Docs). Refactor based\non feedback.\n* **(Week 10: July 29 - Aug 4):** Continue addressing feedback. Ensure\nthe test suite is robust, covers edge cases identified in reviews.\nPerform thorough documentation review for consistency and clarity\nacross the entire man page.\n* **(Week 11: Aug 5 - Aug 11):** Final code cleanup. Final pass on\ntest coverage. *(Stretch Goal Idea):* If all core work is stable and\ntime permits, potentially explore adding one or two *new*, simple,\nagreed-upon repo info queries (not from `rev-parse`) that fit the\ncommand's purpose.\n* **(Week 12: Aug 12 - Aug 18):** Prepare and submit final versions of\nall patch series, incorporating all feedback. Final self-testing.\nWrite blog post update summarizing progress and final state. Code\nfreeze for final evaluation.\n\n**Phase 4: Final Evaluation & Wrap-up (Aug 19 - Nov 19, 2025)**\n* Write final GSoC project summary blog post. Continue engaging with\nthe community in further contributions beyond GSoC.\nThank You,\nJayatheerth\n"},{"id":"515720","messageId":"f5ba0329-5789-4c20-a2ea-b213365af5a5@gmail.com","threadId":"63224","inReplyTo":"CA+rGoLc9g4werz-k4_ZzfNLLGHjzHoOcFYSmV5V-Krq04drgZA@mail.gmail.com","subject":"Re: [GSOC] [Proposal v1] Machine-Readable Repository Information Query Tool","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2025-04-06T18:08:31Z","receivedAt":"2025-04-06T18:08:52Z","isPatch":false,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"Hi Jayatheerth,\n\nOn 06/04/25 11:39, JAYATHEERTH K wrote:\n> # Proposal for GSOC 2025 to Git\n> **Machine-Readable Repository Information Query Tool**\n> \n\nThank you for your proposal! Just wanted to send in a gentle reminder \nthat the proposal submission deadline is April 8 18:00 UTC. So, there's \nvery less time until the same. You may want to consider submitted your \ncurrent proposal and use the option provided in the GSoC website to \nupdate the proposal before the due date (if necessary). This would help \navoid a last minute rush.\n\nFeel free to let me know in case you face any difficulty with submitting \nyour proposal.\n\n--\nSivaraam\n"},{"id":"515740","messageId":"CA+rGoLfPDVmxN7QQjjNhiwL=c1PUiQRKe8JGqkbm=dEaqWJ=9A@mail.gmail.com","threadId":"63224","inReplyTo":"f5ba0329-5789-4c20-a2ea-b213365af5a5@gmail.com","subject":"Re: [GSOC] [Proposal v1] Machine-Readable Repository Information Query Tool","fromName":"JAYATHEERTH K","fromEmail":"jayatheerthkulkarni2005@gmail.com","sentAt":"2025-04-07T02:32:26Z","receivedAt":"2025-04-07T02:32:38Z","isPatch":false,"sender":{"key":"jayatheerthkulkarni2005@gmail.com","avatar":"https://avatars.githubusercontent.com/u/148841023?v=4"},"body":"Hey Sivaraam,\n\nOn Sun, Apr 6, 2025 at 11:38 PM Kaartic Sivaraam\n<kaartic.sivaraam@gmail.com> wrote:\n>\n> Hi Jayatheerth,\n>\n> On 06/04/25 11:39, JAYATHEERTH K wrote:\n> > # Proposal for GSOC 2025 to Git\n> > **Machine-Readable Repository Information Query Tool**\n> >\n>\n> Thank you for your proposal! Just wanted to send in a gentle reminder\n> that the proposal submission deadline is April 8 18:00 UTC. So, there's\n> very less time until the same. You may want to consider submitted your\n> current proposal and use the option provided in the GSoC website to\n> update the proposal before the due date (if necessary). This would help\n> avoid a last minute rush.\n\nGot it, uploaded the current version, based on the feedback will change it.\n\n>\n> Feel free to let me know in case you face any difficulty with submitting\n> your proposal.\n>\n\nSure, thank you!\n\n> --\n> Sivaraam\n\n-Jayatheerth\n"}]}