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

[Jeff King <peff@peff.net>]

On Wed, Apr 22, 2026 at 02:28:40AM +0200, Mirko Faina wrote:

> diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc
> index 2d195a1474..7244e85108 100644
> --- a/Documentation/rev-list-options.adoc
> +++ b/Documentation/rev-list-options.adoc
> @@ -914,10 +914,16 @@ With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
>  avoid showing the commits from two parallel development track mixed
>  together.
>  
> -`--reverse`::
> -	Output the commits chosen to be shown (see 'Commit Limiting'
> -	section above) in reverse order. Cannot be combined with
> -	`--walk-reflogs`.
> +`--[no-]reverse[=(after|before)]`::
> +	Accepts `after` or `before`. Cannot be combined with
> +	`--walk-reflogs`. If `after`, output the commits chosen to be
> +	shown (see 'Commit Limiting' section above) in reverse order. If
> +	`before`, reverse the commits before filtering with `Commit
> +	Limiting` options. This option can be used multiple times, last
> +	one is applied. When the argument for `--reverse` is omitted, if
> +	the current state is in no reverse, it defaults to `after`. If
> +	it is in any reversed state, it restores the original ordering
> +	by removing the reverse state.

I think this is all correct, but I found the final sentences a bit hard
to follow (especially the phrase "reversed state"). Let me take a stab
at it.

  When multiple `--reverse=` options are given, the final option
  overrides any previous options. The `--reverse` option (with no
  specifier) behaves as `--reverse=after`, except that for historical
  reasons it negates any previous reversed state (so `--reverse
  --reverse` does nothing, nor does `--reverse=before --reverse`).

I dunno if that is any better, really. I hoped by mentioning "historical
reasons" that excuses any weirdness, and readers interested in sane
behavior can stop reading. ;)

So anyway, I offer it in case you find it useful or can pick out useful
bits from it.

-Peff