{"thread":{"id":"13844","subject":"[PATCH] improve doc heading for git-bisect","startedAt":"2008-06-07T07:06:37Z","lastAt":"2008-06-08T21:27:58Z","messageCount":8,"participants":["Robert Anderson","Jakub Narebski","Junio C Hamano","Jeff King","Johannes Schindelin"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"79019","messageId":"20080607070637.79B17C7C0E@rwavmlap","threadId":"13844","inReplyTo":null,"subject":"[PATCH] improve doc heading for git-bisect","fromName":"Robert Anderson","fromEmail":"rwa000@gmail.com","sentAt":"2008-06-07T07:06:37Z","receivedAt":"2008-06-07T07:06:37Z","isPatch":true,"sender":{"key":"rwa000@gmail.com","avatar":null},"body":">From 7af03a835b7311c501f2147e25f428642fc3acb7 Mon Sep 17 00:00:00 2001\nFrom: Robert W. Anderson \nDate: Fri, 6 Jun 2008 23:53:37 -0700\nSubject: [PATCH] improve doc heading for git-bisect\n\nImprove awkward heading in git-bisect documentation.\n\nSigned-off-by: Robert W. Anderson \n---\n Documentation/git-bisect.txt | 4 ++--\n 1 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\nindex 37c7acb..3ea2527 100644\n--- a/Documentation/git-bisect.txt\n+++ b/Documentation/git-bisect.txt\n@@ -129,8 +129,8 @@ $ git bisect replay that-file\n if you find later you made a mistake telling good/bad about a\n revision.\n \n-Avoiding to test a commit\n-~~~~~~~~~~~~~~~~~~~~~~~~~\n+Changing the revision to test\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n If in a middle of bisect session, you know what the bisect suggested\n to try next is not a good one to test (e.g. the change the commit\n-- \n1.5.4.3\n"},{"id":"79033","messageId":"m37id1y4zj.fsf@localhost.localdomain","threadId":"13844","inReplyTo":"20080607070637.79B17C7C0E@rwavmlap","subject":"Re: [PATCH] improve doc heading for git-bisect","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2008-06-07T09:22:14Z","receivedAt":"2008-06-07T09:22:14Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"rwa000@gmail.com (Robert Anderson) writes:\n\n> From 7af03a835b7311c501f2147e25f428642fc3acb7 Mon Sep 17 00:00:00 2001\n\nFYI this line is not necessary, and should be removed from\ngit-format-patch output when pasting it to your MUA.\n\n> From: Robert W. Anderson \n> Date: Fri, 6 Jun 2008 23:53:37 -0700\n> Subject: [PATCH] improve doc heading for git-bisect\n\nFYI the above isn't strictly necessary: if you have 'From:' header set\ncorrectly you can simply set subject of email, and put in body the\nrest of commit message and patch only, without extra mail-like\nheaders.\n\n> Improve awkward heading in git-bisect documentation.\n[...]\n> -Avoiding to test a commit\n> -~~~~~~~~~~~~~~~~~~~~~~~~~\n> +Changing the revision to test\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> \n> If in a middle of bisect session, you know what the bisect suggested\n> to try next is not a good one to test (e.g. the change the commit\n\nIt is, I guess, better, but is it the best heading? What we want to\ndescribe here is how to deal when bisect stops on commit which cannot\nbe tested (e.g. project does not compile).\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"79051","messageId":"9af502e50806070906u63e52de4wa0bc4dced0c4d984@mail.gmail.com","threadId":"13844","inReplyTo":"m37id1y4zj.fsf@localhost.localdomain","subject":"Re: [PATCH] improve doc heading for git-bisect","fromName":"Robert Anderson","fromEmail":"rwa000@gmail.com","sentAt":"2008-06-07T16:06:19Z","receivedAt":"2008-06-07T16:06:19Z","isPatch":true,"sender":{"key":"rwa000@gmail.com","avatar":null},"body":"On Sat, Jun 7, 2008 at 2:22 AM, Jakub Narebski wrote:\n> rwa000@gmail.com (Robert Anderson) writes:\n>\n>> From 7af03a835b7311c501f2147e25f428642fc3acb7 Mon Sep 17 00:00:00 2001\n>\n> FYI this line is not necessary, and should be removed from\n> git-format-patch output when pasting it to your MUA.\n\nErr, then shouldn't it be removed from format-patch, rather than\ndeleted manually every time format-patch is used?\n\n>> From: Robert W. Anderson \n>> Date: Fri, 6 Jun 2008 23:53:37 -0700\n>> Subject: [PATCH] improve doc heading for git-bisect\n>\n> FYI the above isn't strictly necessary: if you have 'From:' header set\n> correctly you can simply set subject of email, and put in body the\n> rest of commit message and patch only, without extra mail-like\n> headers.\n\nThen remove them from format-patch, IMO.\n\n>> Improve awkward heading in git-bisect documentation.\n> [...]\n>> -Avoiding to test a commit\n>> -~~~~~~~~~~~~~~~~~~~~~~~~~\n>> +Changing the revision to test\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>>\n>> If in a middle of bisect session, you know what the bisect suggested\n>> to try next is not a good one to test (e.g. the change the commit\n>\n> It is, I guess, better, but is it the best heading? What we want to\n> describe here is how to deal when bisect stops on commit which cannot\n> be tested (e.g. project does not compile).\n\nI disagree. The situation you want to use this is more general than\nthat. Maybe you could test it, but doing so would be a waste of time\nbecause the commit is a trivial comment change. In general, this\nsimply what you need to know when you want to change the revision\nunder test.\n\nBob\n"},{"id":"79055","messageId":"200806071825.53974.jnareb@gmail.com","threadId":"13844","inReplyTo":"9af502e50806070906u63e52de4wa0bc4dced0c4d984@mail.gmail.com","subject":"Re: [PATCH] improve doc heading for git-bisect","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2008-06-07T16:25:53Z","receivedAt":"2008-06-07T16:25:53Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"On Sat, 7 Jun 2008, Robert Anderson wrote:\n> On Sat, Jun 7, 2008 at 2:22 AM, Jakub Narebski wrote:\n>> rwa000@gmail.com (Robert Anderson) writes:\n>>\n>>> From 7af03a835b7311c501f2147e25f428642fc3acb7 Mon Sep 17 00:00:00 2001\n>>\n>> FYI this line is not necessary, and should be removed from\n>> git-format-patch output when pasting it to your MUA.\n> \n> Err, then shouldn't it be removed from format-patch, rather than\n> deleted manually every time format-patch is used?\n\nIt is needed, I think, for git-format-patch output to be in mbox format,\nso you can just send it (for example using git-send-email), or make\nyour MUA open it.\n\nIf you copy'n'paste, or equivalently use \"insert file\", into body of\nyour message, this is not necessary and should be removed.\n\n>>> From: Robert W. Anderson \n>>> Date: Fri, 6 Jun 2008 23:53:37 -0700\n>>> Subject: [PATCH] improve doc heading for git-bisect\n>>\n>> FYI the above isn't strictly necessary: if you have 'From:' header set\n>> correctly you can simply set subject of email, and put in body the\n>> rest of commit message and patch only, without extra mail-like\n>> headers.\n> \n> Then remove them from format-patch, IMO.\n\nWell, the \"Subject:\" is neede to copy it to the email subject line\nin your MUA. If from differs from the account you send email from,\nit should also be set or left in the body of message.\n\nBesides, there are two conventions of sending patches to git mailing\nlist, used in slightly different circumstances.\n\n1. Put \"Subject:\" in the email subject line, remove all headers,\n put comments to patch (those which do not belong in commit message\n itself, for example how the patch differs from previously sent\n version, etc.) between \"---\" and diffstat.\n\n2. In the case when patch is response to longer thread, or the message\n body is much longer than commit message, you have the comments to\n patch or further part of discussion at beginning, then some kind\n of marker e.g. \"-- >8 --\" (scissors), but NOT \"---\" to mark beginning\n of commit, then commit message, including From: and Subject: lines.\n\nIn short: this information is sometimes needed.\n\n>>> Improve awkward heading in git-bisect documentation.\n>> [...]\n>>> -Avoiding to test a commit\n>>> -~~~~~~~~~~~~~~~~~~~~~~~~~\n>>> +Changing the revision to test\n>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>>>\n>>> If in a middle of bisect session, you know what the bisect suggested\n>>> to try next is not a good one to test (e.g. the change the commit\n>>\n>> It is, I guess, better, but is it the best heading? What we want to\n>> describe here is how to deal when bisect stops on commit which cannot\n>> be tested (e.g. project does not compile).\n> \n> I disagree. The situation you want to use this is more general than\n> that. Maybe you could test it, but doing so would be a waste of time\n> because the commit is a trivial comment change. In general, this\n> simply what you need to know when you want to change the revision\n> under test.\n\nWell, I don't have better idea on how to write short but precise header,\nand your change is certainly better...\n\n-- \nJakub Narebski\nPoland\n"},{"id":"79061","messageId":"7vr6b9nnmi.fsf@gitster.siamese.dyndns.org","threadId":"13844","inReplyTo":"9af502e50806070906u63e52de4wa0bc4dced0c4d984@mail.gmail.com","subject":"Re: [PATCH] improve doc heading for git-bisect","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-06-07T17:47:17Z","receivedAt":"2008-06-07T17:47:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Robert Anderson\" writes:\n\n> Err, then shouldn't it be removed from format-patch, rather than\n> deleted manually every time format-patch is used?\n> ...\n> Then remove them from format-patch, IMO.\n\nEverything Jakub said about the presentation is correct, and please take\nhints by looking at patch postings by long timers on this list.\n\nThe output from the command is designed so that it _can_ be pasted into a\nMUA edit buffer, but that's not the sole purpose. It needs to resemble\nmbox format for use of send-email, so when you paste into a context that\ndoes not need some parts, it is your responsibility and common courtesy\nfor readers to remove them.\n\n>>> Improve awkward heading in git-bisect documentation.\n>> [...]\n>>> -Avoiding to test a commit\n>>> -~~~~~~~~~~~~~~~~~~~~~~~~~\n>>> +Changing the revision to test\n>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>>>\n>>> If in a middle of bisect session, you know what the bisect suggested\n>>> to try next is not a good one to test (e.g. the change the commit\n>>\n>> It is, I guess, better, but is it the best heading? What we want to\n>> describe here is how to deal when bisect stops on commit which cannot\n>> be tested (e.g. project does not compile).\n>\n> I disagree. The situation you want to use this is more general than\n> that. Maybe you could test it, but doing so would be a waste of time\n> because the commit is a trivial comment change. In general, this\n> simply what you need to know when you want to change the revision\n> under test.\n\nI agree with your reasoning. Being able to test a different commit than\nthe suggested one is a useful feature of bisect, and we would want to help\nreaders by mentioning, as widely as possible, in what situations this mode\nof operation that is described in the section is applicable.\n\nBefore your change, the title describes \"One very typical situation in\nwhich you may want to do what we teach in this section\" (i.e. \"I do not\nwant to test this commit\"), the first paragraph describes the situation a\nbit further, and then the remainder gives how.\n\nAfter your change, the title describes \"What we teach you how to do in\nthis section\", the first paragraph of the section describes \"Why you may\nwant to do such a thing\".\n\nA title is only one line. It cannot afford to be too verbose. People,\nwhen they have problems, tend to skim documentation to see if there is\nsomething applicable to their situation. At least \"Avoiding to test a\ncommit\" should have worded \"Avoiding to test the suggested commit\" to draw\nattention better from people in such a situation, and I agree with you\nthat \"Changing the revision to test\", \"Testing a different revision\",\netc. would work much better for that purpose.\n\nBut at the same time, I think the first paragraph \"Why you may want to do\nsuch a thing\" should be strenghtened to cover wider scenario without going\nto verbose, especially now the title has become even more bland --- it now\ntells \"what you would do\" without hinting \"why you might want to\" anymore.\nIt currently talks only about what you said in your response \"you could,\nbut you do not want to as you know it is a waste of time\", and no other\nscenarios you hinted in your response by saying \"more general than that\".\n\nMaking the first paragraph richer would help the readers who spotted the\n(now better reworded) title to decide that the section indeed applies to\ntheir situation.\n\nAlso, I think the section that follows this part should be part of this\nsection. Either you reset to a specific commit, or you use \"bisect skip\"\nto pick another one for you. Both are solutions to the same problem.\n"},{"id":"79094","messageId":"20080608043543.GB11194@sigill.intra.peff.net","threadId":"13844","inReplyTo":"9af502e50806070906u63e52de4wa0bc4dced0c4d984@mail.gmail.com","subject":"Re: [PATCH] improve doc heading for git-bisect","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2008-06-08T04:35:43Z","receivedAt":"2008-06-08T04:35:43Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Jun 07, 2008 at 09:06:19AM -0700, Robert Anderson wrote:\n\n> > FYI this line is not necessary, and should be removed from\n> > git-format-patch output when pasting it to your MUA.\n> \n> Err, then shouldn't it be removed from format-patch, rather than\n> deleted manually every time format-patch is used?\n\nAs others have pointed out, the usual way for using format-patch is to\ncreate an mbox that you then pull into your MUA (e.g., I do \"git\nformat-patch --stdout origin >mbox; mutt -f mbox\").\n\nHowever, sometimes it is desirable to cut and paste, either because it\nis inconvenient to bring the message into your MUA this way, or if you\nare just putting a commit into an email you have already started\nwriting.\n\nI was going to suggest a \"--paste\" option for format-patch which would\nproduce a nicer output for cutting and pasting, but it is trivial to do\nwith an alias:\n\n git config --global \\\n alias.pastepatch \\\n 'format-patch --pretty=format:%s%n%n%b'\n\n(actually, this loses the author information versus using the\n--pretty=email format, but if you are just sending your own work, it is\nfine).\n\nIt is essentially the same as \"git log --stat -p\" except that the commit\nmessage is indented properly, and the revision arguments are interpreted\nas format-patch does.\n\n-Peff\n"},{"id":"79117","messageId":"alpine.DEB.1.00.0806081600220.1783@racer","threadId":"13844","inReplyTo":"20080608043543.GB11194@sigill.intra.peff.net","subject":"Re: [PATCH] improve doc heading for git-bisect","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2008-06-08T15:01:48Z","receivedAt":"2008-06-08T15:01:48Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Sun, 8 Jun 2008, Jeff King wrote:\n\n> On Sat, Jun 07, 2008 at 09:06:19AM -0700, Robert Anderson wrote:\n> \n> > > FYI this line is not necessary, and should be removed from\n> > > git-format-patch output when pasting it to your MUA.\n> > \n> > Err, then shouldn't it be removed from format-patch, rather than\n> > deleted manually every time format-patch is used?\n> \n> As others have pointed out, the usual way for using format-patch is to\n> create an mbox that you then pull into your MUA (e.g., I do \"git\n> format-patch --stdout origin >mbox; mutt -f mbox\").\n> \n> However, sometimes it is desirable to cut and paste, either because it\n> is inconvenient to bring the message into your MUA this way, or if you\n> are just putting a commit into an email you have already started\n> writing.\n> \n> I was going to suggest a \"--paste\" option for format-patch which would\n> produce a nicer output for cutting and pasting,\n\nYou still have to move the subject line where it belongs, so I think the \nvalue of --paste is limited. You do have to pay attention anyway (for \nexample when imitating how other people do it), so I think the current \nstate should be fine.\n\nCiao,\nDscho\n"},{"id":"79163","messageId":"20080608212757.GA8034@sigill.intra.peff.net","threadId":"13844","inReplyTo":"alpine.DEB.1.00.0806081600220.1783@racer","subject":"Re: [PATCH] improve doc heading for git-bisect","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2008-06-08T21:27:58Z","receivedAt":"2008-06-08T21:27:58Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Jun 08, 2008 at 04:01:48PM +0100, Johannes Schindelin wrote:\n\n> > I was going to suggest a \"--paste\" option for format-patch which would\n> > produce a nicer output for cutting and pasting,\n> \n> You still have to move the subject line where it belongs, so I think the \n> value of --paste is limited. You do have to pay attention anyway (for \n> example when imitating how other people do it), so I think the current \n> state should be fine.\n\nNot necessarily. I often end up posting patches like:\n\nHow about this?\n\n-- >8 --\nsubject\n\nbody\n\n---\ndiffstat\n\npatch\n\nbut the --pretty=format recipe I provided works just fine for that.\n\n-Peff\n"}]}