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!
