{"thread":{"id":"9664","subject":"Confusion about diffing branches","startedAt":"2007-08-26T23:35:55Z","lastAt":"2007-08-27T22:20:23Z","messageCount":14,"participants":["Shawn Bohrer","Junio C Hamano","Mike Hommey","Francis Moreau","Theodore Tso","Jakub Narebski"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"51614","messageId":"20070826233555.GA7422@mediacenter.austin.rr.com","threadId":"9664","inReplyTo":null,"subject":"Confusion about diffing branches","fromName":"Shawn Bohrer","fromEmail":"shawn.bohrer@gmail.com","sentAt":"2007-08-26T23:35:55Z","receivedAt":"2007-08-26T23:35:55Z","isPatch":false,"sender":{"key":"shawn.bohrer@gmail.com","avatar":"https://gravatar.com/avatar/6eb093ef7d276306d18366254e0c95ff6a5db58231ac7e82fe78c2800aaae1b6?d=mp&s=160"},"body":"So I imagine I'm missing something, or perhaps I'm just looking at this\nfrom the wrong perspective, but here is what I'm seeing. Lets say I\nhave something like:\n\n A---B topic\n /\n C---D---E master\n\nIf I want to see a diff of all of the changes between the two branches I\ncan say:\n\n git diff master topic\n\nWhich shows me the combined diff of commits A, B and E. That is exactly\nwhat I would expect however, I would expect that equivalently I could\nsay:\n\n git diff master...topic\n\nto see all commits reachable from topic and master but not both.\nHowever, this doesn't do what I expect but instead only shows me the\ncombined diff of A and B. Likewise:\n\n git diff topic...master\n\nShows me the diff of E. Am I crazy or isn't this supposed to be the\nbehavior of the topic..master notation? Strangely enough running either\n\n git diff master..topic\n git diff topic..master\n\nboth show me the diff of A, B and E, which is what I would expect from\nthe master...topic notation. Am I the only one who thinks this is\nbackwards? The same experiment using git log shows me what I would\nexpect so somehow I think I'm missing something.\n"},{"id":"51619","messageId":"7v6431omn8.fsf@gitster.siamese.dyndns.org","threadId":"9664","inReplyTo":"20070826233555.GA7422@mediacenter.austin.rr.com","subject":"Re: Confusion about diffing branches","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-08-27T00:18:35Z","receivedAt":"2007-08-27T00:18:35Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Shawn Bohrer writes:\n\n> So I imagine I'm missing something, or perhaps I'm just looking at this\n> from the wrong perspective, but here is what I'm seeing. Lets say I\n> have something like:\n>\n> A---B topic\n> /\n> C---D---E master\n>\n> ...\n> git diff master...topic\n>\n> ... shows me the\n> combined diff of A and B.\n\nThat is working as designed.\n\nWhen you are working on topic it is often desired to see \"what\nhave I done since I forked?\" and \"what have they done while I\nwas looking the other way?\".\n\n\"git diff master topic\" (which is the same as \"git diff\nmaster..topic\" -- the two-dot form is just a syntax sugar to\navoid mistypes for people who are too used to type two dots as\nreflex because that is how you express a revision range) shows\na squashed diff that is A+B-E, and often people found \"-E\" part\ndistracting and useless. Three-dot form was invented\nspecifically to address this problem. You do not have to (and\nyou do not _want_ to) use that form if you _want_ to see the -E\npart of the diff.\n"},{"id":"51626","messageId":"20070827014056.GB7422@mediacenter.austin.rr.com","threadId":"9664","inReplyTo":"7v6431omn8.fsf@gitster.siamese.dyndns.org","subject":"Re: Confusion about diffing branches","fromName":"Shawn Bohrer","fromEmail":"shawn.bohrer@gmail.com","sentAt":"2007-08-27T01:40:56Z","receivedAt":"2007-08-27T01:40:56Z","isPatch":false,"sender":{"key":"shawn.bohrer@gmail.com","avatar":"https://gravatar.com/avatar/6eb093ef7d276306d18366254e0c95ff6a5db58231ac7e82fe78c2800aaae1b6?d=mp&s=160"},"body":"On Sun, Aug 26, 2007 at 05:18:35PM -0700, Junio C Hamano wrote:\n> When you are working on topic it is often desired to see \"what\n> have I done since I forked?\" and \"what have they done while I\n> was looking the other way?\".\n\nAbsolutely, and from the user manual I gathered that this was what the\ntwo-dot form was for. \"git diff master..topic\" show me the diff of\ncommits reachable from topic, but not from master.\n\nThe three-dot form seemed to address the other use case which is\nprobably the more usual case for git-diff which is show me the changes\nreachable from master or topic but not both.\n\n> \"git diff master topic\" (which is the same as \"git diff\n> master..topic\" -- the two-dot form is just a syntax sugar to\n> avoid mistypes for people who are too used to type two dots as\n> reflex because that is how you express a revision range) shows\n> a squashed diff that is A+B-E, and often people found \"-E\" part\n> distracting and useless. Three-dot form was invented\n> specifically to address this problem. You do not have to (and\n> you do not _want_ to) use that form if you _want_ to see the -E\n> part of the diff.\n\nSo if I understand you correctly people in the git world are simply more\nused to typing two dots (instead of three) so that is why the two dot\nnotation shows the more common use case (show me the difference between\nthe tip of the master branch and the tip of the topic branch).\n\nI must admit that for me, a new git user, it would be much more\nintuitive if all git commands used the same syntax for specifying\nrevisions. After all every other git command that I have used so far\nuses the opposite syntax as git-diff. This includes git-log,\ngit-format-patch, gitk, git-rev-list, and git-rev-parse.\n"},{"id":"51638","messageId":"20070827062508.GA9002@glandium.org","threadId":"9664","inReplyTo":"20070827014056.GB7422@mediacenter.austin.rr.com","subject":"Re: Confusion about diffing branches","fromName":"Mike Hommey","fromEmail":"mh@glandium.org","sentAt":"2007-08-27T06:25:08Z","receivedAt":"2007-08-27T06:25:08Z","isPatch":false,"sender":{"key":"mh@glandium.org","avatar":"https://avatars.githubusercontent.com/u/1038527?v=4"},"body":"On Sun, Aug 26, 2007 at 08:40:56PM -0500, Shawn Bohrer wrote:\n> So if I understand you correctly people in the git world are simply more\n> used to typing two dots (instead of three) so that is why the two dot\n> notation shows the more common use case (show me the difference between\n> the tip of the master branch and the tip of the topic branch).\n> \n> I must admit that for me, a new git user, it would be much more\n> intuitive if all git commands used the same syntax for specifying\n> revisions. After all every other git command that I have used so far\n> uses the opposite syntax as git-diff. This includes git-log,\n> git-format-patch, gitk, git-rev-list, and git-rev-parse.\n\nSimilar experience here. It is even more a problem for newcomers when\nyou consider it isn't documented in either git-rev-parse or git-diff\nmanual pages.\n\nMike\n"},{"id":"51640","messageId":"7vlkbxmp50.fsf@gitster.siamese.dyndns.org","threadId":"9664","inReplyTo":"20070827014056.GB7422@mediacenter.austin.rr.com","subject":"Re: Confusion about diffing branches","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-08-27T07:07:39Z","receivedAt":"2007-08-27T07:07:39Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Shawn Bohrer writes:\n\n> So if I understand you correctly people in the git world are simply more\n> used to typing two dots (instead of three) so that is why the two dot\n> notation shows the more common use case (show me the difference between\n> the tip of the master branch and the tip of the topic branch).\n\nNo, what I said was that two dot form is merely there to avoid\nsaying 'if you want to diff two trees, do not say \"diff a..b\"\nbut say \"diff a b\", dummy!'. Instead of giving such an error\nmessage, we just say \"oh, you want difference between a and b?\nhere it is\".\n\nAs to which is common between \"diff a..b\" and \"diff a...b\", that\nreally depends. You seem to be hinting that you think a...b is\nmore useful but that is not always the case. Comparing two\narbitrary trees _is_ the base form of diff, and that is what\n\"diff a b\" gives you. It does not require two trees to be\nrelated in ancestry relationships in _any_ way. For example,\nyou can say \"git diff v2.6.20 v2.6.21\" or \"git diff v2.6.20.4\nv2.6.21.2\".\n\nOn the other hand, when you are into topic branch development\nworkflow, \"diff a...b\" is often useful but that does not mean\npeople using topic branch development does not need \"diff a b\"\nform. You can say either \"diff a b\" if you want straight diff\nbetween two trees, or \"diff a...b\" if you want \"what happened in\nb, since it forked from the history leading to a\"; if the\ntwo-dot form confuses you, you do not have to use that synonym.\n\nBoth semantics of two-dot form and three-dot form are useful,\nand choice between the two depends on what you want out of the\ncommand. You just need to know which one you want.\n"},{"id":"51641","messageId":"20070827075009.GA31438@glandium.org","threadId":"9664","inReplyTo":"7vlkbxmp50.fsf@gitster.siamese.dyndns.org","subject":"Re: Confusion about diffing branches","fromName":"Mike Hommey","fromEmail":"mh@glandium.org","sentAt":"2007-08-27T07:50:09Z","receivedAt":"2007-08-27T07:50:09Z","isPatch":false,"sender":{"key":"mh@glandium.org","avatar":"https://avatars.githubusercontent.com/u/1038527?v=4"},"body":"On Mon, Aug 27, 2007 at 12:07:39AM -0700, Junio C Hamano wrote:\n> Both semantics of two-dot form and three-dot form are useful,\n> and choice between the two depends on what you want out of the\n> command. You just need to know which one you want.\n\nThe problem is not about usefulness of these 2 forms, but consistency\nwith the rest of the tools.\nIf I go git log a..b, I won't get the set of commits involved in\ngit diff a..b. In fact, git log a...b does. And git log a..b gives the\ncommits involved in git diff a...b. Confusing, isn't it ?\nMoreover, this inconsistency isn't even documented in the manual pages.\n\nMike\n"},{"id":"51700","messageId":"38b2ab8a0708270621l63f3da56j4667014e62a5de92@mail.gmail.com","threadId":"9664","inReplyTo":"20070827075009.GA31438@glandium.org","subject":"Re: Confusion about diffing branches","fromName":"Francis Moreau","fromEmail":"francis.moro@gmail.com","sentAt":"2007-08-27T13:21:32Z","receivedAt":"2007-08-27T13:21:32Z","isPatch":false,"sender":{"key":"francis.moro@gmail.com","avatar":null},"body":"Hi !\n\nOn 8/27/07, Mike Hommey wrote:\n> On Mon, Aug 27, 2007 at 12:07:39AM -0700, Junio C Hamano wrote:\n> > Both semantics of two-dot form and three-dot form are useful,\n> > and choice between the two depends on what you want out of the\n> > command. You just need to know which one you want.\n>\n> The problem is not about usefulness of these 2 forms, but consistency\n> with the rest of the tools.\n> If I go git log a..b, I won't get the set of commits involved in\n> git diff a..b. In fact, git log a...b does. And git log a..b gives the\n> commits involved in git diff a...b. Confusing, isn't it ?\n> Moreover, this inconsistency isn't even documented in the manual pages.\n>\n\nThis \"inconsistency\" had already been raised before. Please refer to:\nhttp://www.gelato.unsw.edu.au/archives/git/0612/35354.html\n\nI shared and still share your feeling about that but it seems that\nJunio and Linus don't...\n\ngood luck ;)\n-- \nFrancis\n"},{"id":"51704","messageId":"20070827133314.GA9131@glandium.org","threadId":"9664","inReplyTo":"38b2ab8a0708270621l63f3da56j4667014e62a5de92@mail.gmail.com","subject":"Re: Confusion about diffing branches","fromName":"Mike Hommey","fromEmail":"mh@glandium.org","sentAt":"2007-08-27T13:33:14Z","receivedAt":"2007-08-27T13:33:14Z","isPatch":false,"sender":{"key":"mh@glandium.org","avatar":"https://avatars.githubusercontent.com/u/1038527?v=4"},"body":"On Mon, Aug 27, 2007 at 03:21:32PM +0200, Francis Moreau wrote:\n> Hi !\n> \n> On 8/27/07, Mike Hommey wrote:\n> > On Mon, Aug 27, 2007 at 12:07:39AM -0700, Junio C Hamano wrote:\n> > > Both semantics of two-dot form and three-dot form are useful,\n> > > and choice between the two depends on what you want out of the\n> > > command. You just need to know which one you want.\n> >\n> > The problem is not about usefulness of these 2 forms, but consistency\n> > with the rest of the tools.\n> > If I go git log a..b, I won't get the set of commits involved in\n> > git diff a..b. In fact, git log a...b does. And git log a..b gives the\n> > commits involved in git diff a...b. Confusing, isn't it ?\n> > Moreover, this inconsistency isn't even documented in the manual pages.\n> >\n> \n> This \"inconsistency\" had already been raised before. Please refer to:\n> http://www.gelato.unsw.edu.au/archives/git/0612/35354.html\n> \n> I shared and still share your feeling about that but it seems that\n> Junio and Linus don't...\n\nActually, they may have a good point, cf. the thread you point.\nBut it is annoying that it is not documented.\n\nMike\n"},{"id":"51730","messageId":"20070827170504.GH4680@thunk.org","threadId":"9664","inReplyTo":"38b2ab8a0708270621l63f3da56j4667014e62a5de92@mail.gmail.com","subject":"Re: Confusion about diffing branches","fromName":"Theodore Tso","fromEmail":"tytso@mit.edu","sentAt":"2007-08-27T17:05:04Z","receivedAt":"2007-08-27T17:05:04Z","isPatch":false,"sender":{"key":"tytso@mit.edu","avatar":"https://avatars.githubusercontent.com/u/51416?v=4"},"body":"On Mon, Aug 27, 2007 at 03:21:32PM +0200, Francis Moreau wrote:\n> This \"inconsistency\" had already been raised before. Please refer to:\n> http://www.gelato.unsw.edu.au/archives/git/0612/35354.html\n\nThat's not a major inconsistency problem IMHO because git diff does\nnot take a set of commits, but rather two end points --- conceptually,\nthere's no way to make sense out of trying to feed an arbitrary set of\ncommitments to git-diff.\n\nThe bigger inconsistency is with git-format-patch, which *does* take a\nset of commits, and where \"git-format-patch a\" does operates on a very\ndifferent set of commits than what what \"git-rev-list a\" returns. I\nunderstand that for backwards compatibility \"git-format-patch a\" is\nequivalent to \"git-format-patch a..HEAD\", but what it means is that\nall other ways of specifying sets of commits work with\ngit-format-patch, *except* if you want to specify all commits from the\nbeginning of time to a particular head (i.e., \"git-rev-list a\") is\nsomething that you simply can not possibly do using git-format-patch.\nThis was mentioned on a blog entry as one of those \"really confusing\ninconsistencies\" in git.\n\n\t\t\t\t\t\t- Ted\n"},{"id":"51731","messageId":"7vr6lozz3m.fsf@gitster.siamese.dyndns.org","threadId":"9664","inReplyTo":"20070827133314.GA9131@glandium.org","subject":"Re: Confusion about diffing branches","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-08-27T17:06:21Z","receivedAt":"2007-08-27T17:06:21Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Mike Hommey writes:\n\n> On Mon, Aug 27, 2007 at 03:21:32PM +0200, Francis Moreau wrote:\n>> \n>> This \"inconsistency\" had already been raised before. Please refer to:\n>> http://www.gelato.unsw.edu.au/archives/git/0612/35354.html\n>> \n>> I shared and still share your feeling about that but it seems that\n>> Junio and Linus don't...\n>\n> Actually, they may have a good point, cf. the thread you point.\n> But it is annoying that it is not documented.\n\nWould something like this reduce the annoyance factor?\n\n---\n\n Documentation/git-diff.txt | 20 +++++++++++++++++---\n 1 files changed, 17 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex b36e705..04b62d9 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -42,14 +42,28 @@ tree and the index file, or the index file and the working tree.\n \tbranch name to compare with the tip of a different\n \tbranch.\n \n-'git-diff' [--options] [--] [...]::\n+'git-diff' [--options] [--] [...]::\n \n \tThis form is to view the changes between two ,\n \tfor example, tips of two branches.\n \n+'git-diff' [--options] .. [--] [...]::\n+\n+\tThis is identical to the previous one, just to make the\n+\tspecification of two commits look similar to a commit\n+\trange notation.\n+\n+'git-diff' [--options] ... [--] [...]::\n+\n+\tThis compares the merge base of two commits and the\n+\tsecond commit. Useful to view what happened in the\n+\thistory that leads to the second commit since that\n+\thistory forked from the history that leads to the first\n+\tcommit.\n+\n Just in case if you are doing something exotic, it should be\n-noted that all of the in the above description can be\n-any .\n+noted that all of the in the above description,\n+except for the last two variants, can be any .\n \n For a more complete list of ways to spell , see\n \"SPECIFYING REVISIONS\" section in gitlink:git-rev-parse[1].\n"},{"id":"51734","messageId":"7vmywczyfp.fsf@gitster.siamese.dyndns.org","threadId":"9664","inReplyTo":"20070827170504.GH4680@thunk.org","subject":"Re: Confusion about diffing branches","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-08-27T17:20:42Z","receivedAt":"2007-08-27T17:20:42Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Theodore Tso writes:\n\n> The bigger inconsistency is with git-format-patch, which *does* take a\n> set of commits, and where \"git-format-patch a\" does operates on a very\n> different set of commits than what what \"git-rev-list a\" returns. I\n> understand that for backwards compatibility \"git-format-patch a\" is\n> equivalent to \"git-format-patch a..HEAD\", but what it means is that\n> all other ways of specifying sets of commits work with\n> git-format-patch, *except* if you want to specify all commits from the\n> beginning of time to a particular head (i.e., \"git-rev-list a\") is\n> something that you simply can not possibly do using git-format-patch.\n\nHeh, I really hate when people say this.\n\nIf you wanted to, you could:\n\n\t$ git format-patch a a\n\nThe original syntax\n\n\t$ git format-patch upstream\n\nmay have been a mistake and maybe\n\n\t$ git format-patch ^upstream\n\nor even \n\n\t$ git format-patch --since upstream\n\nmight have been better. It is (1) too late to change now, and\n(2) for too small or perhaps negative a gain.\n\nThe reason why I say (2) is because _I_ think it is far more\ncommon and frequent to want to get \"patches the other guy does\nnot have\" than \"everything since nothingness up to this point\".\n\nOops. I think I have a solution.\n\n\t$ git format-patch a a\n\ndoes not do _ROOT_ commit. So you have to say\n\n\t$ git format-patch --root a a\n\nfor the above example to work. Why not tweak the option parser\nso that:\n\n\t$ git format-patch --root a\n\nto do what you want? Without --root and with a single positive\ncommit, it can keep doing the traditional \"what I did since I\nforked from that guy's history\".\n\nHmm...\n"},{"id":"51736","messageId":"20070827172452.GA10041@glandium.org","threadId":"9664","inReplyTo":"7vr6lozz3m.fsf@gitster.siamese.dyndns.org","subject":"Re: Confusion about diffing branches","fromName":"Mike Hommey","fromEmail":"mh@glandium.org","sentAt":"2007-08-27T17:24:52Z","receivedAt":"2007-08-27T17:24:52Z","isPatch":false,"sender":{"key":"mh@glandium.org","avatar":"https://avatars.githubusercontent.com/u/1038527?v=4"},"body":"On Mon, Aug 27, 2007 at 10:06:21AM -0700, Junio C Hamano wrote:\n> Mike Hommey writes:\n> \n> > On Mon, Aug 27, 2007 at 03:21:32PM +0200, Francis Moreau wrote:\n> >> \n> >> This \"inconsistency\" had already been raised before. Please refer to:\n> >> http://www.gelato.unsw.edu.au/archives/git/0612/35354.html\n> >> \n> >> I shared and still share your feeling about that but it seems that\n> >> Junio and Linus don't...\n> >\n> > Actually, they may have a good point, cf. the thread you point.\n> > But it is annoying that it is not documented.\n> \n> Would something like this reduce the annoyance factor?\n\nI was actually working on the attached diff, though I'm not really\nconvinced by my wording.\n\nMike\n\n\n Documentation/git-diff.txt | 32 ++++++++++++++++++++++++++++++--\n 1 files changed, 30 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex b36e705..082ac0b 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -43,9 +43,22 @@ tree and the index file, or the index file and the working tree.\n \tbranch.\n \n 'git-diff' [--options] [--] [...]::\n+'git-diff' [--options] .. [--] [...]::\n \n-\tThis form is to view the changes between two ,\n-\tfor example, tips of two branches.\n+\tThese forms are to view the changes between two ,\n+\tfor example, tips of two branches. In the second form,\n+\tomitting any one of both will have the same effect\n+\tas using HEAD.\n+\n+'git-diff' [--options] ... [--] [...]::\n+\n+\tThis form is to view the changes on the branch containing\n+\tand up to the second , starting at a common ancestor\n+\tof both .\n+\t\"git-diff A...B\" is equivalent to\n+\t\"git-diff `git-merge-base A B` B\"\n+\tYou can omit any one of both , which has the same\n+\teffect as using HEAD.\n \n Just in case if you are doing something exotic, it should be\n noted that all of the in the above description can be\n@@ -54,6 +67,9 @@ any .\n For a more complete list of ways to spell , see\n \"SPECIFYING REVISIONS\" section in gitlink:git-rev-parse[1].\n \n+Be careful that despite looking like so, both \"..\"\n+and \"...\" forms are NOT ranges as described in\n+the \"SPECIFYING RANGES\" section in gitlink:git-rev-parse[1].\n \n OPTIONS\n -------\n@@ -97,6 +113,18 @@ the tip of the current branch, but limit the comparison to the\n file \"test\".\n <3> Compare the version before the last commit and the last commit.\n \n+Comparing branches::\n++\n+------------\n+$ git diff topic master <1>\n+$ git diff topic..master <2>\n+$ git diff topic...master <2>\n+------------\n++\n+<1> Changes between the tips of the topic and the master branches.\n+<2> Same as <1>\n+<3> Changes that occured on the master branch since when the topic\n+branch was started off it.\n \n Limiting the diff output::\n +\n"},{"id":"51750","messageId":"20070827202949.GA3951@thunk.org","threadId":"9664","inReplyTo":"7vmywczyfp.fsf@gitster.siamese.dyndns.org","subject":"Re: Confusion about diffing branches","fromName":"Theodore Tso","fromEmail":"tytso@mit.edu","sentAt":"2007-08-27T20:29:49Z","receivedAt":"2007-08-27T20:29:49Z","isPatch":false,"sender":{"key":"tytso@mit.edu","avatar":"https://avatars.githubusercontent.com/u/51416?v=4"},"body":"On Mon, Aug 27, 2007 at 10:20:42AM -0700, Junio C Hamano wrote:\n> If you wanted to, you could:\n> \n> \t$ git format-patch a a\n\nUmm.... dare I ask why this works, or how someone would be expected to\nknow this? Or is the answer, \"Meditate deeply on builtin-log.c,\ngrasshopper\"? :-)\n\n> might have been better. It is (1) too late to change now, and\n> (2) for too small or perhaps negative a gain.\n> \n> The reason why I say (2) is because _I_ think it is far more\n> common and frequent to want to get \"patches the other guy does\n> not have\" than \"everything since nothingness up to this point\".\n\nI agree, \"patches the other guy does not have\" is usually the more\ncommon desired result. The problem is that it breaks the regularity\nof git's command line parsing, which is particularly painful given\nthat users are told to read the man page for git-rev-list and\ngit-rev-parse in order to understand all of the many, many options\nthat might be valid. The fact that the man pages expect the user to\ndo this kinda implies that there is a regularity and orthogonality to\ngit's command structure --- which there is, mostly --- which makes the\ngit-format-patch \"hack\" that much more surprising.\n\nSo it's just one of those things which is surprising to someone who\nhasn't been fingers deep in the guts of the git implementation for\nyears and years. I think it took me a good hour or two of searching\nbefore I was able to even figure out how the special case for\ngit-format-patch was getting implemented; it certainly wasn't well\ndocumented in the code last year when I went searching to figure out\nwhat the !@#@? was going on.\n\n> Oops. I think I have a solution.\n> \n> \t$ git format-patch a a\n> \n> does not do _ROOT_ commit. So you have to say\n> \n> \t$ git format-patch --root a a\n\nWow, I had no idea that --root would even be accepted by\ngit-format-patch. It's not mentioned in the documentation, and a grep\nof Documentation/*.txt shows that --root is only mentioned in the man\npages for git-blame, git-fsck, and git-diff-tree. I assume it's the\nlatter which is getting used here, but there isn't even a mention in\nthe git-format-patch man page that options from git-diff-tree might be\napplicable. \n\nI presume this is another, \"meditate deeply on builtin-log.c and\nrevision.c, and understand that they implement many diverse builtin\ncommands, grasshopper\" situation....\n\n> for the above example to work. Why not tweak the option parser\n> so that:\n> \n> \t$ git format-patch --root a\n> \n> to do what you want? Without --root and with a single positive\n> commit, it can keep doing the traditional \"what I did since I\n> forked from that guy's history\".\n\nThat seems to make a lot of sense; given the fact that the current\nbehaivor does make sense and is convenient, the big complaints were\nalways (1) not documenting clearly that this was an exception which\nmight be surprising (i.e., hanging a latern[1] on it), and (2) that\nthere wasn't a way to do the alternate expected behavior. --root\nhandles the second, and an explanation in the man page saying that\nyes, this is a little non-standard wrt to git-rev-list, but it's\nconvenient, and let the user know that he should just give us a pass\non it the non-orthoganlity.\n\n\t\t\t\t\t- Ted\n\n[1] \nDaniel: The mountain... blows up?\nMartin: No possible hope for survival! Cool huh? I just wrote it \n\t based on what's going on with the gate. I love it when art \n\t imitates life. \nMitchell: Hang on. We're alive in the next scene.\nMartin: Oh, I just haven't fixed that part yet. I'm thinking I can \n\t back-sell it and say you were beamed out at the last second.\nDaniel: \"Beamed out?\"\nMartin: Sure, why not?\nTeal'c: Is that not too convenient?\nMartin: Not if you hang a lantern on it.\nDaniel: What's that?\nMartin: It's a writer's term. Another character points out how\n\t convenient it is. Doctor Levant can say, \"Wow, that was\n\t great timing.\" That way, the audience knows I intended for\n\t it to be convenient, and we move on.\n"},{"id":"51757","messageId":"favin5$2sm$1@sea.gmane.org","threadId":"9664","inReplyTo":"20070827014056.GB7422@mediacenter.austin.rr.com","subject":"Re: Confusion about diffing branches","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-08-27T22:20:23Z","receivedAt":"2007-08-27T22:20:23Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Shawn Bohrer wrote:\n\n> I must admit that for me, a new git user, it would be much more\n> intuitive if all git commands used the same syntax for specifying\n> revisions.  After all every other git command that I have used so far\n> uses the opposite syntax as git-diff.  This includes git-log,\n> git-format-patch, gitk, git-rev-list, and git-rev-parse.\n\ngit-rev-list, git-log, gitk accepts _range_ of commits. git-diff and\nits variants accepts _endpoints_ to compare, with some syntactic sugar\nto be able to copy arguments from \"git log a..b\" to \"git diff a..b\". \nThe arguments are just simply different type.\n\nAs to git-format-patch, there is matter of backward compatibilty\nand ease of use (get last commit as a patch).\n\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n"}]}