"Robert Anderson" <rwa000@xxxxxxxxx> writes: > Err, then shouldn't it be removed from format-patch, rather than > deleted manually every time format-patch is used? > ... > Then remove them from format-patch, IMO. Everything Jakub said about the presentation is correct, and please take hints by looking at patch postings by long timers on this list. The output from the command is designed so that it _can_ be pasted into a MUA edit buffer, but that's not the sole purpose. It needs to resemble mbox format for use of send-email, so when you paste into a context that does not need some parts, it is your responsibility and common courtesy for readers to remove them. >>> Improve awkward heading in git-bisect documentation. >> [...] >>> -Avoiding to test a commit >>> -~~~~~~~~~~~~~~~~~~~~~~~~~ >>> +Changing the revision to test >>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ >>> >>> If in a middle of bisect session, you know what the bisect suggested >>> to try next is not a good one to test (e.g. the change the commit >> >> It is, I guess, better, but is it the best heading? What we want to >> describe here is how to deal when bisect stops on commit which cannot >> be tested (e.g. project does not compile). > > I disagree. The situation you want to use this is more general than > that. Maybe you could test it, but doing so would be a waste of time > because the commit is a trivial comment change. In general, this > simply what you need to know when you want to change the revision > under test. I agree with your reasoning. Being able to test a different commit than the suggested one is a useful feature of bisect, and we would want to help readers by mentioning, as widely as possible, in what situations this mode of operation that is described in the section is applicable. Before your change, the title describes "One very typical situation in which you may want to do what we teach in this section" (i.e. "I do not want to test this commit"), the first paragraph describes the situation a bit further, and then the remainder gives how. After your change, the title describes "What we teach you how to do in this section", the first paragraph of the section describes "Why you may want to do such a thing". A title is only one line. It cannot afford to be too verbose. People, when they have problems, tend to skim documentation to see if there is something applicable to their situation. At least "Avoiding to test a commit" should have worded "Avoiding to test the suggested commit" to draw attention better from people in such a situation, and I agree with you that "Changing the revision to test", "Testing a different revision", etc. would work much better for that purpose. But at the same time, I think the first paragraph "Why you may want to do such a thing" should be strenghtened to cover wider scenario without going to verbose, especially now the title has become even more bland --- it now tells "what you would do" without hinting "why you might want to" anymore. It currently talks only about what you said in your response "you could, but you do not want to as you know it is a waste of time", and no other scenarios you hinted in your response by saying "more general than that". Making the first paragraph richer would help the readers who spotted the (now better reworded) title to decide that the section indeed applies to their situation. Also, I think the section that follows this part should be part of this section. Either you reset to a specific commit, or you use "bisect skip" to pick another one for you. Both are solutions to the same problem. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
