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

From: Mirko Faina <mroik@delayed.space>
Date: Apr 27, 2026, 16:48 UTC
Message-ID: <ae-J4ooz2PJ8bZAq@exploit>
In-Reply-To: <xmqq8qa852b5.fsf@gitster.g>

On Mon, Apr 27, 2026 at 03:45:34PM +0900, Junio C Hamano wrote:

Show 15 quoted lines

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

Show 9 quoted lines

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

Show 9 quoted lines

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

Show 6 quoted lines

> 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/xmqqv7dlr4yz.fsf@gitster.g/