{"thread":{"id":"32870","subject":"[PATCH] git-bisect.txt: clarify that reset finishes bisect","startedAt":"2013-02-09T19:47:13Z","lastAt":"2013-02-11T08:39:49Z","messageCount":9,"participants":["Michael J Gruber","Junio C Hamano","Andreas Mohr","Jonathan Nieder"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"209089","messageId":"5e23d4c420f150b700dd5100bffb38d32f874200.1360439176.git.git@drmicha.warpmail.net","threadId":"32870","inReplyTo":null,"subject":"[PATCH] git-bisect.txt: clarify that reset finishes bisect","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2013-02-09T19:47:13Z","receivedAt":"2013-02-09T19:47:13Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"\"reset\" can be easily misunderstood as resetting a bisect session to its\nstart without finishing it. Clarify that it actually finishes the bisect\nsession.\n\nReported-by: Andreas Mohr \nSigned-off-by: Michael J Gruber \n---\n Documentation/git-bisect.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\nindex b4831bb..d50bd89 100644\n--- a/Documentation/git-bisect.txt\n+++ b/Documentation/git-bisect.txt\n@@ -83,7 +83,7 @@ Bisect reset\n ~~~~~~~~~~~~\n \n After a bisect session, to clean up the bisection state and return to\n-the original HEAD, issue the following command:\n+the original HEAD (i.e., to finish bisect), issue the following command:\n \n ------------------------------------------------\n $ git bisect reset\n-- \n1.8.1.2.752.g32d147e\n"},{"id":"209096","messageId":"7v8v6xw3wf.fsf@alter.siamese.dyndns.org","threadId":"32870","inReplyTo":"5e23d4c420f150b700dd5100bffb38d32f874200.1360439176.git.git@drmicha.warpmail.net","subject":"Re: [PATCH] git-bisect.txt: clarify that reset finishes bisect","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-02-09T21:53:04Z","receivedAt":"2013-02-09T21:53:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael J Gruber writes:\n\n> \"reset\" can be easily misunderstood as resetting a bisect session to its\n> start without finishing it. Clarify that it actually finishes the bisect\n> session.\n>\n> Reported-by: Andreas Mohr \n> Signed-off-by: Michael J Gruber \n> ---\n> Documentation/git-bisect.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\n> index b4831bb..d50bd89 100644\n> --- a/Documentation/git-bisect.txt\n> +++ b/Documentation/git-bisect.txt\n> @@ -83,7 +83,7 @@ Bisect reset\n> ~~~~~~~~~~~~\n> \n> After a bisect session, to clean up the bisection state and return to\n> -the original HEAD, issue the following command:\n> +the original HEAD (i.e., to finish bisect), issue the following command:\n\nMakes sense.\n"},{"id":"209101","messageId":"20130209232455.GA31027@rhlx01.hs-esslingen.de","threadId":"32870","inReplyTo":"7v8v6xw3wf.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] git-bisect.txt: clarify that reset finishes bisect","fromName":"Andreas Mohr","fromEmail":"andi@lisas.de","sentAt":"2013-02-09T23:24:55Z","receivedAt":"2013-02-09T23:24:55Z","isPatch":true,"sender":{"key":"andi@lisas.de","avatar":null},"body":"Hi,\n\nOn Sat, Feb 09, 2013 at 01:53:04PM -0800, Junio C Hamano wrote:\n> Michael J Gruber writes:\n> > After a bisect session, to clean up the bisection state and return to\n> > -the original HEAD, issue the following command:\n> > +the original HEAD (i.e., to finish bisect), issue the following command:\n> \n> Makes sense.\n\nDoesn't ;)\n\n[aww, very sorry for this blunt reply]\n\nThe main point of my mail was to stretch the (whether actually intended)\n*perceived* start <-> stop symmetry\n(which a *user* quite likely would end up searching for in the document,\nand fail to find any \"stop\" keyword, thus not getting to the relevant\nreset parameter section in time).\nQuite likely I failed to properly word things to make that obvious,\nin my quickly carved mail.\n\n\nTo clarify intent behind these docs, I would thus propose to have\nthe sentence improved to something quite similar to\n\nthe original HEAD (i.e., to finish - \"stop\" a started - bisect),\nissue the following command:\n\n\nThanks a ton for your immediate handling of my wishlist item!\n\nAndreas Mohr\n"},{"id":"209103","messageId":"7vy5ext60o.fsf@alter.siamese.dyndns.org","threadId":"32870","inReplyTo":"20130209232455.GA31027@rhlx01.hs-esslingen.de","subject":"Re: [PATCH] git-bisect.txt: clarify that reset finishes bisect","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-02-09T23:35:35Z","receivedAt":"2013-02-09T23:35:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andreas Mohr writes:\n\n> On Sat, Feb 09, 2013 at 01:53:04PM -0800, Junio C Hamano wrote:\n>> Michael J Gruber writes:\n>> > After a bisect session, to clean up the bisection state and return to\n>> > -the original HEAD, issue the following command:\n>> > +the original HEAD (i.e., to finish bisect), issue the following command:\n>> \n>> Makes sense.\n>\n> Doesn't ;)\n>\n> [aww, very sorry for this blunt reply]\n>\n> The main point of my mail was to stretch the (whether actually intended)\n> *perceived* start <-> stop symmetry\n\nActually, in that sense, I do no think finish is exactly a good\nwording. The majority of use case would be to finish up after you\nfound the sole culprit, so in that sense \"finish\" is not too bad,\nbut in general, when you \"reset\", there is not necessarily any\nsymmmetry with \"start\". We should definitely not be giving you an\nillusion that there is one by using \"stop\" [*1*].\n\nIt is more like \"abort\".\n\nI may be done with bisection after running the bisection to the very\nend, of I may have realized that the problem is not bisectable due\nto many reasons (e.g. the sympotom may be intermittent, or it has\nalready become apparent that there are more than one cause of the\nobserved breakage) way before we found \"the first bad commit\".\n\nAnd \"reset\" cleans the bisectoin state and returns to the original\nHEAD, regardless of the reason why you are cleaning up. If we were\nto add any explanation to the sentence, I think \"finish\" makes a lot\nmore sense than \"stop\".\n\n\n[Footnote]\n\n*1* another reason to avoid \"stop\" is that it could mean \"I stop\nhere for now, to later come back and start digging again from\nthere\", which is not \"reset\" is about at all.\n"},{"id":"209106","messageId":"20130210002305.GB5744@rhlx01.hs-esslingen.de","threadId":"32870","inReplyTo":"7vy5ext60o.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] git-bisect.txt: clarify that reset finishes bisect","fromName":"Andreas Mohr","fromEmail":"andi@lisas.de","sentAt":"2013-02-10T00:23:05Z","receivedAt":"2013-02-10T00:23:05Z","isPatch":true,"sender":{"key":"andi@lisas.de","avatar":null},"body":"On Sat, Feb 09, 2013 at 03:35:35PM -0800, Junio C Hamano wrote:\n> Andreas Mohr writes:\n> > The main point of my mail was to stretch the (whether actually intended)\n> > *perceived* start <-> stop symmetry\n> \n> Actually, in that sense, I do no think finish is exactly a good\n> wording. The majority of use case would be to finish up after you\n> found the sole culprit, so in that sense \"finish\" is not too bad,\n> but in general, when you \"reset\", there is not necessarily any\n> symmmetry with \"start\". We should definitely not be giving you an\n> illusion that there is one by using \"stop\" [*1*].\n\nYeah, of course, but the whole point was that the *user* will *directly*\nand *immediately* mentally go from a bisect \"start\" parameter to \"stop\",\nand end up failing to find it.\nThus the \"stop\" *KEYWORD* *has* to be mentioned in the man page\n(even if only to then expressly state that reset is not quite about \"stop\"iing\nthings).\n\n> *1* another reason to avoid \"stop\" is that it could mean \"I stop\n> here for now, to later come back and start digging again from\n> there\", which is not \"reset\" is about at all.\n\nSuch reasons for not listing \"stop\" might even be stronger\nthan the reason of\nusers being required to successfully look up the symmetric \"stop\" keyword.\nIf that was decided to be the case, then \"stop\" would indeed have to be\nomitted in the man page - to the detriments of usability.\n\nThanks,\n\nAndreas Mohr\n"},{"id":"209108","messageId":"20130210014900.GA7682@elie.Belkin","threadId":"32870","inReplyTo":"5e23d4c420f150b700dd5100bffb38d32f874200.1360439176.git.git@drmicha.warpmail.net","subject":"Re: [PATCH] git-bisect.txt: clarify that reset finishes bisect","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-02-10T01:49:00Z","receivedAt":"2013-02-10T01:49:00Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nMichael J Gruber wrote:\n\n> \"reset\" can be easily misunderstood as resetting a bisect session to its\n> start without finishing it. Clarify that it actually finishes the bisect\n> session.\n\nFWIW,\nReviewed-by: Jonathan Nieder \n\nAddressing Andreas's original concern about the discoverability of\n'git bisect reset' would presumably require doing two more things:\n\n 1. adding an example of the normal bisection workflow to the EXAMPLES\n section\n\n 2. training users to look to the EXAMPLES section\n\nThat is, something like the below. But I'm not happy with it, because\nit just runs over the same material as the current Description\nsection. Maybe the current tutorial material could be moved to\nexamples and replaced with something terser that fleshes out the\ndescriptions in \"git bisect -h\" output. What do you think?\n\ndiff --git i/Documentation/git-bisect.txt w/Documentation/git-bisect.txt\nindex e4f46bc1..b89abd78 100644\n--- i/Documentation/git-bisect.txt\n+++ w/Documentation/git-bisect.txt\n@@ -356,6 +356,54 @@ $ git bisect run sh -c \"make || exit 125; ~/check_test_case.sh\"\n This shows that you can do without a run script if you write the test\n on a single line.\n \n+* Bisect to find which patch caused a boot failure:\n++\n+Install a recent kernel:\n++\n+------------\n+$ cd ~/src/linux\n+$ git checkout origin/master\n+$ make deb-pkg # or binrpm-pkg, or tar-pkg\n+$ dpkg -i ../ # as root (or rpm -i, or tar -C / -xf)\n+$ reboot # as root\n+------------\n++\n+Hopefully it fails to boot, so tell git so and begin bisection:\n++\n+------------\n+$ cd ~/src/linux\n+$ git bisect start HEAD v3.2 # assuming 3.2 works fine\n+-------------\n++\n+A candidate revision to test is automatically checked out.\n+Test it:\n++\n+-------------\n+$ make deb-pkg # or binrpm-pkg, or tar-pkg\n+$ dpkg -i ../ # as root (or rpm -i, or tar -C / -xf)\n+$ reboot # as root\n+-------------\n++\n+Record the result:\n++\n+-------------\n+$ cd ~/src/linux\n+$ git bisect good # if it booted correctly\n+$ git bisect bad # if it failed to boot\n+$ git bisect skip # if some other bug made it hard to test\n+-------------\n++\n+Repeat until bored or git prints the \"first bad commit\". When\n+done:\n++\n+-------------\n+$ git bisect log >log # let others pick up where you left off\n+$ git bisect reset HEAD # exit the bisecting state\n+-------------\n++\n+At any step, you can run `git bisect visualize` to watch the\n+regression range narrowing.\n+\n * Locate a good region of the object graph in a damaged repository\n +\n ------------\n"},{"id":"209237","messageId":"5118A5F2.6000007@drmicha.warpmail.net","threadId":"32870","inReplyTo":"20130210014900.GA7682@elie.Belkin","subject":"Re: [PATCH] git-bisect.txt: clarify that reset finishes bisect","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2013-02-11T08:04:02Z","receivedAt":"2013-02-11T08:04:02Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Jonathan Nieder venit, vidit, dixit 10.02.2013 02:49:\n> Hi,\n> \n> Michael J Gruber wrote:\n> \n>> \"reset\" can be easily misunderstood as resetting a bisect session to its\n>> start without finishing it. Clarify that it actually finishes the bisect\n>> session.\n> \n> FWIW,\n> Reviewed-by: Jonathan Nieder \n> \n> Addressing Andreas's original concern about the discoverability of\n> 'git bisect reset' would presumably require doing two more things:\n> \n> 1. adding an example of the normal bisection workflow to the EXAMPLES\n> section\n> \n> 2. training users to look to the EXAMPLES section\n> \n> That is, something like the below. But I'm not happy with it, because\n> it just runs over the same material as the current Description\n> section. Maybe the current tutorial material could be moved to\n> examples and replaced with something terser that fleshes out the\n> descriptions in \"git bisect -h\" output. What do you think?\n> \n> diff --git i/Documentation/git-bisect.txt w/Documentation/git-bisect.txt\n> index e4f46bc1..b89abd78 100644\n> --- i/Documentation/git-bisect.txt\n> +++ w/Documentation/git-bisect.txt\n> @@ -356,6 +356,54 @@ $ git bisect run sh -c \"make || exit 125; ~/check_test_case.sh\"\n> This shows that you can do without a run script if you write the test\n> on a single line.\n> \n> +* Bisect to find which patch caused a boot failure:\n> ++\n> +Install a recent kernel:\n> ++\n> +------------\n> +$ cd ~/src/linux\n> +$ git checkout origin/master\n> +$ make deb-pkg # or binrpm-pkg, or tar-pkg\n> +$ dpkg -i ../ # as root (or rpm -i, or tar -C / -xf)\n> +$ reboot # as root\n> +------------\n> ++\n> +Hopefully it fails to boot, so tell git so and begin bisection:\n> ++\n> +------------\n> +$ cd ~/src/linux\n> +$ git bisect start HEAD v3.2 # assuming 3.2 works fine\n> +-------------\n> ++\n> +A candidate revision to test is automatically checked out.\n> +Test it:\n> ++\n> +-------------\n> +$ make deb-pkg # or binrpm-pkg, or tar-pkg\n> +$ dpkg -i ../ # as root (or rpm -i, or tar -C / -xf)\n> +$ reboot # as root\n> +-------------\n> ++\n> +Record the result:\n> ++\n> +-------------\n> +$ cd ~/src/linux\n> +$ git bisect good # if it booted correctly\n> +$ git bisect bad # if it failed to boot\n> +$ git bisect skip # if some other bug made it hard to test\n> +-------------\n> ++\n> +Repeat until bored or git prints the \"first bad commit\". When\n> +done:\n> ++\n> +-------------\n> +$ git bisect log >log # let others pick up where you left off\n> +$ git bisect reset HEAD # exit the bisecting state\n> +-------------\n> ++\n> +At any step, you can run `git bisect visualize` to watch the\n> +regression range narrowing.\n> +\n> * Locate a good region of the object graph in a damaged repository\n> +\n> ------------\n> \n\n[BTW, sorry for failing to set --in-reply-to in the patch e-mail. Need\nto get that automated somehow.]\n\nI did not use \"stop\" for the exact reasons that Junio mentioned. Just\nthrow in a third alternative: \"quit\" may convey that it's not possible\nto ressume, without sounding as \"exceptional\" as \"abort\" does. After\nall, it's the normal end to a bisect session much unlike \"--abort\" for\nrebase, for example.\n\nAs for the example, we have an example section, and we could simply\nthrow in \"git reset\" lines there. I would even amend my patch with that;\nthe great git-bisect.txt refactoring I'd definitely leave to someone else.\n\nMichael\n"},{"id":"209239","messageId":"d679f620f10ad7afc044c9f5dadcf433b388ad10.1360571552.git.git@drmicha.warpmail.net","threadId":"32870","inReplyTo":"5118A5F2.6000007@drmicha.warpmail.net","subject":"[PATCHv2] git-bisect.txt: clarify that reset quits bisect","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2013-02-11T08:35:04Z","receivedAt":"2013-02-11T08:35:04Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"\"reset\" can be easily misunderstood as resetting a bisect session to its\nstart without finishing it. Clarify that it actually quits the bisect\nsession.\n\nReported-by: Andreas Mohr \nSigned-off-by: Michael J Gruber \n---\n Documentation/git-bisect.txt | 7 ++++++-\n 1 file changed, 6 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\nindex b4831bb..f986c5c 100644\n--- a/Documentation/git-bisect.txt\n+++ b/Documentation/git-bisect.txt\n@@ -83,7 +83,7 @@ Bisect reset\n ~~~~~~~~~~~~\n \n After a bisect session, to clean up the bisection state and return to\n-the original HEAD, issue the following command:\n+the original HEAD (i.e., to quit bisecting), issue the following command:\n \n ------------------------------------------------\n $ git bisect reset\n@@ -284,6 +284,7 @@ EXAMPLES\n ------------\n $ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good\n $ git bisect run make # \"make\" builds the app\n+$ git bisect reset # quit the bisect session\n ------------\n \n * Automatically bisect a test failure between origin and HEAD:\n@@ -291,6 +292,7 @@ $ git bisect run make # \"make\" builds the app\n ------------\n $ git bisect start HEAD origin -- # HEAD is bad, origin is good\n $ git bisect run make test # \"make test\" builds and tests\n+$ git bisect reset # quit the bisect session\n ------------\n \n * Automatically bisect a broken test case:\n@@ -302,6 +304,7 @@ make || exit 125 # this skips broken builds\n ~/check_test_case.sh # does the test case pass?\n $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10\n $ git bisect run ~/test.sh\n+$ git bisect reset # quit the bisect session\n ------------\n +\n Here we use a \"test.sh\" custom script. In this script, if \"make\"\n@@ -351,6 +354,7 @@ use `git cherry-pick` instead of `git merge`.)\n ------------\n $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10\n $ git bisect run sh -c \"make || exit 125; ~/check_test_case.sh\"\n+$ git bisect reset # quit the bisect session\n ------------\n +\n This shows that you can do without a run script if you write the test\n@@ -368,6 +372,7 @@ $ git bisect run sh -c '\n \trm -f tmp.$$\n \ttest $rc = 0'\n \n+$ git bisect reset # quit the bisect session\n ------------\n +\n In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit that\n-- \n1.8.1.2.752.g32d147e\n"},{"id":"209240","messageId":"20130211083949.GQ15329@elie.Belkin","threadId":"32870","inReplyTo":"d679f620f10ad7afc044c9f5dadcf433b388ad10.1360571552.git.git@drmicha.warpmail.net","subject":"Re: [PATCHv2] git-bisect.txt: clarify that reset quits bisect","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-02-11T08:39:49Z","receivedAt":"2013-02-11T08:39:49Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Michael J Gruber wrote:\n\n> --- a/Documentation/git-bisect.txt\n> +++ b/Documentation/git-bisect.txt\n[...]\n> @@ -284,6 +284,7 @@ EXAMPLES\n> ------------\n> $ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good\n> $ git bisect run make # \"make\" builds the app\n> +$ git bisect reset # quit the bisect session\n\nI had forgotten that \"git bisect run\" ends in a bisecting state.\nGood call.\n\nReviewed-by: Jonathan Nieder \n\nThanks,\nJonathan\n"}]}