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: