Re: [GSoC][Proposal RFC] Consolidate ref-related functionality into git-refs

[Meet Soni <meetsoni3017@gmail.com>]

On Wed, 2 Apr 2025 at 13:51, Patrick Steinhardt <ps@pks.im> wrote:
>
> On Tue, Apr 01, 2025 at 07:07:21AM +0530, Meet Soni wrote:
[snip]
> > The Plan:
> > ---------
> > To tackle this project, the consolidation of each command will be divided into
> > the following steps:
> >
> >     1. Create subcommands:
> >       Develop the actual subcommand under  the refs
> > command(builtin/refs file) by
> >       leveraging core functions from the refs module. The implementation will
> >       mimic the logic of the legacy commands to maintain consistency
> > with existing
> >       behavior.
>
> It should mimic existing commands where it makes sense indeed, but we
> should also consider whether there is opportunity for improvement. That
> is of course a harder question to answer, but I'm sure that we will find
> some subcommands where it would make sense to break with existing
> behaviour.
>
Makes sense. I'll reflect this in the upcoming version.

> >     2. Tests:
> >       Develop comprehensive tests to verify that the new subcommands function as
> >       expected. This will involve creating a range of tests, including shell
> >       scripts and/or unit tests located in the t/ directory. For the existing
> >       tests covering the legacy commands targeted for consolidation, the plan is
> >       to retain them initially—even if this results in some duplication—with the
> >       intention of deprecating them gradually over time.
> >     3. Update old usage:
> >       Modify all call sites of the legacy commands to invoke the newly created
> >       subcommands, ensuring a smooth transition and seamless integration with
> >       the consolidated command.
>
> This would be nice indeed, but it's not necessary as part of the GSoC
> project from my point of view. The old commands won't go away anytime
> soon as they are extensively used in scripts outside of our control.
>
I wonder if this is a better candidate for "Post GSoC" section maybe?

