hgbook
changeset 343:2fb78d342e07
changed es/Leame.1st
upgraded the list of files on translation and revision.
added a term (builtin) to the glossary
changed es/concepts.tex
file added to define labels needed by other tex files
changed es/preface.tex
killed a TODO
changed es/tour-basic.tex
I have began the translation of this file. 34% completed, according to vim
changed es/undo.tex
file added to define labels needed by other tex files
upgraded the list of files on translation and revision.
added a term (builtin) to the glossary
changed es/concepts.tex
file added to define labels needed by other tex files
changed es/preface.tex
killed a TODO
changed es/tour-basic.tex
I have began the translation of this file. 34% completed, according to vim
changed es/undo.tex
file added to define labels needed by other tex files
author | jerojasro@localhost |
---|---|
date | Sun Oct 19 19:56:21 2008 -0500 (2008-10-19) |
parents | 6e427210bfe0 |
children | cbffdb4dde82 |
files | es/Leame.1st es/concepts.tex es/preface.tex es/tour-basic.tex es/undo.tex |
line diff
1.1 --- a/es/Leame.1st Sun Oct 19 17:08:11 2008 -0500 1.2 +++ b/es/Leame.1st Sun Oct 19 19:56:21 2008 -0500 1.3 @@ -28,15 +28,17 @@ 1.4 de ortografía son siempre bienvenidos. 1.5 1.6 == Archivos en proceso de traducción == 1.7 -||'''archivo''''||'''traductor'''||'''Estado'''||'''Inicio'''|| '''Fin''' || 1.8 -|| 00book.tex || Igor Támara || 100% || 16/10/2008 || 16/10/2008 || 1.9 -|| branch.tex || Igor Támara || 100% || 16/10/2008 || 19/10/2008 || 1.10 -|| preface.tex || Javier Rojas || 25% || 18/10/2008 || || 1.11 +||'''archivo''' ||'''traductor'''||'''Estado'''||'''Inicio'''|| '''Fin''' || 1.12 +|| 00book.tex || Igor Támara || 100% || 16/10/2008 || 16/10/2008 || 1.13 +|| branch.tex || Igor Támara || 100% || 16/10/2008 || 19/10/2008 || 1.14 +|| preface.tex || Javier Rojas || 100% || 18/10/2008 || 19/10/2008 || 1.15 +|| tour-basic.tex || Javier Rojas || 34% || 19/10/2008 || || 1.16 1.17 == Archivos en proceso de revisión == 1.18 -||'''archivo''''|| '''revisor''' ||'''Estado'''||'''Inicio'''|| '''Fin''' || 1.19 +||'''archivo''' || '''revisor''' ||'''Estado'''||'''Inicio'''|| '''Fin''' || 1.20 || 00book.tex || || || || || 1.21 || branch.tex || || || || || 1.22 +|| preface.tex || || || || || 1.23 1.24 1.25 == Archivos terminados == 1.26 @@ -46,6 +48,7 @@ 1.27 1.28 Branch: Rama 1.29 Bug: Fallo 1.30 + Builtin: integrada/o 1.31 Changelog: Bitácora de Cambios 1.32 Changeset: Conjunto de Cambios 1.33 Command: Orden
2.1 --- a/es/concepts.tex Sun Oct 19 17:08:11 2008 -0500 2.2 +++ b/es/concepts.tex Sun Oct 19 19:56:21 2008 -0500 2.3 @@ -0,0 +1,577 @@ 2.4 +\chapter{Behind the scenes} 2.5 +\label{chap:concepts} 2.6 + 2.7 +Unlike many revision control systems, the concepts upon which 2.8 +Mercurial is built are simple enough that it's easy to understand how 2.9 +the software really works. Knowing this certainly isn't necessary, 2.10 +but I find it useful to have a ``mental model'' of what's going on. 2.11 + 2.12 +This understanding gives me confidence that Mercurial has been 2.13 +carefully designed to be both \emph{safe} and \emph{efficient}. And 2.14 +just as importantly, if it's easy for me to retain a good idea of what 2.15 +the software is doing when I perform a revision control task, I'm less 2.16 +likely to be surprised by its behaviour. 2.17 + 2.18 +In this chapter, we'll initially cover the core concepts behind 2.19 +Mercurial's design, then continue to discuss some of the interesting 2.20 +details of its implementation. 2.21 + 2.22 +\section{Mercurial's historical record} 2.23 + 2.24 +\subsection{Tracking the history of a single file} 2.25 + 2.26 +When Mercurial tracks modifications to a file, it stores the history 2.27 +of that file in a metadata object called a \emph{filelog}. Each entry 2.28 +in the filelog contains enough information to reconstruct one revision 2.29 +of the file that is being tracked. Filelogs are stored as files in 2.30 +the \sdirname{.hg/store/data} directory. A filelog contains two kinds 2.31 +of information: revision data, and an index to help Mercurial to find 2.32 +a revision efficiently. 2.33 + 2.34 +A file that is large, or has a lot of history, has its filelog stored 2.35 +in separate data (``\texttt{.d}'' suffix) and index (``\texttt{.i}'' 2.36 +suffix) files. For small files without much history, the revision 2.37 +data and index are combined in a single ``\texttt{.i}'' file. The 2.38 +correspondence between a file in the working directory and the filelog 2.39 +that tracks its history in the repository is illustrated in 2.40 +figure~\ref{fig:concepts:filelog}. 2.41 + 2.42 +\begin{figure}[ht] 2.43 + \centering 2.44 + \grafix{filelog} 2.45 + \caption{Relationships between files in working directory and 2.46 + filelogs in repository} 2.47 + \label{fig:concepts:filelog} 2.48 +\end{figure} 2.49 + 2.50 +\subsection{Managing tracked files} 2.51 + 2.52 +Mercurial uses a structure called a \emph{manifest} to collect 2.53 +together information about the files that it tracks. Each entry in 2.54 +the manifest contains information about the files present in a single 2.55 +changeset. An entry records which files are present in the changeset, 2.56 +the revision of each file, and a few other pieces of file metadata. 2.57 + 2.58 +\subsection{Recording changeset information} 2.59 + 2.60 +The \emph{changelog} contains information about each changeset. Each 2.61 +revision records who committed a change, the changeset comment, other 2.62 +pieces of changeset-related information, and the revision of the 2.63 +manifest to use. 2.64 + 2.65 +\subsection{Relationships between revisions} 2.66 + 2.67 +Within a changelog, a manifest, or a filelog, each revision stores a 2.68 +pointer to its immediate parent (or to its two parents, if it's a 2.69 +merge revision). As I mentioned above, there are also relationships 2.70 +between revisions \emph{across} these structures, and they are 2.71 +hierarchical in nature. 2.72 + 2.73 +For every changeset in a repository, there is exactly one revision 2.74 +stored in the changelog. Each revision of the changelog contains a 2.75 +pointer to a single revision of the manifest. A revision of the 2.76 +manifest stores a pointer to a single revision of each filelog tracked 2.77 +when that changeset was created. These relationships are illustrated 2.78 +in figure~\ref{fig:concepts:metadata}. 2.79 + 2.80 +\begin{figure}[ht] 2.81 + \centering 2.82 + \grafix{metadata} 2.83 + \caption{Metadata relationships} 2.84 + \label{fig:concepts:metadata} 2.85 +\end{figure} 2.86 + 2.87 +As the illustration shows, there is \emph{not} a ``one to one'' 2.88 +relationship between revisions in the changelog, manifest, or filelog. 2.89 +If the manifest hasn't changed between two changesets, the changelog 2.90 +entries for those changesets will point to the same revision of the 2.91 +manifest. If a file that Mercurial tracks hasn't changed between two 2.92 +changesets, the entry for that file in the two revisions of the 2.93 +manifest will point to the same revision of its filelog. 2.94 + 2.95 +\section{Safe, efficient storage} 2.96 + 2.97 +The underpinnings of changelogs, manifests, and filelogs are provided 2.98 +by a single structure called the \emph{revlog}. 2.99 + 2.100 +\subsection{Efficient storage} 2.101 + 2.102 +The revlog provides efficient storage of revisions using a 2.103 +\emph{delta} mechanism. Instead of storing a complete copy of a file 2.104 +for each revision, it stores the changes needed to transform an older 2.105 +revision into the new revision. For many kinds of file data, these 2.106 +deltas are typically a fraction of a percent of the size of a full 2.107 +copy of a file. 2.108 + 2.109 +Some obsolete revision control systems can only work with deltas of 2.110 +text files. They must either store binary files as complete snapshots 2.111 +or encoded into a text representation, both of which are wasteful 2.112 +approaches. Mercurial can efficiently handle deltas of files with 2.113 +arbitrary binary contents; it doesn't need to treat text as special. 2.114 + 2.115 +\subsection{Safe operation} 2.116 +\label{sec:concepts:txn} 2.117 + 2.118 +Mercurial only ever \emph{appends} data to the end of a revlog file. 2.119 +It never modifies a section of a file after it has written it. This 2.120 +is both more robust and efficient than schemes that need to modify or 2.121 +rewrite data. 2.122 + 2.123 +In addition, Mercurial treats every write as part of a 2.124 +\emph{transaction} that can span a number of files. A transaction is 2.125 +\emph{atomic}: either the entire transaction succeeds and its effects 2.126 +are all visible to readers in one go, or the whole thing is undone. 2.127 +This guarantee of atomicity means that if you're running two copies of 2.128 +Mercurial, where one is reading data and one is writing it, the reader 2.129 +will never see a partially written result that might confuse it. 2.130 + 2.131 +The fact that Mercurial only appends to files makes it easier to 2.132 +provide this transactional guarantee. The easier it is to do stuff 2.133 +like this, the more confident you should be that it's done correctly. 2.134 + 2.135 +\subsection{Fast retrieval} 2.136 + 2.137 +Mercurial cleverly avoids a pitfall common to all earlier 2.138 +revision control systems: the problem of \emph{inefficient retrieval}. 2.139 +Most revision control systems store the contents of a revision as an 2.140 +incremental series of modifications against a ``snapshot''. To 2.141 +reconstruct a specific revision, you must first read the snapshot, and 2.142 +then every one of the revisions between the snapshot and your target 2.143 +revision. The more history that a file accumulates, the more 2.144 +revisions you must read, hence the longer it takes to reconstruct a 2.145 +particular revision. 2.146 + 2.147 +\begin{figure}[ht] 2.148 + \centering 2.149 + \grafix{snapshot} 2.150 + \caption{Snapshot of a revlog, with incremental deltas} 2.151 + \label{fig:concepts:snapshot} 2.152 +\end{figure} 2.153 + 2.154 +The innovation that Mercurial applies to this problem is simple but 2.155 +effective. Once the cumulative amount of delta information stored 2.156 +since the last snapshot exceeds a fixed threshold, it stores a new 2.157 +snapshot (compressed, of course), instead of another delta. This 2.158 +makes it possible to reconstruct \emph{any} revision of a file 2.159 +quickly. This approach works so well that it has since been copied by 2.160 +several other revision control systems. 2.161 + 2.162 +Figure~\ref{fig:concepts:snapshot} illustrates the idea. In an entry 2.163 +in a revlog's index file, Mercurial stores the range of entries from 2.164 +the data file that it must read to reconstruct a particular revision. 2.165 + 2.166 +\subsubsection{Aside: the influence of video compression} 2.167 + 2.168 +If you're familiar with video compression or have ever watched a TV 2.169 +feed through a digital cable or satellite service, you may know that 2.170 +most video compression schemes store each frame of video as a delta 2.171 +against its predecessor frame. In addition, these schemes use 2.172 +``lossy'' compression techniques to increase the compression ratio, so 2.173 +visual errors accumulate over the course of a number of inter-frame 2.174 +deltas. 2.175 + 2.176 +Because it's possible for a video stream to ``drop out'' occasionally 2.177 +due to signal glitches, and to limit the accumulation of artefacts 2.178 +introduced by the lossy compression process, video encoders 2.179 +periodically insert a complete frame (called a ``key frame'') into the 2.180 +video stream; the next delta is generated against that frame. This 2.181 +means that if the video signal gets interrupted, it will resume once 2.182 +the next key frame is received. Also, the accumulation of encoding 2.183 +errors restarts anew with each key frame. 2.184 + 2.185 +\subsection{Identification and strong integrity} 2.186 + 2.187 +Along with delta or snapshot information, a revlog entry contains a 2.188 +cryptographic hash of the data that it represents. This makes it 2.189 +difficult to forge the contents of a revision, and easy to detect 2.190 +accidental corruption. 2.191 + 2.192 +Hashes provide more than a mere check against corruption; they are 2.193 +used as the identifiers for revisions. The changeset identification 2.194 +hashes that you see as an end user are from revisions of the 2.195 +changelog. Although filelogs and the manifest also use hashes, 2.196 +Mercurial only uses these behind the scenes. 2.197 + 2.198 +Mercurial verifies that hashes are correct when it retrieves file 2.199 +revisions and when it pulls changes from another repository. If it 2.200 +encounters an integrity problem, it will complain and stop whatever 2.201 +it's doing. 2.202 + 2.203 +In addition to the effect it has on retrieval efficiency, Mercurial's 2.204 +use of periodic snapshots makes it more robust against partial data 2.205 +corruption. If a revlog becomes partly corrupted due to a hardware 2.206 +error or system bug, it's often possible to reconstruct some or most 2.207 +revisions from the uncorrupted sections of the revlog, both before and 2.208 +after the corrupted section. This would not be possible with a 2.209 +delta-only storage model. 2.210 + 2.211 +\section{Revision history, branching, 2.212 + and merging} 2.213 + 2.214 +Every entry in a Mercurial revlog knows the identity of its immediate 2.215 +ancestor revision, usually referred to as its \emph{parent}. In fact, 2.216 +a revision contains room for not one parent, but two. Mercurial uses 2.217 +a special hash, called the ``null ID'', to represent the idea ``there 2.218 +is no parent here''. This hash is simply a string of zeroes. 2.219 + 2.220 +In figure~\ref{fig:concepts:revlog}, you can see an example of the 2.221 +conceptual structure of a revlog. Filelogs, manifests, and changelogs 2.222 +all have this same structure; they differ only in the kind of data 2.223 +stored in each delta or snapshot. 2.224 + 2.225 +The first revision in a revlog (at the bottom of the image) has the 2.226 +null ID in both of its parent slots. For a ``normal'' revision, its 2.227 +first parent slot contains the ID of its parent revision, and its 2.228 +second contains the null ID, indicating that the revision has only one 2.229 +real parent. Any two revisions that have the same parent ID are 2.230 +branches. A revision that represents a merge between branches has two 2.231 +normal revision IDs in its parent slots. 2.232 + 2.233 +\begin{figure}[ht] 2.234 + \centering 2.235 + \grafix{revlog} 2.236 + \caption{} 2.237 + \label{fig:concepts:revlog} 2.238 +\end{figure} 2.239 + 2.240 +\section{The working directory} 2.241 + 2.242 +In the working directory, Mercurial stores a snapshot of the files 2.243 +from the repository as of a particular changeset. 2.244 + 2.245 +The working directory ``knows'' which changeset it contains. When you 2.246 +update the working directory to contain a particular changeset, 2.247 +Mercurial looks up the appropriate revision of the manifest to find 2.248 +out which files it was tracking at the time that changeset was 2.249 +committed, and which revision of each file was then current. It then 2.250 +recreates a copy of each of those files, with the same contents it had 2.251 +when the changeset was committed. 2.252 + 2.253 +The \emph{dirstate} contains Mercurial's knowledge of the working 2.254 +directory. This details which changeset the working directory is 2.255 +updated to, and all of the files that Mercurial is tracking in the 2.256 +working directory. 2.257 + 2.258 +Just as a revision of a revlog has room for two parents, so that it 2.259 +can represent either a normal revision (with one parent) or a merge of 2.260 +two earlier revisions, the dirstate has slots for two parents. When 2.261 +you use the \hgcmd{update} command, the changeset that you update to 2.262 +is stored in the ``first parent'' slot, and the null ID in the second. 2.263 +When you \hgcmd{merge} with another changeset, the first parent 2.264 +remains unchanged, and the second parent is filled in with the 2.265 +changeset you're merging with. The \hgcmd{parents} command tells you 2.266 +what the parents of the dirstate are. 2.267 + 2.268 +\subsection{What happens when you commit} 2.269 + 2.270 +The dirstate stores parent information for more than just book-keeping 2.271 +purposes. Mercurial uses the parents of the dirstate as \emph{the 2.272 + parents of a new changeset} when you perform a commit. 2.273 + 2.274 +\begin{figure}[ht] 2.275 + \centering 2.276 + \grafix{wdir} 2.277 + \caption{The working directory can have two parents} 2.278 + \label{fig:concepts:wdir} 2.279 +\end{figure} 2.280 + 2.281 +Figure~\ref{fig:concepts:wdir} shows the normal state of the working 2.282 +directory, where it has a single changeset as parent. That changeset 2.283 +is the \emph{tip}, the newest changeset in the repository that has no 2.284 +children. 2.285 + 2.286 +\begin{figure}[ht] 2.287 + \centering 2.288 + \grafix{wdir-after-commit} 2.289 + \caption{The working directory gains new parents after a commit} 2.290 + \label{fig:concepts:wdir-after-commit} 2.291 +\end{figure} 2.292 + 2.293 +It's useful to think of the working directory as ``the changeset I'm 2.294 +about to commit''. Any files that you tell Mercurial that you've 2.295 +added, removed, renamed, or copied will be reflected in that 2.296 +changeset, as will modifications to any files that Mercurial is 2.297 +already tracking; the new changeset will have the parents of the 2.298 +working directory as its parents. 2.299 + 2.300 +After a commit, Mercurial will update the parents of the working 2.301 +directory, so that the first parent is the ID of the new changeset, 2.302 +and the second is the null ID. This is shown in 2.303 +figure~\ref{fig:concepts:wdir-after-commit}. Mercurial doesn't touch 2.304 +any of the files in the working directory when you commit; it just 2.305 +modifies the dirstate to note its new parents. 2.306 + 2.307 +\subsection{Creating a new head} 2.308 + 2.309 +It's perfectly normal to update the working directory to a changeset 2.310 +other than the current tip. For example, you might want to know what 2.311 +your project looked like last Tuesday, or you could be looking through 2.312 +changesets to see which one introduced a bug. In cases like this, the 2.313 +natural thing to do is update the working directory to the changeset 2.314 +you're interested in, and then examine the files in the working 2.315 +directory directly to see their contents as they werea when you 2.316 +committed that changeset. The effect of this is shown in 2.317 +figure~\ref{fig:concepts:wdir-pre-branch}. 2.318 + 2.319 +\begin{figure}[ht] 2.320 + \centering 2.321 + \grafix{wdir-pre-branch} 2.322 + \caption{The working directory, updated to an older changeset} 2.323 + \label{fig:concepts:wdir-pre-branch} 2.324 +\end{figure} 2.325 + 2.326 +Having updated the working directory to an older changeset, what 2.327 +happens if you make some changes, and then commit? Mercurial behaves 2.328 +in the same way as I outlined above. The parents of the working 2.329 +directory become the parents of the new changeset. This new changeset 2.330 +has no children, so it becomes the new tip. And the repository now 2.331 +contains two changesets that have no children; we call these 2.332 +\emph{heads}. You can see the structure that this creates in 2.333 +figure~\ref{fig:concepts:wdir-branch}. 2.334 + 2.335 +\begin{figure}[ht] 2.336 + \centering 2.337 + \grafix{wdir-branch} 2.338 + \caption{After a commit made while synced to an older changeset} 2.339 + \label{fig:concepts:wdir-branch} 2.340 +\end{figure} 2.341 + 2.342 +\begin{note} 2.343 + If you're new to Mercurial, you should keep in mind a common 2.344 + ``error'', which is to use the \hgcmd{pull} command without any 2.345 + options. By default, the \hgcmd{pull} command \emph{does not} 2.346 + update the working directory, so you'll bring new changesets into 2.347 + your repository, but the working directory will stay synced at the 2.348 + same changeset as before the pull. If you make some changes and 2.349 + commit afterwards, you'll thus create a new head, because your 2.350 + working directory isn't synced to whatever the current tip is. 2.351 + 2.352 + I put the word ``error'' in quotes because all that you need to do 2.353 + to rectify this situation is \hgcmd{merge}, then \hgcmd{commit}. In 2.354 + other words, this almost never has negative consequences; it just 2.355 + surprises people. I'll discuss other ways to avoid this behaviour, 2.356 + and why Mercurial behaves in this initially surprising way, later 2.357 + on. 2.358 +\end{note} 2.359 + 2.360 +\subsection{Merging heads} 2.361 + 2.362 +When you run the \hgcmd{merge} command, Mercurial leaves the first 2.363 +parent of the working directory unchanged, and sets the second parent 2.364 +to the changeset you're merging with, as shown in 2.365 +figure~\ref{fig:concepts:wdir-merge}. 2.366 + 2.367 +\begin{figure}[ht] 2.368 + \centering 2.369 + \grafix{wdir-merge} 2.370 + \caption{Merging two heads} 2.371 + \label{fig:concepts:wdir-merge} 2.372 +\end{figure} 2.373 + 2.374 +Mercurial also has to modify the working directory, to merge the files 2.375 +managed in the two changesets. Simplified a little, the merging 2.376 +process goes like this, for every file in the manifests of both 2.377 +changesets. 2.378 +\begin{itemize} 2.379 +\item If neither changeset has modified a file, do nothing with that 2.380 + file. 2.381 +\item If one changeset has modified a file, and the other hasn't, 2.382 + create the modified copy of the file in the working directory. 2.383 +\item If one changeset has removed a file, and the other hasn't (or 2.384 + has also deleted it), delete the file from the working directory. 2.385 +\item If one changeset has removed a file, but the other has modified 2.386 + the file, ask the user what to do: keep the modified file, or remove 2.387 + it? 2.388 +\item If both changesets have modified a file, invoke an external 2.389 + merge program to choose the new contents for the merged file. This 2.390 + may require input from the user. 2.391 +\item If one changeset has modified a file, and the other has renamed 2.392 + or copied the file, make sure that the changes follow the new name 2.393 + of the file. 2.394 +\end{itemize} 2.395 +There are more details---merging has plenty of corner cases---but 2.396 +these are the most common choices that are involved in a merge. As 2.397 +you can see, most cases are completely automatic, and indeed most 2.398 +merges finish automatically, without requiring your input to resolve 2.399 +any conflicts. 2.400 + 2.401 +When you're thinking about what happens when you commit after a merge, 2.402 +once again the working directory is ``the changeset I'm about to 2.403 +commit''. After the \hgcmd{merge} command completes, the working 2.404 +directory has two parents; these will become the parents of the new 2.405 +changeset. 2.406 + 2.407 +Mercurial lets you perform multiple merges, but you must commit the 2.408 +results of each individual merge as you go. This is necessary because 2.409 +Mercurial only tracks two parents for both revisions and the working 2.410 +directory. While it would be technically possible to merge multiple 2.411 +changesets at once, the prospect of user confusion and making a 2.412 +terrible mess of a merge immediately becomes overwhelming. 2.413 + 2.414 +\section{Other interesting design features} 2.415 + 2.416 +In the sections above, I've tried to highlight some of the most 2.417 +important aspects of Mercurial's design, to illustrate that it pays 2.418 +careful attention to reliability and performance. However, the 2.419 +attention to detail doesn't stop there. There are a number of other 2.420 +aspects of Mercurial's construction that I personally find 2.421 +interesting. I'll detail a few of them here, separate from the ``big 2.422 +ticket'' items above, so that if you're interested, you can gain a 2.423 +better idea of the amount of thinking that goes into a well-designed 2.424 +system. 2.425 + 2.426 +\subsection{Clever compression} 2.427 + 2.428 +When appropriate, Mercurial will store both snapshots and deltas in 2.429 +compressed form. It does this by always \emph{trying to} compress a 2.430 +snapshot or delta, but only storing the compressed version if it's 2.431 +smaller than the uncompressed version. 2.432 + 2.433 +This means that Mercurial does ``the right thing'' when storing a file 2.434 +whose native form is compressed, such as a \texttt{zip} archive or a 2.435 +JPEG image. When these types of files are compressed a second time, 2.436 +the resulting file is usually bigger than the once-compressed form, 2.437 +and so Mercurial will store the plain \texttt{zip} or JPEG. 2.438 + 2.439 +Deltas between revisions of a compressed file are usually larger than 2.440 +snapshots of the file, and Mercurial again does ``the right thing'' in 2.441 +these cases. It finds that such a delta exceeds the threshold at 2.442 +which it should store a complete snapshot of the file, so it stores 2.443 +the snapshot, again saving space compared to a naive delta-only 2.444 +approach. 2.445 + 2.446 +\subsubsection{Network recompression} 2.447 + 2.448 +When storing revisions on disk, Mercurial uses the ``deflate'' 2.449 +compression algorithm (the same one used by the popular \texttt{zip} 2.450 +archive format), which balances good speed with a respectable 2.451 +compression ratio. However, when transmitting revision data over a 2.452 +network connection, Mercurial uncompresses the compressed revision 2.453 +data. 2.454 + 2.455 +If the connection is over HTTP, Mercurial recompresses the entire 2.456 +stream of data using a compression algorithm that gives a better 2.457 +compression ratio (the Burrows-Wheeler algorithm from the widely used 2.458 +\texttt{bzip2} compression package). This combination of algorithm 2.459 +and compression of the entire stream (instead of a revision at a time) 2.460 +substantially reduces the number of bytes to be transferred, yielding 2.461 +better network performance over almost all kinds of network. 2.462 + 2.463 +(If the connection is over \command{ssh}, Mercurial \emph{doesn't} 2.464 +recompress the stream, because \command{ssh} can already do this 2.465 +itself.) 2.466 + 2.467 +\subsection{Read/write ordering and atomicity} 2.468 + 2.469 +Appending to files isn't the whole story when it comes to guaranteeing 2.470 +that a reader won't see a partial write. If you recall 2.471 +figure~\ref{fig:concepts:metadata}, revisions in the changelog point to 2.472 +revisions in the manifest, and revisions in the manifest point to 2.473 +revisions in filelogs. This hierarchy is deliberate. 2.474 + 2.475 +A writer starts a transaction by writing filelog and manifest data, 2.476 +and doesn't write any changelog data until those are finished. A 2.477 +reader starts by reading changelog data, then manifest data, followed 2.478 +by filelog data. 2.479 + 2.480 +Since the writer has always finished writing filelog and manifest data 2.481 +before it writes to the changelog, a reader will never read a pointer 2.482 +to a partially written manifest revision from the changelog, and it will 2.483 +never read a pointer to a partially written filelog revision from the 2.484 +manifest. 2.485 + 2.486 +\subsection{Concurrent access} 2.487 + 2.488 +The read/write ordering and atomicity guarantees mean that Mercurial 2.489 +never needs to \emph{lock} a repository when it's reading data, even 2.490 +if the repository is being written to while the read is occurring. 2.491 +This has a big effect on scalability; you can have an arbitrary number 2.492 +of Mercurial processes safely reading data from a repository safely 2.493 +all at once, no matter whether it's being written to or not. 2.494 + 2.495 +The lockless nature of reading means that if you're sharing a 2.496 +repository on a multi-user system, you don't need to grant other local 2.497 +users permission to \emph{write} to your repository in order for them 2.498 +to be able to clone it or pull changes from it; they only need 2.499 +\emph{read} permission. (This is \emph{not} a common feature among 2.500 +revision control systems, so don't take it for granted! Most require 2.501 +readers to be able to lock a repository to access it safely, and this 2.502 +requires write permission on at least one directory, which of course 2.503 +makes for all kinds of nasty and annoying security and administrative 2.504 +problems.) 2.505 + 2.506 +Mercurial uses locks to ensure that only one process can write to a 2.507 +repository at a time (the locking mechanism is safe even over 2.508 +filesystems that are notoriously hostile to locking, such as NFS). If 2.509 +a repository is locked, a writer will wait for a while to retry if the 2.510 +repository becomes unlocked, but if the repository remains locked for 2.511 +too long, the process attempting to write will time out after a while. 2.512 +This means that your daily automated scripts won't get stuck forever 2.513 +and pile up if a system crashes unnoticed, for example. (Yes, the 2.514 +timeout is configurable, from zero to infinity.) 2.515 + 2.516 +\subsubsection{Safe dirstate access} 2.517 + 2.518 +As with revision data, Mercurial doesn't take a lock to read the 2.519 +dirstate file; it does acquire a lock to write it. To avoid the 2.520 +possibility of reading a partially written copy of the dirstate file, 2.521 +Mercurial writes to a file with a unique name in the same directory as 2.522 +the dirstate file, then renames the temporary file atomically to 2.523 +\filename{dirstate}. The file named \filename{dirstate} is thus 2.524 +guaranteed to be complete, not partially written. 2.525 + 2.526 +\subsection{Avoiding seeks} 2.527 + 2.528 +Critical to Mercurial's performance is the avoidance of seeks of the 2.529 +disk head, since any seek is far more expensive than even a 2.530 +comparatively large read operation. 2.531 + 2.532 +This is why, for example, the dirstate is stored in a single file. If 2.533 +there were a dirstate file per directory that Mercurial tracked, the 2.534 +disk would seek once per directory. Instead, Mercurial reads the 2.535 +entire single dirstate file in one step. 2.536 + 2.537 +Mercurial also uses a ``copy on write'' scheme when cloning a 2.538 +repository on local storage. Instead of copying every revlog file 2.539 +from the old repository into the new repository, it makes a ``hard 2.540 +link'', which is a shorthand way to say ``these two names point to the 2.541 +same file''. When Mercurial is about to write to one of a revlog's 2.542 +files, it checks to see if the number of names pointing at the file is 2.543 +greater than one. If it is, more than one repository is using the 2.544 +file, so Mercurial makes a new copy of the file that is private to 2.545 +this repository. 2.546 + 2.547 +A few revision control developers have pointed out that this idea of 2.548 +making a complete private copy of a file is not very efficient in its 2.549 +use of storage. While this is true, storage is cheap, and this method 2.550 +gives the highest performance while deferring most book-keeping to the 2.551 +operating system. An alternative scheme would most likely reduce 2.552 +performance and increase the complexity of the software, each of which 2.553 +is much more important to the ``feel'' of day-to-day use. 2.554 + 2.555 +\subsection{Other contents of the dirstate} 2.556 + 2.557 +Because Mercurial doesn't force you to tell it when you're modifying a 2.558 +file, it uses the dirstate to store some extra information so it can 2.559 +determine efficiently whether you have modified a file. For each file 2.560 +in the working directory, it stores the time that it last modified the 2.561 +file itself, and the size of the file at that time. 2.562 + 2.563 +When you explicitly \hgcmd{add}, \hgcmd{remove}, \hgcmd{rename} or 2.564 +\hgcmd{copy} files, Mercurial updates the dirstate so that it knows 2.565 +what to do with those files when you commit. 2.566 + 2.567 +When Mercurial is checking the states of files in the working 2.568 +directory, it first checks a file's modification time. If that has 2.569 +not changed, the file must not have been modified. If the file's size 2.570 +has changed, the file must have been modified. If the modification 2.571 +time has changed, but the size has not, only then does Mercurial need 2.572 +to read the actual contents of the file to see if they've changed. 2.573 +Storing these few extra pieces of information dramatically reduces the 2.574 +amount of data that Mercurial needs to read, which yields large 2.575 +performance improvements compared to other revision control systems. 2.576 + 2.577 +%%% Local Variables: 2.578 +%%% mode: latex 2.579 +%%% TeX-master: "00book" 2.580 +%%% End:
3.1 --- a/es/preface.tex Sun Oct 19 17:08:11 2008 -0500 3.2 +++ b/es/preface.tex Sun Oct 19 19:56:21 2008 -0500 3.3 @@ -2,8 +2,7 @@ 3.4 \addcontentsline{toc}{chapter}{Prefacio} 3.5 \label{chap:preface} 3.6 3.7 -% TODO no es mejor decir control distribuido de revisiones? 3.8 -El control de revisiones distribuido es un territorio relativamente 3.9 +El control distribuido de revisiones es un territorio relativamente 3.10 nuevo, y ha crecido hasta ahora 3.11 % TODO el original dice "due to", que sería "debido", pero creo que "gracias 3.12 % a" queda mejor 3.13 @@ -55,20 +54,19 @@ 3.14 puede ver esto en el ejemplo \hgext{bisect} en la 3.15 sección~\ref{sec:undo:bisect}, por ejemplo. 3.16 3.17 -So when you're reading examples, don't place too much weight on the 3.18 -dates or times you see in the output of commands. But \emph{do} be 3.19 -confident that the behaviour you're seeing is consistent and 3.20 -reproducible. 3.21 +Así que cuando usted lea los ejemplos, no le dé mucha importancia a 3.22 +las fechas o horas que vea en las salidas de los comandos. Pero 3.23 +\emph{tenga} confianza en que el comportamiento que está viendo es 3.24 +consistente y reproducible. 3.25 3.26 -\section{Colophon---this book is Free} 3.27 +\section{Colofón---este libro es Libre} 3.28 +Este libro está licenciado bajo la Licencia de Publicación Abierta, y 3.29 +es producido en su totalidad usando herramientas de Software Libre. Es 3.30 +compuesto con \LaTeX{}; las ilustraciones son dibujadas y generadas 3.31 +con \href{http://www.inkscape.org/}{Inkscape}. 3.32 3.33 -This book is licensed under the Open Publication License, and is 3.34 -produced entirely using Free Software tools. It is typeset with 3.35 -\LaTeX{}; illustrations are drawn and rendered with 3.36 -\href{http://www.inkscape.org/}{Inkscape}. 3.37 - 3.38 -The complete source code for this book is published as a Mercurial 3.39 -repository, at \url{http://hg.serpentine.com/mercurial/book}. 3.40 +El código fuente completo para este libro es publicado como un 3.41 +repositorio Mercurial, en \url{http://hg.serpentine.com/mercurial/book}. 3.42 3.43 %%% Local Variables: 3.44 %%% mode: latex
4.1 --- a/es/tour-basic.tex Sun Oct 19 17:08:11 2008 -0500 4.2 +++ b/es/tour-basic.tex Sun Oct 19 19:56:21 2008 -0500 4.3 @@ -0,0 +1,631 @@ 4.4 +\chapter{Una gira de Mercurial: lo básico} 4.5 +\label{chap:tour-basic} 4.6 + 4.7 +\section{Instalar Mercurial en su sistema} 4.8 +\label{sec:tour:install} 4.9 +Hay paquetes binarios precompilados de Mercurial disponibles para cada 4.10 +sistema operativo popular. Esto hace fácil empezar a usar Mercurial 4.11 +en su computador inmediatamente. 4.12 + 4.13 +\subsection{Linux} 4.14 + 4.15 +Dado que cada distribución de Linux tiene sus propias herramientas de 4.16 +manejo de paquetes, políticas, y ritmos de desarrollo, es difícil dar 4.17 +un conjunto exhaustivo de instrucciones sobre cómo instalar el paquete 4.18 +de Mercurial. La versión de Mercurial que usted tenga a disposición 4.19 +puede variar dependiendo de qué tan activa sea la persona que mantiene 4.20 +el paquete para su distribución. 4.21 + 4.22 +Para mantener las cosas simples, me enfocaré en instalar Mercurial 4.23 +desde la línea de comandos en las distribuciones de Linux más 4.24 +populares. La mayoría de estas distribuciones proveen administradores 4.25 +de paquetes gráficos que le permitirán instalar Mercurial con un solo 4.26 +clic; el nombre de paquete a buscar es \texttt{mercurial}. 4.27 + 4.28 +\begin{itemize} 4.29 +\item[Debian] 4.30 + \begin{codesample4} 4.31 + apt-get install mercurial 4.32 + \end{codesample4} 4.33 + 4.34 +\item[Fedora Core] 4.35 + \begin{codesample4} 4.36 + yum install mercurial 4.37 + \end{codesample4} 4.38 + 4.39 +\item[Gentoo] 4.40 + \begin{codesample4} 4.41 + emerge mercurial 4.42 + \end{codesample4} 4.43 + 4.44 +\item[OpenSUSE] 4.45 + \begin{codesample4} 4.46 + yum install mercurial 4.47 + \end{codesample4} 4.48 + 4.49 +\item[Ubuntu] El paquete de Mercurial de Ubuntu está basado en el de 4.50 + Debian. Para instalarlo, ejecute el siguiente comando. 4.51 + \begin{codesample4} 4.52 + apt-get install mercurial 4.53 + \end{codesample4} 4.54 + El paquete de Mercurial para Ubuntu tiende a atrasarse con respecto 4.55 + a la versión de Debian por un margen de tiempo considerable 4.56 + (al momento de escribir esto, 7 meses), lo que en algunos casos 4.57 + significará que usted puede encontrarse con problemas que ya habrán 4.58 + sido resueltos en el paquete de Debian. 4.59 +\end{itemize} 4.60 + 4.61 +\subsection{Solaris} 4.62 + 4.63 +SunFreeWare, en \url{http://www.sunfreeware.com}, es una buena fuente 4.64 +para un gran número de paquetes compilados para Solaris para las 4.65 +arquitecturas Intel y Sparc de 32 y 64 bits, incluyendo versiones 4.66 +actuales de Mercurial. 4.67 + 4.68 +\subsection{Mac OS X} 4.69 + 4.70 +Lee Cantey publica un instalador de Mercurial para Mac OS~X en 4.71 +\url{http://mercurial.berkwood.com}. Este paquete funciona en tanto 4.72 +en Macs basados en Intel como basados en PowerPC. Antes de que pueda 4.73 +usarlo, usted debe instalar una versión compatible de Universal 4.74 +MacPython~\cite{web:macpython}. Esto es fácil de hacer; simplemente 4.75 +siga las instrucciones de el sitio de Lee. 4.76 + 4.77 +También es posible instalar Mercurial usando Fink o MacPorts, dos 4.78 +administradores de paquetes gratuitos y populares para Mac OS X. Si 4.79 +usted tiene Fink, use \command{sudo apt-get install mercurial-py25}. 4.80 +Si usa MacPorts, \command{sudo port install mercurial}. 4.81 + 4.82 +\subsection{Windows} 4.83 + 4.84 +Lee Cantey publica un instalador de Mercurial para Windows en 4.85 +\url{http://mercurial.berkwood.com}. Este paquete no tiene 4.86 +% TODO traducción de it just works. Agreed? 4.87 +dependencias externas; ``simplemente funciona''. 4.88 + 4.89 +\begin{note} 4.90 + La versión de Windows de Mercurial no convierte automáticamente 4.91 + los fines de línea entre estilos Windows y Unix. Si usted desea 4.92 + compartir trabajo con usuarios de Unix, deberá hacer un trabajo 4.93 + adicional de configuración. XXX Terminar esto. 4.94 +\end{note} 4.95 + 4.96 +\section{Arrancando} 4.97 + 4.98 +Para empezar, usaremos el comando \hgcmd{version} para revisar si 4.99 +Mercurial está instalado adecuadamente. La información de la versión 4.100 +que es impresa no es tan importante; lo que nos importa es si imprime 4.101 +algo en absoluto. 4.102 + 4.103 +\interaction{tour.version} 4.104 + 4.105 +% TODO builtin-> integrado? 4.106 +\subsection{Ayuda integrada} 4.107 + 4.108 +Mercurial provee un sistema de ayuda integrada. Esto es invaluable 4.109 +para ésas ocasiones en la que usted está atorado tratando de recordar 4.110 +cómo ejecutar un comando. Si está completamente atorado, simplemente 4.111 +ejecute \hgcmd{help}; esto imprimirá una breve lista de comandos, 4.112 +junto con una descripción de qué hace cada uno. Si usted solicita 4.113 +ayuda sobre un comando específico (como abajo), se imprime información 4.114 +más detallada. 4.115 +\interaction{tour.help} 4.116 +Para un nivel más impresionante de detalle (que usted no va a 4.117 +necesitar usualmente) ejecute \hgcmdargs{help}{\hggopt{-v}}. La opción 4.118 +\hggopt{-v} es la abreviación para \hggopt{--verbose}, y le indica a 4.119 +Mercurial que imprima más información de lo que haría usualmente. 4.120 + 4.121 +\section{Working with a repository} 4.122 + 4.123 +In Mercurial, everything happens inside a \emph{repository}. The 4.124 +repository for a project contains all of the files that ``belong to'' 4.125 +that project, along with a historical record of the project's files. 4.126 + 4.127 +There's nothing particularly magical about a repository; it is simply 4.128 +a directory tree in your filesystem that Mercurial treats as special. 4.129 +You can rename or delete a repository any time you like, using either the 4.130 +command line or your file browser. 4.131 + 4.132 +\subsection{Making a local copy of a repository} 4.133 + 4.134 +\emph{Copying} a repository is just a little bit special. While you 4.135 +could use a normal file copying command to make a copy of a 4.136 +repository, it's best to use a built-in command that Mercurial 4.137 +provides. This command is called \hgcmd{clone}, because it creates an 4.138 +identical copy of an existing repository. 4.139 +\interaction{tour.clone} 4.140 +If our clone succeeded, we should now have a local directory called 4.141 +\dirname{hello}. This directory will contain some files. 4.142 +\interaction{tour.ls} 4.143 +These files have the same contents and history in our repository as 4.144 +they do in the repository we cloned. 4.145 + 4.146 +Every Mercurial repository is complete, self-contained, and 4.147 +independent. It contains its own private copy of a project's files 4.148 +and history. A cloned repository remembers the location of the 4.149 +repository it was cloned from, but it does not communicate with that 4.150 +repository, or any other, unless you tell it to. 4.151 + 4.152 +What this means for now is that we're free to experiment with our 4.153 +repository, safe in the knowledge that it's a private ``sandbox'' that 4.154 +won't affect anyone else. 4.155 + 4.156 +\subsection{What's in a repository?} 4.157 + 4.158 +When we take a more detailed look inside a repository, we can see that 4.159 +it contains a directory named \dirname{.hg}. This is where Mercurial 4.160 +keeps all of its metadata for the repository. 4.161 +\interaction{tour.ls-a} 4.162 + 4.163 +The contents of the \dirname{.hg} directory and its subdirectories are 4.164 +private to Mercurial. Every other file and directory in the 4.165 +repository is yours to do with as you please. 4.166 + 4.167 +To introduce a little terminology, the \dirname{.hg} directory is the 4.168 +``real'' repository, and all of the files and directories that coexist 4.169 +with it are said to live in the \emph{working directory}. An easy way 4.170 +to remember the distinction is that the \emph{repository} contains the 4.171 +\emph{history} of your project, while the \emph{working directory} 4.172 +contains a \emph{snapshot} of your project at a particular point in 4.173 +history. 4.174 + 4.175 +\section{A tour through history} 4.176 + 4.177 +One of the first things we might want to do with a new, unfamiliar 4.178 +repository is understand its history. The \hgcmd{log} command gives 4.179 +us a view of history. 4.180 +\interaction{tour.log} 4.181 +By default, this command prints a brief paragraph of output for each 4.182 +change to the project that was recorded. In Mercurial terminology, we 4.183 +call each of these recorded events a \emph{changeset}, because it can 4.184 +contain a record of changes to several files. 4.185 + 4.186 +The fields in a record of output from \hgcmd{log} are as follows. 4.187 +\begin{itemize} 4.188 +\item[\texttt{changeset}] This field has the format of a number, 4.189 + followed by a colon, followed by a hexadecimal string. These are 4.190 + \emph{identifiers} for the changeset. There are two identifiers 4.191 + because the number is shorter and easier to type than the hex 4.192 + string. 4.193 +\item[\texttt{user}] The identity of the person who created the 4.194 + changeset. This is a free-form field, but it most often contains a 4.195 + person's name and email address. 4.196 +\item[\texttt{date}] The date and time on which the changeset was 4.197 + created, and the timezone in which it was created. (The date and 4.198 + time are local to that timezone; they display what time and date it 4.199 + was for the person who created the changeset.) 4.200 +\item[\texttt{summary}] The first line of the text message that the 4.201 + creator of the changeset entered to describe the changeset. 4.202 +\end{itemize} 4.203 +The default output printed by \hgcmd{log} is purely a summary; it is 4.204 +missing a lot of detail. 4.205 + 4.206 +Figure~\ref{fig:tour-basic:history} provides a graphical representation of 4.207 +the history of the \dirname{hello} repository, to make it a little 4.208 +easier to see which direction history is ``flowing'' in. We'll be 4.209 +returning to this figure several times in this chapter and the chapter 4.210 +that follows. 4.211 + 4.212 +\begin{figure}[ht] 4.213 + \centering 4.214 + \grafix{tour-history} 4.215 + \caption{Graphical history of the \dirname{hello} repository} 4.216 + \label{fig:tour-basic:history} 4.217 +\end{figure} 4.218 + 4.219 +\subsection{Changesets, revisions, and talking to other 4.220 + people} 4.221 + 4.222 +As English is a notoriously sloppy language, and computer science has 4.223 +a hallowed history of terminological confusion (why use one term when 4.224 +four will do?), revision control has a variety of words and phrases 4.225 +that mean the same thing. If you are talking about Mercurial history 4.226 +with other people, you will find that the word ``changeset'' is often 4.227 +compressed to ``change'' or (when written) ``cset'', and sometimes a 4.228 +changeset is referred to as a ``revision'' or a ``rev''. 4.229 + 4.230 +While it doesn't matter what \emph{word} you use to refer to the 4.231 +concept of ``a~changeset'', the \emph{identifier} that you use to 4.232 +refer to ``a~\emph{specific} changeset'' is of great importance. 4.233 +Recall that the \texttt{changeset} field in the output from 4.234 +\hgcmd{log} identifies a changeset using both a number and a 4.235 +hexadecimal string. 4.236 +\begin{itemize} 4.237 +\item The revision number is \emph{only valid in that repository}, 4.238 +\item while the hex string is the \emph{permanent, unchanging 4.239 + identifier} that will always identify that exact changeset in 4.240 + \emph{every} copy of the repository. 4.241 +\end{itemize} 4.242 +This distinction is important. If you send someone an email talking 4.243 +about ``revision~33'', there's a high likelihood that their 4.244 +revision~33 will \emph{not be the same} as yours. The reason for this 4.245 +is that a revision number depends on the order in which changes 4.246 +arrived in a repository, and there is no guarantee that the same 4.247 +changes will happen in the same order in different repositories. 4.248 +Three changes $a,b,c$ can easily appear in one repository as $0,1,2$, 4.249 +while in another as $1,0,2$. 4.250 + 4.251 +Mercurial uses revision numbers purely as a convenient shorthand. If 4.252 +you need to discuss a changeset with someone, or make a record of a 4.253 +changeset for some other reason (for example, in a bug report), use 4.254 +the hexadecimal identifier. 4.255 + 4.256 +\subsection{Viewing specific revisions} 4.257 + 4.258 +To narrow the output of \hgcmd{log} down to a single revision, use the 4.259 +\hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a 4.260 +revision number or a long-form changeset identifier, and you can 4.261 +provide as many revisions as you want. \interaction{tour.log-r} 4.262 + 4.263 +If you want to see the history of several revisions without having to 4.264 +list each one, you can use \emph{range notation}; this lets you 4.265 +express the idea ``I want all revisions between $a$ and $b$, 4.266 +inclusive''. 4.267 +\interaction{tour.log.range} 4.268 +Mercurial also honours the order in which you specify revisions, so 4.269 +\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2} 4.270 +prints $4,3,2$. 4.271 + 4.272 +\subsection{More detailed information} 4.273 + 4.274 +While the summary information printed by \hgcmd{log} is useful if you 4.275 +already know what you're looking for, you may need to see a complete 4.276 +description of the change, or a list of the files changed, if you're 4.277 +trying to decide whether a changeset is the one you're looking for. 4.278 +The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose}) 4.279 +option gives you this extra detail. 4.280 +\interaction{tour.log-v} 4.281 + 4.282 +If you want to see both the description and content of a change, add 4.283 +the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays 4.284 +the content of a change as a \emph{unified diff} (if you've never seen 4.285 +a unified diff before, see section~\ref{sec:mq:patch} for an overview). 4.286 +\interaction{tour.log-vp} 4.287 + 4.288 +\section{All about command options} 4.289 + 4.290 +Let's take a brief break from exploring Mercurial commands to discuss 4.291 +a pattern in the way that they work; you may find this useful to keep 4.292 +in mind as we continue our tour. 4.293 + 4.294 +Mercurial has a consistent and straightforward approach to dealing 4.295 +with the options that you can pass to commands. It follows the 4.296 +conventions for options that are common to modern Linux and Unix 4.297 +systems. 4.298 +\begin{itemize} 4.299 +\item Every option has a long name. For example, as we've already 4.300 + seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option. 4.301 +\item Most options have short names, too. Instead of 4.302 + \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that 4.303 + some options don't have short names is that the options in question 4.304 + are rarely used.) 4.305 +\item Long options start with two dashes (e.g.~\hgopt{log}{--rev}), 4.306 + while short options start with one (e.g.~\hgopt{log}{-r}). 4.307 +\item Option naming and usage is consistent across commands. For 4.308 + example, every command that lets you specify a changeset~ID or 4.309 + revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev} 4.310 + arguments. 4.311 +\end{itemize} 4.312 +In the examples throughout this book, I use short options instead of 4.313 +long. This just reflects my own preference, so don't read anything 4.314 +significant into it. 4.315 + 4.316 +Most commands that print output of some kind will print more output 4.317 +when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less 4.318 +when passed \hggopt{-q} (or \hggopt{--quiet}). 4.319 + 4.320 +\section{Making and reviewing changes} 4.321 + 4.322 +Now that we have a grasp of viewing history in Mercurial, let's take a 4.323 +look at making some changes and examining them. 4.324 + 4.325 +The first thing we'll do is isolate our experiment in a repository of 4.326 +its own. We use the \hgcmd{clone} command, but we don't need to 4.327 +clone a copy of the remote repository. Since we already have a copy 4.328 +of it locally, we can just clone that instead. This is much faster 4.329 +than cloning over the network, and cloning a local repository uses 4.330 +less disk space in most cases, too. 4.331 +\interaction{tour.reclone} 4.332 +As an aside, it's often good practice to keep a ``pristine'' copy of a 4.333 +remote repository around, which you can then make temporary clones of 4.334 +to create sandboxes for each task you want to work on. This lets you 4.335 +work on multiple tasks in parallel, each isolated from the others 4.336 +until it's complete and you're ready to integrate it back. Because 4.337 +local clones are so cheap, there's almost no overhead to cloning and 4.338 +destroying repositories whenever you want. 4.339 + 4.340 +In our \dirname{my-hello} repository, we have a file 4.341 +\filename{hello.c} that contains the classic ``hello, world'' program. 4.342 +Let's use the ancient and venerable \command{sed} command to edit this 4.343 +file so that it prints a second line of output. (I'm only using 4.344 +\command{sed} to do this because it's easy to write a scripted example 4.345 +this way. Since you're not under the same constraint, you probably 4.346 +won't want to use \command{sed}; simply use your preferred text editor to 4.347 +do the same thing.) 4.348 +\interaction{tour.sed} 4.349 + 4.350 +Mercurial's \hgcmd{status} command will tell us what Mercurial knows 4.351 +about the files in the repository. 4.352 +\interaction{tour.status} 4.353 +The \hgcmd{status} command prints no output for some files, but a line 4.354 +starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell 4.355 +it to, \hgcmd{status} will not print any output for files that have 4.356 +not been modified. 4.357 + 4.358 +The ``\texttt{M}'' indicates that Mercurial has noticed that we 4.359 +modified \filename{hello.c}. We didn't need to \emph{inform} 4.360 +Mercurial that we were going to modify the file before we started, or 4.361 +that we had modified the file after we were done; it was able to 4.362 +figure this out itself. 4.363 + 4.364 +It's a little bit helpful to know that we've modified 4.365 +\filename{hello.c}, but we might prefer to know exactly \emph{what} 4.366 +changes we've made to it. To do this, we use the \hgcmd{diff} 4.367 +command. 4.368 +\interaction{tour.diff} 4.369 + 4.370 +\section{Recording changes in a new changeset} 4.371 + 4.372 +We can modify files, build and test our changes, and use 4.373 +\hgcmd{status} and \hgcmd{diff} to review our changes, until we're 4.374 +satisfied with what we've done and arrive at a natural stopping point 4.375 +where we want to record our work in a new changeset. 4.376 + 4.377 +The \hgcmd{commit} command lets us create a new changeset; we'll 4.378 +usually refer to this as ``making a commit'' or ``committing''. 4.379 + 4.380 +\subsection{Setting up a username} 4.381 + 4.382 +When you try to run \hgcmd{commit} for the first time, it is not 4.383 +guaranteed to succeed. Mercurial records your name and address with 4.384 +each change that you commit, so that you and others will later be able 4.385 +to tell who made each change. Mercurial tries to automatically figure 4.386 +out a sensible username to commit the change with. It will attempt 4.387 +each of the following methods, in order: 4.388 +\begin{enumerate} 4.389 +\item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit} 4.390 + command on the command line, followed by a username, this is always 4.391 + given the highest precedence. 4.392 +\item If you have set the \envar{HGUSER} environment variable, this is 4.393 + checked next. 4.394 +\item If you create a file in your home directory called 4.395 + \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be 4.396 + used next. To see what the contents of this file should look like, 4.397 + refer to section~\ref{sec:tour-basic:username} below. 4.398 +\item If you have set the \envar{EMAIL} environment variable, this 4.399 + will be used next. 4.400 +\item Mercurial will query your system to find out your local user 4.401 + name and host name, and construct a username from these components. 4.402 + Since this often results in a username that is not very useful, it 4.403 + will print a warning if it has to do this. 4.404 +\end{enumerate} 4.405 +If all of these mechanisms fail, Mercurial will fail, printing an 4.406 +error message. In this case, it will not let you commit until you set 4.407 +up a username. 4.408 + 4.409 +You should think of the \envar{HGUSER} environment variable and the 4.410 +\hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to 4.411 +\emph{override} Mercurial's default selection of username. For normal 4.412 +use, the simplest and most robust way to set a username for yourself 4.413 +is by creating a \sfilename{.hgrc} file; see below for details. 4.414 + 4.415 +\subsubsection{Creating a Mercurial configuration file} 4.416 +\label{sec:tour-basic:username} 4.417 + 4.418 +To set a user name, use your favourite editor to create a file called 4.419 +\sfilename{.hgrc} in your home directory. Mercurial will use this 4.420 +file to look up your personalised configuration settings. The initial 4.421 +contents of your \sfilename{.hgrc} should look like this. 4.422 +\begin{codesample2} 4.423 + # This is a Mercurial configuration file. 4.424 + [ui] 4.425 + username = Firstname Lastname <email.address@domain.net> 4.426 +\end{codesample2} 4.427 +The ``\texttt{[ui]}'' line begins a \emph{section} of the config file, 4.428 +so you can read the ``\texttt{username = ...}'' line as meaning ``set 4.429 +the value of the \texttt{username} item in the \texttt{ui} section''. 4.430 +A section continues until a new section begins, or the end of the 4.431 +file. Mercurial ignores empty lines and treats any text from 4.432 +``\texttt{\#}'' to the end of a line as a comment. 4.433 + 4.434 +\subsubsection{Choosing a user name} 4.435 + 4.436 +You can use any text you like as the value of the \texttt{username} 4.437 +config item, since this information is for reading by other people, 4.438 +but for interpreting by Mercurial. The convention that most people 4.439 +follow is to use their name and email address, as in the example 4.440 +above. 4.441 + 4.442 +\begin{note} 4.443 + Mercurial's built-in web server obfuscates email addresses, to make 4.444 + it more difficult for the email harvesting tools that spammers use. 4.445 + This reduces the likelihood that you'll start receiving more junk 4.446 + email if you publish a Mercurial repository on the web. 4.447 +\end{note} 4.448 + 4.449 +\subsection{Writing a commit message} 4.450 + 4.451 +When we commit a change, Mercurial drops us into a text editor, to 4.452 +enter a message that will describe the modifications we've made in 4.453 +this changeset. This is called the \emph{commit message}. It will be 4.454 +a record for readers of what we did and why, and it will be printed by 4.455 +\hgcmd{log} after we've finished committing. 4.456 +\interaction{tour.commit} 4.457 + 4.458 +The editor that the \hgcmd{commit} command drops us into will contain 4.459 +an empty line, followed by a number of lines starting with 4.460 +``\texttt{HG:}''. 4.461 +\begin{codesample2} 4.462 + \emph{empty line} 4.463 + HG: changed hello.c 4.464 +\end{codesample2} 4.465 +Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses 4.466 +them only to tell us which files it's recording changes to. Modifying 4.467 +or deleting these lines has no effect. 4.468 + 4.469 +\subsection{Writing a good commit message} 4.470 + 4.471 +Since \hgcmd{log} only prints the first line of a commit message by 4.472 +default, it's best to write a commit message whose first line stands 4.473 +alone. Here's a real example of a commit message that \emph{doesn't} 4.474 +follow this guideline, and hence has a summary that is not readable. 4.475 +\begin{codesample2} 4.476 + changeset: 73:584af0e231be 4.477 + user: Censored Person <censored.person@example.org> 4.478 + date: Tue Sep 26 21:37:07 2006 -0700 4.479 + summary: include buildmeister/commondefs. Add an exports and install 4.480 +\end{codesample2} 4.481 + 4.482 +As far as the remainder of the contents of the commit message are 4.483 +concerned, there are no hard-and-fast rules. Mercurial itself doesn't 4.484 +interpret or care about the contents of the commit message, though 4.485 +your project may have policies that dictate a certain kind of 4.486 +formatting. 4.487 + 4.488 +My personal preference is for short, but informative, commit messages 4.489 +that tell me something that I can't figure out with a quick glance at 4.490 +the output of \hgcmdargs{log}{--patch}. 4.491 + 4.492 +\subsection{Aborting a commit} 4.493 + 4.494 +If you decide that you don't want to commit while in the middle of 4.495 +editing a commit message, simply exit from your editor without saving 4.496 +the file that it's editing. This will cause nothing to happen to 4.497 +either the repository or the working directory. 4.498 + 4.499 +If we run the \hgcmd{commit} command without any arguments, it records 4.500 +all of the changes we've made, as reported by \hgcmd{status} and 4.501 +\hgcmd{diff}. 4.502 + 4.503 +\subsection{Admiring our new handiwork} 4.504 + 4.505 +Once we've finished the commit, we can use the \hgcmd{tip} command to 4.506 +display the changeset we just created. This command produces output 4.507 +that is identical to \hgcmd{log}, but it only displays the newest 4.508 +revision in the repository. 4.509 +\interaction{tour.tip} 4.510 +We refer to the newest revision in the repository as the tip revision, 4.511 +or simply the tip. 4.512 + 4.513 +\section{Sharing changes} 4.514 + 4.515 +We mentioned earlier that repositories in Mercurial are 4.516 +self-contained. This means that the changeset we just created exists 4.517 +only in our \dirname{my-hello} repository. Let's look at a few ways 4.518 +that we can propagate this change into other repositories. 4.519 + 4.520 +\subsection{Pulling changes from another repository} 4.521 +\label{sec:tour:pull} 4.522 + 4.523 +To get started, let's clone our original \dirname{hello} repository, 4.524 +which does not contain the change we just committed. We'll call our 4.525 +temporary repository \dirname{hello-pull}. 4.526 +\interaction{tour.clone-pull} 4.527 + 4.528 +We'll use the \hgcmd{pull} command to bring changes from 4.529 +\dirname{my-hello} into \dirname{hello-pull}. However, blindly 4.530 +pulling unknown changes into a repository is a somewhat scary 4.531 +prospect. Mercurial provides the \hgcmd{incoming} command to tell us 4.532 +what changes the \hgcmd{pull} command \emph{would} pull into the 4.533 +repository, without actually pulling the changes in. 4.534 +\interaction{tour.incoming} 4.535 +(Of course, someone could cause more changesets to appear in the 4.536 +repository that we ran \hgcmd{incoming} in, before we get a chance to 4.537 +\hgcmd{pull} the changes, so that we could end up pulling changes that we 4.538 +didn't expect.) 4.539 + 4.540 +Bringing changes into a repository is a simple matter of running the 4.541 +\hgcmd{pull} command, and telling it which repository to pull from. 4.542 +\interaction{tour.pull} 4.543 +As you can see from the before-and-after output of \hgcmd{tip}, we 4.544 +have successfully pulled changes into our repository. There remains 4.545 +one step before we can see these changes in the working directory. 4.546 + 4.547 +\subsection{Updating the working directory} 4.548 + 4.549 +We have so far glossed over the relationship between a repository and 4.550 +its working directory. The \hgcmd{pull} command that we ran in 4.551 +section~\ref{sec:tour:pull} brought changes into the repository, but 4.552 +if we check, there's no sign of those changes in the working 4.553 +directory. This is because \hgcmd{pull} does not (by default) touch 4.554 +the working directory. Instead, we use the \hgcmd{update} command to 4.555 +do this. 4.556 +\interaction{tour.update} 4.557 + 4.558 +It might seem a bit strange that \hgcmd{pull} doesn't update the 4.559 +working directory automatically. There's actually a good reason for 4.560 +this: you can use \hgcmd{update} to update the working directory to 4.561 +the state it was in at \emph{any revision} in the history of the 4.562 +repository. If you had the working directory updated to an old 4.563 +revision---to hunt down the origin of a bug, say---and ran a 4.564 +\hgcmd{pull} which automatically updated the working directory to a 4.565 +new revision, you might not be terribly happy. 4.566 + 4.567 +However, since pull-then-update is such a common thing to do, 4.568 +Mercurial lets you combine the two by passing the \hgopt{pull}{-u} 4.569 +option to \hgcmd{pull}. 4.570 +\begin{codesample2} 4.571 + hg pull -u 4.572 +\end{codesample2} 4.573 +If you look back at the output of \hgcmd{pull} in 4.574 +section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u}, 4.575 +you can see that it printed a helpful reminder that we'd have to take 4.576 +an explicit step to update the working directory: 4.577 +\begin{codesample2} 4.578 + (run 'hg update' to get a working copy) 4.579 +\end{codesample2} 4.580 + 4.581 +To find out what revision the working directory is at, use the 4.582 +\hgcmd{parents} command. 4.583 +\interaction{tour.parents} 4.584 +If you look back at figure~\ref{fig:tour-basic:history}, you'll see 4.585 +arrows connecting each changeset. The node that the arrow leads 4.586 +\emph{from} in each case is a parent, and the node that the arrow 4.587 +leads \emph{to} is its child. The working directory has a parent in 4.588 +just the same way; this is the changeset that the working directory 4.589 +currently contains. 4.590 + 4.591 +To update the working directory to a particular revision, give a 4.592 +revision number or changeset~ID to the \hgcmd{update} command. 4.593 +\interaction{tour.older} 4.594 +If you omit an explicit revision, \hgcmd{update} will update to the 4.595 +tip revision, as shown by the second call to \hgcmd{update} in the 4.596 +example above. 4.597 + 4.598 +\subsection{Pushing changes to another repository} 4.599 + 4.600 +Mercurial lets us push changes to another repository, from the 4.601 +repository we're currently visiting. As with the example of 4.602 +\hgcmd{pull} above, we'll create a temporary repository to push our 4.603 +changes into. 4.604 +\interaction{tour.clone-push} 4.605 +The \hgcmd{outgoing} command tells us what changes would be pushed 4.606 +into another repository. 4.607 +\interaction{tour.outgoing} 4.608 +And the \hgcmd{push} command does the actual push. 4.609 +\interaction{tour.push} 4.610 +As with \hgcmd{pull}, the \hgcmd{push} command does not update the 4.611 +working directory in the repository that it's pushing changes into. 4.612 +(Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u} 4.613 +option that updates the other repository's working directory.) 4.614 + 4.615 +What happens if we try to pull or push changes and the receiving 4.616 +repository already has those changes? Nothing too exciting. 4.617 +\interaction{tour.push.nothing} 4.618 + 4.619 +\subsection{Sharing changes over a network} 4.620 + 4.621 +The commands we have covered in the previous few sections are not 4.622 +limited to working with local repositories. Each works in exactly the 4.623 +same fashion over a network connection; simply pass in a URL instead 4.624 +of a local path. 4.625 +\interaction{tour.outgoing.net} 4.626 +In this example, we can see what changes we could push to the remote 4.627 +repository, but the repository is understandably not set up to let 4.628 +anonymous users push to it. 4.629 +\interaction{tour.push.net} 4.630 + 4.631 +%%% Local Variables: 4.632 +%%% mode: latex 4.633 +%%% TeX-master: "00book" 4.634 +%%% End:
5.1 --- a/es/undo.tex Sun Oct 19 17:08:11 2008 -0500 5.2 +++ b/es/undo.tex Sun Oct 19 19:56:21 2008 -0500 5.3 @@ -0,0 +1,767 @@ 5.4 +\chapter{Finding and fixing your mistakes} 5.5 +\label{chap:undo} 5.6 + 5.7 +To err might be human, but to really handle the consequences well 5.8 +takes a top-notch revision control system. In this chapter, we'll 5.9 +discuss some of the techniques you can use when you find that a 5.10 +problem has crept into your project. Mercurial has some highly 5.11 +capable features that will help you to isolate the sources of 5.12 +problems, and to handle them appropriately. 5.13 + 5.14 +\section{Erasing local history} 5.15 + 5.16 +\subsection{The accidental commit} 5.17 + 5.18 +I have the occasional but persistent problem of typing rather more 5.19 +quickly than I can think, which sometimes results in me committing a 5.20 +changeset that is either incomplete or plain wrong. In my case, the 5.21 +usual kind of incomplete changeset is one in which I've created a new 5.22 +source file, but forgotten to \hgcmd{add} it. A ``plain wrong'' 5.23 +changeset is not as common, but no less annoying. 5.24 + 5.25 +\subsection{Rolling back a transaction} 5.26 +\label{sec:undo:rollback} 5.27 + 5.28 +In section~\ref{sec:concepts:txn}, I mentioned that Mercurial treats 5.29 +each modification of a repository as a \emph{transaction}. Every time 5.30 +you commit a changeset or pull changes from another repository, 5.31 +Mercurial remembers what you did. You can undo, or \emph{roll back}, 5.32 +exactly one of these actions using the \hgcmd{rollback} command. (See 5.33 +section~\ref{sec:undo:rollback-after-push} for an important caveat 5.34 +about the use of this command.) 5.35 + 5.36 +Here's a mistake that I often find myself making: committing a change 5.37 +in which I've created a new file, but forgotten to \hgcmd{add} it. 5.38 +\interaction{rollback.commit} 5.39 +Looking at the output of \hgcmd{status} after the commit immediately 5.40 +confirms the error. 5.41 +\interaction{rollback.status} 5.42 +The commit captured the changes to the file \filename{a}, but not the 5.43 +new file \filename{b}. If I were to push this changeset to a 5.44 +repository that I shared with a colleague, the chances are high that 5.45 +something in \filename{a} would refer to \filename{b}, which would not 5.46 +be present in their repository when they pulled my changes. I would 5.47 +thus become the object of some indignation. 5.48 + 5.49 +However, luck is with me---I've caught my error before I pushed the 5.50 +changeset. I use the \hgcmd{rollback} command, and Mercurial makes 5.51 +that last changeset vanish. 5.52 +\interaction{rollback.rollback} 5.53 +Notice that the changeset is no longer present in the repository's 5.54 +history, and the working directory once again thinks that the file 5.55 +\filename{a} is modified. The commit and rollback have left the 5.56 +working directory exactly as it was prior to the commit; the changeset 5.57 +has been completely erased. I can now safely \hgcmd{add} the file 5.58 +\filename{b}, and rerun my commit. 5.59 +\interaction{rollback.add} 5.60 + 5.61 +\subsection{The erroneous pull} 5.62 + 5.63 +It's common practice with Mercurial to maintain separate development 5.64 +branches of a project in different repositories. Your development 5.65 +team might have one shared repository for your project's ``0.9'' 5.66 +release, and another, containing different changes, for the ``1.0'' 5.67 +release. 5.68 + 5.69 +Given this, you can imagine that the consequences could be messy if 5.70 +you had a local ``0.9'' repository, and accidentally pulled changes 5.71 +from the shared ``1.0'' repository into it. At worst, you could be 5.72 +paying insufficient attention, and push those changes into the shared 5.73 +``0.9'' tree, confusing your entire team (but don't worry, we'll 5.74 +return to this horror scenario later). However, it's more likely that 5.75 +you'll notice immediately, because Mercurial will display the URL it's 5.76 +pulling from, or you will see it pull a suspiciously large number of 5.77 +changes into the repository. 5.78 + 5.79 +The \hgcmd{rollback} command will work nicely to expunge all of the 5.80 +changesets that you just pulled. Mercurial groups all changes from 5.81 +one \hgcmd{pull} into a single transaction, so one \hgcmd{rollback} is 5.82 +all you need to undo this mistake. 5.83 + 5.84 +\subsection{Rolling back is useless once you've pushed} 5.85 +\label{sec:undo:rollback-after-push} 5.86 + 5.87 +The value of the \hgcmd{rollback} command drops to zero once you've 5.88 +pushed your changes to another repository. Rolling back a change 5.89 +makes it disappear entirely, but \emph{only} in the repository in 5.90 +which you perform the \hgcmd{rollback}. Because a rollback eliminates 5.91 +history, there's no way for the disappearance of a change to propagate 5.92 +between repositories. 5.93 + 5.94 +If you've pushed a change to another repository---particularly if it's 5.95 +a shared repository---it has essentially ``escaped into the wild,'' 5.96 +and you'll have to recover from your mistake in a different way. What 5.97 +will happen if you push a changeset somewhere, then roll it back, then 5.98 +pull from the repository you pushed to, is that the changeset will 5.99 +reappear in your repository. 5.100 + 5.101 +(If you absolutely know for sure that the change you want to roll back 5.102 +is the most recent change in the repository that you pushed to, 5.103 +\emph{and} you know that nobody else could have pulled it from that 5.104 +repository, you can roll back the changeset there, too, but you really 5.105 +should really not rely on this working reliably. If you do this, 5.106 +sooner or later a change really will make it into a repository that 5.107 +you don't directly control (or have forgotten about), and come back to 5.108 +bite you.) 5.109 + 5.110 +\subsection{You can only roll back once} 5.111 + 5.112 +Mercurial stores exactly one transaction in its transaction log; that 5.113 +transaction is the most recent one that occurred in the repository. 5.114 +This means that you can only roll back one transaction. If you expect 5.115 +to be able to roll back one transaction, then its predecessor, this is 5.116 +not the behaviour you will get. 5.117 +\interaction{rollback.twice} 5.118 +Once you've rolled back one transaction in a repository, you can't 5.119 +roll back again in that repository until you perform another commit or 5.120 +pull. 5.121 + 5.122 +\section{Reverting the mistaken change} 5.123 + 5.124 +If you make a modification to a file, and decide that you really 5.125 +didn't want to change the file at all, and you haven't yet committed 5.126 +your changes, the \hgcmd{revert} command is the one you'll need. It 5.127 +looks at the changeset that's the parent of the working directory, and 5.128 +restores the contents of the file to their state as of that changeset. 5.129 +(That's a long-winded way of saying that, in the normal case, it 5.130 +undoes your modifications.) 5.131 + 5.132 +Let's illustrate how the \hgcmd{revert} command works with yet another 5.133 +small example. We'll begin by modifying a file that Mercurial is 5.134 +already tracking. 5.135 +\interaction{daily.revert.modify} 5.136 +If we don't want that change, we can simply \hgcmd{revert} the file. 5.137 +\interaction{daily.revert.unmodify} 5.138 +The \hgcmd{revert} command provides us with an extra degree of safety 5.139 +by saving our modified file with a \filename{.orig} extension. 5.140 +\interaction{daily.revert.status} 5.141 + 5.142 +Here is a summary of the cases that the \hgcmd{revert} command can 5.143 +deal with. We will describe each of these in more detail in the 5.144 +section that follows. 5.145 +\begin{itemize} 5.146 +\item If you modify a file, it will restore the file to its unmodified 5.147 + state. 5.148 +\item If you \hgcmd{add} a file, it will undo the ``added'' state of 5.149 + the file, but leave the file itself untouched. 5.150 +\item If you delete a file without telling Mercurial, it will restore 5.151 + the file to its unmodified contents. 5.152 +\item If you use the \hgcmd{remove} command to remove a file, it will 5.153 + undo the ``removed'' state of the file, and restore the file to its 5.154 + unmodified contents. 5.155 +\end{itemize} 5.156 + 5.157 +\subsection{File management errors} 5.158 +\label{sec:undo:mgmt} 5.159 + 5.160 +The \hgcmd{revert} command is useful for more than just modified 5.161 +files. It lets you reverse the results of all of Mercurial's file 5.162 +management commands---\hgcmd{add}, \hgcmd{remove}, and so on. 5.163 + 5.164 +If you \hgcmd{add} a file, then decide that in fact you don't want 5.165 +Mercurial to track it, use \hgcmd{revert} to undo the add. Don't 5.166 +worry; Mercurial will not modify the file in any way. It will just 5.167 +``unmark'' the file. 5.168 +\interaction{daily.revert.add} 5.169 + 5.170 +Similarly, if you ask Mercurial to \hgcmd{remove} a file, you can use 5.171 +\hgcmd{revert} to restore it to the contents it had as of the parent 5.172 +of the working directory. 5.173 +\interaction{daily.revert.remove} 5.174 +This works just as well for a file that you deleted by hand, without 5.175 +telling Mercurial (recall that in Mercurial terminology, this kind of 5.176 +file is called ``missing''). 5.177 +\interaction{daily.revert.missing} 5.178 + 5.179 +If you revert a \hgcmd{copy}, the copied-to file remains in your 5.180 +working directory afterwards, untracked. Since a copy doesn't affect 5.181 +the copied-from file in any way, Mercurial doesn't do anything with 5.182 +the copied-from file. 5.183 +\interaction{daily.revert.copy} 5.184 + 5.185 +\subsubsection{A slightly special case: reverting a rename} 5.186 + 5.187 +If you \hgcmd{rename} a file, there is one small detail that 5.188 +you should remember. When you \hgcmd{revert} a rename, it's not 5.189 +enough to provide the name of the renamed-to file, as you can see 5.190 +here. 5.191 +\interaction{daily.revert.rename} 5.192 +As you can see from the output of \hgcmd{status}, the renamed-to file 5.193 +is no longer identified as added, but the renamed-\emph{from} file is 5.194 +still removed! This is counter-intuitive (at least to me), but at 5.195 +least it's easy to deal with. 5.196 +\interaction{daily.revert.rename-orig} 5.197 +So remember, to revert a \hgcmd{rename}, you must provide \emph{both} 5.198 +the source and destination names. 5.199 + 5.200 +% TODO: the output doesn't look like it will be removed! 5.201 + 5.202 +(By the way, if you rename a file, then modify the renamed-to file, 5.203 +then revert both components of the rename, when Mercurial restores the 5.204 +file that was removed as part of the rename, it will be unmodified. 5.205 +If you need the modifications in the renamed-to file to show up in the 5.206 +renamed-from file, don't forget to copy them over.) 5.207 + 5.208 +These fiddly aspects of reverting a rename arguably constitute a small 5.209 +bug in Mercurial. 5.210 + 5.211 +\section{Dealing with committed changes} 5.212 + 5.213 +Consider a case where you have committed a change $a$, and another 5.214 +change $b$ on top of it; you then realise that change $a$ was 5.215 +incorrect. Mercurial lets you ``back out'' an entire changeset 5.216 +automatically, and building blocks that let you reverse part of a 5.217 +changeset by hand. 5.218 + 5.219 +Before you read this section, here's something to keep in mind: the 5.220 +\hgcmd{backout} command undoes changes by \emph{adding} history, not 5.221 +by modifying or erasing it. It's the right tool to use if you're 5.222 +fixing bugs, but not if you're trying to undo some change that has 5.223 +catastrophic consequences. To deal with those, see 5.224 +section~\ref{sec:undo:aaaiiieee}. 5.225 + 5.226 +\subsection{Backing out a changeset} 5.227 + 5.228 +The \hgcmd{backout} command lets you ``undo'' the effects of an entire 5.229 +changeset in an automated fashion. Because Mercurial's history is 5.230 +immutable, this command \emph{does not} get rid of the changeset you 5.231 +want to undo. Instead, it creates a new changeset that 5.232 +\emph{reverses} the effect of the to-be-undone changeset. 5.233 + 5.234 +The operation of the \hgcmd{backout} command is a little intricate, so 5.235 +let's illustrate it with some examples. First, we'll create a 5.236 +repository with some simple changes. 5.237 +\interaction{backout.init} 5.238 + 5.239 +The \hgcmd{backout} command takes a single changeset ID as its 5.240 +argument; this is the changeset to back out. Normally, 5.241 +\hgcmd{backout} will drop you into a text editor to write a commit 5.242 +message, so you can record why you're backing the change out. In this 5.243 +example, we provide a commit message on the command line using the 5.244 +\hgopt{backout}{-m} option. 5.245 + 5.246 +\subsection{Backing out the tip changeset} 5.247 + 5.248 +We're going to start by backing out the last changeset we committed. 5.249 +\interaction{backout.simple} 5.250 +You can see that the second line from \filename{myfile} is no longer 5.251 +present. Taking a look at the output of \hgcmd{log} gives us an idea 5.252 +of what the \hgcmd{backout} command has done. 5.253 +\interaction{backout.simple.log} 5.254 +Notice that the new changeset that \hgcmd{backout} has created is a 5.255 +child of the changeset we backed out. It's easier to see this in 5.256 +figure~\ref{fig:undo:backout}, which presents a graphical view of the 5.257 +change history. As you can see, the history is nice and linear. 5.258 + 5.259 +\begin{figure}[htb] 5.260 + \centering 5.261 + \grafix{undo-simple} 5.262 + \caption{Backing out a change using the \hgcmd{backout} command} 5.263 + \label{fig:undo:backout} 5.264 +\end{figure} 5.265 + 5.266 +\subsection{Backing out a non-tip change} 5.267 + 5.268 +If you want to back out a change other than the last one you 5.269 +committed, pass the \hgopt{backout}{--merge} option to the 5.270 +\hgcmd{backout} command. 5.271 +\interaction{backout.non-tip.clone} 5.272 +This makes backing out any changeset a ``one-shot'' operation that's 5.273 +usually simple and fast. 5.274 +\interaction{backout.non-tip.backout} 5.275 + 5.276 +If you take a look at the contents of \filename{myfile} after the 5.277 +backout finishes, you'll see that the first and third changes are 5.278 +present, but not the second. 5.279 +\interaction{backout.non-tip.cat} 5.280 + 5.281 +As the graphical history in figure~\ref{fig:undo:backout-non-tip} 5.282 +illustrates, Mercurial actually commits \emph{two} changes in this 5.283 +kind of situation (the box-shaped nodes are the ones that Mercurial 5.284 +commits automatically). Before Mercurial begins the backout process, 5.285 +it first remembers what the current parent of the working directory 5.286 +is. It then backs out the target changeset, and commits that as a 5.287 +changeset. Finally, it merges back to the previous parent of the 5.288 +working directory, and commits the result of the merge. 5.289 + 5.290 +% TODO: to me it looks like mercurial doesn't commit the second merge automatically! 5.291 + 5.292 +\begin{figure}[htb] 5.293 + \centering 5.294 + \grafix{undo-non-tip} 5.295 + \caption{Automated backout of a non-tip change using the \hgcmd{backout} command} 5.296 + \label{fig:undo:backout-non-tip} 5.297 +\end{figure} 5.298 + 5.299 +The result is that you end up ``back where you were'', only with some 5.300 +extra history that undoes the effect of the changeset you wanted to 5.301 +back out. 5.302 + 5.303 +\subsubsection{Always use the \hgopt{backout}{--merge} option} 5.304 + 5.305 +In fact, since the \hgopt{backout}{--merge} option will do the ``right 5.306 +thing'' whether or not the changeset you're backing out is the tip 5.307 +(i.e.~it won't try to merge if it's backing out the tip, since there's 5.308 +no need), you should \emph{always} use this option when you run the 5.309 +\hgcmd{backout} command. 5.310 + 5.311 +\subsection{Gaining more control of the backout process} 5.312 + 5.313 +While I've recommended that you always use the 5.314 +\hgopt{backout}{--merge} option when backing out a change, the 5.315 +\hgcmd{backout} command lets you decide how to merge a backout 5.316 +changeset. Taking control of the backout process by hand is something 5.317 +you will rarely need to do, but it can be useful to understand what 5.318 +the \hgcmd{backout} command is doing for you automatically. To 5.319 +illustrate this, let's clone our first repository, but omit the 5.320 +backout change that it contains. 5.321 + 5.322 +\interaction{backout.manual.clone} 5.323 +As with our earlier example, We'll commit a third changeset, then back 5.324 +out its parent, and see what happens. 5.325 +\interaction{backout.manual.backout} 5.326 +Our new changeset is again a descendant of the changeset we backout 5.327 +out; it's thus a new head, \emph{not} a descendant of the changeset 5.328 +that was the tip. The \hgcmd{backout} command was quite explicit in 5.329 +telling us this. 5.330 +\interaction{backout.manual.log} 5.331 + 5.332 +Again, it's easier to see what has happened by looking at a graph of 5.333 +the revision history, in figure~\ref{fig:undo:backout-manual}. This 5.334 +makes it clear that when we use \hgcmd{backout} to back out a change 5.335 +other than the tip, Mercurial adds a new head to the repository (the 5.336 +change it committed is box-shaped). 5.337 + 5.338 +\begin{figure}[htb] 5.339 + \centering 5.340 + \grafix{undo-manual} 5.341 + \caption{Backing out a change using the \hgcmd{backout} command} 5.342 + \label{fig:undo:backout-manual} 5.343 +\end{figure} 5.344 + 5.345 +After the \hgcmd{backout} command has completed, it leaves the new 5.346 +``backout'' changeset as the parent of the working directory. 5.347 +\interaction{backout.manual.parents} 5.348 +Now we have two isolated sets of changes. 5.349 +\interaction{backout.manual.heads} 5.350 + 5.351 +Let's think about what we expect to see as the contents of 5.352 +\filename{myfile} now. The first change should be present, because 5.353 +we've never backed it out. The second change should be missing, as 5.354 +that's the change we backed out. Since the history graph shows the 5.355 +third change as a separate head, we \emph{don't} expect to see the 5.356 +third change present in \filename{myfile}. 5.357 +\interaction{backout.manual.cat} 5.358 +To get the third change back into the file, we just do a normal merge 5.359 +of our two heads. 5.360 +\interaction{backout.manual.merge} 5.361 +Afterwards, the graphical history of our repository looks like 5.362 +figure~\ref{fig:undo:backout-manual-merge}. 5.363 + 5.364 +\begin{figure}[htb] 5.365 + \centering 5.366 + \grafix{undo-manual-merge} 5.367 + \caption{Manually merging a backout change} 5.368 + \label{fig:undo:backout-manual-merge} 5.369 +\end{figure} 5.370 + 5.371 +\subsection{Why \hgcmd{backout} works as it does} 5.372 + 5.373 +Here's a brief description of how the \hgcmd{backout} command works. 5.374 +\begin{enumerate} 5.375 +\item It ensures that the working directory is ``clean'', i.e.~that 5.376 + the output of \hgcmd{status} would be empty. 5.377 +\item It remembers the current parent of the working directory. Let's 5.378 + call this changeset \texttt{orig} 5.379 +\item It does the equivalent of a \hgcmd{update} to sync the working 5.380 + directory to the changeset you want to back out. Let's call this 5.381 + changeset \texttt{backout} 5.382 +\item It finds the parent of that changeset. Let's call that 5.383 + changeset \texttt{parent}. 5.384 +\item For each file that the \texttt{backout} changeset affected, it 5.385 + does the equivalent of a \hgcmdargs{revert}{-r parent} on that file, 5.386 + to restore it to the contents it had before that changeset was 5.387 + committed. 5.388 +\item It commits the result as a new changeset. This changeset has 5.389 + \texttt{backout} as its parent. 5.390 +\item If you specify \hgopt{backout}{--merge} on the command line, it 5.391 + merges with \texttt{orig}, and commits the result of the merge. 5.392 +\end{enumerate} 5.393 + 5.394 +An alternative way to implement the \hgcmd{backout} command would be 5.395 +to \hgcmd{export} the to-be-backed-out changeset as a diff, then use 5.396 +the \cmdopt{patch}{--reverse} option to the \command{patch} command to 5.397 +reverse the effect of the change without fiddling with the working 5.398 +directory. This sounds much simpler, but it would not work nearly as 5.399 +well. 5.400 + 5.401 +The reason that \hgcmd{backout} does an update, a commit, a merge, and 5.402 +another commit is to give the merge machinery the best chance to do a 5.403 +good job when dealing with all the changes \emph{between} the change 5.404 +you're backing out and the current tip. 5.405 + 5.406 +If you're backing out a changeset that's~100 revisions back in your 5.407 +project's history, the chances that the \command{patch} command will 5.408 +be able to apply a reverse diff cleanly are not good, because 5.409 +intervening changes are likely to have ``broken the context'' that 5.410 +\command{patch} uses to determine whether it can apply a patch (if 5.411 +this sounds like gibberish, see \ref{sec:mq:patch} for a 5.412 +discussion of the \command{patch} command). Also, Mercurial's merge 5.413 +machinery will handle files and directories being renamed, permission 5.414 +changes, and modifications to binary files, none of which 5.415 +\command{patch} can deal with. 5.416 + 5.417 +\section{Changes that should never have been} 5.418 +\label{sec:undo:aaaiiieee} 5.419 + 5.420 +Most of the time, the \hgcmd{backout} command is exactly what you need 5.421 +if you want to undo the effects of a change. It leaves a permanent 5.422 +record of exactly what you did, both when committing the original 5.423 +changeset and when you cleaned up after it. 5.424 + 5.425 +On rare occasions, though, you may find that you've committed a change 5.426 +that really should not be present in the repository at all. For 5.427 +example, it would be very unusual, and usually considered a mistake, 5.428 +to commit a software project's object files as well as its source 5.429 +files. Object files have almost no intrinsic value, and they're 5.430 +\emph{big}, so they increase the size of the repository and the amount 5.431 +of time it takes to clone or pull changes. 5.432 + 5.433 +Before I discuss the options that you have if you commit a ``brown 5.434 +paper bag'' change (the kind that's so bad that you want to pull a 5.435 +brown paper bag over your head), let me first discuss some approaches 5.436 +that probably won't work. 5.437 + 5.438 +Since Mercurial treats history as accumulative---every change builds 5.439 +on top of all changes that preceded it---you generally can't just make 5.440 +disastrous changes disappear. The one exception is when you've just 5.441 +committed a change, and it hasn't been pushed or pulled into another 5.442 +repository. That's when you can safely use the \hgcmd{rollback} 5.443 +command, as I detailed in section~\ref{sec:undo:rollback}. 5.444 + 5.445 +After you've pushed a bad change to another repository, you 5.446 +\emph{could} still use \hgcmd{rollback} to make your local copy of the 5.447 +change disappear, but it won't have the consequences you want. The 5.448 +change will still be present in the remote repository, so it will 5.449 +reappear in your local repository the next time you pull. 5.450 + 5.451 +If a situation like this arises, and you know which repositories your 5.452 +bad change has propagated into, you can \emph{try} to get rid of the 5.453 +changeefrom \emph{every} one of those repositories. This is, of 5.454 +course, not a satisfactory solution: if you miss even a single 5.455 +repository while you're expunging, the change is still ``in the 5.456 +wild'', and could propagate further. 5.457 + 5.458 +If you've committed one or more changes \emph{after} the change that 5.459 +you'd like to see disappear, your options are further reduced. 5.460 +Mercurial doesn't provide a way to ``punch a hole'' in history, 5.461 +leaving changesets intact. 5.462 + 5.463 +XXX This needs filling out. The \texttt{hg-replay} script in the 5.464 +\texttt{examples} directory works, but doesn't handle merge 5.465 +changesets. Kind of an important omission. 5.466 + 5.467 +\subsection{Protect yourself from ``escaped'' changes} 5.468 + 5.469 +If you've committed some changes to your local repository and they've 5.470 +been pushed or pulled somewhere else, this isn't necessarily a 5.471 +disaster. You can protect yourself ahead of time against some classes 5.472 +of bad changeset. This is particularly easy if your team usually 5.473 +pulls changes from a central repository. 5.474 + 5.475 +By configuring some hooks on that repository to validate incoming 5.476 +changesets (see chapter~\ref{chap:hook}), you can automatically 5.477 +prevent some kinds of bad changeset from being pushed to the central 5.478 +repository at all. With such a configuration in place, some kinds of 5.479 +bad changeset will naturally tend to ``die out'' because they can't 5.480 +propagate into the central repository. Better yet, this happens 5.481 +without any need for explicit intervention. 5.482 + 5.483 +For instance, an incoming change hook that verifies that a changeset 5.484 +will actually compile can prevent people from inadvertantly ``breaking 5.485 +the build''. 5.486 + 5.487 +\section{Finding the source of a bug} 5.488 +\label{sec:undo:bisect} 5.489 + 5.490 +While it's all very well to be able to back out a changeset that 5.491 +introduced a bug, this requires that you know which changeset to back 5.492 +out. Mercurial provides an invaluable command, called 5.493 +\hgcmd{bisect}, that helps you to automate this process and accomplish 5.494 +it very efficiently. 5.495 + 5.496 +The idea behind the \hgcmd{bisect} command is that a changeset has 5.497 +introduced some change of behaviour that you can identify with a 5.498 +simple binary test. You don't know which piece of code introduced the 5.499 +change, but you know how to test for the presence of the bug. The 5.500 +\hgcmd{bisect} command uses your test to direct its search for the 5.501 +changeset that introduced the code that caused the bug. 5.502 + 5.503 +Here are a few scenarios to help you understand how you might apply 5.504 +this command. 5.505 +\begin{itemize} 5.506 +\item The most recent version of your software has a bug that you 5.507 + remember wasn't present a few weeks ago, but you don't know when it 5.508 + was introduced. Here, your binary test checks for the presence of 5.509 + that bug. 5.510 +\item You fixed a bug in a rush, and now it's time to close the entry 5.511 + in your team's bug database. The bug database requires a changeset 5.512 + ID when you close an entry, but you don't remember which changeset 5.513 + you fixed the bug in. Once again, your binary test checks for the 5.514 + presence of the bug. 5.515 +\item Your software works correctly, but runs~15\% slower than the 5.516 + last time you measured it. You want to know which changeset 5.517 + introduced the performance regression. In this case, your binary 5.518 + test measures the performance of your software, to see whether it's 5.519 + ``fast'' or ``slow''. 5.520 +\item The sizes of the components of your project that you ship 5.521 + exploded recently, and you suspect that something changed in the way 5.522 + you build your project. 5.523 +\end{itemize} 5.524 + 5.525 +From these examples, it should be clear that the \hgcmd{bisect} 5.526 +command is not useful only for finding the sources of bugs. You can 5.527 +use it to find any ``emergent property'' of a repository (anything 5.528 +that you can't find from a simple text search of the files in the 5.529 +tree) for which you can write a binary test. 5.530 + 5.531 +We'll introduce a little bit of terminology here, just to make it 5.532 +clear which parts of the search process are your responsibility, and 5.533 +which are Mercurial's. A \emph{test} is something that \emph{you} run 5.534 +when \hgcmd{bisect} chooses a changeset. A \emph{probe} is what 5.535 +\hgcmd{bisect} runs to tell whether a revision is good. Finally, 5.536 +we'll use the word ``bisect'', as both a noun and a verb, to stand in 5.537 +for the phrase ``search using the \hgcmd{bisect} command. 5.538 + 5.539 +One simple way to automate the searching process would be simply to 5.540 +probe every changeset. However, this scales poorly. If it took ten 5.541 +minutes to test a single changeset, and you had 10,000 changesets in 5.542 +your repository, the exhaustive approach would take on average~35 5.543 +\emph{days} to find the changeset that introduced a bug. Even if you 5.544 +knew that the bug was introduced by one of the last 500 changesets, 5.545 +and limited your search to those, you'd still be looking at over 40 5.546 +hours to find the changeset that introduced your bug. 5.547 + 5.548 +What the \hgcmd{bisect} command does is use its knowledge of the 5.549 +``shape'' of your project's revision history to perform a search in 5.550 +time proportional to the \emph{logarithm} of the number of changesets 5.551 +to check (the kind of search it performs is called a dichotomic 5.552 +search). With this approach, searching through 10,000 changesets will 5.553 +take less than three hours, even at ten minutes per test (the search 5.554 +will require about 14 tests). Limit your search to the last hundred 5.555 +changesets, and it will take only about an hour (roughly seven tests). 5.556 + 5.557 +The \hgcmd{bisect} command is aware of the ``branchy'' nature of a 5.558 +Mercurial project's revision history, so it has no problems dealing 5.559 +with branches, merges, or multiple heads in a repoository. It can 5.560 +prune entire branches of history with a single probe, which is how it 5.561 +operates so efficiently. 5.562 + 5.563 +\subsection{Using the \hgcmd{bisect} command} 5.564 + 5.565 +Here's an example of \hgcmd{bisect} in action. 5.566 + 5.567 +\begin{note} 5.568 + In versions 0.9.5 and earlier of Mercurial, \hgcmd{bisect} was not a 5.569 + core command: it was distributed with Mercurial as an extension. 5.570 + This section describes the built-in command, not the old extension. 5.571 +\end{note} 5.572 + 5.573 +Now let's create a repository, so that we can try out the 5.574 +\hgcmd{bisect} command in isolation. 5.575 +\interaction{bisect.init} 5.576 +We'll simulate a project that has a bug in it in a simple-minded way: 5.577 +create trivial changes in a loop, and nominate one specific change 5.578 +that will have the ``bug''. This loop creates 35 changesets, each 5.579 +adding a single file to the repository. We'll represent our ``bug'' 5.580 +with a file that contains the text ``i have a gub''. 5.581 +\interaction{bisect.commits} 5.582 + 5.583 +The next thing that we'd like to do is figure out how to use the 5.584 +\hgcmd{bisect} command. We can use Mercurial's normal built-in help 5.585 +mechanism for this. 5.586 +\interaction{bisect.help} 5.587 + 5.588 +The \hgcmd{bisect} command works in steps. Each step proceeds as follows. 5.589 +\begin{enumerate} 5.590 +\item You run your binary test. 5.591 + \begin{itemize} 5.592 + \item If the test succeeded, you tell \hgcmd{bisect} by running the 5.593 + \hgcmdargs{bisect}{good} command. 5.594 + \item If it failed, run the \hgcmdargs{bisect}{--bad} command. 5.595 + \end{itemize} 5.596 +\item The command uses your information to decide which changeset to 5.597 + test next. 5.598 +\item It updates the working directory to that changeset, and the 5.599 + process begins again. 5.600 +\end{enumerate} 5.601 +The process ends when \hgcmd{bisect} identifies a unique changeset 5.602 +that marks the point where your test transitioned from ``succeeding'' 5.603 +to ``failing''. 5.604 + 5.605 +To start the search, we must run the \hgcmdargs{bisect}{--reset} command. 5.606 +\interaction{bisect.search.init} 5.607 + 5.608 +In our case, the binary test we use is simple: we check to see if any 5.609 +file in the repository contains the string ``i have a gub''. If it 5.610 +does, this changeset contains the change that ``caused the bug''. By 5.611 +convention, a changeset that has the property we're searching for is 5.612 +``bad'', while one that doesn't is ``good''. 5.613 + 5.614 +Most of the time, the revision to which the working directory is 5.615 +synced (usually the tip) already exhibits the problem introduced by 5.616 +the buggy change, so we'll mark it as ``bad''. 5.617 +\interaction{bisect.search.bad-init} 5.618 + 5.619 +Our next task is to nominate a changeset that we know \emph{doesn't} 5.620 +have the bug; the \hgcmd{bisect} command will ``bracket'' its search 5.621 +between the first pair of good and bad changesets. In our case, we 5.622 +know that revision~10 didn't have the bug. (I'll have more words 5.623 +about choosing the first ``good'' changeset later.) 5.624 +\interaction{bisect.search.good-init} 5.625 + 5.626 +Notice that this command printed some output. 5.627 +\begin{itemize} 5.628 +\item It told us how many changesets it must consider before it can 5.629 + identify the one that introduced the bug, and how many tests that 5.630 + will require. 5.631 +\item It updated the working directory to the next changeset to test, 5.632 + and told us which changeset it's testing. 5.633 +\end{itemize} 5.634 + 5.635 +We now run our test in the working directory. We use the 5.636 +\command{grep} command to see if our ``bad'' file is present in the 5.637 +working directory. If it is, this revision is bad; if not, this 5.638 +revision is good. 5.639 +\interaction{bisect.search.step1} 5.640 + 5.641 +This test looks like a perfect candidate for automation, so let's turn 5.642 +it into a shell function. 5.643 +\interaction{bisect.search.mytest} 5.644 +We can now run an entire test step with a single command, 5.645 +\texttt{mytest}. 5.646 +\interaction{bisect.search.step2} 5.647 +A few more invocations of our canned test step command, and we're 5.648 +done. 5.649 +\interaction{bisect.search.rest} 5.650 + 5.651 +Even though we had~40 changesets to search through, the \hgcmd{bisect} 5.652 +command let us find the changeset that introduced our ``bug'' with 5.653 +only five tests. Because the number of tests that the \hgcmd{bisect} 5.654 +command performs grows logarithmically with the number of changesets to 5.655 +search, the advantage that it has over the ``brute force'' search 5.656 +approach increases with every changeset you add. 5.657 + 5.658 +\subsection{Cleaning up after your search} 5.659 + 5.660 +When you're finished using the \hgcmd{bisect} command in a 5.661 +repository, you can use the \hgcmdargs{bisect}{reset} command to drop 5.662 +the information it was using to drive your search. The command 5.663 +doesn't use much space, so it doesn't matter if you forget to run this 5.664 +command. However, \hgcmd{bisect} won't let you start a new search in 5.665 +that repository until you do a \hgcmdargs{bisect}{reset}. 5.666 +\interaction{bisect.search.reset} 5.667 + 5.668 +\section{Tips for finding bugs effectively} 5.669 + 5.670 +\subsection{Give consistent input} 5.671 + 5.672 +The \hgcmd{bisect} command requires that you correctly report the 5.673 +result of every test you perform. If you tell it that a test failed 5.674 +when it really succeeded, it \emph{might} be able to detect the 5.675 +inconsistency. If it can identify an inconsistency in your reports, 5.676 +it will tell you that a particular changeset is both good and bad. 5.677 +However, it can't do this perfectly; it's about as likely to report 5.678 +the wrong changeset as the source of the bug. 5.679 + 5.680 +\subsection{Automate as much as possible} 5.681 + 5.682 +When I started using the \hgcmd{bisect} command, I tried a few times 5.683 +to run my tests by hand, on the command line. This is an approach 5.684 +that I, at least, am not suited to. After a few tries, I found that I 5.685 +was making enough mistakes that I was having to restart my searches 5.686 +several times before finally getting correct results. 5.687 + 5.688 +My initial problems with driving the \hgcmd{bisect} command by hand 5.689 +occurred even with simple searches on small repositories; if the 5.690 +problem you're looking for is more subtle, or the number of tests that 5.691 +\hgcmd{bisect} must perform increases, the likelihood of operator 5.692 +error ruining the search is much higher. Once I started automating my 5.693 +tests, I had much better results. 5.694 + 5.695 +The key to automated testing is twofold: 5.696 +\begin{itemize} 5.697 +\item always test for the same symptom, and 5.698 +\item always feed consistent input to the \hgcmd{bisect} command. 5.699 +\end{itemize} 5.700 +In my tutorial example above, the \command{grep} command tests for the 5.701 +symptom, and the \texttt{if} statement takes the result of this check 5.702 +and ensures that we always feed the same input to the \hgcmd{bisect} 5.703 +command. The \texttt{mytest} function marries these together in a 5.704 +reproducible way, so that every test is uniform and consistent. 5.705 + 5.706 +\subsection{Check your results} 5.707 + 5.708 +Because the output of a \hgcmd{bisect} search is only as good as the 5.709 +input you give it, don't take the changeset it reports as the 5.710 +absolute truth. A simple way to cross-check its report is to manually 5.711 +run your test at each of the following changesets: 5.712 +\begin{itemize} 5.713 +\item The changeset that it reports as the first bad revision. Your 5.714 + test should still report this as bad. 5.715 +\item The parent of that changeset (either parent, if it's a merge). 5.716 + Your test should report this changeset as good. 5.717 +\item A child of that changeset. Your test should report this 5.718 + changeset as bad. 5.719 +\end{itemize} 5.720 + 5.721 +\subsection{Beware interference between bugs} 5.722 + 5.723 +It's possible that your search for one bug could be disrupted by the 5.724 +presence of another. For example, let's say your software crashes at 5.725 +revision 100, and worked correctly at revision 50. Unknown to you, 5.726 +someone else introduced a different crashing bug at revision 60, and 5.727 +fixed it at revision 80. This could distort your results in one of 5.728 +several ways. 5.729 + 5.730 +It is possible that this other bug completely ``masks'' yours, which 5.731 +is to say that it occurs before your bug has a chance to manifest 5.732 +itself. If you can't avoid that other bug (for example, it prevents 5.733 +your project from building), and so can't tell whether your bug is 5.734 +present in a particular changeset, the \hgcmd{bisect} command cannot 5.735 +help you directly. Instead, you can mark a changeset as untested by 5.736 +running \hgcmdargs{bisect}{--skip}. 5.737 + 5.738 +A different problem could arise if your test for a bug's presence is 5.739 +not specific enough. If you check for ``my program crashes'', then 5.740 +both your crashing bug and an unrelated crashing bug that masks it 5.741 +will look like the same thing, and mislead \hgcmd{bisect}. 5.742 + 5.743 +Another useful situation in which to use \hgcmdargs{bisect}{--skip} is 5.744 +if you can't test a revision because your project was in a broken and 5.745 +hence untestable state at that revision, perhaps because someone 5.746 +checked in a change that prevented the project from building. 5.747 + 5.748 +\subsection{Bracket your search lazily} 5.749 + 5.750 +Choosing the first ``good'' and ``bad'' changesets that will mark the 5.751 +end points of your search is often easy, but it bears a little 5.752 +discussion nevertheless. From the perspective of \hgcmd{bisect}, the 5.753 +``newest'' changeset is conventionally ``bad'', and the older 5.754 +changeset is ``good''. 5.755 + 5.756 +If you're having trouble remembering when a suitable ``good'' change 5.757 +was, so that you can tell \hgcmd{bisect}, you could do worse than 5.758 +testing changesets at random. Just remember to eliminate contenders 5.759 +that can't possibly exhibit the bug (perhaps because the feature with 5.760 +the bug isn't present yet) and those where another problem masks the 5.761 +bug (as I discussed above). 5.762 + 5.763 +Even if you end up ``early'' by thousands of changesets or months of 5.764 +history, you will only add a handful of tests to the total number that 5.765 +\hgcmd{bisect} must perform, thanks to its logarithmic behaviour. 5.766 + 5.767 +%%% Local Variables: 5.768 +%%% mode: latex 5.769 +%%% TeX-master: "00book" 5.770 +%%% End: