The `git-for-each-ref(1)` command is used to iterate over references
present in a repository. In large repositories with millions of
references, it would be optimal to paginate this output such that we
can start iteration from a given reference. This would avoid having to
iterate over all references from the beginning each time when paginating
through results.
This series adds a '--skip-until' option in 'git-for-each-ref(1)'. When
used, the reference iteration seeks to the first matching reference and
iterates from there onward.
This enables efficient pagination workflows like:
git for-each-ref --count=100
git for-each-ref --count=100 --skip-until=refs/heads/branch-100
git for-each-ref --count=100 --skip-until=refs/heads/branch-200
To add this functionality, we expose the `ref_iterator` outside the
'refs/' namespace and modify the `ref_iterator_seek()` to actually seek
to a given reference and only set the prefix when the `set_prefix` field
is set.
On the reftable and packed backend, the changes are simple. But since
the files backend uses 'ref-cache' for reference handling, the changes
there are a little more involved, since we need to setup the right
levels and the indexing.
Initally I was also planning to cleanup all the `refs_for_each...()`
functions in 'refs.h' by simply using the iterator, but this bloated the
series. So I've left that for another day.
Signed-off-by: Karthik Nayak <karthik.188@xxxxxxxxx>
---
Documentation/git-for-each-ref.adoc | 6 +-
builtin/for-each-ref.c | 5 +
ref-filter.c | 57 ++++++++----
ref-filter.h | 1 +
refs.c | 2 +-
refs.h | 153 ++++++++++++++++++++++++++++++
refs/debug.c | 7 +-
refs/files-backend.c | 7 +-
refs/iterator.c | 24 +++--
refs/packed-backend.c | 15 +--
refs/ref-cache.c | 95 +++++++++++++++----
refs/ref-cache.h | 7 --
refs/refs-internal.h | 152 ++----------------------------
refs/reftable-backend.c | 17 ++--
t/t6302-for-each-ref-filter.sh | 180 ++++++++++++++++++++++++++++++++++++
15 files changed, 507 insertions(+), 221 deletions(-)
Karthik Nayak (4):
refs: expose `ref_iterator` via 'refs.h'
ref-cache: remove unused function 'find_ref_entry()'
refs: selectively set prefix in the seek functions
for-each-ref: introduce a '--skip-until' option
base-commit: cf6f63ea6bf35173e02e18bdc6a4ba41288acff9
change-id: 20250605-306-git-for-each-ref-pagination-0ba8a29ae646
Thanks
- Karthik
