[PATCH] git-rev-list.txt: rev stands for revision, not reverse.

[PATCH] git-rev-list.txt: rev stands for revision, not reverse.

[Ralf Wildenhues]

Mention revs, revisions as aliases for commit objects,
to clarify that rev-list is not an abbreviation for
listing in reverse order, but for listing revisions.
---
Yes, believe it or not, but I stumbled over the synopsis

| git-rev-list - Lists commit objects in reverse chronological order

asking myself whether rev could possibly mean "reverse".
I hope this helps avoid this pitfall for others.

Cheers,
Ralf

 Documentation/git-rev-list.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 4852804..8afe34b 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -44,9 +44,9 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Lists commit objects in reverse chronological order starting at the
-given commit(s), taking ancestry relationship into account.  This is
-useful to produce human-readable log output.
+Lists commit objects (revs, revisions) in reverse chronological order
+starting at the given commit(s), taking ancestry relationship into
+account.  This is useful to produce human-readable log output.
 
 Commits which are stated with a preceding '{caret}' cause listing to
 stop at that point. Their parents are implied. Thus the following
-- 
1.5.3.3.g34c6d

Re: [PATCH] git-rev-list.txt: rev stands for revision, not reverse.

[Junio C Hamano]

Ralf Wildenhues <Ralf.Wildenhues@gmx.de> writes:

> Mention revs, revisions as aliases for commit objects,
> to clarify that rev-list is not an abbreviation for
> listing in reverse order, but for listing revisions.
> ---
> Yes, believe it or not, but I stumbled over the synopsis
>
> | git-rev-list - Lists commit objects in reverse chronological order
>
> asking myself whether rev could possibly mean "reverse".
> I hope this helps avoid this pitfall for others.

In addition to your patch,

	git-rev-list - List commits from most recent to older

might be a good rewording?  "rev-list --reverse" reverses that
usual order and we end up explaining double reversal if we use
the phrase "reverse chronological order" to describe the normal
order.

Re: [PATCH] git-rev-list.txt: rev stands for revision, not reverse.

[Ralf Wildenhues]

Hello Junio,

* Junio C Hamano wrote on Thu, Nov 01, 2007 at 08:51:11PM CET:
> Ralf Wildenhues <Ralf.Wildenhues@gmx.de> writes:
> 
> > Yes, believe it or not, but I stumbled over the synopsis
> >
> > | git-rev-list - Lists commit objects in reverse chronological order
> >
> > asking myself whether rev could possibly mean "reverse".
> > I hope this helps avoid this pitfall for others.
> 
> In addition to your patch,
> 
> 	git-rev-list - List commits from most recent to older
> 
> might be a good rewording?

Is the reverse chronological order the primary sorting key at all?
My clone of the git repo gives me

$ git rev-list --pretty=format:%ct master | grep -v ^commit >A
$ sort -k1nr A | diff -u - A
--- -   2007-11-02 18:06:00.115804000 +0100
+++ A   2007-11-02 18:05:37.000000000 +0100
@@ -8162,8 +8162,8 @@
 1141461106
 1141461098
 1141461088
-1141457404
 1141457396
+1141457404
 1141453772
 1141453757
 1141453684

Interestingly, --date-order shows another inconsistency:

$ git rev-list --date-order --pretty=format:%ct master | grep -v ^commit >Ad
$ sort -k1nr Ad | diff -u - Ad
--- -   2007-11-02 18:27:18.091006000 +0100
+++ Ad  2007-11-02 18:25:46.000000000 +0100
@@ -653,8 +653,8 @@
 1188812406
 1188808117
 1188770606
-1188716400
 1188716027
+1188716400
 1188677727
 1188668216
 1188644991
@@ -8162,8 +8162,8 @@
 1141461106
 1141461098
 1141461088
-1141457404
 1141457396
+1141457404
 1141453772
 1141453757
 1141453684

This is "git version 1.5.3.5.474.g3e4bb", both repo and executables.

It looks like there is either a bug or the sorting criterion is subtly
different.

> "rev-list --reverse" reverses that usual order and we end up
> explaining double reversal if we use the phrase "reverse chronological
> order" to describe the normal order.

Well, I'd say the current synopsis would be fine if the default ordering
really were the commit date.  The synopsis should be concise, it's good
enough if the Description clears potential doubts.

Cheers,
Ralf

Re: [PATCH] git-rev-list.txt: rev stands for revision, not reverse.

[Junio C Hamano]

Ralf Wildenhues <Ralf.Wildenhues@gmx.de> writes:

> Hello Junio,
>
> * Junio C Hamano wrote on Thu, Nov 01, 2007 at 08:51:11PM CET:
>> Ralf Wildenhues <Ralf.Wildenhues@gmx.de> writes:
>> 
>> > Yes, believe it or not, but I stumbled over the synopsis
>> >
>> > | git-rev-list - Lists commit objects in reverse chronological order
>> >
>> > asking myself whether rev could possibly mean "reverse".
>> > I hope this helps avoid this pitfall for others.
>> 
>> In addition to your patch,
>> 
>> 	git-rev-list - List commits from most recent to older
>> 
>> might be a good rewording?
>
> Is the reverse chronological order the primary sorting key at all?

It is mostly chrono but there is a topo element as well.  You
would never see a parent none of whose child is shown.

Re: [PATCH] git-rev-list.txt: rev stands for revision, not reverse.

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Ralf Wildenhues <Ralf.Wildenhues@gmx.de> writes:
>
>> Is the reverse chronological order the primary sorting key at all?
>
> It is mostly chrono but there is a topo element as well.  You
> would never see a parent none of whose child is shown.

To be precise...

Internally, it mainly works on topology with an additional logic
to tiebreak with commit timestamps.

 - We always have one or more "output candidates".

 - Initially, the set of output candidates are primed from the
   positive refs (e.g. "foo", foo in "bar..foo", foo and bar in
   "bar...foo") you give to rev-list and/or log family of
   commands, after reachability analysis with negative refs
   (e.g. "^foo", bar in "bar..foo", merge-base of foo and bar in
   "bar...foo") if present.

 - We output the latest one among output candidates.  The
   parents of the commit we output go through the reachability
   analysis and the ones that are reachable from any of the
   negative refs are removed.  The ones that survive this
   reachability analysis are added to the output candidates.
   And the process starts over.  The algorithm terminates when
   there is none.

In practice, because child commits tend to get later commit
timestamps than all of their parent commits, the output looks
mostly reverse chronological.