{"thread":{"id":"47293","subject":"[PATCH v2] doc: clarify that \"git bisect\" accepts one or more good commits","startedAt":"2017-11-22T12:33:43Z","lastAt":"2017-11-24T14:07:21Z","messageCount":5,"participants":["Robert P. J. Day","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"333270","messageId":"alpine.LFD.2.21.1711220729230.13545@DESKTOP-1GPMCEJ","threadId":"47293","inReplyTo":null,"subject":"[PATCH v2] doc: clarify that \"git bisect\" accepts one or more good commits","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-22T12:32:14Z","receivedAt":"2017-11-22T12:33:43Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"Reword the man page for \"git bisect\" to emphasize that, in the general\ncase, this command can take more than one good commit to define the\ninitial range of commits to examine.\n\nSigned-off-by: Robert P. J. Day <rpjday@crashcourse.ca>\n\n---\n\ndiff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\nindex 4a1417bdc..2afbd9562 100644\n--- a/Documentation/git-bisect.txt\n+++ b/Documentation/git-bisect.txt\n@@ -30,10 +30,10 @@ on the subcommand:\n  git bisect help\n\n This command uses a binary search algorithm to find which commit in\n-your project's history introduced a bug. You use it by first telling\n-it a \"bad\" commit that is known to contain the bug, and a \"good\"\n-commit that is known to be before the bug was introduced. Then `git\n-bisect` picks a commit between those two endpoints and asks you\n+your project's history introduced a bug. You use it by first telling it\n+a \"bad\" commit that is known to contain the bug, and one or more \"good\"\n+commits that are known to be before the bug was introduced. Then `git\n+bisect` picks a commit somewhere in between those commits and asks you\n whether the selected commit is \"good\" or \"bad\". It continues narrowing\n down the range until it finds the exact commit that introduced the\n change.\n@@ -58,7 +58,7 @@ $ git bisect bad                 # Current version is bad\n $ git bisect good v2.6.13-rc2    # v2.6.13-rc2 is known to be good\n ------------------------------------------------\n\n-Once you have specified at least one bad and one good commit, `git\n+Once you have specified one bad and one or more good commits, `git\n bisect` selects a commit in the middle of that range of history,\n checks it out, and outputs something similar to the following:\n\n@@ -137,7 +137,7 @@ respectively, in place of \"good\" and \"bad\". (But note that you cannot\n mix \"good\" and \"bad\" with \"old\" and \"new\" in a single session.)\n\n In this more general usage, you provide `git bisect` with a \"new\"\n-commit that has some property and an \"old\" commit that doesn't have that\n+commit with some property and some \"old\" commits that don't have that\n property. Each time `git bisect` checks out a commit, you test if that\n commit has the property. If it does, mark the commit as \"new\";\n otherwise, mark it as \"old\". When the bisection is done, `git bisect`\n@@ -145,19 +145,19 @@ will report which commit introduced the property.\n\n To use \"old\" and \"new\" instead of \"good\" and bad, you must run `git\n bisect start` without commits as argument and then run the following\n-commands to add the commits:\n+commands to identify the commits:\n\n ------------------------------------------------\n-git bisect old [<rev>]\n+git bisect old [<rev>...]\n ------------------------------------------------\n\n-to indicate that a commit was before the sought change, or\n+to identify one or more commits before the sought change, or\n\n ------------------------------------------------\n-git bisect new [<rev>...]\n+git bisect new [<rev>]\n ------------------------------------------------\n\n-to indicate that it was after.\n+to indicate a single commit after that change.\n\n To get a reminder of the currently used terms, use\n\n\n-- \n\n========================================================================\nRobert P. J. Day                                 Ottawa, Ontario, CANADA\n                        http://crashcourse.ca\n\nTwitter:                                       http://twitter.com/rpjday\nLinkedIn:                               http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"333406","messageId":"xmqqh8tkp9nn.fsf@gitster.mtv.corp.google.com","threadId":"47293","inReplyTo":"alpine.LFD.2.21.1711220729230.13545@DESKTOP-1GPMCEJ","subject":"Re: [PATCH v2] doc: clarify that \"git bisect\" accepts one or more good commits","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-11-24T04:45:16Z","receivedAt":"2017-11-24T04:45:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Robert P. J. Day\" <rpjday@crashcourse.ca> writes:\n\n>  This command uses a binary search algorithm to find which commit in\n> -your project's history introduced a bug. You use it by first telling\n> -it a \"bad\" commit that is known to contain the bug, and a \"good\"\n> -commit that is known to be before the bug was introduced. Then `git\n> -bisect` picks a commit between those two endpoints and asks you\n> +your project's history introduced a bug. You use it by first telling it\n> +a \"bad\" commit that is known to contain the bug, and one or more \"good\"\n> +commits that are known to be before the bug was introduced. Then `git\n> +bisect` picks a commit somewhere in between those commits and asks you\n\nGood.\n\n> -Once you have specified at least one bad and one good commit, `git\n> +Once you have specified one bad and one or more good commits, `git\n>  bisect` selects a commit in the middle of that range of history,\n>  checks it out, and outputs something similar to the following:\n\nGood.\n\n> @@ -137,7 +137,7 @@ respectively, in place of \"good\" and \"bad\". (But note that you cannot\n>  mix \"good\" and \"bad\" with \"old\" and \"new\" in a single session.)\n>\n>  In this more general usage, you provide `git bisect` with a \"new\"\n> -commit that has some property and an \"old\" commit that doesn't have that\n> +commit with some property and some \"old\" commits that don't have that\n>  property. Each time `git bisect` checks out a commit, you test if that\n\nGood.\n\n> @@ -145,19 +145,19 @@ will report which commit introduced the property.\n>\n>  To use \"old\" and \"new\" instead of \"good\" and bad, you must run `git\n>  bisect start` without commits as argument and then run the following\n> -commands to add the commits:\n> +commands to identify the commits:\n\nI am not sure if this is an improvement (see below).\n\n>\n>  ------------------------------------------------\n> -git bisect old [<rev>]\n> +git bisect old [<rev>...]\n>  ------------------------------------------------\n\nGood.\n\n> -to indicate that a commit was before the sought change, or\n> +to identify one or more commits before the sought change, or\n>\n>  ------------------------------------------------\n> -git bisect new [<rev>...]\n> +git bisect new [<rev>]\n>  ------------------------------------------------\n\nGood.\n\n> -to indicate that it was after.\n> +to indicate a single commit after that change.\n\nAs to \"identify\", I would say it is better to consistently use\n\"indicate\" like the original of these two hunks at the end says,\ni.e. \"indicate that it is bad/new (or they are good/old)\".\n\nRegarding the earlier \"add the commits\", I do not think the original\nis confusing and any reasonable reader would get that the verb is a\ncasually (or \"carelessly\") used short-hand for \"add the commits to\nthe set of commits the bisect algorithm cares about\", and turning it\nto \"identify\" adds much clarity.\n\nAs it is immediately followed by two illustrations to use old and\nnew, I would think that we could just stop the sentence at \"then run\nthe following commands:\" without saying anything else.\n\nIf you really want to phrase it differently from the two sentences\nto describe use of old and new, because this is acting as a headline\nfor these two, perhaps it is an improvement to say something like\n\"then run the following commands to limit the bisection range\"; that\nwould explain _why_ these commits are \"added\" and would give additional\ninformation to the readers.\n\n\n   \n\n\t\n"},{"id":"333425","messageId":"alpine.LFD.2.21.1711240351170.30318@localhost.localdomain","threadId":"47293","inReplyTo":"xmqqh8tkp9nn.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v2] doc: clarify that \"git bisect\" accepts one or more good commits","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-24T09:11:06Z","receivedAt":"2017-11-24T09:12:43Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Fri, 24 Nov 2017, Junio C Hamano wrote:\n\n> \"Robert P. J. Day\" <rpjday@crashcourse.ca> writes:\n\n... snip ...\n\n> > -to indicate that it was after.\n> > +to indicate a single commit after that change.\n>\n> As to \"identify\", I would say it is better to consistently use\n> \"indicate\" like the original of these two hunks at the end says,\n> i.e. \"indicate that it is bad/new (or they are good/old)\".\n\n  i'm going to ponder this, but let me explain why i am such an\nannoying stickler for the choice of words at times, and you can read\nall about it here:\n\n  http://twain.lib.virginia.edu/projects/rissetto/offense.html\n\nin particular, i draw your attention to twain's trashing of cooper\nfor, in many cases, using *almost* the right word, but not *quite* the\nright word:\n\n\"Cooper's word-sense was singularly dull. When a person has a poor ear\nfor music he will flat and sharp right along without knowing it. He\nkeeps near the tune, but is not the tune. When a person has a poor ear\nfor words, the result is a literary flatting and sharping; you\nperceive what he is intending to say, but you also perceive that he\ndoes not say it. This is Cooper. He was not a word-musician. His ear\nwas satisfied with the approximate words. I will furnish some\ncircumstantial evidence in support of this charge. My instances are\ngathered from half a dozen pages of the tale called \"Deerslayer.\" He\nuses \"Verbal\" for \"oral\"; \"precision\" for \"facility\"; \"phenomena\" for\n\"marvels\"; \"necessary\" for \"predetermined\"; \"unsophisticated\" for\n\"primitive\"; \"preparation\" for \"expectancy\"; \"rebuked\" for \"subdued\";\n\"dependent on\" for \"resulting from\"; \"fact\" for \"condition\"; \"fact\"\nfor \"conjecture\"; \"precaution\" for \"caution\"; \"explain\" for\n\"determine\"; \"mortified\" for \"disappointed\"; \"meretricious\" for\n\"factitious\"; \"materially\" for \"considerably\"; \"decreasing\" for\n\"deepening\"; \"increasing\" for \"disappearing\"; \"embedded\" for\n\"inclosed\"; \"treacherous\" for \"hostile\"; \"stood\" for \"stooped\";\n\"softened\" for \"replaced\"; \"rejoined\" for \"remarked\"; \"situation\" for\n\"condition\"; \"different\" for \"differing\"; \"insensible\" for\n\"unsentient\"; \"brevity\" for \"celerity\"; \"distrusted\" for \"suspicious\";\n\"mental imbecility\" for \"imbecility\"; \"eyes\" for \"sight\";\n\"counteracting\" for \"opposing\"; \"funeral obsequies\" for \"obsequies.\"\n\n  in this sense, i don't think \"indicate\" and \"identify\" are\ncompletely interchangeable. in my mind, the word \"identify\" does\nnothing more than, you know, point at something and say, \"that one,\nthat's the one i'm talking about;\" it goes no further than that.\n\n  on the other hand, the word \"indicate\" (in my mind) implies that\nyou're about to provide some *property* or *quality* of something, and\nyou do exactly that in the earlier quote:\n\n> As to \"identify\", I would say it is better to consistently use\n> \"indicate\" like the original of these two hunks at the end says,\n> i.e. \"indicate that it is bad/new (or they are good/old)\".\n\n  as in, you \"identify\" a commit, but you \"indicate\" that it\nrepresents a good or bad commit. i know this sounds picky, but it is\nexactly this tendency of using *almost* the right word that makes a\nlot of documentation potentially confusing. given this distinction,\ndepending on the word to be used, i would write one of:\n\n1) \"first, identify the bad commit and one or more good commits...\"\n\n2) \"first, indicate which commit is the bad commit, and which commits\nare the good commits ...\"\n\n  the eventual meaning *should* be the same, but the choice of words\ncan make the meaning clear, or can confuse the reader.\n\n  thoughts?\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day                                 Ottawa, Ontario, CANADA\n                        http://crashcourse.ca\n\nTwitter:                                       http://twitter.com/rpjday\nLinkedIn:                               http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"333440","messageId":"xmqqh8tjn6x4.fsf@gitster.mtv.corp.google.com","threadId":"47293","inReplyTo":"alpine.LFD.2.21.1711240351170.30318@localhost.localdomain","subject":"Re: [PATCH v2] doc: clarify that \"git bisect\" accepts one or more good commits","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-11-24T13:27:19Z","receivedAt":"2017-11-24T13:27:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Robert P. J. Day\" <rpjday@crashcourse.ca> writes:\n\n>   in this sense, i don't think \"indicate\" and \"identify\" are\n> completely interchangeable. in my mind, the word \"identify\" does\n> nothing more than, you know, point at something and say, \"that one,\n> that's the one i'm talking about;\" it goes no further than that.\n>\n>   on the other hand, the word \"indicate\" (in my mind) implies that\n> you're about to provide some *property* or *quality* of something, and\n> you do exactly that in the earlier quote:\n\nI do not think the two words have different connotations, so we are\nin agreement.  You do not necessarily need a property in mind when\nyou \"identify\" a commit.  You could just \"identify\" this and that\ncommits to yourself, to keep them in mind.  You _also_ can have a\nproperty in mind and \"identify\" this commit as a good one, and that\ncommit as a bad one.\n\nBut identifying a commit as bad (or another one as good) alone to\nyourself does not get anything started.  In order to advance the\nbisection process, you need to tell the \"git bisect\" machinery that\n\"this commit is good\", \"that commit is bad\", etc.  I would think\n\"indicate\" is a verb with better connotation than \"identify\" for\ndescribing that action.  You indicate something *to* *somebody, and\nin this case you indicate that this commit is good and that commit\nis bad to git.\n\n"},{"id":"333443","messageId":"xmqq3753n52l.fsf@gitster.mtv.corp.google.com","threadId":"47293","inReplyTo":"xmqqh8tjn6x4.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v2] doc: clarify that \"git bisect\" accepts one or more good commits","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-11-24T14:07:14Z","receivedAt":"2017-11-24T14:07:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> \"Robert P. J. Day\" <rpjday@crashcourse.ca> writes:\n>\n>>   in this sense, i don't think \"indicate\" and \"identify\" are\n>> completely interchangeable. in my mind, the word \"identify\" does\n>> nothing more than, you know, point at something and say, \"that one,\n>> that's the one i'm talking about;\" it goes no further than that.\n>>\n>>   on the other hand, the word \"indicate\" (in my mind) implies that\n>> you're about to provide some *property* or *quality* of something, and\n>> you do exactly that in the earlier quote:\n>\n> I do not think the two words have different connotations, so we are\n> in agreement.  You do not necessarily need a property in mind when\n\nEek.  I do do think the two words are not interchangeable.\nI should stop typing late at night.\n"}]}