Hi everyone,
Following the initial discussion, I’ve updated the design for the
`git-refs list` subcommand. Below are the key changes and a
discussion about subcommand options.
### `git-refs list implement plan`
1. Output Format:
The default output format now follows the `git-show-ref` style:
`<oid> SP <ref> LF`. This avoids dependency on ODB and aligns with
lightweight ref listing.
2. Option Categorization:
The functionality is now divided into three distinct types of options
(filter, sort, format) that can be combined:
2.1. **Filtering options**
- In `git-for-each-ref`:
- `--count`
- `--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.2. **Sorting options**
- In `git-for-each-ref`:
- `--sort=<key>`
2.3. **Formatting options**
- In `git-for-each-ref`:
- `--format=<format>`
- `--color[=<when>]`
- `--tcl`
- `--shell`
- `--perl`
- In `git-show-ref`:
- `--dereference`
- `--hash`
Additionally, for filtering and sorting 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.
3. Implementation Approach:
> ### Approach 1:
> `git-refs list` would support both filtering and formatting options,
> meaning it could provide:
> - Filtered output
> - Formatted output
> - Combined filter + format output
>
I will proceed with Approach 1 by implementing `git-refs list` as a
single subcommand that combines filtering, sorting, and formatting
capabilities. To establish a foundation for this, I will first develop
`git-refs show` as a standalone subcommand to replace
`git-show-ref --verify`. The `git-refs list` functionality will then be built
on top of the `git-refs show` codebase."
## Discussion About Options
1. Legacy Formatting Options:
Should `--tcl`, `--shell`, `--perl` be retained?
2. New Options:
Have you used these legacy options or needed modern alternatives?
Any pain points?
I would appreciate any feedback or alternative suggestions on the
best way to structure this functionality.
Thanks!
Zheng Yuting
