[GSoC] git-refs proposal v2

## Name and Contact Information

- Full Name: Zheng Yuting
- Email Address: 05ZYT30@gmail.com
- Time Zone: UTC +8:00

---

## Abstract

The current Git reference management functionality is fragmented across multiple independent commands (`git-show-ref`, `git-for-each-ref`, `git-update-ref`, `git-pack-refs`, `git-check-ref-format`, and `git-symbolic-ref`), leading to code redundancy and increased maintenance costs. Based on Patrick Steinhardt’s integration vision[1], this project aims to consolidate functionality under the unified `git-refs` command by initially implementing three core subcommands: **show**, **list**, and **update**. These subcommands will cover the most essential reference management operations while ensuring backward compatibility and laying the foundation for further refinement.

If time permits, additional subcommands (such as `exists`, `resolve`, `pack`, and `check-format`) will be gradually integrated to extend and enhance the existing functionality. Comprehensive testing and updated documentation will support this phased approach, ensuring a robust transition from the legacy tools.

---

## Implementation Plan

### Command Integration Strategy

#### Implementation Sequence

The development will proceed in the following order:

1. `git-refs show`
   - **Purpose:** Replace `git-show-ref --verify` with strict
reference validation.

2. `git-refs list`
   - **Purpose:** Merge `git-show-ref` and `git-for-each-ref` for
listing references.
   - **Output Format:** `<oid> SP <ref> LF` (git-show-ref style).
   - **Options:**
     - **Filtering:**
       - From `git-for-each-ref`:
         - `--count`,
         - `--points-at=<object>`,
         - `--merged[=<object>]`,
         - `--no-merged[=<object>]`,
         - `--contains[=<object>]`,
         - `--no-contains[=<object>]`,
         - `--omit-empty`,
         - `--exclude=<pattern>`,
         - `--include-root-refs`.
       - From `git-show-ref`:
         - `--head`,
         - `--branches`,
         - `--tags`,
         - `--exclude-existing`.
     - **Sorting:**
       - From `git-for-each-ref`: `--sort=<key>`.
     - **Formatting:**
       - From `git-for-each-ref`:
         - `--format=<format>`,
         - `--color[=<when>]`,
         - `--tcl` (under discussion),
         - `--shell`(under discussion),
         - `--perl`(under discussion).
       - From `git-show-ref`:
         - `--dereference`,
         - `--hash`.
     - **Global:** `--ignore-case` (applies to all filtering/sorting).

3. `git-refs update`
   - **Purpose:** Replace `git-update-ref` with transactional updates and
batch processing.
   - **Options (all from `git-update-ref`):**
     - `<ref>`: Target reference.
     - `<newvalue>`: New object identifier.
     - `[<oldvalue>]`: Expected old value (atomic check).
     - `--stdin`: Read batch updates from stdin.
     - `-d, --delete`: Delete the reference.
     - `-m <message>, --message <message>`: Custom reflog message.
     - `--no-reflog`: Skip reflog updates.
     - `--no-deref`: Update symbolic refs directly.

---

#### Testing & Documentation Updates:

- **Unified Testing:**
  - Develop comprehensive test cases for each subcommand to ensure
that the new commands produce outputs consistent with the legacy ones.
  - Leverage existing test scenarios (e.g., those used for `git-show-ref`
and `git-update-ref`) and add new tests specific to the new option
categories and output formats.

- **Documentation:**
  - Update the user manual (e.g., Documentation/git-refs.txt) to include
detailed sections for each subcommand, mapping the new options to
their legacy equivalents.
  - Provide developer notes to explain changes, highlight areas of
functional parity, and outline the phased implementation approach.

---

### Timeline

- **May 8 – May 17 (10 days):** Design Finalization & Alignment (publish
proposals, resolve conflicts).

- **May 18 – June 7 (21 days):** Implement `git-refs show` (includes
testing/docs).

- **June 8 – July 3 (26 days):** Implement `git-refs list` (includes
testing/docs).

- **July 4 – August 4 (32 days):** Implement `git-refs update` (includes
testing/docs).

- **August 5 – August 25 (21 days):** Cross-command validation &
edge-case fixes.

- **August 26 – September 1 (7 days):** Final Review & Adjustments.

---

## Background & Experience

I graduated in June 2024 from Wenzhou University with a degree in Network Engineering. My experience includes C programming and command-line tool development, along with proficiency in Shell scripting. I am currently in a transitional phase and expect to finalize my schedule by late April, and then update my weekly schedule for GSoC, estimating 25-30 hours per week for this project currently.

### Project Experience

- **One Student One Chip Project[2]**
  Extending the open-source NEMU simulator by implementing CPU cycle
  functionalities in C.
- **Web Development**
  Developed a Django-based campus website, including user chat, news
  publishing, and teacher management modules.
- **Custom Communication Protocols**
  Built a UDP-based chatroom with peer-to-peer and group messaging.
- **Stock Monitoring Tool**
  Implemented real-time monitoring and historical data analysis, with
  email alerting and planned AI-driven strategy optimization.

I have also obtained CCNA certification and gained hands-on experience as a network engineer. Additionally, I contributed a patch (currently pending merge) optimizing send-email functionality in Git [3], which has given me valuable insights into the Git codebase. For reference, my draft proposal discussions can be reviewed on the mailing list [4], and `git-refs list` discussion on the mailing list [5].

---

## Appendix

[1] https://gitlab.com/gitlab-org/git/-/issues/330 [2] https://ysyx.oscc.cc/en/project/intro.html [3] https://lore.kernel.org/git/20250312064639.668875-1-05ZYT30@gmail.com/ [4] https://lore.kernel.org/git/CAMvj1+rbYKFNeWEvvN76MTpzfuWc4TN4ViXRE4nTfWy7ZMspWg@mail.gmail.com/ [5] https://lore.kernel.org/git/20250403154404.3459805-1-05ZYT30@gmail.com/