question about git rev-list --max-count=n

question about git rev-list --max-count=n

[Ruediger Meier]

Hi,

git rev-list --max-count=n

seems to always list the _last_ (newest) n commits. Is there any 
functionality to list the _first_ n commits?

I've tried to add --reverse hoping that this would do it but it does 
not.

The manual could be a bit more clear about that:
    --max-count=<number>   Limit the number of commits to output.


If it really would only limit the _output_ (like head -n), then 
IMO --reverse should do what I want.


Regarding my initial question. Maybe we could support
   --max-count=-n
to list the first n commits.

cu,
Rudi
  

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

[Pranit Bauva]

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

Reported-by: Ruediger Meier <sweet_f_a@gmx.de>
Signed-off-by: Pranit Bauva <pranit.bauva@gmail.com>

---
Hey Ruegiger,

The description is a bit inappropriate for --max-count and thus this
patch.

I cannot comment whether --max-count=-n would be a good choice or not
because personally I never left the need of it. I normally use --reverse
so as to review my patches in a branch serially. So for me the current
usage of --reverse seems more appropriate.
---
 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>.
 
 --skip=<number>::
 	Skip 'number' commits before starting to show the commit output.

--
https://github.com/git/git/pull/296

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

[Junio C Hamano]

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?

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

[Pranit Bauva]

Hey Junio,

On Tue, Sep 27, 2016 at 10:21 PM, Junio C Hamano <gitster@pobox.com> wrote:
> 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.

True.

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

To clear out that confused I used the word "last" but I can now
understand that it can be easily misunderstood.

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

It surely does :)

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

That would be a much better edit. Thanks! Will send out a re-roll.

Regards,
Pranit Bauva

[PATCH v2] rev-list-options: clarify the usage of --reverse

[Pranit Bauva]

Specify even more clearly that --reverse works only with the commits
which are chosen to be shown so as to eliminate the confusion as to
whether the first n or the last n commits with be shown when used
with `-n --reverse`.

Reported-by: Ruediger Meier <sweet_f_a@gmx.de>
Signed-off-by: Pranit Bauva <pranit.bauva@gmail.com>
---
 Documentation/rev-list-options.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 7e462d3..5da7cf5 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -657,8 +657,9 @@ avoid showing the commits from two parallel development track mixed
 together.
 
 --reverse::
-	Output the commits in reverse order.
-	Cannot be combined with `--walk-reflogs`.
+	Output the commits chosen to be shown (see Commit Limiting
+	section above) in reverse order. Cannot be combined with
+	`--walk-reflogs`.
 
 Object Traversal
 ~~~~~~~~~~~~~~~~

--
https://github.com/git/git/pull/296

Re: [PATCH v2] rev-list-options: clarify the usage of --reverse

[Philip Oakley]

From: "Pranit Bauva" <pranit.bauva@gmail.com>
> Specify even more clearly that --reverse works only with the commits
> which are chosen to be shown so as to eliminate the confusion as to
> whether the first n or the last n commits with be shown when used

hi Pranit,
micro-nit: 'first' and 'last' can be tricky to distinguish for lists (e.g. 
of commits) that can be considered from both ends with equal ease (people 
are so easily confused ;-). In such cases its always worth stating the sort 
order mechanism (within the appropriate sentence). However, in this case the 
clarification is to clearly point elsewhere, so I'm OK with the patch.

> with `-n --reverse`.
>
> Reported-by: Ruediger Meier <sweet_f_a@gmx.de>
> Signed-off-by: Pranit Bauva <pranit.bauva@gmail.com>
> ---
> Documentation/rev-list-options.txt | 5 +++--
> 1 file changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/rev-list-options.txt 
> b/Documentation/rev-list-options.txt
> index 7e462d3..5da7cf5 100644
> --- a/Documentation/rev-list-options.txt
> +++ b/Documentation/rev-list-options.txt
> @@ -657,8 +657,9 @@ avoid showing the commits from two parallel 
> development track mixed
> together.
>
> --reverse::
> - Output the commits in reverse order.
> - Cannot be combined with `--walk-reflogs`.
> + Output the commits chosen to be shown (see Commit Limiting
> + section above) in reverse order. Cannot be combined with
> + `--walk-reflogs`.
>
> Object Traversal
> ~~~~~~~~~~~~~~~~
>
> --
> https://github.com/git/git/pull/296
>
--
Philip 

Re: [PATCH v2] rev-list-options: clarify the usage of --reverse

[Junio C Hamano]

"Philip Oakley" <philipoakley@iee.org> writes:

