{"thread":{"id":"50764","subject":"[PATCH] git-diff.txt: prefer not using ..","startedAt":"2019-03-17T11:09:12Z","lastAt":"2019-03-21T14:13:28Z","messageCount":16,"participants":["Denton Liu","Duy Nguyen","Ævar Arnfjörð Bjarmason","Junio C Hamano","Elijah Newren","Johannes Schindelin"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"371693","messageId":"bc7c3f9d769b2d5a108ff4cdc3c7277e112fdb56.1552820745.git.liu.denton@gmail.com","threadId":"50764","inReplyTo":null,"subject":"[PATCH] git-diff.txt: prefer not using ..","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-03-17T11:09:07Z","receivedAt":"2019-03-17T11:09:12Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"The documentation used to consider\n\n\tgit diff \n\nand\n\n\tgit diff ..\n\nto be equal counterparts. However, rev-list-ish commands also use the\n.. notation, but in a logically conflicting manner which\nwas confusing for some users (including me!).\n\nDeprecating the notation entirely is not really an option because it\nwould be an arduous process without much end-value. In addition, there\nare some valid use-cases that we don't want to break.\n\nDocument the preference of the first form so that future confusion can\nbe minimised.\n\nSigned-off-by: Denton Liu \n---\n\nThanks all on your feedback on the discussion thread[1]! I opted for\njust the documentation-only route so we don't break any valid use-cases.\n\n[1]: https://public-inbox.org/git/20190311093751.GA31092@archbookpro.localdomain/\n\n Documentation/git-diff.txt | 6 +++++-\n 1 file changed, 5 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 72179d993c..10c7a2220c 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -63,7 +63,11 @@ two blob objects, or changes between two files on disk.\n \n 'git diff' [] .. [--] [...]::\n \n-\tThis is synonymous to the previous form. If on\n+\tThis is synonymous to the previous form. However,\n+\tusers should prefer the previous form over this form\n+\tas this form may be more confusing due to the same\n+\tnotation having a logically conflicting meaning in\n+\tlinkgit:git-rev-list[1]-ish commands. If on\n \tone side is omitted, it will have the same effect as\n \tusing HEAD instead.\n \n-- \n2.21.0.512.g57bf1b23e1\n\n"},{"id":"371724","messageId":"CACsJy8DU02_kOqAHhU5EgMHKmkNSGdvt+7XzSHoZDB+b9sDRqg@mail.gmail.com","threadId":"50764","inReplyTo":"bc7c3f9d769b2d5a108ff4cdc3c7277e112fdb56.1552820745.git.liu.denton@gmail.com","subject":"Re: [PATCH] git-diff.txt: prefer not using ..","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2019-03-17T13:24:16Z","receivedAt":"2019-03-17T13:24:44Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Sun, Mar 17, 2019 at 6:09 PM Denton Liu wrote:\n>\n> The documentation used to consider\n>\n> git diff \n>\n> and\n>\n> git diff ..\n>\n> to be equal counterparts. However, rev-list-ish commands also use the\n> .. notation, but in a logically conflicting manner which\n> was confusing for some users (including me!).\n>\n> Deprecating the notation entirely is not really an option because it\n> would be an arduous process without much end-value. In addition, there\n> are some valid use-cases that we don't want to break.\n>\n> Document the preference of the first form so that future confusion can\n> be minimised.\n>\n> Signed-off-by: Denton Liu \n> ---\n>\n> Thanks all on your feedback on the discussion thread[1]! I opted for\n> just the documentation-only route so we don't break any valid use-cases.\n>\n> [1]: https://public-inbox.org/git/20190311093751.GA31092@archbookpro.localdomain/\n>\n> Documentation/git-diff.txt | 6 +++++-\n> 1 file changed, 5 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\n> index 72179d993c..10c7a2220c 100644\n> --- a/Documentation/git-diff.txt\n> +++ b/Documentation/git-diff.txt\n> @@ -63,7 +63,11 @@ two blob objects, or changes between two files on disk.\n>\n> 'git diff' [] .. [--] [...]::\n>\n> - This is synonymous to the previous form. If on\n> + This is synonymous to the previous form. However,\n> + users should prefer the previous form over this form\n> + as this form may be more confusing due to the same\n> + notation having a logically conflicting meaning in\n> + linkgit:git-rev-list[1]-ish commands. If on\n> one side is omitted, it will have the same effect as\n> using HEAD instead.\n\nThis is fine as-is. But another option to reduce even more exposure of\nthese forms (both ..[] and ...[]) is\nto delete these forms in \"DESCRIPTION\" section and add maybe \"EXOTIC\nSYNTAX\" (or something) section after \"OPTIONS\" for just them.\n\n> --\n> 2.21.0.512.g57bf1b23e1\n>\n\n\n-- \nDuy\n"},{"id":"371725","messageId":"87multaaac.fsf@evledraar.gmail.com","threadId":"50764","inReplyTo":"bc7c3f9d769b2d5a108ff4cdc3c7277e112fdb56.1552820745.git.liu.denton@gmail.com","subject":"Re: [PATCH] git-diff.txt: prefer not using ..","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2019-03-17T13:40:59Z","receivedAt":"2019-03-17T13:41:03Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Sun, Mar 17 2019, Denton Liu wrote:\n\n> The documentation used to consider\n>\n> \tgit diff \n>\n> and\n>\n> \tgit diff ..\n>\n> to be equal counterparts. However, rev-list-ish commands also use the\n> .. notation, but in a logically conflicting manner which\n> was confusing for some users (including me!).\n>\n> Deprecating the notation entirely is not really an option because it\n> would be an arduous process without much end-value. In addition, there\n> are some valid use-cases that we don't want to break.\n>\n> Document the preference of the first form so that future confusion can\n> be minimised.\n>\n> Signed-off-by: Denton Liu \n> ---\n>\n> Thanks all on your feedback on the discussion thread[1]! I opted for\n> just the documentation-only route so we don't break any valid use-cases.\n>\n> [1]: https://public-inbox.org/git/20190311093751.GA31092@archbookpro.localdomain/\n>\n> Documentation/git-diff.txt | 6 +++++-\n> 1 file changed, 5 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\n> index 72179d993c..10c7a2220c 100644\n> --- a/Documentation/git-diff.txt\n> +++ b/Documentation/git-diff.txt\n> @@ -63,7 +63,11 @@ two blob objects, or changes between two files on disk.\n>\n> 'git diff' [] .. [--] [...]::\n>\n> -\tThis is synonymous to the previous form. If on\n> +\tThis is synonymous to the previous form. However,\n> +\tusers should prefer the previous form over this form\n> +\tas this form may be more confusing due to the same\n> +\tnotation having a logically conflicting meaning in\n> +\tlinkgit:git-rev-list[1]-ish commands. If on\n> \tone side is omitted, it will have the same effect as\n> \tusing HEAD instead.\n\nI think we're better off just consistently recommending \"A..B\" instead\nof \"A B\" and \"fixing\" any occurrence of the latter to the\nformer. I.e. not taking this patch & going in the other direction.\n\nAs noted in the thread you linked we'll always need \"..\" when one side\nis \"HEAD\" implicitly, and that's a really common case.\n\nSo as confusing as the whole \"..\" v.s. \"...\" is in diff v.s. log I think\nwe're worse off with \"A B\", since we'll *still* need to document the\nlikes of \"A..\" and how that differs from log \"A..\" or \"A...\".\n\nSo sometimes using the whitespace form for two revs and then the \"..\"\nwhen we just have one side makes things more confusing, not less. The\nreader will be left having to juggle more complexity in their head, not\nless.\n"},{"id":"371726","messageId":"CACsJy8C3P93896fP8BStmYd1WMNukYV6u8gB0zgC3rKLqxgzyQ@mail.gmail.com","threadId":"50764","inReplyTo":"87multaaac.fsf@evledraar.gmail.com","subject":"Re: [PATCH] git-diff.txt: prefer not using ..","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2019-03-17T14:01:38Z","receivedAt":"2019-03-17T14:02:06Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Sun, Mar 17, 2019 at 8:41 PM Ævar Arnfjörð Bjarmason\n wrote:\n>\n>\n> On Sun, Mar 17 2019, Denton Liu wrote:\n>\n> > The documentation used to consider\n> >\n> > git diff \n> >\n> > and\n> >\n> > git diff ..\n> >\n> > to be equal counterparts. However, rev-list-ish commands also use the\n> > .. notation, but in a logically conflicting manner which\n> > was confusing for some users (including me!).\n> >\n> > Deprecating the notation entirely is not really an option because it\n> > would be an arduous process without much end-value. In addition, there\n> > are some valid use-cases that we don't want to break.\n> >\n> > Document the preference of the first form so that future confusion can\n> > be minimised.\n> >\n> > Signed-off-by: Denton Liu \n> > ---\n> >\n> > Thanks all on your feedback on the discussion thread[1]! I opted for\n> > just the documentation-only route so we don't break any valid use-cases.\n> >\n> > [1]: https://public-inbox.org/git/20190311093751.GA31092@archbookpro.localdomain/\n> >\n> > Documentation/git-diff.txt | 6 +++++-\n> > 1 file changed, 5 insertions(+), 1 deletion(-)\n> >\n> > diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\n> > index 72179d993c..10c7a2220c 100644\n> > --- a/Documentation/git-diff.txt\n> > +++ b/Documentation/git-diff.txt\n> > @@ -63,7 +63,11 @@ two blob objects, or changes between two files on disk.\n> >\n> > 'git diff' [] .. [--] [...]::\n> >\n> > - This is synonymous to the previous form. If on\n> > + This is synonymous to the previous form. However,\n> > + users should prefer the previous form over this form\n> > + as this form may be more confusing due to the same\n> > + notation having a logically conflicting meaning in\n> > + linkgit:git-rev-list[1]-ish commands. If on\n> > one side is omitted, it will have the same effect as\n> > using HEAD instead.\n>\n> I think we're better off just consistently recommending \"A..B\" instead\n> of \"A B\" and \"fixing\" any occurrence of the latter to the\n> former. I.e. not taking this patch & going in the other direction.\n>\n> As noted in the thread you linked we'll always need \"..\" when one side\n> is \"HEAD\" implicitly, and that's a really common case.\n\nYou could just type \" @\" instead of \"..\". And that one is easier to explain.\n\n> So as confusing as the whole \"..\" v.s. \"...\" is in diff v.s. log I think\n> we're worse off with \"A B\", since we'll *still* need to document the\n> likes of \"A..\" and how that differs from log \"A..\" or \"A...\".\n>\n> So sometimes using the whitespace form for two revs and then the \"..\"\n> when we just have one side makes things more confusing, not less. The\n> reader will be left having to juggle more complexity in their head, not\n> less.\n-- \nDuy\n"},{"id":"371727","messageId":"87lg1da8uj.fsf@evledraar.gmail.com","threadId":"50764","inReplyTo":"CACsJy8C3P93896fP8BStmYd1WMNukYV6u8gB0zgC3rKLqxgzyQ@mail.gmail.com","subject":"Re: [PATCH] git-diff.txt: prefer not using ..","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2019-03-17T14:12:04Z","receivedAt":"2019-03-17T14:12:09Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Sun, Mar 17 2019, Duy Nguyen wrote:\n\n> On Sun, Mar 17, 2019 at 8:41 PM Ævar Arnfjörð Bjarmason\n> wrote:\n>>\n>>\n>> On Sun, Mar 17 2019, Denton Liu wrote:\n>>\n>> > The documentation used to consider\n>> >\n>> > git diff \n>> >\n>> > and\n>> >\n>> > git diff ..\n>> >\n>> > to be equal counterparts. However, rev-list-ish commands also use the\n>> > .. notation, but in a logically conflicting manner which\n>> > was confusing for some users (including me!).\n>> >\n>> > Deprecating the notation entirely is not really an option because it\n>> > would be an arduous process without much end-value. In addition, there\n>> > are some valid use-cases that we don't want to break.\n>> >\n>> > Document the preference of the first form so that future confusion can\n>> > be minimised.\n>> >\n>> > Signed-off-by: Denton Liu \n>> > ---\n>> >\n>> > Thanks all on your feedback on the discussion thread[1]! I opted for\n>> > just the documentation-only route so we don't break any valid use-cases.\n>> >\n>> > [1]: https://public-inbox.org/git/20190311093751.GA31092@archbookpro.localdomain/\n>> >\n>> > Documentation/git-diff.txt | 6 +++++-\n>> > 1 file changed, 5 insertions(+), 1 deletion(-)\n>> >\n>> > diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\n>> > index 72179d993c..10c7a2220c 100644\n>> > --- a/Documentation/git-diff.txt\n>> > +++ b/Documentation/git-diff.txt\n>> > @@ -63,7 +63,11 @@ two blob objects, or changes between two files on disk.\n>> >\n>> > 'git diff' [] .. [--] [...]::\n>> >\n>> > - This is synonymous to the previous form. If on\n>> > + This is synonymous to the previous form. However,\n>> > + users should prefer the previous form over this form\n>> > + as this form may be more confusing due to the same\n>> > + notation having a logically conflicting meaning in\n>> > + linkgit:git-rev-list[1]-ish commands. If on\n>> > one side is omitted, it will have the same effect as\n>> > using HEAD instead.\n>>\n>> I think we're better off just consistently recommending \"A..B\" instead\n>> of \"A B\" and \"fixing\" any occurrence of the latter to the\n>> former. I.e. not taking this patch & going in the other direction.\n>>\n>> As noted in the thread you linked we'll always need \"..\" when one side\n>> is \"HEAD\" implicitly, and that's a really common case.\n>\n> You could just type \" @\" instead of \"..\". And that one is easier to explain.\n\nSure, and if we're going to change our docs to consistently use @ at\neither side of such ranges instead of the empty string for \"HEAD\" I\nthink that's worth discussing if the goal is to get rid of \"..\" for\n\"diff\".\n\nI'm commenting on the in-between state being more confusing to users,\nwhich is as far as this patch gets us.\n\n>> So as confusing as the whole \"..\" v.s. \"...\" is in diff v.s. log I think\n>> we're worse off with \"A B\", since we'll *still* need to document the\n>> likes of \"A..\" and how that differs from log \"A..\" or \"A...\".\n>>\n>> So sometimes using the whitespace form for two revs and then the \"..\"\n>> when we just have one side makes things more confusing, not less. The\n>> reader will be left having to juggle more complexity in their head, not\n>> less.\n"},{"id":"371783","messageId":"xmqq5zsg3cl6.fsf@gitster-ct.c.googlers.com","threadId":"50764","inReplyTo":"CACsJy8DU02_kOqAHhU5EgMHKmkNSGdvt+7XzSHoZDB+b9sDRqg@mail.gmail.com","subject":"Re: [PATCH] git-diff.txt: prefer not using ..","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-03-18T06:45:25Z","receivedAt":"2019-03-18T06:45:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Duy Nguyen writes:\n\n>> - This is synonymous to the previous form. If on\n>> + This is synonymous to the previous form. However,\n>> + users should prefer the previous form over this form\n>> + as this form may be more confusing due to the same\n>> + notation having a logically conflicting meaning in\n>> + linkgit:git-rev-list[1]-ish commands. If on\n>> one side is omitted, it will have the same effect as\n>> using HEAD instead.\n>\n> This is fine as-is. But another option to reduce even more exposure of\n> these forms (both ..[] and ...[]) is\n> to delete these forms in \"DESCRIPTION\" section and add maybe \"EXOTIC\n> SYNTAX\" (or something) section after \"OPTIONS\" for just them.\n\nThere is no other way to express A...B (well, short of spelling it\nout as \"$(git merge-base A B) B\"), so while it makes quite a lot of\nsense to discourage A..B (simply because .. is unnecessary and can\nbe replace with a string with one fewer letter in it, namely \" \"),\nI am not sure if it is wise to throw the three-dot form into the\nsame basket.\n\n"},{"id":"371784","messageId":"xmqq1s343chd.fsf@gitster-ct.c.googlers.com","threadId":"50764","inReplyTo":"87lg1da8uj.fsf@evledraar.gmail.com","subject":"Re: [PATCH] git-diff.txt: prefer not using ..","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-03-18T06:47:42Z","receivedAt":"2019-03-18T06:47:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Sure, and if we're going to change our docs to consistently use @ at\n> either side of such ranges instead of the empty string for \"HEAD\" I\n> think that's worth discussing if the goal is to get rid of \"..\" for\n> \"diff\".\n>\n> I'm commenting on the in-between state being more confusing to users,\n> which is as far as this patch gets us.\n\nYuck. Let's not spread the @ disease. We are not Perl where being\ncloser to line noise is somehow considered cool. Spell it out as\nHEAD, please.\n"},{"id":"371829","messageId":"CABPp-BGijBpyV9n4VxNi3QCddO-_4B-E1TUTi8wiqjQmqpU+Nw@mail.gmail.com","threadId":"50764","inReplyTo":"87multaaac.fsf@evledraar.gmail.com","subject":"Re: [PATCH] git-diff.txt: prefer not using ..","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2019-03-18T17:46:27Z","receivedAt":"2019-03-18T17:46:42Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Sun, Mar 17, 2019 at 6:41 AM Ævar Arnfjörð Bjarmason\n wrote:\n> On Sun, Mar 17 2019, Denton Liu wrote:\n>\n> > diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\n> > index 72179d993c..10c7a2220c 100644\n> > --- a/Documentation/git-diff.txt\n> > +++ b/Documentation/git-diff.txt\n> > @@ -63,7 +63,11 @@ two blob objects, or changes between two files on disk.\n> >\n> > 'git diff' [] .. [--] [...]::\n> >\n> > - This is synonymous to the previous form. If on\n> > + This is synonymous to the previous form. However,\n> > + users should prefer the previous form over this form\n> > + as this form may be more confusing due to the same\n> > + notation having a logically conflicting meaning in\n> > + linkgit:git-rev-list[1]-ish commands. If on\n> > one side is omitted, it will have the same effect as\n> > using HEAD instead.\n>\n> I think we're better off just consistently recommending \"A..B\" instead\n> of \"A B\" and \"fixing\" any occurrence of the latter to the\n> former. I.e. not taking this patch & going in the other direction.\n>\n> As noted in the thread you linked we'll always need \"..\" when one side\n> is \"HEAD\" implicitly, and that's a really common case.\n\nBy \"really common\" do you simply mean it is used by enough people that\nit should be supported, or are you trying to claim something about\nit's relative usage compared to \"diff A B\"?\n\n> So as confusing as the whole \"..\" v.s. \"...\" is in diff v.s. log I think\n> we're worse off with \"A B\", since we'll *still* need to document the\n> likes of \"A..\" and how that differs from log \"A..\" or \"A...\".\n>\n> So sometimes using the whitespace form for two revs and then the \"..\"\n> when we just have one side makes things more confusing, not less. The\n> reader will be left having to juggle more complexity in their head, not\n> less.\n\nHere I think you are implying that \"A..\" or \"..A\" is somehow on a\nsimilar magnitude of usage as \"A B\". Is that accurate? If that\nreflected real-world usage, I would be more inclined to agree with\nyour course of action, but I can't fathom them having similar usage\nrates. Personally, I don't think I've ever seen any user use \"A..\" or\n\"..A\" (well, except me), and only rarely even use \"A..B\"; with users I\nhave worked with and supported and taught, I'd guess \"diff A B\" is\nused far more (at least an order of magnitude more) than any other\nform, and that only some of them and only occasionally want to use\nanything else, such as diffing against a merge base.\n\nThis whole topic came up again, IMO, because for the occasional\nusecase of diffing against a merge-base, people's intuition leads them\nto '..' instead of '...', and we wanted to fix or help avoid that\nproblem. To me, your solution sounds like you want to instead embrace\nthe confusion: force people to deal with it early and often so that\nthey become trained on it and can articulate the differences between\n'..' and '...' for both diff and log. Is that accurate, or am I\nmisunderstanding/mis-stating your strategy?\n"},{"id":"371833","messageId":"CABPp-BEy9nN=aV8Y+ueYqv299umHoF2E=8D7heJARM4Qa7P5JQ@mail.gmail.com","threadId":"50764","inReplyTo":"bc7c3f9d769b2d5a108ff4cdc3c7277e112fdb56.1552820745.git.liu.denton@gmail.com","subject":"Re: [PATCH] git-diff.txt: prefer not using ..","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2019-03-18T17:59:56Z","receivedAt":"2019-03-18T18:00:12Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"Hi Denton,\n\nThanks for working on this. Some thoughts...\n\nOn Sun, Mar 17, 2019 at 4:09 AM Denton Liu wrote:\n>\n> The documentation used to consider\n>\n> git diff \n>\n> and\n>\n> git diff ..\n>\n> to be equal counterparts. However, rev-list-ish commands also use the\n> .. notation, but in a logically conflicting manner which\n> was confusing for some users (including me!).\n>\n> Deprecating the notation entirely is not really an option because it\n> would be an arduous process without much end-value. In addition, there\n> are some valid use-cases that we don't want to break.\n\nYes, there were multiple people who commented that they liked to\ncopy-paste the \"A..B\" output from fetch/pull in combination with diff\nand log (even though one suggested that this gave the wrong output and\nwhat they really wanted was \"diff A...B\").\n\nHowever, \"removal of functionality\" isn't the only form of\ndeprecation/warning. Updating the manpage is another one which you\nimplemented, but I'd like to suggest yet another: Prefix the diff with\na warning message, e.g.\n\n\"WARNING: You ran 'git diff A..B' (which means the same thing as 'git\ndiff A B'). Many users confuse 'git diff A..B' and 'git diff A...B'.\nPlease see 'git diff --help' for more details.\"\n\nHaving extra text (e.g. commit message or warning) at the beginning of\nthe diff does not prevent tools like patch(1) or git-apply(1) from\nsuccessfully applying it, it still makes sense to humans (and who as\nan added bonus happen to be really good at filtering out common\nmessages if they do encounter them more than a few times), and gives\nus a chance in the future to figure out how to potentially extend the\nmessage to make it a deprecation warning and/or provide details about\nhow to change the behavior of '..' to either be an error or behave\nlike triple dots or just not warn.\n\n\nElijah\n"},{"id":"371836","messageId":"87mulsdmsi.fsf@evledraar.gmail.com","threadId":"50764","inReplyTo":"CABPp-BGijBpyV9n4VxNi3QCddO-_4B-E1TUTi8wiqjQmqpU+Nw@mail.gmail.com","subject":"Re: [PATCH] git-diff.txt: prefer not using ..","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2019-03-18T19:07:09Z","receivedAt":"2019-03-18T19:07:15Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Mon, Mar 18 2019, Elijah Newren wrote:\n\n> On Sun, Mar 17, 2019 at 6:41 AM Ævar Arnfjörð Bjarmason\n> wrote:\n>> On Sun, Mar 17 2019, Denton Liu wrote:\n>>\n>> > diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\n>> > index 72179d993c..10c7a2220c 100644\n>> > --- a/Documentation/git-diff.txt\n>> > +++ b/Documentation/git-diff.txt\n>> > @@ -63,7 +63,11 @@ two blob objects, or changes between two files on disk.\n>> >\n>> > 'git diff' [] .. [--] [...]::\n>> >\n>> > - This is synonymous to the previous form. If on\n>> > + This is synonymous to the previous form. However,\n>> > + users should prefer the previous form over this form\n>> > + as this form may be more confusing due to the same\n>> > + notation having a logically conflicting meaning in\n>> > + linkgit:git-rev-list[1]-ish commands. If on\n>> > one side is omitted, it will have the same effect as\n>> > using HEAD instead.\n>>\n>> I think we're better off just consistently recommending \"A..B\" instead\n>> of \"A B\" and \"fixing\" any occurrence of the latter to the\n>> former. I.e. not taking this patch & going in the other direction.\n>>\n>> As noted in the thread you linked we'll always need \"..\" when one side\n>> is \"HEAD\" implicitly, and that's a really common case.\n>\n> By \"really common\" do you simply mean it is used by enough people that\n> it should be supported, or are you trying to claim something about\n> it's relative usage compared to \"diff A B\"?\n>\n>> So as confusing as the whole \"..\" v.s. \"...\" is in diff v.s. log I think\n>> we're worse off with \"A B\", since we'll *still* need to document the\n>> likes of \"A..\" and how that differs from log \"A..\" or \"A...\".\n>>\n>> So sometimes using the whitespace form for two revs and then the \"..\"\n>> when we just have one side makes things more confusing, not less. The\n>> reader will be left having to juggle more complexity in their head, not\n>> less.\n>\n> Here I think you are implying that \"A..\" or \"..A\" is somehow on a\n> similar magnitude of usage as \"A B\". Is that accurate? If that\n> reflected real-world usage, I would be more inclined to agree with\n> your course of action, but I can't fathom them having similar usage\n> rates. Personally, I don't think I've ever seen any user use \"A..\" or\n> \"..A\" (well, except me), and only rarely even use \"A..B\"; with users I\n> have worked with and supported and taught, I'd guess \"diff A B\" is\n> used far more (at least an order of magnitude more) than any other\n> form, and that only some of them and only occasionally want to use\n> anything else, such as diffing against a merge base.\n>\n> This whole topic came up again, IMO, because for the occasional\n> usecase of diffing against a merge-base, people's intuition leads them\n> to '..' instead of '...', and we wanted to fix or help avoid that\n> problem. To me, your solution sounds like you want to instead embrace\n> the confusion: force people to deal with it early and often so that\n> they become trained on it and can articulate the differences between\n> '..' and '...' for both diff and log. Is that accurate, or am I\n> misunderstanding/mis-stating your strategy?\n\nSome of this thread's confusing, and on re-reading I see my reply hasn't\nhelped much.\n\nTo clarify. There's at least these things to consider:\n\n1. What should the semantics of .. or ... be?\n2. What semantics (regardless of syntax) should we recommend for common cases?\n3. Depending on #1 and #2, can we make our docs less confusing?\n\nMy opinion:\n\n1. I'd ideally like to switch the semantics of \"..\" and \"...\". I don't\n think anyone argues that it would be a bad thing in theory if we'd\n started out that way, Whether it's worth switching now is another\n matter.\n\n Junio chimed in in \n saying he's not for it, so I'm assuming it's out for now.\n\n2. I agree that we should generally recommend what's now \"...\" instead\n of \"..\", whatever the syntax is to invoke that.\n\n3. And now, coming to the point I was trying to make. Assuming we'd like\n to go for #2 as I noted, and switching them around as in #1 is a\n no-go, what syntax should we prefer for \"X..Z\", aka. \"X Y\"?\n\n I think to reduce doc confusion we'd be better of using \"..\"\n consistently over the whitespace form, since we're going to need to\n show diffs with HEAD on one side. Using either \"@\" or \"HEAD\" there is\n more verbose.\n\n So yeah, I guess I am in a narrow sense advocating for embracing the\n confusion. I'd rather not have it in the first place, but since we\n seem stuck with it let's at least stick with and recommend *one*\n syntax for that confusion, and pick the one we can consistently use\n for 100% of our examples.\n\nAnecdotally I've seen \"..\" in all forms be *way* more common among\nusers, even though if you sat them down and explained to them what it\ndoes v.s. \"...\" they'd usually say they wanted the latter.\n\nI did some brief scraping of .bash_history on one of our big shared\nservers just now that has a lot of users (100-200) using git for daily\ndevelopment. I've got many pages of things like \"@{u}..\",\n\"..\", \".. -- \" etc. against just a couple of uses\nof \"...\". The \" \" form gets a bit of use, but maybe 1/2 of\n\"..\".\n"},{"id":"371867","messageId":"xmqqy35by94j.fsf@gitster-ct.c.googlers.com","threadId":"50764","inReplyTo":"87mulsdmsi.fsf@evledraar.gmail.com","subject":"Re: [PATCH] git-diff.txt: prefer not using ..","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-03-19T00:56:44Z","receivedAt":"2019-03-19T00:56:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Some of this thread's confusing, and on re-reading I see my reply hasn't\n> helped much.\n>\n> To clarify. There's at least these things to consider:\n>\n> 1. What should the semantics of .. or ... be?\n> 2. What semantics (regardless of syntax) should we recommend for common cases?\n> 3. Depending on #1 and #2, can we make our docs less confusing?\n\nNice way to summarise.\n\n> My opinion:\n>\n> 1. I'd ideally like to switch the semantics of \"..\" and \"...\". I don't\n> think anyone argues that it would be a bad thing in theory if we'd\n> started out that way, Whether it's worth switching now is another\n> matter.\n>\n> Junio chimed in in \n> saying he's not for it, so I'm assuming it's out for now.\n\nI do agree with the \"in the ideal world, where we didn't have any\nexisting users and had perfect foresight back when invention of\nthree-dot form for 'log' was even a few months away down the road,\nwe would have used diff A...B for the two-endpoints\", and I also\nagree with \"that is 10 years or more too late now---don't waste time\neven pondering about it\".\n>\n> 2. I agree that we should generally recommend what's now \"...\" instead\n> of \"..\", whatever the syntax is to invoke that.\n\nI do not agree with this at all. When I want to compare what is in\ndevel and what is in master, I may be interested in two completely\ndifferent things depending on why I am doing the comparison.\n\n - I may want to know \"what is in the development track that is yet\n to be merged to 'master'\".\n\n - Or I may be looking for \"what is the difference between the master\n branch and the development branch.\"\n\nThe latter should match the former if 'devel' and 'master' means\nwhat we generally think they are, and by looking at the latter, I\ncan find what would be missed if I wholesale replace 'master' with\n'devel' before merging 'master' backwards into 'devel' to make the\nlatter catch up. So even in that context, I would prefer to see the\nlatter (needless to say, the start-up cost is far less for the\nlatter than for the former).\n\nWhen we discuss a more generic \"two endpoints comparison\" whose\nrelationship between the two endpoints is not as well-defined as\n'devel' and 'master' (i.e. what does it mean to compare v1.2.1 and\nv1.3.4?), I can phrase in human-understandable terms what \"..\" does,\nbut not what \"...\" does. I have no idea how you or anybody can say\nthat \"we should generally recommend\" that the former is the norm and\ntwo-endpoint comparison is an exception.\n"},{"id":"371868","messageId":"20190319011217.GA20393@dev-l","threadId":"50764","inReplyTo":"xmqq5zsg3cl6.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] git-diff.txt: prefer not using ..","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-03-19T01:12:17Z","receivedAt":"2019-03-19T01:12:22Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"On Mon, Mar 18, 2019 at 03:45:25PM +0900, Junio C Hamano wrote:\n> Duy Nguyen writes:\n> \n> >> - This is synonymous to the previous form. If on\n> >> + This is synonymous to the previous form. However,\n> >> + users should prefer the previous form over this form\n> >> + as this form may be more confusing due to the same\n> >> + notation having a logically conflicting meaning in\n> >> + linkgit:git-rev-list[1]-ish commands. If on\n> >> one side is omitted, it will have the same effect as\n> >> using HEAD instead.\n> >\n> > This is fine as-is. But another option to reduce even more exposure of\n> > these forms (both ..[] and ...[]) is\n> > to delete these forms in \"DESCRIPTION\" section and add maybe \"EXOTIC\n> > SYNTAX\" (or something) section after \"OPTIONS\" for just them.\n> \n> There is no other way to express A...B (well, short of spelling it\n> out as \"$(git merge-base A B) B\"), so while it makes quite a lot of\n> sense to discourage A..B (simply because .. is unnecessary and can\n> be replace with a string with one fewer letter in it, namely \" \"),\n> I am not sure if it is wise to throw the three-dot form into the\n> same basket.\n> \n\nPerhaps we could add an option to use the base as a comparison,\nsomething like \"git diff --compare-base A B\" which would mean \n\"git diff $(git merge-base A B) B\".\n\nIf we do this, we could keep feature-parity while deprecating the\nconfusing \"range-notation\" for diff. Then, we could possibly move .. and\n... into a \"RANGE-BASED SYNTAX\" section and call it a day.\n\nI now personally don't think that deprecating it in the code (or even\nadding a warning) would be worth the effort since the syntax is so\ningrained in common usage. However, I believe that we should encourage\nnew users to avoid the range-syntax if possible.\n"},{"id":"372008","messageId":"CABPp-BGymk=FLvC7m4WB3vVi3oObgNkOPQ_TeOWEC=L0kZaRsA@mail.gmail.com","threadId":"50764","inReplyTo":"87mulsdmsi.fsf@evledraar.gmail.com","subject":"Re: [PATCH] git-diff.txt: prefer not using ..","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2019-03-20T14:21:17Z","receivedAt":"2019-03-20T14:21:37Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Mon, Mar 18, 2019 at 12:07 PM Ævar Arnfjörð Bjarmason\n wrote:\n> On Mon, Mar 18 2019, Elijah Newren wrote:\n>\n> > On Sun, Mar 17, 2019 at 6:41 AM Ævar Arnfjörð Bjarmason\n> > wrote:\n> >> On Sun, Mar 17 2019, Denton Liu wrote:\n> >>\n\n> Some of this thread's confusing, and on re-reading I see my reply hasn't\n> helped much.\n>\n> To clarify. There's at least these things to consider:\n>\n> 1. What should the semantics of .. or ... be?\n> 2. What semantics (regardless of syntax) should we recommend for common cases?\n> 3. Depending on #1 and #2, can we make our docs less confusing?\n\nThat's a good framework; thanks for clarifying. Junio has weighed in\nalready, but there were two other things I thought I'd still comment\non. First, I think this list could use another item, related to #3:\n\n4. Given backward compatibility and existing use-case constraints, is\nthere at least a way to warn users of possible confusion besides just\nthe docs?\n\nI suggested one answer elsewhere in this thread (cf.\nCABPp-BEy9nN=aV8Y+ueYqv299umHoF2E=8D7heJARM4Qa7P5JQ@mail.gmail.com);\nnot sure what others think of it yet.\n\n> Anecdotally I've seen \"..\" in all forms be *way* more common among\n> users, even though if you sat them down and explained to them what it\n> does v.s. \"...\" they'd usually say they wanted the latter.\n>\n> I did some brief scraping of .bash_history on one of our big shared\n> servers just now that has a lot of users (100-200) using git for daily\n> development. I've got many pages of things like \"@{u}..\",\n> \"..\", \".. -- \" etc. against just a couple of uses\n> of \"...\". The \" \" form gets a bit of use, but maybe 1/2 of\n> \"..\".\n\nWow, that is extremely surprising to me. I have no mechanism to\naccess any such data (nor any mechanism for pushing new git versions\nout to users other than sending out an email about new upstream\nreleases and asking them to update). So, I did the next best thing\nand sent out a poll to developers (all of whom use git daily); there's\na self-selection bias in the responses that probably tilts away from\nnovice users, but it's all I had:\n\nWhich do you use the most?\n1.`git diff A B` `11`\n2. `git diff A..B` `2`\n3. `git diff A...B`\n4. I never use any of these `5`\n\nThe responses were 11 for #1 (with a number expressing in follow-ups\nthat it was the only form of these three they ever used, though some\nstill used other forms sometimes), 2 for #2 (one of whom responded to\nrequests for more details and found out he was using it wrong and that\nhe could save a character by using form #1 in cases where A was the\nmerge base, which he was happy about), 0 for #3, and 5 for #4.\n\nThat was still a lot more voting for the '..' form than I expected,\nbut still far less than what you have seen. I wonder if there's a\nregional difference?\n"},{"id":"372011","messageId":"20190320172809.GA17593@dev-l","threadId":"50764","inReplyTo":"CABPp-BEy9nN=aV8Y+ueYqv299umHoF2E=8D7heJARM4Qa7P5JQ@mail.gmail.com","subject":"Re: [PATCH] git-diff.txt: prefer not using ..","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2019-03-20T17:28:09Z","receivedAt":"2019-03-20T17:28:35Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"Hi Elijah,\n\nSorry for the late reply, I've been mulling over it for the past couple\nof days.\n\nOn Mon, Mar 18, 2019 at 10:59:56AM -0700, Elijah Newren wrote:\n> Hi Denton,\n> \n> Thanks for working on this. Some thoughts...\n> \n> On Sun, Mar 17, 2019 at 4:09 AM Denton Liu wrote:\n> >\n> > The documentation used to consider\n> >\n> > git diff \n> >\n> > and\n> >\n> > git diff ..\n> >\n> > to be equal counterparts. However, rev-list-ish commands also use the\n> > .. notation, but in a logically conflicting manner which\n> > was confusing for some users (including me!).\n> >\n> > Deprecating the notation entirely is not really an option because it\n> > would be an arduous process without much end-value. In addition, there\n> > are some valid use-cases that we don't want to break.\n> \n> Yes, there were multiple people who commented that they liked to\n> copy-paste the \"A..B\" output from fetch/pull in combination with diff\n> and log (even though one suggested that this gave the wrong output and\n> what they really wanted was \"diff A...B\").\n> \n> However, \"removal of functionality\" isn't the only form of\n> deprecation/warning. Updating the manpage is another one which you\n> implemented, but I'd like to suggest yet another: Prefix the diff with\n> a warning message, e.g.\n> \n> \"WARNING: You ran 'git diff A..B' (which means the same thing as 'git\n> diff A B'). Many users confuse 'git diff A..B' and 'git diff A...B'.\n> Please see 'git diff --help' for more details.\"\n> \n> Having extra text (e.g. commit message or warning) at the beginning of\n> the diff does not prevent tools like patch(1) or git-apply(1) from\n> successfully applying it, it still makes sense to humans (and who as\n> an added bonus happen to be really good at filtering out common\n> messages if they do encounter them more than a few times), and gives\n> us a chance in the future to figure out how to potentially extend the\n> message to make it a deprecation warning and/or provide details about\n> how to change the behavior of '..' to either be an error or behave\n> like triple dots or just not warn.\n> \n> \n> Elijah\n\nI was originally planning on doing something like this (by warning to\nstderr, but your idea actually gets to the user ;) ). The only thing I'm\nworried about for a change like this is that it'll be very controversial\nsince, as we could see anecdotally, a lot of people have trained\nthemselves to use the .. form.\n\nIn terms of backwards compatibility, I think that there's the\npossibility of breaking some scripts by doing this change but we could\nmitigate this by detecting if we're outputting to a terminal and only\nprint the message in that case.\n\nThanks for the suggestion!\n\nDenton\n"},{"id":"372126","messageId":"CABPp-BGg_iSx3QMc-J4Fov97v9NnAtfxZGMrm3WfrGugOThjmA@mail.gmail.com","threadId":"50764","inReplyTo":"20190320172809.GA17593@dev-l","subject":"Re: [PATCH] git-diff.txt: prefer not using ..","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2019-03-21T13:58:31Z","receivedAt":"2019-03-21T13:58:46Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"Hi Denton,\n\nOn Wed, Mar 20, 2019 at 10:28 AM Denton Liu wrote:\n>\n> Hi Elijah,\n>\n> Sorry for the late reply, I've been mulling over it for the past couple\n> of days.\n\nNo worries; thanks for thinking about it.\n\n> On Mon, Mar 18, 2019 at 10:59:56AM -0700, Elijah Newren wrote:\n> > On Sun, Mar 17, 2019 at 4:09 AM Denton Liu wrote:\n> > >\n> > > The documentation used to consider\n> > >\n> > > git diff \n> > >\n> > > and\n> > >\n> > > git diff ..\n> > >\n> > > to be equal counterparts. However, rev-list-ish commands also use the\n> > > .. notation, but in a logically conflicting manner which\n> > > was confusing for some users (including me!).\n> > >\n> > > Deprecating the notation entirely is not really an option because it\n> > > would be an arduous process without much end-value. In addition, there\n> > > are some valid use-cases that we don't want to break.\n> >\n> > Yes, there were multiple people who commented that they liked to\n> > copy-paste the \"A..B\" output from fetch/pull in combination with diff\n> > and log (even though one suggested that this gave the wrong output and\n> > what they really wanted was \"diff A...B\").\n> >\n> > However, \"removal of functionality\" isn't the only form of\n> > deprecation/warning. Updating the manpage is another one which you\n> > implemented, but I'd like to suggest yet another: Prefix the diff with\n> > a warning message, e.g.\n> >\n> > \"WARNING: You ran 'git diff A..B' (which means the same thing as 'git\n> > diff A B'). Many users confuse 'git diff A..B' and 'git diff A...B'.\n> > Please see 'git diff --help' for more details.\"\n> >\n> > Having extra text (e.g. commit message or warning) at the beginning of\n> > the diff does not prevent tools like patch(1) or git-apply(1) from\n> > successfully applying it, it still makes sense to humans (and who as\n> > an added bonus happen to be really good at filtering out common\n> > messages if they do encounter them more than a few times), and gives\n> > us a chance in the future to figure out how to potentially extend the\n> > message to make it a deprecation warning and/or provide details about\n> > how to change the behavior of '..' to either be an error or behave\n> > like triple dots or just not warn.\n>\n> I was originally planning on doing something like this (by warning to\n> stderr, but your idea actually gets to the user ;) ). The only thing I'm\n> worried about for a change like this is that it'll be very controversial\n> since, as we could see anecdotally, a lot of people have trained\n> themselves to use the .. form.\n>\n> In terms of backwards compatibility, I think that there's the\n> possibility of breaking some scripts by doing this change but we could\n> mitigate this by detecting if we're outputting to a terminal and only\n> print the message in that case.\n\nI don't see why anything would break if we just always showed the\nwarning. git diff's purpose is to create a \"patch\", and as such can\nbe used by the patch(1) command. We added additional headers in 'git\ndiff' relative to diff(1), but it's still understandable by patch. We\nalso created git-apply because it could potentially make use of the\nextra headers to do slightly smarter stuff than patch. But both allow\narbitrary extra initial text as long as it doesn't have the relevant\nstart-of-next-diff-hunk characters. Extra text at the beginning (an\nexplanation or a commit message or a warning or whatever) thus doesn't\nchange it from being a valid patch.\n\nHuman beings will see a little extra text by default, but they already\nusually skip right over the diff headers when reading; this is\nessentially just another diff header. And we could provide them with\na config option to turn it off if they used it all the time and found\nthe two extra lines of text annoying.\n\nSince both Ævar and I noted that even among people who use '..' lots\nof them use it erroneously, it seems like a worthwhile warning to add,\nto me at least. That is, unless I've misunderstood my purpose of\n'git-diff' as creating a patch or missed something else important.\n\n\nAnyway, just my $0.02. (And I'd be happy to take this on later if you\ndon't want to).\nElijah\n"},{"id":"372129","messageId":"nycvar.QRO.7.76.6.1903211511031.41@tvgsbejvaqbjf.bet","threadId":"50764","inReplyTo":"xmqq5zsg3cl6.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] git-diff.txt: prefer not using ..","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2019-03-21T14:12:53Z","receivedAt":"2019-03-21T14:13:28Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Junio,\n\nOn Mon, 18 Mar 2019, Junio C Hamano wrote:\n\n> Duy Nguyen writes:\n>\n> >> - This is synonymous to the previous form. If on\n> >> + This is synonymous to the previous form. However,\n> >> + users should prefer the previous form over this form\n> >> + as this form may be more confusing due to the same\n> >> + notation having a logically conflicting meaning in\n> >> + linkgit:git-rev-list[1]-ish commands. If on\n> >> one side is omitted, it will have the same effect as\n> >> using HEAD instead.\n> >\n> > This is fine as-is. But another option to reduce even more exposure of\n> > these forms (both ..[] and ...[]) is\n> > to delete these forms in \"DESCRIPTION\" section and add maybe \"EXOTIC\n> > SYNTAX\" (or something) section after \"OPTIONS\" for just them.\n>\n> There is no other way to express A...B (well, short of spelling it\n> out as \"$(git merge-base A B) B\"), so while it makes quite a lot of\n> sense to discourage A..B (simply because .. is unnecessary and can\n> be replace with a string with one fewer letter in it, namely \" \"),\n> I am not sure if it is wise to throw the three-dot form into the\n> same basket.\n\nI just happened to come upon a use case where the `A..B` way is not\nactually useless: just after fetching a branch, I got the usual update\nlines, and it is pretty convenient to be able to use them not only for\n`git log`, but also for `git diff` invocations, to see what actually\nchanged (from two angles).\n\nSo maybe you could register this as a vote to not totally strike the A..B\nnotation from the manual.\n\nCiao,\nDscho\n"}]}