[GSoC] git-refs proposal v2

[Yuting Zheng <05zyt30@gmail.com>]

## 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/