On Sat, Mar 29, 2025 at 11:02:46PM +0800, Zheng Yuting wrote:

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

I have a couple of opinions on the exact naming of the subcommands, more
on that below.

In any case, I don't think the naming and how exactly each of these
commands should look and work like needs to be hashed out in this
document. It's nice to scope out _what_ we want to achieve and propose
how this could look like, but ultimately I think that most of the design
should happen during the project itself.

- 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.

This one is something that is up for debate. While I do expect that most
of the commands should remain current semantics and options, we could
also use this as an opportunity to think whether there are any issues
with the current design and improve upon it.

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).

Yup. One thing to note is that git-show-ref(1) and git-for-each-ref(1)
are very similar, but not quite the same. One should find good arguments
which of the two semantics are preferable to us and why that is.

For example, git-show-ref(1) outperforms git-for-each-ref(1) due to the
default format:

    Benchmark 1: git show-ref
      Time (mean ± σ):      99.0 ms ±   0.5 ms    [User: 55.6 ms, System: 43.0 ms]
      Range (min … max):    98.0 ms … 100.8 ms    100 runs

    Benchmark 2: git for-each-ref
      Time (mean ± σ):     134.0 ms ±   0.6 ms    [User: 82.3 ms, System: 50.8 ms]
      Range (min … max):   132.7 ms … 135.8 ms    100 runs

    Summary
      git show-ref ran
        1.35 ± 0.01 times faster than git for-each-ref

- git-refs exists
  Replaces git-show-ref --exists, providing reference existence checks
  with positive (<ref>) and exclusion-based (--exclude-existing)
  verification.

I'm not quite clear what exclusion-based existence checks is. How do you
check whether something exists when you exclude it? I don't think that
this option is relevant in the context of `git refs exists`.

- git-refs show
  Replaces git-show-ref --verify, validating reference correctness with
  a strict mode (--strict).

Yup. In contrast to `git refs resolve` this command shouldn't resolve
the ref, but directly show what it's pointing to. And this should be
true for both symbolic and normal refs.

- 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.

Not quite. The difference to `git refs show` is that this command always
resolves the ref to an object. So it's rather more similar to `git
rev-parse --verify`, except that it only ever handles references.

- git-refs pack
  Replaces git-pack-refs, packing loose references with support for
  filtering (--include, --exclude) and automatic cleanup (--prune).

I would probably call this `git refs optimize` or something like that.
git-pack-refs(1) is mostly called this way because it was introduced to
pack refs into the "packed-refs" file. But nowadays with the reftable
backend I think that the command name is somewhat inaccurate.

- 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).

It's up for debate whether we should even have something like `git refs
delete`. As you rightfully notice `git refs update` already handles the
usecase, so it feels like needless duplication.

- git-refs check-format
  Replaces git-check-ref-format, validating reference format with
  support for normalized output (--normalize).

Ah, nice, this is a command I forgot about.

#### Implementation Strategy

1. Option Parsing: Each subcommand will reuse the argument parsing
   logic from legacy commands (e.g., git-pack-refs --prune).

We cannot and do not want to do this for every case. As mentioned above,
we may want to iterate on some of the subcommands to address historic
warts. But overall I agree, we should of course aim to reduce
duplication as far as it is sensible to do.

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.

Same reasoning here, we may want to adapt some of them. The old commands
won't go away as they are used everywhere, and that makes it more
reasonable for us to change behaviour in their newer equivalents.

---

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

You don't actually have to change "git.c" to introduce new subcommands.
We don't want `git refs-pack`, but rather `git refs pack`, which is an
important distinction.

3. Reuse refs/files-backend.c Logic:
   - Ensure cmd_refs_pack calls pack_refs correctly, adjusting as
     necessary for new options.

We shouldn't have to touch any of the backends at all. You should rather
make sure to integrate with "refs.c", which wraps the backends and
provides a backend-agnostic interface to refs.

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

You probably underestimate the time to review and land a specific change
quite significantly. Landing new features in ~2 weeks is thus not quite
realistic and you should allocate a lot more time for each of the
specific subcommands.

That of course raises the question of how to squeeze all of the
subcommands into a single GSoC. And the answer is that you don't: it's
perfectly fine to implement only a subset of the new proposed
subcommands. I'd rather you spend more time thinking about how to
improve upon the status quo for each of the subcommands and thus spend
more time on it than trying to do everything in a hurry.

So: there isn't any expectation that you manage to implement all of
them. I'd recommend to pick a subset of commands that you want to
implement as a realistic goal. You may define other commands as a
stretch goal in case you manage to speed through the implementation way
faster than I anticipate.

Thanks!

Patrick