## Name and Contact Information
- Full Name: Zheng Yuting
- Email Address: 05ZYT30@xxxxxxxxx
- 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@xxxxxxxxx/
[4] https://lore.kernel.org/git/CAMvj1+rbYKFNeWEvvN76MTpzfuWc4TN4ViXRE4nTfWy7ZMspWg@xxxxxxxxxxxxxx/
[5] https://lore.kernel.org/git/20250403154404.3459805-1-05ZYT30@xxxxxxxxx/