> >     4. Documentation:
> >       Develop comprehensive documentation for the newly implemented
> > subcommands to
> >       ensure clear guidance for users and maintainers.
> >
> >
> > Command mapping and naming:
> > ---------------------------
> >
> > I have taken reference for potential names for these subcommands from Patrick’s
> > suggestion (https://gitlab.com/gitlab-org/git/-/issues/330):
> >
> >   # Replaces git-show-ref(1) and git-for-each-ref(1).
> >   $ git refs list
> >
> >   # Replaces `git show-ref --exists`.
> >   $ git refs exist
> >
> >   # Replaces `git show-ref --verify <ref>`.
> >   $ git refs show
> >
> >   # Replaces git-symbolic-ref(1) to show a ref.
> >   $ git refs resolve
> >
> >   # Replaces git-pack-ref(1).
> >   $ git refs pack
>
> As I suggested elsewhere already, I think `git refs optimize` would be a
> better name. The verb "packing" mostly stems from the "files" backend,
> where loose files are indeed moved into a "packed-refs" file. But with
> the "reftable" backend that name makes less sense.
>
> >   # Replaces git-update-ref(1).
> >   $ git refs write
> >
> >   # Replaces git-check-ref-format(1).
> >   $ git refs check-format
>
> I think this one could be improved, as well, as it doesn't quite
> indicate what format you're checking. "check-name" might be a better
> fit.
>
Yeah, makes sense; I'll reflect this in the upcoming version.

> [snip]
> > Options/Config sharing:
> > -----------------------
> > For sharing configuration options, I propose a structure-based approach that
> > centralizes common options while grouping subcommand-specific settings into
> > dedicated substructures. This design embeds common options directly in the
> > top-level configuration structure (struct refs_options), and then uses separate
> > structures (such as struct list_options) to encapsulate options unique to each
> > subcommand.
> >
> > Below is a representative code snippet illustrating this approach:
> >
> > struct refs_options {
> >         ...
> >         // ... Common Options …
> >
> >         struct list_options list_opts;
> >              struct exist_options exist_opts;
> >
> >         // ... Similar fields for other subcommands ...
> >         ...
> > };
>
> The other structures probably do make sense, but I don't think it makes
> sense to have a structure that summarizes all of them. If there are
> common options that will need handling for all of the subcommands (are
> there?) then I'd rather go the other way round and introduce a
> `refs_common_options` structure that gets embedded in e.g.
> `list_options`.
>
Okay. I'll update this in the upcoming version.
In terms of common options, there are a few that come to mind--such as
--quiet, -m, and --branch.
> > struct list_options {
> >      // ... options specific to 'list' subcommand ...
> > };
> >
> >
> > struct exist_options {
> >      // ... options specific to 'exist' subcommand ...
> > };
> >
> >
> > Since we plan to maintain the legacy commands for the foreseeable future, we
> > must ensure backward compatibility while developing these new subcommands. Going
> > through this I wonder if we should make the commands as a standalone
> > entity, like
> > a library. However, it needs to be thoroughly discussed.
>
> Much of the functionality probably already is somewhat encapsulated,
> it's mostly the option handling that we'll have to unify somehow. In any
> case I expect that the exact mechanism will vary between the different
> subcommands and it's fine to decide on a case-by-case basis once you
> start to implement them.
>
> > While studying these commands, I thought why not try out one of them to better
> > understand the project’s requirements, scope and get a firmer grip on the
> > codebase. So, I developed a reference implementation of git refs list that
> > mimics the behaviour of git show-ref with [--head], [--branches|--heads] and
> > [--tag] flags, which can be found (https://github.com/inosmeet/git/pull/1).
> >
> > Although this reference implementation is still a work in progress and not yet
> > ready for merging into master, it demonstrates my understanding of navigating
> > the Git codebase and the process of creating commands and subcommands. More
> > importantly, it indicates my ability to execute this project effectively.
>
> Nice :)
>
> > Timeline:
> > ---------
> > Pre-GSoC (Until May 8):
> > * Continue to work on different things like the pending WIP patch that I have.
> >   Be engaged/involved in the community.
> >
> > Community Bonding (May 8 - June 1):
> > * Talk with mentors and discuss potential names for the new subcommands and
> >   interface design. Start the consolidation early with mentors’ permission.
> >
> > Phase I (June 2 - 29 June):
> > * Consolidate update-ref command along with subcommands/flags to refs… command.
> >
> > Phase II (30 June - 27 July):
> > * Consolidate for-each-ref command along with subcommands/flags to refs…
> >   command.
> >
> > Phase III (28 July - 24 August):
> > * Consolidate show-ref and pack-refs command along with their subcommands/flags
> >   to refs… command.
>
> Part of what git-show-ref(1) does is also covered by
> git-for-each-ref(1). So it would probably make sense to implement those
> two parts in a specific phase, but single out the non-shared parts (e.g.
> the `--exists` flag) into a separate phase.
>
> Also, given that you've already started to work on git-show-ref(1) a
> bit, wouldn't it make sense to move that to phase I?
>
Both of these suggestions make sense. I'll update this :)
> > Final Week:
> > * Some final touches. Make a final report about the work accomplished and
> >   outline future work.
> >
> > I have not allocated separate timeline slots for tests and documentation, as
> > these will be integrated into the patches that introduce the new subcommands.
> >
> > I think if permitted to start early, I can consolidate one more command within
> > the GSoC period.
>
> We cannot keep you from doing this, but please keep in mind that if we
> end up picking a different candidate for this project we would favor
> their work so that they can successfully finish GSoC. So I would
> definitely wait until you've been selected before starting to work on
> anything.
>
I completely understand. Just to clarify, I meant that if I'm fortunate enough
to be selected, I’d be eager to start contributing during the community
bonding period--only if it's allowed--so that I can try to consolidate one more
command within the GSoC period.

> Thanks for your interest!
>
> Patrick

Thank you for reviewing :)
Meet