Re: [GSoC] git-refs proposal draft
On Sat, Mar 29, 2025 at 11:02:46PM +0800, Zheng Yuting wrote:
Show 18 quoted lines
> ## 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.
Show 22 quoted lines
> - 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.
Show 9 quoted lines
> 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.
Show 7 quoted lines
> - 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.
Show 15 quoted lines
> ---
>
> ### 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.
Show 34 quoted lines
> #### 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
Yuting Zheng
