[PATCH 00/17] refs: unify `refs_for_each_*()` functions

Hi,

we currently have 14 different `refs_for_each_*()` functions, with each of them doing slightly different things. This makes for a confusing API surface, and because the API is not built for extension we have to add a new function every now and then to handle another esoteric edge case that will ultimately only have at most a handful of callers.

This design isn't really sensible in my opinion, and this patch series aims to fix that. Instead of having a dozen different functions, it introduces a new `refs_for_each_ref_ext()` function that simply takes an options structure as input. From thereon, callers can mix and match the parameters that they care about.

The patch series is structured like this:

  - Patches 1 to 5 introduce some preliminary cleanups.

  - Patches 6 to 9 introduce `refs_for_each_ref_ext()` and move
    more functionality into it. This also fixes a performance bug that
    we have in one of the implementations.

  - Patch 10 adds some more verification for options that would have
    caught the bugs in ps/for-each-ref-in-fixes.

  - The remaining patches drop 7 out of 14 functions and replace them
    with `refs_for_each_ref_ext()`. It results in a bit of churn, so
    while I think this churn is worth it, I consider these patches to be
    optional.

The patch series is built on top of 73fd77805f (The 5th batch, 2026-02-17) with ps/for-each-ref-in-fixes at 6375a00ef1 (bisect: simplify string_list memory handling, 2026-02-19) merged into it.

Thanks!

Patrick

---
Patrick Steinhardt (17):
      refs: move `refs_head_ref_namespaced()`
      refs: move `do_for_each_ref_flags` further up
      refs: rename `do_for_each_ref_flags`
      refs: rename `each_ref_fn`
      refs: remove unused `refs_for_each_include_root_ref()`
      refs: introduce `refs_for_each_ref_ext`
      refs: speed up `refs_for_each_glob_ref_in()`
      refs: generalize `refs_for_each_namespaced_ref()`
      refs: generalize `refs_for_each_fullref_in_prefixes()`
      refs: improve verification for-each-ref options
      refs: replace `refs_for_each_ref_in()`
      refs: replace `refs_for_each_rawref()`
      refs: replace `refs_for_each_rawref_in()`
      refs: replace `refs_for_each_glob_ref_in()`
      refs: replace `refs_for_each_glob_ref()`
      refs: replace `refs_for_each_namespaced_ref()`
      refs: replace `refs_for_each_fullref_in()`

 bisect.c                  |  16 ++-
 builtin/bisect.c          |  34 ++++--
 builtin/describe.c        |   7 +-
 builtin/fetch.c           |   7 +-
 builtin/fsck.c            |   7 +-
 builtin/receive-pack.c    |   8 +-
 builtin/remote.c          |   8 +-
 builtin/rev-parse.c       |  37 ++++---
 builtin/show-ref.c        |  21 ++--
 fetch-pack.c              |  15 ++-
 http-backend.c            |   8 +-
 ls-refs.c                 |  11 +-
 notes.c                   |   7 +-
 pack-bitmap.c             |  15 +--
 pack-bitmap.h             |   2 +-
 ref-filter.c              |  19 ++--
 refs.c                    | 256 ++++++++++++++++++++++------------------------
 refs.h                    | 198 +++++++++++++++++------------------
 refs/files-backend.c      |  19 ++--
 refs/iterator.c           |   2 +-
 refs/packed-backend.c     |   8 +-
 refs/reftable-backend.c   |  10 +-
 revision.c                |  46 ++++++---
 submodule.c               |   2 +-
 t/helper/test-ref-store.c |  15 ++-
 upload-pack.c             |  13 ++-
 worktree.c                |   2 +-
 worktree.h                |   2 +-
 28 files changed, 437 insertions(+), 358 deletions(-)

--- base-commit: dbbe43524e0814c1f93325795ed6aa26eb6e587e change-id: 20260220-pks-refs-for-each-unification-7572c694cfc0