From: Yuting Zheng <05zyt30@gmail.com>
Date: Fri, 04 Apr 2025 15:16:42 GMT
Subject: Re: Discussion on git-refs list Implementation and Possible Approaches
Message-ID: <CAMvj1+qx8DgNp7kp==YNT6eTmmdA-zyNuYRuEovk5L+eqGw8xQ@mail.gmail.com>
In-Reply-To: <20250403154404.3459805-1-05ZYT30@gmail.com>

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