{"thread":{"id":"44866","subject":"Bug report: Documentation error in git-bisect man description","startedAt":"2017-01-12T23:13:38Z","lastAt":"2017-01-13T01:39:13Z","messageCount":6,"participants":["Manuel Ullmann","Junio C Hamano","Christian Couder"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"309303","messageId":"87r347swz1.fsf@sonnengebleicht.fritz.box","threadId":"44866","inReplyTo":null,"subject":"Bug report: Documentation error in git-bisect man description","fromName":"Manuel Ullmann","fromEmail":"ullman.alias@posteo.de","sentAt":"2017-01-12T23:02:42Z","receivedAt":"2017-01-12T23:13:38Z","isPatch":false,"sender":{"key":"ullman.alias@posteo.de","avatar":null},"body":"Hi,\n\nthere is a mistake in the git-bisect description.\nThe second paragraph of it says ‘the terms \"old\" and \"new\" can be used\nin place of \"good\" and \"bad\"’. So from a logical point of view the\ndescription part stating the usage syntax should be:\n\ngit bisect (bad|good) [<rev>]\ngit bisect (old|new) [<rev>...]\n\ninstead of\n\ngit bisect (bad|new) [<rev>]\ngit bisect (good|old) [<rev>...]\n\nChecked man page version of 2.11.0, but it is in my local 2.10.2 git as well.\n\nBest regards,\nManuel\n"},{"id":"309305","messageId":"xmqqd1frj1lt.fsf@gitster.mtv.corp.google.com","threadId":"44866","inReplyTo":"87r347swz1.fsf@sonnengebleicht.fritz.box","subject":"Re: Bug report: Documentation error in git-bisect man description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-12T23:32:46Z","receivedAt":"2017-01-12T23:32:54Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Manuel Ullmann <ullman.alias@posteo.de> writes:\n\n> Hi,\n>\n> there is a mistake in the git-bisect description.\n> The second paragraph of it says ‘the terms \"old\" and \"new\" can be used\n> in place of \"good\" and \"bad\"’. So from a logical point of view the\n> description part stating the usage syntax should be:\n>\n> git bisect (bad|good) [<rev>]\n> git bisect (old|new) [<rev>...]\n>\n> instead of\n>\n> git bisect (bad|new) [<rev>]\n> git bisect (good|old) [<rev>...]\n>\n> Checked man page version of 2.11.0, but it is in my local 2.10.2 git as well.\n\nHmmm, I tend to agree, modulo a minor fix.\n\nIf the description were in a context inside a paragraph like this:\n\n\tWhen you want to tell 'git bisect' that a <rev> belongs to\n\tthe newer half of the history, you say\n\n\t\tgit bisect (bad|new) [<rev>]\n\n\tOn the other hand, when you want to tell 'git bisect' that a\n\t<rev> belongs to the older half of the history, you can say\n\n\t\tgit bisect (good|old) [<rev>]\n\nthen the pairing we see in the current text makes quite a lot of\nsense.\n\nBut in the early part of the description section, listing the\ninformation that logically belongs to the synopsis section, I think\nthe current one is misleading.  You are painting commits with two\ncolors, and if you are from the \"older vs newer\" school, you say\neither 'old' or 'new' as the names of these two colors, and do not\nuse 'bad' or 'good'.  A line with \"git bisect (old|new) [<rev>]\" in\nthe list would make more sense.\n\nSimilarly, if you are from the \"still good vs already bad\" school,\nyou would either say 'good' or 'bad' so you would want to see a line\nwith \"git bisect (good|bad) [<rev>]\" in the list (not \"bad|good\" in\nthat order, but opposite).\n\nChristian, am I talking nonsense?\n"},{"id":"309306","messageId":"xmqq8tqfj15z.fsf@gitster.mtv.corp.google.com","threadId":"44866","inReplyTo":"xmqqd1frj1lt.fsf@gitster.mtv.corp.google.com","subject":"Re: Bug report: Documentation error in git-bisect man description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-01-12T23:42:16Z","receivedAt":"2017-01-12T23:42:39Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Manuel Ullmann <ullman.alias@posteo.de> writes:\n>\n> Hmmm, I tend to agree, modulo a minor fix.\n>\n> If the description were in a context inside a paragraph like this:\n>\n> \tWhen you want to tell 'git bisect' that a <rev> belongs to\n> \tthe newer half of the history, you say\n>\n> \t\tgit bisect (bad|new) [<rev>]\n>\n> \tOn the other hand, when you want to tell 'git bisect' that a\n> \t<rev> belongs to the older half of the history, you can say\n>\n> \t\tgit bisect (good|old) [<rev>]\n>\n> then the pairing we see in the current text makes quite a lot of\n> sense.\n\nActually, the above is _exactly_ what was intended.  I misread the\ncurrent documentation when I made the comment, and I think that the\ncurrent one _IS_ correct.  The latter half of the above is not about\na single rev.  You can paint multiple commits with the \"older half\"\ncolor, i.e.\n\n\tOn the other hand, when you want to tell 'git bisect' that\n\tone or more <rev>s  belong to the older half of the history,\n\tyou can say\n\n\t\tgit bisect (good|old) [<rev>...]\n\nIn contrast, you can mark only one <rev> as newer (or \"already\nbad\").  So pairing (bad|good) and (new|old) like you suggested\nbreaks the correctness of the command line description.\n\nIf (bad|new) and (good|old) bothers you because they may mislead the\nreaders to think bad is an opposite of new (and good is an opposite\nof old), the only solution I can think of to that problem is to\nexpand these two lines into four and list them like this:\n\n        git bisect bad [<rev>]\n        git bisect good [<rev>...]\n        git bisect new [<rev>]\n        git bisect old [<rev>...]\n\n"},{"id":"309335","messageId":"87bmvbu874.fsf@sonnengebleicht.fritz.box","threadId":"44866","inReplyTo":"xmqq8tqfj15z.fsf@gitster.mtv.corp.google.com","subject":"Re: Bug report: Documentation error in git-bisect man description","fromName":"Manuel Ullmann","fromEmail":"ullman.alias@posteo.de","sentAt":"2017-01-13T00:14:55Z","receivedAt":"2017-01-13T00:15:05Z","isPatch":false,"sender":{"key":"ullman.alias@posteo.de","avatar":null},"body":"I see. Thanks for the clarification. The pairing not being pairs of\nopposites was indeed, what confused me. So that description was not\nmeant in the sense, that you use these pairs when working with bisect, but\ninstead they are ordered according to the argument possibilities.\n\nSorry for spreading confusion. I think the second paragraph should be\nsufficient for documentation.\n\nBest regards\nManuel\n> Junio C Hamano <gitster@pobox.com> writes:\n>\n>> Manuel Ullmann <ullman.alias@posteo.de> writes:\n>>\n>> Hmmm, I tend to agree, modulo a minor fix.\n>>\n>> If the description were in a context inside a paragraph like this:\n>>\n>> \tWhen you want to tell 'git bisect' that a <rev> belongs to\n>> \tthe newer half of the history, you say\n>>\n>> \t\tgit bisect (bad|new) [<rev>]\n>>\n>> \tOn the other hand, when you want to tell 'git bisect' that a\n>> \t<rev> belongs to the older half of the history, you can say\n>>\n>> \t\tgit bisect (good|old) [<rev>]\n>>\n>> then the pairing we see in the current text makes quite a lot of\n>> sense.\n>\n> Actually, the above is _exactly_ what was intended.  I misread the\n> current documentation when I made the comment, and I think that the\n> current one _IS_ correct.  The latter half of the above is not about\n> a single rev.  You can paint multiple commits with the \"older half\"\n> color, i.e.\n>\n> \tOn the other hand, when you want to tell 'git bisect' that\n> \tone or more <rev>s  belong to the older half of the history,\n> \tyou can say\n>\n> \t\tgit bisect (good|old) [<rev>...]\n>\n> In contrast, you can mark only one <rev> as newer (or \"already\n> bad\").  So pairing (bad|good) and (new|old) like you suggested\n> breaks the correctness of the command line description.\n>\n> If (bad|new) and (good|old) bothers you because they may mislead the\n> readers to think bad is an opposite of new (and good is an opposite\n> of old), the only solution I can think of to that problem is to\n> expand these two lines into four and list them like this:\n>\n>         git bisect bad [<rev>]\n>         git bisect good [<rev>...]\n>         git bisect new [<rev>]\n>         git bisect old [<rev>...]\n"},{"id":"309340","messageId":"CAP8UFD3JDWVVTWsSQcnh+dOHoZDcipVUFwkfQYNOAyV4431C2w@mail.gmail.com","threadId":"44866","inReplyTo":"xmqq8tqfj15z.fsf@gitster.mtv.corp.google.com","subject":"Re: Bug report: Documentation error in git-bisect man description","fromName":"Christian Couder","fromEmail":"christian.couder@gmail.com","sentAt":"2017-01-13T01:13:15Z","receivedAt":"2017-01-13T01:13:22Z","isPatch":false,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"On Fri, Jan 13, 2017 at 12:42 AM, Junio C Hamano <gitster@pobox.com> wrote:\n> Junio C Hamano <gitster@pobox.com> writes:\n>\n>> Manuel Ullmann <ullman.alias@posteo.de> writes:\n>>\n>> Hmmm, I tend to agree, modulo a minor fix.\n>>\n>> If the description were in a context inside a paragraph like this:\n>>\n>>       When you want to tell 'git bisect' that a <rev> belongs to\n>>       the newer half of the history, you say\n>>\n>>               git bisect (bad|new) [<rev>]\n>>\n>>       On the other hand, when you want to tell 'git bisect' that a\n>>       <rev> belongs to the older half of the history, you can say\n>>\n>>               git bisect (good|old) [<rev>]\n>>\n>> then the pairing we see in the current text makes quite a lot of\n>> sense.\n>\n> Actually, the above is _exactly_ what was intended.  I misread the\n> current documentation when I made the comment, and I think that the\n> current one _IS_ correct.  The latter half of the above is not about\n> a single rev.  You can paint multiple commits with the \"older half\"\n> color, i.e.\n>\n>         On the other hand, when you want to tell 'git bisect' that\n>         one or more <rev>s  belong to the older half of the history,\n>         you can say\n>\n>                 git bisect (good|old) [<rev>...]\n>\n> In contrast, you can mark only one <rev> as newer (or \"already\n> bad\").  So pairing (bad|good) and (new|old) like you suggested\n> breaks the correctness of the command line description.\n\nYeah, I agree.\n\n> If (bad|new) and (good|old) bothers you because they may mislead the\n> readers to think bad is an opposite of new (and good is an opposite\n> of old), the only solution I can think of to that problem is to\n> expand these two lines into four and list them like this:\n>\n>         git bisect bad [<rev>]\n>         git bisect good [<rev>...]\n>         git bisect new [<rev>]\n>         git bisect old [<rev>...]\n\nMaybe it would be more complete and a bit clearer if it was:\n\n           git bisect (bad|new|<term-new>) [<rev>]\n           git bisect (good|old|<term-old>) [<rev>...]\n"},{"id":"309341","messageId":"871sw7u4au.fsf@sonnengebleicht.fritz.box","threadId":"44866","inReplyTo":"CAP8UFD3JDWVVTWsSQcnh+dOHoZDcipVUFwkfQYNOAyV4431C2w@mail.gmail.com","subject":"Re: Bug report: Documentation error in git-bisect man description","fromName":"Manuel Ullmann","fromEmail":"ullman.alias@posteo.de","sentAt":"2017-01-13T01:39:05Z","receivedAt":"2017-01-13T01:39:13Z","isPatch":false,"sender":{"key":"ullman.alias@posteo.de","avatar":null},"body":"> On Fri, Jan 13, 2017 at 12:42 AM, Junio C Hamano <gitster@pobox.com> wrote:\n>> Junio C Hamano <gitster@pobox.com> writes:\n>>\n>>> Manuel Ullmann <ullman.alias@posteo.de> writes:\n>>>\n>>> Hmmm, I tend to agree, modulo a minor fix.\n>>>\n>>> If the description were in a context inside a paragraph like this:\n>>>\n>>>       When you want to tell 'git bisect' that a <rev> belongs to\n>>>       the newer half of the history, you say\n>>>\n>>>               git bisect (bad|new) [<rev>]\n>>>\n>>>       On the other hand, when you want to tell 'git bisect' that a\n>>>       <rev> belongs to the older half of the history, you can say\n>>>\n>>>               git bisect (good|old) [<rev>]\n>>>\n>>> then the pairing we see in the current text makes quite a lot of\n>>> sense.\n>>\n>> Actually, the above is _exactly_ what was intended.  I misread the\n>> current documentation when I made the comment, and I think that the\n>> current one _IS_ correct.  The latter half of the above is not about\n>> a single rev.  You can paint multiple commits with the \"older half\"\n>> color, i.e.\n>>\n>>         On the other hand, when you want to tell 'git bisect' that\n>>         one or more <rev>s  belong to the older half of the history,\n>>         you can say\n>>\n>>                 git bisect (good|old) [<rev>...]\n>>\n>> In contrast, you can mark only one <rev> as newer (or \"already\n>> bad\").  So pairing (bad|good) and (new|old) like you suggested\n>> breaks the correctness of the command line description.\n>\n> Yeah, I agree.\n>\n>> If (bad|new) and (good|old) bothers you because they may mislead the\n>> readers to think bad is an opposite of new (and good is an opposite\n>> of old), the only solution I can think of to that problem is to\n>> expand these two lines into four and list them like this:\n>>\n>>         git bisect bad [<rev>]\n>>         git bisect good [<rev>...]\n>>         git bisect new [<rev>]\n>>         git bisect old [<rev>...]\n>\n> Maybe it would be more complete and a bit clearer if it was:\n>\n>            git bisect (bad|new|<term-new>) [<rev>]\n>            git bisect (good|old|<term-old>) [<rev>...]\n\nThat would clarify the intention quite a bit (at least for me).\n\nBest regards,\nManuel\n"}]}