[GSoC] git-refs proposal draft

[Zheng Yuting <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 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@gmail.com/