## 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 introduce 8 new subcommands (list, exists, show, resolve, pack,
update, delete, check-format) under the existing git-refs command to
achieve the following objectives:
- Feature Integration: Consolidate existing reference management
commands under git-refs, while maintaining backward compatibility.
- Feature Enhancement: Introduce recursion depth control for git-refs
resolve.
- Testing & Documentation: Add test cases ensuring consistency and
update relevant documentation.
---
## Implementation Plan
### Command Integration Strategy
#### Design Goals
The project will unify scattered reference management functionalities
under the git-refs subcommand framework, ensuring:
1. Complete Feature Coverage: Each subcommand fully replaces its
corresponding legacy command.
2. Parameter Compatibility: Preserve the semantics and output behavior
of legacy command options.
3. Code Reusability: Minimize redundancy by sharing underlying modules
(e.g., refs/files-backend.c).
#### Subcommand Mapping
- git-refs list
Replaces git-show-ref and git-for-each-ref, merging reference listing
functionalities with support for formatting (--format), filtering
(--heads, --tags), and sorting (--sort).
- git-refs exists
Replaces git-show-ref --exists, providing reference existence checks
with positive (<ref>) and exclusion-based (--exclude-existing)
verification.
- git-refs show
Replaces git-show-ref --verify, validating reference correctness with
a strict mode (--strict).
- git-refs resolve
Replaces git-symbolic-ref, resolving symbolic references with added
recursion depth control (--max-depth), while retaining deletion (-d)
and quiet mode (-q) options.
- git-refs pack
Replaces git-pack-refs, packing loose references with support for
filtering (--include, --exclude) and automatic cleanup (--prune).
- git-refs update
Replaces git-update-ref, providing transactional reference updates
with batch processing (--stdin) and atomic guarantees.
- git-refs delete
Separates the delete functionality from git-update-ref, ensuring
explicit handling of reference removals with safety checks and batch
operations (--stdin).
- git-refs check-format
Replaces git-check-ref-format, validating reference format with
support for normalized output (--normalize).
#### Implementation Strategy
1. Option Parsing: Each subcommand will reuse the argument parsing
logic from legacy commands (e.g., git-pack-refs --prune).
2. Shared Backend Logic: Calls to common functions in refs/ (e.g.,
reference traversal, locking mechanisms).
3. Error Consistency: Maintain the same error codes and message
formats as legacy commands.
---
### Example: Implementing git-refs pack
#### Functional Implementation
1. Modify builtin/refs.c:
- Add cmd_refs_pack function implementing git-pack-refs logic.
- Update cmd_refs to include pack with
OPT_SUBCOMMAND("pack", &fn, cmd_refs_pack).
- Define REFS_PACK_USAGE:
git refs pack [--all] [--no-prune] [--auto] [--include <pattern>]
[--exclude <pattern>].
2. Register New Subcommand in git.c:
- Add { "refs-pack", cmd_refs_pack }, to the command array.
3. Reuse refs/files-backend.c Logic:
- Ensure cmd_refs_pack calls pack_refs correctly, adjusting as
necessary for new options.
#### Testing Plan
- Test Cases:
Add t/txxx-refs-pack.sh, leveraging t/t0601-reffiles-pack-refs.sh
scenarios to verify:
- --prune removes obsolete references correctly.
- --include and --exclude apply filtering as expected.
- Packed references match legacy command outputs (diff .git/packed-refs).
- Performance Benchmarking (if needed):
Add performance tests in t/perf to ensure no significant regression
in execution time or memory usage.
#### Documentation Updates
- User Manual:
Add a pack section to Documentation/git-refs.txt, mapping options to
legacy command equivalents.
- Developer Notes:
Comment code to highlight functional parity between git-refs pack
and git-pack-refs.
---
### Timeline
- May 8 - May 11 (4 days): Initial Testing & Subcommand Framework Setup
- May 12 - May 28 (17 days): pack Subcommand Implementation
- May 29 - June 14 (17 days): check-format Subcommand Development
- June 15 - July 5 (21 days): update and delete Subcommands Development
- July 6 - July 26 (21 days): show and exists Subcommands Development
- July 27 - August 16 (21 days): resolve Subcommand Implementation
- August 17 - September 6 (21 days): list Subcommand Implementation
- September 7 - September 16 (10 days): Mid-term Review
- September 17 - September 23 (7 days): Mentor Review & Final 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 optimizing
send-email functionality in Git[3], giving me insights into the Git
codebase.
## 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/
