Subject: Re: [PATCH v4 1/2] revision.c: implement -b-reverse=before for walks

From: Mirko Faina <[email-masked]>
Date: Mon, 27 Apr 2026 18:48:56 +0200

On Mon, Apr 27, 2026 at 03:45:34PM +0900, Junio C Hamano wrote:
> > In a revision walk `--reverse` can only be applied after any commit
> > limiting option. This makes getting a limited amount of commits from the
> > tail impossible. E.g.
> >
> >     git log --reverse --max-count=3
> 
> Can we rephrase "from the tail" somehow to reduce ambiguity?
> 
> Normally we generate a list of commits from newer to older, and you
> are saying that it is not possible to take the oldest three commits
> and show them from older to newer (i.e., in reverse).  But that, to
> some readers, is showing commits from the beginning end, not from
> the tail end.
> 
> Perhaps "... limited number of oldest commits impossible"?

Yes, will rephrase.

> > Teach `get_revision()` to accpet an argument `(after|before)` from the
> > CLI, and apply the reversal before or after the commit limiting options
> > based on this argument.
> 
> I think "after" and "before" comes from "Do other things (including
> count limiting) and then apply reverse after all that" and would be
> very much understandable to those who know how the machinery works,
> but should mere mortals need to know the machinery only to use "git
> log"?

No, they shouldn't, but...

> To put it another way, do you tnink experienced Git users who
> haven't seen the actual implementation of revision traversal can
> immediately answer this question:
> 
>     Now we have --reverse=after and --reverse=before to let you take
>     a limited history from both ends when used with --max-count.
>     Which between after and before do you think corresponds to the
>     traditional --reverse that allowed you to only see the newest
>     part of the history?

...while users might not have read the implementation (and they
shouldn't need to to use log) the order in which the class of options is
applied is already documented in the man pages, so having that knowledge
after and before do make sense despite not having seen the
implementation.

But...

> I doubt that the population to answer correctly would not exceed a
> half by large margin (if it is 50% then it means nobody understood
> the difference correctly and they just flipped a coin).
> 
> I wonder --reverse=oldest and --reverse=newest is easier to teach
> and explain?  I dunno.

...you're right, it is not immediately apparent, but neither are oldest
and newest. Unfortunately I don't think there's any name we can choose
that would make it so without having to read the caveats in the man
pages.

Since many have expressed that this issue is not really about reverse
but about max-count, like you initially assesed, then we should move
towards making changes to the max-count option.

The proposed --max-count-oldest doesn't seem right to me as
max-count-oldest is not about keeping the oldest commits (even tho
that's what we want to achieve when we interact with reverse) but about
when we want to apply max-count. Since [1],

> It might be that the right way to look at this new feature is not that
> "we are changing where reverse is applied", but "count limit is applied
> much later than usual"

maybe --max-count-later as in max count is being applied later than
usual? (either way the users will still need to reach for the man pages
for clarifications).

[1] https://lore.kernel.org/git/[email-masked]/