Re: Discussion on git-refs list Implementation and Possible Approaches

From: Karthik Nayak <karthik.188@gmail.com>
Date: Apr 4, 2025, 11:08 UTC
Message-ID: <CAOLa=ZTTPuNyaE5Z-bfkQougmKQSrRZZwLaxJUL7mdmj8uHoFw@mail.gmail.com>
In-Reply-To: <20250403154404.3459805-1-05ZYT30@gmail.com>

Zheng Yuting <05zyt30@gmail.com> writes:

Show 8 quoted lines

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

Show 28 quoted lines

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

Show 20 quoted lines

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

Show 11 quoted lines

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

Show 10 quoted lines

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

Show 5 quoted lines

>
> I would appreciate any feedback or alternative suggestions on the
> best way to structure this functionality.
>
> Thanks!

Thanks for the proposal! Karthik