Mercurial > hgbook

--- a/es/Leame.1st	Sun Oct 19 17:08:11 2008 -0500
+++ b/es/Leame.1st	Sun Oct 19 19:56:21 2008 -0500
@@ -28,15 +28,17 @@
 de ortografía son siempre bienvenidos.

 == Archivos en proceso de traducción ==
-||'''archivo''''||'''traductor'''||'''Estado'''||'''Inicio'''||  '''Fin'''  ||
-|| 00book.tex   || Igor Támara   ||    100%    || 16/10/2008 ||  16/10/2008 ||
-|| branch.tex   || Igor Támara   ||    100%    || 16/10/2008 ||  19/10/2008 ||
-|| preface.tex  || Javier Rojas  ||    25%     || 18/10/2008 ||             ||
+||'''archivo'''    ||'''traductor'''||'''Estado'''||'''Inicio'''||  '''Fin'''  ||
+|| 00book.tex      || Igor Támara   ||    100%    || 16/10/2008 ||  16/10/2008 ||
+|| branch.tex      || Igor Támara   ||    100%    || 16/10/2008 ||  19/10/2008 ||
+|| preface.tex     || Javier Rojas  ||    100%    || 18/10/2008 ||  19/10/2008 ||
+|| tour-basic.tex  || Javier Rojas  ||    34%     || 19/10/2008 ||             ||

 == Archivos en proceso de revisión ==
-||'''archivo''''|| '''revisor''' ||'''Estado'''||'''Inicio'''||  '''Fin'''  ||
+||'''archivo''' || '''revisor''' ||'''Estado'''||'''Inicio'''||  '''Fin'''  ||
 || 00book.tex   ||               ||            ||            ||             ||
 || branch.tex   ||               ||            ||            ||             ||
+|| preface.tex  ||               ||            ||            ||             ||


 == Archivos terminados ==
@@ -46,6 +48,7 @@

  Branch: Rama
  Bug: Fallo
+ Builtin: integrada/o
  Changelog: Bitácora de Cambios
  Changeset: Conjunto de Cambios
  Command: Orden
--- a/es/concepts.tex	Sun Oct 19 17:08:11 2008 -0500
+++ b/es/concepts.tex	Sun Oct 19 19:56:21 2008 -0500
@@ -0,0 +1,577 @@
+\chapter{Behind the scenes}
+\label{chap:concepts}
+
+Unlike many revision control systems, the concepts upon which
+Mercurial is built are simple enough that it's easy to understand how
+the software really works.  Knowing this certainly isn't necessary,
+but I find it useful to have a ``mental model'' of what's going on.
+
+This understanding gives me confidence that Mercurial has been
+carefully designed to be both \emph{safe} and \emph{efficient}.  And
+just as importantly, if it's easy for me to retain a good idea of what
+the software is doing when I perform a revision control task, I'm less
+likely to be surprised by its behaviour.
+
+In this chapter, we'll initially cover the core concepts behind
+Mercurial's design, then continue to discuss some of the interesting
+details of its implementation.
+
+\section{Mercurial's historical record}
+
+\subsection{Tracking the history of a single file}
+
+When Mercurial tracks modifications to a file, it stores the history
+of that file in a metadata object called a \emph{filelog}.  Each entry
+in the filelog contains enough information to reconstruct one revision
+of the file that is being tracked.  Filelogs are stored as files in
+the \sdirname{.hg/store/data} directory.  A filelog contains two kinds
+of information: revision data, and an index to help Mercurial to find
+a revision efficiently.
+
+A file that is large, or has a lot of history, has its filelog stored
+in separate data (``\texttt{.d}'' suffix) and index (``\texttt{.i}''
+suffix) files.  For small files without much history, the revision
+data and index are combined in a single ``\texttt{.i}'' file.  The
+correspondence between a file in the working directory and the filelog
+that tracks its history in the repository is illustrated in
+figure~\ref{fig:concepts:filelog}.
+
+\begin{figure}[ht]
+  \centering
+  \grafix{filelog}
+  \caption{Relationships between files in working directory and
+    filelogs in repository}
+  \label{fig:concepts:filelog}
+\end{figure}
+
+\subsection{Managing tracked files}
+
+Mercurial uses a structure called a \emph{manifest} to collect
+together information about the files that it tracks.  Each entry in
+the manifest contains information about the files present in a single
+changeset.  An entry records which files are present in the changeset,
+the revision of each file, and a few other pieces of file metadata.
+
+\subsection{Recording changeset information}
+
+The \emph{changelog} contains information about each changeset.  Each
+revision records who committed a change, the changeset comment, other
+pieces of changeset-related information, and the revision of the
+manifest to use.
+
+\subsection{Relationships between revisions}
+
+Within a changelog, a manifest, or a filelog, each revision stores a
+pointer to its immediate parent (or to its two parents, if it's a
+merge revision).  As I mentioned above, there are also relationships
+between revisions \emph{across} these structures, and they are
+hierarchical in nature.
+
+For every changeset in a repository, there is exactly one revision
+stored in the changelog.  Each revision of the changelog contains a
+pointer to a single revision of the manifest.  A revision of the
+manifest stores a pointer to a single revision of each filelog tracked
+when that changeset was created.  These relationships are illustrated
+in figure~\ref{fig:concepts:metadata}.
+
+\begin{figure}[ht]
+  \centering
+  \grafix{metadata}
+  \caption{Metadata relationships}
+  \label{fig:concepts:metadata}
+\end{figure}
+
+As the illustration shows, there is \emph{not} a ``one to one''
+relationship between revisions in the changelog, manifest, or filelog.
+If the manifest hasn't changed between two changesets, the changelog
+entries for those changesets will point to the same revision of the
+manifest.  If a file that Mercurial tracks hasn't changed between two
+changesets, the entry for that file in the two revisions of the
+manifest will point to the same revision of its filelog.
+
+\section{Safe, efficient storage}
+
+The underpinnings of changelogs, manifests, and filelogs are provided
+by a single structure called the \emph{revlog}.
+
+\subsection{Efficient storage}
+
+The revlog provides efficient storage of revisions using a
+\emph{delta} mechanism.  Instead of storing a complete copy of a file
+for each revision, it stores the changes needed to transform an older
+revision into the new revision.  For many kinds of file data, these
+deltas are typically a fraction of a percent of the size of a full
+copy of a file.
+
+Some obsolete revision control systems can only work with deltas of
+text files.  They must either store binary files as complete snapshots
+or encoded into a text representation, both of which are wasteful
+approaches.  Mercurial can efficiently handle deltas of files with
+arbitrary binary contents; it doesn't need to treat text as special.
+
+\subsection{Safe operation}
+\label{sec:concepts:txn}
+
+Mercurial only ever \emph{appends} data to the end of a revlog file.
+It never modifies a section of a file after it has written it.  This
+is both more robust and efficient than schemes that need to modify or
+rewrite data.
+
+In addition, Mercurial treats every write as part of a
+\emph{transaction} that can span a number of files.  A transaction is
+\emph{atomic}: either the entire transaction succeeds and its effects
+are all visible to readers in one go, or the whole thing is undone.
+This guarantee of atomicity means that if you're running two copies of
+Mercurial, where one is reading data and one is writing it, the reader
+will never see a partially written result that might confuse it.
+
+The fact that Mercurial only appends to files makes it easier to
+provide this transactional guarantee.  The easier it is to do stuff
+like this, the more confident you should be that it's done correctly.
+
+\subsection{Fast retrieval}
+
+Mercurial cleverly avoids a pitfall common to all earlier
+revision control systems: the problem of \emph{inefficient retrieval}.
+Most revision control systems store the contents of a revision as an
+incremental series of modifications against a ``snapshot''.  To
+reconstruct a specific revision, you must first read the snapshot, and
+then every one of the revisions between the snapshot and your target
+revision.  The more history that a file accumulates, the more
+revisions you must read, hence the longer it takes to reconstruct a
+particular revision.
+
+\begin{figure}[ht]
+  \centering
+  \grafix{snapshot}
+  \caption{Snapshot of a revlog, with incremental deltas}
+  \label{fig:concepts:snapshot}
+\end{figure}
+
+The innovation that Mercurial applies to this problem is simple but
+effective.  Once the cumulative amount of delta information stored
+since the last snapshot exceeds a fixed threshold, it stores a new
+snapshot (compressed, of course), instead of another delta.  This
+makes it possible to reconstruct \emph{any} revision of a file
+quickly.  This approach works so well that it has since been copied by
+several other revision control systems.
+
+Figure~\ref{fig:concepts:snapshot} illustrates the idea.  In an entry
+in a revlog's index file, Mercurial stores the range of entries from
+the data file that it must read to reconstruct a particular revision.
+
+\subsubsection{Aside: the influence of video compression}
+
+If you're familiar with video compression or have ever watched a TV
+feed through a digital cable or satellite service, you may know that
+most video compression schemes store each frame of video as a delta
+against its predecessor frame.  In addition, these schemes use
+``lossy'' compression techniques to increase the compression ratio, so
+visual errors accumulate over the course of a number of inter-frame
+deltas.
+
+Because it's possible for a video stream to ``drop out'' occasionally
+due to signal glitches, and to limit the accumulation of artefacts
+introduced by the lossy compression process, video encoders
+periodically insert a complete frame (called a ``key frame'') into the
+video stream; the next delta is generated against that frame.  This
+means that if the video signal gets interrupted, it will resume once
+the next key frame is received.  Also, the accumulation of encoding
+errors restarts anew with each key frame.
+
+\subsection{Identification and strong integrity}
+
+Along with delta or snapshot information, a revlog entry contains a
+cryptographic hash of the data that it represents.  This makes it
+difficult to forge the contents of a revision, and easy to detect
+accidental corruption.
+
+Hashes provide more than a mere check against corruption; they are
+used as the identifiers for revisions.  The changeset identification
+hashes that you see as an end user are from revisions of the
+changelog.  Although filelogs and the manifest also use hashes,
+Mercurial only uses these behind the scenes.
+
+Mercurial verifies that hashes are correct when it retrieves file
+revisions and when it pulls changes from another repository.  If it
+encounters an integrity problem, it will complain and stop whatever
+it's doing.
+
+In addition to the effect it has on retrieval efficiency, Mercurial's
+use of periodic snapshots makes it more robust against partial data
+corruption.  If a revlog becomes partly corrupted due to a hardware
+error or system bug, it's often possible to reconstruct some or most
+revisions from the uncorrupted sections of the revlog, both before and
+after the corrupted section.  This would not be possible with a
+delta-only storage model.
+
+\section{Revision history, branching,
+  and merging}
+
+Every entry in a Mercurial revlog knows the identity of its immediate
+ancestor revision, usually referred to as its \emph{parent}.  In fact,
+a revision contains room for not one parent, but two.  Mercurial uses
+a special hash, called the ``null ID'', to represent the idea ``there
+is no parent here''.  This hash is simply a string of zeroes.
+
+In figure~\ref{fig:concepts:revlog}, you can see an example of the
+conceptual structure of a revlog.  Filelogs, manifests, and changelogs
+all have this same structure; they differ only in the kind of data
+stored in each delta or snapshot.
+
+The first revision in a revlog (at the bottom of the image) has the
+null ID in both of its parent slots.  For a ``normal'' revision, its
+first parent slot contains the ID of its parent revision, and its
+second contains the null ID, indicating that the revision has only one
+real parent.  Any two revisions that have the same parent ID are
+branches.  A revision that represents a merge between branches has two
+normal revision IDs in its parent slots.
+
+\begin{figure}[ht]
+  \centering
+  \grafix{revlog}
+  \caption{}
+  \label{fig:concepts:revlog}
+\end{figure}
+
+\section{The working directory}
+
+In the working directory, Mercurial stores a snapshot of the files
+from the repository as of a particular changeset.
+
+The working directory ``knows'' which changeset it contains.  When you
+update the working directory to contain a particular changeset,
+Mercurial looks up the appropriate revision of the manifest to find
+out which files it was tracking at the time that changeset was
+committed, and which revision of each file was then current.  It then
+recreates a copy of each of those files, with the same contents it had
+when the changeset was committed.
+
+The \emph{dirstate} contains Mercurial's knowledge of the working
+directory.  This details which changeset the working directory is
+updated to, and all of the files that Mercurial is tracking in the
+working directory.
+
+Just as a revision of a revlog has room for two parents, so that it
+can represent either a normal revision (with one parent) or a merge of
+two earlier revisions, the dirstate has slots for two parents.  When
+you use the \hgcmd{update} command, the changeset that you update to
+is stored in the ``first parent'' slot, and the null ID in the second.
+When you \hgcmd{merge} with another changeset, the first parent
+remains unchanged, and the second parent is filled in with the
+changeset you're merging with.  The \hgcmd{parents} command tells you
+what the parents of the dirstate are.
+
+\subsection{What happens when you commit}
+
+The dirstate stores parent information for more than just book-keeping
+purposes.  Mercurial uses the parents of the dirstate as \emph{the
+  parents of a new changeset} when you perform a commit.
+
+\begin{figure}[ht]
+  \centering
+  \grafix{wdir}
+  \caption{The working directory can have two parents}
+  \label{fig:concepts:wdir}
+\end{figure}
+
+Figure~\ref{fig:concepts:wdir} shows the normal state of the working
+directory, where it has a single changeset as parent.  That changeset
+is the \emph{tip}, the newest changeset in the repository that has no
+children.
+
+\begin{figure}[ht]
+  \centering
+  \grafix{wdir-after-commit}
+  \caption{The working directory gains new parents after a commit}
+  \label{fig:concepts:wdir-after-commit}
+\end{figure}
+
+It's useful to think of the working directory as ``the changeset I'm
+about to commit''.  Any files that you tell Mercurial that you've
+added, removed, renamed, or copied will be reflected in that
+changeset, as will modifications to any files that Mercurial is
+already tracking; the new changeset will have the parents of the
+working directory as its parents.
+
+After a commit, Mercurial will update the parents of the working
+directory, so that the first parent is the ID of the new changeset,
+and the second is the null ID.  This is shown in
+figure~\ref{fig:concepts:wdir-after-commit}.  Mercurial doesn't touch
+any of the files in the working directory when you commit; it just
+modifies the dirstate to note its new parents.
+
+\subsection{Creating a new head}
+
+It's perfectly normal to update the working directory to a changeset
+other than the current tip.  For example, you might want to know what
+your project looked like last Tuesday, or you could be looking through
+changesets to see which one introduced a bug.  In cases like this, the
+natural thing to do is update the working directory to the changeset
+you're interested in, and then examine the files in the working
+directory directly to see their contents as they werea when you
+committed that changeset.  The effect of this is shown in
+figure~\ref{fig:concepts:wdir-pre-branch}.
+
+\begin{figure}[ht]
+  \centering
+  \grafix{wdir-pre-branch}
+  \caption{The working directory, updated to an older changeset}
+  \label{fig:concepts:wdir-pre-branch}
+\end{figure}
+
+Having updated the working directory to an older changeset, what
+happens if you make some changes, and then commit?  Mercurial behaves
+in the same way as I outlined above.  The parents of the working
+directory become the parents of the new changeset.  This new changeset
+has no children, so it becomes the new tip.  And the repository now
+contains two changesets that have no children; we call these
+\emph{heads}.  You can see the structure that this creates in
+figure~\ref{fig:concepts:wdir-branch}.
+
+\begin{figure}[ht]
+  \centering
+  \grafix{wdir-branch}
+  \caption{After a commit made while synced to an older changeset}
+  \label{fig:concepts:wdir-branch}
+\end{figure}
+
+\begin{note}
+  If you're new to Mercurial, you should keep in mind a common
+  ``error'', which is to use the \hgcmd{pull} command without any
+  options.  By default, the \hgcmd{pull} command \emph{does not}
+  update the working directory, so you'll bring new changesets into
+  your repository, but the working directory will stay synced at the
+  same changeset as before the pull.  If you make some changes and
+  commit afterwards, you'll thus create a new head, because your
+  working directory isn't synced to whatever the current tip is.
+
+  I put the word ``error'' in quotes because all that you need to do
+  to rectify this situation is \hgcmd{merge}, then \hgcmd{commit}.  In
+  other words, this almost never has negative consequences; it just
+  surprises people.  I'll discuss other ways to avoid this behaviour,
+  and why Mercurial behaves in this initially surprising way, later
+  on.
+\end{note}
+
+\subsection{Merging heads}
+
+When you run the \hgcmd{merge} command, Mercurial leaves the first
+parent of the working directory unchanged, and sets the second parent
+to the changeset you're merging with, as shown in
+figure~\ref{fig:concepts:wdir-merge}.
+
+\begin{figure}[ht]
+  \centering
+  \grafix{wdir-merge}
+  \caption{Merging two heads}
+  \label{fig:concepts:wdir-merge}
+\end{figure}
+
+Mercurial also has to modify the working directory, to merge the files
+managed in the two changesets.  Simplified a little, the merging
+process goes like this, for every file in the manifests of both
+changesets.
+\begin{itemize}
+\item If neither changeset has modified a file, do nothing with that
+  file.
+\item If one changeset has modified a file, and the other hasn't,
+  create the modified copy of the file in the working directory.
+\item If one changeset has removed a file, and the other hasn't (or
+  has also deleted it), delete the file from the working directory.
+\item If one changeset has removed a file, but the other has modified
+  the file, ask the user what to do: keep the modified file, or remove
+  it?
+\item If both changesets have modified a file, invoke an external
+  merge program to choose the new contents for the merged file.  This
+  may require input from the user.
+\item If one changeset has modified a file, and the other has renamed
+  or copied the file, make sure that the changes follow the new name
+  of the file.
+\end{itemize}
+There are more details---merging has plenty of corner cases---but
+these are the most common choices that are involved in a merge.  As
+you can see, most cases are completely automatic, and indeed most
+merges finish automatically, without requiring your input to resolve
+any conflicts.
+
+When you're thinking about what happens when you commit after a merge,
+once again the working directory is ``the changeset I'm about to
+commit''.  After the \hgcmd{merge} command completes, the working
+directory has two parents; these will become the parents of the new
+changeset.
+
+Mercurial lets you perform multiple merges, but you must commit the
+results of each individual merge as you go.  This is necessary because
+Mercurial only tracks two parents for both revisions and the working
+directory.  While it would be technically possible to merge multiple
+changesets at once, the prospect of user confusion and making a
+terrible mess of a merge immediately becomes overwhelming.
+
+\section{Other interesting design features}
+
+In the sections above, I've tried to highlight some of the most
+important aspects of Mercurial's design, to illustrate that it pays
+careful attention to reliability and performance.  However, the
+attention to detail doesn't stop there.  There are a number of other
+aspects of Mercurial's construction that I personally find
+interesting.  I'll detail a few of them here, separate from the ``big
+ticket'' items above, so that if you're interested, you can gain a
+better idea of the amount of thinking that goes into a well-designed
+system.
+
+\subsection{Clever compression}
+
+When appropriate, Mercurial will store both snapshots and deltas in
+compressed form.  It does this by always \emph{trying to} compress a
+snapshot or delta, but only storing the compressed version if it's
+smaller than the uncompressed version.
+
+This means that Mercurial does ``the right thing'' when storing a file
+whose native form is compressed, such as a \texttt{zip} archive or a
+JPEG image.  When these types of files are compressed a second time,
+the resulting file is usually bigger than the once-compressed form,
+and so Mercurial will store the plain \texttt{zip} or JPEG.
+
+Deltas between revisions of a compressed file are usually larger than
+snapshots of the file, and Mercurial again does ``the right thing'' in
+these cases.  It finds that such a delta exceeds the threshold at
+which it should store a complete snapshot of the file, so it stores
+the snapshot, again saving space compared to a naive delta-only
+approach.
+
+\subsubsection{Network recompression}
+
+When storing revisions on disk, Mercurial uses the ``deflate''
+compression algorithm (the same one used by the popular \texttt{zip}
+archive format), which balances good speed with a respectable
+compression ratio.  However, when transmitting revision data over a
+network connection, Mercurial uncompresses the compressed revision
+data.
+
+If the connection is over HTTP, Mercurial recompresses the entire
+stream of data using a compression algorithm that gives a better
+compression ratio (the Burrows-Wheeler algorithm from the widely used
+\texttt{bzip2} compression package).  This combination of algorithm
+and compression of the entire stream (instead of a revision at a time)
+substantially reduces the number of bytes to be transferred, yielding
+better network performance over almost all kinds of network.
+
+(If the connection is over \command{ssh}, Mercurial \emph{doesn't}
+recompress the stream, because \command{ssh} can already do this
+itself.)
+
+\subsection{Read/write ordering and atomicity}
+
+Appending to files isn't the whole story when it comes to guaranteeing
+that a reader won't see a partial write.  If you recall
+figure~\ref{fig:concepts:metadata}, revisions in the changelog point to
+revisions in the manifest, and revisions in the manifest point to
+revisions in filelogs.  This hierarchy is deliberate.
+
+A writer starts a transaction by writing filelog and manifest data,
+and doesn't write any changelog data until those are finished.  A
+reader starts by reading changelog data, then manifest data, followed
+by filelog data.
+
+Since the writer has always finished writing filelog and manifest data
+before it writes to the changelog, a reader will never read a pointer
+to a partially written manifest revision from the changelog, and it will
+never read a pointer to a partially written filelog revision from the
+manifest.
+
+\subsection{Concurrent access}
+
+The read/write ordering and atomicity guarantees mean that Mercurial
+never needs to \emph{lock} a repository when it's reading data, even
+if the repository is being written to while the read is occurring.
+This has a big effect on scalability; you can have an arbitrary number
+of Mercurial processes safely reading data from a repository safely
+all at once, no matter whether it's being written to or not.
+
+The lockless nature of reading means that if you're sharing a
+repository on a multi-user system, you don't need to grant other local
+users permission to \emph{write} to your repository in order for them
+to be able to clone it or pull changes from it; they only need
+\emph{read} permission.  (This is \emph{not} a common feature among
+revision control systems, so don't take it for granted!  Most require
+readers to be able to lock a repository to access it safely, and this
+requires write permission on at least one directory, which of course
+makes for all kinds of nasty and annoying security and administrative
+problems.)
+
+Mercurial uses locks to ensure that only one process can write to a
+repository at a time (the locking mechanism is safe even over
+filesystems that are notoriously hostile to locking, such as NFS).  If
+a repository is locked, a writer will wait for a while to retry if the
+repository becomes unlocked, but if the repository remains locked for
+too long, the process attempting to write will time out after a while.
+This means that your daily automated scripts won't get stuck forever
+and pile up if a system crashes unnoticed, for example.  (Yes, the
+timeout is configurable, from zero to infinity.)
+
+\subsubsection{Safe dirstate access}
+
+As with revision data, Mercurial doesn't take a lock to read the
+dirstate file; it does acquire a lock to write it.  To avoid the
+possibility of reading a partially written copy of the dirstate file,
+Mercurial writes to a file with a unique name in the same directory as
+the dirstate file, then renames the temporary file atomically to
+\filename{dirstate}.  The file named \filename{dirstate} is thus
+guaranteed to be complete, not partially written.
+
+\subsection{Avoiding seeks}
+
+Critical to Mercurial's performance is the avoidance of seeks of the
+disk head, since any seek is far more expensive than even a
+comparatively large read operation.
+
+This is why, for example, the dirstate is stored in a single file.  If
+there were a dirstate file per directory that Mercurial tracked, the
+disk would seek once per directory.  Instead, Mercurial reads the
+entire single dirstate file in one step.
+
+Mercurial also uses a ``copy on write'' scheme when cloning a
+repository on local storage.  Instead of copying every revlog file
+from the old repository into the new repository, it makes a ``hard
+link'', which is a shorthand way to say ``these two names point to the
+same file''.  When Mercurial is about to write to one of a revlog's
+files, it checks to see if the number of names pointing at the file is
+greater than one.  If it is, more than one repository is using the
+file, so Mercurial makes a new copy of the file that is private to
+this repository.
+
+A few revision control developers have pointed out that this idea of
+making a complete private copy of a file is not very efficient in its
+use of storage.  While this is true, storage is cheap, and this method
+gives the highest performance while deferring most book-keeping to the
+operating system.  An alternative scheme would most likely reduce
+performance and increase the complexity of the software, each of which
+is much more important to the ``feel'' of day-to-day use.
+
+\subsection{Other contents of the dirstate}
+
+Because Mercurial doesn't force you to tell it when you're modifying a
+file, it uses the dirstate to store some extra information so it can
+determine efficiently whether you have modified a file.  For each file
+in the working directory, it stores the time that it last modified the
+file itself, and the size of the file at that time.
+
+When you explicitly \hgcmd{add}, \hgcmd{remove}, \hgcmd{rename} or
+\hgcmd{copy} files, Mercurial updates the dirstate so that it knows
+what to do with those files when you commit.
+
+When Mercurial is checking the states of files in the working
+directory, it first checks a file's modification time.  If that has
+not changed, the file must not have been modified.  If the file's size
+has changed, the file must have been modified.  If the modification
+time has changed, but the size has not, only then does Mercurial need
+to read the actual contents of the file to see if they've changed.
+Storing these few extra pieces of information dramatically reduces the
+amount of data that Mercurial needs to read, which yields large
+performance improvements compared to other revision control systems.
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "00book"
+%%% End:
--- a/es/preface.tex	Sun Oct 19 17:08:11 2008 -0500
+++ b/es/preface.tex	Sun Oct 19 19:56:21 2008 -0500
@@ -2,8 +2,7 @@
 \addcontentsline{toc}{chapter}{Prefacio}
 \label{chap:preface}

-% TODO no es mejor decir control distribuido de revisiones?
-El control de revisiones distribuido es un territorio relativamente
+El control distribuido de revisiones es un territorio relativamente
 nuevo, y ha crecido hasta ahora
 % TODO el original dice "due to", que sería "debido", pero creo que "gracias
 % a" queda mejor
@@ -55,20 +54,19 @@
 puede ver esto en el ejemplo \hgext{bisect} en la
 sección~\ref{sec:undo:bisect}, por ejemplo.

-So when you're reading examples, don't place too much weight on the
-dates or times you see in the output of commands.  But \emph{do} be
-confident that the behaviour you're seeing is consistent and
-reproducible.
-
-\section{Colophon---this book is Free}
+Así que cuando usted lea los ejemplos, no le dé mucha importancia a
+las fechas o horas que vea en las salidas de los comandos. Pero
+\emph{tenga} confianza en que el comportamiento que está viendo es
+consistente y reproducible.

-This book is licensed under the Open Publication License, and is
-produced entirely using Free Software tools.  It is typeset with
-\LaTeX{}; illustrations are drawn and rendered with
-\href{http://www.inkscape.org/}{Inkscape}.
+\section{Colofón---este libro es Libre}
+Este libro está licenciado bajo la Licencia de Publicación Abierta, y
+es producido en su totalidad usando herramientas de Software Libre. Es
+compuesto con \LaTeX{}; las ilustraciones son dibujadas y generadas
+con \href{http://www.inkscape.org/}{Inkscape}.

-The complete source code for this book is published as a Mercurial
-repository, at \url{http://hg.serpentine.com/mercurial/book}.
+El código fuente completo para este libro es publicado como un
+repositorio Mercurial, en \url{http://hg.serpentine.com/mercurial/book}.

 %%% Local Variables:
 %%% mode: latex
--- a/es/tour-basic.tex	Sun Oct 19 17:08:11 2008 -0500
+++ b/es/tour-basic.tex	Sun Oct 19 19:56:21 2008 -0500
@@ -0,0 +1,631 @@
+\chapter{Una gira de Mercurial: lo básico}
+\label{chap:tour-basic}
+
+\section{Instalar Mercurial en su sistema}
+\label{sec:tour:install}
+Hay paquetes binarios precompilados de Mercurial disponibles para cada
+sistema operativo popular. Esto hace fácil empezar a usar Mercurial
+en su computador inmediatamente.
+
+\subsection{Linux}
+
+Dado que cada distribución de Linux tiene sus propias herramientas de
+manejo de paquetes, políticas, y ritmos de desarrollo, es difícil dar
+un conjunto exhaustivo de instrucciones sobre cómo instalar el paquete
+de Mercurial. La versión de Mercurial que usted tenga a disposición
+puede variar dependiendo de qué tan activa sea la persona que mantiene
+el paquete para su distribución.
+
+Para mantener las cosas simples, me enfocaré en instalar Mercurial
+desde la línea de comandos en las distribuciones de Linux más
+populares. La mayoría de estas distribuciones proveen administradores
+de paquetes gráficos que le permitirán instalar Mercurial con un solo
+clic; el nombre de paquete a buscar es \texttt{mercurial}.
+
+\begin{itemize}
+\item[Debian]
+  \begin{codesample4}
+    apt-get install mercurial
+  \end{codesample4}
+
+\item[Fedora Core]
+  \begin{codesample4}
+    yum install mercurial
+  \end{codesample4}
+
+\item[Gentoo]
+  \begin{codesample4}
+    emerge mercurial
+  \end{codesample4}
+
+\item[OpenSUSE]
+  \begin{codesample4}
+    yum install mercurial
+  \end{codesample4}
+
+\item[Ubuntu] El paquete de Mercurial de Ubuntu está basado en el de
+    Debian. Para instalarlo, ejecute el siguiente comando.
+  \begin{codesample4}
+    apt-get install mercurial
+  \end{codesample4}
+  El paquete de Mercurial para Ubuntu tiende a atrasarse con respecto
+  a la versión de Debian por un margen de tiempo considerable
+  (al momento de escribir esto, 7 meses), lo que en algunos casos
+  significará que usted puede encontrarse con problemas que ya habrán
+  sido resueltos en el paquete de Debian.
+\end{itemize}
+
+\subsection{Solaris}
+
+SunFreeWare, en \url{http://www.sunfreeware.com}, es una buena fuente
+para un gran número de paquetes compilados para Solaris para las
+arquitecturas Intel y Sparc de 32 y 64 bits, incluyendo versiones
+actuales de Mercurial.
+
+\subsection{Mac OS X}
+
+Lee Cantey publica un instalador de Mercurial para Mac OS~X en
+\url{http://mercurial.berkwood.com}.  Este paquete funciona en tanto
+en Macs basados en Intel como basados en PowerPC. Antes de que pueda
+usarlo, usted debe instalar una versión compatible de Universal
+MacPython~\cite{web:macpython}. Esto es fácil de hacer; simplemente
+siga las instrucciones de el sitio de Lee.
+
+También es posible instalar Mercurial usando Fink o MacPorts, dos
+administradores de paquetes gratuitos y populares para Mac OS X. Si
+usted tiene Fink, use \command{sudo apt-get install mercurial-py25}.
+Si usa MacPorts, \command{sudo port install mercurial}.
+
+\subsection{Windows}
+
+Lee Cantey publica un instalador de Mercurial para Windows en
+\url{http://mercurial.berkwood.com}. Este paquete no tiene
+% TODO traducción de it just works. Agreed?
+dependencias externas; ``simplemente funciona''.
+
+\begin{note}
+    La versión de Windows de Mercurial no convierte automáticamente
+    los fines de línea entre estilos Windows y Unix. Si usted desea
+    compartir trabajo con usuarios de Unix, deberá hacer un trabajo
+    adicional de configuración. XXX Terminar esto.
+\end{note}
+
+\section{Arrancando}
+
+Para empezar, usaremos el comando \hgcmd{version} para revisar si
+Mercurial está instalado adecuadamente. La información de la versión
+que es impresa no es tan importante; lo que nos importa es si imprime
+algo en absoluto.
+
+\interaction{tour.version}
+
+% TODO builtin-> integrado?
+\subsection{Ayuda integrada}
+
+Mercurial provee un sistema de ayuda integrada. Esto es invaluable
+para ésas ocasiones en la que usted está atorado tratando de recordar
+cómo ejecutar un comando. Si está completamente atorado, simplemente
+ejecute \hgcmd{help}; esto imprimirá una breve lista de comandos,
+junto con una descripción de qué hace cada uno. Si usted solicita
+ayuda sobre un comando específico (como abajo), se imprime información
+más detallada.
+\interaction{tour.help}
+Para un nivel más impresionante de detalle (que usted no va a
+necesitar usualmente) ejecute \hgcmdargs{help}{\hggopt{-v}}. La opción
+\hggopt{-v} es la abreviación para \hggopt{--verbose}, y le indica a
+Mercurial que imprima más información de lo que haría usualmente.
+
+\section{Working with a repository}
+
+In Mercurial, everything happens inside a \emph{repository}.  The
+repository for a project contains all of the files that ``belong to''
+that project, along with a historical record of the project's files.
+
+There's nothing particularly magical about a repository; it is simply
+a directory tree in your filesystem that Mercurial treats as special.
+You can rename or delete a repository any time you like, using either the
+command line or your file browser.
+
+\subsection{Making a local copy of a repository}
+
+\emph{Copying} a repository is just a little bit special.  While you
+could use a normal file copying command to make a copy of a
+repository, it's best to use a built-in command that Mercurial
+provides.  This command is called \hgcmd{clone}, because it creates an
+identical copy of an existing repository.
+\interaction{tour.clone}
+If our clone succeeded, we should now have a local directory called
+\dirname{hello}.  This directory will contain some files.
+\interaction{tour.ls}
+These files have the same contents and history in our repository as
+they do in the repository we cloned.
+
+Every Mercurial repository is complete, self-contained, and
+independent.  It contains its own private copy of a project's files
+and history.  A cloned repository remembers the location of the
+repository it was cloned from, but it does not communicate with that
+repository, or any other, unless you tell it to.
+
+What this means for now is that we're free to experiment with our
+repository, safe in the knowledge that it's a private ``sandbox'' that
+won't affect anyone else.
+
+\subsection{What's in a repository?}
+
+When we take a more detailed look inside a repository, we can see that
+it contains a directory named \dirname{.hg}.  This is where Mercurial
+keeps all of its metadata for the repository.
+\interaction{tour.ls-a}
+
+The contents of the \dirname{.hg} directory and its subdirectories are
+private to Mercurial.  Every other file and directory in the
+repository is yours to do with as you please.
+
+To introduce a little terminology, the \dirname{.hg} directory is the
+``real'' repository, and all of the files and directories that coexist
+with it are said to live in the \emph{working directory}.  An easy way
+to remember the distinction is that the \emph{repository} contains the
+\emph{history} of your project, while the \emph{working directory}
+contains a \emph{snapshot} of your project at a particular point in
+history.
+
+\section{A tour through history}
+
+One of the first things we might want to do with a new, unfamiliar
+repository is understand its history.  The \hgcmd{log} command gives
+us a view of history.
+\interaction{tour.log}
+By default, this command prints a brief paragraph of output for each
+change to the project that was recorded.  In Mercurial terminology, we
+call each of these recorded events a \emph{changeset}, because it can
+contain a record of changes to several files.
+
+The fields in a record of output from \hgcmd{log} are as follows.
+\begin{itemize}
+\item[\texttt{changeset}] This field has the format of a number,
+  followed by a colon, followed by a hexadecimal string.  These are
+  \emph{identifiers} for the changeset.  There are two identifiers
+  because the number is shorter and easier to type than the hex
+  string.
+\item[\texttt{user}] The identity of the person who created the
+  changeset.  This is a free-form field, but it most often contains a
+  person's name and email address.
+\item[\texttt{date}] The date and time on which the changeset was
+  created, and the timezone in which it was created.  (The date and
+  time are local to that timezone; they display what time and date it
+  was for the person who created the changeset.)
+\item[\texttt{summary}] The first line of the text message that the
+  creator of the changeset entered to describe the changeset.
+\end{itemize}
+The default output printed by \hgcmd{log} is purely a summary; it is
+missing a lot of detail.
+
+Figure~\ref{fig:tour-basic:history} provides a graphical representation of
+the history of the \dirname{hello} repository, to make it a little
+easier to see which direction history is ``flowing'' in.  We'll be
+returning to this figure several times in this chapter and the chapter
+that follows.
+
+\begin{figure}[ht]
+  \centering
+  \grafix{tour-history}
+  \caption{Graphical history of the \dirname{hello} repository}
+  \label{fig:tour-basic:history}
+\end{figure}
+
+\subsection{Changesets, revisions, and talking to other
+  people}
+
+As English is a notoriously sloppy language, and computer science has
+a hallowed history of terminological confusion (why use one term when
+four will do?), revision control has a variety of words and phrases
+that mean the same thing.  If you are talking about Mercurial history
+with other people, you will find that the word ``changeset'' is often
+compressed to ``change'' or (when written) ``cset'', and sometimes a
+changeset is referred to as a ``revision'' or a ``rev''.
+
+While it doesn't matter what \emph{word} you use to refer to the
+concept of ``a~changeset'', the \emph{identifier} that you use to
+refer to ``a~\emph{specific} changeset'' is of great importance.
+Recall that the \texttt{changeset} field in the output from
+\hgcmd{log} identifies a changeset using both a number and a
+hexadecimal string.
+\begin{itemize}
+\item The revision number is \emph{only valid in that repository},
+\item while the hex string is the \emph{permanent, unchanging
+    identifier} that will always identify that exact changeset in
+  \emph{every} copy of the repository.
+\end{itemize}
+This distinction is important.  If you send someone an email talking
+about ``revision~33'', there's a high likelihood that their
+revision~33 will \emph{not be the same} as yours.  The reason for this
+is that a revision number depends on the order in which changes
+arrived in a repository, and there is no guarantee that the same
+changes will happen in the same order in different repositories.
+Three changes $a,b,c$ can easily appear in one repository as $0,1,2$,
+while in another as $1,0,2$.
+
+Mercurial uses revision numbers purely as a convenient shorthand.  If
+you need to discuss a changeset with someone, or make a record of a
+changeset for some other reason (for example, in a bug report), use
+the hexadecimal identifier.
+
+\subsection{Viewing specific revisions}
+
+To narrow the output of \hgcmd{log} down to a single revision, use the
+\hgopt{log}{-r} (or \hgopt{log}{--rev}) option.  You can use either a
+revision number or a long-form changeset identifier, and you can
+provide as many revisions as you want.  \interaction{tour.log-r}
+
+If you want to see the history of several revisions without having to
+list each one, you can use \emph{range notation}; this lets you
+express the idea ``I want all revisions between $a$ and $b$,
+inclusive''.
+\interaction{tour.log.range}
+Mercurial also honours the order in which you specify revisions, so
+\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
+prints $4,3,2$.
+
+\subsection{More detailed information}
+
+While the summary information printed by \hgcmd{log} is useful if you
+already know what you're looking for, you may need to see a complete
+description of the change, or a list of the files changed, if you're
+trying to decide whether a changeset is the one you're looking for.
+The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose})
+option gives you this extra detail.
+\interaction{tour.log-v}
+
+If you want to see both the description and content of a change, add
+the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option.  This displays
+the content of a change as a \emph{unified diff} (if you've never seen
+a unified diff before, see section~\ref{sec:mq:patch} for an overview).
+\interaction{tour.log-vp}
+
+\section{All about command options}
+
+Let's take a brief break from exploring Mercurial commands to discuss
+a pattern in the way that they work; you may find this useful to keep
+in mind as we continue our tour.
+
+Mercurial has a consistent and straightforward approach to dealing
+with the options that you can pass to commands.  It follows the
+conventions for options that are common to modern Linux and Unix
+systems.
+\begin{itemize}
+\item Every option has a long name.  For example, as we've already
+  seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
+\item Most options have short names, too.  Instead of
+  \hgopt{log}{--rev}, we can use \hgopt{log}{-r}.  (The reason that
+  some options don't have short names is that the options in question
+  are rarely used.)
+\item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
+  while short options start with one (e.g.~\hgopt{log}{-r}).
+\item Option naming and usage is consistent across commands.  For
+  example, every command that lets you specify a changeset~ID or
+  revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
+  arguments.
+\end{itemize}
+In the examples throughout this book, I use short options instead of
+long.  This just reflects my own preference, so don't read anything
+significant into it.
+
+Most commands that print output of some kind will print more output
+when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
+when passed \hggopt{-q} (or \hggopt{--quiet}).
+
+\section{Making and reviewing changes}
+
+Now that we have a grasp of viewing history in Mercurial, let's take a
+look at making some changes and examining them.
+
+The first thing we'll do is isolate our experiment in a repository of
+its own.  We use the \hgcmd{clone} command, but we don't need to
+clone a copy of the remote repository.  Since we already have a copy
+of it locally, we can just clone that instead.  This is much faster
+than cloning over the network, and cloning a local repository uses
+less disk space in most cases, too.
+\interaction{tour.reclone}
+As an aside, it's often good practice to keep a ``pristine'' copy of a
+remote repository around, which you can then make temporary clones of
+to create sandboxes for each task you want to work on.  This lets you
+work on multiple tasks in parallel, each isolated from the others
+until it's complete and you're ready to integrate it back.  Because
+local clones are so cheap, there's almost no overhead to cloning and
+destroying repositories whenever you want.
+
+In our \dirname{my-hello} repository, we have a file
+\filename{hello.c} that contains the classic ``hello, world'' program.
+Let's use the ancient and venerable \command{sed} command to edit this
+file so that it prints a second line of output.  (I'm only using
+\command{sed} to do this because it's easy to write a scripted example
+this way.  Since you're not under the same constraint, you probably
+won't want to use \command{sed}; simply use your preferred text editor to
+do the same thing.)
+\interaction{tour.sed}
+
+Mercurial's \hgcmd{status} command will tell us what Mercurial knows
+about the files in the repository.
+\interaction{tour.status}
+The \hgcmd{status} command prints no output for some files, but a line
+starting with ``\texttt{M}'' for \filename{hello.c}.  Unless you tell
+it to, \hgcmd{status} will not print any output for files that have
+not been modified.
+
+The ``\texttt{M}'' indicates that Mercurial has noticed that we
+modified \filename{hello.c}.  We didn't need to \emph{inform}
+Mercurial that we were going to modify the file before we started, or
+that we had modified the file after we were done; it was able to
+figure this out itself.
+
+It's a little bit helpful to know that we've modified
+\filename{hello.c}, but we might prefer to know exactly \emph{what}
+changes we've made to it.  To do this, we use the \hgcmd{diff}
+command.
+\interaction{tour.diff}
+
+\section{Recording changes in a new changeset}
+
+We can modify files, build and test our changes, and use
+\hgcmd{status} and \hgcmd{diff} to review our changes, until we're
+satisfied with what we've done and arrive at a natural stopping point
+where we want to record our work in a new changeset.
+
+The \hgcmd{commit} command lets us create a new changeset; we'll
+usually refer to this as ``making a commit'' or ``committing''.
+
+\subsection{Setting up a username}
+
+When you try to run \hgcmd{commit} for the first time, it is not
+guaranteed to succeed.  Mercurial records your name and address with
+each change that you commit, so that you and others will later be able
+to tell who made each change.  Mercurial tries to automatically figure
+out a sensible username to commit the change with.  It will attempt
+each of the following methods, in order:
+\begin{enumerate}
+\item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit}
+  command on the command line, followed by a username, this is always
+  given the highest precedence.
+\item If you have set the \envar{HGUSER} environment variable, this is
+  checked next.
+\item If you create a file in your home directory called
+  \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be
+  used next.  To see what the contents of this file should look like,
+  refer to section~\ref{sec:tour-basic:username} below.
+\item If you have set the \envar{EMAIL} environment variable, this
+  will be used next.
+\item Mercurial will query your system to find out your local user
+  name and host name, and construct a username from these components.
+  Since this often results in a username that is not very useful, it
+  will print a warning if it has to do this.
+\end{enumerate}
+If all of these mechanisms fail, Mercurial will fail, printing an
+error message.  In this case, it will not let you commit until you set
+up a username.
+
+You should think of the \envar{HGUSER} environment variable and the
+\hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to
+\emph{override} Mercurial's default selection of username.  For normal
+use, the simplest and most robust way to set a username for yourself
+is by creating a \sfilename{.hgrc} file; see below for details.
+
+\subsubsection{Creating a Mercurial configuration file}
+\label{sec:tour-basic:username}
+
+To set a user name, use your favourite editor to create a file called
+\sfilename{.hgrc} in your home directory.  Mercurial will use this
+file to look up your personalised configuration settings.  The initial
+contents of your \sfilename{.hgrc} should look like this.
+\begin{codesample2}
+  # This is a Mercurial configuration file.
+  [ui]
+  username = Firstname Lastname <email.address@domain.net>
+\end{codesample2}
+The ``\texttt{[ui]}'' line begins a \emph{section} of the config file,
+so you can read the ``\texttt{username = ...}'' line as meaning ``set
+the value of the \texttt{username} item in the \texttt{ui} section''.
+A section continues until a new section begins, or the end of the
+file.  Mercurial ignores empty lines and treats any text from
+``\texttt{\#}'' to the end of a line as a comment.
+
+\subsubsection{Choosing a user name}
+
+You can use any text you like as the value of the \texttt{username}
+config item, since this information is for reading by other people,
+but for interpreting by Mercurial.  The convention that most people
+follow is to use their name and email address, as in the example
+above.
+
+\begin{note}
+  Mercurial's built-in web server obfuscates email addresses, to make
+  it more difficult for the email harvesting tools that spammers use.
+  This reduces the likelihood that you'll start receiving more junk
+  email if you publish a Mercurial repository on the web.
+\end{note}
+
+\subsection{Writing a commit message}
+
+When we commit a change, Mercurial drops us into a text editor, to
+enter a message that will describe the modifications we've made in
+this changeset.  This is called the \emph{commit message}.  It will be
+a record for readers of what we did and why, and it will be printed by
+\hgcmd{log} after we've finished committing.
+\interaction{tour.commit}
+
+The editor that the \hgcmd{commit} command drops us into will contain
+an empty line, followed by a number of lines starting with
+``\texttt{HG:}''.
+\begin{codesample2}
+  \emph{empty line}
+  HG: changed hello.c
+\end{codesample2}
+Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
+them only to tell us which files it's recording changes to.  Modifying
+or deleting these lines has no effect.
+
+\subsection{Writing a good commit message}
+
+Since \hgcmd{log} only prints the first line of a commit message by
+default, it's best to write a commit message whose first line stands
+alone.  Here's a real example of a commit message that \emph{doesn't}
+follow this guideline, and hence has a summary that is not readable.
+\begin{codesample2}
+  changeset:   73:584af0e231be
+  user:        Censored Person <censored.person@example.org>
+  date:        Tue Sep 26 21:37:07 2006 -0700
+  summary:     include buildmeister/commondefs.   Add an exports and install
+\end{codesample2}
+
+As far as the remainder of the contents of the commit message are
+concerned, there are no hard-and-fast rules.  Mercurial itself doesn't
+interpret or care about the contents of the commit message, though
+your project may have policies that dictate a certain kind of
+formatting.
+
+My personal preference is for short, but informative, commit messages
+that tell me something that I can't figure out with a quick glance at
+the output of \hgcmdargs{log}{--patch}.
+
+\subsection{Aborting a commit}
+
+If you decide that you don't want to commit while in the middle of
+editing a commit message, simply exit from your editor without saving
+the file that it's editing.  This will cause nothing to happen to
+either the repository or the working directory.
+
+If we run the \hgcmd{commit} command without any arguments, it records
+all of the changes we've made, as reported by \hgcmd{status} and
+\hgcmd{diff}.
+
+\subsection{Admiring our new handiwork}
+
+Once we've finished the commit, we can use the \hgcmd{tip} command to
+display the changeset we just created.  This command produces output
+that is identical to \hgcmd{log}, but it only displays the newest
+revision in the repository.
+\interaction{tour.tip}
+We refer to the newest revision in the repository as the tip revision,
+or simply the tip.
+
+\section{Sharing changes}
+
+We mentioned earlier that repositories in Mercurial are
+self-contained.  This means that the changeset we just created exists
+only in our \dirname{my-hello} repository.  Let's look at a few ways
+that we can propagate this change into other repositories.
+
+\subsection{Pulling changes from another repository}
+\label{sec:tour:pull}
+
+To get started, let's clone our original \dirname{hello} repository,
+which does not contain the change we just committed.  We'll call our
+temporary repository \dirname{hello-pull}.
+\interaction{tour.clone-pull}
+
+We'll use the \hgcmd{pull} command to bring changes from
+\dirname{my-hello} into \dirname{hello-pull}.  However, blindly
+pulling unknown changes into a repository is a somewhat scary
+prospect.  Mercurial provides the \hgcmd{incoming} command to tell us
+what changes the \hgcmd{pull} command \emph{would} pull into the
+repository, without actually pulling the changes in.
+\interaction{tour.incoming}
+(Of course, someone could cause more changesets to appear in the
+repository that we ran \hgcmd{incoming} in, before we get a chance to
+\hgcmd{pull} the changes, so that we could end up pulling changes that we
+didn't expect.)
+
+Bringing changes into a repository is a simple matter of running the
+\hgcmd{pull} command, and telling it which repository to pull from.
+\interaction{tour.pull}
+As you can see from the before-and-after output of \hgcmd{tip}, we
+have successfully pulled changes into our repository.  There remains
+one step before we can see these changes in the working directory.
+
+\subsection{Updating the working directory}
+
+We have so far glossed over the relationship between a repository and
+its working directory.  The \hgcmd{pull} command that we ran in
+section~\ref{sec:tour:pull} brought changes into the repository, but
+if we check, there's no sign of those changes in the working
+directory.  This is because \hgcmd{pull} does not (by default) touch
+the working directory.  Instead, we use the \hgcmd{update} command to
+do this.
+\interaction{tour.update}
+
+It might seem a bit strange that \hgcmd{pull} doesn't update the
+working directory automatically.  There's actually a good reason for
+this: you can use \hgcmd{update} to update the working directory to
+the state it was in at \emph{any revision} in the history of the
+repository.  If you had the working directory updated to an old
+revision---to hunt down the origin of a bug, say---and ran a
+\hgcmd{pull} which automatically updated the working directory to a
+new revision, you might not be terribly happy.
+
+However, since pull-then-update is such a common thing to do,
+Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
+option to \hgcmd{pull}.
+\begin{codesample2}
+  hg pull -u
+\end{codesample2}
+If you look back at the output of \hgcmd{pull} in
+section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
+you can see that it printed a helpful reminder that we'd have to take
+an explicit step to update the working directory:
+\begin{codesample2}
+  (run 'hg update' to get a working copy)
+\end{codesample2}
+
+To find out what revision the working directory is at, use the
+\hgcmd{parents} command.
+\interaction{tour.parents}
+If you look back at figure~\ref{fig:tour-basic:history}, you'll see
+arrows connecting each changeset.  The node that the arrow leads
+\emph{from} in each case is a parent, and the node that the arrow
+leads \emph{to} is its child.  The working directory has a parent in
+just the same way; this is the changeset that the working directory
+currently contains.
+
+To update the working directory to a particular revision, give a
+revision number or changeset~ID to the \hgcmd{update} command.
+\interaction{tour.older}
+If you omit an explicit revision, \hgcmd{update} will update to the
+tip revision, as shown by the second call to \hgcmd{update} in the
+example above.
+
+\subsection{Pushing changes to another repository}
+
+Mercurial lets us push changes to another repository, from the
+repository we're currently visiting.  As with the example of
+\hgcmd{pull} above, we'll create a temporary repository to push our
+changes into.
+\interaction{tour.clone-push}
+The \hgcmd{outgoing} command tells us what changes would be pushed
+into another repository.
+\interaction{tour.outgoing}
+And the \hgcmd{push} command does the actual push.
+\interaction{tour.push}
+As with \hgcmd{pull}, the \hgcmd{push} command does not update the
+working directory in the repository that it's pushing changes into.
+(Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
+option that updates the other repository's working directory.)
+
+What happens if we try to pull or push changes and the receiving
+repository already has those changes?  Nothing too exciting.
+\interaction{tour.push.nothing}
+
+\subsection{Sharing changes over a network}
+
+The commands we have covered in the previous few sections are not
+limited to working with local repositories.  Each works in exactly the
+same fashion over a network connection; simply pass in a URL instead
+of a local path.
+\interaction{tour.outgoing.net}
+In this example, we can see what changes we could push to the remote
+repository, but the repository is understandably not set up to let
+anonymous users push to it.
+\interaction{tour.push.net}
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "00book"
+%%% End:
--- a/es/undo.tex	Sun Oct 19 17:08:11 2008 -0500
+++ b/es/undo.tex	Sun Oct 19 19:56:21 2008 -0500
@@ -0,0 +1,767 @@
+\chapter{Finding and fixing your mistakes}
+\label{chap:undo}
+
+To err might be human, but to really handle the consequences well
+takes a top-notch revision control system.  In this chapter, we'll
+discuss some of the techniques you can use when you find that a
+problem has crept into your project.  Mercurial has some highly
+capable features that will help you to isolate the sources of
+problems, and to handle them appropriately.
+
+\section{Erasing local history}
+
+\subsection{The accidental commit}
+
+I have the occasional but persistent problem of typing rather more
+quickly than I can think, which sometimes results in me committing a
+changeset that is either incomplete or plain wrong.  In my case, the
+usual kind of incomplete changeset is one in which I've created a new
+source file, but forgotten to \hgcmd{add} it.  A ``plain wrong''
+changeset is not as common, but no less annoying.
+
+\subsection{Rolling back a transaction}
+\label{sec:undo:rollback}
+
+In section~\ref{sec:concepts:txn}, I mentioned that Mercurial treats
+each modification of a repository as a \emph{transaction}.  Every time
+you commit a changeset or pull changes from another repository,
+Mercurial remembers what you did.  You can undo, or \emph{roll back},
+exactly one of these actions using the \hgcmd{rollback} command.  (See
+section~\ref{sec:undo:rollback-after-push} for an important caveat
+about the use of this command.)
+
+Here's a mistake that I often find myself making: committing a change
+in which I've created a new file, but forgotten to \hgcmd{add} it.
+\interaction{rollback.commit}
+Looking at the output of \hgcmd{status} after the commit immediately
+confirms the error.
+\interaction{rollback.status}
+The commit captured the changes to the file \filename{a}, but not the
+new file \filename{b}.  If I were to push this changeset to a
+repository that I shared with a colleague, the chances are high that
+something in \filename{a} would refer to \filename{b}, which would not
+be present in their repository when they pulled my changes.  I would
+thus become the object of some indignation.
+
+However, luck is with me---I've caught my error before I pushed the
+changeset.  I use the \hgcmd{rollback} command, and Mercurial makes
+that last changeset vanish.
+\interaction{rollback.rollback}
+Notice that the changeset is no longer present in the repository's
+history, and the working directory once again thinks that the file
+\filename{a} is modified.  The commit and rollback have left the
+working directory exactly as it was prior to the commit; the changeset
+has been completely erased.  I can now safely \hgcmd{add} the file
+\filename{b}, and rerun my commit.
+\interaction{rollback.add}
+
+\subsection{The erroneous pull}
+
+It's common practice with Mercurial to maintain separate development
+branches of a project in different repositories.  Your development
+team might have one shared repository for your project's ``0.9''
+release, and another, containing different changes, for the ``1.0''
+release.
+
+Given this, you can imagine that the consequences could be messy if
+you had a local ``0.9'' repository, and accidentally pulled changes
+from the shared ``1.0'' repository into it.  At worst, you could be
+paying insufficient attention, and push those changes into the shared
+``0.9'' tree, confusing your entire team (but don't worry, we'll
+return to this horror scenario later).  However, it's more likely that
+you'll notice immediately, because Mercurial will display the URL it's
+pulling from, or you will see it pull a suspiciously large number of
+changes into the repository.
+
+The \hgcmd{rollback} command will work nicely to expunge all of the
+changesets that you just pulled.  Mercurial groups all changes from
+one \hgcmd{pull} into a single transaction, so one \hgcmd{rollback} is
+all you need to undo this mistake.
+
+\subsection{Rolling back is useless once you've pushed}
+\label{sec:undo:rollback-after-push}
+
+The value of the \hgcmd{rollback} command drops to zero once you've
+pushed your changes to another repository.  Rolling back a change
+makes it disappear entirely, but \emph{only} in the repository in
+which you perform the \hgcmd{rollback}.  Because a rollback eliminates
+history, there's no way for the disappearance of a change to propagate
+between repositories.
+
+If you've pushed a change to another repository---particularly if it's
+a shared repository---it has essentially ``escaped into the wild,''
+and you'll have to recover from your mistake in a different way.  What
+will happen if you push a changeset somewhere, then roll it back, then
+pull from the repository you pushed to, is that the changeset will
+reappear in your repository.
+
+(If you absolutely know for sure that the change you want to roll back
+is the most recent change in the repository that you pushed to,
+\emph{and} you know that nobody else could have pulled it from that
+repository, you can roll back the changeset there, too, but you really
+should really not rely on this working reliably.  If you do this,
+sooner or later a change really will make it into a repository that
+you don't directly control (or have forgotten about), and come back to
+bite you.)
+
+\subsection{You can only roll back once}
+
+Mercurial stores exactly one transaction in its transaction log; that
+transaction is the most recent one that occurred in the repository.
+This means that you can only roll back one transaction.  If you expect
+to be able to roll back one transaction, then its predecessor, this is
+not the behaviour you will get.
+\interaction{rollback.twice}
+Once you've rolled back one transaction in a repository, you can't
+roll back again in that repository until you perform another commit or
+pull.
+
+\section{Reverting the mistaken change}
+
+If you make a modification to a file, and decide that you really
+didn't want to change the file at all, and you haven't yet committed
+your changes, the \hgcmd{revert} command is the one you'll need.  It
+looks at the changeset that's the parent of the working directory, and
+restores the contents of the file to their state as of that changeset.
+(That's a long-winded way of saying that, in the normal case, it
+undoes your modifications.)
+
+Let's illustrate how the \hgcmd{revert} command works with yet another
+small example.  We'll begin by modifying a file that Mercurial is
+already tracking.
+\interaction{daily.revert.modify}
+If we don't want that change, we can simply \hgcmd{revert} the file.
+\interaction{daily.revert.unmodify}
+The \hgcmd{revert} command provides us with an extra degree of safety
+by saving our modified file with a \filename{.orig} extension.
+\interaction{daily.revert.status}
+
+Here is a summary of the cases that the \hgcmd{revert} command can
+deal with.  We will describe each of these in more detail in the
+section that follows.
+\begin{itemize}
+\item If you modify a file, it will restore the file to its unmodified
+  state.
+\item If you \hgcmd{add} a file, it will undo the ``added'' state of
+  the file, but leave the file itself untouched.
+\item If you delete a file without telling Mercurial, it will restore
+  the file to its unmodified contents.
+\item If you use the \hgcmd{remove} command to remove a file, it will
+  undo the ``removed'' state of the file, and restore the file to its
+  unmodified contents.
+\end{itemize}
+
+\subsection{File management errors}
+\label{sec:undo:mgmt}
+
+The \hgcmd{revert} command is useful for more than just modified
+files.  It lets you reverse the results of all of Mercurial's file
+management commands---\hgcmd{add}, \hgcmd{remove}, and so on.
+
+If you \hgcmd{add} a file, then decide that in fact you don't want
+Mercurial to track it, use \hgcmd{revert} to undo the add.  Don't
+worry; Mercurial will not modify the file in any way.  It will just
+``unmark'' the file.
+\interaction{daily.revert.add}
+
+Similarly, if you ask Mercurial to \hgcmd{remove} a file, you can use
+\hgcmd{revert} to restore it to the contents it had as of the parent
+of the working directory.
+\interaction{daily.revert.remove}
+This works just as well for a file that you deleted by hand, without
+telling Mercurial (recall that in Mercurial terminology, this kind of
+file is called ``missing'').
+\interaction{daily.revert.missing}
+
+If you revert a \hgcmd{copy}, the copied-to file remains in your
+working directory afterwards, untracked.  Since a copy doesn't affect
+the copied-from file in any way, Mercurial doesn't do anything with
+the copied-from file.
+\interaction{daily.revert.copy}
+
+\subsubsection{A slightly special case: reverting a rename}
+
+If you \hgcmd{rename} a file, there is one small detail that
+you should remember.  When you \hgcmd{revert} a rename, it's not
+enough to provide the name of the renamed-to file, as you can see
+here.
+\interaction{daily.revert.rename}
+As you can see from the output of \hgcmd{status}, the renamed-to file
+is no longer identified as added, but the renamed-\emph{from} file is
+still removed!  This is counter-intuitive (at least to me), but at
+least it's easy to deal with.
+\interaction{daily.revert.rename-orig}
+So remember, to revert a \hgcmd{rename}, you must provide \emph{both}
+the source and destination names.
+
+% TODO: the output doesn't look like it will be removed!
+
+(By the way, if you rename a file, then modify the renamed-to file,
+then revert both components of the rename, when Mercurial restores the
+file that was removed as part of the rename, it will be unmodified.
+If you need the modifications in the renamed-to file to show up in the
+renamed-from file, don't forget to copy them over.)
+
+These fiddly aspects of reverting a rename arguably constitute a small
+bug in Mercurial.
+
+\section{Dealing with committed changes}
+
+Consider a case where you have committed a change $a$, and another
+change $b$ on top of it; you then realise that change $a$ was
+incorrect.  Mercurial lets you ``back out'' an entire changeset
+automatically, and building blocks that let you reverse part of a
+changeset by hand.
+
+Before you read this section, here's something to keep in mind: the
+\hgcmd{backout} command undoes changes by \emph{adding} history, not
+by modifying or erasing it.  It's the right tool to use if you're
+fixing bugs, but not if you're trying to undo some change that has
+catastrophic consequences.  To deal with those, see
+section~\ref{sec:undo:aaaiiieee}.
+
+\subsection{Backing out a changeset}
+
+The \hgcmd{backout} command lets you ``undo'' the effects of an entire
+changeset in an automated fashion.  Because Mercurial's history is
+immutable, this command \emph{does not} get rid of the changeset you
+want to undo.  Instead, it creates a new changeset that
+\emph{reverses} the effect of the to-be-undone changeset.
+
+The operation of the \hgcmd{backout} command is a little intricate, so
+let's illustrate it with some examples.  First, we'll create a
+repository with some simple changes.
+\interaction{backout.init}
+
+The \hgcmd{backout} command takes a single changeset ID as its
+argument; this is the changeset to back out.  Normally,
+\hgcmd{backout} will drop you into a text editor to write a commit
+message, so you can record why you're backing the change out.  In this
+example, we provide a commit message on the command line using the
+\hgopt{backout}{-m} option.
+
+\subsection{Backing out the tip changeset}
+
+We're going to start by backing out the last changeset we committed.
+\interaction{backout.simple}
+You can see that the second line from \filename{myfile} is no longer
+present.  Taking a look at the output of \hgcmd{log} gives us an idea
+of what the \hgcmd{backout} command has done.
+\interaction{backout.simple.log}
+Notice that the new changeset that \hgcmd{backout} has created is a
+child of the changeset we backed out.  It's easier to see this in
+figure~\ref{fig:undo:backout}, which presents a graphical view of the
+change history.  As you can see, the history is nice and linear.
+
+\begin{figure}[htb]
+  \centering
+  \grafix{undo-simple}
+  \caption{Backing out a change using the \hgcmd{backout} command}
+  \label{fig:undo:backout}
+\end{figure}
+
+\subsection{Backing out a non-tip change}
+
+If you want to back out a change other than the last one you
+committed, pass the \hgopt{backout}{--merge} option to the
+\hgcmd{backout} command.
+\interaction{backout.non-tip.clone}
+This makes backing out any changeset a ``one-shot'' operation that's
+usually simple and fast.
+\interaction{backout.non-tip.backout}
+
+If you take a look at the contents of \filename{myfile} after the
+backout finishes, you'll see that the first and third changes are
+present, but not the second.
+\interaction{backout.non-tip.cat}
+
+As the graphical history in figure~\ref{fig:undo:backout-non-tip}
+illustrates, Mercurial actually commits \emph{two} changes in this
+kind of situation (the box-shaped nodes are the ones that Mercurial
+commits automatically).  Before Mercurial begins the backout process,
+it first remembers what the current parent of the working directory
+is.  It then backs out the target changeset, and commits that as a
+changeset.  Finally, it merges back to the previous parent of the
+working directory, and commits the result of the merge.
+
+% TODO: to me it looks like mercurial doesn't commit the second merge automatically!
+
+\begin{figure}[htb]
+  \centering
+  \grafix{undo-non-tip}
+  \caption{Automated backout of a non-tip change using the \hgcmd{backout} command}
+  \label{fig:undo:backout-non-tip}
+\end{figure}
+
+The result is that you end up ``back where you were'', only with some
+extra history that undoes the effect of the changeset you wanted to
+back out.
+
+\subsubsection{Always use the \hgopt{backout}{--merge} option}
+
+In fact, since the \hgopt{backout}{--merge} option will do the ``right
+thing'' whether or not the changeset you're backing out is the tip
+(i.e.~it won't try to merge if it's backing out the tip, since there's
+no need), you should \emph{always} use this option when you run the
+\hgcmd{backout} command.
+
+\subsection{Gaining more control of the backout process}
+
+While I've recommended that you always use the
+\hgopt{backout}{--merge} option when backing out a change, the
+\hgcmd{backout} command lets you decide how to merge a backout
+changeset.  Taking control of the backout process by hand is something
+you will rarely need to do, but it can be useful to understand what
+the \hgcmd{backout} command is doing for you automatically.  To
+illustrate this, let's clone our first repository, but omit the
+backout change that it contains.
+
+\interaction{backout.manual.clone}
+As with our earlier example, We'll commit a third changeset, then back
+out its parent, and see what happens.
+\interaction{backout.manual.backout}
+Our new changeset is again a descendant of the changeset we backout
+out; it's thus a new head, \emph{not} a descendant of the changeset
+that was the tip.  The \hgcmd{backout} command was quite explicit in
+telling us this.
+\interaction{backout.manual.log}
+
+Again, it's easier to see what has happened by looking at a graph of
+the revision history, in figure~\ref{fig:undo:backout-manual}.  This
+makes it clear that when we use \hgcmd{backout} to back out a change
+other than the tip, Mercurial adds a new head to the repository (the
+change it committed is box-shaped).
+
+\begin{figure}[htb]
+  \centering
+  \grafix{undo-manual}
+  \caption{Backing out a change using the \hgcmd{backout} command}
+  \label{fig:undo:backout-manual}
+\end{figure}
+
+After the \hgcmd{backout} command has completed, it leaves the new
+``backout'' changeset as the parent of the working directory.
+\interaction{backout.manual.parents}
+Now we have two isolated sets of changes.
+\interaction{backout.manual.heads}
+
+Let's think about what we expect to see as the contents of
+\filename{myfile} now.  The first change should be present, because
+we've never backed it out.  The second change should be missing, as
+that's the change we backed out.  Since the history graph shows the
+third change as a separate head, we \emph{don't} expect to see the
+third change present in \filename{myfile}.
+\interaction{backout.manual.cat}
+To get the third change back into the file, we just do a normal merge
+of our two heads.
+\interaction{backout.manual.merge}
+Afterwards, the graphical history of our repository looks like
+figure~\ref{fig:undo:backout-manual-merge}.
+
+\begin{figure}[htb]
+  \centering
+  \grafix{undo-manual-merge}
+  \caption{Manually merging a backout change}
+  \label{fig:undo:backout-manual-merge}
+\end{figure}
+
+\subsection{Why \hgcmd{backout} works as it does}
+
+Here's a brief description of how the \hgcmd{backout} command works.
+\begin{enumerate}
+\item It ensures that the working directory is ``clean'', i.e.~that
+  the output of \hgcmd{status} would be empty.
+\item It remembers the current parent of the working directory.  Let's
+  call this changeset \texttt{orig}
+\item It does the equivalent of a \hgcmd{update} to sync the working
+  directory to the changeset you want to back out.  Let's call this
+  changeset \texttt{backout}
+\item It finds the parent of that changeset.  Let's call that
+  changeset \texttt{parent}.
+\item For each file that the \texttt{backout} changeset affected, it
+  does the equivalent of a \hgcmdargs{revert}{-r parent} on that file,
+  to restore it to the contents it had before that changeset was
+  committed.
+\item It commits the result as a new changeset.  This changeset has
+  \texttt{backout} as its parent.
+\item If you specify \hgopt{backout}{--merge} on the command line, it
+  merges with \texttt{orig}, and commits the result of the merge.
+\end{enumerate}
+
+An alternative way to implement the \hgcmd{backout} command would be
+to \hgcmd{export} the to-be-backed-out changeset as a diff, then use
+the \cmdopt{patch}{--reverse} option to the \command{patch} command to
+reverse the effect of the change without fiddling with the working
+directory.  This sounds much simpler, but it would not work nearly as
+well.
+
+The reason that \hgcmd{backout} does an update, a commit, a merge, and
+another commit is to give the merge machinery the best chance to do a
+good job when dealing with all the changes \emph{between} the change
+you're backing out and the current tip.
+
+If you're backing out a changeset that's~100 revisions back in your
+project's history, the chances that the \command{patch} command will
+be able to apply a reverse diff cleanly are not good, because
+intervening changes are likely to have ``broken the context'' that
+\command{patch} uses to determine whether it can apply a patch (if
+this sounds like gibberish, see \ref{sec:mq:patch} for a
+discussion of the \command{patch} command).  Also, Mercurial's merge
+machinery will handle files and directories being renamed, permission
+changes, and modifications to binary files, none of which
+\command{patch} can deal with.
+
+\section{Changes that should never have been}
+\label{sec:undo:aaaiiieee}
+
+Most of the time, the \hgcmd{backout} command is exactly what you need
+if you want to undo the effects of a change.  It leaves a permanent
+record of exactly what you did, both when committing the original
+changeset and when you cleaned up after it.
+
+On rare occasions, though, you may find that you've committed a change
+that really should not be present in the repository at all.  For
+example, it would be very unusual, and usually considered a mistake,
+to commit a software project's object files as well as its source
+files.  Object files have almost no intrinsic value, and they're
+\emph{big}, so they increase the size of the repository and the amount
+of time it takes to clone or pull changes.
+
+Before I discuss the options that you have if you commit a ``brown
+paper bag'' change (the kind that's so bad that you want to pull a
+brown paper bag over your head), let me first discuss some approaches
+that probably won't work.
+
+Since Mercurial treats history as accumulative---every change builds
+on top of all changes that preceded it---you generally can't just make
+disastrous changes disappear.  The one exception is when you've just
+committed a change, and it hasn't been pushed or pulled into another
+repository.  That's when you can safely use the \hgcmd{rollback}
+command, as I detailed in section~\ref{sec:undo:rollback}.
+
+After you've pushed a bad change to another repository, you
+\emph{could} still use \hgcmd{rollback} to make your local copy of the
+change disappear, but it won't have the consequences you want.  The
+change will still be present in the remote repository, so it will
+reappear in your local repository the next time you pull.
+
+If a situation like this arises, and you know which repositories your
+bad change has propagated into, you can \emph{try} to get rid of the
+changeefrom \emph{every} one of those repositories.  This is, of
+course, not a satisfactory solution: if you miss even a single
+repository while you're expunging, the change is still ``in the
+wild'', and could propagate further.
+
+If you've committed one or more changes \emph{after} the change that
+you'd like to see disappear, your options are further reduced.
+Mercurial doesn't provide a way to ``punch a hole'' in history,
+leaving changesets intact.
+
+XXX This needs filling out.  The \texttt{hg-replay} script in the
+\texttt{examples} directory works, but doesn't handle merge
+changesets.  Kind of an important omission.
+
+\subsection{Protect yourself from ``escaped'' changes}
+
+If you've committed some changes to your local repository and they've
+been pushed or pulled somewhere else, this isn't necessarily a
+disaster.  You can protect yourself ahead of time against some classes
+of bad changeset.  This is particularly easy if your team usually
+pulls changes from a central repository.
+
+By configuring some hooks on that repository to validate incoming
+changesets (see chapter~\ref{chap:hook}), you can automatically
+prevent some kinds of bad changeset from being pushed to the central
+repository at all.  With such a configuration in place, some kinds of
+bad changeset will naturally tend to ``die out'' because they can't
+propagate into the central repository.  Better yet, this happens
+without any need for explicit intervention.
+
+For instance, an incoming change hook that verifies that a changeset
+will actually compile can prevent people from inadvertantly ``breaking
+the build''.
+
+\section{Finding the source of a bug}
+\label{sec:undo:bisect}
+
+While it's all very well to be able to back out a changeset that
+introduced a bug, this requires that you know which changeset to back
+out.  Mercurial provides an invaluable command, called
+\hgcmd{bisect}, that helps you to automate this process and accomplish
+it very efficiently.
+
+The idea behind the \hgcmd{bisect} command is that a changeset has
+introduced some change of behaviour that you can identify with a
+simple binary test.  You don't know which piece of code introduced the
+change, but you know how to test for the presence of the bug.  The
+\hgcmd{bisect} command uses your test to direct its search for the
+changeset that introduced the code that caused the bug.
+
+Here are a few scenarios to help you understand how you might apply
+this command.
+\begin{itemize}
+\item The most recent version of your software has a bug that you
+  remember wasn't present a few weeks ago, but you don't know when it
+  was introduced.  Here, your binary test checks for the presence of
+  that bug.
+\item You fixed a bug in a rush, and now it's time to close the entry
+  in your team's bug database.  The bug database requires a changeset
+  ID when you close an entry, but you don't remember which changeset
+  you fixed the bug in.  Once again, your binary test checks for the
+  presence of the bug.
+\item Your software works correctly, but runs~15\% slower than the
+  last time you measured it.  You want to know which changeset
+  introduced the performance regression.  In this case, your binary
+  test measures the performance of your software, to see whether it's
+  ``fast'' or ``slow''.
+\item The sizes of the components of your project that you ship
+  exploded recently, and you suspect that something changed in the way
+  you build your project.
+\end{itemize}
+
+From these examples, it should be clear that the \hgcmd{bisect}
+command is not useful only for finding the sources of bugs.  You can
+use it to find any ``emergent property'' of a repository (anything
+that you can't find from a simple text search of the files in the
+tree) for which you can write a binary test.
+
+We'll introduce a little bit of terminology here, just to make it
+clear which parts of the search process are your responsibility, and
+which are Mercurial's.  A \emph{test} is something that \emph{you} run
+when \hgcmd{bisect} chooses a changeset.  A \emph{probe} is what
+\hgcmd{bisect} runs to tell whether a revision is good.  Finally,
+we'll use the word ``bisect'', as both a noun and a verb, to stand in
+for the phrase ``search using the \hgcmd{bisect} command.
+
+One simple way to automate the searching process would be simply to
+probe every changeset.  However, this scales poorly.  If it took ten
+minutes to test a single changeset, and you had 10,000 changesets in
+your repository, the exhaustive approach would take on average~35
+\emph{days} to find the changeset that introduced a bug.  Even if you
+knew that the bug was introduced by one of the last 500 changesets,
+and limited your search to those, you'd still be looking at over 40
+hours to find the changeset that introduced your bug.
+
+What the \hgcmd{bisect} command does is use its knowledge of the
+``shape'' of your project's revision history to perform a search in
+time proportional to the \emph{logarithm} of the number of changesets
+to check (the kind of search it performs is called a dichotomic
+search).  With this approach, searching through 10,000 changesets will
+take less than three hours, even at ten minutes per test (the search
+will require about 14 tests).  Limit your search to the last hundred
+changesets, and it will take only about an hour (roughly seven tests).
+
+The \hgcmd{bisect} command is aware of the ``branchy'' nature of a
+Mercurial project's revision history, so it has no problems dealing
+with branches, merges, or multiple heads in a repoository.  It can
+prune entire branches of history with a single probe, which is how it
+operates so efficiently.
+
+\subsection{Using the \hgcmd{bisect} command}
+
+Here's an example of \hgcmd{bisect} in action.
+
+\begin{note}
+  In versions 0.9.5 and earlier of Mercurial, \hgcmd{bisect} was not a
+  core command: it was distributed with Mercurial as an extension.
+  This section describes the built-in command, not the old extension.
+\end{note}
+
+Now let's create a repository, so that we can try out the
+\hgcmd{bisect} command in isolation.
+\interaction{bisect.init}
+We'll simulate a project that has a bug in it in a simple-minded way:
+create trivial changes in a loop, and nominate one specific change
+that will have the ``bug''.  This loop creates 35 changesets, each
+adding a single file to the repository.  We'll represent our ``bug''
+with a file that contains the text ``i have a gub''.
+\interaction{bisect.commits}
+
+The next thing that we'd like to do is figure out how to use the
+\hgcmd{bisect} command.  We can use Mercurial's normal built-in help
+mechanism for this.
+\interaction{bisect.help}
+
+The \hgcmd{bisect} command works in steps.  Each step proceeds as follows.
+\begin{enumerate}
+\item You run your binary test.
+  \begin{itemize}
+  \item If the test succeeded, you tell \hgcmd{bisect} by running the
+    \hgcmdargs{bisect}{good} command.
+  \item If it failed, run the \hgcmdargs{bisect}{--bad} command.
+  \end{itemize}
+\item The command uses your information to decide which changeset to
+  test next.
+\item It updates the working directory to that changeset, and the
+  process begins again.
+\end{enumerate}
+The process ends when \hgcmd{bisect} identifies a unique changeset
+that marks the point where your test transitioned from ``succeeding''
+to ``failing''.
+
+To start the search, we must run the \hgcmdargs{bisect}{--reset} command.
+\interaction{bisect.search.init}
+
+In our case, the binary test we use is simple: we check to see if any
+file in the repository contains the string ``i have a gub''.  If it
+does, this changeset contains the change that ``caused the bug''.  By
+convention, a changeset that has the property we're searching for is
+``bad'', while one that doesn't is ``good''.
+
+Most of the time, the revision to which the working directory is
+synced (usually the tip) already exhibits the problem introduced by
+the buggy change, so we'll mark it as ``bad''.
+\interaction{bisect.search.bad-init}
+
+Our next task is to nominate a changeset that we know \emph{doesn't}
+have the bug; the \hgcmd{bisect} command will ``bracket'' its search
+between the first pair of good and bad changesets.  In our case, we
+know that revision~10 didn't have the bug.  (I'll have more words
+about choosing the first ``good'' changeset later.)
+\interaction{bisect.search.good-init}
+
+Notice that this command printed some output.
+\begin{itemize}
+\item It told us how many changesets it must consider before it can
+  identify the one that introduced the bug, and how many tests that
+  will require.
+\item It updated the working directory to the next changeset to test,
+  and told us which changeset it's testing.
+\end{itemize}
+
+We now run our test in the working directory.  We use the
+\command{grep} command to see if our ``bad'' file is present in the
+working directory.  If it is, this revision is bad; if not, this
+revision is good.
+\interaction{bisect.search.step1}
+
+This test looks like a perfect candidate for automation, so let's turn
+it into a shell function.
+\interaction{bisect.search.mytest}
+We can now run an entire test step with a single command,
+\texttt{mytest}.
+\interaction{bisect.search.step2}
+A few more invocations of our canned test step command, and we're
+done.
+\interaction{bisect.search.rest}
+
+Even though we had~40 changesets to search through, the \hgcmd{bisect}
+command let us find the changeset that introduced our ``bug'' with
+only five tests.  Because the number of tests that the \hgcmd{bisect}
+command performs grows logarithmically with the number of changesets to
+search, the advantage that it has over the ``brute force'' search
+approach increases with every changeset you add.
+
+\subsection{Cleaning up after your search}
+
+When you're finished using the \hgcmd{bisect} command in a
+repository, you can use the \hgcmdargs{bisect}{reset} command to drop
+the information it was using to drive your search.  The command
+doesn't use much space, so it doesn't matter if you forget to run this
+command.  However, \hgcmd{bisect} won't let you start a new search in
+that repository until you do a \hgcmdargs{bisect}{reset}.
+\interaction{bisect.search.reset}
+
+\section{Tips for finding bugs effectively}
+
+\subsection{Give consistent input}
+
+The \hgcmd{bisect} command requires that you correctly report the
+result of every test you perform.  If you tell it that a test failed
+when it really succeeded, it \emph{might} be able to detect the
+inconsistency.  If it can identify an inconsistency in your reports,
+it will tell you that a particular changeset is both good and bad.
+However, it can't do this perfectly; it's about as likely to report
+the wrong changeset as the source of the bug.
+
+\subsection{Automate as much as possible}
+
+When I started using the \hgcmd{bisect} command, I tried a few times
+to run my tests by hand, on the command line.  This is an approach
+that I, at least, am not suited to.  After a few tries, I found that I
+was making enough mistakes that I was having to restart my searches
+several times before finally getting correct results.
+
+My initial problems with driving the \hgcmd{bisect} command by hand
+occurred even with simple searches on small repositories; if the
+problem you're looking for is more subtle, or the number of tests that
+\hgcmd{bisect} must perform increases, the likelihood of operator
+error ruining the search is much higher.  Once I started automating my
+tests, I had much better results.
+
+The key to automated testing is twofold:
+\begin{itemize}
+\item always test for the same symptom, and
+\item always feed consistent input to the \hgcmd{bisect} command.
+\end{itemize}
+In my tutorial example above, the \command{grep} command tests for the
+symptom, and the \texttt{if} statement takes the result of this check
+and ensures that we always feed the same input to the \hgcmd{bisect}
+command.  The \texttt{mytest} function marries these together in a
+reproducible way, so that every test is uniform and consistent.
+
+\subsection{Check your results}
+
+Because the output of a \hgcmd{bisect} search is only as good as the
+input you give it, don't take the changeset it reports as the
+absolute truth.  A simple way to cross-check its report is to manually
+run your test at each of the following changesets:
+\begin{itemize}
+\item The changeset that it reports as the first bad revision.  Your
+  test should still report this as bad.
+\item The parent of that changeset (either parent, if it's a merge).
+  Your test should report this changeset as good.
+\item A child of that changeset.  Your test should report this
+  changeset as bad.
+\end{itemize}
+
+\subsection{Beware interference between bugs}
+
+It's possible that your search for one bug could be disrupted by the
+presence of another.  For example, let's say your software crashes at
+revision 100, and worked correctly at revision 50.  Unknown to you,
+someone else introduced a different crashing bug at revision 60, and
+fixed it at revision 80.  This could distort your results in one of
+several ways.
+
+It is possible that this other bug completely ``masks'' yours, which
+is to say that it occurs before your bug has a chance to manifest
+itself.  If you can't avoid that other bug (for example, it prevents
+your project from building), and so can't tell whether your bug is
+present in a particular changeset, the \hgcmd{bisect} command cannot
+help you directly.  Instead, you can mark a changeset as untested by
+running \hgcmdargs{bisect}{--skip}.
+
+A different problem could arise if your test for a bug's presence is
+not specific enough.  If you check for ``my program crashes'', then
+both your crashing bug and an unrelated crashing bug that masks it
+will look like the same thing, and mislead \hgcmd{bisect}.
+
+Another useful situation in which to use \hgcmdargs{bisect}{--skip} is
+if you can't test a revision because your project was in a broken and
+hence untestable state at that revision, perhaps because someone
+checked in a change that prevented the project from building.
+
+\subsection{Bracket your search lazily}
+
+Choosing the first ``good'' and ``bad'' changesets that will mark the
+end points of your search is often easy, but it bears a little
+discussion nevertheless.  From the perspective of \hgcmd{bisect}, the
+``newest'' changeset is conventionally ``bad'', and the older
+changeset is ``good''.
+
+If you're having trouble remembering when a suitable ``good'' change
+was, so that you can tell \hgcmd{bisect}, you could do worse than
+testing changesets at random.  Just remember to eliminate contenders
+that can't possibly exhibit the bug (perhaps because the feature with
+the bug isn't present yet) and those where another problem masks the
+bug (as I discussed above).
+
+Even if you end up ``early'' by thousands of changesets or months of
+history, you will only add a handful of tests to the total number that
+\hgcmd{bisect} must perform, thanks to its logarithmic behaviour.
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "00book"
+%%% End: