{"thread":{"id":"10553","subject":"[PATCH] git-rev-list.txt: rev stands for revision, not reverse.","startedAt":"2007-11-01T08:45:53Z","lastAt":"2007-11-02T20:46:01Z","messageCount":5,"participants":["Ralf Wildenhues","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"57793","messageId":"20071101084552.GA4934@ins.uni-bonn.de","threadId":"10553","inReplyTo":null,"subject":"[PATCH] git-rev-list.txt: rev stands for revision, not reverse.","fromName":"Ralf Wildenhues","fromEmail":"ralf.wildenhues@gmx.de","sentAt":"2007-11-01T08:45:53Z","receivedAt":"2007-11-01T08:45:53Z","isPatch":true,"sender":{"key":"ralf.wildenhues@gmx.de","avatar":null},"body":"Mention revs, revisions as aliases for commit objects,\nto clarify that rev-list is not an abbreviation for\nlisting in reverse order, but for listing revisions.\n---\nYes, believe it or not, but I stumbled over the synopsis\n\n| git-rev-list - Lists commit objects in reverse chronological order\n\nasking myself whether rev could possibly mean \"reverse\".\nI hope this helps avoid this pitfall for others.\n\nCheers,\nRalf\n\n Documentation/git-rev-list.txt | 6 +++---\n 1 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex 4852804..8afe34b 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -44,9 +44,9 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Lists commit objects in reverse chronological order starting at the\n-given commit(s), taking ancestry relationship into account. This is\n-useful to produce human-readable log output.\n+Lists commit objects (revs, revisions) in reverse chronological order\n+starting at the given commit(s), taking ancestry relationship into\n+account. This is useful to produce human-readable log output.\n \n Commits which are stated with a preceding '{caret}' cause listing to\n stop at that point. Their parents are implied. Thus the following\n-- \n1.5.3.3.g34c6d\n"},{"id":"57849","messageId":"7vr6j9bv80.fsf@gitster.siamese.dyndns.org","threadId":"10553","inReplyTo":"20071101084552.GA4934@ins.uni-bonn.de","subject":"Re: [PATCH] git-rev-list.txt: rev stands for revision, not reverse.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-11-01T19:51:11Z","receivedAt":"2007-11-01T19:51:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ralf Wildenhues writes:\n\n> Mention revs, revisions as aliases for commit objects,\n> to clarify that rev-list is not an abbreviation for\n> listing in reverse order, but for listing revisions.\n> ---\n> Yes, believe it or not, but I stumbled over the synopsis\n>\n> | git-rev-list - Lists commit objects in reverse chronological order\n>\n> asking myself whether rev could possibly mean \"reverse\".\n> I hope this helps avoid this pitfall for others.\n\nIn addition to your patch,\n\n\tgit-rev-list - List commits from most recent to older\n\nmight be a good rewording? \"rev-list --reverse\" reverses that\nusual order and we end up explaining double reversal if we use\nthe phrase \"reverse chronological order\" to describe the normal\norder.\n"},{"id":"58019","messageId":"20071102185509.GA5242@ins.uni-bonn.de","threadId":"10553","inReplyTo":"7vr6j9bv80.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] git-rev-list.txt: rev stands for revision, not reverse.","fromName":"Ralf Wildenhues","fromEmail":"ralf.wildenhues@gmx.de","sentAt":"2007-11-02T18:55:10Z","receivedAt":"2007-11-02T18:55:10Z","isPatch":true,"sender":{"key":"ralf.wildenhues@gmx.de","avatar":null},"body":"Hello Junio,\n\n* Junio C Hamano wrote on Thu, Nov 01, 2007 at 08:51:11PM CET:\n> Ralf Wildenhues writes:\n> \n> > Yes, believe it or not, but I stumbled over the synopsis\n> >\n> > | git-rev-list - Lists commit objects in reverse chronological order\n> >\n> > asking myself whether rev could possibly mean \"reverse\".\n> > I hope this helps avoid this pitfall for others.\n> \n> In addition to your patch,\n> \n> \tgit-rev-list - List commits from most recent to older\n> \n> might be a good rewording?\n\nIs the reverse chronological order the primary sorting key at all?\nMy clone of the git repo gives me\n\n$ git rev-list --pretty=format:%ct master | grep -v ^commit >A\n$ sort -k1nr A | diff -u - A\n--- - 2007-11-02 18:06:00.115804000 +0100\n+++ A 2007-11-02 18:05:37.000000000 +0100\n@@ -8162,8 +8162,8 @@\n 1141461106\n 1141461098\n 1141461088\n-1141457404\n 1141457396\n+1141457404\n 1141453772\n 1141453757\n 1141453684\n\nInterestingly, --date-order shows another inconsistency:\n\n$ git rev-list --date-order --pretty=format:%ct master | grep -v ^commit >Ad\n$ sort -k1nr Ad | diff -u - Ad\n--- - 2007-11-02 18:27:18.091006000 +0100\n+++ Ad 2007-11-02 18:25:46.000000000 +0100\n@@ -653,8 +653,8 @@\n 1188812406\n 1188808117\n 1188770606\n-1188716400\n 1188716027\n+1188716400\n 1188677727\n 1188668216\n 1188644991\n@@ -8162,8 +8162,8 @@\n 1141461106\n 1141461098\n 1141461088\n-1141457404\n 1141457396\n+1141457404\n 1141453772\n 1141453757\n 1141453684\n\nThis is \"git version 1.5.3.5.474.g3e4bb\", both repo and executables.\n\nIt looks like there is either a bug or the sorting criterion is subtly\ndifferent.\n\n> \"rev-list --reverse\" reverses that usual order and we end up\n> explaining double reversal if we use the phrase \"reverse chronological\n> order\" to describe the normal order.\n\nWell, I'd say the current synopsis would be fine if the default ordering\nreally were the commit date. The synopsis should be concise, it's good\nenough if the Description clears potential doubts.\n\nCheers,\nRalf\n"},{"id":"58031","messageId":"7vprys1k5m.fsf@gitster.siamese.dyndns.org","threadId":"10553","inReplyTo":"20071102185509.GA5242@ins.uni-bonn.de","subject":"Re: [PATCH] git-rev-list.txt: rev stands for revision, not reverse.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-11-02T20:12:37Z","receivedAt":"2007-11-02T20:12:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ralf Wildenhues writes:\n\n> Hello Junio,\n>\n> * Junio C Hamano wrote on Thu, Nov 01, 2007 at 08:51:11PM CET:\n>> Ralf Wildenhues writes:\n>> \n>> > Yes, believe it or not, but I stumbled over the synopsis\n>> >\n>> > | git-rev-list - Lists commit objects in reverse chronological order\n>> >\n>> > asking myself whether rev could possibly mean \"reverse\".\n>> > I hope this helps avoid this pitfall for others.\n>> \n>> In addition to your patch,\n>> \n>> \tgit-rev-list - List commits from most recent to older\n>> \n>> might be a good rewording?\n>\n> Is the reverse chronological order the primary sorting key at all?\n\nIt is mostly chrono but there is a topo element as well. You\nwould never see a parent none of whose child is shown.\n"},{"id":"58038","messageId":"7v8x5g1ily.fsf@gitster.siamese.dyndns.org","threadId":"10553","inReplyTo":"7vprys1k5m.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] git-rev-list.txt: rev stands for revision, not reverse.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-11-02T20:46:01Z","receivedAt":"2007-11-02T20:46:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Ralf Wildenhues writes:\n>\n>> Is the reverse chronological order the primary sorting key at all?\n>\n> It is mostly chrono but there is a topo element as well. You\n> would never see a parent none of whose child is shown.\n\nTo be precise...\n\nInternally, it mainly works on topology with an additional logic\nto tiebreak with commit timestamps.\n\n - We always have one or more \"output candidates\".\n\n - Initially, the set of output candidates are primed from the\n positive refs (e.g. \"foo\", foo in \"bar..foo\", foo and bar in\n \"bar...foo\") you give to rev-list and/or log family of\n commands, after reachability analysis with negative refs\n (e.g. \"^foo\", bar in \"bar..foo\", merge-base of foo and bar in\n \"bar...foo\") if present.\n\n - We output the latest one among output candidates. The\n parents of the commit we output go through the reachability\n analysis and the ones that are reachable from any of the\n negative refs are removed. The ones that survive this\n reachability analysis are added to the output candidates.\n And the process starts over. The algorithm terminates when\n there is none.\n\nIn practice, because child commits tend to get later commit\ntimestamps than all of their parent commits, the output looks\nmostly reverse chronological.\n"}]}