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

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 8, 2025, 20:25 UTC
Message-ID: <xmqq4ivmv3a0.fsf@gitster.g>
In-Reply-To: <20250708-306-git-for-each-ref-pagination-v3-4-8cfba1080be4@gmail.com>

Karthik Nayak <karthik.188@gmail.com> writes:

Show 16 quoted lines

> 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>`::

Show 6 quoted lines

> +    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.