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

> Pranit Bauva <pranit.bauva@gmail.com> writes:
>
>> -n=<number>, -<number>, --max-number=<number> shows the last n commits
>> specified in <number> irrespective of whether --reverse is used or not.
>> With --reverse, it just shows the last n commits in reverse order.
>
> 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.

>>  Documentation/rev-list-options.txt | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
>> index 7e462d3..6b7c2e5 100644
>> --- a/Documentation/rev-list-options.txt
>> +++ b/Documentation/rev-list-options.txt
>> @@ -18,7 +18,7 @@ ordering and formatting options, such as `--reverse`.
>>  -<number>::
>>  -n <number>::
>>  --max-count=<number>::
>> -     Limit the number of commits to output.
>> +     Limit to last n number of commits to output specified in <number>.
>
> 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?