From: Zheng Yuting <05zyt30@gmail.com>
Date: Thu, 03 Apr 2025 15:44:04 GMT
Subject: Discussion on git-refs list Implementation and Possible Approaches
Message-ID: <20250403154404.3459805-1-05ZYT30@gmail.com>
In-Reply-To: <20250329150248.2274482-1-05ZYT30@gmail.com>

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

**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?
2. The performance could be worse than `git-for-each-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?

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

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

Thanks!