{"thread":{"id":"13735","subject":"git-log vs git-rev-list","startedAt":"2008-05-30T16:56:41Z","lastAt":"2008-05-30T21:34:43Z","messageCount":7,"participants":["Petr Baudis","Linus Torvalds","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"78157","messageId":"20080530165641.GG18781@machine.or.cz","threadId":"13735","inReplyTo":null,"subject":"git-log vs git-rev-list","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2008-05-30T16:56:41Z","receivedAt":"2008-05-30T16:56:41Z","isPatch":false,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"  Hi,\n\n  the baroque usage options of both git-log and git-rev-list make them\npretty much equivalent as far as I can see, except that:\n\n  * Both have slightly different options set\n\n  * git log --pretty=format is actually sane and does not pollute the\noutput with spurious 'commit' lines\n\n  * I assume there are more subtle behaviour differences\n\n  I think that having two commands that by now do essentially the same\nthing, but slightly differently, is rather messy UI. Thus, I'm wondering\nif it would be worthwhile to make rev-list a thin git-log wrapper and\nstart phasing it out?\n\n  Yes, git-rev-list is supposed to be a plumbing thing, but from my\nporcelain, I actually have to use git-log anyway if I'm to avoid messing\nup my code with workarounds to the --pretty=format commit lines\nevilness (hey, if I'm using --pretty=format, it means I actually want\nto _control_ rev-list output, not having it trying to outsmart me\nanyway).\n\n  Merging porcelain and plumbing interface in a single command may sound\nlike a bad idea UI-wise, but I believe that consolidation would actually\nresult in a UI _improvement_ - you can cleanly separate the\ndocumentation to the porcelain and plumbing part (actually, maybe\npushing all the plumbing part like --pretty documentation to\ngit-log-plumbing(1), having actually user-relevant options like -p or\n--no-meges in git-log(1)). And you do not have to tell the user \"oh, and\nthere is also git-rev-list(1) which does the same thing, but\ndifferently; ah, and for some reason you are also to use only that one\nif you need to query for bisect points\".\n\n  Should I do it?\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nWhatever you can do, or dream you can, begin it.\nBoldness has genius, power, and magic in it.\t-- J. W. von Goethe\n"},{"id":"78158","messageId":"alpine.LFD.1.10.0805301021310.3141@woody.linux-foundation.org","threadId":"13735","inReplyTo":"20080530165641.GG18781@machine.or.cz","subject":"Re: git-log vs git-rev-list","fromName":"Linus Torvalds","fromEmail":"torvalds@linux-foundation.org","sentAt":"2008-05-30T17:25:47Z","receivedAt":"2008-05-30T17:25:47Z","isPatch":false,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Fri, 30 May 2008, Petr Baudis wrote:\n> \n>   * git log --pretty=format is actually sane and does not pollute the\n> output with spurious 'commit' lines\n\nWhy would you want to use \"git-rev-list\" at all?\n\nThe common case for git-rev-list is for things that git log simply won't \ndo, ie things like \"git rev-list --all --objects\" that is a nonsensical \noperation to do on \"git log\".\n\nSo if you use \"--pretty\" or anything like that, you generally shouldn't \nuse rev-list. Sure, it works, but it works for mainly historical reasons.\n\n>   I think that having two commands that by now do essentially the same\n> thing, but slightly differently, is rather messy UI. Thus, I'm wondering\n> if it would be worthwhile to make rev-list a thin git-log wrapper and\n> start phasing it out?\n\nIt already is. It's already phased out in the sense that I don't see why \nyou complain. If you don't like it, don't use it. It has legacy reasons \nfor existing, and it does *some* things that are simply not sensible at \nall for \"git log\" (ie the non-commit things).\n\n>   Yes, git-rev-list is supposed to be a plumbing thing, but from my\n> porcelain, I actually have to use git-log anyway [..]\n\nSo why do you care?\n\nNo, git-rev-list is *not* the same as \"git log\". \n\nYes, git rev-list can do a lot of the same things, for historical reasons.\n\nYes, they share most of the code. No, they're not the same.\n\n\t\t\tLinus\n"},{"id":"78161","messageId":"20080530194635.GI593@machine.or.cz","threadId":"13735","inReplyTo":"alpine.LFD.1.10.0805301021310.3141@woody.linux-foundation.org","subject":"Re: git-log vs git-rev-list","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2008-05-30T19:46:35Z","receivedAt":"2008-05-30T19:46:35Z","isPatch":false,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"On Fri, May 30, 2008 at 10:25:47AM -0700, Linus Torvalds wrote:\n> On Fri, 30 May 2008, Petr Baudis wrote:\n> > \n> >   * git log --pretty=format is actually sane and does not pollute the\n> > output with spurious 'commit' lines\n> \n> Why would you want to use \"git-rev-list\" at all?\n\nBecause it was the natural command to access history from a script to me\nand nothing in the documentation hinted me that I shouldn't use it.\n\n> The common case for git-rev-list is for things that git log simply won't \n> do, ie things like \"git rev-list --all --objects\" that is a nonsensical \n> operation to do on \"git log\".\n\nStep back a bit: it's git-_REV_-list. Technically, --all --objects is\nnonsensical operation to do on revision list either.\n\n> >   I think that having two commands that by now do essentially the same\n> > thing, but slightly differently, is rather messy UI. Thus, I'm wondering\n> > if it would be worthwhile to make rev-list a thin git-log wrapper and\n> > start phasing it out?\n> \n> It already is. It's already phased out in the sense that I don't see why \n> you complain. If you don't like it, don't use it. It has legacy reasons \n> for existing, and it does *some* things that are simply not sensible at \n> all for \"git log\" (ie the non-commit things).\n\nBut there is no indication that it is phased out whatsoever. My point is\nthat presence of this command is confusing. If it is going to stand\naround for non-commit things, it should be called 'git-object-list' or\nsomething, and the difference to git-log should be made clear. But I\nthink there is no fundamental reason why git-log shouldn't be made able\nto list non-commit objects either.\n\n> >   Yes, git-rev-list is supposed to be a plumbing thing, but from my\n> > porcelain, I actually have to use git-log anyway [..]\n> \n> So why do you care?\n\nBecause it confused me, I'm probably not the first to be confused and it\nwill probably confuse others in the future too. The UI should be more\nconsistent.\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nWhatever you can do, or dream you can, begin it.\nBoldness has genius, power, and magic in it.\t-- J. W. von Goethe\n"},{"id":"78163","messageId":"alpine.LFD.1.10.0805301316580.3141@woody.linux-foundation.org","threadId":"13735","inReplyTo":"20080530194635.GI593@machine.or.cz","subject":"Re: git-log vs git-rev-list","fromName":"Linus Torvalds","fromEmail":"torvalds@linux-foundation.org","sentAt":"2008-05-30T20:20:13Z","receivedAt":"2008-05-30T20:20:13Z","isPatch":false,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Fri, 30 May 2008, Petr Baudis wrote:\n> > \n> > Why would you want to use \"git-rev-list\" at all?\n> \n> Because it was the natural command to access history from a script to me\n> and nothing in the documentation hinted me that I shouldn't use it.\n\nSo use it. Or not.\n\nJust don't think it's the same as \"git log\".\n\n> Step back a bit: it's git-_REV_-list. Technically, --all --objects is\n> nonsensical operation to do on revision list either.\n\nWho cares?\n\nWhy are you arguing against *facts*?\n\nThe *fact* is, git rev-list can traverse the whole object chain.\n\nThe *fact* is that git rev-list can do other operations that have nothing \nto do with logs (bisection, for example).\n\nThe *fact* is that both git rev-list and git log can traverse a set of \nrevisions, but that doesn't make them the same command.\n\nI totally don't see your arguments. They are pointless. git rev-list and \ngit log already share all the relevant internal machinery for the things \nwhere they overlap in capabilities. And the fact that they output \ndifferent things is because they are different.\n\n\t\t\tLinus\n"},{"id":"78164","messageId":"alpine.LFD.1.10.0805301320460.3141@woody.linux-foundation.org","threadId":"13735","inReplyTo":"20080530194635.GI593@machine.or.cz","subject":"Re: git-log vs git-rev-list","fromName":"Linus Torvalds","fromEmail":"torvalds@linux-foundation.org","sentAt":"2008-05-30T20:22:37Z","receivedAt":"2008-05-30T20:22:37Z","isPatch":false,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Fri, 30 May 2008, Petr Baudis wrote:\n> \n> Because it confused me, I'm probably not the first to be confused and it\n> will probably confuse others in the future too. The UI should be more\n> consistent.\n\nBtw, the reason this is irrelevant is that \"git rev-list\" isn't even a UI. \nIt's internal plumbing, and almost all of it's flags etc are directly from \nhistorical reasons. IOW, it does bisection because it used to be the only \nprogram that did any revision walking. It can do pretty much what git log \ndoes for the same reason.\n\nSo breaking git rev-list because somebody thinks it's \"UI\" is odd totally \nmisses the whole _point_ of the command.\n\n\t\tLinus\n"},{"id":"78170","messageId":"7v7idbk04d.fsf@gitster.siamese.dyndns.org","threadId":"13735","inReplyTo":"20080530165641.GG18781@machine.or.cz","subject":"Re: git-log vs git-rev-list","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-05-30T20:28:18Z","receivedAt":"2008-05-30T20:28:18Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Petr Baudis <pasky@suse.cz> writes:\n\n>   I think that having two commands that by now do essentially the same\n> thing, but slightly differently, is rather messy UI. Thus, I'm wondering\n> if it would be worthwhile to make rev-list a thin git-log wrapper and\n> start phasing it out?\n\nTwo answers and a half.\n\n (1) There are a few things git-log does not do but git-rev-list is\n     designed to do.\n\n (2) They are _already_ thin wrappers to the same core \"revision\n     traversal\" engine, and each of them does what it is meant to do well\n     as specified.\n\n (3) rev-list is an established script interface.  You could enhance it if\n     it does not fit your Porcelain needs, but you cannot break it, let\n     alone phase it out.  What you can contribute is perhaps to document\n     it better so that casual end users do not accidentally try to use\n     rev-list as if it is the first class end-user interface and get\n     confused.\n\nI do not think there is much to be gained by further refactoring of the\nimplementations between the two.\n"},{"id":"78181","messageId":"20080530213443.GJ593@machine.or.cz","threadId":"13735","inReplyTo":"alpine.LFD.1.10.0805301316580.3141@woody.linux-foundation.org","subject":"Re: git-log vs git-rev-list","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2008-05-30T21:34:43Z","receivedAt":"2008-05-30T21:34:43Z","isPatch":false,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"On Fri, May 30, 2008 at 01:20:13PM -0700, Linus Torvalds wrote:\n> On Fri, 30 May 2008, Petr Baudis wrote:\n> > Step back a bit: it's git-_REV_-list. Technically, --all --objects is\n> > nonsensical operation to do on revision list either.\n> \n> Who cares?\n\nYou did in case of git log.\n\n> Why are you arguing against *facts*?\n> \n> The *fact* is, git rev-list can traverse the whole object chain.\n> \n> The *fact* is that git rev-list can do other operations that have nothing \n> to do with logs (bisection, for example).\n> \n> The *fact* is that both git rev-list and git log can traverse a set of \n> revisions, but that doesn't make them the same command.\n\nHuh? Of course these are facts, but I don't see what does that have to\ndo with anything. I'm not arguing this isn't so, I'm arguing it _is_ so\nand some of it is _wrong_ from user interface standpoint.\n\n> I totally don't see your arguments. They are pointless. git rev-list and \n> git log already share all the relevant internal machinery for the things \n> where they overlap in capabilities. And the fact that they output \n> different things is because they are different.\n\nMy argument is that there should not be two different commands with\nsimilar interface and almost similar feature set when a single interface\nwould be more than enough - no matter if it is UI or an API, redundant\ninterfaces mean more clutter for users (or developers) to wade through\nand more bitrot for the project. After all, as I said - when I've hit\nthe rev-list / log inconsitencies, I was not looking for UI but indeed\nfor an internal helper.\n\n\nHaving said that, I'm fine with Junio's argument that we need to keep\ngit-rev-list for compatibility reasons as long as the relationship\nbetween git-rev-list and git-log is more clearly documented; I would be\nhappier if the few remaining options would get implemented for git-log\nand git-rev-list got deprecated (which does not mean removing it right\naway; git-ssh-push was removed after two years), but I don't care that\nmuch as to flame on, it's too hot over here in Central Europe already.\n:-)\n\nI will send some documentation patches soon.\n\n\nBy the way, is git log regarded as porcelain or plumbing? That is, are\nthere any guarantees about stability of git log output format etc.? Can\nI use git log in my script and rely on it to behave forever exactly as\nit does now? (Modulo bugfixes.)\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nWhatever you can do, or dream you can, begin it.\nBoldness has genius, power, and magic in it.\t-- J. W. von Goethe\n"}]}