Subject: Re: [PATCH v3 4/4] for-each-ref: introduce a '--start-after' option

From: Junio C Hamano <[email-masked]>
Date: Tue, 08 Jul 2025 13:25:11 -0700

Karthik Nayak <[email-masked]> writes:

> 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.
>
> The previous commit added 'seek' functionality to the reference
> backends. Utilize this and expose a '--start-after' option in
> 'git-for-each-ref(1)'. When used, the reference iteration seeks to the
> lexicographically next reference and iterates from there onward.
>
> This enables efficient pagination workflows like:
>     git for-each-ref --count=100
>     git for-each-ref --count=100 --start-after=refs/heads/branch-100
>     git for-each-ref --count=100 --start-after=refs/heads/branch-200

It is a bit hard to understand how this leads to "efficient
pagination" unless the reader is told what the calling script does
after the first call before making the second call.  It remembers
the last output from the Nth call and prepares the N+1th call by
using that last output entry.

But that probably belongs to the end-user facing documentation, not
in the log message.

> +--start-after::

`--start-after=<marker>`::

> +    Allows paginating the output by skipping references up to and including the
> +    specified marker. When paging, it should be noted that references may be
> +    deleted, modified or added between invocations. Output will only yield those
> +    references which follow the marker lexicographically. If the marker does not
> +    exist, output begins from the first reference that would come after it
> +    alphabetically.

It is true that the first entry shown would be what would come
immediately _after_ the given <marker>, whether the marker does or
does not exist.  So "If the marker does not exist, output begins..."
-> "Output begins ..."

Other than that, looked pretty good to me.

Thanks, will queue.