> micro-nit: 'first' and 'last' can be tricky to distinguish for lists...

Let's do this then.

-- >8 --
From: Pranit Bauva <pranit.bauva@gmail.com>
Date: Tue, 27 Sep 2016 20:44:09 +0000
Subject: [PATCH] rev-list-options: clarify the usage of --reverse

Users often wonder if the oldest or the newest n commits are shown
by `log -n --reverse`.  Clarify that --reverse kicks in only after
deciding which commits are to be shown to unconfuse them.

Reported-by: Ruediger Meier <sweet_f_a@gmx.de>
Signed-off-by: Pranit Bauva <pranit.bauva@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/rev-list-options.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 4f009d4..f8946d4 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -638,8 +638,9 @@ avoid showing the commits from two parallel development track mixed
 together.
 
 --reverse::
-	Output the commits in reverse order.
-	Cannot be combined with `--walk-reflogs`.
+	Output the commits chosen to be shown (see Commit Limiting
+	section above) in reverse order. Cannot be combined with
+	`--walk-reflogs`.
 
 Object Traversal
 ~~~~~~~~~~~~~~~~
-- 
2.10.0-561-g98a6b79

Re: [PATCH v2] rev-list-options: clarify the usage of --reverse

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> micro-nit: 'first' and 'last' can be tricky to distinguish for lists...
>
> Let's do this then.

Looks good to me. Thanks. -- Philip

>
> -- >8 --
> From: Pranit Bauva <pranit.bauva@gmail.com>
> Date: Tue, 27 Sep 2016 20:44:09 +0000
> Subject: [PATCH] rev-list-options: clarify the usage of --reverse
>
> Users often wonder if the oldest or the newest n commits are shown
> by `log -n --reverse`.  Clarify that --reverse kicks in only after
> deciding which commits are to be shown to unconfuse them.
>
> Reported-by: Ruediger Meier <sweet_f_a@gmx.de>
> Signed-off-by: Pranit Bauva <pranit.bauva@gmail.com>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> Documentation/rev-list-options.txt | 5 +++--
> 1 file changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/rev-list-options.txt 
> b/Documentation/rev-list-options.txt
> index 4f009d4..f8946d4 100644
> --- a/Documentation/rev-list-options.txt
> +++ b/Documentation/rev-list-options.txt
> @@ -638,8 +638,9 @@ avoid showing the commits from two parallel 
> development track mixed
> together.
>
> --reverse::
> - Output the commits in reverse order.
> - Cannot be combined with `--walk-reflogs`.
> + Output the commits chosen to be shown (see Commit Limiting
> + section above) in reverse order. Cannot be combined with
> + `--walk-reflogs`.
>
> Object Traversal
> ~~~~~~~~~~~~~~~~
> -- 
> 2.10.0-561-g98a6b79
>
> 

Re: [PATCH v2] rev-list-options: clarify the usage of --reverse

[Pranit Bauva]

Hey Junio,

On Wed, Sep 28, 2016 at 3:42 AM, Junio C Hamano <gitster@pobox.com> wrote:
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> micro-nit: 'first' and 'last' can be tricky to distinguish for lists...
>
> Let's do this then.
>
> -- >8 --
> From: Pranit Bauva <pranit.bauva@gmail.com>
> Date: Tue, 27 Sep 2016 20:44:09 +0000
> Subject: [PATCH] rev-list-options: clarify the usage of --reverse
>
> Users often wonder if the oldest or the newest n commits are shown
> by `log -n --reverse`.  Clarify that --reverse kicks in only after
> deciding which commits are to be shown to unconfuse them.
>
> Reported-by: Ruediger Meier <sweet_f_a@gmx.de>
> Signed-off-by: Pranit Bauva <pranit.bauva@gmail.com>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---

Looks good! Thanks!

>  Documentation/rev-list-options.txt | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
> index 4f009d4..f8946d4 100644
> --- a/Documentation/rev-list-options.txt
> +++ b/Documentation/rev-list-options.txt
> @@ -638,8 +638,9 @@ avoid showing the commits from two parallel development track mixed
>  together.
>
>  --reverse::
> -       Output the commits in reverse order.
> -       Cannot be combined with `--walk-reflogs`.
> +       Output the commits chosen to be shown (see Commit Limiting
> +       section above) in reverse order. Cannot be combined with
> +       `--walk-reflogs`.
>
>  Object Traversal
>  ~~~~~~~~~~~~~~~~
> --
> 2.10.0-561-g98a6b79
>