Re: [PATCH] rev-list-options: clarify the usage of -n/--max-number

Pranit Bauva <pranit.bauva@gmail.com> writes:

I think it is easier to understand if you updated the description of "--reverse", rather than "-<n>". "rev-list -n $N" that stops after showing $N commits is something everybody understands. What often dissapoints some users is that "--reverse" kicks in _after_ what commits are to be shown are decided.

These essentially say the same thing. The original does not mention where and how <number> is used, but "Limit the number of commits" as a description for "-<number>" would be understood by anybody halfway intelligent that the given number is used as that limit, so I do not think an updated description is making it easier to understand.

There is a paragraph of interest in an earlier part of "Commit Limiting" section (which is the section "-n" appears in, among other options):

    Note that these are applied before commit
    ordering and formatting options, such as `--reverse`.

So the documentation already makes an attempt to avoid confusion Ruediger saw, i.e. "rev-list traverses, limits the output to N, and then shows these N commits in reverse" is what it expects readers to understand, and that it also expects it would lead naturally to "these N commits are still from the newest part of the history, hence 'rev-list --reverse -n N' is not how you grab the earliest N".

But apparently the attempt by the current documentation is not enough. Let's see how it describes the '--reverse' option:

    Commit Ordering
    ~~~~~~~~~~~~~~~

    By default, the commits are shown in reverse chronological order.
    ...

    --reverse::
            Output the commits in reverse order.
            Cannot be combined with `--walk-reflogs`.

Perhaps "Output the commits chosen to be shown (see Commit Limiting section above) in reverse order." would make it clearer?