1.1 --- a/en/00book.tex	Thu Jan 29 22:47:34 2009 -0800
     1.2 +++ b/en/00book.tex	Thu Jan 29 22:56:27 2009 -0800
     1.3 @@ -40,27 +40,27 @@
     1.4  
     1.5  \pagenumbering{arabic}
     1.6  
     1.7 -\include{preface}
     1.8 -\include{intro}
     1.9 -\include{tour-basic}
    1.10 -\include{tour-merge}
    1.11 -\include{concepts}
    1.12 -\include{daily}
    1.13 -\include{collab}
    1.14 -\include{filenames}
    1.15 -\include{branch}
    1.16 -\include{undo}
    1.17 -\include{hook}
    1.18 -\include{template}
    1.19 -\include{mq}
    1.20 -\include{mq-collab}
    1.21 -\include{hgext}
    1.22 +\include{ch00-preface}
    1.23 +\include{ch01-intro}
    1.24 +\include{ch02-tour-basic}
    1.25 +\include{ch03-tour-merge}
    1.26 +\include{ch04-concepts}
    1.27 +\include{ch05-daily}
    1.28 +\include{ch06-collab}
    1.29 +\include{ch07-filenames}
    1.30 +\include{ch08-branch}
    1.31 +\include{ch09-undo}
    1.32 +\include{ch10-hook}
    1.33 +\include{ch11-template}
    1.34 +\include{ch12-mq}
    1.35 +\include{ch13-mq-collab}
    1.36 +\include{ch14-hgext}
    1.37  
    1.38  \appendix
    1.39 -\include{cmdref}
    1.40 -\include{mq-ref}
    1.41 -\include{srcinstall}
    1.42 -\include{license}
    1.43 +\include{appA-cmdref}
    1.44 +\include{appB-mq-ref}
    1.45 +\include{appC-srcinstall}
    1.46 +\include{appD-license}
    1.47  \addcontentsline{toc}{chapter}{Bibliography}
    1.48  \bibliographystyle{alpha}
    1.49  \bibliography{99book}

     2.1 --- a/en/Makefile	Thu Jan 29 22:47:34 2009 -0800
     2.2 +++ b/en/Makefile	Thu Jan 29 22:56:27 2009 -0800
     2.3 @@ -4,26 +4,8 @@
     2.4  	00book.tex \
     2.5  	99book.bib \
     2.6  	99defs.tex \
     2.7 -	build_id.tex \
     2.8 -	branch.tex \
     2.9 -	cmdref.tex \
    2.10 -	collab.tex \
    2.11 -	concepts.tex \
    2.12 -	daily.tex \
    2.13 -	filenames.tex \
    2.14 -	hg_id.tex \
    2.15 -	hgext.tex \
    2.16 -	hook.tex \
    2.17 -	intro.tex \
    2.18 -	mq.tex \
    2.19 -	mq-collab.tex \
    2.20 -	mq-ref.tex \
    2.21 -	preface.tex \
    2.22 -	srcinstall.tex \
    2.23 -	template.tex \
    2.24 -	tour-basic.tex \
    2.25 -	tour-merge.tex \
    2.26 -	undo.tex
    2.27 +	app*.tex \
    2.28 +	ch*.tex
    2.29  
    2.30  image-sources := \
    2.31  	feature-branches.dot \

     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/en/appA-cmdref.tex	Thu Jan 29 22:56:27 2009 -0800
     3.3 @@ -0,0 +1,176 @@
     3.4 +\chapter{Command reference}
     3.5 +\label{cmdref}
     3.6 +
     3.7 +\cmdref{add}{add files at the next commit}
     3.8 +\optref{add}{I}{include}
     3.9 +\optref{add}{X}{exclude}
    3.10 +\optref{add}{n}{dry-run}
    3.11 +
    3.12 +\cmdref{diff}{print changes in history or working directory}
    3.13 +
    3.14 +Show differences between revisions for the specified files or
    3.15 +directories, using the unified diff format.  For a description of the
    3.16 +unified diff format, see section~\ref{sec:mq:patch}.
    3.17 +
    3.18 +By default, this command does not print diffs for files that Mercurial
    3.19 +considers to contain binary data.  To control this behaviour, see the
    3.20 +\hgopt{diff}{-a} and \hgopt{diff}{--git} options.
    3.21 +
    3.22 +\subsection{Options}
    3.23 +
    3.24 +\loptref{diff}{nodates}
    3.25 +
    3.26 +Omit date and time information when printing diff headers.
    3.27 +
    3.28 +\optref{diff}{B}{ignore-blank-lines}
    3.29 +
    3.30 +Do not print changes that only insert or delete blank lines.  A line
    3.31 +that contains only whitespace is not considered blank.
    3.32 +
    3.33 +\optref{diff}{I}{include}
    3.34 +
    3.35 +Include files and directories whose names match the given patterns.
    3.36 +
    3.37 +\optref{diff}{X}{exclude}
    3.38 +
    3.39 +Exclude files and directories whose names match the given patterns.
    3.40 +
    3.41 +\optref{diff}{a}{text}
    3.42 +
    3.43 +If this option is not specified, \hgcmd{diff} will refuse to print
    3.44 +diffs for files that it detects as binary. Specifying \hgopt{diff}{-a}
    3.45 +forces \hgcmd{diff} to treat all files as text, and generate diffs for
    3.46 +all of them.
    3.47 +
    3.48 +This option is useful for files that are ``mostly text'' but have a
    3.49 +few embedded NUL characters.  If you use it on files that contain a
    3.50 +lot of binary data, its output will be incomprehensible.
    3.51 +
    3.52 +\optref{diff}{b}{ignore-space-change}
    3.53 +
    3.54 +Do not print a line if the only change to that line is in the amount
    3.55 +of white space it contains.
    3.56 +
    3.57 +\optref{diff}{g}{git}
    3.58 +
    3.59 +Print \command{git}-compatible diffs.  XXX reference a format
    3.60 +description.
    3.61 +
    3.62 +\optref{diff}{p}{show-function}
    3.63 +
    3.64 +Display the name of the enclosing function in a hunk header, using a
    3.65 +simple heuristic.  This functionality is enabled by default, so the
    3.66 +\hgopt{diff}{-p} option has no effect unless you change the value of
    3.67 +the \rcitem{diff}{showfunc} config item, as in the following example.
    3.68 +\interaction{cmdref.diff-p}
    3.69 +
    3.70 +\optref{diff}{r}{rev}
    3.71 +
    3.72 +Specify one or more revisions to compare.  The \hgcmd{diff} command
    3.73 +accepts up to two \hgopt{diff}{-r} options to specify the revisions to
    3.74 +compare.
    3.75 +
    3.76 +\begin{enumerate}
    3.77 +\setcounter{enumi}{0}
    3.78 +\item Display the differences between the parent revision of the
    3.79 +  working directory and the working directory.
    3.80 +\item Display the differences between the specified changeset and the
    3.81 +  working directory.
    3.82 +\item Display the differences between the two specified changesets.
    3.83 +\end{enumerate}
    3.84 +
    3.85 +You can specify two revisions using either two \hgopt{diff}{-r}
    3.86 +options or revision range notation.  For example, the two revision
    3.87 +specifications below are equivalent.
    3.88 +\begin{codesample2}
    3.89 +  hg diff -r 10 -r 20
    3.90 +  hg diff -r10:20
    3.91 +\end{codesample2}
    3.92 +
    3.93 +When you provide two revisions, Mercurial treats the order of those
    3.94 +revisions as significant.  Thus, \hgcmdargs{diff}{-r10:20} will
    3.95 +produce a diff that will transform files from their contents as of
    3.96 +revision~10 to their contents as of revision~20, while
    3.97 +\hgcmdargs{diff}{-r20:10} means the opposite: the diff that will
    3.98 +transform files from their revision~20 contents to their revision~10
    3.99 +contents.  You cannot reverse the ordering in this way if you are
   3.100 +diffing against the working directory.
   3.101 +
   3.102 +\optref{diff}{w}{ignore-all-space}
   3.103 +
   3.104 +\cmdref{version}{print version and copyright information}
   3.105 +
   3.106 +This command displays the version of Mercurial you are running, and
   3.107 +its copyright license.  There are four kinds of version string that
   3.108 +you may see.
   3.109 +\begin{itemize}
   3.110 +\item The string ``\texttt{unknown}''. This version of Mercurial was
   3.111 +  not built in a Mercurial repository, and cannot determine its own
   3.112 +  version.
   3.113 +\item A short numeric string, such as ``\texttt{1.1}''. This is a
   3.114 +  build of a revision of Mercurial that was identified by a specific
   3.115 +  tag in the repository where it was built.  (This doesn't necessarily
   3.116 +  mean that you're running an official release; someone else could
   3.117 +  have added that tag to any revision in the repository where they
   3.118 +  built Mercurial.)
   3.119 +\item A hexadecimal string, such as ``\texttt{875489e31abe}''.  This
   3.120 +  is a build of the given revision of Mercurial.
   3.121 +\item A hexadecimal string followed by a date, such as
   3.122 +  ``\texttt{875489e31abe+20070205}''.  This is a build of the given
   3.123 +  revision of Mercurial, where the build repository contained some
   3.124 +  local changes that had not been committed.
   3.125 +\end{itemize}
   3.126 +
   3.127 +\subsection{Tips and tricks}
   3.128 +
   3.129 +\subsubsection{Why do the results of \hgcmd{diff} and \hgcmd{status}
   3.130 +  differ?}
   3.131 +\label{cmdref:diff-vs-status}
   3.132 +
   3.133 +When you run the \hgcmd{status} command, you'll see a list of files
   3.134 +that Mercurial will record changes for the next time you perform a
   3.135 +commit.  If you run the \hgcmd{diff} command, you may notice that it
   3.136 +prints diffs for only a \emph{subset} of the files that \hgcmd{status}
   3.137 +listed.  There are two possible reasons for this.
   3.138 +
   3.139 +The first is that \hgcmd{status} prints some kinds of modifications
   3.140 +that \hgcmd{diff} doesn't normally display.  The \hgcmd{diff} command
   3.141 +normally outputs unified diffs, which don't have the ability to
   3.142 +represent some changes that Mercurial can track.  Most notably,
   3.143 +traditional diffs can't represent a change in whether or not a file is
   3.144 +executable, but Mercurial records this information.
   3.145 +
   3.146 +If you use the \hgopt{diff}{--git} option to \hgcmd{diff}, it will
   3.147 +display \command{git}-compatible diffs that \emph{can} display this
   3.148 +extra information.
   3.149 +
   3.150 +The second possible reason that \hgcmd{diff} might be printing diffs
   3.151 +for a subset of the files displayed by \hgcmd{status} is that if you
   3.152 +invoke it without any arguments, \hgcmd{diff} prints diffs against the
   3.153 +first parent of the working directory.  If you have run \hgcmd{merge}
   3.154 +to merge two changesets, but you haven't yet committed the results of
   3.155 +the merge, your working directory has two parents (use \hgcmd{parents}
   3.156 +to see them).  While \hgcmd{status} prints modifications relative to
   3.157 +\emph{both} parents after an uncommitted merge, \hgcmd{diff} still
   3.158 +operates relative only to the first parent.  You can get it to print
   3.159 +diffs relative to the second parent by specifying that parent with the
   3.160 +\hgopt{diff}{-r} option.  There is no way to print diffs relative to
   3.161 +both parents.
   3.162 +
   3.163 +\subsubsection{Generating safe binary diffs}
   3.164 +
   3.165 +If you use the \hgopt{diff}{-a} option to force Mercurial to print
   3.166 +diffs of files that are either ``mostly text'' or contain lots of
   3.167 +binary data, those diffs cannot subsequently be applied by either
   3.168 +Mercurial's \hgcmd{import} command or the system's \command{patch}
   3.169 +command.  
   3.170 +
   3.171 +If you want to generate a diff of a binary file that is safe to use as
   3.172 +input for \hgcmd{import}, use the \hgcmd{diff}{--git} option when you
   3.173 +generate the patch.  The system \command{patch} command cannot handle
   3.174 +binary patches at all.
   3.175 +
   3.176 +%%% Local Variables: 
   3.177 +%%% mode: latex
   3.178 +%%% TeX-master: "00book"
   3.179 +%%% End: 

     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/en/appB-mq-ref.tex	Thu Jan 29 22:56:27 2009 -0800
     4.3 @@ -0,0 +1,349 @@
     4.4 +\chapter{Mercurial Queues reference}
     4.5 +\label{chap:mqref}
     4.6 +
     4.7 +\section{MQ command reference}
     4.8 +\label{sec:mqref:cmdref}
     4.9 +
    4.10 +For an overview of the commands provided by MQ, use the command
    4.11 +\hgcmdargs{help}{mq}.
    4.12 +
    4.13 +\subsection{\hgxcmd{mq}{qapplied}---print applied patches}
    4.14 +
    4.15 +The \hgxcmd{mq}{qapplied} command prints the current stack of applied
    4.16 +patches.  Patches are printed in oldest-to-newest order, so the last
    4.17 +patch in the list is the ``top'' patch.
    4.18 +
    4.19 +\subsection{\hgxcmd{mq}{qcommit}---commit changes in the queue repository}
    4.20 +
    4.21 +The \hgxcmd{mq}{qcommit} command commits any outstanding changes in the
    4.22 +\sdirname{.hg/patches} repository.  This command only works if the
    4.23 +\sdirname{.hg/patches} directory is a repository, i.e.~you created the
    4.24 +directory using \hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}} or ran
    4.25 +\hgcmd{init} in the directory after running \hgxcmd{mq}{qinit}.
    4.26 +
    4.27 +This command is shorthand for \hgcmdargs{commit}{--cwd .hg/patches}.
    4.28 +
    4.29 +\subsection{\hgxcmd{mq}{qdelete}---delete a patch from the
    4.30 +  \sfilename{series} file}
    4.31 +
    4.32 +The \hgxcmd{mq}{qdelete} command removes the entry for a patch from the
    4.33 +\sfilename{series} file in the \sdirname{.hg/patches} directory.  It
    4.34 +does not pop the patch if the patch is already applied.  By default,
    4.35 +it does not delete the patch file; use the \hgxopt{mq}{qdel}{-f} option to
    4.36 +do that.
    4.37 +
    4.38 +Options:
    4.39 +\begin{itemize}
    4.40 +\item[\hgxopt{mq}{qdel}{-f}] Delete the patch file.
    4.41 +\end{itemize}
    4.42 +
    4.43 +\subsection{\hgxcmd{mq}{qdiff}---print a diff of the topmost applied patch}
    4.44 +
    4.45 +The \hgxcmd{mq}{qdiff} command prints a diff of the topmost applied patch.
    4.46 +It is equivalent to \hgcmdargs{diff}{-r-2:-1}.
    4.47 +
    4.48 +\subsection{\hgxcmd{mq}{qfold}---merge (``fold'') several patches into one}
    4.49 +
    4.50 +The \hgxcmd{mq}{qfold} command merges multiple patches into the topmost
    4.51 +applied patch, so that the topmost applied patch makes the union of
    4.52 +all of the changes in the patches in question.
    4.53 +
    4.54 +The patches to fold must not be applied; \hgxcmd{mq}{qfold} will exit with
    4.55 +an error if any is.  The order in which patches are folded is
    4.56 +significant; \hgcmdargs{qfold}{a b} means ``apply the current topmost
    4.57 +patch, followed by \texttt{a}, followed by \texttt{b}''.
    4.58 +
    4.59 +The comments from the folded patches are appended to the comments of
    4.60 +the destination patch, with each block of comments separated by three
    4.61 +asterisk (``\texttt{*}'') characters.  Use the \hgxopt{mq}{qfold}{-e}
    4.62 +option to edit the commit message for the combined patch/changeset
    4.63 +after the folding has completed.
    4.64 +
    4.65 +Options:
    4.66 +\begin{itemize}
    4.67 +\item[\hgxopt{mq}{qfold}{-e}] Edit the commit message and patch description
    4.68 +  for the newly folded patch.
    4.69 +\item[\hgxopt{mq}{qfold}{-l}] Use the contents of the given file as the new
    4.70 +  commit message and patch description for the folded patch.
    4.71 +\item[\hgxopt{mq}{qfold}{-m}] Use the given text as the new commit message
    4.72 +  and patch description for the folded patch.
    4.73 +\end{itemize}
    4.74 +
    4.75 +\subsection{\hgxcmd{mq}{qheader}---display the header/description of a patch}
    4.76 +
    4.77 +The \hgxcmd{mq}{qheader} command prints the header, or description, of a
    4.78 +patch.  By default, it prints the header of the topmost applied patch.
    4.79 +Given an argument, it prints the header of the named patch.
    4.80 +
    4.81 +\subsection{\hgxcmd{mq}{qimport}---import a third-party patch into the queue}
    4.82 +
    4.83 +The \hgxcmd{mq}{qimport} command adds an entry for an external patch to the
    4.84 +\sfilename{series} file, and copies the patch into the
    4.85 +\sdirname{.hg/patches} directory.  It adds the entry immediately after
    4.86 +the topmost applied patch, but does not push the patch.
    4.87 +
    4.88 +If the \sdirname{.hg/patches} directory is a repository,
    4.89 +\hgxcmd{mq}{qimport} automatically does an \hgcmd{add} of the imported
    4.90 +patch.
    4.91 +
    4.92 +\subsection{\hgxcmd{mq}{qinit}---prepare a repository to work with MQ}
    4.93 +
    4.94 +The \hgxcmd{mq}{qinit} command prepares a repository to work with MQ.  It
    4.95 +creates a directory called \sdirname{.hg/patches}.
    4.96 +
    4.97 +Options:
    4.98 +\begin{itemize}
    4.99 +\item[\hgxopt{mq}{qinit}{-c}] Create \sdirname{.hg/patches} as a repository
   4.100 +  in its own right.  Also creates a \sfilename{.hgignore} file that
   4.101 +  will ignore the \sfilename{status} file.
   4.102 +\end{itemize}
   4.103 +
   4.104 +When the \sdirname{.hg/patches} directory is a repository, the
   4.105 +\hgxcmd{mq}{qimport} and \hgxcmd{mq}{qnew} commands automatically \hgcmd{add}
   4.106 +new patches.
   4.107 +
   4.108 +\subsection{\hgxcmd{mq}{qnew}---create a new patch}
   4.109 +
   4.110 +The \hgxcmd{mq}{qnew} command creates a new patch.  It takes one mandatory
   4.111 +argument, the name to use for the patch file.  The newly created patch
   4.112 +is created empty by default.  It is added to the \sfilename{series}
   4.113 +file after the current topmost applied patch, and is immediately
   4.114 +pushed on top of that patch.
   4.115 +
   4.116 +If \hgxcmd{mq}{qnew} finds modified files in the working directory, it will
   4.117 +refuse to create a new patch unless the \hgxopt{mq}{qnew}{-f} option is
   4.118 +used (see below).  This behaviour allows you to \hgxcmd{mq}{qrefresh} your
   4.119 +topmost applied patch before you apply a new patch on top of it.
   4.120 +
   4.121 +Options:
   4.122 +\begin{itemize}
   4.123 +\item[\hgxopt{mq}{qnew}{-f}] Create a new patch if the contents of the
   4.124 +  working directory are modified.  Any outstanding modifications are
   4.125 +  added to the newly created patch, so after this command completes,
   4.126 +  the working directory will no longer be modified.
   4.127 +\item[\hgxopt{mq}{qnew}{-m}] Use the given text as the commit message.
   4.128 +  This text will be stored at the beginning of the patch file, before
   4.129 +  the patch data.
   4.130 +\end{itemize}
   4.131 +
   4.132 +\subsection{\hgxcmd{mq}{qnext}---print the name of the next patch}
   4.133 +
   4.134 +The \hgxcmd{mq}{qnext} command prints the name name of the next patch in
   4.135 +the \sfilename{series} file after the topmost applied patch.  This
   4.136 +patch will become the topmost applied patch if you run \hgxcmd{mq}{qpush}.
   4.137 +
   4.138 +\subsection{\hgxcmd{mq}{qpop}---pop patches off the stack}
   4.139 +
   4.140 +The \hgxcmd{mq}{qpop} command removes applied patches from the top of the
   4.141 +stack of applied patches.  By default, it removes only one patch.
   4.142 +
   4.143 +This command removes the changesets that represent the popped patches
   4.144 +from the repository, and updates the working directory to undo the
   4.145 +effects of the patches.
   4.146 +
   4.147 +This command takes an optional argument, which it uses as the name or
   4.148 +index of the patch to pop to.  If given a name, it will pop patches
   4.149 +until the named patch is the topmost applied patch.  If given a
   4.150 +number, \hgxcmd{mq}{qpop} treats the number as an index into the entries in
   4.151 +the series file, counting from zero (empty lines and lines containing
   4.152 +only comments do not count).  It pops patches until the patch
   4.153 +identified by the given index is the topmost applied patch.
   4.154 +
   4.155 +The \hgxcmd{mq}{qpop} command does not read or write patches or the
   4.156 +\sfilename{series} file.  It is thus safe to \hgxcmd{mq}{qpop} a patch that
   4.157 +you have removed from the \sfilename{series} file, or a patch that you
   4.158 +have renamed or deleted entirely.  In the latter two cases, use the
   4.159 +name of the patch as it was when you applied it.
   4.160 +
   4.161 +By default, the \hgxcmd{mq}{qpop} command will not pop any patches if the
   4.162 +working directory has been modified.  You can override this behaviour
   4.163 +using the \hgxopt{mq}{qpop}{-f} option, which reverts all modifications in
   4.164 +the working directory.
   4.165 +
   4.166 +Options:
   4.167 +\begin{itemize}
   4.168 +\item[\hgxopt{mq}{qpop}{-a}] Pop all applied patches.  This returns the
   4.169 +  repository to its state before you applied any patches.
   4.170 +\item[\hgxopt{mq}{qpop}{-f}] Forcibly revert any modifications to the
   4.171 +  working directory when popping.
   4.172 +\item[\hgxopt{mq}{qpop}{-n}] Pop a patch from the named queue.
   4.173 +\end{itemize}
   4.174 +
   4.175 +The \hgxcmd{mq}{qpop} command removes one line from the end of the
   4.176 +\sfilename{status} file for each patch that it pops.
   4.177 +
   4.178 +\subsection{\hgxcmd{mq}{qprev}---print the name of the previous patch}
   4.179 +
   4.180 +The \hgxcmd{mq}{qprev} command prints the name of the patch in the
   4.181 +\sfilename{series} file that comes before the topmost applied patch.
   4.182 +This will become the topmost applied patch if you run \hgxcmd{mq}{qpop}.
   4.183 +
   4.184 +\subsection{\hgxcmd{mq}{qpush}---push patches onto the stack}
   4.185 +\label{sec:mqref:cmd:qpush}
   4.186 +
   4.187 +The \hgxcmd{mq}{qpush} command adds patches onto the applied stack.  By
   4.188 +default, it adds only one patch.
   4.189 +
   4.190 +This command creates a new changeset to represent each applied patch,
   4.191 +and updates the working directory to apply the effects of the patches.
   4.192 +
   4.193 +The default data used when creating a changeset are as follows:
   4.194 +\begin{itemize}
   4.195 +\item The commit date and time zone are the current date and time
   4.196 +  zone.  Because these data are used to compute the identity of a
   4.197 +  changeset, this means that if you \hgxcmd{mq}{qpop} a patch and
   4.198 +  \hgxcmd{mq}{qpush} it again, the changeset that you push will have a
   4.199 +  different identity than the changeset you popped.
   4.200 +\item The author is the same as the default used by the \hgcmd{commit}
   4.201 +  command.
   4.202 +\item The commit message is any text from the patch file that comes
   4.203 +  before the first diff header.  If there is no such text, a default
   4.204 +  commit message is used that identifies the name of the patch.
   4.205 +\end{itemize}
   4.206 +If a patch contains a Mercurial patch header (XXX add link), the
   4.207 +information in the patch header overrides these defaults.
   4.208 +
   4.209 +Options:
   4.210 +\begin{itemize}
   4.211 +\item[\hgxopt{mq}{qpush}{-a}] Push all unapplied patches from the
   4.212 +  \sfilename{series} file until there are none left to push.
   4.213 +\item[\hgxopt{mq}{qpush}{-l}] Add the name of the patch to the end
   4.214 +  of the commit message.
   4.215 +\item[\hgxopt{mq}{qpush}{-m}] If a patch fails to apply cleanly, use the
   4.216 +  entry for the patch in another saved queue to compute the parameters
   4.217 +  for a three-way merge, and perform a three-way merge using the
   4.218 +  normal Mercurial merge machinery.  Use the resolution of the merge
   4.219 +  as the new patch content.
   4.220 +\item[\hgxopt{mq}{qpush}{-n}] Use the named queue if merging while pushing.
   4.221 +\end{itemize}
   4.222 +
   4.223 +The \hgxcmd{mq}{qpush} command reads, but does not modify, the
   4.224 +\sfilename{series} file.  It appends one line to the \hgcmd{status}
   4.225 +file for each patch that it pushes.
   4.226 +
   4.227 +\subsection{\hgxcmd{mq}{qrefresh}---update the topmost applied patch}
   4.228 +
   4.229 +The \hgxcmd{mq}{qrefresh} command updates the topmost applied patch.  It
   4.230 +modifies the patch, removes the old changeset that represented the
   4.231 +patch, and creates a new changeset to represent the modified patch.
   4.232 +
   4.233 +The \hgxcmd{mq}{qrefresh} command looks for the following modifications:
   4.234 +\begin{itemize}
   4.235 +\item Changes to the commit message, i.e.~the text before the first
   4.236 +  diff header in the patch file, are reflected in the new changeset
   4.237 +  that represents the patch.
   4.238 +\item Modifications to tracked files in the working directory are
   4.239 +  added to the patch.
   4.240 +\item Changes to the files tracked using \hgcmd{add}, \hgcmd{copy},
   4.241 +  \hgcmd{remove}, or \hgcmd{rename}.  Added files and copy and rename
   4.242 +  destinations are added to the patch, while removed files and rename
   4.243 +  sources are removed.
   4.244 +\end{itemize}
   4.245 +
   4.246 +Even if \hgxcmd{mq}{qrefresh} detects no changes, it still recreates the
   4.247 +changeset that represents the patch.  This causes the identity of the
   4.248 +changeset to differ from the previous changeset that identified the
   4.249 +patch.
   4.250 +
   4.251 +Options:
   4.252 +\begin{itemize}
   4.253 +\item[\hgxopt{mq}{qrefresh}{-e}] Modify the commit and patch description,
   4.254 +  using the preferred text editor.
   4.255 +\item[\hgxopt{mq}{qrefresh}{-m}] Modify the commit message and patch
   4.256 +  description, using the given text.
   4.257 +\item[\hgxopt{mq}{qrefresh}{-l}] Modify the commit message and patch
   4.258 +  description, using text from the given file.
   4.259 +\end{itemize}
   4.260 +
   4.261 +\subsection{\hgxcmd{mq}{qrename}---rename a patch}
   4.262 +
   4.263 +The \hgxcmd{mq}{qrename} command renames a patch, and changes the entry for
   4.264 +the patch in the \sfilename{series} file.
   4.265 +
   4.266 +With a single argument, \hgxcmd{mq}{qrename} renames the topmost applied
   4.267 +patch.  With two arguments, it renames its first argument to its
   4.268 +second.
   4.269 +
   4.270 +\subsection{\hgxcmd{mq}{qrestore}---restore saved queue state}
   4.271 +
   4.272 +XXX No idea what this does.
   4.273 +
   4.274 +\subsection{\hgxcmd{mq}{qsave}---save current queue state}
   4.275 +
   4.276 +XXX Likewise.
   4.277 +
   4.278 +\subsection{\hgxcmd{mq}{qseries}---print the entire patch series}
   4.279 +
   4.280 +The \hgxcmd{mq}{qseries} command prints the entire patch series from the
   4.281 +\sfilename{series} file.  It prints only patch names, not empty lines
   4.282 +or comments.  It prints in order from first to be applied to last.
   4.283 +
   4.284 +\subsection{\hgxcmd{mq}{qtop}---print the name of the current patch}
   4.285 +
   4.286 +The \hgxcmd{mq}{qtop} prints the name of the topmost currently applied
   4.287 +patch.
   4.288 +
   4.289 +\subsection{\hgxcmd{mq}{qunapplied}---print patches not yet applied}
   4.290 +
   4.291 +The \hgxcmd{mq}{qunapplied} command prints the names of patches from the
   4.292 +\sfilename{series} file that are not yet applied.  It prints them in
   4.293 +order from the next patch that will be pushed to the last.
   4.294 +
   4.295 +\subsection{\hgcmd{strip}---remove a revision and descendants}
   4.296 +
   4.297 +The \hgcmd{strip} command removes a revision, and all of its
   4.298 +descendants, from the repository.  It undoes the effects of the
   4.299 +removed revisions from the repository, and updates the working
   4.300 +directory to the first parent of the removed revision.
   4.301 +
   4.302 +The \hgcmd{strip} command saves a backup of the removed changesets in
   4.303 +a bundle, so that they can be reapplied if removed in error.
   4.304 +
   4.305 +Options:
   4.306 +\begin{itemize}
   4.307 +\item[\hgopt{strip}{-b}] Save unrelated changesets that are intermixed
   4.308 +  with the stripped changesets in the backup bundle.
   4.309 +\item[\hgopt{strip}{-f}] If a branch has multiple heads, remove all
   4.310 +  heads. XXX This should be renamed, and use \texttt{-f} to strip revs
   4.311 +  when there are pending changes.
   4.312 +\item[\hgopt{strip}{-n}] Do not save a backup bundle.
   4.313 +\end{itemize}
   4.314 +
   4.315 +\section{MQ file reference}
   4.316 +
   4.317 +\subsection{The \sfilename{series} file}
   4.318 +
   4.319 +The \sfilename{series} file contains a list of the names of all
   4.320 +patches that MQ can apply.  It is represented as a list of names, with
   4.321 +one name saved per line.  Leading and trailing white space in each
   4.322 +line are ignored.
   4.323 +
   4.324 +Lines may contain comments.  A comment begins with the ``\texttt{\#}''
   4.325 +character, and extends to the end of the line.  Empty lines, and lines
   4.326 +that contain only comments, are ignored.
   4.327 +
   4.328 +You will often need to edit the \sfilename{series} file by hand, hence
   4.329 +the support for comments and empty lines noted above.  For example,
   4.330 +you can comment out a patch temporarily, and \hgxcmd{mq}{qpush} will skip
   4.331 +over that patch when applying patches.  You can also change the order
   4.332 +in which patches are applied by reordering their entries in the
   4.333 +\sfilename{series} file.
   4.334 +
   4.335 +Placing the \sfilename{series} file under revision control is also
   4.336 +supported; it is a good idea to place all of the patches that it
   4.337 +refers to under revision control, as well.  If you create a patch
   4.338 +directory using the \hgxopt{mq}{qinit}{-c} option to \hgxcmd{mq}{qinit}, this
   4.339 +will be done for you automatically.
   4.340 +
   4.341 +\subsection{The \sfilename{status} file}
   4.342 +
   4.343 +The \sfilename{status} file contains the names and changeset hashes of
   4.344 +all patches that MQ currently has applied.  Unlike the
   4.345 +\sfilename{series} file, this file is not intended for editing.  You
   4.346 +should not place this file under revision control, or modify it in any
   4.347 +way.  It is used by MQ strictly for internal book-keeping.
   4.348 +
   4.349 +%%% Local Variables: 
   4.350 +%%% mode: latex
   4.351 +%%% TeX-master: "00book"
   4.352 +%%% End: 

     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/en/appC-srcinstall.tex	Thu Jan 29 22:56:27 2009 -0800
     5.3 @@ -0,0 +1,53 @@
     5.4 +\chapter{Installing Mercurial from source}
     5.5 +\label{chap:srcinstall}
     5.6 +
     5.7 +\section{On a Unix-like system}
     5.8 +\label{sec:srcinstall:unixlike}
     5.9 +
    5.10 +If you are using a Unix-like system that has a sufficiently recent
    5.11 +version of Python (2.3~or newer) available, it is easy to install
    5.12 +Mercurial from source.
    5.13 +\begin{enumerate}
    5.14 +\item Download a recent source tarball from
    5.15 +  \url{http://www.selenic.com/mercurial/download}.
    5.16 +\item Unpack the tarball:
    5.17 +  \begin{codesample4}
    5.18 +    gzip -dc mercurial-\emph{version}.tar.gz | tar xf -
    5.19 +  \end{codesample4}
    5.20 +\item Go into the source directory and run the installer script.  This
    5.21 +  will build Mercurial and install it in your home directory.
    5.22 +  \begin{codesample4}
    5.23 +    cd mercurial-\emph{version}
    5.24 +    python setup.py install --force --home=\$HOME
    5.25 +  \end{codesample4}
    5.26 +\end{enumerate}
    5.27 +Once the install finishes, Mercurial will be in the \texttt{bin}
    5.28 +subdirectory of your home directory.  Don't forget to make sure that
    5.29 +this directory is present in your shell's search path.
    5.30 +
    5.31 +You will probably need to set the \envar{PYTHONPATH} environment
    5.32 +variable so that the Mercurial executable can find the rest of the
    5.33 +Mercurial packages.  For example, on my laptop, I have set it to
    5.34 +\texttt{/home/bos/lib/python}.  The exact path that you will need to
    5.35 +use depends on how Python was built for your system, but should be
    5.36 +easy to figure out.  If you're uncertain, look through the output of
    5.37 +the installer script above, and see where the contents of the
    5.38 +\texttt{mercurial} directory were installed to.
    5.39 +
    5.40 +\section{On Windows}
    5.41 +
    5.42 +Building and installing Mercurial on Windows requires a variety of
    5.43 +tools, a fair amount of technical knowledge, and considerable
    5.44 +patience.  I very much \emph{do not recommend} this route if you are a
    5.45 +``casual user''.  Unless you intend to hack on Mercurial, I strongly
    5.46 +suggest that you use a binary package instead.
    5.47 +
    5.48 +If you are intent on building Mercurial from source on Windows, follow
    5.49 +the ``hard way'' directions on the Mercurial wiki at
    5.50 +\url{http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall},
    5.51 +and expect the process to involve a lot of fiddly work.
    5.52 +
    5.53 +%%% Local Variables: 
    5.54 +%%% mode: latex
    5.55 +%%% TeX-master: "00book"
    5.56 +%%% End: 

     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/en/appD-license.tex	Thu Jan 29 22:56:27 2009 -0800
     6.3 @@ -0,0 +1,138 @@
     6.4 +\chapter{Open Publication License}
     6.5 +\label{cha:opl}
     6.6 +
     6.7 +Version 1.0, 8 June 1999
     6.8 +
     6.9 +\section{Requirements on both unmodified and modified versions}
    6.10 +
    6.11 +The Open Publication works may be reproduced and distributed in whole
    6.12 +or in part, in any medium physical or electronic, provided that the
    6.13 +terms of this license are adhered to, and that this license or an
    6.14 +incorporation of it by reference (with any options elected by the
    6.15 +author(s) and/or publisher) is displayed in the reproduction.
    6.16 +
    6.17 +Proper form for an incorporation by reference is as follows:
    6.18 +
    6.19 +\begin{quote}
    6.20 +  Copyright (c) \emph{year} by \emph{author's name or designee}. This
    6.21 +  material may be distributed only subject to the terms and conditions
    6.22 +  set forth in the Open Publication License, v\emph{x.y} or later (the
    6.23 +  latest version is presently available at
    6.24 +  \url{http://www.opencontent.org/openpub/}).
    6.25 +\end{quote}
    6.26 +
    6.27 +The reference must be immediately followed with any options elected by
    6.28 +the author(s) and/or publisher of the document (see
    6.29 +section~\ref{sec:opl:options}).
    6.30 +
    6.31 +Commercial redistribution of Open Publication-licensed material is
    6.32 +permitted.
    6.33 +
    6.34 +Any publication in standard (paper) book form shall require the
    6.35 +citation of the original publisher and author. The publisher and
    6.36 +author's names shall appear on all outer surfaces of the book. On all
    6.37 +outer surfaces of the book the original publisher's name shall be as
    6.38 +large as the title of the work and cited as possessive with respect to
    6.39 +the title.
    6.40 +
    6.41 +\section{Copyright}
    6.42 +
    6.43 +The copyright to each Open Publication is owned by its author(s) or
    6.44 +designee.
    6.45 +
    6.46 +\section{Scope of license}
    6.47 +
    6.48 +The following license terms apply to all Open Publication works,
    6.49 +unless otherwise explicitly stated in the document.
    6.50 +
    6.51 +Mere aggregation of Open Publication works or a portion of an Open
    6.52 +Publication work with other works or programs on the same media shall
    6.53 +not cause this license to apply to those other works. The aggregate
    6.54 +work shall contain a notice specifying the inclusion of the Open
    6.55 +Publication material and appropriate copyright notice.
    6.56 +
    6.57 +\textbf{Severability}. If any part of this license is found to be
    6.58 +unenforceable in any jurisdiction, the remaining portions of the
    6.59 +license remain in force.
    6.60 +
    6.61 +\textbf{No warranty}. Open Publication works are licensed and provided
    6.62 +``as is'' without warranty of any kind, express or implied, including,
    6.63 +but not limited to, the implied warranties of merchantability and
    6.64 +fitness for a particular purpose or a warranty of non-infringement.
    6.65 +
    6.66 +\section{Requirements on modified works}
    6.67 +
    6.68 +All modified versions of documents covered by this license, including
    6.69 +translations, anthologies, compilations and partial documents, must
    6.70 +meet the following requirements:
    6.71 +
    6.72 +\begin{enumerate}
    6.73 +\item The modified version must be labeled as such.
    6.74 +\item The person making the modifications must be identified and the
    6.75 +  modifications dated.
    6.76 +\item Acknowledgement of the original author and publisher if
    6.77 +  applicable must be retained according to normal academic citation
    6.78 +  practices.
    6.79 +\item The location of the original unmodified document must be
    6.80 +  identified.
    6.81 +\item The original author's (or authors') name(s) may not be used to
    6.82 +  assert or imply endorsement of the resulting document without the
    6.83 +  original author's (or authors') permission.
    6.84 +\end{enumerate}
    6.85 +
    6.86 +\section{Good-practice recommendations}
    6.87 +
    6.88 +In addition to the requirements of this license, it is requested from
    6.89 +and strongly recommended of redistributors that:
    6.90 +
    6.91 +\begin{enumerate}
    6.92 +\item If you are distributing Open Publication works on hardcopy or
    6.93 +  CD-ROM, you provide email notification to the authors of your intent
    6.94 +  to redistribute at least thirty days before your manuscript or media
    6.95 +  freeze, to give the authors time to provide updated documents. This
    6.96 +  notification should describe modifications, if any, made to the
    6.97 +  document.
    6.98 +\item All substantive modifications (including deletions) be either
    6.99 +  clearly marked up in the document or else described in an attachment
   6.100 +  to the document.
   6.101 +\item Finally, while it is not mandatory under this license, it is
   6.102 +  considered good form to offer a free copy of any hardcopy and CD-ROM
   6.103 +  expression of an Open Publication-licensed work to its author(s).
   6.104 +\end{enumerate}
   6.105 +
   6.106 +\section{License options}
   6.107 +\label{sec:opl:options}
   6.108 +
   6.109 +The author(s) and/or publisher of an Open Publication-licensed
   6.110 +document may elect certain options by appending language to the
   6.111 +reference to or copy of the license. These options are considered part
   6.112 +of the license instance and must be included with the license (or its
   6.113 +incorporation by reference) in derived works.
   6.114 +
   6.115 +\begin{enumerate}[A]
   6.116 +\item To prohibit distribution of substantively modified versions
   6.117 +  without the explicit permission of the author(s). ``Substantive
   6.118 +  modification'' is defined as a change to the semantic content of the
   6.119 +  document, and excludes mere changes in format or typographical
   6.120 +  corrections.
   6.121 +
   6.122 +  To accomplish this, add the phrase ``Distribution of substantively
   6.123 +  modified versions of this document is prohibited without the
   6.124 +  explicit permission of the copyright holder.'' to the license
   6.125 +  reference or copy.
   6.126 +
   6.127 +\item To prohibit any publication of this work or derivative works in
   6.128 +  whole or in part in standard (paper) book form for commercial
   6.129 +  purposes is prohibited unless prior permission is obtained from the
   6.130 +  copyright holder.
   6.131 +
   6.132 +  To accomplish this, add the phrase ``Distribution of the work or
   6.133 +  derivative of the work in any standard (paper) book form is
   6.134 +  prohibited unless prior permission is obtained from the copyright
   6.135 +  holder.'' to the license reference or copy.
   6.136 +\end{enumerate}
   6.137 +
   6.138 +%%% Local Variables: 
   6.139 +%%% mode: latex
   6.140 +%%% TeX-master: "00book"
   6.141 +%%% End: 

     7.1 --- a/en/branch.tex	Thu Jan 29 22:47:34 2009 -0800
     7.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.3 @@ -1,392 +0,0 @@
     7.4 -\chapter{Managing releases and branchy development}
     7.5 -\label{chap:branch}
     7.6 -
     7.7 -Mercurial provides several mechanisms for you to manage a project that
     7.8 -is making progress on multiple fronts at once.  To understand these
     7.9 -mechanisms, let's first take a brief look at a fairly normal software
    7.10 -project structure.
    7.11 -
    7.12 -Many software projects issue periodic ``major'' releases that contain
    7.13 -substantial new features.  In parallel, they may issue ``minor''
    7.14 -releases.  These are usually identical to the major releases off which
    7.15 -they're based, but with a few bugs fixed.
    7.16 -
    7.17 -In this chapter, we'll start by talking about how to keep records of
    7.18 -project milestones such as releases.  We'll then continue on to talk
    7.19 -about the flow of work between different phases of a project, and how
    7.20 -Mercurial can help you to isolate and manage this work.
    7.21 -
    7.22 -\section{Giving a persistent name to a revision}
    7.23 -
    7.24 -Once you decide that you'd like to call a particular revision a
    7.25 -``release'', it's a good idea to record the identity of that revision.
    7.26 -This will let you reproduce that release at a later date, for whatever
    7.27 -purpose you might need at the time (reproducing a bug, porting to a
    7.28 -new platform, etc).
    7.29 -\interaction{tag.init}
    7.30 -
    7.31 -Mercurial lets you give a permanent name to any revision using the
    7.32 -\hgcmd{tag} command.  Not surprisingly, these names are called
    7.33 -``tags''.
    7.34 -\interaction{tag.tag}
    7.35 -
    7.36 -A tag is nothing more than a ``symbolic name'' for a revision.  Tags
    7.37 -exist purely for your convenience, so that you have a handy permanent
    7.38 -way to refer to a revision; Mercurial doesn't interpret the tag names
    7.39 -you use in any way.  Neither does Mercurial place any restrictions on
    7.40 -the name of a tag, beyond a few that are necessary to ensure that a
    7.41 -tag can be parsed unambiguously.  A tag name cannot contain any of the
    7.42 -following characters:
    7.43 -\begin{itemize}
    7.44 -\item Colon (ASCII 58, ``\texttt{:}'')
    7.45 -\item Carriage return (ASCII 13, ``\Verb+\r+'')
    7.46 -\item Newline (ASCII 10, ``\Verb+\n+'')
    7.47 -\end{itemize}
    7.48 -
    7.49 -You can use the \hgcmd{tags} command to display the tags present in
    7.50 -your repository.  In the output, each tagged revision is identified
    7.51 -first by its name, then by revision number, and finally by the unique
    7.52 -hash of the revision.  
    7.53 -\interaction{tag.tags}
    7.54 -Notice that \texttt{tip} is listed in the output of \hgcmd{tags}.  The
    7.55 -\texttt{tip} tag is a special ``floating'' tag, which always
    7.56 -identifies the newest revision in the repository.
    7.57 -
    7.58 -In the output of the \hgcmd{tags} command, tags are listed in reverse
    7.59 -order, by revision number.  This usually means that recent tags are
    7.60 -listed before older tags.  It also means that \texttt{tip} is always
    7.61 -going to be the first tag listed in the output of \hgcmd{tags}.
    7.62 -
    7.63 -When you run \hgcmd{log}, if it displays a revision that has tags
    7.64 -associated with it, it will print those tags.
    7.65 -\interaction{tag.log}
    7.66 -
    7.67 -Any time you need to provide a revision~ID to a Mercurial command, the
    7.68 -command will accept a tag name in its place.  Internally, Mercurial
    7.69 -will translate your tag name into the corresponding revision~ID, then
    7.70 -use that.
    7.71 -\interaction{tag.log.v1.0}
    7.72 -
    7.73 -There's no limit on the number of tags you can have in a repository,
    7.74 -or on the number of tags that a single revision can have.  As a
    7.75 -practical matter, it's not a great idea to have ``too many'' (a number
    7.76 -which will vary from project to project), simply because tags are
    7.77 -supposed to help you to find revisions.  If you have lots of tags, the
    7.78 -ease of using them to identify revisions diminishes rapidly.
    7.79 -
    7.80 -For example, if your project has milestones as frequent as every few
    7.81 -days, it's perfectly reasonable to tag each one of those.  But if you
    7.82 -have a continuous build system that makes sure every revision can be
    7.83 -built cleanly, you'd be introducing a lot of noise if you were to tag
    7.84 -every clean build.  Instead, you could tag failed builds (on the
    7.85 -assumption that they're rare!), or simply not use tags to track
    7.86 -buildability.
    7.87 -
    7.88 -If you want to remove a tag that you no longer want, use
    7.89 -\hgcmdargs{tag}{--remove}.  
    7.90 -\interaction{tag.remove}
    7.91 -You can also modify a tag at any time, so that it identifies a
    7.92 -different revision, by simply issuing a new \hgcmd{tag} command.
    7.93 -You'll have to use the \hgopt{tag}{-f} option to tell Mercurial that
    7.94 -you \emph{really} want to update the tag.
    7.95 -\interaction{tag.replace}
    7.96 -There will still be a permanent record of the previous identity of the
    7.97 -tag, but Mercurial will no longer use it.  There's thus no penalty to
    7.98 -tagging the wrong revision; all you have to do is turn around and tag
    7.99 -the correct revision once you discover your error.
   7.100 -
   7.101 -Mercurial stores tags in a normal revision-controlled file in your
   7.102 -repository.  If you've created any tags, you'll find them in a file
   7.103 -named \sfilename{.hgtags}.  When you run the \hgcmd{tag} command,
   7.104 -Mercurial modifies this file, then automatically commits the change to
   7.105 -it.  This means that every time you run \hgcmd{tag}, you'll see a
   7.106 -corresponding changeset in the output of \hgcmd{log}.
   7.107 -\interaction{tag.tip}
   7.108 -
   7.109 -\subsection{Handling tag conflicts during a merge}
   7.110 -
   7.111 -You won't often need to care about the \sfilename{.hgtags} file, but
   7.112 -it sometimes makes its presence known during a merge.  The format of
   7.113 -the file is simple: it consists of a series of lines.  Each line
   7.114 -starts with a changeset hash, followed by a space, followed by the
   7.115 -name of a tag.
   7.116 -
   7.117 -If you're resolving a conflict in the \sfilename{.hgtags} file during
   7.118 -a merge, there's one twist to modifying the \sfilename{.hgtags} file:
   7.119 -when Mercurial is parsing the tags in a repository, it \emph{never}
   7.120 -reads the working copy of the \sfilename{.hgtags} file.  Instead, it
   7.121 -reads the \emph{most recently committed} revision of the file.
   7.122 -
   7.123 -An unfortunate consequence of this design is that you can't actually
   7.124 -verify that your merged \sfilename{.hgtags} file is correct until
   7.125 -\emph{after} you've committed a change.  So if you find yourself
   7.126 -resolving a conflict on \sfilename{.hgtags} during a merge, be sure to
   7.127 -run \hgcmd{tags} after you commit.  If it finds an error in the
   7.128 -\sfilename{.hgtags} file, it will report the location of the error,
   7.129 -which you can then fix and commit.  You should then run \hgcmd{tags}
   7.130 -again, just to be sure that your fix is correct.
   7.131 -
   7.132 -\subsection{Tags and cloning}
   7.133 -
   7.134 -You may have noticed that the \hgcmd{clone} command has a
   7.135 -\hgopt{clone}{-r} option that lets you clone an exact copy of the
   7.136 -repository as of a particular changeset.  The new clone will not
   7.137 -contain any project history that comes after the revision you
   7.138 -specified.  This has an interaction with tags that can surprise the
   7.139 -unwary.
   7.140 -
   7.141 -Recall that a tag is stored as a revision to the \sfilename{.hgtags}
   7.142 -file, so that when you create a tag, the changeset in which it's
   7.143 -recorded necessarily refers to an older changeset.  When you run
   7.144 -\hgcmdargs{clone}{-r foo} to clone a repository as of tag
   7.145 -\texttt{foo}, the new clone \emph{will not contain the history that
   7.146 -  created the tag} that you used to clone the repository.  The result
   7.147 -is that you'll get exactly the right subset of the project's history
   7.148 -in the new repository, but \emph{not} the tag you might have expected.
   7.149 -
   7.150 -\subsection{When permanent tags are too much}
   7.151 -
   7.152 -Since Mercurial's tags are revision controlled and carried around with
   7.153 -a project's history, everyone you work with will see the tags you
   7.154 -create.  But giving names to revisions has uses beyond simply noting
   7.155 -that revision \texttt{4237e45506ee} is really \texttt{v2.0.2}.  If
   7.156 -you're trying to track down a subtle bug, you might want a tag to
   7.157 -remind you of something like ``Anne saw the symptoms with this
   7.158 -revision''.
   7.159 -
   7.160 -For cases like this, what you might want to use are \emph{local} tags.
   7.161 -You can create a local tag with the \hgopt{tag}{-l} option to the
   7.162 -\hgcmd{tag} command.  This will store the tag in a file called
   7.163 -\sfilename{.hg/localtags}.  Unlike \sfilename{.hgtags},
   7.164 -\sfilename{.hg/localtags} is not revision controlled.  Any tags you
   7.165 -create using \hgopt{tag}{-l} remain strictly local to the repository
   7.166 -you're currently working in.
   7.167 -
   7.168 -\section{The flow of changes---big picture vs. little}
   7.169 -
   7.170 -To return to the outline I sketched at the beginning of a chapter,
   7.171 -let's think about a project that has multiple concurrent pieces of
   7.172 -work under development at once.
   7.173 -
   7.174 -There might be a push for a new ``main'' release; a new minor bugfix
   7.175 -release to the last main release; and an unexpected ``hot fix'' to an
   7.176 -old release that is now in maintenance mode.
   7.177 -
   7.178 -The usual way people refer to these different concurrent directions of
   7.179 -development is as ``branches''.  However, we've already seen numerous
   7.180 -times that Mercurial treats \emph{all of history} as a series of
   7.181 -branches and merges.  Really, what we have here is two ideas that are
   7.182 -peripherally related, but which happen to share a name.
   7.183 -\begin{itemize}
   7.184 -\item ``Big picture'' branches represent the sweep of a project's
   7.185 -  evolution; people give them names, and talk about them in
   7.186 -  conversation.
   7.187 -\item ``Little picture'' branches are artefacts of the day-to-day
   7.188 -  activity of developing and merging changes.  They expose the
   7.189 -  narrative of how the code was developed.
   7.190 -\end{itemize}
   7.191 -
   7.192 -\section{Managing big-picture branches in repositories}
   7.193 -
   7.194 -The easiest way to isolate a ``big picture'' branch in Mercurial is in
   7.195 -a dedicated repository.  If you have an existing shared
   7.196 -repository---let's call it \texttt{myproject}---that reaches a ``1.0''
   7.197 -milestone, you can start to prepare for future maintenance releases on
   7.198 -top of version~1.0 by tagging the revision from which you prepared
   7.199 -the~1.0 release.
   7.200 -\interaction{branch-repo.tag}
   7.201 -You can then clone a new shared \texttt{myproject-1.0.1} repository as
   7.202 -of that tag.
   7.203 -\interaction{branch-repo.clone}
   7.204 -
   7.205 -Afterwards, if someone needs to work on a bug fix that ought to go
   7.206 -into an upcoming~1.0.1 minor release, they clone the
   7.207 -\texttt{myproject-1.0.1} repository, make their changes, and push them
   7.208 -back.
   7.209 -\interaction{branch-repo.bugfix}
   7.210 -Meanwhile, development for the next major release can continue,
   7.211 -isolated and unabated, in the \texttt{myproject} repository.
   7.212 -\interaction{branch-repo.new}
   7.213 -
   7.214 -\section{Don't repeat yourself: merging across branches}
   7.215 -
   7.216 -In many cases, if you have a bug to fix on a maintenance branch, the
   7.217 -chances are good that the bug exists on your project's main branch
   7.218 -(and possibly other maintenance branches, too).  It's a rare developer
   7.219 -who wants to fix the same bug multiple times, so let's look at a few
   7.220 -ways that Mercurial can help you to manage these bugfixes without
   7.221 -duplicating your work.
   7.222 -
   7.223 -In the simplest instance, all you need to do is pull changes from your
   7.224 -maintenance branch into your local clone of the target branch.
   7.225 -\interaction{branch-repo.pull}
   7.226 -You'll then need to merge the heads of the two branches, and push back
   7.227 -to the main branch.
   7.228 -\interaction{branch-repo.merge}
   7.229 -
   7.230 -\section{Naming branches within one repository}
   7.231 -
   7.232 -In most instances, isolating branches in repositories is the right
   7.233 -approach.  Its simplicity makes it easy to understand; and so it's
   7.234 -hard to make mistakes.  There's a one-to-one relationship between
   7.235 -branches you're working in and directories on your system.  This lets
   7.236 -you use normal (non-Mercurial-aware) tools to work on files within a
   7.237 -branch/repository.
   7.238 -
   7.239 -If you're more in the ``power user'' category (\emph{and} your
   7.240 -collaborators are too), there is an alternative way of handling
   7.241 -branches that you can consider.  I've already mentioned the
   7.242 -human-level distinction between ``small picture'' and ``big picture''
   7.243 -branches.  While Mercurial works with multiple ``small picture''
   7.244 -branches in a repository all the time (for example after you pull
   7.245 -changes in, but before you merge them), it can \emph{also} work with
   7.246 -multiple ``big picture'' branches.
   7.247 -
   7.248 -The key to working this way is that Mercurial lets you assign a
   7.249 -persistent \emph{name} to a branch.  There always exists a branch
   7.250 -named \texttt{default}.  Even before you start naming branches
   7.251 -yourself, you can find traces of the \texttt{default} branch if you
   7.252 -look for them.
   7.253 -
   7.254 -As an example, when you run the \hgcmd{commit} command, and it pops up
   7.255 -your editor so that you can enter a commit message, look for a line
   7.256 -that contains the text ``\texttt{HG: branch default}'' at the bottom.
   7.257 -This is telling you that your commit will occur on the branch named
   7.258 -\texttt{default}.
   7.259 -
   7.260 -To start working with named branches, use the \hgcmd{branches}
   7.261 -command.  This command lists the named branches already present in
   7.262 -your repository, telling you which changeset is the tip of each.
   7.263 -\interaction{branch-named.branches}
   7.264 -Since you haven't created any named branches yet, the only one that
   7.265 -exists is \texttt{default}.
   7.266 -
   7.267 -To find out what the ``current'' branch is, run the \hgcmd{branch}
   7.268 -command, giving it no arguments.  This tells you what branch the
   7.269 -parent of the current changeset is on.
   7.270 -\interaction{branch-named.branch}
   7.271 -
   7.272 -To create a new branch, run the \hgcmd{branch} command again.  This
   7.273 -time, give it one argument: the name of the branch you want to create.
   7.274 -\interaction{branch-named.create}
   7.275 -
   7.276 -After you've created a branch, you might wonder what effect the
   7.277 -\hgcmd{branch} command has had.  What do the \hgcmd{status} and
   7.278 -\hgcmd{tip} commands report?
   7.279 -\interaction{branch-named.status}
   7.280 -Nothing has changed in the working directory, and there's been no new
   7.281 -history created.  As this suggests, running the \hgcmd{branch} command
   7.282 -has no permanent effect; it only tells Mercurial what branch name to
   7.283 -use the \emph{next} time you commit a changeset.
   7.284 -
   7.285 -When you commit a change, Mercurial records the name of the branch on
   7.286 -which you committed.  Once you've switched from the \texttt{default}
   7.287 -branch to another and committed, you'll see the name of the new branch
   7.288 -show up in the output of \hgcmd{log}, \hgcmd{tip}, and other commands
   7.289 -that display the same kind of output.
   7.290 -\interaction{branch-named.commit}
   7.291 -The \hgcmd{log}-like commands will print the branch name of every
   7.292 -changeset that's not on the \texttt{default} branch.  As a result, if
   7.293 -you never use named branches, you'll never see this information.
   7.294 -
   7.295 -Once you've named a branch and committed a change with that name,
   7.296 -every subsequent commit that descends from that change will inherit
   7.297 -the same branch name.  You can change the name of a branch at any
   7.298 -time, using the \hgcmd{branch} command.  
   7.299 -\interaction{branch-named.rebranch}
   7.300 -In practice, this is something you won't do very often, as branch
   7.301 -names tend to have fairly long lifetimes.  (This isn't a rule, just an
   7.302 -observation.)
   7.303 -
   7.304 -\section{Dealing with multiple named branches in a repository}
   7.305 -
   7.306 -If you have more than one named branch in a repository, Mercurial will
   7.307 -remember the branch that your working directory on when you start a
   7.308 -command like \hgcmd{update} or \hgcmdargs{pull}{-u}.  It will update
   7.309 -the working directory to the tip of this branch, no matter what the
   7.310 -``repo-wide'' tip is.  To update to a revision that's on a different
   7.311 -named branch, you may need to use the \hgopt{update}{-C} option to
   7.312 -\hgcmd{update}.
   7.313 -
   7.314 -This behaviour is a little subtle, so let's see it in action.  First,
   7.315 -let's remind ourselves what branch we're currently on, and what
   7.316 -branches are in our repository.
   7.317 -\interaction{branch-named.parents}
   7.318 -We're on the \texttt{bar} branch, but there also exists an older
   7.319 -\hgcmd{foo} branch.
   7.320 -
   7.321 -We can \hgcmd{update} back and forth between the tips of the
   7.322 -\texttt{foo} and \texttt{bar} branches without needing to use the
   7.323 -\hgopt{update}{-C} option, because this only involves going backwards
   7.324 -and forwards linearly through our change history.
   7.325 -\interaction{branch-named.update-switchy}
   7.326 -
   7.327 -If we go back to the \texttt{foo} branch and then run \hgcmd{update},
   7.328 -it will keep us on \texttt{foo}, not move us to the tip of
   7.329 -\texttt{bar}.
   7.330 -\interaction{branch-named.update-nothing}
   7.331 -
   7.332 -Committing a new change on the \texttt{foo} branch introduces a new
   7.333 -head.
   7.334 -\interaction{branch-named.foo-commit}
   7.335 -
   7.336 -\section{Branch names and merging}
   7.337 -
   7.338 -As you've probably noticed, merges in Mercurial are not symmetrical.
   7.339 -Let's say our repository has two heads, 17 and 23.  If I
   7.340 -\hgcmd{update} to 17 and then \hgcmd{merge} with 23, Mercurial records
   7.341 -17 as the first parent of the merge, and 23 as the second.  Whereas if
   7.342 -I \hgcmd{update} to 23 and then \hgcmd{merge} with 17, it records 23
   7.343 -as the first parent, and 17 as the second.
   7.344 -
   7.345 -This affects Mercurial's choice of branch name when you merge.  After
   7.346 -a merge, Mercurial will retain the branch name of the first parent
   7.347 -when you commit the result of the merge.  If your first parent's
   7.348 -branch name is \texttt{foo}, and you merge with \texttt{bar}, the
   7.349 -branch name will still be \texttt{foo} after you merge.
   7.350 -
   7.351 -It's not unusual for a repository to contain multiple heads, each with
   7.352 -the same branch name.  Let's say I'm working on the \texttt{foo}
   7.353 -branch, and so are you.  We commit different changes; I pull your
   7.354 -changes; I now have two heads, each claiming to be on the \texttt{foo}
   7.355 -branch.  The result of a merge will be a single head on the
   7.356 -\texttt{foo} branch, as you might hope.
   7.357 -
   7.358 -But if I'm working on the \texttt{bar} branch, and I merge work from
   7.359 -the \texttt{foo} branch, the result will remain on the \texttt{bar}
   7.360 -branch.
   7.361 -\interaction{branch-named.merge}
   7.362 -
   7.363 -To give a more concrete example, if I'm working on the
   7.364 -\texttt{bleeding-edge} branch, and I want to bring in the latest fixes
   7.365 -from the \texttt{stable} branch, Mercurial will choose the ``right''
   7.366 -(\texttt{bleeding-edge}) branch name when I pull and merge from
   7.367 -\texttt{stable}.
   7.368 -
   7.369 -\section{Branch naming is generally useful}
   7.370 -
   7.371 -You shouldn't think of named branches as applicable only to situations
   7.372 -where you have multiple long-lived branches cohabiting in a single
   7.373 -repository.  They're very useful even in the one-branch-per-repository
   7.374 -case.  
   7.375 -
   7.376 -In the simplest case, giving a name to each branch gives you a
   7.377 -permanent record of which branch a changeset originated on.  This
   7.378 -gives you more context when you're trying to follow the history of a
   7.379 -long-lived branchy project.
   7.380 -
   7.381 -If you're working with shared repositories, you can set up a
   7.382 -\hook{pretxnchangegroup} hook on each that will block incoming changes
   7.383 -that have the ``wrong'' branch name.  This provides a simple, but
   7.384 -effective, defence against people accidentally pushing changes from a
   7.385 -``bleeding edge'' branch to a ``stable'' branch.  Such a hook might
   7.386 -look like this inside the shared repo's \hgrc.
   7.387 -\begin{codesample2}
   7.388 -  [hooks]
   7.389 -  pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch
   7.390 -\end{codesample2}
   7.391 -
   7.392 -%%% Local Variables: 
   7.393 -%%% mode: latex
   7.394 -%%% TeX-master: "00book"
   7.395 -%%% End: 

     8.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     8.2 +++ b/en/ch00-preface.tex	Thu Jan 29 22:56:27 2009 -0800
     8.3 @@ -0,0 +1,67 @@
     8.4 +\chapter*{Preface}
     8.5 +\addcontentsline{toc}{chapter}{Preface}
     8.6 +\label{chap:preface}
     8.7 +
     8.8 +Distributed revision control is a relatively new territory, and has
     8.9 +thus far grown due to people's willingness to strike out into
    8.10 +ill-charted territory.
    8.11 +
    8.12 +I am writing a book about distributed revision control because I
    8.13 +believe that it is an important subject that deserves a field guide.
    8.14 +I chose to write about Mercurial because it is the easiest tool to
    8.15 +learn the terrain with, and yet it scales to the demands of real,
    8.16 +challenging environments where many other revision control tools fail.
    8.17 +
    8.18 +\section{This book is a work in progress}
    8.19 +
    8.20 +I am releasing this book while I am still writing it, in the hope that
    8.21 +it will prove useful to others.  I also hope that readers will
    8.22 +contribute as they see fit.
    8.23 +
    8.24 +\section{About the examples in this book}
    8.25 +
    8.26 +This book takes an unusual approach to code samples.  Every example is
    8.27 +``live''---each one is actually the result of a shell script that
    8.28 +executes the Mercurial commands you see.  Every time an image of the
    8.29 +book is built from its sources, all the example scripts are
    8.30 +automatically run, and their current results compared against their
    8.31 +expected results.
    8.32 +
    8.33 +The advantage of this approach is that the examples are always
    8.34 +accurate; they describe \emph{exactly} the behaviour of the version of
    8.35 +Mercurial that's mentioned at the front of the book.  If I update the
    8.36 +version of Mercurial that I'm documenting, and the output of some
    8.37 +command changes, the build fails.
    8.38 +
    8.39 +There is a small disadvantage to this approach, which is that the
    8.40 +dates and times you'll see in examples tend to be ``squashed''
    8.41 +together in a way that they wouldn't be if the same commands were
    8.42 +being typed by a human.  Where a human can issue no more than one
    8.43 +command every few seconds, with any resulting timestamps
    8.44 +correspondingly spread out, my automated example scripts run many
    8.45 +commands in one second.
    8.46 +
    8.47 +As an instance of this, several consecutive commits in an example can
    8.48 +show up as having occurred during the same second.  You can see this
    8.49 +occur in the \hgext{bisect} example in section~\ref{sec:undo:bisect},
    8.50 +for instance.
    8.51 +
    8.52 +So when you're reading examples, don't place too much weight on the
    8.53 +dates or times you see in the output of commands.  But \emph{do} be
    8.54 +confident that the behaviour you're seeing is consistent and
    8.55 +reproducible.
    8.56 +
    8.57 +\section{Colophon---this book is Free}
    8.58 +
    8.59 +This book is licensed under the Open Publication License, and is
    8.60 +produced entirely using Free Software tools.  It is typeset with
    8.61 +\LaTeX{}; illustrations are drawn and rendered with
    8.62 +\href{http://www.inkscape.org/}{Inkscape}.
    8.63 +
    8.64 +The complete source code for this book is published as a Mercurial
    8.65 +repository, at \url{http://hg.serpentine.com/mercurial/book}.
    8.66 +
    8.67 +%%% Local Variables: 
    8.68 +%%% mode: latex
    8.69 +%%% TeX-master: "00book"
    8.70 +%%% End: 

     9.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     9.2 +++ b/en/ch01-intro.tex	Thu Jan 29 22:56:27 2009 -0800
     9.3 @@ -0,0 +1,561 @@
     9.4 +\chapter{Introduction}
     9.5 +\label{chap:intro}
     9.6 +
     9.7 +\section{About revision control}
     9.8 +
     9.9 +Revision control is the process of managing multiple versions of a
    9.10 +piece of information.  In its simplest form, this is something that
    9.11 +many people do by hand: every time you modify a file, save it under a
    9.12 +new name that contains a number, each one higher than the number of
    9.13 +the preceding version.
    9.14 +
    9.15 +Manually managing multiple versions of even a single file is an
    9.16 +error-prone task, though, so software tools to help automate this
    9.17 +process have long been available.  The earliest automated revision
    9.18 +control tools were intended to help a single user to manage revisions
    9.19 +of a single file.  Over the past few decades, the scope of revision
    9.20 +control tools has expanded greatly; they now manage multiple files,
    9.21 +and help multiple people to work together.  The best modern revision
    9.22 +control tools have no problem coping with thousands of people working
    9.23 +together on projects that consist of hundreds of thousands of files.
    9.24 +
    9.25 +\subsection{Why use revision control?}
    9.26 +
    9.27 +There are a number of reasons why you or your team might want to use
    9.28 +an automated revision control tool for a project.
    9.29 +\begin{itemize}
    9.30 +\item It will track the history and evolution of your project, so you
    9.31 +  don't have to.  For every change, you'll have a log of \emph{who}
    9.32 +  made it; \emph{why} they made it; \emph{when} they made it; and
    9.33 +  \emph{what} the change was.
    9.34 +\item When you're working with other people, revision control software
    9.35 +  makes it easier for you to collaborate.  For example, when people
    9.36 +  more or less simultaneously make potentially incompatible changes,
    9.37 +  the software will help you to identify and resolve those conflicts.
    9.38 +\item It can help you to recover from mistakes.  If you make a change
    9.39 +  that later turns out to be in error, you can revert to an earlier
    9.40 +  version of one or more files.  In fact, a \emph{really} good
    9.41 +  revision control tool will even help you to efficiently figure out
    9.42 +  exactly when a problem was introduced (see
    9.43 +  section~\ref{sec:undo:bisect} for details).
    9.44 +\item It will help you to work simultaneously on, and manage the drift
    9.45 +  between, multiple versions of your project.
    9.46 +\end{itemize}
    9.47 +Most of these reasons are equally valid---at least in theory---whether
    9.48 +you're working on a project by yourself, or with a hundred other
    9.49 +people.
    9.50 +
    9.51 +A key question about the practicality of revision control at these two
    9.52 +different scales (``lone hacker'' and ``huge team'') is how its
    9.53 +\emph{benefits} compare to its \emph{costs}.  A revision control tool
    9.54 +that's difficult to understand or use is going to impose a high cost.
    9.55 +
    9.56 +A five-hundred-person project is likely to collapse under its own
    9.57 +weight almost immediately without a revision control tool and process.
    9.58 +In this case, the cost of using revision control might hardly seem
    9.59 +worth considering, since \emph{without} it, failure is almost
    9.60 +guaranteed.
    9.61 +
    9.62 +On the other hand, a one-person ``quick hack'' might seem like a poor
    9.63 +place to use a revision control tool, because surely the cost of using
    9.64 +one must be close to the overall cost of the project.  Right?
    9.65 +
    9.66 +Mercurial uniquely supports \emph{both} of these scales of
    9.67 +development.  You can learn the basics in just a few minutes, and due
    9.68 +to its low overhead, you can apply revision control to the smallest of
    9.69 +projects with ease.  Its simplicity means you won't have a lot of
    9.70 +abstruse concepts or command sequences competing for mental space with
    9.71 +whatever you're \emph{really} trying to do.  At the same time,
    9.72 +Mercurial's high performance and peer-to-peer nature let you scale
    9.73 +painlessly to handle large projects.
    9.74 +
    9.75 +No revision control tool can rescue a poorly run project, but a good
    9.76 +choice of tools can make a huge difference to the fluidity with which
    9.77 +you can work on a project.
    9.78 +
    9.79 +\subsection{The many names of revision control}
    9.80 +
    9.81 +Revision control is a diverse field, so much so that it doesn't
    9.82 +actually have a single name or acronym.  Here are a few of the more
    9.83 +common names and acronyms you'll encounter:
    9.84 +\begin{itemize}
    9.85 +\item Revision control (RCS)
    9.86 +\item Software configuration management (SCM), or configuration management
    9.87 +\item Source code management
    9.88 +\item Source code control, or source control
    9.89 +\item Version control (VCS)
    9.90 +\end{itemize}
    9.91 +Some people claim that these terms actually have different meanings,
    9.92 +but in practice they overlap so much that there's no agreed or even
    9.93 +useful way to tease them apart.
    9.94 +
    9.95 +\section{A short history of revision control}
    9.96 +
    9.97 +The best known of the old-time revision control tools is SCCS (Source
    9.98 +Code Control System), which Marc Rochkind wrote at Bell Labs, in the
    9.99 +early 1970s.  SCCS operated on individual files, and required every
   9.100 +person working on a project to have access to a shared workspace on a
   9.101 +single system.  Only one person could modify a file at any time;
   9.102 +arbitration for access to files was via locks.  It was common for
   9.103 +people to lock files, and later forget to unlock them, preventing
   9.104 +anyone else from modifying those files without the help of an
   9.105 +administrator.  
   9.106 +
   9.107 +Walter Tichy developed a free alternative to SCCS in the early 1980s;
   9.108 +he called his program RCS (Revison Control System).  Like SCCS, RCS
   9.109 +required developers to work in a single shared workspace, and to lock
   9.110 +files to prevent multiple people from modifying them simultaneously.
   9.111 +
   9.112 +Later in the 1980s, Dick Grune used RCS as a building block for a set
   9.113 +of shell scripts he initially called cmt, but then renamed to CVS
   9.114 +(Concurrent Versions System).  The big innovation of CVS was that it
   9.115 +let developers work simultaneously and somewhat independently in their
   9.116 +own personal workspaces.  The personal workspaces prevented developers
   9.117 +from stepping on each other's toes all the time, as was common with
   9.118 +SCCS and RCS.  Each developer had a copy of every project file, and
   9.119 +could modify their copies independently.  They had to merge their
   9.120 +edits prior to committing changes to the central repository.
   9.121 +
   9.122 +Brian Berliner took Grune's original scripts and rewrote them in~C,
   9.123 +releasing in 1989 the code that has since developed into the modern
   9.124 +version of CVS.  CVS subsequently acquired the ability to operate over
   9.125 +a network connection, giving it a client/server architecture.  CVS's
   9.126 +architecture is centralised; only the server has a copy of the history
   9.127 +of the project.  Client workspaces just contain copies of recent
   9.128 +versions of the project's files, and a little metadata to tell them
   9.129 +where the server is.  CVS has been enormously successful; it is
   9.130 +probably the world's most widely used revision control system.
   9.131 +
   9.132 +In the early 1990s, Sun Microsystems developed an early distributed
   9.133 +revision control system, called TeamWare.  A TeamWare workspace
   9.134 +contains a complete copy of the project's history.  TeamWare has no
   9.135 +notion of a central repository.  (CVS relied upon RCS for its history
   9.136 +storage; TeamWare used SCCS.)
   9.137 +
   9.138 +As the 1990s progressed, awareness grew of a number of problems with
   9.139 +CVS.  It records simultaneous changes to multiple files individually,
   9.140 +instead of grouping them together as a single logically atomic
   9.141 +operation.  It does not manage its file hierarchy well; it is easy to
   9.142 +make a mess of a repository by renaming files and directories.  Worse,
   9.143 +its source code is difficult to read and maintain, which made the
   9.144 +``pain level'' of fixing these architectural problems prohibitive.
   9.145 +
   9.146 +In 2001, Jim Blandy and Karl Fogel, two developers who had worked on
   9.147 +CVS, started a project to replace it with a tool that would have a
   9.148 +better architecture and cleaner code.  The result, Subversion, does
   9.149 +not stray from CVS's centralised client/server model, but it adds
   9.150 +multi-file atomic commits, better namespace management, and a number
   9.151 +of other features that make it a generally better tool than CVS.
   9.152 +Since its initial release, it has rapidly grown in popularity.
   9.153 +
   9.154 +More or less simultaneously, Graydon Hoare began working on an
   9.155 +ambitious distributed revision control system that he named Monotone.
   9.156 +While Monotone addresses many of CVS's design flaws and has a
   9.157 +peer-to-peer architecture, it goes beyond earlier (and subsequent)
   9.158 +revision control tools in a number of innovative ways.  It uses
   9.159 +cryptographic hashes as identifiers, and has an integral notion of
   9.160 +``trust'' for code from different sources.
   9.161 +
   9.162 +Mercurial began life in 2005.  While a few aspects of its design are
   9.163 +influenced by Monotone, Mercurial focuses on ease of use, high
   9.164 +performance, and scalability to very large projects.
   9.165 +
   9.166 +\section{Trends in revision control}
   9.167 +
   9.168 +There has been an unmistakable trend in the development and use of
   9.169 +revision control tools over the past four decades, as people have
   9.170 +become familiar with the capabilities of their tools and constrained
   9.171 +by their limitations.
   9.172 +
   9.173 +The first generation began by managing single files on individual
   9.174 +computers.  Although these tools represented a huge advance over
   9.175 +ad-hoc manual revision control, their locking model and reliance on a
   9.176 +single computer limited them to small, tightly-knit teams.
   9.177 +
   9.178 +The second generation loosened these constraints by moving to
   9.179 +network-centered architectures, and managing entire projects at a
   9.180 +time.  As projects grew larger, they ran into new problems.  With
   9.181 +clients needing to talk to servers very frequently, server scaling
   9.182 +became an issue for large projects.  An unreliable network connection
   9.183 +could prevent remote users from being able to talk to the server at
   9.184 +all.  As open source projects started making read-only access
   9.185 +available anonymously to anyone, people without commit privileges
   9.186 +found that they could not use the tools to interact with a project in
   9.187 +a natural way, as they could not record their changes.
   9.188 +
   9.189 +The current generation of revision control tools is peer-to-peer in
   9.190 +nature.  All of these systems have dropped the dependency on a single
   9.191 +central server, and allow people to distribute their revision control
   9.192 +data to where it's actually needed.  Collaboration over the Internet
   9.193 +has moved from constrained by technology to a matter of choice and
   9.194 +consensus.  Modern tools can operate offline indefinitely and
   9.195 +autonomously, with a network connection only needed when syncing
   9.196 +changes with another repository.
   9.197 +
   9.198 +\section{A few of the advantages of distributed revision control}
   9.199 +
   9.200 +Even though distributed revision control tools have for several years
   9.201 +been as robust and usable as their previous-generation counterparts,
   9.202 +people using older tools have not yet necessarily woken up to their
   9.203 +advantages.  There are a number of ways in which distributed tools
   9.204 +shine relative to centralised ones.
   9.205 +
   9.206 +For an individual developer, distributed tools are almost always much
   9.207 +faster than centralised tools.  This is for a simple reason: a
   9.208 +centralised tool needs to talk over the network for many common
   9.209 +operations, because most metadata is stored in a single copy on the
   9.210 +central server.  A distributed tool stores all of its metadata
   9.211 +locally.  All else being equal, talking over the network adds overhead
   9.212 +to a centralised tool.  Don't underestimate the value of a snappy,
   9.213 +responsive tool: you're going to spend a lot of time interacting with
   9.214 +your revision control software.
   9.215 +
   9.216 +Distributed tools are indifferent to the vagaries of your server
   9.217 +infrastructure, again because they replicate metadata to so many
   9.218 +locations.  If you use a centralised system and your server catches
   9.219 +fire, you'd better hope that your backup media are reliable, and that
   9.220 +your last backup was recent and actually worked.  With a distributed
   9.221 +tool, you have many backups available on every contributor's computer.
   9.222 +
   9.223 +The reliability of your network will affect distributed tools far less
   9.224 +than it will centralised tools.  You can't even use a centralised tool
   9.225 +without a network connection, except for a few highly constrained
   9.226 +commands.  With a distributed tool, if your network connection goes
   9.227 +down while you're working, you may not even notice.  The only thing
   9.228 +you won't be able to do is talk to repositories on other computers,
   9.229 +something that is relatively rare compared with local operations.  If
   9.230 +you have a far-flung team of collaborators, this may be significant.
   9.231 +
   9.232 +\subsection{Advantages for open source projects}
   9.233 +
   9.234 +If you take a shine to an open source project and decide that you
   9.235 +would like to start hacking on it, and that project uses a distributed
   9.236 +revision control tool, you are at once a peer with the people who
   9.237 +consider themselves the ``core'' of that project.  If they publish
   9.238 +their repositories, you can immediately copy their project history,
   9.239 +start making changes, and record your work, using the same tools in
   9.240 +the same ways as insiders.  By contrast, with a centralised tool, you
   9.241 +must use the software in a ``read only'' mode unless someone grants
   9.242 +you permission to commit changes to their central server.  Until then,
   9.243 +you won't be able to record changes, and your local modifications will
   9.244 +be at risk of corruption any time you try to update your client's view
   9.245 +of the repository.
   9.246 +
   9.247 +\subsubsection{The forking non-problem}
   9.248 +
   9.249 +It has been suggested that distributed revision control tools pose
   9.250 +some sort of risk to open source projects because they make it easy to
   9.251 +``fork'' the development of a project.  A fork happens when there are
   9.252 +differences in opinion or attitude between groups of developers that
   9.253 +cause them to decide that they can't work together any longer.  Each
   9.254 +side takes a more or less complete copy of the project's source code,
   9.255 +and goes off in its own direction.
   9.256 +
   9.257 +Sometimes the camps in a fork decide to reconcile their differences.
   9.258 +With a centralised revision control system, the \emph{technical}
   9.259 +process of reconciliation is painful, and has to be performed largely
   9.260 +by hand.  You have to decide whose revision history is going to
   9.261 +``win'', and graft the other team's changes into the tree somehow.
   9.262 +This usually loses some or all of one side's revision history.
   9.263 +
   9.264 +What distributed tools do with respect to forking is they make forking
   9.265 +the \emph{only} way to develop a project.  Every single change that
   9.266 +you make is potentially a fork point.  The great strength of this
   9.267 +approach is that a distributed revision control tool has to be really
   9.268 +good at \emph{merging} forks, because forks are absolutely
   9.269 +fundamental: they happen all the time.  
   9.270 +
   9.271 +If every piece of work that everybody does, all the time, is framed in
   9.272 +terms of forking and merging, then what the open source world refers
   9.273 +to as a ``fork'' becomes \emph{purely} a social issue.  If anything,
   9.274 +distributed tools \emph{lower} the likelihood of a fork:
   9.275 +\begin{itemize}
   9.276 +\item They eliminate the social distinction that centralised tools
   9.277 +  impose: that between insiders (people with commit access) and
   9.278 +  outsiders (people without).
   9.279 +\item They make it easier to reconcile after a social fork, because
   9.280 +  all that's involved from the perspective of the revision control
   9.281 +  software is just another merge.
   9.282 +\end{itemize}
   9.283 +
   9.284 +Some people resist distributed tools because they want to retain tight
   9.285 +control over their projects, and they believe that centralised tools
   9.286 +give them this control.  However, if you're of this belief, and you
   9.287 +publish your CVS or Subversion repositories publically, there are
   9.288 +plenty of tools available that can pull out your entire project's
   9.289 +history (albeit slowly) and recreate it somewhere that you don't
   9.290 +control.  So while your control in this case is illusory, you are
   9.291 +forgoing the ability to fluidly collaborate with whatever people feel
   9.292 +compelled to mirror and fork your history.
   9.293 +
   9.294 +\subsection{Advantages for commercial projects}
   9.295 +
   9.296 +Many commercial projects are undertaken by teams that are scattered
   9.297 +across the globe.  Contributors who are far from a central server will
   9.298 +see slower command execution and perhaps less reliability.  Commercial
   9.299 +revision control systems attempt to ameliorate these problems with
   9.300 +remote-site replication add-ons that are typically expensive to buy
   9.301 +and cantankerous to administer.  A distributed system doesn't suffer
   9.302 +from these problems in the first place.  Better yet, you can easily
   9.303 +set up multiple authoritative servers, say one per site, so that
   9.304 +there's no redundant communication between repositories over expensive
   9.305 +long-haul network links.
   9.306 +
   9.307 +Centralised revision control systems tend to have relatively low
   9.308 +scalability.  It's not unusual for an expensive centralised system to
   9.309 +fall over under the combined load of just a few dozen concurrent
   9.310 +users.  Once again, the typical response tends to be an expensive and
   9.311 +clunky replication facility.  Since the load on a central server---if
   9.312 +you have one at all---is many times lower with a distributed
   9.313 +tool (because all of the data is replicated everywhere), a single
   9.314 +cheap server can handle the needs of a much larger team, and
   9.315 +replication to balance load becomes a simple matter of scripting.
   9.316 +
   9.317 +If you have an employee in the field, troubleshooting a problem at a
   9.318 +customer's site, they'll benefit from distributed revision control.
   9.319 +The tool will let them generate custom builds, try different fixes in
   9.320 +isolation from each other, and search efficiently through history for
   9.321 +the sources of bugs and regressions in the customer's environment, all
   9.322 +without needing to connect to your company's network.
   9.323 +
   9.324 +\section{Why choose Mercurial?}
   9.325 +
   9.326 +Mercurial has a unique set of properties that make it a particularly
   9.327 +good choice as a revision control system.
   9.328 +\begin{itemize}
   9.329 +\item It is easy to learn and use.
   9.330 +\item It is lightweight.
   9.331 +\item It scales excellently.
   9.332 +\item It is easy to customise.
   9.333 +\end{itemize}
   9.334 +
   9.335 +If you are at all familiar with revision control systems, you should
   9.336 +be able to get up and running with Mercurial in less than five
   9.337 +minutes.  Even if not, it will take no more than a few minutes
   9.338 +longer.  Mercurial's command and feature sets are generally uniform
   9.339 +and consistent, so you can keep track of a few general rules instead
   9.340 +of a host of exceptions.
   9.341 +
   9.342 +On a small project, you can start working with Mercurial in moments.
   9.343 +Creating new changes and branches; transferring changes around
   9.344 +(whether locally or over a network); and history and status operations
   9.345 +are all fast.  Mercurial attempts to stay nimble and largely out of
   9.346 +your way by combining low cognitive overhead with blazingly fast
   9.347 +operations.
   9.348 +
   9.349 +The usefulness of Mercurial is not limited to small projects: it is
   9.350 +used by projects with hundreds to thousands of contributors, each
   9.351 +containing tens of thousands of files and hundreds of megabytes of
   9.352 +source code.
   9.353 +
   9.354 +If the core functionality of Mercurial is not enough for you, it's
   9.355 +easy to build on.  Mercurial is well suited to scripting tasks, and
   9.356 +its clean internals and implementation in Python make it easy to add
   9.357 +features in the form of extensions.  There are a number of popular and
   9.358 +useful extensions already available, ranging from helping to identify
   9.359 +bugs to improving performance.
   9.360 +
   9.361 +\section{Mercurial compared with other tools}
   9.362 +
   9.363 +Before you read on, please understand that this section necessarily
   9.364 +reflects my own experiences, interests, and (dare I say it) biases.  I
   9.365 +have used every one of the revision control tools listed below, in
   9.366 +most cases for several years at a time.
   9.367 +
   9.368 +
   9.369 +\subsection{Subversion}
   9.370 +
   9.371 +Subversion is a popular revision control tool, developed to replace
   9.372 +CVS.  It has a centralised client/server architecture.
   9.373 +
   9.374 +Subversion and Mercurial have similarly named commands for performing
   9.375 +the same operations, so if you're familiar with one, it is easy to
   9.376 +learn to use the other.  Both tools are portable to all popular
   9.377 +operating systems.
   9.378 +
   9.379 +Prior to version 1.5, Subversion had no useful support for merges.
   9.380 +At the time of writing, its merge tracking capability is new, and known to be
   9.381 +\href{http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword}{complicated
   9.382 +  and buggy}.
   9.383 +
   9.384 +Mercurial has a substantial performance advantage over Subversion on
   9.385 +every revision control operation I have benchmarked.  I have measured
   9.386 +its advantage as ranging from a factor of two to a factor of six when
   9.387 +compared with Subversion~1.4.3's \emph{ra\_local} file store, which is
   9.388 +the fastest access method available.  In more realistic deployments
   9.389 +involving a network-based store, Subversion will be at a substantially
   9.390 +larger disadvantage.  Because many Subversion commands must talk to
   9.391 +the server and Subversion does not have useful replication facilities,
   9.392 +server capacity and network bandwidth become bottlenecks for modestly
   9.393 +large projects.
   9.394 +
   9.395 +Additionally, Subversion incurs substantial storage overhead to avoid
   9.396 +network transactions for a few common operations, such as finding
   9.397 +modified files (\texttt{status}) and displaying modifications against
   9.398 +the current revision (\texttt{diff}).  As a result, a Subversion
   9.399 +working copy is often the same size as, or larger than, a Mercurial
   9.400 +repository and working directory, even though the Mercurial repository
   9.401 +contains a complete history of the project.
   9.402 +
   9.403 +Subversion is widely supported by third party tools.  Mercurial
   9.404 +currently lags considerably in this area.  This gap is closing,
   9.405 +however, and indeed some of Mercurial's GUI tools now outshine their
   9.406 +Subversion equivalents.  Like Mercurial, Subversion has an excellent
   9.407 +user manual.
   9.408 +
   9.409 +Because Subversion doesn't store revision history on the client, it is
   9.410 +well suited to managing projects that deal with lots of large, opaque
   9.411 +binary files.  If you check in fifty revisions to an incompressible
   9.412 +10MB file, Subversion's client-side space usage stays constant The
   9.413 +space used by any distributed SCM will grow rapidly in proportion to
   9.414 +the number of revisions, because the differences between each revision
   9.415 +are large.
   9.416 +
   9.417 +In addition, it's often difficult or, more usually, impossible to
   9.418 +merge different versions of a binary file.  Subversion's ability to
   9.419 +let a user lock a file, so that they temporarily have the exclusive
   9.420 +right to commit changes to it, can be a significant advantage to a
   9.421 +project where binary files are widely used.
   9.422 +
   9.423 +Mercurial can import revision history from a Subversion repository.
   9.424 +It can also export revision history to a Subversion repository.  This
   9.425 +makes it easy to ``test the waters'' and use Mercurial and Subversion
   9.426 +in parallel before deciding to switch.  History conversion is
   9.427 +incremental, so you can perform an initial conversion, then small
   9.428 +additional conversions afterwards to bring in new changes.
   9.429 +
   9.430 +
   9.431 +\subsection{Git}
   9.432 +
   9.433 +Git is a distributed revision control tool that was developed for
   9.434 +managing the Linux kernel source tree.  Like Mercurial, its early
   9.435 +design was somewhat influenced by Monotone.
   9.436 +
   9.437 +Git has a very large command set, with version~1.5.0 providing~139
   9.438 +individual commands.  It has something of a reputation for being
   9.439 +difficult to learn.  Compared to Git, Mercurial has a strong focus on
   9.440 +simplicity.
   9.441 +
   9.442 +In terms of performance, Git is extremely fast.  In several cases, it
   9.443 +is faster than Mercurial, at least on Linux, while Mercurial performs
   9.444 +better on other operations.  However, on Windows, the performance and
   9.445 +general level of support that Git provides is, at the time of writing,
   9.446 +far behind that of Mercurial.
   9.447 +
   9.448 +While a Mercurial repository needs no maintenance, a Git repository
   9.449 +requires frequent manual ``repacks'' of its metadata.  Without these,
   9.450 +performance degrades, while space usage grows rapidly.  A server that
   9.451 +contains many Git repositories that are not rigorously and frequently
   9.452 +repacked will become heavily disk-bound during backups, and there have
   9.453 +been instances of daily backups taking far longer than~24 hours as a
   9.454 +result.  A freshly packed Git repository is slightly smaller than a
   9.455 +Mercurial repository, but an unpacked repository is several orders of
   9.456 +magnitude larger.
   9.457 +
   9.458 +The core of Git is written in C.  Many Git commands are implemented as
   9.459 +shell or Perl scripts, and the quality of these scripts varies widely.
   9.460 +I have encountered several instances where scripts charged along
   9.461 +blindly in the presence of errors that should have been fatal.
   9.462 +
   9.463 +Mercurial can import revision history from a Git repository.
   9.464 +
   9.465 +
   9.466 +\subsection{CVS}
   9.467 +
   9.468 +CVS is probably the most widely used revision control tool in the
   9.469 +world.  Due to its age and internal untidiness, it has been only
   9.470 +lightly maintained for many years.
   9.471 +
   9.472 +It has a centralised client/server architecture.  It does not group
   9.473 +related file changes into atomic commits, making it easy for people to
   9.474 +``break the build'': one person can successfully commit part of a
   9.475 +change and then be blocked by the need for a merge, causing other
   9.476 +people to see only a portion of the work they intended to do.  This
   9.477 +also affects how you work with project history.  If you want to see
   9.478 +all of the modifications someone made as part of a task, you will need
   9.479 +to manually inspect the descriptions and timestamps of the changes
   9.480 +made to each file involved (if you even know what those files were).
   9.481 +
   9.482 +CVS has a muddled notion of tags and branches that I will not attempt
   9.483 +to even describe.  It does not support renaming of files or
   9.484 +directories well, making it easy to corrupt a repository.  It has
   9.485 +almost no internal consistency checking capabilities, so it is usually
   9.486 +not even possible to tell whether or how a repository is corrupt.  I
   9.487 +would not recommend CVS for any project, existing or new.
   9.488 +
   9.489 +Mercurial can import CVS revision history.  However, there are a few
   9.490 +caveats that apply; these are true of every other revision control
   9.491 +tool's CVS importer, too.  Due to CVS's lack of atomic changes and
   9.492 +unversioned filesystem hierarchy, it is not possible to reconstruct
   9.493 +CVS history completely accurately; some guesswork is involved, and
   9.494 +renames will usually not show up.  Because a lot of advanced CVS
   9.495 +administration has to be done by hand and is hence error-prone, it's
   9.496 +common for CVS importers to run into multiple problems with corrupted
   9.497 +repositories (completely bogus revision timestamps and files that have
   9.498 +remained locked for over a decade are just two of the less interesting
   9.499 +problems I can recall from personal experience).
   9.500 +
   9.501 +Mercurial can import revision history from a CVS repository.
   9.502 +
   9.503 +
   9.504 +\subsection{Commercial tools}
   9.505 +
   9.506 +Perforce has a centralised client/server architecture, with no
   9.507 +client-side caching of any data.  Unlike modern revision control
   9.508 +tools, Perforce requires that a user run a command to inform the
   9.509 +server about every file they intend to edit.
   9.510 +
   9.511 +The performance of Perforce is quite good for small teams, but it
   9.512 +falls off rapidly as the number of users grows beyond a few dozen.
   9.513 +Modestly large Perforce installations require the deployment of
   9.514 +proxies to cope with the load their users generate.
   9.515 +
   9.516 +
   9.517 +\subsection{Choosing a revision control tool}
   9.518 +
   9.519 +With the exception of CVS, all of the tools listed above have unique
   9.520 +strengths that suit them to particular styles of work.  There is no
   9.521 +single revision control tool that is best in all situations.
   9.522 +
   9.523 +As an example, Subversion is a good choice for working with frequently
   9.524 +edited binary files, due to its centralised nature and support for
   9.525 +file locking.
   9.526 +
   9.527 +I personally find Mercurial's properties of simplicity, performance,
   9.528 +and good merge support to be a compelling combination that has served
   9.529 +me well for several years.
   9.530 +
   9.531 +
   9.532 +\section{Switching from another tool to Mercurial}
   9.533 +
   9.534 +Mercurial is bundled with an extension named \hgext{convert}, which
   9.535 +can incrementally import revision history from several other revision
   9.536 +control tools.  By ``incremental'', I mean that you can convert all of
   9.537 +a project's history to date in one go, then rerun the conversion later
   9.538 +to obtain new changes that happened after the initial conversion.
   9.539 +
   9.540 +The revision control tools supported by \hgext{convert} are as
   9.541 +follows:
   9.542 +\begin{itemize}
   9.543 +\item Subversion
   9.544 +\item CVS
   9.545 +\item Git
   9.546 +\item Darcs
   9.547 +\end{itemize}
   9.548 +
   9.549 +In addition, \hgext{convert} can export changes from Mercurial to
   9.550 +Subversion.  This makes it possible to try Subversion and Mercurial in
   9.551 +parallel before committing to a switchover, without risking the loss
   9.552 +of any work.
   9.553 +
   9.554 +The \hgxcmd{conver}{convert} command is easy to use.  Simply point it
   9.555 +at the path or URL of the source repository, optionally give it the
   9.556 +name of the destination repository, and it will start working.  After
   9.557 +the initial conversion, just run the same command again to import new
   9.558 +changes.
   9.559 +
   9.560 +
   9.561 +%%% Local Variables: 
   9.562 +%%% mode: latex
   9.563 +%%% TeX-master: "00book"
   9.564 +%%% End: 

    10.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    10.2 +++ b/en/ch02-tour-basic.tex	Thu Jan 29 22:56:27 2009 -0800
    10.3 @@ -0,0 +1,624 @@
    10.4 +\chapter{A tour of Mercurial: the basics}
    10.5 +\label{chap:tour-basic}
    10.6 +
    10.7 +\section{Installing Mercurial on your system}
    10.8 +\label{sec:tour:install}
    10.9 +
   10.10 +Prebuilt binary packages of Mercurial are available for every popular
   10.11 +operating system.  These make it easy to start using Mercurial on your
   10.12 +computer immediately.
   10.13 +
   10.14 +\subsection{Linux}
   10.15 +
   10.16 +Because each Linux distribution has its own packaging tools, policies,
   10.17 +and rate of development, it's difficult to give a comprehensive set of
   10.18 +instructions on how to install Mercurial binaries.  The version of
   10.19 +Mercurial that you will end up with can vary depending on how active
   10.20 +the person is who maintains the package for your distribution.
   10.21 +
   10.22 +To keep things simple, I will focus on installing Mercurial from the
   10.23 +command line under the most popular Linux distributions.  Most of
   10.24 +these distributions provide graphical package managers that will let
   10.25 +you install Mercurial with a single click; the package name to look
   10.26 +for is \texttt{mercurial}.
   10.27 +
   10.28 +\begin{itemize}
   10.29 +\item[Debian]
   10.30 +  \begin{codesample4}
   10.31 +    apt-get install mercurial
   10.32 +  \end{codesample4}
   10.33 +
   10.34 +\item[Fedora Core]
   10.35 +  \begin{codesample4}
   10.36 +    yum install mercurial
   10.37 +  \end{codesample4}
   10.38 +
   10.39 +\item[Gentoo]
   10.40 +  \begin{codesample4}
   10.41 +    emerge mercurial
   10.42 +  \end{codesample4}
   10.43 +
   10.44 +\item[OpenSUSE]
   10.45 +  \begin{codesample4}
   10.46 +    yum install mercurial
   10.47 +  \end{codesample4}
   10.48 +
   10.49 +\item[Ubuntu] Ubuntu's Mercurial package is based on Debian's.  To
   10.50 +  install it, run the following command.
   10.51 +  \begin{codesample4}
   10.52 +    apt-get install mercurial
   10.53 +  \end{codesample4}
   10.54 +  The Ubuntu package for Mercurial tends to lag behind the Debian
   10.55 +  version by a considerable time margin (at the time of writing, seven
   10.56 +  months), which in some cases will mean that on Ubuntu, you may run
   10.57 +  into problems that have since been fixed in the Debian package.
   10.58 +\end{itemize}
   10.59 +
   10.60 +\subsection{Solaris}
   10.61 +
   10.62 +SunFreeWare, at \url{http://www.sunfreeware.com}, is a good source for a
   10.63 +large number of pre-built Solaris packages for 32 and 64 bit Intel and
   10.64 +Sparc architectures, including current versions of Mercurial.
   10.65 +
   10.66 +\subsection{Mac OS X}
   10.67 +
   10.68 +Lee Cantey publishes an installer of Mercurial for Mac OS~X at
   10.69 +\url{http://mercurial.berkwood.com}.  This package works on both
   10.70 +Intel-~and Power-based Macs.  Before you can use it, you must install
   10.71 +a compatible version of Universal MacPython~\cite{web:macpython}.  This
   10.72 +is easy to do; simply follow the instructions on Lee's site.
   10.73 +
   10.74 +It's also possible to install Mercurial using Fink or MacPorts,
   10.75 +two popular free package managers for Mac OS X.  If you have Fink,
   10.76 +use \command{sudo apt-get install mercurial-py25}.  If MacPorts,
   10.77 +\command{sudo port install mercurial}.
   10.78 +
   10.79 +\subsection{Windows}
   10.80 +
   10.81 +Lee Cantey publishes an installer of Mercurial for Windows at
   10.82 +\url{http://mercurial.berkwood.com}.  This package has no external
   10.83 +dependencies; it ``just works''.
   10.84 +
   10.85 +\begin{note}
   10.86 +  The Windows version of Mercurial does not automatically convert line
   10.87 +  endings between Windows and Unix styles.  If you want to share work
   10.88 +  with Unix users, you must do a little additional configuration
   10.89 +  work. XXX Flesh this out.
   10.90 +\end{note}
   10.91 +
   10.92 +\section{Getting started}
   10.93 +
   10.94 +To begin, we'll use the \hgcmd{version} command to find out whether
   10.95 +Mercurial is actually installed properly.  The actual version
   10.96 +information that it prints isn't so important; it's whether it prints
   10.97 +anything at all that we care about.
   10.98 +\interaction{tour.version}
   10.99 +
  10.100 +\subsection{Built-in help}
  10.101 +
  10.102 +Mercurial provides a built-in help system.  This is invaluable for those
  10.103 +times when you find yourself stuck trying to remember how to run a
  10.104 +command.  If you are completely stuck, simply run \hgcmd{help}; it
  10.105 +will print a brief list of commands, along with a description of what
  10.106 +each does.  If you ask for help on a specific command (as below), it
  10.107 +prints more detailed information.
  10.108 +\interaction{tour.help}
  10.109 +For a more impressive level of detail (which you won't usually need)
  10.110 +run \hgcmdargs{help}{\hggopt{-v}}.  The \hggopt{-v} option is short
  10.111 +for \hggopt{--verbose}, and tells Mercurial to print more information
  10.112 +than it usually would.
  10.113 +
  10.114 +\section{Working with a repository}
  10.115 +
  10.116 +In Mercurial, everything happens inside a \emph{repository}.  The
  10.117 +repository for a project contains all of the files that ``belong to''
  10.118 +that project, along with a historical record of the project's files.
  10.119 +
  10.120 +There's nothing particularly magical about a repository; it is simply
  10.121 +a directory tree in your filesystem that Mercurial treats as special.
  10.122 +You can rename or delete a repository any time you like, using either the
  10.123 +command line or your file browser.
  10.124 +
  10.125 +\subsection{Making a local copy of a repository}
  10.126 +
  10.127 +\emph{Copying} a repository is just a little bit special.  While you
  10.128 +could use a normal file copying command to make a copy of a
  10.129 +repository, it's best to use a built-in command that Mercurial
  10.130 +provides.  This command is called \hgcmd{clone}, because it creates an
  10.131 +identical copy of an existing repository.
  10.132 +\interaction{tour.clone}
  10.133 +If our clone succeeded, we should now have a local directory called
  10.134 +\dirname{hello}.  This directory will contain some files.
  10.135 +\interaction{tour.ls}
  10.136 +These files have the same contents and history in our repository as
  10.137 +they do in the repository we cloned.
  10.138 +
  10.139 +Every Mercurial repository is complete, self-contained, and
  10.140 +independent.  It contains its own private copy of a project's files
  10.141 +and history.  A cloned repository remembers the location of the
  10.142 +repository it was cloned from, but it does not communicate with that
  10.143 +repository, or any other, unless you tell it to.
  10.144 +
  10.145 +What this means for now is that we're free to experiment with our
  10.146 +repository, safe in the knowledge that it's a private ``sandbox'' that
  10.147 +won't affect anyone else.
  10.148 +
  10.149 +\subsection{What's in a repository?}
  10.150 +
  10.151 +When we take a more detailed look inside a repository, we can see that
  10.152 +it contains a directory named \dirname{.hg}.  This is where Mercurial
  10.153 +keeps all of its metadata for the repository.
  10.154 +\interaction{tour.ls-a}
  10.155 +
  10.156 +The contents of the \dirname{.hg} directory and its subdirectories are
  10.157 +private to Mercurial.  Every other file and directory in the
  10.158 +repository is yours to do with as you please.
  10.159 +
  10.160 +To introduce a little terminology, the \dirname{.hg} directory is the
  10.161 +``real'' repository, and all of the files and directories that coexist
  10.162 +with it are said to live in the \emph{working directory}.  An easy way
  10.163 +to remember the distinction is that the \emph{repository} contains the
  10.164 +\emph{history} of your project, while the \emph{working directory}
  10.165 +contains a \emph{snapshot} of your project at a particular point in
  10.166 +history.
  10.167 +
  10.168 +\section{A tour through history}
  10.169 +
  10.170 +One of the first things we might want to do with a new, unfamiliar
  10.171 +repository is understand its history.  The \hgcmd{log} command gives
  10.172 +us a view of history.
  10.173 +\interaction{tour.log}
  10.174 +By default, this command prints a brief paragraph of output for each
  10.175 +change to the project that was recorded.  In Mercurial terminology, we
  10.176 +call each of these recorded events a \emph{changeset}, because it can
  10.177 +contain a record of changes to several files.
  10.178 +
  10.179 +The fields in a record of output from \hgcmd{log} are as follows.
  10.180 +\begin{itemize}
  10.181 +\item[\texttt{changeset}] This field has the format of a number,
  10.182 +  followed by a colon, followed by a hexadecimal string.  These are
  10.183 +  \emph{identifiers} for the changeset.  There are two identifiers
  10.184 +  because the number is shorter and easier to type than the hex
  10.185 +  string.
  10.186 +\item[\texttt{user}] The identity of the person who created the
  10.187 +  changeset.  This is a free-form field, but it most often contains a
  10.188 +  person's name and email address.
  10.189 +\item[\texttt{date}] The date and time on which the changeset was
  10.190 +  created, and the timezone in which it was created.  (The date and
  10.191 +  time are local to that timezone; they display what time and date it
  10.192 +  was for the person who created the changeset.)
  10.193 +\item[\texttt{summary}] The first line of the text message that the
  10.194 +  creator of the changeset entered to describe the changeset.
  10.195 +\end{itemize}
  10.196 +The default output printed by \hgcmd{log} is purely a summary; it is
  10.197 +missing a lot of detail.
  10.198 +
  10.199 +Figure~\ref{fig:tour-basic:history} provides a graphical representation of
  10.200 +the history of the \dirname{hello} repository, to make it a little
  10.201 +easier to see which direction history is ``flowing'' in.  We'll be
  10.202 +returning to this figure several times in this chapter and the chapter
  10.203 +that follows.
  10.204 +
  10.205 +\begin{figure}[ht]
  10.206 +  \centering
  10.207 +  \grafix{tour-history}
  10.208 +  \caption{Graphical history of the \dirname{hello} repository}
  10.209 +  \label{fig:tour-basic:history}
  10.210 +\end{figure}
  10.211 +
  10.212 +\subsection{Changesets, revisions, and talking to other 
  10.213 +  people}
  10.214 +
  10.215 +As English is a notoriously sloppy language, and computer science has
  10.216 +a hallowed history of terminological confusion (why use one term when
  10.217 +four will do?), revision control has a variety of words and phrases
  10.218 +that mean the same thing.  If you are talking about Mercurial history
  10.219 +with other people, you will find that the word ``changeset'' is often
  10.220 +compressed to ``change'' or (when written) ``cset'', and sometimes a
  10.221 +changeset is referred to as a ``revision'' or a ``rev''.
  10.222 +
  10.223 +While it doesn't matter what \emph{word} you use to refer to the
  10.224 +concept of ``a~changeset'', the \emph{identifier} that you use to
  10.225 +refer to ``a~\emph{specific} changeset'' is of great importance.
  10.226 +Recall that the \texttt{changeset} field in the output from
  10.227 +\hgcmd{log} identifies a changeset using both a number and a
  10.228 +hexadecimal string.
  10.229 +\begin{itemize}
  10.230 +\item The revision number is \emph{only valid in that repository},
  10.231 +\item while the hex string is the \emph{permanent, unchanging
  10.232 +    identifier} that will always identify that exact changeset in
  10.233 +  \emph{every} copy of the repository.
  10.234 +\end{itemize}
  10.235 +This distinction is important.  If you send someone an email talking
  10.236 +about ``revision~33'', there's a high likelihood that their
  10.237 +revision~33 will \emph{not be the same} as yours.  The reason for this
  10.238 +is that a revision number depends on the order in which changes
  10.239 +arrived in a repository, and there is no guarantee that the same
  10.240 +changes will happen in the same order in different repositories.
  10.241 +Three changes $a,b,c$ can easily appear in one repository as $0,1,2$,
  10.242 +while in another as $1,0,2$.
  10.243 +
  10.244 +Mercurial uses revision numbers purely as a convenient shorthand.  If
  10.245 +you need to discuss a changeset with someone, or make a record of a
  10.246 +changeset for some other reason (for example, in a bug report), use
  10.247 +the hexadecimal identifier.
  10.248 +
  10.249 +\subsection{Viewing specific revisions}
  10.250 +
  10.251 +To narrow the output of \hgcmd{log} down to a single revision, use the
  10.252 +\hgopt{log}{-r} (or \hgopt{log}{--rev}) option.  You can use either a
  10.253 +revision number or a long-form changeset identifier, and you can
  10.254 +provide as many revisions as you want.  \interaction{tour.log-r}
  10.255 +
  10.256 +If you want to see the history of several revisions without having to
  10.257 +list each one, you can use \emph{range notation}; this lets you
  10.258 +express the idea ``I want all revisions between $a$ and $b$,
  10.259 +inclusive''.
  10.260 +\interaction{tour.log.range}
  10.261 +Mercurial also honours the order in which you specify revisions, so
  10.262 +\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
  10.263 +prints $4,3,2$.
  10.264 +
  10.265 +\subsection{More detailed information}
  10.266 +
  10.267 +While the summary information printed by \hgcmd{log} is useful if you
  10.268 +already know what you're looking for, you may need to see a complete
  10.269 +description of the change, or a list of the files changed, if you're
  10.270 +trying to decide whether a changeset is the one you're looking for.
  10.271 +The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose})
  10.272 +option gives you this extra detail.
  10.273 +\interaction{tour.log-v}
  10.274 +
  10.275 +If you want to see both the description and content of a change, add
  10.276 +the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option.  This displays
  10.277 +the content of a change as a \emph{unified diff} (if you've never seen
  10.278 +a unified diff before, see section~\ref{sec:mq:patch} for an overview).
  10.279 +\interaction{tour.log-vp}
  10.280 +
  10.281 +\section{All about command options}
  10.282 +
  10.283 +Let's take a brief break from exploring Mercurial commands to discuss
  10.284 +a pattern in the way that they work; you may find this useful to keep
  10.285 +in mind as we continue our tour.
  10.286 +
  10.287 +Mercurial has a consistent and straightforward approach to dealing
  10.288 +with the options that you can pass to commands.  It follows the
  10.289 +conventions for options that are common to modern Linux and Unix
  10.290 +systems.
  10.291 +\begin{itemize}
  10.292 +\item Every option has a long name.  For example, as we've already
  10.293 +  seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
  10.294 +\item Most options have short names, too.  Instead of
  10.295 +  \hgopt{log}{--rev}, we can use \hgopt{log}{-r}.  (The reason that
  10.296 +  some options don't have short names is that the options in question
  10.297 +  are rarely used.)
  10.298 +\item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
  10.299 +  while short options start with one (e.g.~\hgopt{log}{-r}).
  10.300 +\item Option naming and usage is consistent across commands.  For
  10.301 +  example, every command that lets you specify a changeset~ID or
  10.302 +  revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
  10.303 +  arguments.
  10.304 +\end{itemize}
  10.305 +In the examples throughout this book, I use short options instead of
  10.306 +long.  This just reflects my own preference, so don't read anything
  10.307 +significant into it.
  10.308 +
  10.309 +Most commands that print output of some kind will print more output
  10.310 +when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
  10.311 +when passed \hggopt{-q} (or \hggopt{--quiet}).
  10.312 +
  10.313 +\section{Making and reviewing changes}
  10.314 +
  10.315 +Now that we have a grasp of viewing history in Mercurial, let's take a
  10.316 +look at making some changes and examining them.
  10.317 +
  10.318 +The first thing we'll do is isolate our experiment in a repository of
  10.319 +its own.  We use the \hgcmd{clone} command, but we don't need to
  10.320 +clone a copy of the remote repository.  Since we already have a copy
  10.321 +of it locally, we can just clone that instead.  This is much faster
  10.322 +than cloning over the network, and cloning a local repository uses
  10.323 +less disk space in most cases, too.
  10.324 +\interaction{tour.reclone}
  10.325 +As an aside, it's often good practice to keep a ``pristine'' copy of a
  10.326 +remote repository around, which you can then make temporary clones of
  10.327 +to create sandboxes for each task you want to work on.  This lets you
  10.328 +work on multiple tasks in parallel, each isolated from the others
  10.329 +until it's complete and you're ready to integrate it back.  Because
  10.330 +local clones are so cheap, there's almost no overhead to cloning and
  10.331 +destroying repositories whenever you want.
  10.332 +
  10.333 +In our \dirname{my-hello} repository, we have a file
  10.334 +\filename{hello.c} that contains the classic ``hello, world'' program.
  10.335 +Let's use the ancient and venerable \command{sed} command to edit this
  10.336 +file so that it prints a second line of output.  (I'm only using
  10.337 +\command{sed} to do this because it's easy to write a scripted example
  10.338 +this way.  Since you're not under the same constraint, you probably
  10.339 +won't want to use \command{sed}; simply use your preferred text editor to
  10.340 +do the same thing.)
  10.341 +\interaction{tour.sed}
  10.342 +
  10.343 +Mercurial's \hgcmd{status} command will tell us what Mercurial knows
  10.344 +about the files in the repository.
  10.345 +\interaction{tour.status}
  10.346 +The \hgcmd{status} command prints no output for some files, but a line
  10.347 +starting with ``\texttt{M}'' for \filename{hello.c}.  Unless you tell
  10.348 +it to, \hgcmd{status} will not print any output for files that have
  10.349 +not been modified.  
  10.350 +
  10.351 +The ``\texttt{M}'' indicates that Mercurial has noticed that we
  10.352 +modified \filename{hello.c}.  We didn't need to \emph{inform}
  10.353 +Mercurial that we were going to modify the file before we started, or
  10.354 +that we had modified the file after we were done; it was able to
  10.355 +figure this out itself.
  10.356 +
  10.357 +It's a little bit helpful to know that we've modified
  10.358 +\filename{hello.c}, but we might prefer to know exactly \emph{what}
  10.359 +changes we've made to it.  To do this, we use the \hgcmd{diff}
  10.360 +command.
  10.361 +\interaction{tour.diff}
  10.362 +
  10.363 +\section{Recording changes in a new changeset}
  10.364 +
  10.365 +We can modify files, build and test our changes, and use
  10.366 +\hgcmd{status} and \hgcmd{diff} to review our changes, until we're
  10.367 +satisfied with what we've done and arrive at a natural stopping point
  10.368 +where we want to record our work in a new changeset.
  10.369 +
  10.370 +The \hgcmd{commit} command lets us create a new changeset; we'll
  10.371 +usually refer to this as ``making a commit'' or ``committing''.  
  10.372 +
  10.373 +\subsection{Setting up a username}
  10.374 +
  10.375 +When you try to run \hgcmd{commit} for the first time, it is not
  10.376 +guaranteed to succeed.  Mercurial records your name and address with
  10.377 +each change that you commit, so that you and others will later be able
  10.378 +to tell who made each change.  Mercurial tries to automatically figure
  10.379 +out a sensible username to commit the change with.  It will attempt
  10.380 +each of the following methods, in order:
  10.381 +\begin{enumerate}
  10.382 +\item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit}
  10.383 +  command on the command line, followed by a username, this is always
  10.384 +  given the highest precedence.
  10.385 +\item If you have set the \envar{HGUSER} environment variable, this is
  10.386 +  checked next.
  10.387 +\item If you create a file in your home directory called
  10.388 +  \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be
  10.389 +  used next.  To see what the contents of this file should look like,
  10.390 +  refer to section~\ref{sec:tour-basic:username} below.
  10.391 +\item If you have set the \envar{EMAIL} environment variable, this
  10.392 +  will be used next.
  10.393 +\item Mercurial will query your system to find out your local user
  10.394 +  name and host name, and construct a username from these components.
  10.395 +  Since this often results in a username that is not very useful, it
  10.396 +  will print a warning if it has to do this.
  10.397 +\end{enumerate}
  10.398 +If all of these mechanisms fail, Mercurial will fail, printing an
  10.399 +error message.  In this case, it will not let you commit until you set
  10.400 +up a username.
  10.401 +
  10.402 +You should think of the \envar{HGUSER} environment variable and the
  10.403 +\hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to
  10.404 +\emph{override} Mercurial's default selection of username.  For normal
  10.405 +use, the simplest and most robust way to set a username for yourself
  10.406 +is by creating a \sfilename{.hgrc} file; see below for details.
  10.407 +
  10.408 +\subsubsection{Creating a Mercurial configuration file}
  10.409 +\label{sec:tour-basic:username}
  10.410 +
  10.411 +To set a user name, use your favourite editor to create a file called
  10.412 +\sfilename{.hgrc} in your home directory.  Mercurial will use this
  10.413 +file to look up your personalised configuration settings.  The initial
  10.414 +contents of your \sfilename{.hgrc} should look like this.
  10.415 +\begin{codesample2}
  10.416 +  # This is a Mercurial configuration file.
  10.417 +  [ui]
  10.418 +  username = Firstname Lastname <email.address@domain.net>
  10.419 +\end{codesample2}
  10.420 +The ``\texttt{[ui]}'' line begins a \emph{section} of the config file,
  10.421 +so you can read the ``\texttt{username = ...}'' line as meaning ``set
  10.422 +the value of the \texttt{username} item in the \texttt{ui} section''.
  10.423 +A section continues until a new section begins, or the end of the
  10.424 +file.  Mercurial ignores empty lines and treats any text from
  10.425 +``\texttt{\#}'' to the end of a line as a comment.
  10.426 +
  10.427 +\subsubsection{Choosing a user name}
  10.428 +
  10.429 +You can use any text you like as the value of the \texttt{username}
  10.430 +config item, since this information is for reading by other people,
  10.431 +but for interpreting by Mercurial.  The convention that most people
  10.432 +follow is to use their name and email address, as in the example
  10.433 +above.
  10.434 +
  10.435 +\begin{note}
  10.436 +  Mercurial's built-in web server obfuscates email addresses, to make
  10.437 +  it more difficult for the email harvesting tools that spammers use.
  10.438 +  This reduces the likelihood that you'll start receiving more junk
  10.439 +  email if you publish a Mercurial repository on the web.
  10.440 +\end{note}
  10.441 +
  10.442 +\subsection{Writing a commit message}
  10.443 +
  10.444 +When we commit a change, Mercurial drops us into a text editor, to
  10.445 +enter a message that will describe the modifications we've made in
  10.446 +this changeset.  This is called the \emph{commit message}.  It will be
  10.447 +a record for readers of what we did and why, and it will be printed by
  10.448 +\hgcmd{log} after we've finished committing.
  10.449 +\interaction{tour.commit}
  10.450 +
  10.451 +The editor that the \hgcmd{commit} command drops us into will contain
  10.452 +an empty line, followed by a number of lines starting with
  10.453 +``\texttt{HG:}''.
  10.454 +\begin{codesample2}
  10.455 +  \emph{empty line}
  10.456 +  HG: changed hello.c
  10.457 +\end{codesample2}
  10.458 +Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
  10.459 +them only to tell us which files it's recording changes to.  Modifying
  10.460 +or deleting these lines has no effect.
  10.461 +
  10.462 +\subsection{Writing a good commit message}
  10.463 +
  10.464 +Since \hgcmd{log} only prints the first line of a commit message by
  10.465 +default, it's best to write a commit message whose first line stands
  10.466 +alone.  Here's a real example of a commit message that \emph{doesn't}
  10.467 +follow this guideline, and hence has a summary that is not readable.
  10.468 +\begin{codesample2}
  10.469 +  changeset:   73:584af0e231be
  10.470 +  user:        Censored Person <censored.person@example.org>
  10.471 +  date:        Tue Sep 26 21:37:07 2006 -0700
  10.472 +  summary:     include buildmeister/commondefs.   Add an exports and install
  10.473 +\end{codesample2}
  10.474 +
  10.475 +As far as the remainder of the contents of the commit message are
  10.476 +concerned, there are no hard-and-fast rules.  Mercurial itself doesn't
  10.477 +interpret or care about the contents of the commit message, though
  10.478 +your project may have policies that dictate a certain kind of
  10.479 +formatting.
  10.480 +
  10.481 +My personal preference is for short, but informative, commit messages
  10.482 +that tell me something that I can't figure out with a quick glance at
  10.483 +the output of \hgcmdargs{log}{--patch}.
  10.484 +
  10.485 +\subsection{Aborting a commit}
  10.486 +
  10.487 +If you decide that you don't want to commit while in the middle of
  10.488 +editing a commit message, simply exit from your editor without saving
  10.489 +the file that it's editing.  This will cause nothing to happen to
  10.490 +either the repository or the working directory.
  10.491 +
  10.492 +If we run the \hgcmd{commit} command without any arguments, it records
  10.493 +all of the changes we've made, as reported by \hgcmd{status} and
  10.494 +\hgcmd{diff}.
  10.495 +
  10.496 +\subsection{Admiring our new handiwork}
  10.497 +
  10.498 +Once we've finished the commit, we can use the \hgcmd{tip} command to
  10.499 +display the changeset we just created.  This command produces output
  10.500 +that is identical to \hgcmd{log}, but it only displays the newest
  10.501 +revision in the repository.
  10.502 +\interaction{tour.tip}
  10.503 +We refer to the newest revision in the repository as the tip revision,
  10.504 +or simply the tip.
  10.505 +
  10.506 +\section{Sharing changes}
  10.507 +
  10.508 +We mentioned earlier that repositories in Mercurial are
  10.509 +self-contained.  This means that the changeset we just created exists
  10.510 +only in our \dirname{my-hello} repository.  Let's look at a few ways
  10.511 +that we can propagate this change into other repositories.
  10.512 +
  10.513 +\subsection{Pulling changes from another repository}
  10.514 +\label{sec:tour:pull}
  10.515 +
  10.516 +To get started, let's clone our original \dirname{hello} repository,
  10.517 +which does not contain the change we just committed.  We'll call our
  10.518 +temporary repository \dirname{hello-pull}.
  10.519 +\interaction{tour.clone-pull}
  10.520 +
  10.521 +We'll use the \hgcmd{pull} command to bring changes from
  10.522 +\dirname{my-hello} into \dirname{hello-pull}.  However, blindly
  10.523 +pulling unknown changes into a repository is a somewhat scary
  10.524 +prospect.  Mercurial provides the \hgcmd{incoming} command to tell us
  10.525 +what changes the \hgcmd{pull} command \emph{would} pull into the
  10.526 +repository, without actually pulling the changes in.
  10.527 +\interaction{tour.incoming}
  10.528 +(Of course, someone could cause more changesets to appear in the
  10.529 +repository that we ran \hgcmd{incoming} in, before we get a chance to
  10.530 +\hgcmd{pull} the changes, so that we could end up pulling changes that we
  10.531 +didn't expect.)
  10.532 +
  10.533 +Bringing changes into a repository is a simple matter of running the
  10.534 +\hgcmd{pull} command, and telling it which repository to pull from.
  10.535 +\interaction{tour.pull}
  10.536 +As you can see from the before-and-after output of \hgcmd{tip}, we
  10.537 +have successfully pulled changes into our repository.  There remains
  10.538 +one step before we can see these changes in the working directory.
  10.539 +
  10.540 +\subsection{Updating the working directory}
  10.541 +
  10.542 +We have so far glossed over the relationship between a repository and
  10.543 +its working directory.  The \hgcmd{pull} command that we ran in
  10.544 +section~\ref{sec:tour:pull} brought changes into the repository, but
  10.545 +if we check, there's no sign of those changes in the working
  10.546 +directory.  This is because \hgcmd{pull} does not (by default) touch
  10.547 +the working directory.  Instead, we use the \hgcmd{update} command to
  10.548 +do this.
  10.549 +\interaction{tour.update}
  10.550 +
  10.551 +It might seem a bit strange that \hgcmd{pull} doesn't update the
  10.552 +working directory automatically.  There's actually a good reason for
  10.553 +this: you can use \hgcmd{update} to update the working directory to
  10.554 +the state it was in at \emph{any revision} in the history of the
  10.555 +repository.  If you had the working directory updated to an old
  10.556 +revision---to hunt down the origin of a bug, say---and ran a
  10.557 +\hgcmd{pull} which automatically updated the working directory to a
  10.558 +new revision, you might not be terribly happy.
  10.559 +
  10.560 +However, since pull-then-update is such a common thing to do,
  10.561 +Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
  10.562 +option to \hgcmd{pull}.
  10.563 +\begin{codesample2}
  10.564 +  hg pull -u
  10.565 +\end{codesample2}
  10.566 +If you look back at the output of \hgcmd{pull} in
  10.567 +section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
  10.568 +you can see that it printed a helpful reminder that we'd have to take
  10.569 +an explicit step to update the working directory:
  10.570 +\begin{codesample2}
  10.571 +  (run 'hg update' to get a working copy)
  10.572 +\end{codesample2}
  10.573 +
  10.574 +To find out what revision the working directory is at, use the
  10.575 +\hgcmd{parents} command.
  10.576 +\interaction{tour.parents}
  10.577 +If you look back at figure~\ref{fig:tour-basic:history}, you'll see
  10.578 +arrows connecting each changeset.  The node that the arrow leads
  10.579 +\emph{from} in each case is a parent, and the node that the arrow
  10.580 +leads \emph{to} is its child.  The working directory has a parent in
  10.581 +just the same way; this is the changeset that the working directory
  10.582 +currently contains.
  10.583 +
  10.584 +To update the working directory to a particular revision, give a
  10.585 +revision number or changeset~ID to the \hgcmd{update} command.
  10.586 +\interaction{tour.older}
  10.587 +If you omit an explicit revision, \hgcmd{update} will update to the
  10.588 +tip revision, as shown by the second call to \hgcmd{update} in the
  10.589 +example above.
  10.590 +
  10.591 +\subsection{Pushing changes to another repository}
  10.592 +
  10.593 +Mercurial lets us push changes to another repository, from the
  10.594 +repository we're currently visiting.  As with the example of
  10.595 +\hgcmd{pull} above, we'll create a temporary repository to push our
  10.596 +changes into.
  10.597 +\interaction{tour.clone-push}
  10.598 +The \hgcmd{outgoing} command tells us what changes would be pushed
  10.599 +into another repository.
  10.600 +\interaction{tour.outgoing}
  10.601 +And the \hgcmd{push} command does the actual push.
  10.602 +\interaction{tour.push}
  10.603 +As with \hgcmd{pull}, the \hgcmd{push} command does not update the
  10.604 +working directory in the repository that it's pushing changes into.
  10.605 +(Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
  10.606 +option that updates the other repository's working directory.)
  10.607 +
  10.608 +What happens if we try to pull or push changes and the receiving
  10.609 +repository already has those changes?  Nothing too exciting.
  10.610 +\interaction{tour.push.nothing}
  10.611 +
  10.612 +\subsection{Sharing changes over a network}
  10.613 +
  10.614 +The commands we have covered in the previous few sections are not
  10.615 +limited to working with local repositories.  Each works in exactly the
  10.616 +same fashion over a network connection; simply pass in a URL instead
  10.617 +of a local path.
  10.618 +\interaction{tour.outgoing.net}
  10.619 +In this example, we can see what changes we could push to the remote
  10.620 +repository, but the repository is understandably not set up to let
  10.621 +anonymous users push to it.
  10.622 +\interaction{tour.push.net}
  10.623 +
  10.624 +%%% Local Variables: 
  10.625 +%%% mode: latex
  10.626 +%%% TeX-master: "00book"
  10.627 +%%% End: 

    11.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    11.2 +++ b/en/ch03-tour-merge.tex	Thu Jan 29 22:56:27 2009 -0800
    11.3 @@ -0,0 +1,286 @@
    11.4 +\chapter{A tour of Mercurial: merging work}
    11.5 +\label{chap:tour-merge}
    11.6 +
    11.7 +We've now covered cloning a repository, making changes in a
    11.8 +repository, and pulling or pushing changes from one repository into
    11.9 +another.  Our next step is \emph{merging} changes from separate
   11.10 +repositories.
   11.11 +
   11.12 +\section{Merging streams of work}
   11.13 +
   11.14 +Merging is a fundamental part of working with a distributed revision
   11.15 +control tool.
   11.16 +\begin{itemize}
   11.17 +\item Alice and Bob each have a personal copy of a repository for a
   11.18 +  project they're collaborating on.  Alice fixes a bug in her
   11.19 +  repository; Bob adds a new feature in his.  They want the shared
   11.20 +  repository to contain both the bug fix and the new feature.
   11.21 +\item I frequently work on several different tasks for a single
   11.22 +  project at once, each safely isolated in its own repository.
   11.23 +  Working this way means that I often need to merge one piece of my
   11.24 +  own work with another.
   11.25 +\end{itemize}
   11.26 +
   11.27 +Because merging is such a common thing to need to do, Mercurial makes
   11.28 +it easy.  Let's walk through the process.  We'll begin by cloning yet
   11.29 +another repository (see how often they spring up?) and making a change
   11.30 +in it.
   11.31 +\interaction{tour.merge.clone}
   11.32 +We should now have two copies of \filename{hello.c} with different
   11.33 +contents.  The histories of the two repositories have also diverged,
   11.34 +as illustrated in figure~\ref{fig:tour-merge:sep-repos}.
   11.35 +\interaction{tour.merge.cat}
   11.36 +
   11.37 +\begin{figure}[ht]
   11.38 +  \centering
   11.39 +  \grafix{tour-merge-sep-repos}
   11.40 +  \caption{Divergent recent histories of the \dirname{my-hello} and
   11.41 +    \dirname{my-new-hello} repositories}
   11.42 +  \label{fig:tour-merge:sep-repos}
   11.43 +\end{figure}
   11.44 +
   11.45 +We already know that pulling changes from our \dirname{my-hello}
   11.46 +repository will have no effect on the working directory.
   11.47 +\interaction{tour.merge.pull}
   11.48 +However, the \hgcmd{pull} command says something about ``heads''.  
   11.49 +
   11.50 +\subsection{Head changesets}
   11.51 +
   11.52 +A head is a change that has no descendants, or children, as they're
   11.53 +also known.  The tip revision is thus a head, because the newest
   11.54 +revision in a repository doesn't have any children, but a repository
   11.55 +can contain more than one head.
   11.56 +
   11.57 +\begin{figure}[ht]
   11.58 +  \centering
   11.59 +  \grafix{tour-merge-pull}
   11.60 +  \caption{Repository contents after pulling from \dirname{my-hello} into
   11.61 +    \dirname{my-new-hello}}
   11.62 +  \label{fig:tour-merge:pull}
   11.63 +\end{figure}
   11.64 +
   11.65 +In figure~\ref{fig:tour-merge:pull}, you can see the effect of the
   11.66 +pull from \dirname{my-hello} into \dirname{my-new-hello}.  The history
   11.67 +that was already present in \dirname{my-new-hello} is untouched, but a
   11.68 +new revision has been added.  By referring to
   11.69 +figure~\ref{fig:tour-merge:sep-repos}, we can see that the
   11.70 +\emph{changeset ID} remains the same in the new repository, but the
   11.71 +\emph{revision number} has changed.  (This, incidentally, is a fine
   11.72 +example of why it's not safe to use revision numbers when discussing
   11.73 +changesets.)  We can view the heads in a repository using the
   11.74 +\hgcmd{heads} command.
   11.75 +\interaction{tour.merge.heads}
   11.76 +
   11.77 +\subsection{Performing the merge}
   11.78 +
   11.79 +What happens if we try to use the normal \hgcmd{update} command to
   11.80 +update to the new tip?
   11.81 +\interaction{tour.merge.update}
   11.82 +Mercurial is telling us that the \hgcmd{update} command won't do a
   11.83 +merge; it won't update the working directory when it thinks we might
   11.84 +be wanting to do a merge, unless we force it to do so.  Instead, we
   11.85 +use the \hgcmd{merge} command to merge the two heads.
   11.86 +\interaction{tour.merge.merge}
   11.87 +
   11.88 +\begin{figure}[ht]
   11.89 +  \centering
   11.90 +  \grafix{tour-merge-merge}
   11.91 +  \caption{Working directory and repository during merge, and
   11.92 +    following commit}
   11.93 +  \label{fig:tour-merge:merge}
   11.94 +\end{figure}
   11.95 +
   11.96 +This updates the working directory so that it contains changes from
   11.97 +\emph{both} heads, which is reflected in both the output of
   11.98 +\hgcmd{parents} and the contents of \filename{hello.c}.
   11.99 +\interaction{tour.merge.parents}
  11.100 +
  11.101 +\subsection{Committing the results of the merge}
  11.102 +
  11.103 +Whenever we've done a merge, \hgcmd{parents} will display two parents
  11.104 +until we \hgcmd{commit} the results of the merge.
  11.105 +\interaction{tour.merge.commit}
  11.106 +We now have a new tip revision; notice that it has \emph{both} of
  11.107 +our former heads as its parents.  These are the same revisions that
  11.108 +were previously displayed by \hgcmd{parents}.
  11.109 +\interaction{tour.merge.tip}
  11.110 +In figure~\ref{fig:tour-merge:merge}, you can see a representation of
  11.111 +what happens to the working directory during the merge, and how this
  11.112 +affects the repository when the commit happens.  During the merge, the
  11.113 +working directory has two parent changesets, and these become the
  11.114 +parents of the new changeset.
  11.115 +
  11.116 +\section{Merging conflicting changes}
  11.117 +
  11.118 +Most merges are simple affairs, but sometimes you'll find yourself
  11.119 +merging changes where each modifies the same portions of the same
  11.120 +files.  Unless both modifications are identical, this results in a
  11.121 +\emph{conflict}, where you have to decide how to reconcile the
  11.122 +different changes into something coherent.
  11.123 +
  11.124 +\begin{figure}[ht]
  11.125 +  \centering
  11.126 +  \grafix{tour-merge-conflict}
  11.127 +  \caption{Conflicting changes to a document}
  11.128 +  \label{fig:tour-merge:conflict}
  11.129 +\end{figure}
  11.130 +
  11.131 +Figure~\ref{fig:tour-merge:conflict} illustrates an instance of two
  11.132 +conflicting changes to a document.  We started with a single version
  11.133 +of the file; then we made some changes; while someone else made
  11.134 +different changes to the same text.  Our task in resolving the
  11.135 +conflicting changes is to decide what the file should look like.
  11.136 +
  11.137 +Mercurial doesn't have a built-in facility for handling conflicts.
  11.138 +Instead, it runs an external program called \command{hgmerge}.  This
  11.139 +is a shell script that is bundled with Mercurial; you can change it to
  11.140 +behave however you please.  What it does by default is try to find one
  11.141 +of several different merging tools that are likely to be installed on
  11.142 +your system.  It first tries a few fully automatic merging tools; if
  11.143 +these don't succeed (because the resolution process requires human
  11.144 +guidance) or aren't present, the script tries a few different
  11.145 +graphical merging tools.
  11.146 +
  11.147 +It's also possible to get Mercurial to run another program or script
  11.148 +instead of \command{hgmerge}, by setting the \envar{HGMERGE}
  11.149 +environment variable to the name of your preferred program.
  11.150 +
  11.151 +\subsection{Using a graphical merge tool}
  11.152 +
  11.153 +My preferred graphical merge tool is \command{kdiff3}, which I'll use
  11.154 +to describe the features that are common to graphical file merging
  11.155 +tools.  You can see a screenshot of \command{kdiff3} in action in
  11.156 +figure~\ref{fig:tour-merge:kdiff3}.  The kind of merge it is
  11.157 +performing is called a \emph{three-way merge}, because there are three
  11.158 +different versions of the file of interest to us.  The tool thus
  11.159 +splits the upper portion of the window into three panes:
  11.160 +\begin{itemize}
  11.161 +\item At the left is the \emph{base} version of the file, i.e.~the
  11.162 +  most recent version from which the two versions we're trying to
  11.163 +  merge are descended.
  11.164 +\item In the middle is ``our'' version of the file, with the contents
  11.165 +  that we modified.
  11.166 +\item On the right is ``their'' version of the file, the one that
  11.167 +  from the changeset that we're trying to merge with.
  11.168 +\end{itemize}
  11.169 +In the pane below these is the current \emph{result} of the merge.
  11.170 +Our task is to replace all of the red text, which indicates unresolved
  11.171 +conflicts, with some sensible merger of the ``ours'' and ``theirs''
  11.172 +versions of the file.
  11.173 +
  11.174 +All four of these panes are \emph{locked together}; if we scroll
  11.175 +vertically or horizontally in any of them, the others are updated to
  11.176 +display the corresponding sections of their respective files.
  11.177 +
  11.178 +\begin{figure}[ht]
  11.179 +  \centering
  11.180 +  \grafix{kdiff3}
  11.181 +  \caption{Using \command{kdiff3} to merge versions of a file}
  11.182 +  \label{fig:tour-merge:kdiff3}
  11.183 +\end{figure}
  11.184 +
  11.185 +For each conflicting portion of the file, we can choose to resolve
  11.186 +the conflict using some combination of text from the base version,
  11.187 +ours, or theirs.  We can also manually edit the merged file at any
  11.188 +time, in case we need to make further modifications.
  11.189 +
  11.190 +There are \emph{many} file merging tools available, too many to cover
  11.191 +here.  They vary in which platforms they are available for, and in
  11.192 +their particular strengths and weaknesses.  Most are tuned for merging
  11.193 +files containing plain text, while a few are aimed at specialised file
  11.194 +formats (generally XML).
  11.195 +
  11.196 +\subsection{A worked example}
  11.197 +
  11.198 +In this example, we will reproduce the file modification history of
  11.199 +figure~\ref{fig:tour-merge:conflict} above.  Let's begin by creating a
  11.200 +repository with a base version of our document.
  11.201 +\interaction{tour-merge-conflict.wife}
  11.202 +We'll clone the repository and make a change to the file.
  11.203 +\interaction{tour-merge-conflict.cousin}
  11.204 +And another clone, to simulate someone else making a change to the
  11.205 +file.  (This hints at the idea that it's not all that unusual to merge
  11.206 +with yourself when you isolate tasks in separate repositories, and
  11.207 +indeed to find and resolve conflicts while doing so.)
  11.208 +\interaction{tour-merge-conflict.son}
  11.209 +Having created two different versions of the file, we'll set up an
  11.210 +environment suitable for running our merge.
  11.211 +\interaction{tour-merge-conflict.pull}
  11.212 +
  11.213 +In this example, I won't use Mercurial's normal \command{hgmerge}
  11.214 +program to do the merge, because it would drop my nice automated
  11.215 +example-running tool into a graphical user interface.  Instead, I'll
  11.216 +set \envar{HGMERGE} to tell Mercurial to use the non-interactive
  11.217 +\command{merge} command.  This is bundled with many Unix-like systems.
  11.218 +If you're following this example on your computer, don't bother
  11.219 +setting \envar{HGMERGE}.
  11.220 +
  11.221 +\textbf{XXX FIX THIS EXAMPLE.}
  11.222 +
  11.223 +\interaction{tour-merge-conflict.merge}
  11.224 +Because \command{merge} can't resolve the conflicting changes, it
  11.225 +leaves \emph{merge markers} inside the file that has conflicts,
  11.226 +indicating which lines have conflicts, and whether they came from our
  11.227 +version of the file or theirs.
  11.228 +
  11.229 +Mercurial can tell from the way \command{merge} exits that it wasn't
  11.230 +able to merge successfully, so it tells us what commands we'll need to
  11.231 +run if we want to redo the merging operation.  This could be useful
  11.232 +if, for example, we were running a graphical merge tool and quit
  11.233 +because we were confused or realised we had made a mistake.
  11.234 +
  11.235 +If automatic or manual merges fail, there's nothing to prevent us from
  11.236 +``fixing up'' the affected files ourselves, and committing the results
  11.237 +of our merge:
  11.238 +\interaction{tour-merge-conflict.commit}
  11.239 +
  11.240 +\section{Simplifying the pull-merge-commit sequence}
  11.241 +\label{sec:tour-merge:fetch}
  11.242 +
  11.243 +The process of merging changes as outlined above is straightforward,
  11.244 +but requires running three commands in sequence.
  11.245 +\begin{codesample2}
  11.246 +  hg pull
  11.247 +  hg merge
  11.248 +  hg commit -m 'Merged remote changes'
  11.249 +\end{codesample2}
  11.250 +In the case of the final commit, you also need to enter a commit
  11.251 +message, which is almost always going to be a piece of uninteresting
  11.252 +``boilerplate'' text.
  11.253 +
  11.254 +It would be nice to reduce the number of steps needed, if this were
  11.255 +possible.  Indeed, Mercurial is distributed with an extension called
  11.256 +\hgext{fetch} that does just this.
  11.257 +
  11.258 +Mercurial provides a flexible extension mechanism that lets people
  11.259 +extend its functionality, while keeping the core of Mercurial small
  11.260 +and easy to deal with.  Some extensions add new commands that you can
  11.261 +use from the command line, while others work ``behind the scenes,''
  11.262 +for example adding capabilities to the server.
  11.263 +
  11.264 +The \hgext{fetch} extension adds a new command called, not
  11.265 +surprisingly, \hgcmd{fetch}.  This extension acts as a combination of
  11.266 +\hgcmd{pull}, \hgcmd{update} and \hgcmd{merge}.  It begins by pulling
  11.267 +changes from another repository into the current repository.  If it
  11.268 +finds that the changes added a new head to the repository, it begins a
  11.269 +merge, then commits the result of the merge with an
  11.270 +automatically-generated commit message.  If no new heads were added,
  11.271 +it updates the working directory to the new tip changeset.
  11.272 +
  11.273 +Enabling the \hgext{fetch} extension is easy.  Edit your
  11.274 +\sfilename{.hgrc}, and either go to the \rcsection{extensions} section
  11.275 +or create an \rcsection{extensions} section.  Then add a line that
  11.276 +simply reads ``\Verb+fetch +''.
  11.277 +\begin{codesample2}
  11.278 +  [extensions]
  11.279 +  fetch =
  11.280 +\end{codesample2}
  11.281 +(Normally, on the right-hand side of the ``\texttt{=}'' would appear
  11.282 +the location of the extension, but since the \hgext{fetch} extension
  11.283 +is in the standard distribution, Mercurial knows where to search for
  11.284 +it.)
  11.285 +
  11.286 +%%% Local Variables: 
  11.287 +%%% mode: latex
  11.288 +%%% TeX-master: "00book"
  11.289 +%%% End: 

    12.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    12.2 +++ b/en/ch04-concepts.tex	Thu Jan 29 22:56:27 2009 -0800
    12.3 @@ -0,0 +1,577 @@
    12.4 +\chapter{Behind the scenes}
    12.5 +\label{chap:concepts}
    12.6 +
    12.7 +Unlike many revision control systems, the concepts upon which
    12.8 +Mercurial is built are simple enough that it's easy to understand how
    12.9 +the software really works.  Knowing this certainly isn't necessary,
   12.10 +but I find it useful to have a ``mental model'' of what's going on.
   12.11 +
   12.12 +This understanding gives me confidence that Mercurial has been
   12.13 +carefully designed to be both \emph{safe} and \emph{efficient}.  And
   12.14 +just as importantly, if it's easy for me to retain a good idea of what
   12.15 +the software is doing when I perform a revision control task, I'm less
   12.16 +likely to be surprised by its behaviour.
   12.17 +
   12.18 +In this chapter, we'll initially cover the core concepts behind
   12.19 +Mercurial's design, then continue to discuss some of the interesting
   12.20 +details of its implementation.
   12.21 +
   12.22 +\section{Mercurial's historical record}
   12.23 +
   12.24 +\subsection{Tracking the history of a single file}
   12.25 +
   12.26 +When Mercurial tracks modifications to a file, it stores the history
   12.27 +of that file in a metadata object called a \emph{filelog}.  Each entry
   12.28 +in the filelog contains enough information to reconstruct one revision
   12.29 +of the file that is being tracked.  Filelogs are stored as files in
   12.30 +the \sdirname{.hg/store/data} directory.  A filelog contains two kinds
   12.31 +of information: revision data, and an index to help Mercurial to find
   12.32 +a revision efficiently.
   12.33 +
   12.34 +A file that is large, or has a lot of history, has its filelog stored
   12.35 +in separate data (``\texttt{.d}'' suffix) and index (``\texttt{.i}''
   12.36 +suffix) files.  For small files without much history, the revision
   12.37 +data and index are combined in a single ``\texttt{.i}'' file.  The
   12.38 +correspondence between a file in the working directory and the filelog
   12.39 +that tracks its history in the repository is illustrated in
   12.40 +figure~\ref{fig:concepts:filelog}.
   12.41 +
   12.42 +\begin{figure}[ht]
   12.43 +  \centering
   12.44 +  \grafix{filelog}
   12.45 +  \caption{Relationships between files in working directory and
   12.46 +    filelogs in repository}
   12.47 +  \label{fig:concepts:filelog}
   12.48 +\end{figure}
   12.49 +
   12.50 +\subsection{Managing tracked files}
   12.51 +
   12.52 +Mercurial uses a structure called a \emph{manifest} to collect
   12.53 +together information about the files that it tracks.  Each entry in
   12.54 +the manifest contains information about the files present in a single
   12.55 +changeset.  An entry records which files are present in the changeset,
   12.56 +the revision of each file, and a few other pieces of file metadata.
   12.57 +
   12.58 +\subsection{Recording changeset information}
   12.59 +
   12.60 +The \emph{changelog} contains information about each changeset.  Each
   12.61 +revision records who committed a change, the changeset comment, other
   12.62 +pieces of changeset-related information, and the revision of the
   12.63 +manifest to use.
   12.64 +
   12.65 +\subsection{Relationships between revisions}
   12.66 +
   12.67 +Within a changelog, a manifest, or a filelog, each revision stores a
   12.68 +pointer to its immediate parent (or to its two parents, if it's a
   12.69 +merge revision).  As I mentioned above, there are also relationships
   12.70 +between revisions \emph{across} these structures, and they are
   12.71 +hierarchical in nature.
   12.72 +
   12.73 +For every changeset in a repository, there is exactly one revision
   12.74 +stored in the changelog.  Each revision of the changelog contains a
   12.75 +pointer to a single revision of the manifest.  A revision of the
   12.76 +manifest stores a pointer to a single revision of each filelog tracked
   12.77 +when that changeset was created.  These relationships are illustrated
   12.78 +in figure~\ref{fig:concepts:metadata}.
   12.79 +
   12.80 +\begin{figure}[ht]
   12.81 +  \centering
   12.82 +  \grafix{metadata}
   12.83 +  \caption{Metadata relationships}
   12.84 +  \label{fig:concepts:metadata}
   12.85 +\end{figure}
   12.86 +
   12.87 +As the illustration shows, there is \emph{not} a ``one to one''
   12.88 +relationship between revisions in the changelog, manifest, or filelog.
   12.89 +If the manifest hasn't changed between two changesets, the changelog
   12.90 +entries for those changesets will point to the same revision of the
   12.91 +manifest.  If a file that Mercurial tracks hasn't changed between two
   12.92 +changesets, the entry for that file in the two revisions of the
   12.93 +manifest will point to the same revision of its filelog.
   12.94 +
   12.95 +\section{Safe, efficient storage}
   12.96 +
   12.97 +The underpinnings of changelogs, manifests, and filelogs are provided
   12.98 +by a single structure called the \emph{revlog}.
   12.99 +
  12.100 +\subsection{Efficient storage}
  12.101 +
  12.102 +The revlog provides efficient storage of revisions using a
  12.103 +\emph{delta} mechanism.  Instead of storing a complete copy of a file
  12.104 +for each revision, it stores the changes needed to transform an older
  12.105 +revision into the new revision.  For many kinds of file data, these
  12.106 +deltas are typically a fraction of a percent of the size of a full
  12.107 +copy of a file.
  12.108 +
  12.109 +Some obsolete revision control systems can only work with deltas of
  12.110 +text files.  They must either store binary files as complete snapshots
  12.111 +or encoded into a text representation, both of which are wasteful
  12.112 +approaches.  Mercurial can efficiently handle deltas of files with
  12.113 +arbitrary binary contents; it doesn't need to treat text as special.
  12.114 +
  12.115 +\subsection{Safe operation}
  12.116 +\label{sec:concepts:txn}
  12.117 +
  12.118 +Mercurial only ever \emph{appends} data to the end of a revlog file.
  12.119 +It never modifies a section of a file after it has written it.  This
  12.120 +is both more robust and efficient than schemes that need to modify or
  12.121 +rewrite data.
  12.122 +
  12.123 +In addition, Mercurial treats every write as part of a
  12.124 +\emph{transaction} that can span a number of files.  A transaction is
  12.125 +\emph{atomic}: either the entire transaction succeeds and its effects
  12.126 +are all visible to readers in one go, or the whole thing is undone.
  12.127 +This guarantee of atomicity means that if you're running two copies of
  12.128 +Mercurial, where one is reading data and one is writing it, the reader
  12.129 +will never see a partially written result that might confuse it.
  12.130 +
  12.131 +The fact that Mercurial only appends to files makes it easier to
  12.132 +provide this transactional guarantee.  The easier it is to do stuff
  12.133 +like this, the more confident you should be that it's done correctly.
  12.134 +
  12.135 +\subsection{Fast retrieval}
  12.136 +
  12.137 +Mercurial cleverly avoids a pitfall common to all earlier
  12.138 +revision control systems: the problem of \emph{inefficient retrieval}.
  12.139 +Most revision control systems store the contents of a revision as an
  12.140 +incremental series of modifications against a ``snapshot''.  To
  12.141 +reconstruct a specific revision, you must first read the snapshot, and
  12.142 +then every one of the revisions between the snapshot and your target
  12.143 +revision.  The more history that a file accumulates, the more
  12.144 +revisions you must read, hence the longer it takes to reconstruct a
  12.145 +particular revision.
  12.146 +
  12.147 +\begin{figure}[ht]
  12.148 +  \centering
  12.149 +  \grafix{snapshot}
  12.150 +  \caption{Snapshot of a revlog, with incremental deltas}
  12.151 +  \label{fig:concepts:snapshot}
  12.152 +\end{figure}
  12.153 +
  12.154 +The innovation that Mercurial applies to this problem is simple but
  12.155 +effective.  Once the cumulative amount of delta information stored
  12.156 +since the last snapshot exceeds a fixed threshold, it stores a new
  12.157 +snapshot (compressed, of course), instead of another delta.  This
  12.158 +makes it possible to reconstruct \emph{any} revision of a file
  12.159 +quickly.  This approach works so well that it has since been copied by
  12.160 +several other revision control systems.
  12.161 +
  12.162 +Figure~\ref{fig:concepts:snapshot} illustrates the idea.  In an entry
  12.163 +in a revlog's index file, Mercurial stores the range of entries from
  12.164 +the data file that it must read to reconstruct a particular revision.
  12.165 +
  12.166 +\subsubsection{Aside: the influence of video compression}
  12.167 +
  12.168 +If you're familiar with video compression or have ever watched a TV
  12.169 +feed through a digital cable or satellite service, you may know that
  12.170 +most video compression schemes store each frame of video as a delta
  12.171 +against its predecessor frame.  In addition, these schemes use
  12.172 +``lossy'' compression techniques to increase the compression ratio, so
  12.173 +visual errors accumulate over the course of a number of inter-frame
  12.174 +deltas.
  12.175 +
  12.176 +Because it's possible for a video stream to ``drop out'' occasionally
  12.177 +due to signal glitches, and to limit the accumulation of artefacts
  12.178 +introduced by the lossy compression process, video encoders
  12.179 +periodically insert a complete frame (called a ``key frame'') into the
  12.180 +video stream; the next delta is generated against that frame.  This
  12.181 +means that if the video signal gets interrupted, it will resume once
  12.182 +the next key frame is received.  Also, the accumulation of encoding
  12.183 +errors restarts anew with each key frame.
  12.184 +
  12.185 +\subsection{Identification and strong integrity}
  12.186 +
  12.187 +Along with delta or snapshot information, a revlog entry contains a
  12.188 +cryptographic hash of the data that it represents.  This makes it
  12.189 +difficult to forge the contents of a revision, and easy to detect
  12.190 +accidental corruption.  
  12.191 +
  12.192 +Hashes provide more than a mere check against corruption; they are
  12.193 +used as the identifiers for revisions.  The changeset identification
  12.194 +hashes that you see as an end user are from revisions of the
  12.195 +changelog.  Although filelogs and the manifest also use hashes,
  12.196 +Mercurial only uses these behind the scenes.
  12.197 +
  12.198 +Mercurial verifies that hashes are correct when it retrieves file
  12.199 +revisions and when it pulls changes from another repository.  If it
  12.200 +encounters an integrity problem, it will complain and stop whatever
  12.201 +it's doing.
  12.202 +
  12.203 +In addition to the effect it has on retrieval efficiency, Mercurial's
  12.204 +use of periodic snapshots makes it more robust against partial data
  12.205 +corruption.  If a revlog becomes partly corrupted due to a hardware
  12.206 +error or system bug, it's often possible to reconstruct some or most
  12.207 +revisions from the uncorrupted sections of the revlog, both before and
  12.208 +after the corrupted section.  This would not be possible with a
  12.209 +delta-only storage model.
  12.210 +
  12.211 +\section{Revision history, branching,
  12.212 +  and merging}
  12.213 +
  12.214 +Every entry in a Mercurial revlog knows the identity of its immediate
  12.215 +ancestor revision, usually referred to as its \emph{parent}.  In fact,
  12.216 +a revision contains room for not one parent, but two.  Mercurial uses
  12.217 +a special hash, called the ``null ID'', to represent the idea ``there
  12.218 +is no parent here''.  This hash is simply a string of zeroes.
  12.219 +
  12.220 +In figure~\ref{fig:concepts:revlog}, you can see an example of the
  12.221 +conceptual structure of a revlog.  Filelogs, manifests, and changelogs
  12.222 +all have this same structure; they differ only in the kind of data
  12.223 +stored in each delta or snapshot.
  12.224 +
  12.225 +The first revision in a revlog (at the bottom of the image) has the
  12.226 +null ID in both of its parent slots.  For a ``normal'' revision, its
  12.227 +first parent slot contains the ID of its parent revision, and its
  12.228 +second contains the null ID, indicating that the revision has only one
  12.229 +real parent.  Any two revisions that have the same parent ID are
  12.230 +branches.  A revision that represents a merge between branches has two
  12.231 +normal revision IDs in its parent slots.
  12.232 +
  12.233 +\begin{figure}[ht]
  12.234 +  \centering
  12.235 +  \grafix{revlog}
  12.236 +  \caption{}
  12.237 +  \label{fig:concepts:revlog}
  12.238 +\end{figure}
  12.239 +
  12.240 +\section{The working directory}
  12.241 +
  12.242 +In the working directory, Mercurial stores a snapshot of the files
  12.243 +from the repository as of a particular changeset.
  12.244 +
  12.245 +The working directory ``knows'' which changeset it contains.  When you
  12.246 +update the working directory to contain a particular changeset,
  12.247 +Mercurial looks up the appropriate revision of the manifest to find
  12.248 +out which files it was tracking at the time that changeset was
  12.249 +committed, and which revision of each file was then current.  It then
  12.250 +recreates a copy of each of those files, with the same contents it had
  12.251 +when the changeset was committed.
  12.252 +
  12.253 +The \emph{dirstate} contains Mercurial's knowledge of the working
  12.254 +directory.  This details which changeset the working directory is
  12.255 +updated to, and all of the files that Mercurial is tracking in the
  12.256 +working directory.
  12.257 +
  12.258 +Just as a revision of a revlog has room for two parents, so that it
  12.259 +can represent either a normal revision (with one parent) or a merge of
  12.260 +two earlier revisions, the dirstate has slots for two parents.  When
  12.261 +you use the \hgcmd{update} command, the changeset that you update to
  12.262 +is stored in the ``first parent'' slot, and the null ID in the second.
  12.263 +When you \hgcmd{merge} with another changeset, the first parent
  12.264 +remains unchanged, and the second parent is filled in with the
  12.265 +changeset you're merging with.  The \hgcmd{parents} command tells you
  12.266 +what the parents of the dirstate are.
  12.267 +
  12.268 +\subsection{What happens when you commit}
  12.269 +
  12.270 +The dirstate stores parent information for more than just book-keeping
  12.271 +purposes.  Mercurial uses the parents of the dirstate as \emph{the
  12.272 +  parents of a new changeset} when you perform a commit.
  12.273 +
  12.274 +\begin{figure}[ht]
  12.275 +  \centering
  12.276 +  \grafix{wdir}
  12.277 +  \caption{The working directory can have two parents}
  12.278 +  \label{fig:concepts:wdir}
  12.279 +\end{figure}
  12.280 +
  12.281 +Figure~\ref{fig:concepts:wdir} shows the normal state of the working
  12.282 +directory, where it has a single changeset as parent.  That changeset
  12.283 +is the \emph{tip}, the newest changeset in the repository that has no
  12.284 +children.
  12.285 +
  12.286 +\begin{figure}[ht]
  12.287 +  \centering
  12.288 +  \grafix{wdir-after-commit}
  12.289 +  \caption{The working directory gains new parents after a commit}
  12.290 +  \label{fig:concepts:wdir-after-commit}
  12.291 +\end{figure}
  12.292 +
  12.293 +It's useful to think of the working directory as ``the changeset I'm
  12.294 +about to commit''.  Any files that you tell Mercurial that you've
  12.295 +added, removed, renamed, or copied will be reflected in that
  12.296 +changeset, as will modifications to any files that Mercurial is
  12.297 +already tracking; the new changeset will have the parents of the
  12.298 +working directory as its parents.
  12.299 +
  12.300 +After a commit, Mercurial will update the parents of the working
  12.301 +directory, so that the first parent is the ID of the new changeset,
  12.302 +and the second is the null ID.  This is shown in
  12.303 +figure~\ref{fig:concepts:wdir-after-commit}.  Mercurial doesn't touch
  12.304 +any of the files in the working directory when you commit; it just
  12.305 +modifies the dirstate to note its new parents.
  12.306 +
  12.307 +\subsection{Creating a new head}
  12.308 +
  12.309 +It's perfectly normal to update the working directory to a changeset
  12.310 +other than the current tip.  For example, you might want to know what
  12.311 +your project looked like last Tuesday, or you could be looking through
  12.312 +changesets to see which one introduced a bug.  In cases like this, the
  12.313 +natural thing to do is update the working directory to the changeset
  12.314 +you're interested in, and then examine the files in the working
  12.315 +directory directly to see their contents as they were when you
  12.316 +committed that changeset.  The effect of this is shown in
  12.317 +figure~\ref{fig:concepts:wdir-pre-branch}.
  12.318 +
  12.319 +\begin{figure}[ht]
  12.320 +  \centering
  12.321 +  \grafix{wdir-pre-branch}
  12.322 +  \caption{The working directory, updated to an older changeset}
  12.323 +  \label{fig:concepts:wdir-pre-branch}
  12.324 +\end{figure}
  12.325 +
  12.326 +Having updated the working directory to an older changeset, what
  12.327 +happens if you make some changes, and then commit?  Mercurial behaves
  12.328 +in the same way as I outlined above.  The parents of the working
  12.329 +directory become the parents of the new changeset.  This new changeset
  12.330 +has no children, so it becomes the new tip.  And the repository now
  12.331 +contains two changesets that have no children; we call these
  12.332 +\emph{heads}.  You can see the structure that this creates in
  12.333 +figure~\ref{fig:concepts:wdir-branch}.
  12.334 +
  12.335 +\begin{figure}[ht]
  12.336 +  \centering
  12.337 +  \grafix{wdir-branch}
  12.338 +  \caption{After a commit made while synced to an older changeset}
  12.339 +  \label{fig:concepts:wdir-branch}
  12.340 +\end{figure}
  12.341 +
  12.342 +\begin{note}
  12.343 +  If you're new to Mercurial, you should keep in mind a common
  12.344 +  ``error'', which is to use the \hgcmd{pull} command without any
  12.345 +  options.  By default, the \hgcmd{pull} command \emph{does not}
  12.346 +  update the working directory, so you'll bring new changesets into
  12.347 +  your repository, but the working directory will stay synced at the
  12.348 +  same changeset as before the pull.  If you make some changes and
  12.349 +  commit afterwards, you'll thus create a new head, because your
  12.350 +  working directory isn't synced to whatever the current tip is.
  12.351 +
  12.352 +  I put the word ``error'' in quotes because all that you need to do
  12.353 +  to rectify this situation is \hgcmd{merge}, then \hgcmd{commit}.  In
  12.354 +  other words, this almost never has negative consequences; it just
  12.355 +  surprises people.  I'll discuss other ways to avoid this behaviour,
  12.356 +  and why Mercurial behaves in this initially surprising way, later
  12.357 +  on.
  12.358 +\end{note}
  12.359 +
  12.360 +\subsection{Merging heads}
  12.361 +
  12.362 +When you run the \hgcmd{merge} command, Mercurial leaves the first
  12.363 +parent of the working directory unchanged, and sets the second parent
  12.364 +to the changeset you're merging with, as shown in
  12.365 +figure~\ref{fig:concepts:wdir-merge}.
  12.366 +
  12.367 +\begin{figure}[ht]
  12.368 +  \centering
  12.369 +  \grafix{wdir-merge}
  12.370 +  \caption{Merging two heads}
  12.371 +  \label{fig:concepts:wdir-merge}
  12.372 +\end{figure}
  12.373 +
  12.374 +Mercurial also has to modify the working directory, to merge the files
  12.375 +managed in the two changesets.  Simplified a little, the merging
  12.376 +process goes like this, for every file in the manifests of both
  12.377 +changesets.
  12.378 +\begin{itemize}
  12.379 +\item If neither changeset has modified a file, do nothing with that
  12.380 +  file.
  12.381 +\item If one changeset has modified a file, and the other hasn't,
  12.382 +  create the modified copy of the file in the working directory.
  12.383 +\item If one changeset has removed a file, and the other hasn't (or
  12.384 +  has also deleted it), delete the file from the working directory.
  12.385 +\item If one changeset has removed a file, but the other has modified
  12.386 +  the file, ask the user what to do: keep the modified file, or remove
  12.387 +  it?
  12.388 +\item If both changesets have modified a file, invoke an external
  12.389 +  merge program to choose the new contents for the merged file.  This
  12.390 +  may require input from the user.
  12.391 +\item If one changeset has modified a file, and the other has renamed
  12.392 +  or copied the file, make sure that the changes follow the new name
  12.393 +  of the file.
  12.394 +\end{itemize}
  12.395 +There are more details---merging has plenty of corner cases---but
  12.396 +these are the most common choices that are involved in a merge.  As
  12.397 +you can see, most cases are completely automatic, and indeed most
  12.398 +merges finish automatically, without requiring your input to resolve
  12.399 +any conflicts.
  12.400 +
  12.401 +When you're thinking about what happens when you commit after a merge,
  12.402 +once again the working directory is ``the changeset I'm about to
  12.403 +commit''.  After the \hgcmd{merge} command completes, the working
  12.404 +directory has two parents; these will become the parents of the new
  12.405 +changeset.
  12.406 +
  12.407 +Mercurial lets you perform multiple merges, but you must commit the
  12.408 +results of each individual merge as you go.  This is necessary because
  12.409 +Mercurial only tracks two parents for both revisions and the working
  12.410 +directory.  While it would be technically possible to merge multiple
  12.411 +changesets at once, the prospect of user confusion and making a
  12.412 +terrible mess of a merge immediately becomes overwhelming.
  12.413 +
  12.414 +\section{Other interesting design features}
  12.415 +
  12.416 +In the sections above, I've tried to highlight some of the most
  12.417 +important aspects of Mercurial's design, to illustrate that it pays
  12.418 +careful attention to reliability and performance.  However, the
  12.419 +attention to detail doesn't stop there.  There are a number of other
  12.420 +aspects of Mercurial's construction that I personally find
  12.421 +interesting.  I'll detail a few of them here, separate from the ``big
  12.422 +ticket'' items above, so that if you're interested, you can gain a
  12.423 +better idea of the amount of thinking that goes into a well-designed
  12.424 +system.
  12.425 +
  12.426 +\subsection{Clever compression}
  12.427 +
  12.428 +When appropriate, Mercurial will store both snapshots and deltas in
  12.429 +compressed form.  It does this by always \emph{trying to} compress a
  12.430 +snapshot or delta, but only storing the compressed version if it's
  12.431 +smaller than the uncompressed version.
  12.432 +
  12.433 +This means that Mercurial does ``the right thing'' when storing a file
  12.434 +whose native form is compressed, such as a \texttt{zip} archive or a
  12.435 +JPEG image.  When these types of files are compressed a second time,
  12.436 +the resulting file is usually bigger than the once-compressed form,
  12.437 +and so Mercurial will store the plain \texttt{zip} or JPEG.
  12.438 +
  12.439 +Deltas between revisions of a compressed file are usually larger than
  12.440 +snapshots of the file, and Mercurial again does ``the right thing'' in
  12.441 +these cases.  It finds that such a delta exceeds the threshold at
  12.442 +which it should store a complete snapshot of the file, so it stores
  12.443 +the snapshot, again saving space compared to a naive delta-only
  12.444 +approach.
  12.445 +
  12.446 +\subsubsection{Network recompression}
  12.447 +
  12.448 +When storing revisions on disk, Mercurial uses the ``deflate''
  12.449 +compression algorithm (the same one used by the popular \texttt{zip}
  12.450 +archive format), which balances good speed with a respectable
  12.451 +compression ratio.  However, when transmitting revision data over a
  12.452 +network connection, Mercurial uncompresses the compressed revision
  12.453 +data.
  12.454 +
  12.455 +If the connection is over HTTP, Mercurial recompresses the entire
  12.456 +stream of data using a compression algorithm that gives a better
  12.457 +compression ratio (the Burrows-Wheeler algorithm from the widely used
  12.458 +\texttt{bzip2} compression package).  This combination of algorithm
  12.459 +and compression of the entire stream (instead of a revision at a time)
  12.460 +substantially reduces the number of bytes to be transferred, yielding
  12.461 +better network performance over almost all kinds of network.
  12.462 +
  12.463 +(If the connection is over \command{ssh}, Mercurial \emph{doesn't}
  12.464 +recompress the stream, because \command{ssh} can already do this
  12.465 +itself.)
  12.466 +
  12.467 +\subsection{Read/write ordering and atomicity}
  12.468 +
  12.469 +Appending to files isn't the whole story when it comes to guaranteeing
  12.470 +that a reader won't see a partial write.  If you recall
  12.471 +figure~\ref{fig:concepts:metadata}, revisions in the changelog point to
  12.472 +revisions in the manifest, and revisions in the manifest point to
  12.473 +revisions in filelogs.  This hierarchy is deliberate.
  12.474 +
  12.475 +A writer starts a transaction by writing filelog and manifest data,
  12.476 +and doesn't write any changelog data until those are finished.  A
  12.477 +reader starts by reading changelog data, then manifest data, followed
  12.478 +by filelog data.
  12.479 +
  12.480 +Since the writer has always finished writing filelog and manifest data
  12.481 +before it writes to the changelog, a reader will never read a pointer
  12.482 +to a partially written manifest revision from the changelog, and it will
  12.483 +never read a pointer to a partially written filelog revision from the
  12.484 +manifest.
  12.485 +
  12.486 +\subsection{Concurrent access}
  12.487 +
  12.488 +The read/write ordering and atomicity guarantees mean that Mercurial
  12.489 +never needs to \emph{lock} a repository when it's reading data, even
  12.490 +if the repository is being written to while the read is occurring.
  12.491 +This has a big effect on scalability; you can have an arbitrary number
  12.492 +of Mercurial processes safely reading data from a repository safely
  12.493 +all at once, no matter whether it's being written to or not.
  12.494 +
  12.495 +The lockless nature of reading means that if you're sharing a
  12.496 +repository on a multi-user system, you don't need to grant other local
  12.497 +users permission to \emph{write} to your repository in order for them
  12.498 +to be able to clone it or pull changes from it; they only need
  12.499 +\emph{read} permission.  (This is \emph{not} a common feature among
  12.500 +revision control systems, so don't take it for granted!  Most require
  12.501 +readers to be able to lock a repository to access it safely, and this
  12.502 +requires write permission on at least one directory, which of course
  12.503 +makes for all kinds of nasty and annoying security and administrative
  12.504 +problems.)
  12.505 +
  12.506 +Mercurial uses locks to ensure that only one process can write to a
  12.507 +repository at a time (the locking mechanism is safe even over
  12.508 +filesystems that are notoriously hostile to locking, such as NFS).  If
  12.509 +a repository is locked, a writer will wait for a while to retry if the
  12.510 +repository becomes unlocked, but if the repository remains locked for
  12.511 +too long, the process attempting to write will time out after a while.
  12.512 +This means that your daily automated scripts won't get stuck forever
  12.513 +and pile up if a system crashes unnoticed, for example.  (Yes, the
  12.514 +timeout is configurable, from zero to infinity.)
  12.515 +
  12.516 +\subsubsection{Safe dirstate access}
  12.517 +
  12.518 +As with revision data, Mercurial doesn't take a lock to read the
  12.519 +dirstate file; it does acquire a lock to write it.  To avoid the
  12.520 +possibility of reading a partially written copy of the dirstate file,
  12.521 +Mercurial writes to a file with a unique name in the same directory as
  12.522 +the dirstate file, then renames the temporary file atomically to
  12.523 +\filename{dirstate}.  The file named \filename{dirstate} is thus
  12.524 +guaranteed to be complete, not partially written.
  12.525 +
  12.526 +\subsection{Avoiding seeks}
  12.527 +
  12.528 +Critical to Mercurial's performance is the avoidance of seeks of the
  12.529 +disk head, since any seek is far more expensive than even a
  12.530 +comparatively large read operation.
  12.531 +
  12.532 +This is why, for example, the dirstate is stored in a single file.  If
  12.533 +there were a dirstate file per directory that Mercurial tracked, the
  12.534 +disk would seek once per directory.  Instead, Mercurial reads the
  12.535 +entire single dirstate file in one step.
  12.536 +
  12.537 +Mercurial also uses a ``copy on write'' scheme when cloning a
  12.538 +repository on local storage.  Instead of copying every revlog file
  12.539 +from the old repository into the new repository, it makes a ``hard
  12.540 +link'', which is a shorthand way to say ``these two names point to the
  12.541 +same file''.  When Mercurial is about to write to one of a revlog's
  12.542 +files, it checks to see if the number of names pointing at the file is
  12.543 +greater than one.  If it is, more than one repository is using the
  12.544 +file, so Mercurial makes a new copy of the file that is private to
  12.545 +this repository.
  12.546 +
  12.547 +A few revision control developers have pointed out that this idea of
  12.548 +making a complete private copy of a file is not very efficient in its
  12.549 +use of storage.  While this is true, storage is cheap, and this method
  12.550 +gives the highest performance while deferring most book-keeping to the
  12.551 +operating system.  An alternative scheme would most likely reduce
  12.552 +performance and increase the complexity of the software, each of which
  12.553 +is much more important to the ``feel'' of day-to-day use.
  12.554 +
  12.555 +\subsection{Other contents of the dirstate}
  12.556 +
  12.557 +Because Mercurial doesn't force you to tell it when you're modifying a
  12.558 +file, it uses the dirstate to store some extra information so it can
  12.559 +determine efficiently whether you have modified a file.  For each file
  12.560 +in the working directory, it stores the time that it last modified the
  12.561 +file itself, and the size of the file at that time.  
  12.562 +
  12.563 +When you explicitly \hgcmd{add}, \hgcmd{remove}, \hgcmd{rename} or
  12.564 +\hgcmd{copy} files, Mercurial updates the dirstate so that it knows
  12.565 +what to do with those files when you commit.
  12.566 +
  12.567 +When Mercurial is checking the states of files in the working
  12.568 +directory, it first checks a file's modification time.  If that has
  12.569 +not changed, the file must not have been modified.  If the file's size
  12.570 +has changed, the file must have been modified.  If the modification
  12.571 +time has changed, but the size has not, only then does Mercurial need
  12.572 +to read the actual contents of the file to see if they've changed.
  12.573 +Storing these few extra pieces of information dramatically reduces the
  12.574 +amount of data that Mercurial needs to read, which yields large
  12.575 +performance improvements compared to other revision control systems.
  12.576 +
  12.577 +%%% Local Variables: 
  12.578 +%%% mode: latex
  12.579 +%%% TeX-master: "00book"
  12.580 +%%% End:

    13.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    13.2 +++ b/en/ch05-daily.tex	Thu Jan 29 22:56:27 2009 -0800
    13.3 @@ -0,0 +1,381 @@
    13.4 +\chapter{Mercurial in daily use}
    13.5 +\label{chap:daily}
    13.6 +
    13.7 +\section{Telling Mercurial which files to track}
    13.8 +
    13.9 +Mercurial does not work with files in your repository unless you tell
   13.10 +it to manage them.  The \hgcmd{status} command will tell you which
   13.11 +files Mercurial doesn't know about; it uses a ``\texttt{?}'' to
   13.12 +display such files.
   13.13 +
   13.14 +To tell Mercurial to track a file, use the \hgcmd{add} command.  Once
   13.15 +you have added a file, the entry in the output of \hgcmd{status} for
   13.16 +that file changes from ``\texttt{?}'' to ``\texttt{A}''.
   13.17 +\interaction{daily.files.add}
   13.18 +
   13.19 +After you run a \hgcmd{commit}, the files that you added before the
   13.20 +commit will no longer be listed in the output of \hgcmd{status}.  The
   13.21 +reason for this is that \hgcmd{status} only tells you about
   13.22 +``interesting'' files---those that you have modified or told Mercurial
   13.23 +to do something with---by default.  If you have a repository that
   13.24 +contains thousands of files, you will rarely want to know about files
   13.25 +that Mercurial is tracking, but that have not changed.  (You can still
   13.26 +get this information; we'll return to this later.)
   13.27 +
   13.28 +Once you add a file, Mercurial doesn't do anything with it
   13.29 +immediately.  Instead, it will take a snapshot of the file's state the
   13.30 +next time you perform a commit.  It will then continue to track the
   13.31 +changes you make to the file every time you commit, until you remove
   13.32 +the file.
   13.33 +
   13.34 +\subsection{Explicit versus implicit file naming}
   13.35 +
   13.36 +A useful behaviour that Mercurial has is that if you pass the name of
   13.37 +a directory to a command, every Mercurial command will treat this as
   13.38 +``I want to operate on every file in this directory and its
   13.39 +subdirectories''.
   13.40 +\interaction{daily.files.add-dir}
   13.41 +Notice in this example that Mercurial printed the names of the files
   13.42 +it added, whereas it didn't do so when we added the file named
   13.43 +\filename{a} in the earlier example.
   13.44 +
   13.45 +What's going on is that in the former case, we explicitly named the
   13.46 +file to add on the command line, so the assumption that Mercurial
   13.47 +makes in such cases is that you know what you were doing, and it
   13.48 +doesn't print any output.
   13.49 +
   13.50 +However, when we \emph{imply} the names of files by giving the name of
   13.51 +a directory, Mercurial takes the extra step of printing the name of
   13.52 +each file that it does something with.  This makes it more clear what
   13.53 +is happening, and reduces the likelihood of a silent and nasty
   13.54 +surprise.  This behaviour is common to most Mercurial commands.
   13.55 +
   13.56 +\subsection{Aside: Mercurial tracks files, not directories}
   13.57 +
   13.58 +Mercurial does not track directory information.  Instead, it tracks
   13.59 +the path to a file.  Before creating a file, it first creates any
   13.60 +missing directory components of the path.  After it deletes a file, it
   13.61 +then deletes any empty directories that were in the deleted file's
   13.62 +path.  This sounds like a trivial distinction, but it has one minor
   13.63 +practical consequence: it is not possible to represent a completely
   13.64 +empty directory in Mercurial.
   13.65 +
   13.66 +Empty directories are rarely useful, and there are unintrusive
   13.67 +workarounds that you can use to achieve an appropriate effect.  The
   13.68 +developers of Mercurial thus felt that the complexity that would be
   13.69 +required to manage empty directories was not worth the limited benefit
   13.70 +this feature would bring.
   13.71 +
   13.72 +If you need an empty directory in your repository, there are a few
   13.73 +ways to achieve this. One is to create a directory, then \hgcmd{add} a
   13.74 +``hidden'' file to that directory.  On Unix-like systems, any file
   13.75 +name that begins with a period (``\texttt{.}'') is treated as hidden
   13.76 +by most commands and GUI tools.  This approach is illustrated in
   13.77 +figure~\ref{ex:daily:hidden}.
   13.78 +
   13.79 +\begin{figure}[ht]
   13.80 +  \interaction{daily.files.hidden}
   13.81 +  \caption{Simulating an empty directory using a hidden file}
   13.82 +  \label{ex:daily:hidden}
   13.83 +\end{figure}
   13.84 +
   13.85 +Another way to tackle a need for an empty directory is to simply
   13.86 +create one in your automated build scripts before they will need it.
   13.87 +
   13.88 +\section{How to stop tracking a file}
   13.89 +
   13.90 +Once you decide that a file no longer belongs in your repository, use
   13.91 +the \hgcmd{remove} command; this deletes the file, and tells Mercurial
   13.92 +to stop tracking it.  A removed file is represented in the output of
   13.93 +\hgcmd{status} with a ``\texttt{R}''.
   13.94 +\interaction{daily.files.remove}
   13.95 +
   13.96 +After you \hgcmd{remove} a file, Mercurial will no longer track
   13.97 +changes to that file, even if you recreate a file with the same name
   13.98 +in your working directory.  If you do recreate a file with the same
   13.99 +name and want Mercurial to track the new file, simply \hgcmd{add} it.
  13.100 +Mercurial will know that the newly added file is not related to the
  13.101 +old file of the same name.
  13.102 +
  13.103 +\subsection{Removing a file does not affect its history}
  13.104 +
  13.105 +It is important to understand that removing a file has only two
  13.106 +effects.
  13.107 +\begin{itemize}
  13.108 +\item It removes the current version of the file from the working
  13.109 +  directory.
  13.110 +\item It stops Mercurial from tracking changes to the file, from the
  13.111 +  time of the next commit.
  13.112 +\end{itemize}
  13.113 +Removing a file \emph{does not} in any way alter the \emph{history} of
  13.114 +the file.
  13.115 +
  13.116 +If you update the working directory to a changeset in which a file
  13.117 +that you have removed was still tracked, it will reappear in the
  13.118 +working directory, with the contents it had when you committed that
  13.119 +changeset.  If you then update the working directory to a later
  13.120 +changeset, in which the file had been removed, Mercurial will once
  13.121 +again remove the file from the working directory.
  13.122 +
  13.123 +\subsection{Missing files}
  13.124 +
  13.125 +Mercurial considers a file that you have deleted, but not used
  13.126 +\hgcmd{remove} to delete, to be \emph{missing}.  A missing file is
  13.127 +represented with ``\texttt{!}'' in the output of \hgcmd{status}.
  13.128 +Mercurial commands will not generally do anything with missing files.
  13.129 +\interaction{daily.files.missing}
  13.130 +
  13.131 +If your repository contains a file that \hgcmd{status} reports as
  13.132 +missing, and you want the file to stay gone, you can run
  13.133 +\hgcmdargs{remove}{\hgopt{remove}{--after}} at any time later on, to
  13.134 +tell Mercurial that you really did mean to remove the file.
  13.135 +\interaction{daily.files.remove-after}
  13.136 +
  13.137 +On the other hand, if you deleted the missing file by accident, use
  13.138 +\hgcmdargs{revert}{\emph{filename}} to recover the file.  It will
  13.139 +reappear, in unmodified form.
  13.140 +\interaction{daily.files.recover-missing}
  13.141 +
  13.142 +\subsection{Aside: why tell Mercurial explicitly to 
  13.143 +  remove a file?}
  13.144 +
  13.145 +You might wonder why Mercurial requires you to explicitly tell it that
  13.146 +you are deleting a file.  Early during the development of Mercurial,
  13.147 +it let you delete a file however you pleased; Mercurial would notice
  13.148 +the absence of the file automatically when you next ran a
  13.149 +\hgcmd{commit}, and stop tracking the file.  In practice, this made it
  13.150 +too easy to accidentally remove a file without noticing.
  13.151 +
  13.152 +\subsection{Useful shorthand---adding and removing files
  13.153 +  in one step}
  13.154 +
  13.155 +Mercurial offers a combination command, \hgcmd{addremove}, that adds
  13.156 +untracked files and marks missing files as removed.  
  13.157 +\interaction{daily.files.addremove}
  13.158 +The \hgcmd{commit} command also provides a \hgopt{commit}{-A} option
  13.159 +that performs this same add-and-remove, immediately followed by a
  13.160 +commit.
  13.161 +\interaction{daily.files.commit-addremove}
  13.162 +
  13.163 +\section{Copying files}
  13.164 +
  13.165 +Mercurial provides a \hgcmd{copy} command that lets you make a new
  13.166 +copy of a file.  When you copy a file using this command, Mercurial
  13.167 +makes a record of the fact that the new file is a copy of the original
  13.168 +file.  It treats these copied files specially when you merge your work
  13.169 +with someone else's.
  13.170 +
  13.171 +\subsection{The results of copying during a merge}
  13.172 +
  13.173 +What happens during a merge is that changes ``follow'' a copy.  To
  13.174 +best illustrate what this means, let's create an example.  We'll start
  13.175 +with the usual tiny repository that contains a single file.
  13.176 +\interaction{daily.copy.init}
  13.177 +We need to do some work in parallel, so that we'll have something to
  13.178 +merge.  So let's clone our repository.
  13.179 +\interaction{daily.copy.clone}
  13.180 +Back in our initial repository, let's use the \hgcmd{copy} command to
  13.181 +make a copy of the first file we created.
  13.182 +\interaction{daily.copy.copy}
  13.183 +
  13.184 +If we look at the output of the \hgcmd{status} command afterwards, the
  13.185 +copied file looks just like a normal added file.
  13.186 +\interaction{daily.copy.status}
  13.187 +But if we pass the \hgopt{status}{-C} option to \hgcmd{status}, it
  13.188 +prints another line of output: this is the file that our newly-added
  13.189 +file was copied \emph{from}.
  13.190 +\interaction{daily.copy.status-copy}
  13.191 +
  13.192 +Now, back in the repository we cloned, let's make a change in
  13.193 +parallel.  We'll add a line of content to the original file that we
  13.194 +created.
  13.195 +\interaction{daily.copy.other}
  13.196 +Now we have a modified \filename{file} in this repository.  When we
  13.197 +pull the changes from the first repository, and merge the two heads,
  13.198 +Mercurial will propagate the changes that we made locally to
  13.199 +\filename{file} into its copy, \filename{new-file}.
  13.200 +\interaction{daily.copy.merge}
  13.201 +
  13.202 +\subsection{Why should changes follow copies?}
  13.203 +\label{sec:daily:why-copy}
  13.204 +
  13.205 +This behaviour, of changes to a file propagating out to copies of the
  13.206 +file, might seem esoteric, but in most cases it's highly desirable.
  13.207 +
  13.208 +First of all, remember that this propagation \emph{only} happens when
  13.209 +you merge.  So if you \hgcmd{copy} a file, and subsequently modify the
  13.210 +original file during the normal course of your work, nothing will
  13.211 +happen.
  13.212 +
  13.213 +The second thing to know is that modifications will only propagate
  13.214 +across a copy as long as the repository that you're pulling changes
  13.215 +from \emph{doesn't know} about the copy.
  13.216 +
  13.217 +The reason that Mercurial does this is as follows.  Let's say I make
  13.218 +an important bug fix in a source file, and commit my changes.
  13.219 +Meanwhile, you've decided to \hgcmd{copy} the file in your repository,
  13.220 +without knowing about the bug or having seen the fix, and you have
  13.221 +started hacking on your copy of the file.
  13.222 +
  13.223 +If you pulled and merged my changes, and Mercurial \emph{didn't}
  13.224 +propagate changes across copies, your source file would now contain
  13.225 +the bug, and unless you remembered to propagate the bug fix by hand,
  13.226 +the bug would \emph{remain} in your copy of the file.
  13.227 +
  13.228 +By automatically propagating the change that fixed the bug from the
  13.229 +original file to the copy, Mercurial prevents this class of problem.
  13.230 +To my knowledge, Mercurial is the \emph{only} revision control system
  13.231 +that propagates changes across copies like this.
  13.232 +
  13.233 +Once your change history has a record that the copy and subsequent
  13.234 +merge occurred, there's usually no further need to propagate changes
  13.235 +from the original file to the copied file, and that's why Mercurial
  13.236 +only propagates changes across copies until this point, and no
  13.237 +further.
  13.238 +
  13.239 +\subsection{How to make changes \emph{not} follow a copy}
  13.240 +
  13.241 +If, for some reason, you decide that this business of automatically
  13.242 +propagating changes across copies is not for you, simply use your
  13.243 +system's normal file copy command (on Unix-like systems, that's
  13.244 +\command{cp}) to make a copy of a file, then \hgcmd{add} the new copy
  13.245 +by hand.  Before you do so, though, please do reread
  13.246 +section~\ref{sec:daily:why-copy}, and make an informed decision that
  13.247 +this behaviour is not appropriate to your specific case.
  13.248 +
  13.249 +\subsection{Behaviour of the \hgcmd{copy} command}
  13.250 +
  13.251 +When you use the \hgcmd{copy} command, Mercurial makes a copy of each
  13.252 +source file as it currently stands in the working directory.  This
  13.253 +means that if you make some modifications to a file, then \hgcmd{copy}
  13.254 +it without first having committed those changes, the new copy will
  13.255 +also contain the modifications you have made up until that point.  (I
  13.256 +find this behaviour a little counterintuitive, which is why I mention
  13.257 +it here.)
  13.258 +
  13.259 +The \hgcmd{copy} command acts similarly to the Unix \command{cp}
  13.260 +command (you can use the \hgcmd{cp} alias if you prefer).  The last
  13.261 +argument is the \emph{destination}, and all prior arguments are
  13.262 +\emph{sources}.  If you pass it a single file as the source, and the
  13.263 +destination does not exist, it creates a new file with that name.
  13.264 +\interaction{daily.copy.simple}
  13.265 +If the destination is a directory, Mercurial copies its sources into
  13.266 +that directory.
  13.267 +\interaction{daily.copy.dir-dest}
  13.268 +Copying a directory is recursive, and preserves the directory
  13.269 +structure of the source.
  13.270 +\interaction{daily.copy.dir-src}
  13.271 +If the source and destination are both directories, the source tree is
  13.272 +recreated in the destination directory.
  13.273 +\interaction{daily.copy.dir-src-dest}
  13.274 +
  13.275 +As with the \hgcmd{rename} command, if you copy a file manually and
  13.276 +then want Mercurial to know that you've copied the file, simply use
  13.277 +the \hgopt{copy}{--after} option to \hgcmd{copy}.
  13.278 +\interaction{daily.copy.after}
  13.279 +
  13.280 +\section{Renaming files}
  13.281 +
  13.282 +It's rather more common to need to rename a file than to make a copy
  13.283 +of it.  The reason I discussed the \hgcmd{copy} command before talking
  13.284 +about renaming files is that Mercurial treats a rename in essentially
  13.285 +the same way as a copy.  Therefore, knowing what Mercurial does when
  13.286 +you copy a file tells you what to expect when you rename a file.
  13.287 +
  13.288 +When you use the \hgcmd{rename} command, Mercurial makes a copy of
  13.289 +each source file, then deletes it and marks the file as removed.
  13.290 +\interaction{daily.rename.rename}
  13.291 +The \hgcmd{status} command shows the newly copied file as added, and
  13.292 +the copied-from file as removed.
  13.293 +\interaction{daily.rename.status}
  13.294 +As with the results of a \hgcmd{copy}, we must use the
  13.295 +\hgopt{status}{-C} option to \hgcmd{status} to see that the added file
  13.296 +is really being tracked by Mercurial as a copy of the original, now
  13.297 +removed, file.
  13.298 +\interaction{daily.rename.status-copy}
  13.299 +
  13.300 +As with \hgcmd{remove} and \hgcmd{copy}, you can tell Mercurial about
  13.301 +a rename after the fact using the \hgopt{rename}{--after} option.  In
  13.302 +most other respects, the behaviour of the \hgcmd{rename} command, and
  13.303 +the options it accepts, are similar to the \hgcmd{copy} command.
  13.304 +
  13.305 +\subsection{Renaming files and merging changes}
  13.306 +
  13.307 +Since Mercurial's rename is implemented as copy-and-remove, the same
  13.308 +propagation of changes happens when you merge after a rename as after
  13.309 +a copy.
  13.310 +
  13.311 +If I modify a file, and you rename it to a new name, and then we merge
  13.312 +our respective changes, my modifications to the file under its
  13.313 +original name will be propagated into the file under its new name.
  13.314 +(This is something you might expect to ``simply work,'' but not all
  13.315 +revision control systems actually do this.)
  13.316 +
  13.317 +Whereas having changes follow a copy is a feature where you can
  13.318 +perhaps nod and say ``yes, that might be useful,'' it should be clear
  13.319 +that having them follow a rename is definitely important.  Without
  13.320 +this facility, it would simply be too easy for changes to become
  13.321 +orphaned when files are renamed.
  13.322 +
  13.323 +\subsection{Divergent renames and merging}
  13.324 +
  13.325 +The case of diverging names occurs when two developers start with a
  13.326 +file---let's call it \filename{foo}---in their respective
  13.327 +repositories.
  13.328 +
  13.329 +\interaction{rename.divergent.clone}
  13.330 +Anne renames the file to \filename{bar}.
  13.331 +\interaction{rename.divergent.rename.anne}
  13.332 +Meanwhile, Bob renames it to \filename{quux}.
  13.333 +\interaction{rename.divergent.rename.bob}
  13.334 +
  13.335 +I like to think of this as a conflict because each developer has
  13.336 +expressed different intentions about what the file ought to be named.
  13.337 +
  13.338 +What do you think should happen when they merge their work?
  13.339 +Mercurial's actual behaviour is that it always preserves \emph{both}
  13.340 +names when it merges changesets that contain divergent renames.
  13.341 +\interaction{rename.divergent.merge}
  13.342 +
  13.343 +Notice that Mercurial does warn about the divergent renames, but it
  13.344 +leaves it up to you to do something about the divergence after the merge.
  13.345 +
  13.346 +\subsection{Convergent renames and merging}
  13.347 +
  13.348 +Another kind of rename conflict occurs when two people choose to
  13.349 +rename different \emph{source} files to the same \emph{destination}.
  13.350 +In this case, Mercurial runs its normal merge machinery, and lets you
  13.351 +guide it to a suitable resolution.
  13.352 +
  13.353 +\subsection{Other name-related corner cases}
  13.354 +
  13.355 +Mercurial has a longstanding bug in which it fails to handle a merge
  13.356 +where one side has a file with a given name, while another has a
  13.357 +directory with the same name.  This is documented as~\bug{29}.
  13.358 +\interaction{issue29.go}
  13.359 +
  13.360 +\section{Recovering from mistakes}
  13.361 +
  13.362 +Mercurial has some useful commands that will help you to recover from
  13.363 +some common mistakes.
  13.364 +
  13.365 +The \hgcmd{revert} command lets you undo changes that you have made to
  13.366 +your working directory.  For example, if you \hgcmd{add} a file by
  13.367 +accident, just run \hgcmd{revert} with the name of the file you added,
  13.368 +and while the file won't be touched in any way, it won't be tracked
  13.369 +for adding by Mercurial any longer, either.  You can also use
  13.370 +\hgcmd{revert} to get rid of erroneous changes to a file.
  13.371 +
  13.372 +It's useful to remember that the \hgcmd{revert} command is useful for
  13.373 +changes that you have not yet committed.  Once you've committed a
  13.374 +change, if you decide it was a mistake, you can still do something
  13.375 +about it, though your options may be more limited.
  13.376 +
  13.377 +For more information about the \hgcmd{revert} command, and details
  13.378 +about how to deal with changes you have already committed, see
  13.379 +chapter~\ref{chap:undo}.
  13.380 +
  13.381 +%%% Local Variables: 
  13.382 +%%% mode: latex
  13.383 +%%% TeX-master: "00book"
  13.384 +%%% End: 

    14.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    14.2 +++ b/en/ch06-collab.tex	Thu Jan 29 22:56:27 2009 -0800
    14.3 @@ -0,0 +1,1118 @@
    14.4 +\chapter{Collaborating with other people}
    14.5 +\label{cha:collab}
    14.6 +
    14.7 +As a completely decentralised tool, Mercurial doesn't impose any
    14.8 +policy on how people ought to work with each other.  However, if
    14.9 +you're new to distributed revision control, it helps to have some
   14.10 +tools and examples in mind when you're thinking about possible
   14.11 +workflow models.
   14.12 +
   14.13 +\section{Mercurial's web interface}
   14.14 +
   14.15 +Mercurial has a powerful web interface that provides several 
   14.16 +useful capabilities.
   14.17 +
   14.18 +For interactive use, the web interface lets you browse a single
   14.19 +repository or a collection of repositories.  You can view the history
   14.20 +of a repository, examine each change (comments and diffs), and view
   14.21 +the contents of each directory and file.
   14.22 +
   14.23 +Also for human consumption, the web interface provides an RSS feed of
   14.24 +the changes in a repository.  This lets you ``subscribe'' to a
   14.25 +repository using your favourite feed reader, and be automatically
   14.26 +notified of activity in that repository as soon as it happens.  I find
   14.27 +this capability much more convenient than the model of subscribing to
   14.28 +a mailing list to which notifications are sent, as it requires no
   14.29 +additional configuration on the part of whoever is serving the
   14.30 +repository.
   14.31 +
   14.32 +The web interface also lets remote users clone a repository, pull
   14.33 +changes from it, and (when the server is configured to permit it) push
   14.34 +changes back to it.  Mercurial's HTTP tunneling protocol aggressively
   14.35 +compresses data, so that it works efficiently even over low-bandwidth
   14.36 +network connections.
   14.37 +
   14.38 +The easiest way to get started with the web interface is to use your
   14.39 +web browser to visit an existing repository, such as the master
   14.40 +Mercurial repository at
   14.41 +\url{http://www.selenic.com/repo/hg?style=gitweb}.
   14.42 +
   14.43 +If you're interested in providing a web interface to your own
   14.44 +repositories, Mercurial provides two ways to do this.  The first is
   14.45 +using the \hgcmd{serve} command, which is best suited to short-term
   14.46 +``lightweight'' serving.  See section~\ref{sec:collab:serve} below for
   14.47 +details of how to use this command.  If you have a long-lived
   14.48 +repository that you'd like to make permanently available, Mercurial
   14.49 +has built-in support for the CGI (Common Gateway Interface) standard,
   14.50 +which all common web servers support.  See
   14.51 +section~\ref{sec:collab:cgi} for details of CGI configuration.
   14.52 +
   14.53 +\section{Collaboration models}
   14.54 +
   14.55 +With a suitably flexible tool, making decisions about workflow is much
   14.56 +more of a social engineering challenge than a technical one.
   14.57 +Mercurial imposes few limitations on how you can structure the flow of
   14.58 +work in a project, so it's up to you and your group to set up and live
   14.59 +with a model that matches your own particular needs.
   14.60 +
   14.61 +\subsection{Factors to keep in mind}
   14.62 +
   14.63 +The most important aspect of any model that you must keep in mind is
   14.64 +how well it matches the needs and capabilities of the people who will
   14.65 +be using it.  This might seem self-evident; even so, you still can't
   14.66 +afford to forget it for a moment.
   14.67 +
   14.68 +I once put together a workflow model that seemed to make perfect sense
   14.69 +to me, but that caused a considerable amount of consternation and
   14.70 +strife within my development team.  In spite of my attempts to explain
   14.71 +why we needed a complex set of branches, and how changes ought to flow
   14.72 +between them, a few team members revolted.  Even though they were
   14.73 +smart people, they didn't want to pay attention to the constraints we
   14.74 +were operating under, or face the consequences of those constraints in
   14.75 +the details of the model that I was advocating.
   14.76 +
   14.77 +Don't sweep foreseeable social or technical problems under the rug.
   14.78 +Whatever scheme you put into effect, you should plan for mistakes and
   14.79 +problem scenarios.  Consider adding automated machinery to prevent, or
   14.80 +quickly recover from, trouble that you can anticipate.  As an example,
   14.81 +if you intend to have a branch with not-for-release changes in it,
   14.82 +you'd do well to think early about the possibility that someone might
   14.83 +accidentally merge those changes into a release branch.  You could
   14.84 +avoid this particular problem by writing a hook that prevents changes
   14.85 +from being merged from an inappropriate branch.
   14.86 +
   14.87 +\subsection{Informal anarchy}
   14.88 +
   14.89 +I wouldn't suggest an ``anything goes'' approach as something
   14.90 +sustainable, but it's a model that's easy to grasp, and it works
   14.91 +perfectly well in a few unusual situations.
   14.92 +
   14.93 +As one example, many projects have a loose-knit group of collaborators
   14.94 +who rarely physically meet each other.  Some groups like to overcome
   14.95 +the isolation of working at a distance by organising occasional
   14.96 +``sprints''.  In a sprint, a number of people get together in a single
   14.97 +location (a company's conference room, a hotel meeting room, that kind
   14.98 +of place) and spend several days more or less locked in there, hacking
   14.99 +intensely on a handful of projects.
  14.100 +
  14.101 +A sprint is the perfect place to use the \hgcmd{serve} command, since
  14.102 +\hgcmd{serve} does not requires any fancy server infrastructure.  You
  14.103 +can get started with \hgcmd{serve} in moments, by reading
  14.104 +section~\ref{sec:collab:serve} below.  Then simply tell the person
  14.105 +next to you that you're running a server, send the URL to them in an
  14.106 +instant message, and you immediately have a quick-turnaround way to
  14.107 +work together.  They can type your URL into their web browser and
  14.108 +quickly review your changes; or they can pull a bugfix from you and
  14.109 +verify it; or they can clone a branch containing a new feature and try
  14.110 +it out.
  14.111 +
  14.112 +The charm, and the problem, with doing things in an ad hoc fashion
  14.113 +like this is that only people who know about your changes, and where
  14.114 +they are, can see them.  Such an informal approach simply doesn't
  14.115 +scale beyond a handful people, because each individual needs to know
  14.116 +about $n$ different repositories to pull from.
  14.117 +
  14.118 +\subsection{A single central repository}
  14.119 +
  14.120 +For smaller projects migrating from a centralised revision control
  14.121 +tool, perhaps the easiest way to get started is to have changes flow
  14.122 +through a single shared central repository.  This is also the
  14.123 +most common ``building block'' for more ambitious workflow schemes.
  14.124 +
  14.125 +Contributors start by cloning a copy of this repository.  They can
  14.126 +pull changes from it whenever they need to, and some (perhaps all)
  14.127 +developers have permission to push a change back when they're ready
  14.128 +for other people to see it.
  14.129 +
  14.130 +Under this model, it can still often make sense for people to pull
  14.131 +changes directly from each other, without going through the central
  14.132 +repository.  Consider a case in which I have a tentative bug fix, but
  14.133 +I am worried that if I were to publish it to the central repository,
  14.134 +it might subsequently break everyone else's trees as they pull it.  To
  14.135 +reduce the potential for damage, I can ask you to clone my repository
  14.136 +into a temporary repository of your own and test it.  This lets us put
  14.137 +off publishing the potentially unsafe change until it has had a little
  14.138 +testing.
  14.139 +
  14.140 +In this kind of scenario, people usually use the \command{ssh}
  14.141 +protocol to securely push changes to the central repository, as
  14.142 +documented in section~\ref{sec:collab:ssh}.  It's also usual to
  14.143 +publish a read-only copy of the repository over HTTP using CGI, as in
  14.144 +section~\ref{sec:collab:cgi}.  Publishing over HTTP satisfies the
  14.145 +needs of people who don't have push access, and those who want to use
  14.146 +web browsers to browse the repository's history.
  14.147 +
  14.148 +\subsection{Working with multiple branches}
  14.149 +
  14.150 +Projects of any significant size naturally tend to make progress on
  14.151 +several fronts simultaneously.  In the case of software, it's common
  14.152 +for a project to go through periodic official releases.  A release
  14.153 +might then go into ``maintenance mode'' for a while after its first
  14.154 +publication; maintenance releases tend to contain only bug fixes, not
  14.155 +new features.  In parallel with these maintenance releases, one or
  14.156 +more future releases may be under development.  People normally use
  14.157 +the word ``branch'' to refer to one of these many slightly different
  14.158 +directions in which development is proceeding.
  14.159 +
  14.160 +Mercurial is particularly well suited to managing a number of
  14.161 +simultaneous, but not identical, branches.  Each ``development
  14.162 +direction'' can live in its own central repository, and you can merge
  14.163 +changes from one to another as the need arises.  Because repositories
  14.164 +are independent of each other, unstable changes in a development
  14.165 +branch will never affect a stable branch unless someone explicitly
  14.166 +merges those changes in.
  14.167 +
  14.168 +Here's an example of how this can work in practice.  Let's say you
  14.169 +have one ``main branch'' on a central server.
  14.170 +\interaction{branching.init}
  14.171 +People clone it, make changes locally, test them, and push them back.
  14.172 +
  14.173 +Once the main branch reaches a release milestone, you can use the
  14.174 +\hgcmd{tag} command to give a permanent name to the milestone
  14.175 +revision.
  14.176 +\interaction{branching.tag}
  14.177 +Let's say some ongoing development occurs on the main branch.
  14.178 +\interaction{branching.main}
  14.179 +Using the tag that was recorded at the milestone, people who clone
  14.180 +that repository at any time in the future can use \hgcmd{update} to
  14.181 +get a copy of the working directory exactly as it was when that tagged
  14.182 +revision was committed.  
  14.183 +\interaction{branching.update}
  14.184 +
  14.185 +In addition, immediately after the main branch is tagged, someone can
  14.186 +then clone the main branch on the server to a new ``stable'' branch,
  14.187 +also on the server.
  14.188 +\interaction{branching.clone}
  14.189 +
  14.190 +Someone who needs to make a change to the stable branch can then clone
  14.191 +\emph{that} repository, make their changes, commit, and push their
  14.192 +changes back there.
  14.193 +\interaction{branching.stable}
  14.194 +Because Mercurial repositories are independent, and Mercurial doesn't
  14.195 +move changes around automatically, the stable and main branches are
  14.196 +\emph{isolated} from each other.  The changes that you made on the
  14.197 +main branch don't ``leak'' to the stable branch, and vice versa.
  14.198 +
  14.199 +You'll often want all of your bugfixes on the stable branch to show up
  14.200 +on the main branch, too.  Rather than rewrite a bugfix on the main
  14.201 +branch, you can simply pull and merge changes from the stable to the
  14.202 +main branch, and Mercurial will bring those bugfixes in for you.
  14.203 +\interaction{branching.merge}
  14.204 +The main branch will still contain changes that are not on the stable
  14.205 +branch, but it will also contain all of the bugfixes from the stable
  14.206 +branch.  The stable branch remains unaffected by these changes.
  14.207 +
  14.208 +\subsection{Feature branches}
  14.209 +
  14.210 +For larger projects, an effective way to manage change is to break up
  14.211 +a team into smaller groups.  Each group has a shared branch of its
  14.212 +own, cloned from a single ``master'' branch used by the entire
  14.213 +project.  People working on an individual branch are typically quite
  14.214 +isolated from developments on other branches.
  14.215 +
  14.216 +\begin{figure}[ht]
  14.217 +  \centering
  14.218 +  \grafix{feature-branches}
  14.219 +  \caption{Feature branches}
  14.220 +  \label{fig:collab:feature-branches}
  14.221 +\end{figure}
  14.222 +
  14.223 +When a particular feature is deemed to be in suitable shape, someone
  14.224 +on that feature team pulls and merges from the master branch into the
  14.225 +feature branch, then pushes back up to the master branch.
  14.226 +
  14.227 +\subsection{The release train}
  14.228 +
  14.229 +Some projects are organised on a ``train'' basis: a release is
  14.230 +scheduled to happen every few months, and whatever features are ready
  14.231 +when the ``train'' is ready to leave are allowed in.
  14.232 +
  14.233 +This model resembles working with feature branches.  The difference is
  14.234 +that when a feature branch misses a train, someone on the feature team
  14.235 +pulls and merges the changes that went out on that train release into
  14.236 +the feature branch, and the team continues its work on top of that
  14.237 +release so that their feature can make the next release.
  14.238 +
  14.239 +\subsection{The Linux kernel model}
  14.240 +
  14.241 +The development of the Linux kernel has a shallow hierarchical
  14.242 +structure, surrounded by a cloud of apparent chaos.  Because most
  14.243 +Linux developers use \command{git}, a distributed revision control
  14.244 +tool with capabilities similar to Mercurial, it's useful to describe
  14.245 +the way work flows in that environment; if you like the ideas, the
  14.246 +approach translates well across tools.
  14.247 +
  14.248 +At the center of the community sits Linus Torvalds, the creator of
  14.249 +Linux.  He publishes a single source repository that is considered the
  14.250 +``authoritative'' current tree by the entire developer community.
  14.251 +Anyone can clone Linus's tree, but he is very choosy about whose trees
  14.252 +he pulls from.
  14.253 +
  14.254 +Linus has a number of ``trusted lieutenants''.  As a general rule, he
  14.255 +pulls whatever changes they publish, in most cases without even
  14.256 +reviewing those changes.  Some of those lieutenants are generally
  14.257 +agreed to be ``maintainers'', responsible for specific subsystems
  14.258 +within the kernel.  If a random kernel hacker wants to make a change
  14.259 +to a subsystem that they want to end up in Linus's tree, they must
  14.260 +find out who the subsystem's maintainer is, and ask that maintainer to
  14.261 +take their change.  If the maintainer reviews their changes and agrees
  14.262 +to take them, they'll pass them along to Linus in due course.
  14.263 +
  14.264 +Individual lieutenants have their own approaches to reviewing,
  14.265 +accepting, and publishing changes; and for deciding when to feed them
  14.266 +to Linus.  In addition, there are several well known branches that
  14.267 +people use for different purposes.  For example, a few people maintain
  14.268 +``stable'' repositories of older versions of the kernel, to which they
  14.269 +apply critical fixes as needed.  Some maintainers publish multiple
  14.270 +trees: one for experimental changes; one for changes that they are
  14.271 +about to feed upstream; and so on.  Others just publish a single
  14.272 +tree.
  14.273 +
  14.274 +This model has two notable features.  The first is that it's ``pull
  14.275 +only''.  You have to ask, convince, or beg another developer to take a
  14.276 +change from you, because there are almost no trees to which more than
  14.277 +one person can push, and there's no way to push changes into a tree
  14.278 +that someone else controls.
  14.279 +
  14.280 +The second is that it's based on reputation and acclaim.  If you're an
  14.281 +unknown, Linus will probably ignore changes from you without even
  14.282 +responding.  But a subsystem maintainer will probably review them, and
  14.283 +will likely take them if they pass their criteria for suitability.
  14.284 +The more ``good'' changes you contribute to a maintainer, the more
  14.285 +likely they are to trust your judgment and accept your changes.  If
  14.286 +you're well-known and maintain a long-lived branch for something Linus
  14.287 +hasn't yet accepted, people with similar interests may pull your
  14.288 +changes regularly to keep up with your work.
  14.289 +
  14.290 +Reputation and acclaim don't necessarily cross subsystem or ``people''
  14.291 +boundaries.  If you're a respected but specialised storage hacker, and
  14.292 +you try to fix a networking bug, that change will receive a level of
  14.293 +scrutiny from a network maintainer comparable to a change from a
  14.294 +complete stranger.
  14.295 +
  14.296 +To people who come from more orderly project backgrounds, the
  14.297 +comparatively chaotic Linux kernel development process often seems
  14.298 +completely insane.  It's subject to the whims of individuals; people
  14.299 +make sweeping changes whenever they deem it appropriate; and the pace
  14.300 +of development is astounding.  And yet Linux is a highly successful,
  14.301 +well-regarded piece of software.
  14.302 +
  14.303 +\subsection{Pull-only versus shared-push collaboration}
  14.304 +
  14.305 +A perpetual source of heat in the open source community is whether a
  14.306 +development model in which people only ever pull changes from others
  14.307 +is ``better than'' one in which multiple people can push changes to a
  14.308 +shared repository.
  14.309 +
  14.310 +Typically, the backers of the shared-push model use tools that
  14.311 +actively enforce this approach.  If you're using a centralised
  14.312 +revision control tool such as Subversion, there's no way to make a
  14.313 +choice over which model you'll use: the tool gives you shared-push,
  14.314 +and if you want to do anything else, you'll have to roll your own
  14.315 +approach on top (such as applying a patch by hand).
  14.316 +
  14.317 +A good distributed revision control tool, such as Mercurial, will
  14.318 +support both models.  You and your collaborators can then structure
  14.319 +how you work together based on your own needs and preferences, not on
  14.320 +what contortions your tools force you into.
  14.321 +
  14.322 +\subsection{Where collaboration meets branch management}
  14.323 +
  14.324 +Once you and your team set up some shared repositories and start
  14.325 +propagating changes back and forth between local and shared repos, you
  14.326 +begin to face a related, but slightly different challenge: that of
  14.327 +managing the multiple directions in which your team may be moving at
  14.328 +once.  Even though this subject is intimately related to how your team
  14.329 +collaborates, it's dense enough to merit treatment of its own, in
  14.330 +chapter~\ref{chap:branch}.
  14.331 +
  14.332 +\section{The technical side of sharing}
  14.333 +
  14.334 +The remainder of this chapter is devoted to the question of serving
  14.335 +data to your collaborators.
  14.336 +
  14.337 +\section{Informal sharing with \hgcmd{serve}}
  14.338 +\label{sec:collab:serve}
  14.339 +
  14.340 +Mercurial's \hgcmd{serve} command is wonderfully suited to small,
  14.341 +tight-knit, and fast-paced group environments.  It also provides a
  14.342 +great way to get a feel for using Mercurial commands over a network.
  14.343 +
  14.344 +Run \hgcmd{serve} inside a repository, and in under a second it will
  14.345 +bring up a specialised HTTP server; this will accept connections from
  14.346 +any client, and serve up data for that repository until you terminate
  14.347 +it.  Anyone who knows the URL of the server you just started, and can
  14.348 +talk to your computer over the network, can then use a web browser or
  14.349 +Mercurial to read data from that repository.  A URL for a
  14.350 +\hgcmd{serve} instance running on a laptop is likely to look something
  14.351 +like \Verb|http://my-laptop.local:8000/|.
  14.352 +
  14.353 +The \hgcmd{serve} command is \emph{not} a general-purpose web server.
  14.354 +It can do only two things:
  14.355 +\begin{itemize}
  14.356 +\item Allow people to browse the history of the repository it's
  14.357 +  serving, from their normal web browsers.
  14.358 +\item Speak Mercurial's wire protocol, so that people can
  14.359 +  \hgcmd{clone} or \hgcmd{pull} changes from that repository.
  14.360 +\end{itemize}
  14.361 +In particular, \hgcmd{serve} won't allow remote users to \emph{modify}
  14.362 +your repository.  It's intended for read-only use.
  14.363 +
  14.364 +If you're getting started with Mercurial, there's nothing to prevent
  14.365 +you from using \hgcmd{serve} to serve up a repository on your own
  14.366 +computer, then use commands like \hgcmd{clone}, \hgcmd{incoming}, and
  14.367 +so on to talk to that server as if the repository was hosted remotely.
  14.368 +This can help you to quickly get acquainted with using commands on
  14.369 +network-hosted repositories.
  14.370 +
  14.371 +\subsection{A few things to keep in mind}
  14.372 +
  14.373 +Because it provides unauthenticated read access to all clients, you
  14.374 +should only use \hgcmd{serve} in an environment where you either don't
  14.375 +care, or have complete control over, who can access your network and
  14.376 +pull data from your repository.
  14.377 +
  14.378 +The \hgcmd{serve} command knows nothing about any firewall software
  14.379 +you might have installed on your system or network.  It cannot detect
  14.380 +or control your firewall software.  If other people are unable to talk
  14.381 +to a running \hgcmd{serve} instance, the second thing you should do
  14.382 +(\emph{after} you make sure that they're using the correct URL) is
  14.383 +check your firewall configuration.
  14.384 +
  14.385 +By default, \hgcmd{serve} listens for incoming connections on
  14.386 +port~8000.  If another process is already listening on the port you
  14.387 +want to use, you can specify a different port to listen on using the
  14.388 +\hgopt{serve}{-p} option.
  14.389 +
  14.390 +Normally, when \hgcmd{serve} starts, it prints no output, which can be
  14.391 +a bit unnerving.  If you'd like to confirm that it is indeed running
  14.392 +correctly, and find out what URL you should send to your
  14.393 +collaborators, start it with the \hggopt{-v} option.
  14.394 +
  14.395 +\section{Using the Secure Shell (ssh) protocol}
  14.396 +\label{sec:collab:ssh}
  14.397 +
  14.398 +You can pull and push changes securely over a network connection using
  14.399 +the Secure Shell (\texttt{ssh}) protocol.  To use this successfully,
  14.400 +you may have to do a little bit of configuration on the client or
  14.401 +server sides.
  14.402 +
  14.403 +If you're not familiar with ssh, it's a network protocol that lets you
  14.404 +securely communicate with another computer.  To use it with Mercurial,
  14.405 +you'll be setting up one or more user accounts on a server so that
  14.406 +remote users can log in and execute commands.
  14.407 +
  14.408 +(If you \emph{are} familiar with ssh, you'll probably find some of the
  14.409 +material that follows to be elementary in nature.)
  14.410 +
  14.411 +\subsection{How to read and write ssh URLs}
  14.412 +
  14.413 +An ssh URL tends to look like this:
  14.414 +\begin{codesample2}
  14.415 +  ssh://bos@hg.serpentine.com:22/hg/hgbook
  14.416 +\end{codesample2}
  14.417 +\begin{enumerate}
  14.418 +\item The ``\texttt{ssh://}'' part tells Mercurial to use the ssh
  14.419 +  protocol.
  14.420 +\item The ``\texttt{bos@}'' component indicates what username to log
  14.421 +  into the server as.  You can leave this out if the remote username
  14.422 +  is the same as your local username.
  14.423 +\item The ``\texttt{hg.serpentine.com}'' gives the hostname of the
  14.424 +  server to log into.
  14.425 +\item The ``:22'' identifies the port number to connect to the server
  14.426 +  on.  The default port is~22, so you only need to specify this part
  14.427 +  if you're \emph{not} using port~22.
  14.428 +\item The remainder of the URL is the local path to the repository on
  14.429 +  the server.
  14.430 +\end{enumerate}
  14.431 +
  14.432 +There's plenty of scope for confusion with the path component of ssh
  14.433 +URLs, as there is no standard way for tools to interpret it.  Some
  14.434 +programs behave differently than others when dealing with these paths.
  14.435 +This isn't an ideal situation, but it's unlikely to change.  Please
  14.436 +read the following paragraphs carefully.
  14.437 +
  14.438 +Mercurial treats the path to a repository on the server as relative to
  14.439 +the remote user's home directory.  For example, if user \texttt{foo}
  14.440 +on the server has a home directory of \dirname{/home/foo}, then an ssh
  14.441 +URL that contains a path component of \dirname{bar}
  14.442 +\emph{really} refers to the directory \dirname{/home/foo/bar}.
  14.443 +
  14.444 +If you want to specify a path relative to another user's home
  14.445 +directory, you can use a path that starts with a tilde character
  14.446 +followed by the user's name (let's call them \texttt{otheruser}), like
  14.447 +this.
  14.448 +\begin{codesample2}
  14.449 +  ssh://server/~otheruser/hg/repo
  14.450 +\end{codesample2}
  14.451 +
  14.452 +And if you really want to specify an \emph{absolute} path on the
  14.453 +server, begin the path component with two slashes, as in this example.
  14.454 +\begin{codesample2}
  14.455 +  ssh://server//absolute/path
  14.456 +\end{codesample2}
  14.457 +
  14.458 +\subsection{Finding an ssh client for your system}
  14.459 +
  14.460 +Almost every Unix-like system comes with OpenSSH preinstalled.  If
  14.461 +you're using such a system, run \Verb|which ssh| to find out if
  14.462 +the \command{ssh} command is installed (it's usually in
  14.463 +\dirname{/usr/bin}).  In the unlikely event that it isn't present,
  14.464 +take a look at your system documentation to figure out how to install
  14.465 +it.
  14.466 +
  14.467 +On Windows, you'll first need to download a suitable ssh
  14.468 +client.  There are two alternatives.
  14.469 +\begin{itemize}
  14.470 +\item Simon Tatham's excellent PuTTY package~\cite{web:putty} provides
  14.471 +  a complete suite of ssh client commands.
  14.472 +\item If you have a high tolerance for pain, you can use the Cygwin
  14.473 +  port of OpenSSH.
  14.474 +\end{itemize}
  14.475 +In either case, you'll need to edit your \hgini\ file to tell
  14.476 +Mercurial where to find the actual client command.  For example, if
  14.477 +you're using PuTTY, you'll need to use the \command{plink} command as
  14.478 +a command-line ssh client.
  14.479 +\begin{codesample2}
  14.480 +  [ui]
  14.481 +  ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"
  14.482 +\end{codesample2}
  14.483 +
  14.484 +\begin{note}
  14.485 +  The path to \command{plink} shouldn't contain any whitespace
  14.486 +  characters, or Mercurial may not be able to run it correctly (so
  14.487 +  putting it in \dirname{C:\\Program Files} is probably not a good
  14.488 +  idea).
  14.489 +\end{note}
  14.490 +
  14.491 +\subsection{Generating a key pair}
  14.492 +
  14.493 +To avoid the need to repetitively type a password every time you need
  14.494 +to use your ssh client, I recommend generating a key pair.  On a
  14.495 +Unix-like system, the \command{ssh-keygen} command will do the trick.
  14.496 +On Windows, if you're using PuTTY, the \command{puttygen} command is
  14.497 +what you'll need.
  14.498 +
  14.499 +When you generate a key pair, it's usually \emph{highly} advisable to
  14.500 +protect it with a passphrase.  (The only time that you might not want
  14.501 +to do this is when you're using the ssh protocol for automated tasks
  14.502 +on a secure network.)
  14.503 +
  14.504 +Simply generating a key pair isn't enough, however.  You'll need to
  14.505 +add the public key to the set of authorised keys for whatever user
  14.506 +you're logging in remotely as.  For servers using OpenSSH (the vast
  14.507 +majority), this will mean adding the public key to a list in a file
  14.508 +called \sfilename{authorized\_keys} in their \sdirname{.ssh}
  14.509 +directory.
  14.510 +
  14.511 +On a Unix-like system, your public key will have a \filename{.pub}
  14.512 +extension.  If you're using \command{puttygen} on Windows, you can
  14.513 +save the public key to a file of your choosing, or paste it from the
  14.514 +window it's displayed in straight into the
  14.515 +\sfilename{authorized\_keys} file.
  14.516 +
  14.517 +\subsection{Using an authentication agent}
  14.518 +
  14.519 +An authentication agent is a daemon that stores passphrases in memory
  14.520 +(so it will forget passphrases if you log out and log back in again).
  14.521 +An ssh client will notice if it's running, and query it for a
  14.522 +passphrase.  If there's no authentication agent running, or the agent
  14.523 +doesn't store the necessary passphrase, you'll have to type your
  14.524 +passphrase every time Mercurial tries to communicate with a server on
  14.525 +your behalf (e.g.~whenever you pull or push changes).
  14.526 +
  14.527 +The downside of storing passphrases in an agent is that it's possible
  14.528 +for a well-prepared attacker to recover the plain text of your
  14.529 +passphrases, in some cases even if your system has been power-cycled.
  14.530 +You should make your own judgment as to whether this is an acceptable
  14.531 +risk.  It certainly saves a lot of repeated typing.
  14.532 +
  14.533 +On Unix-like systems, the agent is called \command{ssh-agent}, and
  14.534 +it's often run automatically for you when you log in.  You'll need to
  14.535 +use the \command{ssh-add} command to add passphrases to the agent's
  14.536 +store.  On Windows, if you're using PuTTY, the \command{pageant}
  14.537 +command acts as the agent.  It adds an icon to your system tray that
  14.538 +will let you manage stored passphrases.
  14.539 +
  14.540 +\subsection{Configuring the server side properly}
  14.541 +
  14.542 +Because ssh can be fiddly to set up if you're new to it, there's a
  14.543 +variety of things that can go wrong.  Add Mercurial on top, and
  14.544 +there's plenty more scope for head-scratching.  Most of these
  14.545 +potential problems occur on the server side, not the client side.  The
  14.546 +good news is that once you've gotten a configuration working, it will
  14.547 +usually continue to work indefinitely.
  14.548 +
  14.549 +Before you try using Mercurial to talk to an ssh server, it's best to
  14.550 +make sure that you can use the normal \command{ssh} or \command{putty}
  14.551 +command to talk to the server first.  If you run into problems with
  14.552 +using these commands directly, Mercurial surely won't work.  Worse, it
  14.553 +will obscure the underlying problem.  Any time you want to debug
  14.554 +ssh-related Mercurial problems, you should drop back to making sure
  14.555 +that plain ssh client commands work first, \emph{before} you worry
  14.556 +about whether there's a problem with Mercurial.
  14.557 +
  14.558 +The first thing to be sure of on the server side is that you can
  14.559 +actually log in from another machine at all.  If you can't use
  14.560 +\command{ssh} or \command{putty} to log in, the error message you get
  14.561 +may give you a few hints as to what's wrong.  The most common problems
  14.562 +are as follows.
  14.563 +\begin{itemize}
  14.564 +\item If you get a ``connection refused'' error, either there isn't an
  14.565 +  SSH daemon running on the server at all, or it's inaccessible due to
  14.566 +  firewall configuration.
  14.567 +\item If you get a ``no route to host'' error, you either have an
  14.568 +  incorrect address for the server or a seriously locked down firewall
  14.569 +  that won't admit its existence at all.
  14.570 +\item If you get a ``permission denied'' error, you may have mistyped
  14.571 +  the username on the server, or you could have mistyped your key's
  14.572 +  passphrase or the remote user's password.
  14.573 +\end{itemize}
  14.574 +In summary, if you're having trouble talking to the server's ssh
  14.575 +daemon, first make sure that one is running at all.  On many systems
  14.576 +it will be installed, but disabled, by default.  Once you're done with
  14.577 +this step, you should then check that the server's firewall is
  14.578 +configured to allow incoming connections on the port the ssh daemon is
  14.579 +listening on (usually~22).  Don't worry about more exotic
  14.580 +possibilities for misconfiguration until you've checked these two
  14.581 +first.
  14.582 +
  14.583 +If you're using an authentication agent on the client side to store
  14.584 +passphrases for your keys, you ought to be able to log into the server
  14.585 +without being prompted for a passphrase or a password.  If you're
  14.586 +prompted for a passphrase, there are a few possible culprits.
  14.587 +\begin{itemize}
  14.588 +\item You might have forgotten to use \command{ssh-add} or
  14.589 +  \command{pageant} to store the passphrase.
  14.590 +\item You might have stored the passphrase for the wrong key.
  14.591 +\end{itemize}
  14.592 +If you're being prompted for the remote user's password, there are
  14.593 +another few possible problems to check.
  14.594 +\begin{itemize}
  14.595 +\item Either the user's home directory or their \sdirname{.ssh}
  14.596 +  directory might have excessively liberal permissions.  As a result,
  14.597 +  the ssh daemon will not trust or read their
  14.598 +  \sfilename{authorized\_keys} file.  For example, a group-writable
  14.599 +  home or \sdirname{.ssh} directory will often cause this symptom.
  14.600 +\item The user's \sfilename{authorized\_keys} file may have a problem.
  14.601 +  If anyone other than the user owns or can write to that file, the
  14.602 +  ssh daemon will not trust or read it.
  14.603 +\end{itemize}
  14.604 +
  14.605 +In the ideal world, you should be able to run the following command
  14.606 +successfully, and it should print exactly one line of output, the
  14.607 +current date and time.
  14.608 +\begin{codesample2}
  14.609 +  ssh myserver date
  14.610 +\end{codesample2}
  14.611 +
  14.612 +If, on your server, you have login scripts that print banners or other
  14.613 +junk even when running non-interactive commands like this, you should
  14.614 +fix them before you continue, so that they only print output if
  14.615 +they're run interactively.  Otherwise these banners will at least
  14.616 +clutter up Mercurial's output.  Worse, they could potentially cause
  14.617 +problems with running Mercurial commands remotely.  Mercurial makes
  14.618 +tries to detect and ignore banners in non-interactive \command{ssh}
  14.619 +sessions, but it is not foolproof.  (If you're editing your login
  14.620 +scripts on your server, the usual way to see if a login script is
  14.621 +running in an interactive shell is to check the return code from the
  14.622 +command \Verb|tty -s|.)
  14.623 +
  14.624 +Once you've verified that plain old ssh is working with your server,
  14.625 +the next step is to ensure that Mercurial runs on the server.  The
  14.626 +following command should run successfully:
  14.627 +\begin{codesample2}
  14.628 +  ssh myserver hg version
  14.629 +\end{codesample2}
  14.630 +If you see an error message instead of normal \hgcmd{version} output,
  14.631 +this is usually because you haven't installed Mercurial to
  14.632 +\dirname{/usr/bin}.  Don't worry if this is the case; you don't need
  14.633 +to do that.  But you should check for a few possible problems.
  14.634 +\begin{itemize}
  14.635 +\item Is Mercurial really installed on the server at all?  I know this
  14.636 +  sounds trivial, but it's worth checking!
  14.637 +\item Maybe your shell's search path (usually set via the \envar{PATH}
  14.638 +  environment variable) is simply misconfigured.
  14.639 +\item Perhaps your \envar{PATH} environment variable is only being set
  14.640 +  to point to the location of the \command{hg} executable if the login
  14.641 +  session is interactive.  This can happen if you're setting the path
  14.642 +  in the wrong shell login script.  See your shell's documentation for
  14.643 +  details.
  14.644 +\item The \envar{PYTHONPATH} environment variable may need to contain
  14.645 +  the path to the Mercurial Python modules.  It might not be set at
  14.646 +  all; it could be incorrect; or it may be set only if the login is
  14.647 +  interactive.
  14.648 +\end{itemize}
  14.649 +
  14.650 +If you can run \hgcmd{version} over an ssh connection, well done!
  14.651 +You've got the server and client sorted out.  You should now be able
  14.652 +to use Mercurial to access repositories hosted by that username on
  14.653 +that server.  If you run into problems with Mercurial and ssh at this
  14.654 +point, try using the \hggopt{--debug} option to get a clearer picture
  14.655 +of what's going on.
  14.656 +
  14.657 +\subsection{Using compression with ssh}
  14.658 +
  14.659 +Mercurial does not compress data when it uses the ssh protocol,
  14.660 +because the ssh protocol can transparently compress data.  However,
  14.661 +the default behaviour of ssh clients is \emph{not} to request
  14.662 +compression.
  14.663 +
  14.664 +Over any network other than a fast LAN (even a wireless network),
  14.665 +using compression is likely to significantly speed up Mercurial's
  14.666 +network operations.  For example, over a WAN, someone measured
  14.667 +compression as reducing the amount of time required to clone a
  14.668 +particularly large repository from~51 minutes to~17 minutes.
  14.669 +
  14.670 +Both \command{ssh} and \command{plink} accept a \cmdopt{ssh}{-C}
  14.671 +option which turns on compression.  You can easily edit your \hgrc\ to
  14.672 +enable compression for all of Mercurial's uses of the ssh protocol.
  14.673 +\begin{codesample2}
  14.674 +  [ui]
  14.675 +  ssh = ssh -C
  14.676 +\end{codesample2}
  14.677 +
  14.678 +If you use \command{ssh}, you can configure it to always use
  14.679 +compression when talking to your server.  To do this, edit your
  14.680 +\sfilename{.ssh/config} file (which may not yet exist), as follows.
  14.681 +\begin{codesample2}
  14.682 +  Host hg
  14.683 +    Compression yes
  14.684 +    HostName hg.example.com
  14.685 +\end{codesample2}
  14.686 +This defines an alias, \texttt{hg}.  When you use it on the
  14.687 +\command{ssh} command line or in a Mercurial \texttt{ssh}-protocol
  14.688 +URL, it will cause \command{ssh} to connect to \texttt{hg.example.com}
  14.689 +and use compression.  This gives you both a shorter name to type and
  14.690 +compression, each of which is a good thing in its own right.
  14.691 +
  14.692 +\section{Serving over HTTP using CGI}
  14.693 +\label{sec:collab:cgi}
  14.694 +
  14.695 +Depending on how ambitious you are, configuring Mercurial's CGI
  14.696 +interface can take anything from a few moments to several hours.
  14.697 +
  14.698 +We'll begin with the simplest of examples, and work our way towards a
  14.699 +more complex configuration.  Even for the most basic case, you're
  14.700 +almost certainly going to need to read and modify your web server's
  14.701 +configuration.
  14.702 +
  14.703 +\begin{note}
  14.704 +  Configuring a web server is a complex, fiddly, and highly
  14.705 +  system-dependent activity.  I can't possibly give you instructions
  14.706 +  that will cover anything like all of the cases you will encounter.
  14.707 +  Please use your discretion and judgment in following the sections
  14.708 +  below.  Be prepared to make plenty of mistakes, and to spend a lot
  14.709 +  of time reading your server's error logs.
  14.710 +\end{note}
  14.711 +
  14.712 +\subsection{Web server configuration checklist}
  14.713 +
  14.714 +Before you continue, do take a few moments to check a few aspects of
  14.715 +your system's setup.
  14.716 +
  14.717 +\begin{enumerate}
  14.718 +\item Do you have a web server installed at all?  Mac OS X ships with
  14.719 +  Apache, but many other systems may not have a web server installed.
  14.720 +\item If you have a web server installed, is it actually running?  On
  14.721 +  most systems, even if one is present, it will be disabled by
  14.722 +  default.
  14.723 +\item Is your server configured to allow you to run CGI programs in
  14.724 +  the directory where you plan to do so?  Most servers default to
  14.725 +  explicitly disabling the ability to run CGI programs.
  14.726 +\end{enumerate}
  14.727 +
  14.728 +If you don't have a web server installed, and don't have substantial
  14.729 +experience configuring Apache, you should consider using the
  14.730 +\texttt{lighttpd} web server instead of Apache.  Apache has a
  14.731 +well-deserved reputation for baroque and confusing configuration.
  14.732 +While \texttt{lighttpd} is less capable in some ways than Apache, most
  14.733 +of these capabilities are not relevant to serving Mercurial
  14.734 +repositories.  And \texttt{lighttpd} is undeniably \emph{much} easier
  14.735 +to get started with than Apache.
  14.736 +
  14.737 +\subsection{Basic CGI configuration}
  14.738 +
  14.739 +On Unix-like systems, it's common for users to have a subdirectory
  14.740 +named something like \dirname{public\_html} in their home directory,
  14.741 +from which they can serve up web pages.  A file named \filename{foo}
  14.742 +in this directory will be accessible at a URL of the form
  14.743 +\texttt{http://www.example.com/\~{}username/foo}.
  14.744 +
  14.745 +To get started, find the \sfilename{hgweb.cgi} script that should be
  14.746 +present in your Mercurial installation.  If you can't quickly find a
  14.747 +local copy on your system, simply download one from the master
  14.748 +Mercurial repository at
  14.749 +\url{http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi}.
  14.750 +
  14.751 +You'll need to copy this script into your \dirname{public\_html}
  14.752 +directory, and ensure that it's executable.
  14.753 +\begin{codesample2}
  14.754 +  cp .../hgweb.cgi ~/public_html
  14.755 +  chmod 755 ~/public_html/hgweb.cgi
  14.756 +\end{codesample2}
  14.757 +The \texttt{755} argument to \command{chmod} is a little more general
  14.758 +than just making the script executable: it ensures that the script is
  14.759 +executable by anyone, and that ``group'' and ``other'' write
  14.760 +permissions are \emph{not} set.  If you were to leave those write
  14.761 +permissions enabled, Apache's \texttt{suexec} subsystem would likely
  14.762 +refuse to execute the script.  In fact, \texttt{suexec} also insists
  14.763 +that the \emph{directory} in which the script resides must not be
  14.764 +writable by others.
  14.765 +\begin{codesample2}
  14.766 +  chmod 755 ~/public_html
  14.767 +\end{codesample2}
  14.768 +
  14.769 +\subsubsection{What could \emph{possibly} go wrong?}
  14.770 +\label{sec:collab:wtf}
  14.771 +
  14.772 +Once you've copied the CGI script into place, go into a web browser,
  14.773 +and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi},
  14.774 +\emph{but} brace yourself for instant failure.  There's a high
  14.775 +probability that trying to visit this URL will fail, and there are
  14.776 +many possible reasons for this.  In fact, you're likely to stumble
  14.777 +over almost every one of the possible errors below, so please read
  14.778 +carefully.  The following are all of the problems I ran into on a
  14.779 +system running Fedora~7, with a fresh installation of Apache, and a
  14.780 +user account that I created specially to perform this exercise.
  14.781 +
  14.782 +Your web server may have per-user directories disabled.  If you're
  14.783 +using Apache, search your config file for a \texttt{UserDir}
  14.784 +directive.  If there's none present, per-user directories will be
  14.785 +disabled.  If one exists, but its value is \texttt{disabled}, then
  14.786 +per-user directories will be disabled.  Otherwise, the string after
  14.787 +\texttt{UserDir} gives the name of the subdirectory that Apache will
  14.788 +look in under your home directory, for example \dirname{public\_html}.
  14.789 +
  14.790 +Your file access permissions may be too restrictive.  The web server
  14.791 +must be able to traverse your home directory and directories under
  14.792 +your \dirname{public\_html} directory, and read files under the latter
  14.793 +too.  Here's a quick recipe to help you to make your permissions more
  14.794 +appropriate.
  14.795 +\begin{codesample2}
  14.796 +  chmod 755 ~
  14.797 +  find ~/public_html -type d -print0 | xargs -0r chmod 755
  14.798 +  find ~/public_html -type f -print0 | xargs -0r chmod 644
  14.799 +\end{codesample2}
  14.800 +
  14.801 +The other possibility with permissions is that you might get a
  14.802 +completely empty window when you try to load the script.  In this
  14.803 +case, it's likely that your access permissions are \emph{too
  14.804 +  permissive}.  Apache's \texttt{suexec} subsystem won't execute a
  14.805 +script that's group-~or world-writable, for example.
  14.806 +
  14.807 +Your web server may be configured to disallow execution of CGI
  14.808 +programs in your per-user web directory.  Here's Apache's
  14.809 +default per-user configuration from my Fedora system.
  14.810 +\begin{codesample2}
  14.811 +  <Directory /home/*/public_html>
  14.812 +      AllowOverride FileInfo AuthConfig Limit
  14.813 +      Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
  14.814 +      <Limit GET POST OPTIONS>
  14.815 +          Order allow,deny
  14.816 +          Allow from all
  14.817 +      </Limit>
  14.818 +      <LimitExcept GET POST OPTIONS>
  14.819 +          Order deny,allow
  14.820 +          Deny from all
  14.821 +      </LimitExcept>
  14.822 +  </Directory>
  14.823 +\end{codesample2}
  14.824 +If you find a similar-looking \texttt{Directory} group in your Apache
  14.825 +configuration, the directive to look at inside it is \texttt{Options}.
  14.826 +Add \texttt{ExecCGI} to the end of this list if it's missing, and
  14.827 +restart the web server.
  14.828 +
  14.829 +If you find that Apache serves you the text of the CGI script instead
  14.830 +of executing it, you may need to either uncomment (if already present)
  14.831 +or add a directive like this.
  14.832 +\begin{codesample2}
  14.833 +  AddHandler cgi-script .cgi
  14.834 +\end{codesample2}
  14.835 +
  14.836 +The next possibility is that you might be served with a colourful
  14.837 +Python backtrace claiming that it can't import a
  14.838 +\texttt{mercurial}-related module.  This is actually progress!  The
  14.839 +server is now capable of executing your CGI script.  This error is
  14.840 +only likely to occur if you're running a private installation of
  14.841 +Mercurial, instead of a system-wide version.  Remember that the web
  14.842 +server runs the CGI program without any of the environment variables
  14.843 +that you take for granted in an interactive session.  If this error
  14.844 +happens to you, edit your copy of \sfilename{hgweb.cgi} and follow the
  14.845 +directions inside it to correctly set your \envar{PYTHONPATH}
  14.846 +environment variable.
  14.847 +
  14.848 +Finally, you are \emph{certain} to by served with another colourful
  14.849 +Python backtrace: this one will complain that it can't find
  14.850 +\dirname{/path/to/repository}.  Edit your \sfilename{hgweb.cgi} script
  14.851 +and replace the \dirname{/path/to/repository} string with the complete
  14.852 +path to the repository you want to serve up.
  14.853 +
  14.854 +At this point, when you try to reload the page, you should be
  14.855 +presented with a nice HTML view of your repository's history.  Whew!
  14.856 +
  14.857 +\subsubsection{Configuring lighttpd}
  14.858 +
  14.859 +To be exhaustive in my experiments, I tried configuring the
  14.860 +increasingly popular \texttt{lighttpd} web server to serve the same
  14.861 +repository as I described with Apache above.  I had already overcome
  14.862 +all of the problems I outlined with Apache, many of which are not
  14.863 +server-specific.  As a result, I was fairly sure that my file and
  14.864 +directory permissions were good, and that my \sfilename{hgweb.cgi}
  14.865 +script was properly edited.
  14.866 +
  14.867 +Once I had Apache running, getting \texttt{lighttpd} to serve the
  14.868 +repository was a snap (in other words, even if you're trying to use
  14.869 +\texttt{lighttpd}, you should read the Apache section).  I first had
  14.870 +to edit the \texttt{mod\_access} section of its config file to enable
  14.871 +\texttt{mod\_cgi} and \texttt{mod\_userdir}, both of which were
  14.872 +disabled by default on my system.  I then added a few lines to the end
  14.873 +of the config file, to configure these modules.
  14.874 +\begin{codesample2}
  14.875 +  userdir.path = "public_html"
  14.876 +  cgi.assign = ( ".cgi" => "" )
  14.877 +\end{codesample2}
  14.878 +With this done, \texttt{lighttpd} ran immediately for me.  If I had
  14.879 +configured \texttt{lighttpd} before Apache, I'd almost certainly have
  14.880 +run into many of the same system-level configuration problems as I did
  14.881 +with Apache.  However, I found \texttt{lighttpd} to be noticeably
  14.882 +easier to configure than Apache, even though I've used Apache for over
  14.883 +a decade, and this was my first exposure to \texttt{lighttpd}.
  14.884 +
  14.885 +\subsection{Sharing multiple repositories with one CGI script}
  14.886 +
  14.887 +The \sfilename{hgweb.cgi} script only lets you publish a single
  14.888 +repository, which is an annoying restriction.  If you want to publish
  14.889 +more than one without wracking yourself with multiple copies of the
  14.890 +same script, each with different names, a better choice is to use the
  14.891 +\sfilename{hgwebdir.cgi} script.
  14.892 +
  14.893 +The procedure to configure \sfilename{hgwebdir.cgi} is only a little
  14.894 +more involved than for \sfilename{hgweb.cgi}.  First, you must obtain
  14.895 +a copy of the script.  If you don't have one handy, you can download a
  14.896 +copy from the master Mercurial repository at
  14.897 +\url{http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi}.
  14.898 +
  14.899 +You'll need to copy this script into your \dirname{public\_html}
  14.900 +directory, and ensure that it's executable.
  14.901 +\begin{codesample2}
  14.902 +  cp .../hgwebdir.cgi ~/public_html
  14.903 +  chmod 755 ~/public_html ~/public_html/hgwebdir.cgi
  14.904 +\end{codesample2}
  14.905 +With basic configuration out of the way, try to visit
  14.906 +\url{http://myhostname/~myuser/hgwebdir.cgi} in your browser.  It
  14.907 +should display an empty list of repositories.  If you get a blank
  14.908 +window or error message, try walking through the list of potential
  14.909 +problems in section~\ref{sec:collab:wtf}.
  14.910 +
  14.911 +The \sfilename{hgwebdir.cgi} script relies on an external
  14.912 +configuration file.  By default, it searches for a file named
  14.913 +\sfilename{hgweb.config} in the same directory as itself.  You'll need
  14.914 +to create this file, and make it world-readable.  The format of the
  14.915 +file is similar to a Windows ``ini'' file, as understood by Python's
  14.916 +\texttt{ConfigParser}~\cite{web:configparser} module.
  14.917 +
  14.918 +The easiest way to configure \sfilename{hgwebdir.cgi} is with a
  14.919 +section named \texttt{collections}.  This will automatically publish
  14.920 +\emph{every} repository under the directories you name.  The section
  14.921 +should look like this:
  14.922 +\begin{codesample2}
  14.923 +  [collections]
  14.924 +  /my/root = /my/root
  14.925 +\end{codesample2}
  14.926 +Mercurial interprets this by looking at the directory name on the
  14.927 +\emph{right} hand side of the ``\texttt{=}'' sign; finding
  14.928 +repositories in that directory hierarchy; and using the text on the
  14.929 +\emph{left} to strip off matching text from the names it will actually
  14.930 +list in the web interface.  The remaining component of a path after
  14.931 +this stripping has occurred is called a ``virtual path''.
  14.932 +
  14.933 +Given the example above, if we have a repository whose local path is
  14.934 +\dirname{/my/root/this/repo}, the CGI script will strip the leading
  14.935 +\dirname{/my/root} from the name, and publish the repository with a
  14.936 +virtual path of \dirname{this/repo}.  If the base URL for our CGI
  14.937 +script is \url{http://myhostname/~myuser/hgwebdir.cgi}, the complete
  14.938 +URL for that repository will be
  14.939 +\url{http://myhostname/~myuser/hgwebdir.cgi/this/repo}.
  14.940 +
  14.941 +If we replace \dirname{/my/root} on the left hand side of this example
  14.942 +with \dirname{/my}, then \sfilename{hgwebdir.cgi} will only strip off
  14.943 +\dirname{/my} from the repository name, and will give us a virtual
  14.944 +path of \dirname{root/this/repo} instead of \dirname{this/repo}.
  14.945 +
  14.946 +The \sfilename{hgwebdir.cgi} script will recursively search each
  14.947 +directory listed in the \texttt{collections} section of its
  14.948 +configuration file, but it will \texttt{not} recurse into the
  14.949 +repositories it finds.
  14.950 +
  14.951 +The \texttt{collections} mechanism makes it easy to publish many
  14.952 +repositories in a ``fire and forget'' manner.  You only need to set up
  14.953 +the CGI script and configuration file one time.  Afterwards, you can
  14.954 +publish or unpublish a repository at any time by simply moving it
  14.955 +into, or out of, the directory hierarchy in which you've configured
  14.956 +\sfilename{hgwebdir.cgi} to look.
  14.957 +
  14.958 +\subsubsection{Explicitly specifying which repositories to publish}
  14.959 +
  14.960 +In addition to the \texttt{collections} mechanism, the
  14.961 +\sfilename{hgwebdir.cgi} script allows you to publish a specific list
  14.962 +of repositories.  To do so, create a \texttt{paths} section, with
  14.963 +contents of the following form.
  14.964 +\begin{codesample2}
  14.965 +  [paths]
  14.966 +  repo1 = /my/path/to/some/repo
  14.967 +  repo2 = /some/path/to/another
  14.968 +\end{codesample2}
  14.969 +In this case, the virtual path (the component that will appear in a
  14.970 +URL) is on the left hand side of each definition, while the path to
  14.971 +the repository is on the right.  Notice that there does not need to be
  14.972 +any relationship between the virtual path you choose and the location
  14.973 +of a repository in your filesystem.
  14.974 +
  14.975 +If you wish, you can use both the \texttt{collections} and
  14.976 +\texttt{paths} mechanisms simultaneously in a single configuration
  14.977 +file.
  14.978 +
  14.979 +\begin{note}
  14.980 +  If multiple repositories have the same virtual path,
  14.981 +  \sfilename{hgwebdir.cgi} will not report an error.  Instead, it will
  14.982 +  behave unpredictably.
  14.983 +\end{note}
  14.984 +
  14.985 +\subsection{Downloading source archives}
  14.986 +
  14.987 +Mercurial's web interface lets users download an archive of any
  14.988 +revision.  This archive will contain a snapshot of the working
  14.989 +directory as of that revision, but it will not contain a copy of the
  14.990 +repository data.
  14.991 +
  14.992 +By default, this feature is not enabled.  To enable it, you'll need to
  14.993 +add an \rcitem{web}{allow\_archive} item to the \rcsection{web}
  14.994 +section of your \hgrc.
  14.995 +
  14.996 +\subsection{Web configuration options}
  14.997 +
  14.998 +Mercurial's web interfaces (the \hgcmd{serve} command, and the
  14.999 +\sfilename{hgweb.cgi} and \sfilename{hgwebdir.cgi} scripts) have a
 14.1000 +number of configuration options that you can set.  These belong in a
 14.1001 +section named \rcsection{web}.
 14.1002 +\begin{itemize}
 14.1003 +\item[\rcitem{web}{allow\_archive}] Determines which (if any) archive
 14.1004 +  download mechanisms Mercurial supports.  If you enable this
 14.1005 +  feature, users of the web interface will be able to download an
 14.1006 +  archive of whatever revision of a repository they are viewing.
 14.1007 +  To enable the archive feature, this item must take the form of a
 14.1008 +  sequence of words drawn from the list below.
 14.1009 +  \begin{itemize}
 14.1010 +  \item[\texttt{bz2}] A \command{tar} archive, compressed using
 14.1011 +    \texttt{bzip2} compression.  This has the best compression ratio,
 14.1012 +    but uses the most CPU time on the server.
 14.1013 +  \item[\texttt{gz}] A \command{tar} archive, compressed using
 14.1014 +    \texttt{gzip} compression.
 14.1015 +  \item[\texttt{zip}] A \command{zip} archive, compressed using LZW
 14.1016 +    compression.  This format has the worst compression ratio, but is
 14.1017 +    widely used in the Windows world.
 14.1018 +  \end{itemize}
 14.1019 +  If you provide an empty list, or don't have an
 14.1020 +  \rcitem{web}{allow\_archive} entry at all, this feature will be
 14.1021 +  disabled.  Here is an example of how to enable all three supported
 14.1022 +  formats.
 14.1023 +  \begin{codesample4}
 14.1024 +    [web]
 14.1025 +    allow_archive = bz2 gz zip
 14.1026 +  \end{codesample4}
 14.1027 +\item[\rcitem{web}{allowpull}] Boolean.  Determines whether the web
 14.1028 +  interface allows remote users to \hgcmd{pull} and \hgcmd{clone} this
 14.1029 +  repository over~HTTP.  If set to \texttt{no} or \texttt{false}, only
 14.1030 +  the ``human-oriented'' portion of the web interface is available.
 14.1031 +\item[\rcitem{web}{contact}] String.  A free-form (but preferably
 14.1032 +  brief) string identifying the person or group in charge of the
 14.1033 +  repository.  This often contains the name and email address of a
 14.1034 +  person or mailing list.  It often makes sense to place this entry in
 14.1035 +  a repository's own \sfilename{.hg/hgrc} file, but it can make sense
 14.1036 +  to use in a global \hgrc\ if every repository has a single
 14.1037 +  maintainer.
 14.1038 +\item[\rcitem{web}{maxchanges}] Integer.  The default maximum number
 14.1039 +  of changesets to display in a single page of output.
 14.1040 +\item[\rcitem{web}{maxfiles}] Integer.  The default maximum number
 14.1041 +  of modified files to display in a single page of output.
 14.1042 +\item[\rcitem{web}{stripes}] Integer.  If the web interface displays
 14.1043 +  alternating ``stripes'' to make it easier to visually align rows
 14.1044 +  when you are looking at a table, this number controls the number of
 14.1045 +  rows in each stripe.
 14.1046 +\item[\rcitem{web}{style}] Controls the template Mercurial uses to
 14.1047 +  display the web interface.  Mercurial ships with two web templates,
 14.1048 +  named \texttt{default} and \texttt{gitweb} (the latter is much more
 14.1049 +  visually attractive).  You can also specify a custom template of
 14.1050 +  your own; see chapter~\ref{chap:template} for details.  Here, you
 14.1051 +  can see how to enable the \texttt{gitweb} style.
 14.1052 +  \begin{codesample4}
 14.1053 +    [web]
 14.1054 +    style = gitweb
 14.1055 +  \end{codesample4}
 14.1056 +\item[\rcitem{web}{templates}] Path.  The directory in which to search
 14.1057 +  for template files.  By default, Mercurial searches in the directory
 14.1058 +  in which it was installed.
 14.1059 +\end{itemize}
 14.1060 +If you are using \sfilename{hgwebdir.cgi}, you can place a few
 14.1061 +configuration items in a \rcsection{web} section of the
 14.1062 +\sfilename{hgweb.config} file instead of a \hgrc\ file, for
 14.1063 +convenience.  These items are \rcitem{web}{motd} and
 14.1064 +\rcitem{web}{style}.
 14.1065 +
 14.1066 +\subsubsection{Options specific to an individual repository}
 14.1067 +
 14.1068 +A few \rcsection{web} configuration items ought to be placed in a
 14.1069 +repository's local \sfilename{.hg/hgrc}, rather than a user's or
 14.1070 +global \hgrc.
 14.1071 +\begin{itemize}
 14.1072 +\item[\rcitem{web}{description}] String.  A free-form (but preferably
 14.1073 +  brief) string that describes the contents or purpose of the
 14.1074 +  repository.
 14.1075 +\item[\rcitem{web}{name}] String.  The name to use for the repository
 14.1076 +  in the web interface.  This overrides the default name, which is the
 14.1077 +  last component of the repository's path.
 14.1078 +\end{itemize}
 14.1079 +
 14.1080 +\subsubsection{Options specific to the \hgcmd{serve} command}
 14.1081 +
 14.1082 +Some of the items in the \rcsection{web} section of a \hgrc\ file are
 14.1083 +only for use with the \hgcmd{serve} command.
 14.1084 +\begin{itemize}
 14.1085 +\item[\rcitem{web}{accesslog}] Path.  The name of a file into which to
 14.1086 +  write an access log.  By default, the \hgcmd{serve} command writes
 14.1087 +  this information to standard output, not to a file.  Log entries are
 14.1088 +  written in the standard ``combined'' file format used by almost all
 14.1089 +  web servers.
 14.1090 +\item[\rcitem{web}{address}] String.  The local address on which the
 14.1091 +  server should listen for incoming connections.  By default, the
 14.1092 +  server listens on all addresses.
 14.1093 +\item[\rcitem{web}{errorlog}] Path.  The name of a file into which to
 14.1094 +  write an error log.  By default, the \hgcmd{serve} command writes this
 14.1095 +  information to standard error, not to a file.
 14.1096 +\item[\rcitem{web}{ipv6}] Boolean.  Whether to use the IPv6 protocol.
 14.1097 +  By default, IPv6 is not used. 
 14.1098 +\item[\rcitem{web}{port}] Integer.  The TCP~port number on which the
 14.1099 +  server should listen.  The default port number used is~8000.
 14.1100 +\end{itemize}
 14.1101 +
 14.1102 +\subsubsection{Choosing the right \hgrc\ file to add \rcsection{web}
 14.1103 +  items to}
 14.1104 +
 14.1105 +It is important to remember that a web server like Apache or
 14.1106 +\texttt{lighttpd} will run under a user~ID that is different to yours.
 14.1107 +CGI scripts run by your server, such as \sfilename{hgweb.cgi}, will
 14.1108 +usually also run under that user~ID.
 14.1109 +
 14.1110 +If you add \rcsection{web} items to your own personal \hgrc\ file, CGI
 14.1111 +scripts won't read that \hgrc\ file.  Those settings will thus only
 14.1112 +affect the behaviour of the \hgcmd{serve} command when you run it.  To
 14.1113 +cause CGI scripts to see your settings, either create a \hgrc\ file in
 14.1114 +the home directory of the user ID that runs your web server, or add
 14.1115 +those settings to a system-wide \hgrc\ file.
 14.1116 +
 14.1117 +
 14.1118 +%%% Local Variables: 
 14.1119 +%%% mode: latex
 14.1120 +%%% TeX-master: "00book"
 14.1121 +%%% End: