On Wed, 2 Apr 2025 at 13:51, Patrick Steinhardt <ps@xxxxxx> 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
