git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Discussion on git-refs list Implementation and Possible Approaches

From
Zheng Yuting <05zyt30@gmail.com>
Date
Apr 3, 2025, 15:44 UTC
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!
Previous: Patrick SteinhardtNext: Karthik Nayak
Message 10 of 17 in “[GSoC] Proposal Discussion: git-refs Project”
  1. Yuting ZhengMar 23, 2025
  2. Patrick SteinhardtMar 24, 2025
  3. Yuting ZhengMar 27, 2025
  4. shejialuoMar 28, 2025
  5. Yuting ZhengMar 29, 2025
  6. [GSoC] git-refs proposal draftZheng Yuting, Mar 29, 2025
  7. Patrick SteinhardtMar 31, 2025
  8. Yuting ZhengApr 1, 2025
  9. Patrick SteinhardtApr 2, 2025
  10. Discussion on git-refs list Implementation and Possible ApproachesZheng Yuting, Apr 3, 2025
  11. Karthik NayakApr 4, 2025
  12. Yuting ZhengApr 4, 2025
  13. Patrick SteinhardtApr 4, 2025
  14. Yuting ZhengApr 4, 2025
  15. Yuting ZhengApr 4, 2025
  16. [GSoC] git-refs proposal v2Yuting Zheng, Apr 6, 2025
  17. Fwd: Discussion on git-refs list Implementation and Possible ApproachesYuting Zheng, Apr 4, 2025

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.