hgbook
changeset 282:7a6bd93174bd
Update bisect docs
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Mon Dec 31 20:06:58 2007 -0800 (2007-12-31) |
parents | a880d07f2d29 |
children | 4ed483f08e33 |
files | en/examples/bisect en/examples/bisect.commits.out en/examples/bisect.help.out en/examples/bisect.init.out en/examples/bisect.search.bad-init.out en/examples/bisect.search.good-init.out en/examples/bisect.search.init.out en/examples/bisect.search.reset.out en/examples/bisect.search.rest.out en/examples/bisect.search.step1.out en/examples/bisect.search.step2.out en/hgext.tex en/mq.tex en/undo.tex |
line diff
1.1 --- a/en/examples/bisect Mon Dec 17 23:16:59 2007 -0500 1.2 +++ b/en/examples/bisect Mon Dec 31 20:06:58 2007 -0800 1.3 @@ -30,19 +30,18 @@ 1.4 #$ name: help 1.5 1.6 hg help bisect 1.7 -hg bisect help 1.8 1.9 #$ name: search.init 1.10 1.11 -hg bisect init 1.12 +hg bisect --init 1.13 1.14 #$ name: search.bad-init 1.15 1.16 -hg bisect bad 1.17 +hg bisect --bad 1.18 1.19 #$ name: search.good-init 1.20 1.21 -hg bisect good 10 1.22 +hg bisect --good 10 1.23 1.24 #$ name: search.step1 1.25 1.26 @@ -54,7 +53,7 @@ 1.27 fi 1.28 1.29 echo this revision is $result 1.30 -hg bisect $result 1.31 +hg bisect --$result 1.32 1.33 #$ name: search.mytest 1.34 1.35 @@ -67,7 +66,7 @@ 1.36 fi 1.37 1.38 echo this revision is $result 1.39 - hg bisect $result 1.40 + hg bisect --$result 1.41 } 1.42 1.43 #$ name: search.step2 1.44 @@ -82,7 +81,7 @@ 1.45 1.46 #$ name: search.reset 1.47 1.48 -hg bisect reset 1.49 +hg bisect --reset 1.50 1.51 #$ name: 1.52
2.1 --- a/en/examples/bisect.commits.out Mon Dec 17 23:16:59 2007 -0500 2.2 +++ b/en/examples/bisect.commits.out Mon Dec 31 20:06:58 2007 -0800 2.3 @@ -8,3 +8,38 @@ 2.4 2.5 2.6 2.7 + 2.8 + 2.9 + 2.10 + 2.11 + 2.12 + 2.13 + 2.14 + 2.15 + 2.16 + 2.17 + 2.18 + 2.19 + 2.20 + 2.21 + 2.22 + 2.23 + 2.24 + 2.25 + 2.26 + 2.27 + 2.28 + 2.29 + 2.30 + 2.31 + 2.32 + 2.33 + 2.34 + 2.35 + 2.36 + 2.37 + 2.38 + 2.39 + 2.40 + 2.41 +
3.1 --- a/en/examples/bisect.help.out Mon Dec 17 23:16:59 2007 -0500 3.2 +++ b/en/examples/bisect.help.out Mon Dec 31 20:06:58 2007 -0800 3.3 @@ -24,6 +24,3 @@ 3.4 3.5 3.6 3.7 - 3.8 - 3.9 -
4.1 --- a/en/examples/bisect.init.out Mon Dec 17 23:16:59 2007 -0500 4.2 +++ b/en/examples/bisect.init.out Mon Dec 31 20:06:58 2007 -0800 4.3 @@ -1,2 +1,3 @@ 4.4 4.5 4.6 +
5.1 --- a/en/examples/bisect.search.bad-init.out Mon Dec 17 23:16:59 2007 -0500 5.2 +++ b/en/examples/bisect.search.bad-init.out Mon Dec 31 20:06:58 2007 -0800 5.3 @@ -1,1 +1,2 @@ 5.4 5.5 +
6.1 --- a/en/examples/bisect.search.good-init.out Mon Dec 17 23:16:59 2007 -0500 6.2 +++ b/en/examples/bisect.search.good-init.out Mon Dec 31 20:06:58 2007 -0800 6.3 @@ -1,3 +1,4 @@ 6.4 6.5 6.6 6.7 +
7.1 --- a/en/examples/bisect.search.init.out Mon Dec 17 23:16:59 2007 -0500 7.2 +++ b/en/examples/bisect.search.init.out Mon Dec 31 20:06:58 2007 -0800 7.3 @@ -1,3 +1,27 @@ 7.4 7.5 7.6 7.7 + 7.8 + 7.9 + 7.10 + 7.11 + 7.12 + 7.13 + 7.14 + 7.15 + 7.16 + 7.17 + 7.18 + 7.19 + 7.20 + 7.21 + 7.22 + 7.23 + 7.24 + 7.25 + 7.26 + 7.27 + 7.28 + 7.29 + 7.30 +
8.1 --- a/en/examples/bisect.search.reset.out Mon Dec 17 23:16:59 2007 -0500 8.2 +++ b/en/examples/bisect.search.reset.out Mon Dec 31 20:06:58 2007 -0800 8.3 @@ -1,1 +1,2 @@ 8.4 8.5 +
9.1 --- a/en/examples/bisect.search.rest.out Mon Dec 17 23:16:59 2007 -0500 9.2 +++ b/en/examples/bisect.search.rest.out Mon Dec 31 20:06:58 2007 -0800 9.3 @@ -14,3 +14,6 @@ 9.4 9.5 9.6 9.7 + 9.8 + 9.9 +
10.1 --- a/en/examples/bisect.search.step1.out Mon Dec 17 23:16:59 2007 -0500 10.2 +++ b/en/examples/bisect.search.step1.out Mon Dec 31 20:06:58 2007 -0800 10.3 @@ -9,3 +9,4 @@ 10.4 10.5 10.6 10.7 +
11.1 --- a/en/examples/bisect.search.step2.out Mon Dec 17 23:16:59 2007 -0500 11.2 +++ b/en/examples/bisect.search.step2.out Mon Dec 31 20:06:58 2007 -0800 11.3 @@ -2,3 +2,4 @@ 11.4 11.5 11.6 11.7 +
12.1 --- a/en/hgext.tex Mon Dec 17 23:16:59 2007 -0500 12.2 +++ b/en/hgext.tex Mon Dec 31 20:06:58 2007 -0800 12.3 @@ -14,9 +14,6 @@ 12.4 \item Section~\ref{sec:tour-merge:fetch} covers the \hgext{fetch} 12.5 extension; this combines pulling new changes and merging them with 12.6 local changes into a single command, \hgxcmd{fetch}{fetch}. 12.7 -\item The \hgext{bisect} extension adds an efficient pruning search 12.8 - for changes that introduced bugs, and we documented it in 12.9 - chapter~\ref{sec:undo:bisect}. 12.10 \item In chapter~\ref{chap:hook}, we covered several extensions that 12.11 are useful for hook-related functionality: \hgext{acl} adds access 12.12 control lists; \hgext{bugzilla} adds integration with the Bugzilla
13.1 --- a/en/mq.tex Mon Dec 17 23:16:59 2007 -0500 13.2 +++ b/en/mq.tex Mon Dec 31 20:06:58 2007 -0800 13.3 @@ -146,7 +146,7 @@ 13.4 interplay with the code they're based on---\emph{enormously} easier. 13.5 Since every applied patch has an associated changeset, you can use 13.6 \hgcmdargs{log}{\emph{filename}} to see which changesets and patches 13.7 -affected a file. You can use the \hgext{bisect} extension to 13.8 +affected a file. You can use the \hgext{bisect} command to 13.9 binary-search through all changesets and applied patches to see where 13.10 a bug got introduced or fixed. You can use the \hgcmd{annotate} 13.11 command to see which changeset or patch modified a particular line of
14.1 --- a/en/undo.tex Mon Dec 17 23:16:59 2007 -0500 14.2 +++ b/en/undo.tex Mon Dec 31 20:06:58 2007 -0800 14.3 @@ -482,19 +482,19 @@ 14.4 14.5 While it's all very well to be able to back out a changeset that 14.6 introduced a bug, this requires that you know which changeset to back 14.7 -out. Mercurial provides an invaluable extension, called 14.8 -\hgext{bisect}, that helps you to automate this process and accomplish 14.9 +out. Mercurial provides an invaluable command, called 14.10 +\hgcmd{bisect}, that helps you to automate this process and accomplish 14.11 it very efficiently. 14.12 14.13 -The idea behind the \hgext{bisect} extension is that a changeset has 14.14 +The idea behind the \hgcmd{bisect} command is that a changeset has 14.15 introduced some change of behaviour that you can identify with a 14.16 simple binary test. You don't know which piece of code introduced the 14.17 change, but you know how to test for the presence of the bug. The 14.18 -\hgext{bisect} extension uses your test to direct its search for the 14.19 +\hgcmd{bisect} command uses your test to direct its search for the 14.20 changeset that introduced the code that caused the bug. 14.21 14.22 -Here are a few scenarios to help you understand how you might apply this 14.23 -extension. 14.24 +Here are a few scenarios to help you understand how you might apply 14.25 +this command. 14.26 \begin{itemize} 14.27 \item The most recent version of your software has a bug that you 14.28 remember wasn't present a few weeks ago, but you don't know when it 14.29 @@ -515,8 +515,8 @@ 14.30 you build your project. 14.31 \end{itemize} 14.32 14.33 -From these examples, it should be clear that the \hgext{bisect} 14.34 -extension is not useful only for finding the sources of bugs. You can 14.35 +From these examples, it should be clear that the \hgcmd{bisect} 14.36 +command is not useful only for finding the sources of bugs. You can 14.37 use it to find any ``emergent property'' of a repository (anything 14.38 that you can't find from a simple text search of the files in the 14.39 tree) for which you can write a binary test. 14.40 @@ -524,10 +524,10 @@ 14.41 We'll introduce a little bit of terminology here, just to make it 14.42 clear which parts of the search process are your responsibility, and 14.43 which are Mercurial's. A \emph{test} is something that \emph{you} run 14.44 -when \hgext{bisect} chooses a changeset. A \emph{probe} is what 14.45 -\hgext{bisect} runs to tell whether a revision is good. Finally, 14.46 +when \hgcmd{bisect} chooses a changeset. A \emph{probe} is what 14.47 +\hgcmd{bisect} runs to tell whether a revision is good. Finally, 14.48 we'll use the word ``bisect'', as both a noun and a verb, to stand in 14.49 -for the phrase ``search using the \hgext{bisect} extension''. 14.50 +for the phrase ``search using the \hgcmd{bisect} command. 14.51 14.52 One simple way to automate the searching process would be simply to 14.53 probe every changeset. However, this scales poorly. If it took ten 14.54 @@ -538,47 +538,33 @@ 14.55 and limited your search to those, you'd still be looking at over 40 14.56 hours to find the changeset that introduced your bug. 14.57 14.58 -What the \emph{bisect} extension does is use its knowledge of the 14.59 +What the \hgcmd{bisect} command does is use its knowledge of the 14.60 ``shape'' of your project's revision history to perform a search in 14.61 time proportional to the \emph{logarithm} of the number of changesets 14.62 to check (the kind of search it performs is called a dichotomic 14.63 search). With this approach, searching through 10,000 changesets will 14.64 -take less than two hours, even at ten minutes per test. Limit your 14.65 -search to the last 500 changesets, and it will take less than an hour. 14.66 - 14.67 -The \hgext{bisect} extension is aware of the ``branchy'' nature of a 14.68 +take less than three hours, even at ten minutes per test (the search 14.69 +will require about 14 tests). Limit your search to the last hundred 14.70 +changesets, and it will take only about an hour (roughly seven tests). 14.71 + 14.72 +The \hgcmd{bisect} command is aware of the ``branchy'' nature of a 14.73 Mercurial project's revision history, so it has no problems dealing 14.74 with branches, merges, or multiple heads in a repoository. It can 14.75 prune entire branches of history with a single probe, which is how it 14.76 operates so efficiently. 14.77 14.78 -\subsection{Using the \hgext{bisect} extension} 14.79 - 14.80 -Here's an example of \hgext{bisect} in action. To keep the core of 14.81 -Mercurial simple, \hgext{bisect} is packaged as an extension; this 14.82 -means that it won't be present unless you explicitly enable it. To do 14.83 -this, edit your \hgrc\ and add the following section header (if it's 14.84 -not already present): 14.85 -\begin{codesample2} 14.86 - [extensions] 14.87 -\end{codesample2} 14.88 -Then add a line to this section to enable the extension: 14.89 -\begin{codesample2} 14.90 - hbisect = 14.91 -\end{codesample2} 14.92 +\subsection{Using the \hgcmd{bisect} command} 14.93 + 14.94 +Here's an example of \hgcmd{bisect} in action. 14.95 + 14.96 \begin{note} 14.97 - That's right, there's a ``\texttt{h}'' at the front of the name of 14.98 - the \hgext{bisect} extension. The reason is that Mercurial is 14.99 - written in Python, and uses a standard Python package called 14.100 - \texttt{bisect}. If you omit the ``\texttt{h}'' from the name 14.101 - ``\texttt{hbisect}'', Mercurial will erroneously find the standard 14.102 - Python \texttt{bisect} package, and try to use it as a Mercurial 14.103 - extension. This won't work, and Mercurial will crash repeatedly 14.104 - until you fix the spelling in your \hgrc. Ugh. 14.105 + In versions 0.9.5 and earlier of Mercurial, \hgcmd{bisect} was not a 14.106 + core command: it was distributed with Mercurial as an extension. 14.107 + This section describes the built-in command, not the old extension. 14.108 \end{note} 14.109 14.110 Now let's create a repository, so that we can try out the 14.111 -\hgext{bisect} extension in isolation. 14.112 +\hgcmd{bisect} command in isolation. 14.113 \interaction{bisect.init} 14.114 We'll simulate a project that has a bug in it in a simple-minded way: 14.115 create trivial changes in a loop, and nominate one specific change 14.116 @@ -588,29 +574,28 @@ 14.117 \interaction{bisect.commits} 14.118 14.119 The next thing that we'd like to do is figure out how to use the 14.120 -\hgext{bisect} extension. We can use Mercurial's normal built-in help 14.121 +\hgcmd{bisect} command. We can use Mercurial's normal built-in help 14.122 mechanism for this. 14.123 \interaction{bisect.help} 14.124 14.125 -The \hgext{bisect} extension works in steps. Each step proceeds as follows. 14.126 +The \hgcmd{bisect} command works in steps. Each step proceeds as follows. 14.127 \begin{enumerate} 14.128 \item You run your binary test. 14.129 \begin{itemize} 14.130 - \item If the test succeeded, you tell \hgext{bisect} by running the 14.131 + \item If the test succeeded, you tell \hgcmd{bisect} by running the 14.132 \hgcmdargs{bisect}{good} command. 14.133 - \item If it failed, use the \hgcmdargs{bisect}{bad} command to let 14.134 - the \hgext{bisect} extension know. 14.135 + \item If it failed, run the \hgcmdargs{bisect}{--bad} command. 14.136 \end{itemize} 14.137 -\item The extension uses your information to decide which changeset to 14.138 +\item The command uses your information to decide which changeset to 14.139 test next. 14.140 \item It updates the working directory to that changeset, and the 14.141 process begins again. 14.142 \end{enumerate} 14.143 -The process ends when \hgext{bisect} identifies a unique changeset 14.144 +The process ends when \hgcmd{bisect} identifies a unique changeset 14.145 that marks the point where your test transitioned from ``succeeding'' 14.146 to ``failing''. 14.147 14.148 -To start the search, we must run the \hgcmdargs{bisect}{init} command. 14.149 +To start the search, we must run the \hgcmdargs{bisect}{--reset} command. 14.150 \interaction{bisect.search.init} 14.151 14.152 In our case, the binary test we use is simple: we check to see if any 14.153 @@ -625,7 +610,7 @@ 14.154 \interaction{bisect.search.bad-init} 14.155 14.156 Our next task is to nominate a changeset that we know \emph{doesn't} 14.157 -have the bug; the \hgext{bisect} extension will ``bracket'' its search 14.158 +have the bug; the \hgcmd{bisect} command will ``bracket'' its search 14.159 between the first pair of good and bad changesets. In our case, we 14.160 know that revision~10 didn't have the bug. (I'll have more words 14.161 about choosing the first ``good'' changeset later.) 14.162 @@ -656,20 +641,20 @@ 14.163 done. 14.164 \interaction{bisect.search.rest} 14.165 14.166 -Even though we had~40 changesets to search through, the \hgext{bisect} 14.167 -extension let us find the changeset that introduced our ``bug'' with 14.168 -only five tests. Because the number of tests that the \hgext{bisect} 14.169 -extension grows logarithmically with the number of changesets to 14.170 +Even though we had~40 changesets to search through, the \hgcmd{bisect} 14.171 +command let us find the changeset that introduced our ``bug'' with 14.172 +only five tests. Because the number of tests that the \hgcmd{bisect} 14.173 +command grows logarithmically with the number of changesets to 14.174 search, the advantage that it has over the ``brute force'' search 14.175 approach increases with every changeset you add. 14.176 14.177 \subsection{Cleaning up after your search} 14.178 14.179 -When you're finished using the \hgext{bisect} extension in a 14.180 +When you're finished using the \hgcmd{bisect} command in a 14.181 repository, you can use the \hgcmdargs{bisect}{reset} command to drop 14.182 -the information it was using to drive your search. The extension 14.183 +the information it was using to drive your search. The command 14.184 doesn't use much space, so it doesn't matter if you forget to run this 14.185 -command. However, \hgext{bisect} won't let you start a new search in 14.186 +command. However, \hgcmd{bisect} won't let you start a new search in 14.187 that repository until you do a \hgcmdargs{bisect}{reset}. 14.188 \interaction{bisect.search.reset} 14.189 14.190 @@ -677,7 +662,7 @@ 14.191 14.192 \subsection{Give consistent input} 14.193 14.194 -The \hgext{bisect} extension requires that you correctly report the 14.195 +The \hgcmd{bisect} command requires that you correctly report the 14.196 result of every test you perform. If you tell it that a test failed 14.197 when it really succeeded, it \emph{might} be able to detect the 14.198 inconsistency. If it can identify an inconsistency in your reports, 14.199 @@ -687,16 +672,16 @@ 14.200 14.201 \subsection{Automate as much as possible} 14.202 14.203 -When I started using the \hgext{bisect} extension, I tried a few times 14.204 +When I started using the \hgcmd{bisect} command, I tried a few times 14.205 to run my tests by hand, on the command line. This is an approach 14.206 that I, at least, am not suited to. After a few tries, I found that I 14.207 was making enough mistakes that I was having to restart my searches 14.208 -several times before finally getting correct results. 14.209 - 14.210 -My initial problems with driving the \hgext{bisect} extension by hand 14.211 +several times before finally getting correct results. 14.212 + 14.213 +My initial problems with driving the \hgcmd{bisect} command by hand 14.214 occurred even with simple searches on small repositories; if the 14.215 problem you're looking for is more subtle, or the number of tests that 14.216 -\hgext{bisect} must perform increases, the likelihood of operator 14.217 +\hgcmd{bisect} must perform increases, the likelihood of operator 14.218 error ruining the search is much higher. Once I started automating my 14.219 tests, I had much better results. 14.220 14.221 @@ -713,7 +698,7 @@ 14.222 14.223 \subsection{Check your results} 14.224 14.225 -Because the output of a \hgext{bisect} search is only as good as the 14.226 +Because the output of a \hgcmd{bisect} search is only as good as the 14.227 input you give it, don't take the changeset it reports as the 14.228 absolute truth. A simple way to cross-check its report is to manually 14.229 run your test at each of the following changesets: 14.230 @@ -739,26 +724,30 @@ 14.231 is to say that it occurs before your bug has a chance to manifest 14.232 itself. If you can't avoid that other bug (for example, it prevents 14.233 your project from building), and so can't tell whether your bug is 14.234 -present in a particular changeset, the \hgext{bisect} extension cannot 14.235 -help you directly. Instead, you'll need to manually avoid the 14.236 -changesets where that bug is present, and do separate searches 14.237 -``around'' it. 14.238 +present in a particular changeset, the \hgcmd{bisect} command cannot 14.239 +help you directly. Instead, you can mark a changeset as untested by 14.240 +running \hgcmdargs{bisect}{--skip}. 14.241 14.242 A different problem could arise if your test for a bug's presence is 14.243 not specific enough. If you check for ``my program crashes'', then 14.244 both your crashing bug and an unrelated crashing bug that masks it 14.245 -will look like the same thing, and mislead \hgext{bisect}. 14.246 +will look like the same thing, and mislead \hgcmd{bisect}. 14.247 + 14.248 +Another useful situation in which to use \hgcmdargs{bisect}{--skip} is 14.249 +if you can't test a revision because your project was in a broken and 14.250 +hence untestable state at that revision, perhaps because someone 14.251 +checked in a change that prevented the project from building. 14.252 14.253 \subsection{Bracket your search lazily} 14.254 14.255 Choosing the first ``good'' and ``bad'' changesets that will mark the 14.256 end points of your search is often easy, but it bears a little 14.257 -discussion nevertheless. From the perspective of \hgext{bisect}, the 14.258 +discussion nevertheless. From the perspective of \hgcmd{bisect}, the 14.259 ``newest'' changeset is conventionally ``bad'', and the older 14.260 changeset is ``good''. 14.261 14.262 If you're having trouble remembering when a suitable ``good'' change 14.263 -was, so that you can tell \hgext{bisect}, you could do worse than 14.264 +was, so that you can tell \hgcmd{bisect}, you could do worse than 14.265 testing changesets at random. Just remember to eliminate contenders 14.266 that can't possibly exhibit the bug (perhaps because the feature with 14.267 the bug isn't present yet) and those where another problem masks the 14.268 @@ -766,7 +755,7 @@ 14.269 14.270 Even if you end up ``early'' by thousands of changesets or months of 14.271 history, you will only add a handful of tests to the total number that 14.272 -\hgext{bisect} must perform, thanks to its logarithmic behaviour. 14.273 +\hgcmd{bisect} must perform, thanks to its logarithmic behaviour. 14.274 14.275 %%% Local Variables: 14.276 %%% mode: latex