Zheng Yuting <05zyt30@xxxxxxxxx> writes:
> After an initial review of the code and documentation for `git-show-ref`
> and `git-for-each-ref`, I believe the functionality of the `git-refs list`
> subcommand can be categorized into two major types:
>
> 1. **Filtering options**
> - In `git-for-each-ref`:
> - `--count`
> - `--sort=<key>`
I would categorize '--sort' into a third subcategory. Filtering refers
to possible change in the size of the sample set. While sorting is more
of a presentation utility.
> - `--points-at=<object>`
> - `--merged[=<object>]`
> - `--no-merged[=<object>]`
> - `--contains[=<object>]`
> - `--no-contains[=<object>]`
> - `--omit-empty`
> - `--exclude=<pattern>`
> - `--include-root-refs`
> - In `git-show-ref`:
> - `--head`
> - `--branches`
> - `--tags`
> - `--exclude-existing[=<pattern>]`
>
> 2. **Formatting options**
> - In `git-for-each-ref`:
> - `--format=<format>`
> - `--color[=<when>]`
> - `--tcl`
> - `--shell`
> - `--perl`
> - In `git-show-ref`:
> - `--dereference`
> - `--hash`
>
> Additionally, for filtering functionality, the `--ignore-case` option
> from `git-for-each-ref` should be supported across the board.
>
This is indeed a special case which applies to both sorting and
filtering.
> **Note**: The `--verify`, `--quiet` and `--exist` options in
> `git-show-ref` are intended to be implemented as separate
> `git-refs` subcommands and are not within the scope of this
> discussion.
>
>
> ## Implementation Considerations
>
> At this point, I haven't come up with a perfect implementation
> plan, as each approach has some issues:
>
> ### Approach 1:
> `git-refs list` would support both filtering and formatting options,
> meaning it could provide:
> - Filtered output
> - Formatted output
> - Combined filter + format output
>
> However, I see two potential problems with this approach:
> 1. Would it make the `list` subcommand too complex?
You mean complex from the user perspective of having too many options or
from the implementation perspective.
I think from the UX perspective, it is a good time to rethink usage and
need for the options you mentioned above. , for e.g. with '--format', do
we need to have '--tcl', `--shell` and `--perl`?
> 2. The performance could be worse than `git-for-each-ref`.
>
Why would it be worse? The performance difference between
`git-for-each-ref(1)` and `git-show-ref(1)` stem from the formats they
use by default.
$ hyperfine --shell=none --warmup=3 "git for-each-ref" "git show-ref"
Benchmark 1: git for-each-ref
Time (mean ± σ): 4.0 ms ± 0.6 ms [User: 1.9 ms, System: 1.9 ms]
Range (min … max): 3.0 ms … 5.7 ms 680 runs
Benchmark 2: git show-ref
Time (mean ± σ): 2.9 ms ± 0.4 ms [User: 1.2 ms, System: 1.5 ms]
Range (min … max): 2.0 ms … 4.3 ms 909 runs
Summary
git show-ref ran
1.38 ± 0.28 times faster than git for-each-ref
What I found interesting was that changing the format for
'git-for-each-ref(1)' gives it a boost:
$ hyperfine --shell=none --warmup=3 'git for-each-ref
--format="%(objectname) %(refname)"' "git show-ref"
Benchmark 1: git for-each-ref --format="%(objectname) %(refname)"
Time (mean ± σ): 2.4 ms ± 0.3 ms [User: 1.1 ms, System: 1.1 ms]
Range (min … max): 1.7 ms … 3.6 ms 1070 runs
Benchmark 2: git show-ref
Time (mean ± σ): 2.9 ms ± 0.4 ms [User: 1.2 ms, System: 1.5 ms]
Range (min … max): 2.0 ms … 4.5 ms 833 runs
Summary
git for-each-ref --format="%(objectname) %(refname)" ran
1.20 ± 0.23 times faster than git show-ref
> ### Approach 2:
> Split the functionality into two separate subcommands:
> - `git-refs filter`: Handles filtering and filter + format output
> - `git-refs show`: Supports formatting options
>
> For implementation, my initial thought is that `git-refs filter` could
> reuse the formatting options from `git-refs show`. Perhaps this could
> work similarly to how `git-add --patch` and `git-restore --patch`
> share logic, though I haven’t thoroughly reviewed that part of the
> code yet. Would this be a reasonable approach?
>
And what is the expectation that when you want to do both filtering and
formatting, would the user be expected to do `git refs filter | git refs
show`? Generally users want to combine both of these options.
Also wasn't the idea to already implement `git-refs show` as a
standalone which simply shows what value a reference holds (without
derefence)?
> ## Overall Plan
>
> If Approach 2 is preferable, I could start with `git-refs show` since it
> only deals with basic ref listing and formatting. I would then make
> the formatting code more reusable to support `git-refs filter`, which
> would focus solely on filtering.
>
> If Approach 1 is chosen, the implementation plan would remain the
> same, but everything would be handled within a single `git-refs list`
> command.
While I would think Approach 1 is the better option here, I'm also
seeing how it is complex, perhaps a good option to get started would be
to implement a simpler subcommand as a first case? Perhaps the
originally discussed `git refs show`?
>
> I would appreciate any feedback or alternative suggestions on the
> best way to structure this functionality.
>
> Thanks!
Thanks for the proposal!
Karthik
Attachment:
signature.asc
Description: PGP signature
