1.1 --- a/en/00book.tex	Thu Mar 05 21:52:23 2009 +0200
     1.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.3 @@ -1,76 +0,0 @@
     1.4 -% The use of oneside here is a temporary hack; \marginpar entries
     1.5 -% don't show up on odd pages of PDF output without it.  Sigh.
     1.6 -\documentclass[oneside]{book}
     1.7 -\usepackage{enumerate}
     1.8 -\usepackage{fullpage}
     1.9 -\usepackage{makeidx}
    1.10 -\usepackage{ifpdf}
    1.11 -\usepackage{graphicx}
    1.12 -\usepackage{pslatex}
    1.13 -\usepackage{fancyvrb}
    1.14 -% leave hyperref until last
    1.15 -\usepackage[colorlinks=true,bookmarks=true,pdftitle={Distributed
    1.16 -  revision control with Mercurial},pdfsubject={Revision
    1.17 -  control},pdfkeywords={Mercurial, Revision control, Distributed
    1.18 -  revision control},pdfauthor={Bryan O'Sullivan}]{hyperref}
    1.19 -
    1.20 -\include{99defs}
    1.21 -
    1.22 -\title{Distributed revision control with Mercurial} \author{Bryan
    1.23 -  O'Sullivan}
    1.24 -\date{Copyright \copyright\ 2006, 2007 Bryan O'Sullivan.\\
    1.25 -  This material may be distributed only subject to the terms and
    1.26 -  conditions set forth in version 1.0 of the Open Publication License.
    1.27 -  Please refer to Appendix~\ref{cha:opl} for the license text.\\
    1.28 -  This book was prepared from
    1.29 -  \href{http://hg.serpentine.com/mercurial/book/}{rev~\input{build_id}}
    1.30 -  using \href{http://www.selenic.com/hg/}{rev~\input{hg_id}} of Mercurial.}
    1.31 -
    1.32 -\makeindex
    1.33 -
    1.34 -\begin{document}
    1.35 -
    1.36 -\maketitle
    1.37 -
    1.38 -\addcontentsline{toc}{chapter}{Contents}
    1.39 -\pagenumbering{roman}
    1.40 -\tableofcontents
    1.41 -\listoffigures
    1.42 -%\listoftables
    1.43 -
    1.44 -\pagenumbering{arabic}
    1.45 -
    1.46 -\include{ch00-preface}
    1.47 -\include{ch01-intro}
    1.48 -\include{ch02-tour-basic}
    1.49 -\include{ch03-tour-merge}
    1.50 -\include{ch04-concepts}
    1.51 -\include{ch05-daily}
    1.52 -\include{ch06-collab}
    1.53 -\include{ch07-filenames}
    1.54 -\include{ch08-branch}
    1.55 -\include{ch09-undo}
    1.56 -\include{ch10-hook}
    1.57 -\include{ch11-template}
    1.58 -\include{ch12-mq}
    1.59 -\include{ch13-mq-collab}
    1.60 -\include{ch14-hgext}
    1.61 -
    1.62 -\appendix
    1.63 -\include{appA-cmdref}
    1.64 -\include{appB-mq-ref}
    1.65 -\include{appC-srcinstall}
    1.66 -\include{appD-license}
    1.67 -\addcontentsline{toc}{chapter}{Bibliography}
    1.68 -\bibliographystyle{alpha}
    1.69 -\bibliography{99book}
    1.70 -
    1.71 -\addcontentsline{toc}{chapter}{Index}
    1.72 -\printindex
    1.73 -
    1.74 -\end{document}
    1.75 -
    1.76 -%%% Local Variables: 
    1.77 -%%% mode: latex
    1.78 -%%% TeX-master: t
    1.79 -%%% End: 

     2.1 --- a/en/99defs.tex	Thu Mar 05 21:52:23 2009 +0200
     2.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.3 @@ -1,146 +0,0 @@
     2.4 -% Bug ID.
     2.5 -\newcommand{\bug}[1]{\index{Mercurial bug
     2.6 -    database!\href{http://www.selenic.com/mercurial/bts/issue#1}{bug
     2.7 -      ~#1}}\href{http://www.selenic.com/mercurial/bts/issue#1}{Mercurial
     2.8 -    bug no.~#1}}
     2.9 -
    2.10 -% File name in the user's home directory.
    2.11 -\newcommand{\tildefile}[1]{\texttt{\~{}/#1}}
    2.12 -
    2.13 -% File name.
    2.14 -\newcommand{\filename}[1]{\texttt{#1}}
    2.15 -
    2.16 -% Directory name.
    2.17 -\newcommand{\dirname}[1]{\texttt{#1}}
    2.18 -
    2.19 -% File name, with index entry.
    2.20 -% The ``s'' prefix comes from ``special''.
    2.21 -\newcommand{\sfilename}[1]{\index{\texttt{#1} file}\texttt{#1}}
    2.22 -
    2.23 -% Directory name, with index entry.
    2.24 -\newcommand{\sdirname}[1]{\index{\texttt{#1} directory}\texttt{#1}}
    2.25 -
    2.26 -% Mercurial extension.
    2.27 -\newcommand{\hgext}[1]{\index{\texttt{#1} extension}\texttt{#1}}
    2.28 -
    2.29 -% Command provided by a Mercurial extension.
    2.30 -\newcommand{\hgxcmd}[2]{\index{\texttt{#2} command (\texttt{#1}
    2.31 -      extension)}\index{\texttt{#1} extension!\texttt{#2} command}``\texttt{hg #2}''}
    2.32 -
    2.33 -% Mercurial command.
    2.34 -\newcommand{\hgcmd}[1]{\index{\texttt{#1} command}``\texttt{hg #1}''}
    2.35 -
    2.36 -% Mercurial command, with arguments.
    2.37 -\newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''}
    2.38 -
    2.39 -\newcommand{\tplkword}[1]{\index{\texttt{#1} template keyword}\index{template keywords!\texttt{#1}}\texttt{#1}}
    2.40 -
    2.41 -\newcommand{\tplkwfilt}[2]{\index{\texttt{#1} template keyword!\texttt{#2}
    2.42 -    filter}\index{template filters!\texttt{#2}}\index{\texttt{#2}
    2.43 -    template filter}\texttt{#2}}
    2.44 -
    2.45 -\newcommand{\tplfilter}[1]{\index{template
    2.46 -    filters!\texttt{#1}}\index{\texttt{#1} template
    2.47 -    filter}\texttt{#1}}
    2.48 -
    2.49 -% Shell/system command.
    2.50 -\newcommand{\command}[1]{\index{\texttt{#1} system command}\texttt{#1}}
    2.51 -
    2.52 -% Shell/system command, with arguments.
    2.53 -\newcommand{\cmdargs}[2]{\index{\texttt{#1} system command}``\texttt{#1 #2}''}
    2.54 -
    2.55 -% Mercurial command option.
    2.56 -\newcommand{\hgopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}}
    2.57 -
    2.58 -% Mercurial command option, provided by an extension command.
    2.59 -\newcommand{\hgxopt}[3]{\index{\texttt{#2} command (\texttt{#1} extension)!\texttt{#3} option}\index{\texttt{#1} extension!\texttt{#2} command!\texttt{#3} option}\texttt{#3}}
    2.60 -
    2.61 -% Mercurial global option.
    2.62 -\newcommand{\hggopt}[1]{\index{global options!\texttt{#1} option}\texttt{#1}}
    2.63 -
    2.64 -% Shell/system command option.
    2.65 -\newcommand{\cmdopt}[2]{\index{\texttt{#1} command!\texttt{#2} option}\texttt{#2}}
    2.66 -
    2.67 -% Command option.
    2.68 -\newcommand{\option}[1]{\texttt{#1}}
    2.69 -
    2.70 -% Software package.
    2.71 -\newcommand{\package}[1]{\index{\texttt{#1} package}\texttt{#1}}
    2.72 -
    2.73 -% Section name from a hgrc file.
    2.74 -\newcommand{\rcsection}[1]{\index{\texttt{hgrc} file!\texttt{#1} section}\texttt{[#1]}}
    2.75 -
    2.76 -% Named item in a hgrc file section.
    2.77 -\newcommand{\rcitem}[2]{\index{\texttt{hgrc} file!\texttt{#1}
    2.78 -    section!\texttt{#2} entry}\texttt{#2}}
    2.79 -
    2.80 -% hgrc file.
    2.81 -\newcommand{\hgrc}{\index{configuration file!\texttt{hgrc}
    2.82 -    (Linux/Unix)}\index{\texttt{hgrc} configuration file}\texttt{hgrc}}
    2.83 -
    2.84 -% Mercurial.ini file.
    2.85 -\newcommand{\hgini}{\index{configuration file!\texttt{Mercurial.ini}
    2.86 -    (Windows)}\index{\texttt{Mercurial.ini} configuration file}\texttt{Mercurial.ini}}
    2.87 -
    2.88 -% Hook name.
    2.89 -\newcommand{\hook}[1]{\index{\texttt{#1} hook}\index{hooks!\texttt{#1}}\texttt{#1}}
    2.90 -
    2.91 -% Environment variable.
    2.92 -\newcommand{\envar}[1]{\index{\texttt{#1} environment
    2.93 -    variable}\index{environment variables!\texttt{#1}}\texttt{#1}}
    2.94 -
    2.95 -% Python module.
    2.96 -\newcommand{\pymod}[1]{\index{\texttt{#1} module}\texttt{#1}}
    2.97 -
    2.98 -% Python class in a module.
    2.99 -\newcommand{\pymodclass}[2]{\index{\texttt{#1} module!\texttt{#2}
   2.100 -    class}\texttt{#1.#2}}
   2.101 -
   2.102 -% Python function in a module.
   2.103 -\newcommand{\pymodfunc}[2]{\index{\texttt{#1} module!\texttt{#2}
   2.104 -    function}\texttt{#1.#2}}
   2.105 -
   2.106 -% Note: blah blah.
   2.107 -\newsavebox{\notebox}
   2.108 -\newenvironment{note}%
   2.109 -  {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Note:}\space}%
   2.110 -  {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}}
   2.111 -\newenvironment{caution}%
   2.112 -  {\begin{lrbox}{\notebox}\begin{minipage}{0.7\textwidth}\textbf{Caution:}\space}%
   2.113 -  {\end{minipage}\end{lrbox}\fbox{\usebox{\notebox}}}
   2.114 -
   2.115 -% Code sample, eating 4 characters of leading space.
   2.116 -\DefineVerbatimEnvironment{codesample4}{Verbatim}{frame=single,gobble=4,numbers=left,commandchars=\\\{\}}
   2.117 -
   2.118 -% Code sample, eating 2 characters of leading space.
   2.119 -\DefineVerbatimEnvironment{codesample2}{Verbatim}{frame=single,gobble=2,numbers=left,commandchars=\\\{\}}
   2.120 -
   2.121 -% Interaction from the examples directory.
   2.122 -\newcommand{\interaction}[1]{\VerbatimInput[frame=single,numbers=left,commandchars=\\\{\}]{examples/#1.lxo}}
   2.123 -% Example code from the examples directory.
   2.124 -\newcommand{\excode}[1]{\VerbatimInput[frame=single,numbers=left,commandchars=\\\{\}]{../examples/#1}}
   2.125 -
   2.126 -% Graphics inclusion.
   2.127 -\ifpdf
   2.128 -  \newcommand{\grafix}[1]{\includegraphics{#1}}
   2.129 -\else
   2.130 -  \newcommand{\grafix}[1]{\includegraphics{#1.png}}
   2.131 -\fi
   2.132 -
   2.133 -% Reference entry for a command.
   2.134 -\newcommand{\cmdref}[2]{\section{\hgcmd{#1}---#2}\label{cmdref:#1}\index{\texttt{#1} command}}
   2.135 -
   2.136 -% Reference entry for a command option with long and short forms.
   2.137 -\newcommand{\optref}[3]{\subsubsection{\hgopt{#1}{--#3}, also \hgopt{#1}{-#2}}}
   2.138 -
   2.139 -% Reference entry for a command option with only long form.
   2.140 -\newcommand{\loptref}[2]{\subsubsection{\hgopt{#1}{--#2} option}}
   2.141 -
   2.142 -% command to generate a footnote to be used as a translator's note
   2.143 -\newcommand{\ndt}[1]{\footnote{\textbf{N. del T.} #1}}
   2.144 -
   2.145 -
   2.146 -%%% Local Variables: 
   2.147 -%%% mode: latex
   2.148 -%%% TeX-master: "00book"
   2.149 -%%% End: 

     3.1 --- a/en/appA-cmdref.tex	Thu Mar 05 21:52:23 2009 +0200
     3.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.3 @@ -1,175 +0,0 @@
     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} differ?}
   3.130 -\label{cmdref:diff-vs-status}
   3.131 -
   3.132 -When you run the \hgcmd{status} command, you'll see a list of files
   3.133 -that Mercurial will record changes for the next time you perform a
   3.134 -commit.  If you run the \hgcmd{diff} command, you may notice that it
   3.135 -prints diffs for only a \emph{subset} of the files that \hgcmd{status}
   3.136 -listed.  There are two possible reasons for this.
   3.137 -
   3.138 -The first is that \hgcmd{status} prints some kinds of modifications
   3.139 -that \hgcmd{diff} doesn't normally display.  The \hgcmd{diff} command
   3.140 -normally outputs unified diffs, which don't have the ability to
   3.141 -represent some changes that Mercurial can track.  Most notably,
   3.142 -traditional diffs can't represent a change in whether or not a file is
   3.143 -executable, but Mercurial records this information.
   3.144 -
   3.145 -If you use the \hgopt{diff}{--git} option to \hgcmd{diff}, it will
   3.146 -display \command{git}-compatible diffs that \emph{can} display this
   3.147 -extra information.
   3.148 -
   3.149 -The second possible reason that \hgcmd{diff} might be printing diffs
   3.150 -for a subset of the files displayed by \hgcmd{status} is that if you
   3.151 -invoke it without any arguments, \hgcmd{diff} prints diffs against the
   3.152 -first parent of the working directory.  If you have run \hgcmd{merge}
   3.153 -to merge two changesets, but you haven't yet committed the results of
   3.154 -the merge, your working directory has two parents (use \hgcmd{parents}
   3.155 -to see them).  While \hgcmd{status} prints modifications relative to
   3.156 -\emph{both} parents after an uncommitted merge, \hgcmd{diff} still
   3.157 -operates relative only to the first parent.  You can get it to print
   3.158 -diffs relative to the second parent by specifying that parent with the
   3.159 -\hgopt{diff}{-r} option.  There is no way to print diffs relative to
   3.160 -both parents.
   3.161 -
   3.162 -\subsubsection{Generating safe binary diffs}
   3.163 -
   3.164 -If you use the \hgopt{diff}{-a} option to force Mercurial to print
   3.165 -diffs of files that are either ``mostly text'' or contain lots of
   3.166 -binary data, those diffs cannot subsequently be applied by either
   3.167 -Mercurial's \hgcmd{import} command or the system's \command{patch}
   3.168 -command.  
   3.169 -
   3.170 -If you want to generate a diff of a binary file that is safe to use as
   3.171 -input for \hgcmd{import}, use the \hgcmd{diff}{--git} option when you
   3.172 -generate the patch.  The system \command{patch} command cannot handle
   3.173 -binary patches at all.
   3.174 -
   3.175 -%%% Local Variables: 
   3.176 -%%% mode: latex
   3.177 -%%% TeX-master: "00book"
   3.178 -%%% End: 

     4.1 --- a/en/appB-mq-ref.tex	Thu Mar 05 21:52:23 2009 +0200
     4.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.3 @@ -1,349 +0,0 @@
     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 --- a/en/appC-srcinstall.tex	Thu Mar 05 21:52:23 2009 +0200
     5.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.3 @@ -1,53 +0,0 @@
     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 --- a/en/appD-license.tex	Thu Mar 05 21:52:23 2009 +0200
     6.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.3 @@ -1,138 +0,0 @@
     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/ch00-preface.tex	Thu Mar 05 21:52:23 2009 +0200
     7.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.3 @@ -1,67 +0,0 @@
     7.4 -\chapter*{Preface}
     7.5 -\addcontentsline{toc}{chapter}{Preface}
     7.6 -\label{chap:preface}
     7.7 -
     7.8 -Distributed revision control is a relatively new territory, and has
     7.9 -thus far grown due to people's willingness to strike out into
    7.10 -ill-charted territory.
    7.11 -
    7.12 -I am writing a book about distributed revision control because I
    7.13 -believe that it is an important subject that deserves a field guide.
    7.14 -I chose to write about Mercurial because it is the easiest tool to
    7.15 -learn the terrain with, and yet it scales to the demands of real,
    7.16 -challenging environments where many other revision control tools fail.
    7.17 -
    7.18 -\section{This book is a work in progress}
    7.19 -
    7.20 -I am releasing this book while I am still writing it, in the hope that
    7.21 -it will prove useful to others.  I also hope that readers will
    7.22 -contribute as they see fit.
    7.23 -
    7.24 -\section{About the examples in this book}
    7.25 -
    7.26 -This book takes an unusual approach to code samples.  Every example is
    7.27 -``live''---each one is actually the result of a shell script that
    7.28 -executes the Mercurial commands you see.  Every time an image of the
    7.29 -book is built from its sources, all the example scripts are
    7.30 -automatically run, and their current results compared against their
    7.31 -expected results.
    7.32 -
    7.33 -The advantage of this approach is that the examples are always
    7.34 -accurate; they describe \emph{exactly} the behaviour of the version of
    7.35 -Mercurial that's mentioned at the front of the book.  If I update the
    7.36 -version of Mercurial that I'm documenting, and the output of some
    7.37 -command changes, the build fails.
    7.38 -
    7.39 -There is a small disadvantage to this approach, which is that the
    7.40 -dates and times you'll see in examples tend to be ``squashed''
    7.41 -together in a way that they wouldn't be if the same commands were
    7.42 -being typed by a human.  Where a human can issue no more than one
    7.43 -command every few seconds, with any resulting timestamps
    7.44 -correspondingly spread out, my automated example scripts run many
    7.45 -commands in one second.
    7.46 -
    7.47 -As an instance of this, several consecutive commits in an example can
    7.48 -show up as having occurred during the same second.  You can see this
    7.49 -occur in the \hgext{bisect} example in section~\ref{sec:undo:bisect},
    7.50 -for instance.
    7.51 -
    7.52 -So when you're reading examples, don't place too much weight on the
    7.53 -dates or times you see in the output of commands.  But \emph{do} be
    7.54 -confident that the behaviour you're seeing is consistent and
    7.55 -reproducible.
    7.56 -
    7.57 -\section{Colophon---this book is Free}
    7.58 -
    7.59 -This book is licensed under the Open Publication License, and is
    7.60 -produced entirely using Free Software tools.  It is typeset with
    7.61 -\LaTeX{}; illustrations are drawn and rendered with
    7.62 -\href{http://www.inkscape.org/}{Inkscape}.
    7.63 -
    7.64 -The complete source code for this book is published as a Mercurial
    7.65 -repository, at \url{http://hg.serpentine.com/mercurial/book}.
    7.66 -
    7.67 -%%% Local Variables: 
    7.68 -%%% mode: latex
    7.69 -%%% TeX-master: "00book"
    7.70 -%%% End: 

     8.1 --- a/en/ch01-intro.tex	Thu Mar 05 21:52:23 2009 +0200
     8.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     8.3 @@ -1,560 +0,0 @@
     8.4 -\chapter{Introduction}
     8.5 -\label{chap:intro}
     8.6 -
     8.7 -\section{About revision control}
     8.8 -
     8.9 -Revision control is the process of managing multiple versions of a
    8.10 -piece of information.  In its simplest form, this is something that
    8.11 -many people do by hand: every time you modify a file, save it under a
    8.12 -new name that contains a number, each one higher than the number of
    8.13 -the preceding version.
    8.14 -
    8.15 -Manually managing multiple versions of even a single file is an
    8.16 -error-prone task, though, so software tools to help automate this
    8.17 -process have long been available.  The earliest automated revision
    8.18 -control tools were intended to help a single user to manage revisions
    8.19 -of a single file.  Over the past few decades, the scope of revision
    8.20 -control tools has expanded greatly; they now manage multiple files,
    8.21 -and help multiple people to work together.  The best modern revision
    8.22 -control tools have no problem coping with thousands of people working
    8.23 -together on projects that consist of hundreds of thousands of files.
    8.24 -
    8.25 -\subsection{Why use revision control?}
    8.26 -
    8.27 -There are a number of reasons why you or your team might want to use
    8.28 -an automated revision control tool for a project.
    8.29 -\begin{itemize}
    8.30 -\item It will track the history and evolution of your project, so you
    8.31 -  don't have to.  For every change, you'll have a log of \emph{who}
    8.32 -  made it; \emph{why} they made it; \emph{when} they made it; and
    8.33 -  \emph{what} the change was.
    8.34 -\item When you're working with other people, revision control software
    8.35 -  makes it easier for you to collaborate.  For example, when people
    8.36 -  more or less simultaneously make potentially incompatible changes,
    8.37 -  the software will help you to identify and resolve those conflicts.
    8.38 -\item It can help you to recover from mistakes.  If you make a change
    8.39 -  that later turns out to be in error, you can revert to an earlier
    8.40 -  version of one or more files.  In fact, a \emph{really} good
    8.41 -  revision control tool will even help you to efficiently figure out
    8.42 -  exactly when a problem was introduced (see
    8.43 -  section~\ref{sec:undo:bisect} for details).
    8.44 -\item It will help you to work simultaneously on, and manage the drift
    8.45 -  between, multiple versions of your project.
    8.46 -\end{itemize}
    8.47 -Most of these reasons are equally valid---at least in theory---whether
    8.48 -you're working on a project by yourself, or with a hundred other
    8.49 -people.
    8.50 -
    8.51 -A key question about the practicality of revision control at these two
    8.52 -different scales (``lone hacker'' and ``huge team'') is how its
    8.53 -\emph{benefits} compare to its \emph{costs}.  A revision control tool
    8.54 -that's difficult to understand or use is going to impose a high cost.
    8.55 -
    8.56 -A five-hundred-person project is likely to collapse under its own
    8.57 -weight almost immediately without a revision control tool and process.
    8.58 -In this case, the cost of using revision control might hardly seem
    8.59 -worth considering, since \emph{without} it, failure is almost
    8.60 -guaranteed.
    8.61 -
    8.62 -On the other hand, a one-person ``quick hack'' might seem like a poor
    8.63 -place to use a revision control tool, because surely the cost of using
    8.64 -one must be close to the overall cost of the project.  Right?
    8.65 -
    8.66 -Mercurial uniquely supports \emph{both} of these scales of
    8.67 -development.  You can learn the basics in just a few minutes, and due
    8.68 -to its low overhead, you can apply revision control to the smallest of
    8.69 -projects with ease.  Its simplicity means you won't have a lot of
    8.70 -abstruse concepts or command sequences competing for mental space with
    8.71 -whatever you're \emph{really} trying to do.  At the same time,
    8.72 -Mercurial's high performance and peer-to-peer nature let you scale
    8.73 -painlessly to handle large projects.
    8.74 -
    8.75 -No revision control tool can rescue a poorly run project, but a good
    8.76 -choice of tools can make a huge difference to the fluidity with which
    8.77 -you can work on a project.
    8.78 -
    8.79 -\subsection{The many names of revision control}
    8.80 -
    8.81 -Revision control is a diverse field, so much so that it doesn't
    8.82 -actually have a single name or acronym.  Here are a few of the more
    8.83 -common names and acronyms you'll encounter:
    8.84 -\begin{itemize}
    8.85 -\item Revision control (RCS)
    8.86 -\item Software configuration management (SCM), or configuration management
    8.87 -\item Source code management
    8.88 -\item Source code control, or source control
    8.89 -\item Version control (VCS)
    8.90 -\end{itemize}
    8.91 -Some people claim that these terms actually have different meanings,
    8.92 -but in practice they overlap so much that there's no agreed or even
    8.93 -useful way to tease them apart.
    8.94 -
    8.95 -\section{A short history of revision control}
    8.96 -
    8.97 -The best known of the old-time revision control tools is SCCS (Source
    8.98 -Code Control System), which Marc Rochkind wrote at Bell Labs, in the
    8.99 -early 1970s.  SCCS operated on individual files, and required every
   8.100 -person working on a project to have access to a shared workspace on a
   8.101 -single system.  Only one person could modify a file at any time;
   8.102 -arbitration for access to files was via locks.  It was common for
   8.103 -people to lock files, and later forget to unlock them, preventing
   8.104 -anyone else from modifying those files without the help of an
   8.105 -administrator.  
   8.106 -
   8.107 -Walter Tichy developed a free alternative to SCCS in the early 1980s;
   8.108 -he called his program RCS (Revison Control System).  Like SCCS, RCS
   8.109 -required developers to work in a single shared workspace, and to lock
   8.110 -files to prevent multiple people from modifying them simultaneously.
   8.111 -
   8.112 -Later in the 1980s, Dick Grune used RCS as a building block for a set
   8.113 -of shell scripts he initially called cmt, but then renamed to CVS
   8.114 -(Concurrent Versions System).  The big innovation of CVS was that it
   8.115 -let developers work simultaneously and somewhat independently in their
   8.116 -own personal workspaces.  The personal workspaces prevented developers
   8.117 -from stepping on each other's toes all the time, as was common with
   8.118 -SCCS and RCS.  Each developer had a copy of every project file, and
   8.119 -could modify their copies independently.  They had to merge their
   8.120 -edits prior to committing changes to the central repository.
   8.121 -
   8.122 -Brian Berliner took Grune's original scripts and rewrote them in~C,
   8.123 -releasing in 1989 the code that has since developed into the modern
   8.124 -version of CVS.  CVS subsequently acquired the ability to operate over
   8.125 -a network connection, giving it a client/server architecture.  CVS's
   8.126 -architecture is centralised; only the server has a copy of the history
   8.127 -of the project.  Client workspaces just contain copies of recent
   8.128 -versions of the project's files, and a little metadata to tell them
   8.129 -where the server is.  CVS has been enormously successful; it is
   8.130 -probably the world's most widely used revision control system.
   8.131 -
   8.132 -In the early 1990s, Sun Microsystems developed an early distributed
   8.133 -revision control system, called TeamWare.  A TeamWare workspace
   8.134 -contains a complete copy of the project's history.  TeamWare has no
   8.135 -notion of a central repository.  (CVS relied upon RCS for its history
   8.136 -storage; TeamWare used SCCS.)
   8.137 -
   8.138 -As the 1990s progressed, awareness grew of a number of problems with
   8.139 -CVS.  It records simultaneous changes to multiple files individually,
   8.140 -instead of grouping them together as a single logically atomic
   8.141 -operation.  It does not manage its file hierarchy well; it is easy to
   8.142 -make a mess of a repository by renaming files and directories.  Worse,
   8.143 -its source code is difficult to read and maintain, which made the
   8.144 -``pain level'' of fixing these architectural problems prohibitive.
   8.145 -
   8.146 -In 2001, Jim Blandy and Karl Fogel, two developers who had worked on
   8.147 -CVS, started a project to replace it with a tool that would have a
   8.148 -better architecture and cleaner code.  The result, Subversion, does
   8.149 -not stray from CVS's centralised client/server model, but it adds
   8.150 -multi-file atomic commits, better namespace management, and a number
   8.151 -of other features that make it a generally better tool than CVS.
   8.152 -Since its initial release, it has rapidly grown in popularity.
   8.153 -
   8.154 -More or less simultaneously, Graydon Hoare began working on an
   8.155 -ambitious distributed revision control system that he named Monotone.
   8.156 -While Monotone addresses many of CVS's design flaws and has a
   8.157 -peer-to-peer architecture, it goes beyond earlier (and subsequent)
   8.158 -revision control tools in a number of innovative ways.  It uses
   8.159 -cryptographic hashes as identifiers, and has an integral notion of
   8.160 -``trust'' for code from different sources.
   8.161 -
   8.162 -Mercurial began life in 2005.  While a few aspects of its design are
   8.163 -influenced by Monotone, Mercurial focuses on ease of use, high
   8.164 -performance, and scalability to very large projects.
   8.165 -
   8.166 -\section{Trends in revision control}
   8.167 -
   8.168 -There has been an unmistakable trend in the development and use of
   8.169 -revision control tools over the past four decades, as people have
   8.170 -become familiar with the capabilities of their tools and constrained
   8.171 -by their limitations.
   8.172 -
   8.173 -The first generation began by managing single files on individual
   8.174 -computers.  Although these tools represented a huge advance over
   8.175 -ad-hoc manual revision control, their locking model and reliance on a
   8.176 -single computer limited them to small, tightly-knit teams.
   8.177 -
   8.178 -The second generation loosened these constraints by moving to
   8.179 -network-centered architectures, and managing entire projects at a
   8.180 -time.  As projects grew larger, they ran into new problems.  With
   8.181 -clients needing to talk to servers very frequently, server scaling
   8.182 -became an issue for large projects.  An unreliable network connection
   8.183 -could prevent remote users from being able to talk to the server at
   8.184 -all.  As open source projects started making read-only access
   8.185 -available anonymously to anyone, people without commit privileges
   8.186 -found that they could not use the tools to interact with a project in
   8.187 -a natural way, as they could not record their changes.
   8.188 -
   8.189 -The current generation of revision control tools is peer-to-peer in
   8.190 -nature.  All of these systems have dropped the dependency on a single
   8.191 -central server, and allow people to distribute their revision control
   8.192 -data to where it's actually needed.  Collaboration over the Internet
   8.193 -has moved from constrained by technology to a matter of choice and
   8.194 -consensus.  Modern tools can operate offline indefinitely and
   8.195 -autonomously, with a network connection only needed when syncing
   8.196 -changes with another repository.
   8.197 -
   8.198 -\section{A few of the advantages of distributed revision control}
   8.199 -
   8.200 -Even though distributed revision control tools have for several years
   8.201 -been as robust and usable as their previous-generation counterparts,
   8.202 -people using older tools have not yet necessarily woken up to their
   8.203 -advantages.  There are a number of ways in which distributed tools
   8.204 -shine relative to centralised ones.
   8.205 -
   8.206 -For an individual developer, distributed tools are almost always much
   8.207 -faster than centralised tools.  This is for a simple reason: a
   8.208 -centralised tool needs to talk over the network for many common
   8.209 -operations, because most metadata is stored in a single copy on the
   8.210 -central server.  A distributed tool stores all of its metadata
   8.211 -locally.  All else being equal, talking over the network adds overhead
   8.212 -to a centralised tool.  Don't underestimate the value of a snappy,
   8.213 -responsive tool: you're going to spend a lot of time interacting with
   8.214 -your revision control software.
   8.215 -
   8.216 -Distributed tools are indifferent to the vagaries of your server
   8.217 -infrastructure, again because they replicate metadata to so many
   8.218 -locations.  If you use a centralised system and your server catches
   8.219 -fire, you'd better hope that your backup media are reliable, and that
   8.220 -your last backup was recent and actually worked.  With a distributed
   8.221 -tool, you have many backups available on every contributor's computer.
   8.222 -
   8.223 -The reliability of your network will affect distributed tools far less
   8.224 -than it will centralised tools.  You can't even use a centralised tool
   8.225 -without a network connection, except for a few highly constrained
   8.226 -commands.  With a distributed tool, if your network connection goes
   8.227 -down while you're working, you may not even notice.  The only thing
   8.228 -you won't be able to do is talk to repositories on other computers,
   8.229 -something that is relatively rare compared with local operations.  If
   8.230 -you have a far-flung team of collaborators, this may be significant.
   8.231 -
   8.232 -\subsection{Advantages for open source projects}
   8.233 -
   8.234 -If you take a shine to an open source project and decide that you
   8.235 -would like to start hacking on it, and that project uses a distributed
   8.236 -revision control tool, you are at once a peer with the people who
   8.237 -consider themselves the ``core'' of that project.  If they publish
   8.238 -their repositories, you can immediately copy their project history,
   8.239 -start making changes, and record your work, using the same tools in
   8.240 -the same ways as insiders.  By contrast, with a centralised tool, you
   8.241 -must use the software in a ``read only'' mode unless someone grants
   8.242 -you permission to commit changes to their central server.  Until then,
   8.243 -you won't be able to record changes, and your local modifications will
   8.244 -be at risk of corruption any time you try to update your client's view
   8.245 -of the repository.
   8.246 -
   8.247 -\subsubsection{The forking non-problem}
   8.248 -
   8.249 -It has been suggested that distributed revision control tools pose
   8.250 -some sort of risk to open source projects because they make it easy to
   8.251 -``fork'' the development of a project.  A fork happens when there are
   8.252 -differences in opinion or attitude between groups of developers that
   8.253 -cause them to decide that they can't work together any longer.  Each
   8.254 -side takes a more or less complete copy of the project's source code,
   8.255 -and goes off in its own direction.
   8.256 -
   8.257 -Sometimes the camps in a fork decide to reconcile their differences.
   8.258 -With a centralised revision control system, the \emph{technical}
   8.259 -process of reconciliation is painful, and has to be performed largely
   8.260 -by hand.  You have to decide whose revision history is going to
   8.261 -``win'', and graft the other team's changes into the tree somehow.
   8.262 -This usually loses some or all of one side's revision history.
   8.263 -
   8.264 -What distributed tools do with respect to forking is they make forking
   8.265 -the \emph{only} way to develop a project.  Every single change that
   8.266 -you make is potentially a fork point.  The great strength of this
   8.267 -approach is that a distributed revision control tool has to be really
   8.268 -good at \emph{merging} forks, because forks are absolutely
   8.269 -fundamental: they happen all the time.  
   8.270 -
   8.271 -If every piece of work that everybody does, all the time, is framed in
   8.272 -terms of forking and merging, then what the open source world refers
   8.273 -to as a ``fork'' becomes \emph{purely} a social issue.  If anything,
   8.274 -distributed tools \emph{lower} the likelihood of a fork:
   8.275 -\begin{itemize}
   8.276 -\item They eliminate the social distinction that centralised tools
   8.277 -  impose: that between insiders (people with commit access) and
   8.278 -  outsiders (people without).
   8.279 -\item They make it easier to reconcile after a social fork, because
   8.280 -  all that's involved from the perspective of the revision control
   8.281 -  software is just another merge.
   8.282 -\end{itemize}
   8.283 -
   8.284 -Some people resist distributed tools because they want to retain tight
   8.285 -control over their projects, and they believe that centralised tools
   8.286 -give them this control.  However, if you're of this belief, and you
   8.287 -publish your CVS or Subversion repositories publically, there are
   8.288 -plenty of tools available that can pull out your entire project's
   8.289 -history (albeit slowly) and recreate it somewhere that you don't
   8.290 -control.  So while your control in this case is illusory, you are
   8.291 -forgoing the ability to fluidly collaborate with whatever people feel
   8.292 -compelled to mirror and fork your history.
   8.293 -
   8.294 -\subsection{Advantages for commercial projects}
   8.295 -
   8.296 -Many commercial projects are undertaken by teams that are scattered
   8.297 -across the globe.  Contributors who are far from a central server will
   8.298 -see slower command execution and perhaps less reliability.  Commercial
   8.299 -revision control systems attempt to ameliorate these problems with
   8.300 -remote-site replication add-ons that are typically expensive to buy
   8.301 -and cantankerous to administer.  A distributed system doesn't suffer
   8.302 -from these problems in the first place.  Better yet, you can easily
   8.303 -set up multiple authoritative servers, say one per site, so that
   8.304 -there's no redundant communication between repositories over expensive
   8.305 -long-haul network links.
   8.306 -
   8.307 -Centralised revision control systems tend to have relatively low
   8.308 -scalability.  It's not unusual for an expensive centralised system to
   8.309 -fall over under the combined load of just a few dozen concurrent
   8.310 -users.  Once again, the typical response tends to be an expensive and
   8.311 -clunky replication facility.  Since the load on a central server---if
   8.312 -you have one at all---is many times lower with a distributed
   8.313 -tool (because all of the data is replicated everywhere), a single
   8.314 -cheap server can handle the needs of a much larger team, and
   8.315 -replication to balance load becomes a simple matter of scripting.
   8.316 -
   8.317 -If you have an employee in the field, troubleshooting a problem at a
   8.318 -customer's site, they'll benefit from distributed revision control.
   8.319 -The tool will let them generate custom builds, try different fixes in
   8.320 -isolation from each other, and search efficiently through history for
   8.321 -the sources of bugs and regressions in the customer's environment, all
   8.322 -without needing to connect to your company's network.
   8.323 -
   8.324 -\section{Why choose Mercurial?}
   8.325 -
   8.326 -Mercurial has a unique set of properties that make it a particularly
   8.327 -good choice as a revision control system.
   8.328 -\begin{itemize}
   8.329 -\item It is easy to learn and use.
   8.330 -\item It is lightweight.
   8.331 -\item It scales excellently.
   8.332 -\item It is easy to customise.
   8.333 -\end{itemize}
   8.334 -
   8.335 -If you are at all familiar with revision control systems, you should
   8.336 -be able to get up and running with Mercurial in less than five
   8.337 -minutes.  Even if not, it will take no more than a few minutes
   8.338 -longer.  Mercurial's command and feature sets are generally uniform
   8.339 -and consistent, so you can keep track of a few general rules instead
   8.340 -of a host of exceptions.
   8.341 -
   8.342 -On a small project, you can start working with Mercurial in moments.
   8.343 -Creating new changes and branches; transferring changes around
   8.344 -(whether locally or over a network); and history and status operations
   8.345 -are all fast.  Mercurial attempts to stay nimble and largely out of
   8.346 -your way by combining low cognitive overhead with blazingly fast
   8.347 -operations.
   8.348 -
   8.349 -The usefulness of Mercurial is not limited to small projects: it is
   8.350 -used by projects with hundreds to thousands of contributors, each
   8.351 -containing tens of thousands of files and hundreds of megabytes of
   8.352 -source code.
   8.353 -
   8.354 -If the core functionality of Mercurial is not enough for you, it's
   8.355 -easy to build on.  Mercurial is well suited to scripting tasks, and
   8.356 -its clean internals and implementation in Python make it easy to add
   8.357 -features in the form of extensions.  There are a number of popular and
   8.358 -useful extensions already available, ranging from helping to identify
   8.359 -bugs to improving performance.
   8.360 -
   8.361 -\section{Mercurial compared with other tools}
   8.362 -
   8.363 -Before you read on, please understand that this section necessarily
   8.364 -reflects my own experiences, interests, and (dare I say it) biases.  I
   8.365 -have used every one of the revision control tools listed below, in
   8.366 -most cases for several years at a time.
   8.367 -
   8.368 -
   8.369 -\subsection{Subversion}
   8.370 -
   8.371 -Subversion is a popular revision control tool, developed to replace
   8.372 -CVS.  It has a centralised client/server architecture.
   8.373 -
   8.374 -Subversion and Mercurial have similarly named commands for performing
   8.375 -the same operations, so if you're familiar with one, it is easy to
   8.376 -learn to use the other.  Both tools are portable to all popular
   8.377 -operating systems.
   8.378 -
   8.379 -Prior to version 1.5, Subversion had no useful support for merges.
   8.380 -At the time of writing, its merge tracking capability is new, and known to be
   8.381 -\href{http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword}{complicated and buggy}.
   8.382 -
   8.383 -Mercurial has a substantial performance advantage over Subversion on
   8.384 -every revision control operation I have benchmarked.  I have measured
   8.385 -its advantage as ranging from a factor of two to a factor of six when
   8.386 -compared with Subversion~1.4.3's \emph{ra\_local} file store, which is
   8.387 -the fastest access method available.  In more realistic deployments
   8.388 -involving a network-based store, Subversion will be at a substantially
   8.389 -larger disadvantage.  Because many Subversion commands must talk to
   8.390 -the server and Subversion does not have useful replication facilities,
   8.391 -server capacity and network bandwidth become bottlenecks for modestly
   8.392 -large projects.
   8.393 -
   8.394 -Additionally, Subversion incurs substantial storage overhead to avoid
   8.395 -network transactions for a few common operations, such as finding
   8.396 -modified files (\texttt{status}) and displaying modifications against
   8.397 -the current revision (\texttt{diff}).  As a result, a Subversion
   8.398 -working copy is often the same size as, or larger than, a Mercurial
   8.399 -repository and working directory, even though the Mercurial repository
   8.400 -contains a complete history of the project.
   8.401 -
   8.402 -Subversion is widely supported by third party tools.  Mercurial
   8.403 -currently lags considerably in this area.  This gap is closing,
   8.404 -however, and indeed some of Mercurial's GUI tools now outshine their
   8.405 -Subversion equivalents.  Like Mercurial, Subversion has an excellent
   8.406 -user manual.
   8.407 -
   8.408 -Because Subversion doesn't store revision history on the client, it is
   8.409 -well suited to managing projects that deal with lots of large, opaque
   8.410 -binary files.  If you check in fifty revisions to an incompressible
   8.411 -10MB file, Subversion's client-side space usage stays constant The
   8.412 -space used by any distributed SCM will grow rapidly in proportion to
   8.413 -the number of revisions, because the differences between each revision
   8.414 -are large.
   8.415 -
   8.416 -In addition, it's often difficult or, more usually, impossible to
   8.417 -merge different versions of a binary file.  Subversion's ability to
   8.418 -let a user lock a file, so that they temporarily have the exclusive
   8.419 -right to commit changes to it, can be a significant advantage to a
   8.420 -project where binary files are widely used.
   8.421 -
   8.422 -Mercurial can import revision history from a Subversion repository.
   8.423 -It can also export revision history to a Subversion repository.  This
   8.424 -makes it easy to ``test the waters'' and use Mercurial and Subversion
   8.425 -in parallel before deciding to switch.  History conversion is
   8.426 -incremental, so you can perform an initial conversion, then small
   8.427 -additional conversions afterwards to bring in new changes.
   8.428 -
   8.429 -
   8.430 -\subsection{Git}
   8.431 -
   8.432 -Git is a distributed revision control tool that was developed for
   8.433 -managing the Linux kernel source tree.  Like Mercurial, its early
   8.434 -design was somewhat influenced by Monotone.
   8.435 -
   8.436 -Git has a very large command set, with version~1.5.0 providing~139
   8.437 -individual commands.  It has something of a reputation for being
   8.438 -difficult to learn.  Compared to Git, Mercurial has a strong focus on
   8.439 -simplicity.
   8.440 -
   8.441 -In terms of performance, Git is extremely fast.  In several cases, it
   8.442 -is faster than Mercurial, at least on Linux, while Mercurial performs
   8.443 -better on other operations.  However, on Windows, the performance and
   8.444 -general level of support that Git provides is, at the time of writing,
   8.445 -far behind that of Mercurial.
   8.446 -
   8.447 -While a Mercurial repository needs no maintenance, a Git repository
   8.448 -requires frequent manual ``repacks'' of its metadata.  Without these,
   8.449 -performance degrades, while space usage grows rapidly.  A server that
   8.450 -contains many Git repositories that are not rigorously and frequently
   8.451 -repacked will become heavily disk-bound during backups, and there have
   8.452 -been instances of daily backups taking far longer than~24 hours as a
   8.453 -result.  A freshly packed Git repository is slightly smaller than a
   8.454 -Mercurial repository, but an unpacked repository is several orders of
   8.455 -magnitude larger.
   8.456 -
   8.457 -The core of Git is written in C.  Many Git commands are implemented as
   8.458 -shell or Perl scripts, and the quality of these scripts varies widely.
   8.459 -I have encountered several instances where scripts charged along
   8.460 -blindly in the presence of errors that should have been fatal.
   8.461 -
   8.462 -Mercurial can import revision history from a Git repository.
   8.463 -
   8.464 -
   8.465 -\subsection{CVS}
   8.466 -
   8.467 -CVS is probably the most widely used revision control tool in the
   8.468 -world.  Due to its age and internal untidiness, it has been only
   8.469 -lightly maintained for many years.
   8.470 -
   8.471 -It has a centralised client/server architecture.  It does not group
   8.472 -related file changes into atomic commits, making it easy for people to
   8.473 -``break the build'': one person can successfully commit part of a
   8.474 -change and then be blocked by the need for a merge, causing other
   8.475 -people to see only a portion of the work they intended to do.  This
   8.476 -also affects how you work with project history.  If you want to see
   8.477 -all of the modifications someone made as part of a task, you will need
   8.478 -to manually inspect the descriptions and timestamps of the changes
   8.479 -made to each file involved (if you even know what those files were).
   8.480 -
   8.481 -CVS has a muddled notion of tags and branches that I will not attempt
   8.482 -to even describe.  It does not support renaming of files or
   8.483 -directories well, making it easy to corrupt a repository.  It has
   8.484 -almost no internal consistency checking capabilities, so it is usually
   8.485 -not even possible to tell whether or how a repository is corrupt.  I
   8.486 -would not recommend CVS for any project, existing or new.
   8.487 -
   8.488 -Mercurial can import CVS revision history.  However, there are a few
   8.489 -caveats that apply; these are true of every other revision control
   8.490 -tool's CVS importer, too.  Due to CVS's lack of atomic changes and
   8.491 -unversioned filesystem hierarchy, it is not possible to reconstruct
   8.492 -CVS history completely accurately; some guesswork is involved, and
   8.493 -renames will usually not show up.  Because a lot of advanced CVS
   8.494 -administration has to be done by hand and is hence error-prone, it's
   8.495 -common for CVS importers to run into multiple problems with corrupted
   8.496 -repositories (completely bogus revision timestamps and files that have
   8.497 -remained locked for over a decade are just two of the less interesting
   8.498 -problems I can recall from personal experience).
   8.499 -
   8.500 -Mercurial can import revision history from a CVS repository.
   8.501 -
   8.502 -
   8.503 -\subsection{Commercial tools}
   8.504 -
   8.505 -Perforce has a centralised client/server architecture, with no
   8.506 -client-side caching of any data.  Unlike modern revision control
   8.507 -tools, Perforce requires that a user run a command to inform the
   8.508 -server about every file they intend to edit.
   8.509 -
   8.510 -The performance of Perforce is quite good for small teams, but it
   8.511 -falls off rapidly as the number of users grows beyond a few dozen.
   8.512 -Modestly large Perforce installations require the deployment of
   8.513 -proxies to cope with the load their users generate.
   8.514 -
   8.515 -
   8.516 -\subsection{Choosing a revision control tool}
   8.517 -
   8.518 -With the exception of CVS, all of the tools listed above have unique
   8.519 -strengths that suit them to particular styles of work.  There is no
   8.520 -single revision control tool that is best in all situations.
   8.521 -
   8.522 -As an example, Subversion is a good choice for working with frequently
   8.523 -edited binary files, due to its centralised nature and support for
   8.524 -file locking.
   8.525 -
   8.526 -I personally find Mercurial's properties of simplicity, performance,
   8.527 -and good merge support to be a compelling combination that has served
   8.528 -me well for several years.
   8.529 -
   8.530 -
   8.531 -\section{Switching from another tool to Mercurial}
   8.532 -
   8.533 -Mercurial is bundled with an extension named \hgext{convert}, which
   8.534 -can incrementally import revision history from several other revision
   8.535 -control tools.  By ``incremental'', I mean that you can convert all of
   8.536 -a project's history to date in one go, then rerun the conversion later
   8.537 -to obtain new changes that happened after the initial conversion.
   8.538 -
   8.539 -The revision control tools supported by \hgext{convert} are as
   8.540 -follows:
   8.541 -\begin{itemize}
   8.542 -\item Subversion
   8.543 -\item CVS
   8.544 -\item Git
   8.545 -\item Darcs
   8.546 -\end{itemize}
   8.547 -
   8.548 -In addition, \hgext{convert} can export changes from Mercurial to
   8.549 -Subversion.  This makes it possible to try Subversion and Mercurial in
   8.550 -parallel before committing to a switchover, without risking the loss
   8.551 -of any work.
   8.552 -
   8.553 -The \hgxcmd{conver}{convert} command is easy to use.  Simply point it
   8.554 -at the path or URL of the source repository, optionally give it the
   8.555 -name of the destination repository, and it will start working.  After
   8.556 -the initial conversion, just run the same command again to import new
   8.557 -changes.
   8.558 -
   8.559 -
   8.560 -%%% Local Variables: 
   8.561 -%%% mode: latex
   8.562 -%%% TeX-master: "00book"
   8.563 -%%% End: 

     9.1 --- a/en/ch02-tour-basic.tex	Thu Mar 05 21:52:23 2009 +0200
     9.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     9.3 @@ -1,622 +0,0 @@
     9.4 -\chapter{A tour of Mercurial: the basics}
     9.5 -\label{chap:tour-basic}
     9.6 -
     9.7 -\section{Installing Mercurial on your system}
     9.8 -\label{sec:tour:install}
     9.9 -
    9.10 -Prebuilt binary packages of Mercurial are available for every popular
    9.11 -operating system.  These make it easy to start using Mercurial on your
    9.12 -computer immediately.
    9.13 -
    9.14 -\subsection{Linux}
    9.15 -
    9.16 -Because each Linux distribution has its own packaging tools, policies,
    9.17 -and rate of development, it's difficult to give a comprehensive set of
    9.18 -instructions on how to install Mercurial binaries.  The version of
    9.19 -Mercurial that you will end up with can vary depending on how active
    9.20 -the person is who maintains the package for your distribution.
    9.21 -
    9.22 -To keep things simple, I will focus on installing Mercurial from the
    9.23 -command line under the most popular Linux distributions.  Most of
    9.24 -these distributions provide graphical package managers that will let
    9.25 -you install Mercurial with a single click; the package name to look
    9.26 -for is \texttt{mercurial}.
    9.27 -
    9.28 -\begin{itemize}
    9.29 -\item[Debian]
    9.30 -  \begin{codesample4}
    9.31 -    apt-get install mercurial
    9.32 -  \end{codesample4}
    9.33 -
    9.34 -\item[Fedora Core]
    9.35 -  \begin{codesample4}
    9.36 -    yum install mercurial
    9.37 -  \end{codesample4}
    9.38 -
    9.39 -\item[Gentoo]
    9.40 -  \begin{codesample4}
    9.41 -    emerge mercurial
    9.42 -  \end{codesample4}
    9.43 -
    9.44 -\item[OpenSUSE]
    9.45 -  \begin{codesample4}
    9.46 -    yum install mercurial
    9.47 -  \end{codesample4}
    9.48 -
    9.49 -\item[Ubuntu] Ubuntu's Mercurial package is based on Debian's.  To
    9.50 -  install it, run the following command.
    9.51 -  \begin{codesample4}
    9.52 -    apt-get install mercurial
    9.53 -  \end{codesample4}
    9.54 -  The Ubuntu package for Mercurial tends to lag behind the Debian
    9.55 -  version by a considerable time margin (at the time of writing, seven
    9.56 -  months), which in some cases will mean that on Ubuntu, you may run
    9.57 -  into problems that have since been fixed in the Debian package.
    9.58 -\end{itemize}
    9.59 -
    9.60 -\subsection{Solaris}
    9.61 -
    9.62 -SunFreeWare, at \url{http://www.sunfreeware.com}, is a good source for a
    9.63 -large number of pre-built Solaris packages for 32 and 64 bit Intel and
    9.64 -Sparc architectures, including current versions of Mercurial.
    9.65 -
    9.66 -\subsection{Mac OS X}
    9.67 -
    9.68 -Lee Cantey publishes an installer of Mercurial for Mac OS~X at
    9.69 -\url{http://mercurial.berkwood.com}.  This package works on both
    9.70 -Intel-~and Power-based Macs.  Before you can use it, you must install
    9.71 -a compatible version of Universal MacPython~\cite{web:macpython}.  This
    9.72 -is easy to do; simply follow the instructions on Lee's site.
    9.73 -
    9.74 -It's also possible to install Mercurial using Fink or MacPorts,
    9.75 -two popular free package managers for Mac OS X.  If you have Fink,
    9.76 -use \command{sudo apt-get install mercurial-py25}.  If MacPorts,
    9.77 -\command{sudo port install mercurial}.
    9.78 -
    9.79 -\subsection{Windows}
    9.80 -
    9.81 -Lee Cantey publishes an installer of Mercurial for Windows at
    9.82 -\url{http://mercurial.berkwood.com}.  This package has no external
    9.83 -dependencies; it ``just works''.
    9.84 -
    9.85 -\begin{note}
    9.86 -  The Windows version of Mercurial does not automatically convert line
    9.87 -  endings between Windows and Unix styles.  If you want to share work
    9.88 -  with Unix users, you must do a little additional configuration
    9.89 -  work. XXX Flesh this out.
    9.90 -\end{note}
    9.91 -
    9.92 -\section{Getting started}
    9.93 -
    9.94 -To begin, we'll use the \hgcmd{version} command to find out whether
    9.95 -Mercurial is actually installed properly.  The actual version
    9.96 -information that it prints isn't so important; it's whether it prints
    9.97 -anything at all that we care about.
    9.98 -\interaction{tour.version}
    9.99 -
   9.100 -\subsection{Built-in help}
   9.101 -
   9.102 -Mercurial provides a built-in help system.  This is invaluable for those
   9.103 -times when you find yourself stuck trying to remember how to run a
   9.104 -command.  If you are completely stuck, simply run \hgcmd{help}; it
   9.105 -will print a brief list of commands, along with a description of what
   9.106 -each does.  If you ask for help on a specific command (as below), it
   9.107 -prints more detailed information.
   9.108 -\interaction{tour.help}
   9.109 -For a more impressive level of detail (which you won't usually need)
   9.110 -run \hgcmdargs{help}{\hggopt{-v}}.  The \hggopt{-v} option is short
   9.111 -for \hggopt{--verbose}, and tells Mercurial to print more information
   9.112 -than it usually would.
   9.113 -
   9.114 -\section{Working with a repository}
   9.115 -
   9.116 -In Mercurial, everything happens inside a \emph{repository}.  The
   9.117 -repository for a project contains all of the files that ``belong to''
   9.118 -that project, along with a historical record of the project's files.
   9.119 -
   9.120 -There's nothing particularly magical about a repository; it is simply
   9.121 -a directory tree in your filesystem that Mercurial treats as special.
   9.122 -You can rename or delete a repository any time you like, using either the
   9.123 -command line or your file browser.
   9.124 -
   9.125 -\subsection{Making a local copy of a repository}
   9.126 -
   9.127 -\emph{Copying} a repository is just a little bit special.  While you
   9.128 -could use a normal file copying command to make a copy of a
   9.129 -repository, it's best to use a built-in command that Mercurial
   9.130 -provides.  This command is called \hgcmd{clone}, because it creates an
   9.131 -identical copy of an existing repository.
   9.132 -\interaction{tour.clone}
   9.133 -If our clone succeeded, we should now have a local directory called
   9.134 -\dirname{hello}.  This directory will contain some files.
   9.135 -\interaction{tour.ls}
   9.136 -These files have the same contents and history in our repository as
   9.137 -they do in the repository we cloned.
   9.138 -
   9.139 -Every Mercurial repository is complete, self-contained, and
   9.140 -independent.  It contains its own private copy of a project's files
   9.141 -and history.  A cloned repository remembers the location of the
   9.142 -repository it was cloned from, but it does not communicate with that
   9.143 -repository, or any other, unless you tell it to.
   9.144 -
   9.145 -What this means for now is that we're free to experiment with our
   9.146 -repository, safe in the knowledge that it's a private ``sandbox'' that
   9.147 -won't affect anyone else.
   9.148 -
   9.149 -\subsection{What's in a repository?}
   9.150 -
   9.151 -When we take a more detailed look inside a repository, we can see that
   9.152 -it contains a directory named \dirname{.hg}.  This is where Mercurial
   9.153 -keeps all of its metadata for the repository.
   9.154 -\interaction{tour.ls-a}
   9.155 -
   9.156 -The contents of the \dirname{.hg} directory and its subdirectories are
   9.157 -private to Mercurial.  Every other file and directory in the
   9.158 -repository is yours to do with as you please.
   9.159 -
   9.160 -To introduce a little terminology, the \dirname{.hg} directory is the
   9.161 -``real'' repository, and all of the files and directories that coexist
   9.162 -with it are said to live in the \emph{working directory}.  An easy way
   9.163 -to remember the distinction is that the \emph{repository} contains the
   9.164 -\emph{history} of your project, while the \emph{working directory}
   9.165 -contains a \emph{snapshot} of your project at a particular point in
   9.166 -history.
   9.167 -
   9.168 -\section{A tour through history}
   9.169 -
   9.170 -One of the first things we might want to do with a new, unfamiliar
   9.171 -repository is understand its history.  The \hgcmd{log} command gives
   9.172 -us a view of history.
   9.173 -\interaction{tour.log}
   9.174 -By default, this command prints a brief paragraph of output for each
   9.175 -change to the project that was recorded.  In Mercurial terminology, we
   9.176 -call each of these recorded events a \emph{changeset}, because it can
   9.177 -contain a record of changes to several files.
   9.178 -
   9.179 -The fields in a record of output from \hgcmd{log} are as follows.
   9.180 -\begin{itemize}
   9.181 -\item[\texttt{changeset}] This field has the format of a number,
   9.182 -  followed by a colon, followed by a hexadecimal string.  These are
   9.183 -  \emph{identifiers} for the changeset.  There are two identifiers
   9.184 -  because the number is shorter and easier to type than the hex
   9.185 -  string.
   9.186 -\item[\texttt{user}] The identity of the person who created the
   9.187 -  changeset.  This is a free-form field, but it most often contains a
   9.188 -  person's name and email address.
   9.189 -\item[\texttt{date}] The date and time on which the changeset was
   9.190 -  created, and the timezone in which it was created.  (The date and
   9.191 -  time are local to that timezone; they display what time and date it
   9.192 -  was for the person who created the changeset.)
   9.193 -\item[\texttt{summary}] The first line of the text message that the
   9.194 -  creator of the changeset entered to describe the changeset.
   9.195 -\end{itemize}
   9.196 -The default output printed by \hgcmd{log} is purely a summary; it is
   9.197 -missing a lot of detail.
   9.198 -
   9.199 -Figure~\ref{fig:tour-basic:history} provides a graphical representation of
   9.200 -the history of the \dirname{hello} repository, to make it a little
   9.201 -easier to see which direction history is ``flowing'' in.  We'll be
   9.202 -returning to this figure several times in this chapter and the chapter
   9.203 -that follows.
   9.204 -
   9.205 -\begin{figure}[ht]
   9.206 -  \centering
   9.207 -  \grafix{tour-history}
   9.208 -  \caption{Graphical history of the \dirname{hello} repository}
   9.209 -  \label{fig:tour-basic:history}
   9.210 -\end{figure}
   9.211 -
   9.212 -\subsection{Changesets, revisions, and talking to other people}
   9.213 -
   9.214 -As English is a notoriously sloppy language, and computer science has
   9.215 -a hallowed history of terminological confusion (why use one term when
   9.216 -four will do?), revision control has a variety of words and phrases
   9.217 -that mean the same thing.  If you are talking about Mercurial history
   9.218 -with other people, you will find that the word ``changeset'' is often
   9.219 -compressed to ``change'' or (when written) ``cset'', and sometimes a
   9.220 -changeset is referred to as a ``revision'' or a ``rev''.
   9.221 -
   9.222 -While it doesn't matter what \emph{word} you use to refer to the
   9.223 -concept of ``a~changeset'', the \emph{identifier} that you use to
   9.224 -refer to ``a~\emph{specific} changeset'' is of great importance.
   9.225 -Recall that the \texttt{changeset} field in the output from
   9.226 -\hgcmd{log} identifies a changeset using both a number and a
   9.227 -hexadecimal string.
   9.228 -\begin{itemize}
   9.229 -\item The revision number is \emph{only valid in that repository},
   9.230 -\item while the hex string is the \emph{permanent, unchanging identifier} that will always identify that exact changeset in
   9.231 -  \emph{every} copy of the repository.
   9.232 -\end{itemize}
   9.233 -This distinction is important.  If you send someone an email talking
   9.234 -about ``revision~33'', there's a high likelihood that their
   9.235 -revision~33 will \emph{not be the same} as yours.  The reason for this
   9.236 -is that a revision number depends on the order in which changes
   9.237 -arrived in a repository, and there is no guarantee that the same
   9.238 -changes will happen in the same order in different repositories.
   9.239 -Three changes $a,b,c$ can easily appear in one repository as $0,1,2$,
   9.240 -while in another as $1,0,2$.
   9.241 -
   9.242 -Mercurial uses revision numbers purely as a convenient shorthand.  If
   9.243 -you need to discuss a changeset with someone, or make a record of a
   9.244 -changeset for some other reason (for example, in a bug report), use
   9.245 -the hexadecimal identifier.
   9.246 -
   9.247 -\subsection{Viewing specific revisions}
   9.248 -
   9.249 -To narrow the output of \hgcmd{log} down to a single revision, use the
   9.250 -\hgopt{log}{-r} (or \hgopt{log}{--rev}) option.  You can use either a
   9.251 -revision number or a long-form changeset identifier, and you can
   9.252 -provide as many revisions as you want.  \interaction{tour.log-r}
   9.253 -
   9.254 -If you want to see the history of several revisions without having to
   9.255 -list each one, you can use \emph{range notation}; this lets you
   9.256 -express the idea ``I want all revisions between $a$ and $b$,
   9.257 -inclusive''.
   9.258 -\interaction{tour.log.range}
   9.259 -Mercurial also honours the order in which you specify revisions, so
   9.260 -\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
   9.261 -prints $4,3,2$.
   9.262 -
   9.263 -\subsection{More detailed information}
   9.264 -
   9.265 -While the summary information printed by \hgcmd{log} is useful if you
   9.266 -already know what you're looking for, you may need to see a complete
   9.267 -description of the change, or a list of the files changed, if you're
   9.268 -trying to decide whether a changeset is the one you're looking for.
   9.269 -The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose})
   9.270 -option gives you this extra detail.
   9.271 -\interaction{tour.log-v}
   9.272 -
   9.273 -If you want to see both the description and content of a change, add
   9.274 -the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option.  This displays
   9.275 -the content of a change as a \emph{unified diff} (if you've never seen
   9.276 -a unified diff before, see section~\ref{sec:mq:patch} for an overview).
   9.277 -\interaction{tour.log-vp}
   9.278 -
   9.279 -\section{All about command options}
   9.280 -
   9.281 -Let's take a brief break from exploring Mercurial commands to discuss
   9.282 -a pattern in the way that they work; you may find this useful to keep
   9.283 -in mind as we continue our tour.
   9.284 -
   9.285 -Mercurial has a consistent and straightforward approach to dealing
   9.286 -with the options that you can pass to commands.  It follows the
   9.287 -conventions for options that are common to modern Linux and Unix
   9.288 -systems.
   9.289 -\begin{itemize}
   9.290 -\item Every option has a long name.  For example, as we've already
   9.291 -  seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
   9.292 -\item Most options have short names, too.  Instead of
   9.293 -  \hgopt{log}{--rev}, we can use \hgopt{log}{-r}.  (The reason that
   9.294 -  some options don't have short names is that the options in question
   9.295 -  are rarely used.)
   9.296 -\item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
   9.297 -  while short options start with one (e.g.~\hgopt{log}{-r}).
   9.298 -\item Option naming and usage is consistent across commands.  For
   9.299 -  example, every command that lets you specify a changeset~ID or
   9.300 -  revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
   9.301 -  arguments.
   9.302 -\end{itemize}
   9.303 -In the examples throughout this book, I use short options instead of
   9.304 -long.  This just reflects my own preference, so don't read anything
   9.305 -significant into it.
   9.306 -
   9.307 -Most commands that print output of some kind will print more output
   9.308 -when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
   9.309 -when passed \hggopt{-q} (or \hggopt{--quiet}).
   9.310 -
   9.311 -\section{Making and reviewing changes}
   9.312 -
   9.313 -Now that we have a grasp of viewing history in Mercurial, let's take a
   9.314 -look at making some changes and examining them.
   9.315 -
   9.316 -The first thing we'll do is isolate our experiment in a repository of
   9.317 -its own.  We use the \hgcmd{clone} command, but we don't need to
   9.318 -clone a copy of the remote repository.  Since we already have a copy
   9.319 -of it locally, we can just clone that instead.  This is much faster
   9.320 -than cloning over the network, and cloning a local repository uses
   9.321 -less disk space in most cases, too.
   9.322 -\interaction{tour.reclone}
   9.323 -As an aside, it's often good practice to keep a ``pristine'' copy of a
   9.324 -remote repository around, which you can then make temporary clones of
   9.325 -to create sandboxes for each task you want to work on.  This lets you
   9.326 -work on multiple tasks in parallel, each isolated from the others
   9.327 -until it's complete and you're ready to integrate it back.  Because
   9.328 -local clones are so cheap, there's almost no overhead to cloning and
   9.329 -destroying repositories whenever you want.
   9.330 -
   9.331 -In our \dirname{my-hello} repository, we have a file
   9.332 -\filename{hello.c} that contains the classic ``hello, world'' program.
   9.333 -Let's use the ancient and venerable \command{sed} command to edit this
   9.334 -file so that it prints a second line of output.  (I'm only using
   9.335 -\command{sed} to do this because it's easy to write a scripted example
   9.336 -this way.  Since you're not under the same constraint, you probably
   9.337 -won't want to use \command{sed}; simply use your preferred text editor to
   9.338 -do the same thing.)
   9.339 -\interaction{tour.sed}
   9.340 -
   9.341 -Mercurial's \hgcmd{status} command will tell us what Mercurial knows
   9.342 -about the files in the repository.
   9.343 -\interaction{tour.status}
   9.344 -The \hgcmd{status} command prints no output for some files, but a line
   9.345 -starting with ``\texttt{M}'' for \filename{hello.c}.  Unless you tell
   9.346 -it to, \hgcmd{status} will not print any output for files that have
   9.347 -not been modified.  
   9.348 -
   9.349 -The ``\texttt{M}'' indicates that Mercurial has noticed that we
   9.350 -modified \filename{hello.c}.  We didn't need to \emph{inform}
   9.351 -Mercurial that we were going to modify the file before we started, or
   9.352 -that we had modified the file after we were done; it was able to
   9.353 -figure this out itself.
   9.354 -
   9.355 -It's a little bit helpful to know that we've modified
   9.356 -\filename{hello.c}, but we might prefer to know exactly \emph{what}
   9.357 -changes we've made to it.  To do this, we use the \hgcmd{diff}
   9.358 -command.
   9.359 -\interaction{tour.diff}
   9.360 -
   9.361 -\section{Recording changes in a new changeset}
   9.362 -
   9.363 -We can modify files, build and test our changes, and use
   9.364 -\hgcmd{status} and \hgcmd{diff} to review our changes, until we're
   9.365 -satisfied with what we've done and arrive at a natural stopping point
   9.366 -where we want to record our work in a new changeset.
   9.367 -
   9.368 -The \hgcmd{commit} command lets us create a new changeset; we'll
   9.369 -usually refer to this as ``making a commit'' or ``committing''.  
   9.370 -
   9.371 -\subsection{Setting up a username}
   9.372 -
   9.373 -When you try to run \hgcmd{commit} for the first time, it is not
   9.374 -guaranteed to succeed.  Mercurial records your name and address with
   9.375 -each change that you commit, so that you and others will later be able
   9.376 -to tell who made each change.  Mercurial tries to automatically figure
   9.377 -out a sensible username to commit the change with.  It will attempt
   9.378 -each of the following methods, in order:
   9.379 -\begin{enumerate}
   9.380 -\item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit}
   9.381 -  command on the command line, followed by a username, this is always
   9.382 -  given the highest precedence.
   9.383 -\item If you have set the \envar{HGUSER} environment variable, this is
   9.384 -  checked next.
   9.385 -\item If you create a file in your home directory called
   9.386 -  \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be
   9.387 -  used next.  To see what the contents of this file should look like,
   9.388 -  refer to section~\ref{sec:tour-basic:username} below.
   9.389 -\item If you have set the \envar{EMAIL} environment variable, this
   9.390 -  will be used next.
   9.391 -\item Mercurial will query your system to find out your local user
   9.392 -  name and host name, and construct a username from these components.
   9.393 -  Since this often results in a username that is not very useful, it
   9.394 -  will print a warning if it has to do this.
   9.395 -\end{enumerate}
   9.396 -If all of these mechanisms fail, Mercurial will fail, printing an
   9.397 -error message.  In this case, it will not let you commit until you set
   9.398 -up a username.
   9.399 -
   9.400 -You should think of the \envar{HGUSER} environment variable and the
   9.401 -\hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to
   9.402 -\emph{override} Mercurial's default selection of username.  For normal
   9.403 -use, the simplest and most robust way to set a username for yourself
   9.404 -is by creating a \sfilename{.hgrc} file; see below for details.
   9.405 -
   9.406 -\subsubsection{Creating a Mercurial configuration file}
   9.407 -\label{sec:tour-basic:username}
   9.408 -
   9.409 -To set a user name, use your favourite editor to create a file called
   9.410 -\sfilename{.hgrc} in your home directory.  Mercurial will use this
   9.411 -file to look up your personalised configuration settings.  The initial
   9.412 -contents of your \sfilename{.hgrc} should look like this.
   9.413 -\begin{codesample2}
   9.414 -  # This is a Mercurial configuration file.
   9.415 -  [ui]
   9.416 -  username = Firstname Lastname <email.address@domain.net>
   9.417 -\end{codesample2}
   9.418 -The ``\texttt{[ui]}'' line begins a \emph{section} of the config file,
   9.419 -so you can read the ``\texttt{username = ...}'' line as meaning ``set
   9.420 -the value of the \texttt{username} item in the \texttt{ui} section''.
   9.421 -A section continues until a new section begins, or the end of the
   9.422 -file.  Mercurial ignores empty lines and treats any text from
   9.423 -``\texttt{\#}'' to the end of a line as a comment.
   9.424 -
   9.425 -\subsubsection{Choosing a user name}
   9.426 -
   9.427 -You can use any text you like as the value of the \texttt{username}
   9.428 -config item, since this information is for reading by other people,
   9.429 -but for interpreting by Mercurial.  The convention that most people
   9.430 -follow is to use their name and email address, as in the example
   9.431 -above.
   9.432 -
   9.433 -\begin{note}
   9.434 -  Mercurial's built-in web server obfuscates email addresses, to make
   9.435 -  it more difficult for the email harvesting tools that spammers use.
   9.436 -  This reduces the likelihood that you'll start receiving more junk
   9.437 -  email if you publish a Mercurial repository on the web.
   9.438 -\end{note}
   9.439 -
   9.440 -\subsection{Writing a commit message}
   9.441 -
   9.442 -When we commit a change, Mercurial drops us into a text editor, to
   9.443 -enter a message that will describe the modifications we've made in
   9.444 -this changeset.  This is called the \emph{commit message}.  It will be
   9.445 -a record for readers of what we did and why, and it will be printed by
   9.446 -\hgcmd{log} after we've finished committing.
   9.447 -\interaction{tour.commit}
   9.448 -
   9.449 -The editor that the \hgcmd{commit} command drops us into will contain
   9.450 -an empty line, followed by a number of lines starting with
   9.451 -``\texttt{HG:}''.
   9.452 -\begin{codesample2}
   9.453 -  \emph{empty line}
   9.454 -  HG: changed hello.c
   9.455 -\end{codesample2}
   9.456 -Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
   9.457 -them only to tell us which files it's recording changes to.  Modifying
   9.458 -or deleting these lines has no effect.
   9.459 -
   9.460 -\subsection{Writing a good commit message}
   9.461 -
   9.462 -Since \hgcmd{log} only prints the first line of a commit message by
   9.463 -default, it's best to write a commit message whose first line stands
   9.464 -alone.  Here's a real example of a commit message that \emph{doesn't}
   9.465 -follow this guideline, and hence has a summary that is not readable.
   9.466 -\begin{codesample2}
   9.467 -  changeset:   73:584af0e231be
   9.468 -  user:        Censored Person <censored.person@example.org>
   9.469 -  date:        Tue Sep 26 21:37:07 2006 -0700
   9.470 -  summary:     include buildmeister/commondefs.   Add an exports and install
   9.471 -\end{codesample2}
   9.472 -
   9.473 -As far as the remainder of the contents of the commit message are
   9.474 -concerned, there are no hard-and-fast rules.  Mercurial itself doesn't
   9.475 -interpret or care about the contents of the commit message, though
   9.476 -your project may have policies that dictate a certain kind of
   9.477 -formatting.
   9.478 -
   9.479 -My personal preference is for short, but informative, commit messages
   9.480 -that tell me something that I can't figure out with a quick glance at
   9.481 -the output of \hgcmdargs{log}{--patch}.
   9.482 -
   9.483 -\subsection{Aborting a commit}
   9.484 -
   9.485 -If you decide that you don't want to commit while in the middle of
   9.486 -editing a commit message, simply exit from your editor without saving
   9.487 -the file that it's editing.  This will cause nothing to happen to
   9.488 -either the repository or the working directory.
   9.489 -
   9.490 -If we run the \hgcmd{commit} command without any arguments, it records
   9.491 -all of the changes we've made, as reported by \hgcmd{status} and
   9.492 -\hgcmd{diff}.
   9.493 -
   9.494 -\subsection{Admiring our new handiwork}
   9.495 -
   9.496 -Once we've finished the commit, we can use the \hgcmd{tip} command to
   9.497 -display the changeset we just created.  This command produces output
   9.498 -that is identical to \hgcmd{log}, but it only displays the newest
   9.499 -revision in the repository.
   9.500 -\interaction{tour.tip}
   9.501 -We refer to the newest revision in the repository as the tip revision,
   9.502 -or simply the tip.
   9.503 -
   9.504 -\section{Sharing changes}
   9.505 -
   9.506 -We mentioned earlier that repositories in Mercurial are
   9.507 -self-contained.  This means that the changeset we just created exists
   9.508 -only in our \dirname{my-hello} repository.  Let's look at a few ways
   9.509 -that we can propagate this change into other repositories.
   9.510 -
   9.511 -\subsection{Pulling changes from another repository}
   9.512 -\label{sec:tour:pull}
   9.513 -
   9.514 -To get started, let's clone our original \dirname{hello} repository,
   9.515 -which does not contain the change we just committed.  We'll call our
   9.516 -temporary repository \dirname{hello-pull}.
   9.517 -\interaction{tour.clone-pull}
   9.518 -
   9.519 -We'll use the \hgcmd{pull} command to bring changes from
   9.520 -\dirname{my-hello} into \dirname{hello-pull}.  However, blindly
   9.521 -pulling unknown changes into a repository is a somewhat scary
   9.522 -prospect.  Mercurial provides the \hgcmd{incoming} command to tell us
   9.523 -what changes the \hgcmd{pull} command \emph{would} pull into the
   9.524 -repository, without actually pulling the changes in.
   9.525 -\interaction{tour.incoming}
   9.526 -(Of course, someone could cause more changesets to appear in the
   9.527 -repository that we ran \hgcmd{incoming} in, before we get a chance to
   9.528 -\hgcmd{pull} the changes, so that we could end up pulling changes that we
   9.529 -didn't expect.)
   9.530 -
   9.531 -Bringing changes into a repository is a simple matter of running the
   9.532 -\hgcmd{pull} command, and telling it which repository to pull from.
   9.533 -\interaction{tour.pull}
   9.534 -As you can see from the before-and-after output of \hgcmd{tip}, we
   9.535 -have successfully pulled changes into our repository.  There remains
   9.536 -one step before we can see these changes in the working directory.
   9.537 -
   9.538 -\subsection{Updating the working directory}
   9.539 -
   9.540 -We have so far glossed over the relationship between a repository and
   9.541 -its working directory.  The \hgcmd{pull} command that we ran in
   9.542 -section~\ref{sec:tour:pull} brought changes into the repository, but
   9.543 -if we check, there's no sign of those changes in the working
   9.544 -directory.  This is because \hgcmd{pull} does not (by default) touch
   9.545 -the working directory.  Instead, we use the \hgcmd{update} command to
   9.546 -do this.
   9.547 -\interaction{tour.update}
   9.548 -
   9.549 -It might seem a bit strange that \hgcmd{pull} doesn't update the
   9.550 -working directory automatically.  There's actually a good reason for
   9.551 -this: you can use \hgcmd{update} to update the working directory to
   9.552 -the state it was in at \emph{any revision} in the history of the
   9.553 -repository.  If you had the working directory updated to an old
   9.554 -revision---to hunt down the origin of a bug, say---and ran a
   9.555 -\hgcmd{pull} which automatically updated the working directory to a
   9.556 -new revision, you might not be terribly happy.
   9.557 -
   9.558 -However, since pull-then-update is such a common thing to do,
   9.559 -Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
   9.560 -option to \hgcmd{pull}.
   9.561 -\begin{codesample2}
   9.562 -  hg pull -u
   9.563 -\end{codesample2}
   9.564 -If you look back at the output of \hgcmd{pull} in
   9.565 -section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
   9.566 -you can see that it printed a helpful reminder that we'd have to take
   9.567 -an explicit step to update the working directory:
   9.568 -\begin{codesample2}
   9.569 -  (run 'hg update' to get a working copy)
   9.570 -\end{codesample2}
   9.571 -
   9.572 -To find out what revision the working directory is at, use the
   9.573 -\hgcmd{parents} command.
   9.574 -\interaction{tour.parents}
   9.575 -If you look back at figure~\ref{fig:tour-basic:history}, you'll see
   9.576 -arrows connecting each changeset.  The node that the arrow leads
   9.577 -\emph{from} in each case is a parent, and the node that the arrow
   9.578 -leads \emph{to} is its child.  The working directory has a parent in
   9.579 -just the same way; this is the changeset that the working directory
   9.580 -currently contains.
   9.581 -
   9.582 -To update the working directory to a particular revision, give a
   9.583 -revision number or changeset~ID to the \hgcmd{update} command.
   9.584 -\interaction{tour.older}
   9.585 -If you omit an explicit revision, \hgcmd{update} will update to the
   9.586 -tip revision, as shown by the second call to \hgcmd{update} in the
   9.587 -example above.
   9.588 -
   9.589 -\subsection{Pushing changes to another repository}
   9.590 -
   9.591 -Mercurial lets us push changes to another repository, from the
   9.592 -repository we're currently visiting.  As with the example of
   9.593 -\hgcmd{pull} above, we'll create a temporary repository to push our
   9.594 -changes into.
   9.595 -\interaction{tour.clone-push}
   9.596 -The \hgcmd{outgoing} command tells us what changes would be pushed
   9.597 -into another repository.
   9.598 -\interaction{tour.outgoing}
   9.599 -And the \hgcmd{push} command does the actual push.
   9.600 -\interaction{tour.push}
   9.601 -As with \hgcmd{pull}, the \hgcmd{push} command does not update the
   9.602 -working directory in the repository that it's pushing changes into.
   9.603 -(Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
   9.604 -option that updates the other repository's working directory.)
   9.605 -
   9.606 -What happens if we try to pull or push changes and the receiving
   9.607 -repository already has those changes?  Nothing too exciting.
   9.608 -\interaction{tour.push.nothing}
   9.609 -
   9.610 -\subsection{Sharing changes over a network}
   9.611 -
   9.612 -The commands we have covered in the previous few sections are not
   9.613 -limited to working with local repositories.  Each works in exactly the
   9.614 -same fashion over a network connection; simply pass in a URL instead
   9.615 -of a local path.
   9.616 -\interaction{tour.outgoing.net}
   9.617 -In this example, we can see what changes we could push to the remote
   9.618 -repository, but the repository is understandably not set up to let
   9.619 -anonymous users push to it.
   9.620 -\interaction{tour.push.net}
   9.621 -
   9.622 -%%% Local Variables: 
   9.623 -%%% mode: latex
   9.624 -%%% TeX-master: "00book"
   9.625 -%%% End: 

    10.1 --- a/en/ch03-tour-merge.tex	Thu Mar 05 21:52:23 2009 +0200
    10.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
    10.3 @@ -1,285 +0,0 @@
    10.4 -\chapter{A tour of Mercurial: merging work}
    10.5 -\label{chap:tour-merge}
    10.6 -
    10.7 -We've now covered cloning a repository, making changes in a
    10.8 -repository, and pulling or pushing changes from one repository into
    10.9 -another.  Our next step is \emph{merging} changes from separate
   10.10 -repositories.
   10.11 -
   10.12 -\section{Merging streams of work}
   10.13 -
   10.14 -Merging is a fundamental part of working with a distributed revision
   10.15 -control tool.
   10.16 -\begin{itemize}
   10.17 -\item Alice and Bob each have a personal copy of a repository for a
   10.18 -  project they're collaborating on.  Alice fixes a bug in her
   10.19 -  repository; Bob adds a new feature in his.  They want the shared
   10.20 -  repository to contain both the bug fix and the new feature.
   10.21 -\item I frequently work on several different tasks for a single
   10.22 -  project at once, each safely isolated in its own repository.
   10.23 -  Working this way means that I often need to merge one piece of my
   10.24 -  own work with another.
   10.25 -\end{itemize}
   10.26 -
   10.27 -Because merging is such a common thing to need to do, Mercurial makes
   10.28 -it easy.  Let's walk through the process.  We'll begin by cloning yet
   10.29 -another repository (see how often they spring up?) and making a change
   10.30 -in it.
   10.31 -\interaction{tour.merge.clone}
   10.32 -We should now have two copies of \filename{hello.c} with different
   10.33 -contents.  The histories of the two repositories have also diverged,
   10.34 -as illustrated in figure~\ref{fig:tour-merge:sep-repos}.
   10.35 -\interaction{tour.merge.cat}
   10.36 -
   10.37 -\begin{figure}[ht]
   10.38 -  \centering
   10.39 -  \grafix{tour-merge-sep-repos}
   10.40 -  \caption{Divergent recent histories of the \dirname{my-hello} and
   10.41 -    \dirname{my-new-hello} repositories}
   10.42 -  \label{fig:tour-merge:sep-repos}
   10.43 -\end{figure}
   10.44 -
   10.45 -We already know that pulling changes from our \dirname{my-hello}
   10.46 -repository will have no effect on the working directory.
   10.47 -\interaction{tour.merge.pull}
   10.48 -However, the \hgcmd{pull} command says something about ``heads''.  
   10.49 -
   10.50 -\subsection{Head changesets}
   10.51 -
   10.52 -A head is a change that has no descendants, or children, as they're
   10.53 -also known.  The tip revision is thus a head, because the newest
   10.54 -revision in a repository doesn't have any children, but a repository
   10.55 -can contain more than one head.
   10.56 -
   10.57 -\begin{figure}[ht]
   10.58 -  \centering
   10.59 -  \grafix{tour-merge-pull}
   10.60 -  \caption{Repository contents after pulling from \dirname{my-hello} into
   10.61 -    \dirname{my-new-hello}}
   10.62 -  \label{fig:tour-merge:pull}
   10.63 -\end{figure}
   10.64 -
   10.65 -In figure~\ref{fig:tour-merge:pull}, you can see the effect of the
   10.66 -pull from \dirname{my-hello} into \dirname{my-new-hello}.  The history
   10.67 -that was already present in \dirname{my-new-hello} is untouched, but a
   10.68 -new revision has been added.  By referring to
   10.69 -figure~\ref{fig:tour-merge:sep-repos}, we can see that the
   10.70 -\emph{changeset ID} remains the same in the new repository, but the
   10.71 -\emph{revision number} has changed.  (This, incidentally, is a fine
   10.72 -example of why it's not safe to use revision numbers when discussing
   10.73 -changesets.)  We can view the heads in a repository using the
   10.74 -\hgcmd{heads} command.
   10.75 -\interaction{tour.merge.heads}
   10.76 -
   10.77 -\subsection{Performing the merge}
   10.78 -
   10.79 -What happens if we try to use the normal \hgcmd{update} command to
   10.80 -update to the new tip?
   10.81 -\interaction{tour.merge.update}
   10.82 -Mercurial is telling us that the \hgcmd{update} command won't do a
   10.83 -merge; it won't update the working directory when it thinks we might
   10.84 -be wanting to do a merge, unless we force it to do so.  Instead, we
   10.85 -use the \hgcmd{merge} command to merge the two heads.
   10.86 -\interaction{tour.merge.merge}
   10.87 -
   10.88 -\begin{figure}[ht]
   10.89 -  \centering
   10.90 -  \grafix{tour-merge-merge}
   10.91 -  \caption{Working directory and repository during merge, and following commit}
   10.92 -  \label{fig:tour-merge:merge}
   10.93 -\end{figure}
   10.94 -
   10.95 -This updates the working directory so that it contains changes from
   10.96 -\emph{both} heads, which is reflected in both the output of
   10.97 -\hgcmd{parents} and the contents of \filename{hello.c}.
   10.98 -\interaction{tour.merge.parents}
   10.99 -
  10.100 -\subsection{Committing the results of the merge}
  10.101 -
  10.102 -Whenever we've done a merge, \hgcmd{parents} will display two parents
  10.103 -until we \hgcmd{commit} the results of the merge.
  10.104 -\interaction{tour.merge.commit}
  10.105 -We now have a new tip revision; notice that it has \emph{both} of
  10.106 -our former heads as its parents.  These are the same revisions that
  10.107 -were previously displayed by \hgcmd{parents}.
  10.108 -\interaction{tour.merge.tip}
  10.109 -In figure~\ref{fig:tour-merge:merge}, you can see a representation of
  10.110 -what happens to the working directory during the merge, and how this
  10.111 -affects the repository when the commit happens.  During the merge, the
  10.112 -working directory has two parent changesets, and these become the
  10.113 -parents of the new changeset.
  10.114 -
  10.115 -\section{Merging conflicting changes}
  10.116 -
  10.117 -Most merges are simple affairs, but sometimes you'll find yourself
  10.118 -merging changes where each modifies the same portions of the same
  10.119 -files.  Unless both modifications are identical, this results in a
  10.120 -\emph{conflict}, where you have to decide how to reconcile the
  10.121 -different changes into something coherent.
  10.122 -
  10.123 -\begin{figure}[ht]
  10.124 -  \centering
  10.125 -  \grafix{tour-merge-conflict}
  10.126 -  \caption{Conflicting changes to a document}
  10.127 -  \label{fig:tour-merge:conflict}
  10.128 -\end{figure}
  10.129 -
  10.130 -Figure~\ref{fig:tour-merge:conflict} illustrates an instance of two
  10.131 -conflicting changes to a document.  We started with a single version
  10.132 -of the file; then we made some changes; while someone else made
  10.133 -different changes to the same text.  Our task in resolving the
  10.134 -conflicting changes is to decide what the file should look like.
  10.135 -
  10.136 -Mercurial doesn't have a built-in facility for handling conflicts.
  10.137 -Instead, it runs an external program called \command{hgmerge}.  This
  10.138 -is a shell script that is bundled with Mercurial; you can change it to
  10.139 -behave however you please.  What it does by default is try to find one
  10.140 -of several different merging tools that are likely to be installed on
  10.141 -your system.  It first tries a few fully automatic merging tools; if
  10.142 -these don't succeed (because the resolution process requires human
  10.143 -guidance) or aren't present, the script tries a few different
  10.144 -graphical merging tools.
  10.145 -
  10.146 -It's also possible to get Mercurial to run another program or script
  10.147 -instead of \command{hgmerge}, by setting the \envar{HGMERGE}
  10.148 -environment variable to the name of your preferred program.
  10.149 -
  10.150 -\subsection{Using a graphical merge tool}
  10.151 -
  10.152 -My preferred graphical merge tool is \command{kdiff3}, which I'll use
  10.153 -to describe the features that are common to graphical file merging
  10.154 -tools.  You can see a screenshot of \command{kdiff3} in action in
  10.155 -figure~\ref{fig:tour-merge:kdiff3}.  The kind of merge it is
  10.156 -performing is called a \emph{three-way merge}, because there are three
  10.157 -different versions of the file of interest to us.  The tool thus
  10.158 -splits the upper portion of the window into three panes:
  10.159 -\begin{itemize}
  10.160 -\item At the left is the \emph{base} version of the file, i.e.~the
  10.161 -  most recent version from which the two versions we're trying to
  10.162 -  merge are descended.
  10.163 -\item In the middle is ``our'' version of the file, with the contents
  10.164 -  that we modified.
  10.165 -\item On the right is ``their'' version of the file, the one that
  10.166 -  from the changeset that we're trying to merge with.
  10.167 -\end{itemize}
  10.168 -In the pane below these is the current \emph{result} of the merge.
  10.169 -Our task is to replace all of the red text, which indicates unresolved
  10.170 -conflicts, with some sensible merger of the ``ours'' and ``theirs''
  10.171 -versions of the file.
  10.172 -
  10.173 -All four of these panes are \emph{locked together}; if we scroll
  10.174 -vertically or horizontally in any of them, the others are updated to
  10.175 -display the corresponding sections of their respective files.
  10.176 -
  10.177 -\begin{figure}[ht]
  10.178 -  \centering
  10.179 -  \grafix{kdiff3}
  10.180 -  \caption{Using \command{kdiff3} to merge versions of a file}
  10.181 -  \label{fig:tour-merge:kdiff3}
  10.182 -\end{figure}
  10.183 -
  10.184 -For each conflicting portion of the file, we can choose to resolve
  10.185 -the conflict using some combination of text from the base version,
  10.186 -ours, or theirs.  We can also manually edit the merged file at any
  10.187 -time, in case we need to make further modifications.
  10.188 -
  10.189 -There are \emph{many} file merging tools available, too many to cover
  10.190 -here.  They vary in which platforms they are available for, and in
  10.191 -their particular strengths and weaknesses.  Most are tuned for merging
  10.192 -files containing plain text, while a few are aimed at specialised file
  10.193 -formats (generally XML).
  10.194 -
  10.195 -\subsection{A worked example}
  10.196 -
  10.197 -In this example, we will reproduce the file modification history of
  10.198 -figure~\ref{fig:tour-merge:conflict} above.  Let's begin by creating a
  10.199 -repository with a base version of our document.
  10.200 -\interaction{tour-merge-conflict.wife}
  10.201 -We'll clone the repository and make a change to the file.
  10.202 -\interaction{tour-merge-conflict.cousin}
  10.203 -And another clone, to simulate someone else making a change to the
  10.204 -file.  (This hints at the idea that it's not all that unusual to merge
  10.205 -with yourself when you isolate tasks in separate repositories, and
  10.206 -indeed to find and resolve conflicts while doing so.)
  10.207 -\interaction{tour-merge-conflict.son}
  10.208 -Having created two different versions of the file, we'll set up an
  10.209 -environment suitable for running our merge.
  10.210 -\interaction{tour-merge-conflict.pull}
  10.211 -
  10.212 -In this example, I won't use Mercurial's normal \command{hgmerge}
  10.213 -program to do the merge, because it would drop my nice automated
  10.214 -example-running tool into a graphical user interface.  Instead, I'll
  10.215 -set \envar{HGMERGE} to tell Mercurial to use the non-interactive
  10.216 -\command{merge} command.  This is bundled with many Unix-like systems.
  10.217 -If you're following this example on your computer, don't bother
  10.218 -setting \envar{HGMERGE}.
  10.219 -
  10.220 -\textbf{XXX FIX THIS EXAMPLE.}
  10.221 -
  10.222 -\interaction{tour-merge-conflict.merge}
  10.223 -Because \command{merge} can't resolve the conflicting changes, it
  10.224 -leaves \emph{merge markers} inside the file that has conflicts,
  10.225 -indicating which lines have conflicts, and whether they came from our
  10.226 -version of the file or theirs.
  10.227 -
  10.228 -Mercurial can tell from the way \command{merge} exits that it wasn't
  10.229 -able to merge successfully, so it tells us what commands we'll need to
  10.230 -run if we want to redo the merging operation.  This could be useful
  10.231 -if, for example, we were running a graphical merge tool and quit
  10.232 -because we were confused or realised we had made a mistake.
  10.233 -
  10.234 -If automatic or manual merges fail, there's nothing to prevent us from
  10.235 -``fixing up'' the affected files ourselves, and committing the results
  10.236 -of our merge:
  10.237 -\interaction{tour-merge-conflict.commit}
  10.238 -
  10.239 -\section{Simplifying the pull-merge-commit sequence}
  10.240 -\label{sec:tour-merge:fetch}
  10.241 -
  10.242 -The process of merging changes as outlined above is straightforward,
  10.243 -but requires running three commands in sequence.
  10.244 -\begin{codesample2}
  10.245 -  hg pull
  10.246 -  hg merge
  10.247 -  hg commit -m 'Merged remote changes'
  10.248 -\end{codesample2}
  10.249 -In the case of the final commit, you also need to enter a commit
  10.250 -message, which is almost always going to be a piece of uninteresting
  10.251 -``boilerplate'' text.
  10.252 -
  10.253 -It would be nice to reduce the number of steps needed, if this were
  10.254 -possible.  Indeed, Mercurial is distributed with an extension called
  10.255 -\hgext{fetch} that does just this.
  10.256 -
  10.257 -Mercurial provides a flexible extension mechanism that lets people
  10.258 -extend its functionality, while keeping the core of Mercurial small
  10.259 -and easy to deal with.  Some extensions add new commands that you can
  10.260 -use from the command line, while others work ``behind the scenes,''
  10.261 -for example adding capabilities to the server.
  10.262 -
  10.263 -The \hgext{fetch} extension adds a new command called, not
  10.264 -surprisingly, \hgcmd{fetch}.  This extension acts as a combination of
  10.265 -\hgcmd{pull}, \hgcmd{update} and \hgcmd{merge}.  It begins by pulling
  10.266 -changes from another repository into the current repository.  If it
  10.267 -finds that the changes added a new head to the repository, it begins a
  10.268 -merge, then commits the result of the merge with an
  10.269 -automatically-generated commit message.  If no new heads were added,
  10.270 -it updates the working directory to the new tip changeset.
  10.271 -
  10.272 -Enabling the \hgext{fetch} extension is easy.  Edit your
  10.273 -\sfilename{.hgrc}, and either go to the \rcsection{extensions} section
  10.274 -or create an \rcsection{extensions} section.  Then add a line that
  10.275 -simply reads ``\Verb+fetch +''.
  10.276 -\begin{codesample2}
  10.277 -  [extensions]
  10.278 -  fetch =
  10.279 -\end{codesample2}
  10.280 -(Normally, on the right-hand side of the ``\texttt{=}'' would appear
  10.281 -the location of the extension, but since the \hgext{fetch} extension
  10.282 -is in the standard distribution, Mercurial knows where to search for
  10.283 -it.)
  10.284 -
  10.285 -%%% Local Variables: 
  10.286 -%%% mode: latex
  10.287 -%%% TeX-master: "00book"
  10.288 -%%% End: 

    11.1 --- a/en/ch04-concepts.tex	Thu Mar 05 21:52:23 2009 +0200
    11.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
    11.3 @@ -1,574 +0,0 @@
    11.4 -\chapter{Behind the scenes}
    11.5 -\label{chap:concepts}
    11.6 -
    11.7 -Unlike many revision control systems, the concepts upon which
    11.8 -Mercurial is built are simple enough that it's easy to understand how
    11.9 -the software really works.  Knowing this certainly isn't necessary,
   11.10 -but I find it useful to have a ``mental model'' of what's going on.
   11.11 -
   11.12 -This understanding gives me confidence that Mercurial has been
   11.13 -carefully designed to be both \emph{safe} and \emph{efficient}.  And
   11.14 -just as importantly, if it's easy for me to retain a good idea of what
   11.15 -the software is doing when I perform a revision control task, I'm less
   11.16 -likely to be surprised by its behaviour.
   11.17 -
   11.18 -In this chapter, we'll initially cover the core concepts behind
   11.19 -Mercurial's design, then continue to discuss some of the interesting
   11.20 -details of its implementation.
   11.21 -
   11.22 -\section{Mercurial's historical record}
   11.23 -
   11.24 -\subsection{Tracking the history of a single file}
   11.25 -
   11.26 -When Mercurial tracks modifications to a file, it stores the history
   11.27 -of that file in a metadata object called a \emph{filelog}.  Each entry
   11.28 -in the filelog contains enough information to reconstruct one revision
   11.29 -of the file that is being tracked.  Filelogs are stored as files in
   11.30 -the \sdirname{.hg/store/data} directory.  A filelog contains two kinds
   11.31 -of information: revision data, and an index to help Mercurial to find
   11.32 -a revision efficiently.
   11.33 -
   11.34 -A file that is large, or has a lot of history, has its filelog stored
   11.35 -in separate data (``\texttt{.d}'' suffix) and index (``\texttt{.i}''
   11.36 -suffix) files.  For small files without much history, the revision
   11.37 -data and index are combined in a single ``\texttt{.i}'' file.  The
   11.38 -correspondence between a file in the working directory and the filelog
   11.39 -that tracks its history in the repository is illustrated in
   11.40 -figure~\ref{fig:concepts:filelog}.
   11.41 -
   11.42 -\begin{figure}[ht]
   11.43 -  \centering
   11.44 -  \grafix{filelog}
   11.45 -  \caption{Relationships between files in working directory and filelogs in repository}
   11.46 -  \label{fig:concepts:filelog}
   11.47 -\end{figure}
   11.48 -
   11.49 -\subsection{Managing tracked files}
   11.50 -
   11.51 -Mercurial uses a structure called a \emph{manifest} to collect
   11.52 -together information about the files that it tracks.  Each entry in
   11.53 -the manifest contains information about the files present in a single
   11.54 -changeset.  An entry records which files are present in the changeset,
   11.55 -the revision of each file, and a few other pieces of file metadata.
   11.56 -
   11.57 -\subsection{Recording changeset information}
   11.58 -
   11.59 -The \emph{changelog} contains information about each changeset.  Each
   11.60 -revision records who committed a change, the changeset comment, other
   11.61 -pieces of changeset-related information, and the revision of the
   11.62 -manifest to use.
   11.63 -
   11.64 -\subsection{Relationships between revisions}
   11.65 -
   11.66 -Within a changelog, a manifest, or a filelog, each revision stores a
   11.67 -pointer to its immediate parent (or to its two parents, if it's a
   11.68 -merge revision).  As I mentioned above, there are also relationships
   11.69 -between revisions \emph{across} these structures, and they are
   11.70 -hierarchical in nature.
   11.71 -
   11.72 -For every changeset in a repository, there is exactly one revision
   11.73 -stored in the changelog.  Each revision of the changelog contains a
   11.74 -pointer to a single revision of the manifest.  A revision of the
   11.75 -manifest stores a pointer to a single revision of each filelog tracked
   11.76 -when that changeset was created.  These relationships are illustrated
   11.77 -in figure~\ref{fig:concepts:metadata}.
   11.78 -
   11.79 -\begin{figure}[ht]
   11.80 -  \centering
   11.81 -  \grafix{metadata}
   11.82 -  \caption{Metadata relationships}
   11.83 -  \label{fig:concepts:metadata}
   11.84 -\end{figure}
   11.85 -
   11.86 -As the illustration shows, there is \emph{not} a ``one to one''
   11.87 -relationship between revisions in the changelog, manifest, or filelog.
   11.88 -If the manifest hasn't changed between two changesets, the changelog
   11.89 -entries for those changesets will point to the same revision of the
   11.90 -manifest.  If a file that Mercurial tracks hasn't changed between two
   11.91 -changesets, the entry for that file in the two revisions of the
   11.92 -manifest will point to the same revision of its filelog.
   11.93 -
   11.94 -\section{Safe, efficient storage}
   11.95 -
   11.96 -The underpinnings of changelogs, manifests, and filelogs are provided
   11.97 -by a single structure called the \emph{revlog}.
   11.98 -
   11.99 -\subsection{Efficient storage}
  11.100 -
  11.101 -The revlog provides efficient storage of revisions using a
  11.102 -\emph{delta} mechanism.  Instead of storing a complete copy of a file
  11.103 -for each revision, it stores the changes needed to transform an older
  11.104 -revision into the new revision.  For many kinds of file data, these
  11.105 -deltas are typically a fraction of a percent of the size of a full
  11.106 -copy of a file.
  11.107 -
  11.108 -Some obsolete revision control systems can only work with deltas of
  11.109 -text files.  They must either store binary files as complete snapshots
  11.110 -or encoded into a text representation, both of which are wasteful
  11.111 -approaches.  Mercurial can efficiently handle deltas of files with
  11.112 -arbitrary binary contents; it doesn't need to treat text as special.
  11.113 -
  11.114 -\subsection{Safe operation}
  11.115 -\label{sec:concepts:txn}
  11.116 -
  11.117 -Mercurial only ever \emph{appends} data to the end of a revlog file.
  11.118 -It never modifies a section of a file after it has written it.  This
  11.119 -is both more robust and efficient than schemes that need to modify or
  11.120 -rewrite data.
  11.121 -
  11.122 -In addition, Mercurial treats every write as part of a
  11.123 -\emph{transaction} that can span a number of files.  A transaction is
  11.124 -\emph{atomic}: either the entire transaction succeeds and its effects
  11.125 -are all visible to readers in one go, or the whole thing is undone.
  11.126 -This guarantee of atomicity means that if you're running two copies of
  11.127 -Mercurial, where one is reading data and one is writing it, the reader
  11.128 -will never see a partially written result that might confuse it.
  11.129 -
  11.130 -The fact that Mercurial only appends to files makes it easier to
  11.131 -provide this transactional guarantee.  The easier it is to do stuff
  11.132 -like this, the more confident you should be that it's done correctly.
  11.133 -
  11.134 -\subsection{Fast retrieval}
  11.135 -
  11.136 -Mercurial cleverly avoids a pitfall common to all earlier
  11.137 -revision control systems: the problem of \emph{inefficient retrieval}.
  11.138 -Most revision control systems store the contents of a revision as an
  11.139 -incremental series of modifications against a ``snapshot''.  To
  11.140 -reconstruct a specific revision, you must first read the snapshot, and
  11.141 -then every one of the revisions between the snapshot and your target
  11.142 -revision.  The more history that a file accumulates, the more
  11.143 -revisions you must read, hence the longer it takes to reconstruct a
  11.144 -particular revision.
  11.145 -
  11.146 -\begin{figure}[ht]
  11.147 -  \centering
  11.148 -  \grafix{snapshot}
  11.149 -  \caption{Snapshot of a revlog, with incremental deltas}
  11.150 -  \label{fig:concepts:snapshot}
  11.151 -\end{figure}
  11.152 -
  11.153 -The innovation that Mercurial applies to this problem is simple but
  11.154 -effective.  Once the cumulative amount of delta information stored
  11.155 -since the last snapshot exceeds a fixed threshold, it stores a new
  11.156 -snapshot (compressed, of course), instead of another delta.  This
  11.157 -makes it possible to reconstruct \emph{any} revision of a file
  11.158 -quickly.  This approach works so well that it has since been copied by
  11.159 -several other revision control systems.
  11.160 -
  11.161 -Figure~\ref{fig:concepts:snapshot} illustrates the idea.  In an entry
  11.162 -in a revlog's index file, Mercurial stores the range of entries from
  11.163 -the data file that it must read to reconstruct a particular revision.
  11.164 -
  11.165 -\subsubsection{Aside: the influence of video compression}
  11.166 -
  11.167 -If you're familiar with video compression or have ever watched a TV
  11.168 -feed through a digital cable or satellite service, you may know that
  11.169 -most video compression schemes store each frame of video as a delta
  11.170 -against its predecessor frame.  In addition, these schemes use
  11.171 -``lossy'' compression techniques to increase the compression ratio, so
  11.172 -visual errors accumulate over the course of a number of inter-frame
  11.173 -deltas.
  11.174 -
  11.175 -Because it's possible for a video stream to ``drop out'' occasionally
  11.176 -due to signal glitches, and to limit the accumulation of artefacts
  11.177 -introduced by the lossy compression process, video encoders
  11.178 -periodically insert a complete frame (called a ``key frame'') into the
  11.179 -video stream; the next delta is generated against that frame.  This
  11.180 -means that if the video signal gets interrupted, it will resume once
  11.181 -the next key frame is received.  Also, the accumulation of encoding
  11.182 -errors restarts anew with each key frame.
  11.183 -
  11.184 -\subsection{Identification and strong integrity}
  11.185 -
  11.186 -Along with delta or snapshot information, a revlog entry contains a
  11.187 -cryptographic hash of the data that it represents.  This makes it
  11.188 -difficult to forge the contents of a revision, and easy to detect
  11.189 -accidental corruption.  
  11.190 -
  11.191 -Hashes provide more than a mere check against corruption; they are
  11.192 -used as the identifiers for revisions.  The changeset identification
  11.193 -hashes that you see as an end user are from revisions of the
  11.194 -changelog.  Although filelogs and the manifest also use hashes,
  11.195 -Mercurial only uses these behind the scenes.
  11.196 -
  11.197 -Mercurial verifies that hashes are correct when it retrieves file
  11.198 -revisions and when it pulls changes from another repository.  If it
  11.199 -encounters an integrity problem, it will complain and stop whatever
  11.200 -it's doing.
  11.201 -
  11.202 -In addition to the effect it has on retrieval efficiency, Mercurial's
  11.203 -use of periodic snapshots makes it more robust against partial data
  11.204 -corruption.  If a revlog becomes partly corrupted due to a hardware
  11.205 -error or system bug, it's often possible to reconstruct some or most
  11.206 -revisions from the uncorrupted sections of the revlog, both before and
  11.207 -after the corrupted section.  This would not be possible with a
  11.208 -delta-only storage model.
  11.209 -
  11.210 -\section{Revision history, branching, and merging}
  11.211 -
  11.212 -Every entry in a Mercurial revlog knows the identity of its immediate
  11.213 -ancestor revision, usually referred to as its \emph{parent}.  In fact,
  11.214 -a revision contains room for not one parent, but two.  Mercurial uses
  11.215 -a special hash, called the ``null ID'', to represent the idea ``there
  11.216 -is no parent here''.  This hash is simply a string of zeroes.
  11.217 -
  11.218 -In figure~\ref{fig:concepts:revlog}, you can see an example of the
  11.219 -conceptual structure of a revlog.  Filelogs, manifests, and changelogs
  11.220 -all have this same structure; they differ only in the kind of data
  11.221 -stored in each delta or snapshot.
  11.222 -
  11.223 -The first revision in a revlog (at the bottom of the image) has the
  11.224 -null ID in both of its parent slots.  For a ``normal'' revision, its
  11.225 -first parent slot contains the ID of its parent revision, and its
  11.226 -second contains the null ID, indicating that the revision has only one
  11.227 -real parent.  Any two revisions that have the same parent ID are
  11.228 -branches.  A revision that represents a merge between branches has two
  11.229 -normal revision IDs in its parent slots.
  11.230 -
  11.231 -\begin{figure}[ht]
  11.232 -  \centering
  11.233 -  \grafix{revlog}
  11.234 -  \caption{}
  11.235 -  \label{fig:concepts:revlog}
  11.236 -\end{figure}
  11.237 -
  11.238 -\section{The working directory}
  11.239 -
  11.240 -In the working directory, Mercurial stores a snapshot of the files
  11.241 -from the repository as of a particular changeset.
  11.242 -
  11.243 -The working directory ``knows'' which changeset it contains.  When you
  11.244 -update the working directory to contain a particular changeset,
  11.245 -Mercurial looks up the appropriate revision of the manifest to find
  11.246 -out which files it was tracking at the time that changeset was
  11.247 -committed, and which revision of each file was then current.  It then
  11.248 -recreates a copy of each of those files, with the same contents it had
  11.249 -when the changeset was committed.
  11.250 -
  11.251 -The \emph{dirstate} contains Mercurial's knowledge of the working
  11.252 -directory.  This details which changeset the working directory is
  11.253 -updated to, and all of the files that Mercurial is tracking in the
  11.254 -working directory.
  11.255 -
  11.256 -Just as a revision of a revlog has room for two parents, so that it
  11.257 -can represent either a normal revision (with one parent) or a merge of
  11.258 -two earlier revisions, the dirstate has slots for two parents.  When
  11.259 -you use the \hgcmd{update} command, the changeset that you update to
  11.260 -is stored in the ``first parent'' slot, and the null ID in the second.
  11.261 -When you \hgcmd{merge} with another changeset, the first parent
  11.262 -remains unchanged, and the second parent is filled in with the
  11.263 -changeset you're merging with.  The \hgcmd{parents} command tells you
  11.264 -what the parents of the dirstate are.
  11.265 -
  11.266 -\subsection{What happens when you commit}
  11.267 -
  11.268 -The dirstate stores parent information for more than just book-keeping
  11.269 -purposes.  Mercurial uses the parents of the dirstate as \emph{the parents of a new changeset} when you perform a commit.
  11.270 -
  11.271 -\begin{figure}[ht]
  11.272 -  \centering
  11.273 -  \grafix{wdir}
  11.274 -  \caption{The working directory can have two parents}
  11.275 -  \label{fig:concepts:wdir}
  11.276 -\end{figure}
  11.277 -
  11.278 -Figure~\ref{fig:concepts:wdir} shows the normal state of the working
  11.279 -directory, where it has a single changeset as parent.  That changeset
  11.280 -is the \emph{tip}, the newest changeset in the repository that has no
  11.281 -children.
  11.282 -
  11.283 -\begin{figure}[ht]
  11.284 -  \centering
  11.285 -  \grafix{wdir-after-commit}
  11.286 -  \caption{The working directory gains new parents after a commit}
  11.287 -  \label{fig:concepts:wdir-after-commit}
  11.288 -\end{figure}
  11.289 -
  11.290 -It's useful to think of the working directory as ``the changeset I'm
  11.291 -about to commit''.  Any files that you tell Mercurial that you've
  11.292 -added, removed, renamed, or copied will be reflected in that
  11.293 -changeset, as will modifications to any files that Mercurial is
  11.294 -already tracking; the new changeset will have the parents of the
  11.295 -working directory as its parents.
  11.296 -
  11.297 -After a commit, Mercurial will update the parents of the working
  11.298 -directory, so that the first parent is the ID of the new changeset,
  11.299 -and the second is the null ID.  This is shown in
  11.300 -figure~\ref{fig:concepts:wdir-after-commit}.  Mercurial doesn't touch
  11.301 -any of the files in the working directory when you commit; it just
  11.302 -modifies the dirstate to note its new parents.
  11.303 -
  11.304 -\subsection{Creating a new head}
  11.305 -
  11.306 -It's perfectly normal to update the working directory to a changeset
  11.307 -other than the current tip.  For example, you might want to know what
  11.308 -your project looked like last Tuesday, or you could be looking through
  11.309 -changesets to see which one introduced a bug.  In cases like this, the
  11.310 -natural thing to do is update the working directory to the changeset
  11.311 -you're interested in, and then examine the files in the working
  11.312 -directory directly to see their contents as they were when you
  11.313 -committed that changeset.  The effect of this is shown in
  11.314 -figure~\ref{fig:concepts:wdir-pre-branch}.
  11.315 -
  11.316 -\begin{figure}[ht]
  11.317 -  \centering
  11.318 -  \grafix{wdir-pre-branch}
  11.319 -  \caption{The working directory, updated to an older changeset}
  11.320 -  \label{fig:concepts:wdir-pre-branch}
  11.321 -\end{figure}
  11.322 -
  11.323 -Having updated the working directory to an older changeset, what
  11.324 -happens if you make some changes, and then commit?  Mercurial behaves
  11.325 -in the same way as I outlined above.  The parents of the working
  11.326 -directory become the parents of the new changeset.  This new changeset
  11.327 -has no children, so it becomes the new tip.  And the repository now
  11.328 -contains two changesets that have no children; we call these
  11.329 -\emph{heads}.  You can see the structure that this creates in
  11.330 -figure~\ref{fig:concepts:wdir-branch}.
  11.331 -
  11.332 -\begin{figure}[ht]
  11.333 -  \centering
  11.334 -  \grafix{wdir-branch}
  11.335 -  \caption{After a commit made while synced to an older changeset}
  11.336 -  \label{fig:concepts:wdir-branch}
  11.337 -\end{figure}
  11.338 -
  11.339 -\begin{note}
  11.340 -  If you're new to Mercurial, you should keep in mind a common
  11.341 -  ``error'', which is to use the \hgcmd{pull} command without any
  11.342 -  options.  By default, the \hgcmd{pull} command \emph{does not}
  11.343 -  update the working directory, so you'll bring new changesets into
  11.344 -  your repository, but the working directory will stay synced at the
  11.345 -  same changeset as before the pull.  If you make some changes and
  11.346 -  commit afterwards, you'll thus create a new head, because your
  11.347 -  working directory isn't synced to whatever the current tip is.
  11.348 -
  11.349 -  I put the word ``error'' in quotes because all that you need to do
  11.350 -  to rectify this situation is \hgcmd{merge}, then \hgcmd{commit}.  In
  11.351 -  other words, this almost never has negative consequences; it just
  11.352 -  surprises people.  I'll discuss other ways to avoid this behaviour,
  11.353 -  and why Mercurial behaves in this initially surprising way, later
  11.354 -  on.
  11.355 -\end{note}
  11.356 -
  11.357 -\subsection{Merging heads}
  11.358 -
  11.359 -When you run the \hgcmd{merge} command, Mercurial leaves the first
  11.360 -parent of the working directory unchanged, and sets the second parent
  11.361 -to the changeset you're merging with, as shown in
  11.362 -figure~\ref{fig:concepts:wdir-merge}.
  11.363 -
  11.364 -\begin{figure}[ht]
  11.365 -  \centering
  11.366 -  \grafix{wdir-merge}
  11.367 -  \caption{Merging two heads}
  11.368 -  \label{fig:concepts:wdir-merge}
  11.369 -\end{figure}
  11.370 -
  11.371 -Mercurial also has to modify the working directory, to merge the files
  11.372 -managed in the two changesets.  Simplified a little, the merging
  11.373 -process goes like this, for every file in the manifests of both
  11.374 -changesets.
  11.375 -\begin{itemize}
  11.376 -\item If neither changeset has modified a file, do nothing with that
  11.377 -  file.
  11.378 -\item If one changeset has modified a file, and the other hasn't,
  11.379 -  create the modified copy of the file in the working directory.
  11.380 -\item If one changeset has removed a file, and the other hasn't (or
  11.381 -  has also deleted it), delete the file from the working directory.
  11.382 -\item If one changeset has removed a file, but the other has modified
  11.383 -  the file, ask the user what to do: keep the modified file, or remove
  11.384 -  it?
  11.385 -\item If both changesets have modified a file, invoke an external
  11.386 -  merge program to choose the new contents for the merged file.  This
  11.387 -  may require input from the user.
  11.388 -\item If one changeset has modified a file, and the other has renamed
  11.389 -  or copied the file, make sure that the changes follow the new name
  11.390 -  of the file.
  11.391 -\end{itemize}
  11.392 -There are more details---merging has plenty of corner cases---but
  11.393 -these are the most common choices that are involved in a merge.  As
  11.394 -you can see, most cases are completely automatic, and indeed most
  11.395 -merges finish automatically, without requiring your input to resolve
  11.396 -any conflicts.
  11.397 -
  11.398 -When you're thinking about what happens when you commit after a merge,
  11.399 -once again the working directory is ``the changeset I'm about to
  11.400 -commit''.  After the \hgcmd{merge} command completes, the working
  11.401 -directory has two parents; these will become the parents of the new
  11.402 -changeset.
  11.403 -
  11.404 -Mercurial lets you perform multiple merges, but you must commit the
  11.405 -results of each individual merge as you go.  This is necessary because
  11.406 -Mercurial only tracks two parents for both revisions and the working
  11.407 -directory.  While it would be technically possible to merge multiple
  11.408 -changesets at once, the prospect of user confusion and making a
  11.409 -terrible mess of a merge immediately becomes overwhelming.
  11.410 -
  11.411 -\section{Other interesting design features}
  11.412 -
  11.413 -In the sections above, I've tried to highlight some of the most
  11.414 -important aspects of Mercurial's design, to illustrate that it pays
  11.415 -careful attention to reliability and performance.  However, the
  11.416 -attention to detail doesn't stop there.  There are a number of other
  11.417 -aspects of Mercurial's construction that I personally find
  11.418 -interesting.  I'll detail a few of them here, separate from the ``big
  11.419 -ticket'' items above, so that if you're interested, you can gain a
  11.420 -better idea of the amount of thinking that goes into a well-designed
  11.421 -system.
  11.422 -
  11.423 -\subsection{Clever compression}
  11.424 -
  11.425 -When appropriate, Mercurial will store both snapshots and deltas in
  11.426 -compressed form.  It does this by always \emph{trying to} compress a
  11.427 -snapshot or delta, but only storing the compressed version if it's
  11.428 -smaller than the uncompressed version.
  11.429 -
  11.430 -This means that Mercurial does ``the right thing'' when storing a file
  11.431 -whose native form is compressed, such as a \texttt{zip} archive or a
  11.432 -JPEG image.  When these types of files are compressed a second time,
  11.433 -the resulting file is usually bigger than the once-compressed form,
  11.434 -and so Mercurial will store the plain \texttt{zip} or JPEG.
  11.435 -
  11.436 -Deltas between revisions of a compressed file are usually larger than
  11.437 -snapshots of the file, and Mercurial again does ``the right thing'' in
  11.438 -these cases.  It finds that such a delta exceeds the threshold at
  11.439 -which it should store a complete snapshot of the file, so it stores
  11.440 -the snapshot, again saving space compared to a naive delta-only
  11.441 -approach.
  11.442 -
  11.443 -\subsubsection{Network recompression}
  11.444 -
  11.445 -When storing revisions on disk, Mercurial uses the ``deflate''
  11.446 -compression algorithm (the same one used by the popular \texttt{zip}
  11.447 -archive format), which balances good speed with a respectable
  11.448 -compression ratio.  However, when transmitting revision data over a
  11.449 -network connection, Mercurial uncompresses the compressed revision
  11.450 -data.
  11.451 -
  11.452 -If the connection is over HTTP, Mercurial recompresses the entire
  11.453 -stream of data using a compression algorithm that gives a better
  11.454 -compression ratio (the Burrows-Wheeler algorithm from the widely used
  11.455 -\texttt{bzip2} compression package).  This combination of algorithm
  11.456 -and compression of the entire stream (instead of a revision at a time)
  11.457 -substantially reduces the number of bytes to be transferred, yielding
  11.458 -better network performance over almost all kinds of network.
  11.459 -
  11.460 -(If the connection is over \command{ssh}, Mercurial \emph{doesn't}
  11.461 -recompress the stream, because \command{ssh} can already do this
  11.462 -itself.)
  11.463 -
  11.464 -\subsection{Read/write ordering and atomicity}
  11.465 -
  11.466 -Appending to files isn't the whole story when it comes to guaranteeing
  11.467 -that a reader won't see a partial write.  If you recall
  11.468 -figure~\ref{fig:concepts:metadata}, revisions in the changelog point to
  11.469 -revisions in the manifest, and revisions in the manifest point to
  11.470 -revisions in filelogs.  This hierarchy is deliberate.
  11.471 -
  11.472 -A writer starts a transaction by writing filelog and manifest data,
  11.473 -and doesn't write any changelog data until those are finished.  A
  11.474 -reader starts by reading changelog data, then manifest data, followed
  11.475 -by filelog data.
  11.476 -
  11.477 -Since the writer has always finished writing filelog and manifest data
  11.478 -before it writes to the changelog, a reader will never read a pointer
  11.479 -to a partially written manifest revision from the changelog, and it will
  11.480 -never read a pointer to a partially written filelog revision from the
  11.481 -manifest.
  11.482 -
  11.483 -\subsection{Concurrent access}
  11.484 -
  11.485 -The read/write ordering and atomicity guarantees mean that Mercurial
  11.486 -never needs to \emph{lock} a repository when it's reading data, even
  11.487 -if the repository is being written to while the read is occurring.
  11.488 -This has a big effect on scalability; you can have an arbitrary number
  11.489 -of Mercurial processes safely reading data from a repository safely
  11.490 -all at once, no matter whether it's being written to or not.
  11.491 -
  11.492 -The lockless nature of reading means that if you're sharing a
  11.493 -repository on a multi-user system, you don't need to grant other local
  11.494 -users permission to \emph{write} to your repository in order for them
  11.495 -to be able to clone it or pull changes from it; they only need
  11.496 -\emph{read} permission.  (This is \emph{not} a common feature among
  11.497 -revision control systems, so don't take it for granted!  Most require
  11.498 -readers to be able to lock a repository to access it safely, and this
  11.499 -requires write permission on at least one directory, which of course
  11.500 -makes for all kinds of nasty and annoying security and administrative
  11.501 -problems.)
  11.502 -
  11.503 -Mercurial uses locks to ensure that only one process can write to a
  11.504 -repository at a time (the locking mechanism is safe even over
  11.505 -filesystems that are notoriously hostile to locking, such as NFS).  If
  11.506 -a repository is locked, a writer will wait for a while to retry if the
  11.507 -repository becomes unlocked, but if the repository remains locked for
  11.508 -too long, the process attempting to write will time out after a while.
  11.509 -This means that your daily automated scripts won't get stuck forever
  11.510 -and pile up if a system crashes unnoticed, for example.  (Yes, the
  11.511 -timeout is configurable, from zero to infinity.)
  11.512 -
  11.513 -\subsubsection{Safe dirstate access}
  11.514 -
  11.515 -As with revision data, Mercurial doesn't take a lock to read the
  11.516 -dirstate file; it does acquire a lock to write it.  To avoid the
  11.517 -possibility of reading a partially written copy of the dirstate file,
  11.518 -Mercurial writes to a file with a unique name in the same directory as
  11.519 -the dirstate file, then renames the temporary file atomically to
  11.520 -\filename{dirstate}.  The file named \filename{dirstate} is thus
  11.521 -guaranteed to be complete, not partially written.
  11.522 -
  11.523 -\subsection{Avoiding seeks}
  11.524 -
  11.525 -Critical to Mercurial's performance is the avoidance of seeks of the
  11.526 -disk head, since any seek is far more expensive than even a
  11.527 -comparatively large read operation.
  11.528 -
  11.529 -This is why, for example, the dirstate is stored in a single file.  If
  11.530 -there were a dirstate file per directory that Mercurial tracked, the
  11.531 -disk would seek once per directory.  Instead, Mercurial reads the
  11.532 -entire single dirstate file in one step.
  11.533 -
  11.534 -Mercurial also uses a ``copy on write'' scheme when cloning a
  11.535 -repository on local storage.  Instead of copying every revlog file
  11.536 -from the old repository into the new repository, it makes a ``hard
  11.537 -link'', which is a shorthand way to say ``these two names point to the
  11.538 -same file''.  When Mercurial is about to write to one of a revlog's
  11.539 -files, it checks to see if the number of names pointing at the file is
  11.540 -greater than one.  If it is, more than one repository is using the
  11.541 -file, so Mercurial makes a new copy of the file that is private to
  11.542 -this repository.
  11.543 -
  11.544 -A few revision control developers have pointed out that this idea of
  11.545 -making a complete private copy of a file is not very efficient in its
  11.546 -use of storage.  While this is true, storage is cheap, and this method
  11.547 -gives the highest performance while deferring most book-keeping to the
  11.548 -operating system.  An alternative scheme would most likely reduce
  11.549 -performance and increase the complexity of the software, each of which
  11.550 -is much more important to the ``feel'' of day-to-day use.
  11.551 -
  11.552 -\subsection{Other contents of the dirstate}
  11.553 -
  11.554 -Because Mercurial doesn't force you to tell it when you're modifying a
  11.555 -file, it uses the dirstate to store some extra information so it can
  11.556 -determine efficiently whether you have modified a file.  For each file
  11.557 -in the working directory, it stores the time that it last modified the
  11.558 -file itself, and the size of the file at that time.  
  11.559 -
  11.560 -When you explicitly \hgcmd{add}, \hgcmd{remove}, \hgcmd{rename} or
  11.561 -\hgcmd{copy} files, Mercurial updates the dirstate so that it knows
  11.562 -what to do with those files when you commit.
  11.563 -
  11.564 -When Mercurial is checking the states of files in the working
  11.565 -directory, it first checks a file's modification time.  If that has
  11.566 -not changed, the file must not have been modified.  If the file's size
  11.567 -has changed, the file must have been modified.  If the modification
  11.568 -time has changed, but the size has not, only then does Mercurial need
  11.569 -to read the actual contents of the file to see if they've changed.
  11.570 -Storing these few extra pieces of information dramatically reduces the
  11.571 -amount of data that Mercurial needs to read, which yields large
  11.572 -performance improvements compared to other revision control systems.
  11.573 -
  11.574 -%%% Local Variables: 
  11.575 -%%% mode: latex
  11.576 -%%% TeX-master: "00book"
  11.577 -%%% End:

    12.1 --- a/en/ch05-daily.tex	Thu Mar 05 21:52:23 2009 +0200
    12.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
    12.3 @@ -1,379 +0,0 @@
    12.4 -\chapter{Mercurial in daily use}
    12.5 -\label{chap:daily}
    12.6 -
    12.7 -\section{Telling Mercurial which files to track}
    12.8 -
    12.9 -Mercurial does not work with files in your repository unless you tell
   12.10 -it to manage them.  The \hgcmd{status} command will tell you which
   12.11 -files Mercurial doesn't know about; it uses a ``\texttt{?}'' to
   12.12 -display such files.
   12.13 -
   12.14 -To tell Mercurial to track a file, use the \hgcmd{add} command.  Once
   12.15 -you have added a file, the entry in the output of \hgcmd{status} for
   12.16 -that file changes from ``\texttt{?}'' to ``\texttt{A}''.
   12.17 -\interaction{daily.files.add}
   12.18 -
   12.19 -After you run a \hgcmd{commit}, the files that you added before the
   12.20 -commit will no longer be listed in the output of \hgcmd{status}.  The
   12.21 -reason for this is that \hgcmd{status} only tells you about
   12.22 -``interesting'' files---those that you have modified or told Mercurial
   12.23 -to do something with---by default.  If you have a repository that
   12.24 -contains thousands of files, you will rarely want to know about files
   12.25 -that Mercurial is tracking, but that have not changed.  (You can still
   12.26 -get this information; we'll return to this later.)
   12.27 -
   12.28 -Once you add a file, Mercurial doesn't do anything with it
   12.29 -immediately.  Instead, it will take a snapshot of the file's state the
   12.30 -next time you perform a commit.  It will then continue to track the
   12.31 -changes you make to the file every time you commit, until you remove
   12.32 -the file.
   12.33 -
   12.34 -\subsection{Explicit versus implicit file naming}
   12.35 -
   12.36 -A useful behaviour that Mercurial has is that if you pass the name of
   12.37 -a directory to a command, every Mercurial command will treat this as
   12.38 -``I want to operate on every file in this directory and its
   12.39 -subdirectories''.
   12.40 -\interaction{daily.files.add-dir}
   12.41 -Notice in this example that Mercurial printed the names of the files
   12.42 -it added, whereas it didn't do so when we added the file named
   12.43 -\filename{a} in the earlier example.
   12.44 -
   12.45 -What's going on is that in the former case, we explicitly named the
   12.46 -file to add on the command line, so the assumption that Mercurial
   12.47 -makes in such cases is that you know what you were doing, and it
   12.48 -doesn't print any output.
   12.49 -
   12.50 -However, when we \emph{imply} the names of files by giving the name of
   12.51 -a directory, Mercurial takes the extra step of printing the name of
   12.52 -each file that it does something with.  This makes it more clear what
   12.53 -is happening, and reduces the likelihood of a silent and nasty
   12.54 -surprise.  This behaviour is common to most Mercurial commands.
   12.55 -
   12.56 -\subsection{Aside: Mercurial tracks files, not directories}
   12.57 -
   12.58 -Mercurial does not track directory information.  Instead, it tracks
   12.59 -the path to a file.  Before creating a file, it first creates any
   12.60 -missing directory components of the path.  After it deletes a file, it
   12.61 -then deletes any empty directories that were in the deleted file's
   12.62 -path.  This sounds like a trivial distinction, but it has one minor
   12.63 -practical consequence: it is not possible to represent a completely
   12.64 -empty directory in Mercurial.
   12.65 -
   12.66 -Empty directories are rarely useful, and there are unintrusive
   12.67 -workarounds that you can use to achieve an appropriate effect.  The
   12.68 -developers of Mercurial thus felt that the complexity that would be
   12.69 -required to manage empty directories was not worth the limited benefit
   12.70 -this feature would bring.
   12.71 -
   12.72 -If you need an empty directory in your repository, there are a few
   12.73 -ways to achieve this. One is to create a directory, then \hgcmd{add} a
   12.74 -``hidden'' file to that directory.  On Unix-like systems, any file
   12.75 -name that begins with a period (``\texttt{.}'') is treated as hidden
   12.76 -by most commands and GUI tools.  This approach is illustrated in
   12.77 -figure~\ref{ex:daily:hidden}.
   12.78 -
   12.79 -\begin{figure}[ht]
   12.80 -  \interaction{daily.files.hidden}
   12.81 -  \caption{Simulating an empty directory using a hidden file}
   12.82 -  \label{ex:daily:hidden}
   12.83 -\end{figure}
   12.84 -
   12.85 -Another way to tackle a need for an empty directory is to simply
   12.86 -create one in your automated build scripts before they will need it.
   12.87 -
   12.88 -\section{How to stop tracking a file}
   12.89 -
   12.90 -Once you decide that a file no longer belongs in your repository, use
   12.91 -the \hgcmd{remove} command; this deletes the file, and tells Mercurial
   12.92 -to stop tracking it.  A removed file is represented in the output of
   12.93 -\hgcmd{status} with a ``\texttt{R}''.
   12.94 -\interaction{daily.files.remove}
   12.95 -
   12.96 -After you \hgcmd{remove} a file, Mercurial will no longer track
   12.97 -changes to that file, even if you recreate a file with the same name
   12.98 -in your working directory.  If you do recreate a file with the same
   12.99 -name and want Mercurial to track the new file, simply \hgcmd{add} it.
  12.100 -Mercurial will know that the newly added file is not related to the
  12.101 -old file of the same name.
  12.102 -
  12.103 -\subsection{Removing a file does not affect its history}
  12.104 -
  12.105 -It is important to understand that removing a file has only two
  12.106 -effects.
  12.107 -\begin{itemize}
  12.108 -\item It removes the current version of the file from the working
  12.109 -  directory.
  12.110 -\item It stops Mercurial from tracking changes to the file, from the
  12.111 -  time of the next commit.
  12.112 -\end{itemize}
  12.113 -Removing a file \emph{does not} in any way alter the \emph{history} of
  12.114 -the file.
  12.115 -
  12.116 -If you update the working directory to a changeset in which a file
  12.117 -that you have removed was still tracked, it will reappear in the
  12.118 -working directory, with the contents it had when you committed that
  12.119 -changeset.  If you then update the working directory to a later
  12.120 -changeset, in which the file had been removed, Mercurial will once
  12.121 -again remove the file from the working directory.
  12.122 -
  12.123 -\subsection{Missing files}
  12.124 -
  12.125 -Mercurial considers a file that you have deleted, but not used
  12.126 -\hgcmd{remove} to delete, to be \emph{missing}.  A missing file is
  12.127 -represented with ``\texttt{!}'' in the output of \hgcmd{status}.
  12.128 -Mercurial commands will not generally do anything with missing files.
  12.129 -\interaction{daily.files.missing}
  12.130 -
  12.131 -If your repository contains a file that \hgcmd{status} reports as
  12.132 -missing, and you want the file to stay gone, you can run
  12.133 -\hgcmdargs{remove}{\hgopt{remove}{--after}} at any time later on, to
  12.134 -tell Mercurial that you really did mean to remove the file.
  12.135 -\interaction{daily.files.remove-after}
  12.136 -
  12.137 -On the other hand, if you deleted the missing file by accident, use
  12.138 -\hgcmdargs{revert}{\emph{filename}} to recover the file.  It will
  12.139 -reappear, in unmodified form.
  12.140 -\interaction{daily.files.recover-missing}
  12.141 -
  12.142 -\subsection{Aside: why tell Mercurial explicitly to remove a file?}
  12.143 -
  12.144 -You might wonder why Mercurial requires you to explicitly tell it that
  12.145 -you are deleting a file.  Early during the development of Mercurial,
  12.146 -it let you delete a file however you pleased; Mercurial would notice
  12.147 -the absence of the file automatically when you next ran a
  12.148 -\hgcmd{commit}, and stop tracking the file.  In practice, this made it
  12.149 -too easy to accidentally remove a file without noticing.
  12.150 -
  12.151 -\subsection{Useful shorthand---adding and removing files in one step}
  12.152 -
  12.153 -Mercurial offers a combination command, \hgcmd{addremove}, that adds
  12.154 -untracked files and marks missing files as removed.  
  12.155 -\interaction{daily.files.addremove}
  12.156 -The \hgcmd{commit} command also provides a \hgopt{commit}{-A} option
  12.157 -that performs this same add-and-remove, immediately followed by a
  12.158 -commit.
  12.159 -\interaction{daily.files.commit-addremove}
  12.160 -
  12.161 -\section{Copying files}
  12.162 -
  12.163 -Mercurial provides a \hgcmd{copy} command that lets you make a new
  12.164 -copy of a file.  When you copy a file using this command, Mercurial
  12.165 -makes a record of the fact that the new file is a copy of the original
  12.166 -file.  It treats these copied files specially when you merge your work
  12.167 -with someone else's.
  12.168 -
  12.169 -\subsection{The results of copying during a merge}
  12.170 -
  12.171 -What happens during a merge is that changes ``follow'' a copy.  To
  12.172 -best illustrate what this means, let's create an example.  We'll start
  12.173 -with the usual tiny repository that contains a single file.
  12.174 -\interaction{daily.copy.init}
  12.175 -We need to do some work in parallel, so that we'll have something to
  12.176 -merge.  So let's clone our repository.
  12.177 -\interaction{daily.copy.clone}
  12.178 -Back in our initial repository, let's use the \hgcmd{copy} command to
  12.179 -make a copy of the first file we created.
  12.180 -\interaction{daily.copy.copy}
  12.181 -
  12.182 -If we look at the output of the \hgcmd{status} command afterwards, the
  12.183 -copied file looks just like a normal added file.
  12.184 -\interaction{daily.copy.status}
  12.185 -But if we pass the \hgopt{status}{-C} option to \hgcmd{status}, it
  12.186 -prints another line of output: this is the file that our newly-added
  12.187 -file was copied \emph{from}.
  12.188 -\interaction{daily.copy.status-copy}
  12.189 -
  12.190 -Now, back in the repository we cloned, let's make a change in
  12.191 -parallel.  We'll add a line of content to the original file that we
  12.192 -created.
  12.193 -\interaction{daily.copy.other}
  12.194 -Now we have a modified \filename{file} in this repository.  When we
  12.195 -pull the changes from the first repository, and merge the two heads,
  12.196 -Mercurial will propagate the changes that we made locally to
  12.197 -\filename{file} into its copy, \filename{new-file}.
  12.198 -\interaction{daily.copy.merge}
  12.199 -
  12.200 -\subsection{Why should changes follow copies?}
  12.201 -\label{sec:daily:why-copy}
  12.202 -
  12.203 -This behaviour, of changes to a file propagating out to copies of the
  12.204 -file, might seem esoteric, but in most cases it's highly desirable.
  12.205 -
  12.206 -First of all, remember that this propagation \emph{only} happens when
  12.207 -you merge.  So if you \hgcmd{copy} a file, and subsequently modify the
  12.208 -original file during the normal course of your work, nothing will
  12.209 -happen.
  12.210 -
  12.211 -The second thing to know is that modifications will only propagate
  12.212 -across a copy as long as the repository that you're pulling changes
  12.213 -from \emph{doesn't know} about the copy.
  12.214 -
  12.215 -The reason that Mercurial does this is as follows.  Let's say I make
  12.216 -an important bug fix in a source file, and commit my changes.
  12.217 -Meanwhile, you've decided to \hgcmd{copy} the file in your repository,
  12.218 -without knowing about the bug or having seen the fix, and you have
  12.219 -started hacking on your copy of the file.
  12.220 -
  12.221 -If you pulled and merged my changes, and Mercurial \emph{didn't}
  12.222 -propagate changes across copies, your source file would now contain
  12.223 -the bug, and unless you remembered to propagate the bug fix by hand,
  12.224 -the bug would \emph{remain} in your copy of the file.
  12.225 -
  12.226 -By automatically propagating the change that fixed the bug from the
  12.227 -original file to the copy, Mercurial prevents this class of problem.
  12.228 -To my knowledge, Mercurial is the \emph{only} revision control system
  12.229 -that propagates changes across copies like this.
  12.230 -
  12.231 -Once your change history has a record that the copy and subsequent
  12.232 -merge occurred, there's usually no further need to propagate changes
  12.233 -from the original file to the copied file, and that's why Mercurial
  12.234 -only propagates changes across copies until this point, and no
  12.235 -further.
  12.236 -
  12.237 -\subsection{How to make changes \emph{not} follow a copy}
  12.238 -
  12.239 -If, for some reason, you decide that this business of automatically
  12.240 -propagating changes across copies is not for you, simply use your
  12.241 -system's normal file copy command (on Unix-like systems, that's
  12.242 -\command{cp}) to make a copy of a file, then \hgcmd{add} the new copy
  12.243 -by hand.  Before you do so, though, please do reread
  12.244 -section~\ref{sec:daily:why-copy}, and make an informed decision that
  12.245 -this behaviour is not appropriate to your specific case.
  12.246 -
  12.247 -\subsection{Behaviour of the \hgcmd{copy} command}
  12.248 -
  12.249 -When you use the \hgcmd{copy} command, Mercurial makes a copy of each
  12.250 -source file as it currently stands in the working directory.  This
  12.251 -means that if you make some modifications to a file, then \hgcmd{copy}
  12.252 -it without first having committed those changes, the new copy will
  12.253 -also contain the modifications you have made up until that point.  (I
  12.254 -find this behaviour a little counterintuitive, which is why I mention
  12.255 -it here.)
  12.256 -
  12.257 -The \hgcmd{copy} command acts similarly to the Unix \command{cp}
  12.258 -command (you can use the \hgcmd{cp} alias if you prefer).  The last
  12.259 -argument is the \emph{destination}, and all prior arguments are
  12.260 -\emph{sources}.  If you pass it a single file as the source, and the
  12.261 -destination does not exist, it creates a new file with that name.
  12.262 -\interaction{daily.copy.simple}
  12.263 -If the destination is a directory, Mercurial copies its sources into
  12.264 -that directory.
  12.265 -\interaction{daily.copy.dir-dest}
  12.266 -Copying a directory is recursive, and preserves the directory
  12.267 -structure of the source.
  12.268 -\interaction{daily.copy.dir-src}
  12.269 -If the source and destination are both directories, the source tree is
  12.270 -recreated in the destination directory.
  12.271 -\interaction{daily.copy.dir-src-dest}
  12.272 -
  12.273 -As with the \hgcmd{rename} command, if you copy a file manually and
  12.274 -then want Mercurial to know that you've copied the file, simply use
  12.275 -the \hgopt{copy}{--after} option to \hgcmd{copy}.
  12.276 -\interaction{daily.copy.after}
  12.277 -
  12.278 -\section{Renaming files}
  12.279 -
  12.280 -It's rather more common to need to rename a file than to make a copy
  12.281 -of it.  The reason I discussed the \hgcmd{copy} command before talking
  12.282 -about renaming files is that Mercurial treats a rename in essentially
  12.283 -the same way as a copy.  Therefore, knowing what Mercurial does when
  12.284 -you copy a file tells you what to expect when you rename a file.
  12.285 -
  12.286 -When you use the \hgcmd{rename} command, Mercurial makes a copy of
  12.287 -each source file, then deletes it and marks the file as removed.
  12.288 -\interaction{daily.rename.rename}
  12.289 -The \hgcmd{status} command shows the newly copied file as added, and
  12.290 -the copied-from file as removed.
  12.291 -\interaction{daily.rename.status}
  12.292 -As with the results of a \hgcmd{copy}, we must use the
  12.293 -\hgopt{status}{-C} option to \hgcmd{status} to see that the added file
  12.294 -is really being tracked by Mercurial as a copy of the original, now
  12.295 -removed, file.
  12.296 -\interaction{daily.rename.status-copy}
  12.297 -
  12.298 -As with \hgcmd{remove} and \hgcmd{copy}, you can tell Mercurial about
  12.299 -a rename after the fact using the \hgopt{rename}{--after} option.  In
  12.300 -most other respects, the behaviour of the \hgcmd{rename} command, and
  12.301 -the options it accepts, are similar to the \hgcmd{copy} command.
  12.302 -
  12.303 -\subsection{Renaming files and merging changes}
  12.304 -
  12.305 -Since Mercurial's rename is implemented as copy-and-remove, the same
  12.306 -propagation of changes happens when you merge after a rename as after
  12.307 -a copy.
  12.308 -
  12.309 -If I modify a file, and you rename it to a new name, and then we merge
  12.310 -our respective changes, my modifications to the file under its
  12.311 -original name will be propagated into the file under its new name.
  12.312 -(This is something you might expect to ``simply work,'' but not all
  12.313 -revision control systems actually do this.)
  12.314 -
  12.315 -Whereas having changes follow a copy is a feature where you can
  12.316 -perhaps nod and say ``yes, that might be useful,'' it should be clear
  12.317 -that having them follow a rename is definitely important.  Without
  12.318 -this facility, it would simply be too easy for changes to become
  12.319 -orphaned when files are renamed.
  12.320 -
  12.321 -\subsection{Divergent renames and merging}
  12.322 -
  12.323 -The case of diverging names occurs when two developers start with a
  12.324 -file---let's call it \filename{foo}---in their respective
  12.325 -repositories.
  12.326 -
  12.327 -\interaction{rename.divergent.clone}
  12.328 -Anne renames the file to \filename{bar}.
  12.329 -\interaction{rename.divergent.rename.anne}
  12.330 -Meanwhile, Bob renames it to \filename{quux}.
  12.331 -\interaction{rename.divergent.rename.bob}
  12.332 -
  12.333 -I like to think of this as a conflict because each developer has
  12.334 -expressed different intentions about what the file ought to be named.
  12.335 -
  12.336 -What do you think should happen when they merge their work?
  12.337 -Mercurial's actual behaviour is that it always preserves \emph{both}
  12.338 -names when it merges changesets that contain divergent renames.
  12.339 -\interaction{rename.divergent.merge}
  12.340 -
  12.341 -Notice that Mercurial does warn about the divergent renames, but it
  12.342 -leaves it up to you to do something about the divergence after the merge.
  12.343 -
  12.344 -\subsection{Convergent renames and merging}
  12.345 -
  12.346 -Another kind of rename conflict occurs when two people choose to
  12.347 -rename different \emph{source} files to the same \emph{destination}.
  12.348 -In this case, Mercurial runs its normal merge machinery, and lets you
  12.349 -guide it to a suitable resolution.
  12.350 -
  12.351 -\subsection{Other name-related corner cases}
  12.352 -
  12.353 -Mercurial has a longstanding bug in which it fails to handle a merge
  12.354 -where one side has a file with a given name, while another has a
  12.355 -directory with the same name.  This is documented as~\bug{29}.
  12.356 -\interaction{issue29.go}
  12.357 -
  12.358 -\section{Recovering from mistakes}
  12.359 -
  12.360 -Mercurial has some useful commands that will help you to recover from
  12.361 -some common mistakes.
  12.362 -
  12.363 -The \hgcmd{revert} command lets you undo changes that you have made to
  12.364 -your working directory.  For example, if you \hgcmd{add} a file by
  12.365 -accident, just run \hgcmd{revert} with the name of the file you added,
  12.366 -and while the file won't be touched in any way, it won't be tracked
  12.367 -for adding by Mercurial any longer, either.  You can also use
  12.368 -\hgcmd{revert} to get rid of erroneous changes to a file.
  12.369 -
  12.370 -It's useful to remember that the \hgcmd{revert} command is useful for
  12.371 -changes that you have not yet committed.  Once you've committed a
  12.372 -change, if you decide it was a mistake, you can still do something
  12.373 -about it, though your options may be more limited.
  12.374 -
  12.375 -For more information about the \hgcmd{revert} command, and details
  12.376 -about how to deal with changes you have already committed, see
  12.377 -chapter~\ref{chap:undo}.
  12.378 -
  12.379 -%%% Local Variables: 
  12.380 -%%% mode: latex
  12.381 -%%% TeX-master: "00book"
  12.382 -%%% End: 

    13.1 --- a/en/ch06-collab.tex	Thu Mar 05 21:52:23 2009 +0200
    13.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
    13.3 @@ -1,1117 +0,0 @@
    13.4 -\chapter{Collaborating with other people}
    13.5 -\label{cha:collab}
    13.6 -
    13.7 -As a completely decentralised tool, Mercurial doesn't impose any
    13.8 -policy on how people ought to work with each other.  However, if
    13.9 -you're new to distributed revision control, it helps to have some
   13.10 -tools and examples in mind when you're thinking about possible
   13.11 -workflow models.
   13.12 -
   13.13 -\section{Mercurial's web interface}
   13.14 -
   13.15 -Mercurial has a powerful web interface that provides several 
   13.16 -useful capabilities.
   13.17 -
   13.18 -For interactive use, the web interface lets you browse a single
   13.19 -repository or a collection of repositories.  You can view the history
   13.20 -of a repository, examine each change (comments and diffs), and view
   13.21 -the contents of each directory and file.
   13.22 -
   13.23 -Also for human consumption, the web interface provides an RSS feed of
   13.24 -the changes in a repository.  This lets you ``subscribe'' to a
   13.25 -repository using your favourite feed reader, and be automatically
   13.26 -notified of activity in that repository as soon as it happens.  I find
   13.27 -this capability much more convenient than the model of subscribing to
   13.28 -a mailing list to which notifications are sent, as it requires no
   13.29 -additional configuration on the part of whoever is serving the
   13.30 -repository.
   13.31 -
   13.32 -The web interface also lets remote users clone a repository, pull
   13.33 -changes from it, and (when the server is configured to permit it) push
   13.34 -changes back to it.  Mercurial's HTTP tunneling protocol aggressively
   13.35 -compresses data, so that it works efficiently even over low-bandwidth
   13.36 -network connections.
   13.37 -
   13.38 -The easiest way to get started with the web interface is to use your
   13.39 -web browser to visit an existing repository, such as the master
   13.40 -Mercurial repository at
   13.41 -\url{http://www.selenic.com/repo/hg?style=gitweb}.
   13.42 -
   13.43 -If you're interested in providing a web interface to your own
   13.44 -repositories, Mercurial provides two ways to do this.  The first is
   13.45 -using the \hgcmd{serve} command, which is best suited to short-term
   13.46 -``lightweight'' serving.  See section~\ref{sec:collab:serve} below for
   13.47 -details of how to use this command.  If you have a long-lived
   13.48 -repository that you'd like to make permanently available, Mercurial
   13.49 -has built-in support for the CGI (Common Gateway Interface) standard,
   13.50 -which all common web servers support.  See
   13.51 -section~\ref{sec:collab:cgi} for details of CGI configuration.
   13.52 -
   13.53 -\section{Collaboration models}
   13.54 -
   13.55 -With a suitably flexible tool, making decisions about workflow is much
   13.56 -more of a social engineering challenge than a technical one.
   13.57 -Mercurial imposes few limitations on how you can structure the flow of
   13.58 -work in a project, so it's up to you and your group to set up and live
   13.59 -with a model that matches your own particular needs.
   13.60 -
   13.61 -\subsection{Factors to keep in mind}
   13.62 -
   13.63 -The most important aspect of any model that you must keep in mind is
   13.64 -how well it matches the needs and capabilities of the people who will
   13.65 -be using it.  This might seem self-evident; even so, you still can't
   13.66 -afford to forget it for a moment.
   13.67 -
   13.68 -I once put together a workflow model that seemed to make perfect sense
   13.69 -to me, but that caused a considerable amount of consternation and
   13.70 -strife within my development team.  In spite of my attempts to explain
   13.71 -why we needed a complex set of branches, and how changes ought to flow
   13.72 -between them, a few team members revolted.  Even though they were
   13.73 -smart people, they didn't want to pay attention to the constraints we
   13.74 -were operating under, or face the consequences of those constraints in
   13.75 -the details of the model that I was advocating.
   13.76 -
   13.77 -Don't sweep foreseeable social or technical problems under the rug.
   13.78 -Whatever scheme you put into effect, you should plan for mistakes and
   13.79 -problem scenarios.  Consider adding automated machinery to prevent, or
   13.80 -quickly recover from, trouble that you can anticipate.  As an example,
   13.81 -if you intend to have a branch with not-for-release changes in it,
   13.82 -you'd do well to think early about the possibility that someone might
   13.83 -accidentally merge those changes into a release branch.  You could
   13.84 -avoid this particular problem by writing a hook that prevents changes
   13.85 -from being merged from an inappropriate branch.
   13.86 -
   13.87 -\subsection{Informal anarchy}
   13.88 -
   13.89 -I wouldn't suggest an ``anything goes'' approach as something
   13.90 -sustainable, but it's a model that's easy to grasp, and it works
   13.91 -perfectly well in a few unusual situations.
   13.92 -
   13.93 -As one example, many projects have a loose-knit group of collaborators
   13.94 -who rarely physically meet each other.  Some groups like to overcome
   13.95 -the isolation of working at a distance by organising occasional
   13.96 -``sprints''.  In a sprint, a number of people get together in a single
   13.97 -location (a company's conference room, a hotel meeting room, that kind
   13.98 -of place) and spend several days more or less locked in there, hacking
   13.99 -intensely on a handful of projects.
  13.100 -
  13.101 -A sprint is the perfect place to use the \hgcmd{serve} command, since
  13.102 -\hgcmd{serve} does not require any fancy server infrastructure.  You
  13.103 -can get started with \hgcmd{serve} in moments, by reading
  13.104 -section~\ref{sec:collab:serve} below.  Then simply tell the person
  13.105 -next to you that you're running a server, send the URL to them in an
  13.106 -instant message, and you immediately have a quick-turnaround way to
  13.107 -work together.  They can type your URL into their web browser and
  13.108 -quickly review your changes; or they can pull a bugfix from you and
  13.109 -verify it; or they can clone a branch containing a new feature and try
  13.110 -it out.
  13.111 -
  13.112 -The charm, and the problem, with doing things in an ad hoc fashion
  13.113 -like this is that only people who know about your changes, and where
  13.114 -they are, can see them.  Such an informal approach simply doesn't
  13.115 -scale beyond a handful people, because each individual needs to know
  13.116 -about $n$ different repositories to pull from.
  13.117 -
  13.118 -\subsection{A single central repository}
  13.119 -
  13.120 -For smaller projects migrating from a centralised revision control
  13.121 -tool, perhaps the easiest way to get started is to have changes flow
  13.122 -through a single shared central repository.  This is also the
  13.123 -most common ``building block'' for more ambitious workflow schemes.
  13.124 -
  13.125 -Contributors start by cloning a copy of this repository.  They can
  13.126 -pull changes from it whenever they need to, and some (perhaps all)
  13.127 -developers have permission to push a change back when they're ready
  13.128 -for other people to see it.
  13.129 -
  13.130 -Under this model, it can still often make sense for people to pull
  13.131 -changes directly from each other, without going through the central
  13.132 -repository.  Consider a case in which I have a tentative bug fix, but
  13.133 -I am worried that if I were to publish it to the central repository,
  13.134 -it might subsequently break everyone else's trees as they pull it.  To
  13.135 -reduce the potential for damage, I can ask you to clone my repository
  13.136 -into a temporary repository of your own and test it.  This lets us put
  13.137 -off publishing the potentially unsafe change until it has had a little
  13.138 -testing.
  13.139 -
  13.140 -In this kind of scenario, people usually use the \command{ssh}
  13.141 -protocol to securely push changes to the central repository, as
  13.142 -documented in section~\ref{sec:collab:ssh}.  It's also usual to
  13.143 -publish a read-only copy of the repository over HTTP using CGI, as in
  13.144 -section~\ref{sec:collab:cgi}.  Publishing over HTTP satisfies the
  13.145 -needs of people who don't have push access, and those who want to use
  13.146 -web browsers to browse the repository's history.
  13.147 -
  13.148 -\subsection{Working with multiple branches}
  13.149 -
  13.150 -Projects of any significant size naturally tend to make progress on
  13.151 -several fronts simultaneously.  In the case of software, it's common
  13.152 -for a project to go through periodic official releases.  A release
  13.153 -might then go into ``maintenance mode'' for a while after its first
  13.154 -publication; maintenance releases tend to contain only bug fixes, not
  13.155 -new features.  In parallel with these maintenance releases, one or
  13.156 -more future releases may be under development.  People normally use
  13.157 -the word ``branch'' to refer to one of these many slightly different
  13.158 -directions in which development is proceeding.
  13.159 -
  13.160 -Mercurial is particularly well suited to managing a number of
  13.161 -simultaneous, but not identical, branches.  Each ``development
  13.162 -direction'' can live in its own central repository, and you can merge
  13.163 -changes from one to another as the need arises.  Because repositories
  13.164 -are independent of each other, unstable changes in a development
  13.165 -branch will never affect a stable branch unless someone explicitly
  13.166 -merges those changes in.
  13.167 -
  13.168 -Here's an example of how this can work in practice.  Let's say you
  13.169 -have one ``main branch'' on a central server.
  13.170 -\interaction{branching.init}
  13.171 -People clone it, make changes locally, test them, and push them back.
  13.172 -
  13.173 -Once the main branch reaches a release milestone, you can use the
  13.174 -\hgcmd{tag} command to give a permanent name to the milestone
  13.175 -revision.
  13.176 -\interaction{branching.tag}
  13.177 -Let's say some ongoing development occurs on the main branch.
  13.178 -\interaction{branching.main}
  13.179 -Using the tag that was recorded at the milestone, people who clone
  13.180 -that repository at any time in the future can use \hgcmd{update} to
  13.181 -get a copy of the working directory exactly as it was when that tagged
  13.182 -revision was committed.  
  13.183 -\interaction{branching.update}
  13.184 -
  13.185 -In addition, immediately after the main branch is tagged, someone can
  13.186 -then clone the main branch on the server to a new ``stable'' branch,
  13.187 -also on the server.
  13.188 -\interaction{branching.clone}
  13.189 -
  13.190 -Someone who needs to make a change to the stable branch can then clone
  13.191 -\emph{that} repository, make their changes, commit, and push their
  13.192 -changes back there.
  13.193 -\interaction{branching.stable}
  13.194 -Because Mercurial repositories are independent, and Mercurial doesn't
  13.195 -move changes around automatically, the stable and main branches are
  13.196 -\emph{isolated} from each other.  The changes that you made on the
  13.197 -main branch don't ``leak'' to the stable branch, and vice versa.
  13.198 -
  13.199 -You'll often want all of your bugfixes on the stable branch to show up
  13.200 -on the main branch, too.  Rather than rewrite a bugfix on the main
  13.201 -branch, you can simply pull and merge changes from the stable to the
  13.202 -main branch, and Mercurial will bring those bugfixes in for you.
  13.203 -\interaction{branching.merge}
  13.204 -The main branch will still contain changes that are not on the stable
  13.205 -branch, but it will also contain all of the bugfixes from the stable
  13.206 -branch.  The stable branch remains unaffected by these changes.
  13.207 -
  13.208 -\subsection{Feature branches}
  13.209 -
  13.210 -For larger projects, an effective way to manage change is to break up
  13.211 -a team into smaller groups.  Each group has a shared branch of its
  13.212 -own, cloned from a single ``master'' branch used by the entire
  13.213 -project.  People working on an individual branch are typically quite
  13.214 -isolated from developments on other branches.
  13.215 -
  13.216 -\begin{figure}[ht]
  13.217 -  \centering
  13.218 -  \grafix{feature-branches}
  13.219 -  \caption{Feature branches}
  13.220 -  \label{fig:collab:feature-branches}
  13.221 -\end{figure}
  13.222 -
  13.223 -When a particular feature is deemed to be in suitable shape, someone
  13.224 -on that feature team pulls and merges from the master branch into the
  13.225 -feature branch, then pushes back up to the master branch.
  13.226 -
  13.227 -\subsection{The release train}
  13.228 -
  13.229 -Some projects are organised on a ``train'' basis: a release is
  13.230 -scheduled to happen every few months, and whatever features are ready
  13.231 -when the ``train'' is ready to leave are allowed in.
  13.232 -
  13.233 -This model resembles working with feature branches.  The difference is
  13.234 -that when a feature branch misses a train, someone on the feature team
  13.235 -pulls and merges the changes that went out on that train release into
  13.236 -the feature branch, and the team continues its work on top of that
  13.237 -release so that their feature can make the next release.
  13.238 -
  13.239 -\subsection{The Linux kernel model}
  13.240 -
  13.241 -The development of the Linux kernel has a shallow hierarchical
  13.242 -structure, surrounded by a cloud of apparent chaos.  Because most
  13.243 -Linux developers use \command{git}, a distributed revision control
  13.244 -tool with capabilities similar to Mercurial, it's useful to describe
  13.245 -the way work flows in that environment; if you like the ideas, the
  13.246 -approach translates well across tools.
  13.247 -
  13.248 -At the center of the community sits Linus Torvalds, the creator of
  13.249 -Linux.  He publishes a single source repository that is considered the
  13.250 -``authoritative'' current tree by the entire developer community.
  13.251 -Anyone can clone Linus's tree, but he is very choosy about whose trees
  13.252 -he pulls from.
  13.253 -
  13.254 -Linus has a number of ``trusted lieutenants''.  As a general rule, he
  13.255 -pulls whatever changes they publish, in most cases without even
  13.256 -reviewing those changes.  Some of those lieutenants are generally
  13.257 -agreed to be ``maintainers'', responsible for specific subsystems
  13.258 -within the kernel.  If a random kernel hacker wants to make a change
  13.259 -to a subsystem that they want to end up in Linus's tree, they must
  13.260 -find out who the subsystem's maintainer is, and ask that maintainer to
  13.261 -take their change.  If the maintainer reviews their changes and agrees
  13.262 -to take them, they'll pass them along to Linus in due course.
  13.263 -
  13.264 -Individual lieutenants have their own approaches to reviewing,
  13.265 -accepting, and publishing changes; and for deciding when to feed them
  13.266 -to Linus.  In addition, there are several well known branches that
  13.267 -people use for different purposes.  For example, a few people maintain
  13.268 -``stable'' repositories of older versions of the kernel, to which they
  13.269 -apply critical fixes as needed.  Some maintainers publish multiple
  13.270 -trees: one for experimental changes; one for changes that they are
  13.271 -about to feed upstream; and so on.  Others just publish a single
  13.272 -tree.
  13.273 -
  13.274 -This model has two notable features.  The first is that it's ``pull
  13.275 -only''.  You have to ask, convince, or beg another developer to take a
  13.276 -change from you, because there are almost no trees to which more than
  13.277 -one person can push, and there's no way to push changes into a tree
  13.278 -that someone else controls.
  13.279 -
  13.280 -The second is that it's based on reputation and acclaim.  If you're an
  13.281 -unknown, Linus will probably ignore changes from you without even
  13.282 -responding.  But a subsystem maintainer will probably review them, and
  13.283 -will likely take them if they pass their criteria for suitability.
  13.284 -The more ``good'' changes you contribute to a maintainer, the more
  13.285 -likely they are to trust your judgment and accept your changes.  If
  13.286 -you're well-known and maintain a long-lived branch for something Linus
  13.287 -hasn't yet accepted, people with similar interests may pull your
  13.288 -changes regularly to keep up with your work.
  13.289 -
  13.290 -Reputation and acclaim don't necessarily cross subsystem or ``people''
  13.291 -boundaries.  If you're a respected but specialised storage hacker, and
  13.292 -you try to fix a networking bug, that change will receive a level of
  13.293 -scrutiny from a network maintainer comparable to a change from a
  13.294 -complete stranger.
  13.295 -
  13.296 -To people who come from more orderly project backgrounds, the
  13.297 -comparatively chaotic Linux kernel development process often seems
  13.298 -completely insane.  It's subject to the whims of individuals; people
  13.299 -make sweeping changes whenever they deem it appropriate; and the pace
  13.300 -of development is astounding.  And yet Linux is a highly successful,
  13.301 -well-regarded piece of software.
  13.302 -
  13.303 -\subsection{Pull-only versus shared-push collaboration}
  13.304 -
  13.305 -A perpetual source of heat in the open source community is whether a
  13.306 -development model in which people only ever pull changes from others
  13.307 -is ``better than'' one in which multiple people can push changes to a
  13.308 -shared repository.
  13.309 -
  13.310 -Typically, the backers of the shared-push model use tools that
  13.311 -actively enforce this approach.  If you're using a centralised
  13.312 -revision control tool such as Subversion, there's no way to make a
  13.313 -choice over which model you'll use: the tool gives you shared-push,
  13.314 -and if you want to do anything else, you'll have to roll your own
  13.315 -approach on top (such as applying a patch by hand).
  13.316 -
  13.317 -A good distributed revision control tool, such as Mercurial, will
  13.318 -support both models.  You and your collaborators can then structure
  13.319 -how you work together based on your own needs and preferences, not on
  13.320 -what contortions your tools force you into.
  13.321 -
  13.322 -\subsection{Where collaboration meets branch management}
  13.323 -
  13.324 -Once you and your team set up some shared repositories and start
  13.325 -propagating changes back and forth between local and shared repos, you
  13.326 -begin to face a related, but slightly different challenge: that of
  13.327 -managing the multiple directions in which your team may be moving at
  13.328 -once.  Even though this subject is intimately related to how your team
  13.329 -collaborates, it's dense enough to merit treatment of its own, in
  13.330 -chapter~\ref{chap:branch}.
  13.331 -
  13.332 -\section{The technical side of sharing}
  13.333 -
  13.334 -The remainder of this chapter is devoted to the question of serving
  13.335 -data to your collaborators.
  13.336 -
  13.337 -\section{Informal sharing with \hgcmd{serve}}
  13.338 -\label{sec:collab:serve}
  13.339 -
  13.340 -Mercurial's \hgcmd{serve} command is wonderfully suited to small,
  13.341 -tight-knit, and fast-paced group environments.  It also provides a
  13.342 -great way to get a feel for using Mercurial commands over a network.
  13.343 -
  13.344 -Run \hgcmd{serve} inside a repository, and in under a second it will
  13.345 -bring up a specialised HTTP server; this will accept connections from
  13.346 -any client, and serve up data for that repository until you terminate
  13.347 -it.  Anyone who knows the URL of the server you just started, and can
  13.348 -talk to your computer over the network, can then use a web browser or
  13.349 -Mercurial to read data from that repository.  A URL for a
  13.350 -\hgcmd{serve} instance running on a laptop is likely to look something
  13.351 -like \Verb|http://my-laptop.local:8000/|.
  13.352 -
  13.353 -The \hgcmd{serve} command is \emph{not} a general-purpose web server.
  13.354 -It can do only two things:
  13.355 -\begin{itemize}
  13.356 -\item Allow people to browse the history of the repository it's
  13.357 -  serving, from their normal web browsers.
  13.358 -\item Speak Mercurial's wire protocol, so that people can
  13.359 -  \hgcmd{clone} or \hgcmd{pull} changes from that repository.
  13.360 -\end{itemize}
  13.361 -In particular, \hgcmd{serve} won't allow remote users to \emph{modify}
  13.362 -your repository.  It's intended for read-only use.
  13.363 -
  13.364 -If you're getting started with Mercurial, there's nothing to prevent
  13.365 -you from using \hgcmd{serve} to serve up a repository on your own
  13.366 -computer, then use commands like \hgcmd{clone}, \hgcmd{incoming}, and
  13.367 -so on to talk to that server as if the repository was hosted remotely.
  13.368 -This can help you to quickly get acquainted with using commands on
  13.369 -network-hosted repositories.
  13.370 -
  13.371 -\subsection{A few things to keep in mind}
  13.372 -
  13.373 -Because it provides unauthenticated read access to all clients, you
  13.374 -should only use \hgcmd{serve} in an environment where you either don't
  13.375 -care, or have complete control over, who can access your network and
  13.376 -pull data from your repository.
  13.377 -
  13.378 -The \hgcmd{serve} command knows nothing about any firewall software
  13.379 -you might have installed on your system or network.  It cannot detect
  13.380 -or control your firewall software.  If other people are unable to talk
  13.381 -to a running \hgcmd{serve} instance, the second thing you should do
  13.382 -(\emph{after} you make sure that they're using the correct URL) is
  13.383 -check your firewall configuration.
  13.384 -
  13.385 -By default, \hgcmd{serve} listens for incoming connections on
  13.386 -port~8000.  If another process is already listening on the port you
  13.387 -want to use, you can specify a different port to listen on using the
  13.388 -\hgopt{serve}{-p} option.
  13.389 -
  13.390 -Normally, when \hgcmd{serve} starts, it prints no output, which can be
  13.391 -a bit unnerving.  If you'd like to confirm that it is indeed running
  13.392 -correctly, and find out what URL you should send to your
  13.393 -collaborators, start it with the \hggopt{-v} option.
  13.394 -
  13.395 -\section{Using the Secure Shell (ssh) protocol}
  13.396 -\label{sec:collab:ssh}
  13.397 -
  13.398 -You can pull and push changes securely over a network connection using
  13.399 -the Secure Shell (\texttt{ssh}) protocol.  To use this successfully,
  13.400 -you may have to do a little bit of configuration on the client or
  13.401 -server sides.
  13.402 -
  13.403 -If you're not familiar with ssh, it's a network protocol that lets you
  13.404 -securely communicate with another computer.  To use it with Mercurial,
  13.405 -you'll be setting up one or more user accounts on a server so that
  13.406 -remote users can log in and execute commands.
  13.407 -
  13.408 -(If you \emph{are} familiar with ssh, you'll probably find some of the
  13.409 -material that follows to be elementary in nature.)
  13.410 -
  13.411 -\subsection{How to read and write ssh URLs}
  13.412 -
  13.413 -An ssh URL tends to look like this:
  13.414 -\begin{codesample2}
  13.415 -  ssh://bos@hg.serpentine.com:22/hg/hgbook
  13.416 -\end{codesample2}
  13.417 -\begin{enumerate}
  13.418 -\item The ``\texttt{ssh://}'' part tells Mercurial to use the ssh
  13.419 -  protocol.
  13.420 -\item The ``\texttt{bos@}'' component indicates what username to log
  13.421 -  into the server as.  You can leave this out if the remote username
  13.422 -  is the same as your local username.
  13.423 -\item The ``\texttt{hg.serpentine.com}'' gives the hostname of the
  13.424 -  server to log into.
  13.425 -\item The ``:22'' identifies the port number to connect to the server
  13.426 -  on.  The default port is~22, so you only need to specify this part
  13.427 -  if you're \emph{not} using port~22.
  13.428 -\item The remainder of the URL is the local path to the repository on
  13.429 -  the server.
  13.430 -\end{enumerate}
  13.431 -
  13.432 -There's plenty of scope for confusion with the path component of ssh
  13.433 -URLs, as there is no standard way for tools to interpret it.  Some
  13.434 -programs behave differently than others when dealing with these paths.
  13.435 -This isn't an ideal situation, but it's unlikely to change.  Please
  13.436 -read the following paragraphs carefully.
  13.437 -
  13.438 -Mercurial treats the path to a repository on the server as relative to
  13.439 -the remote user's home directory.  For example, if user \texttt{foo}
  13.440 -on the server has a home directory of \dirname{/home/foo}, then an ssh
  13.441 -URL that contains a path component of \dirname{bar}
  13.442 -\emph{really} refers to the directory \dirname{/home/foo/bar}.
  13.443 -
  13.444 -If you want to specify a path relative to another user's home
  13.445 -directory, you can use a path that starts with a tilde character
  13.446 -followed by the user's name (let's call them \texttt{otheruser}), like
  13.447 -this.
  13.448 -\begin{codesample2}
  13.449 -  ssh://server/~otheruser/hg/repo
  13.450 -\end{codesample2}
  13.451 -
  13.452 -And if you really want to specify an \emph{absolute} path on the
  13.453 -server, begin the path component with two slashes, as in this example.
  13.454 -\begin{codesample2}
  13.455 -  ssh://server//absolute/path
  13.456 -\end{codesample2}
  13.457 -
  13.458 -\subsection{Finding an ssh client for your system}
  13.459 -
  13.460 -Almost every Unix-like system comes with OpenSSH preinstalled.  If
  13.461 -you're using such a system, run \Verb|which ssh| to find out if
  13.462 -the \command{ssh} command is installed (it's usually in
  13.463 -\dirname{/usr/bin}).  In the unlikely event that it isn't present,
  13.464 -take a look at your system documentation to figure out how to install
  13.465 -it.
  13.466 -
  13.467 -On Windows, you'll first need to download a suitable ssh
  13.468 -client.  There are two alternatives.
  13.469 -\begin{itemize}
  13.470 -\item Simon Tatham's excellent PuTTY package~\cite{web:putty} provides
  13.471 -  a complete suite of ssh client commands.
  13.472 -\item If you have a high tolerance for pain, you can use the Cygwin
  13.473 -  port of OpenSSH.
  13.474 -\end{itemize}
  13.475 -In either case, you'll need to edit your \hgini\ file to tell
  13.476 -Mercurial where to find the actual client command.  For example, if
  13.477 -you're using PuTTY, you'll need to use the \command{plink} command as
  13.478 -a command-line ssh client.
  13.479 -\begin{codesample2}
  13.480 -  [ui]
  13.481 -  ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"
  13.482 -\end{codesample2}
  13.483 -
  13.484 -\begin{note}
  13.485 -  The path to \command{plink} shouldn't contain any whitespace
  13.486 -  characters, or Mercurial may not be able to run it correctly (so
  13.487 -  putting it in \dirname{C:\\Program Files} is probably not a good
  13.488 -  idea).
  13.489 -\end{note}
  13.490 -
  13.491 -\subsection{Generating a key pair}
  13.492 -
  13.493 -To avoid the need to repetitively type a password every time you need
  13.494 -to use your ssh client, I recommend generating a key pair.  On a
  13.495 -Unix-like system, the \command{ssh-keygen} command will do the trick.
  13.496 -On Windows, if you're using PuTTY, the \command{puttygen} command is
  13.497 -what you'll need.
  13.498 -
  13.499 -When you generate a key pair, it's usually \emph{highly} advisable to
  13.500 -protect it with a passphrase.  (The only time that you might not want
  13.501 -to do this is when you're using the ssh protocol for automated tasks
  13.502 -on a secure network.)
  13.503 -
  13.504 -Simply generating a key pair isn't enough, however.  You'll need to
  13.505 -add the public key to the set of authorised keys for whatever user
  13.506 -you're logging in remotely as.  For servers using OpenSSH (the vast
  13.507 -majority), this will mean adding the public key to a list in a file
  13.508 -called \sfilename{authorized\_keys} in their \sdirname{.ssh}
  13.509 -directory.
  13.510 -
  13.511 -On a Unix-like system, your public key will have a \filename{.pub}
  13.512 -extension.  If you're using \command{puttygen} on Windows, you can
  13.513 -save the public key to a file of your choosing, or paste it from the
  13.514 -window it's displayed in straight into the
  13.515 -\sfilename{authorized\_keys} file.
  13.516 -
  13.517 -\subsection{Using an authentication agent}
  13.518 -
  13.519 -An authentication agent is a daemon that stores passphrases in memory
  13.520 -(so it will forget passphrases if you log out and log back in again).
  13.521 -An ssh client will notice if it's running, and query it for a
  13.522 -passphrase.  If there's no authentication agent running, or the agent
  13.523 -doesn't store the necessary passphrase, you'll have to type your
  13.524 -passphrase every time Mercurial tries to communicate with a server on
  13.525 -your behalf (e.g.~whenever you pull or push changes).
  13.526 -
  13.527 -The downside of storing passphrases in an agent is that it's possible
  13.528 -for a well-prepared attacker to recover the plain text of your
  13.529 -passphrases, in some cases even if your system has been power-cycled.
  13.530 -You should make your own judgment as to whether this is an acceptable
  13.531 -risk.  It certainly saves a lot of repeated typing.
  13.532 -
  13.533 -On Unix-like systems, the agent is called \command{ssh-agent}, and
  13.534 -it's often run automatically for you when you log in.  You'll need to
  13.535 -use the \command{ssh-add} command to add passphrases to the agent's
  13.536 -store.  On Windows, if you're using PuTTY, the \command{pageant}
  13.537 -command acts as the agent.  It adds an icon to your system tray that
  13.538 -will let you manage stored passphrases.
  13.539 -
  13.540 -\subsection{Configuring the server side properly}
  13.541 -
  13.542 -Because ssh can be fiddly to set up if you're new to it, there's a
  13.543 -variety of things that can go wrong.  Add Mercurial on top, and
  13.544 -there's plenty more scope for head-scratching.  Most of these
  13.545 -potential problems occur on the server side, not the client side.  The
  13.546 -good news is that once you've gotten a configuration working, it will
  13.547 -usually continue to work indefinitely.
  13.548 -
  13.549 -Before you try using Mercurial to talk to an ssh server, it's best to
  13.550 -make sure that you can use the normal \command{ssh} or \command{putty}
  13.551 -command to talk to the server first.  If you run into problems with
  13.552 -using these commands directly, Mercurial surely won't work.  Worse, it
  13.553 -will obscure the underlying problem.  Any time you want to debug
  13.554 -ssh-related Mercurial problems, you should drop back to making sure
  13.555 -that plain ssh client commands work first, \emph{before} you worry
  13.556 -about whether there's a problem with Mercurial.
  13.557 -
  13.558 -The first thing to be sure of on the server side is that you can
  13.559 -actually log in from another machine at all.  If you can't use
  13.560 -\command{ssh} or \command{putty} to log in, the error message you get
  13.561 -may give you a few hints as to what's wrong.  The most common problems
  13.562 -are as follows.
  13.563 -\begin{itemize}
  13.564 -\item If you get a ``connection refused'' error, either there isn't an
  13.565 -  SSH daemon running on the server at all, or it's inaccessible due to
  13.566 -  firewall configuration.
  13.567 -\item If you get a ``no route to host'' error, you either have an
  13.568 -  incorrect address for the server or a seriously locked down firewall
  13.569 -  that won't admit its existence at all.
  13.570 -\item If you get a ``permission denied'' error, you may have mistyped
  13.571 -  the username on the server, or you could have mistyped your key's
  13.572 -  passphrase or the remote user's password.
  13.573 -\end{itemize}
  13.574 -In summary, if you're having trouble talking to the server's ssh
  13.575 -daemon, first make sure that one is running at all.  On many systems
  13.576 -it will be installed, but disabled, by default.  Once you're done with
  13.577 -this step, you should then check that the server's firewall is
  13.578 -configured to allow incoming connections on the port the ssh daemon is
  13.579 -listening on (usually~22).  Don't worry about more exotic
  13.580 -possibilities for misconfiguration until you've checked these two
  13.581 -first.
  13.582 -
  13.583 -If you're using an authentication agent on the client side to store
  13.584 -passphrases for your keys, you ought to be able to log into the server
  13.585 -without being prompted for a passphrase or a password.  If you're
  13.586 -prompted for a passphrase, there are a few possible culprits.
  13.587 -\begin{itemize}
  13.588 -\item You might have forgotten to use \command{ssh-add} or
  13.589 -  \command{pageant} to store the passphrase.
  13.590 -\item You might have stored the passphrase for the wrong key.
  13.591 -\end{itemize}
  13.592 -If you're being prompted for the remote user's password, there are
  13.593 -another few possible problems to check.
  13.594 -\begin{itemize}
  13.595 -\item Either the user's home directory or their \sdirname{.ssh}
  13.596 -  directory might have excessively liberal permissions.  As a result,
  13.597 -  the ssh daemon will not trust or read their
  13.598 -  \sfilename{authorized\_keys} file.  For example, a group-writable
  13.599 -  home or \sdirname{.ssh} directory will often cause this symptom.
  13.600 -\item The user's \sfilename{authorized\_keys} file may have a problem.
  13.601 -  If anyone other than the user owns or can write to that file, the
  13.602 -  ssh daemon will not trust or read it.
  13.603 -\end{itemize}
  13.604 -
  13.605 -In the ideal world, you should be able to run the following command
  13.606 -successfully, and it should print exactly one line of output, the
  13.607 -current date and time.
  13.608 -\begin{codesample2}
  13.609 -  ssh myserver date
  13.610 -\end{codesample2}
  13.611 -
  13.612 -If, on your server, you have login scripts that print banners or other
  13.613 -junk even when running non-interactive commands like this, you should
  13.614 -fix them before you continue, so that they only print output if
  13.615 -they're run interactively.  Otherwise these banners will at least
  13.616 -clutter up Mercurial's output.  Worse, they could potentially cause
  13.617 -problems with running Mercurial commands remotely.  Mercurial makes
  13.618 -tries to detect and ignore banners in non-interactive \command{ssh}
  13.619 -sessions, but it is not foolproof.  (If you're editing your login
  13.620 -scripts on your server, the usual way to see if a login script is
  13.621 -running in an interactive shell is to check the return code from the
  13.622 -command \Verb|tty -s|.)
  13.623 -
  13.624 -Once you've verified that plain old ssh is working with your server,
  13.625 -the next step is to ensure that Mercurial runs on the server.  The
  13.626 -following command should run successfully:
  13.627 -\begin{codesample2}
  13.628 -  ssh myserver hg version
  13.629 -\end{codesample2}
  13.630 -If you see an error message instead of normal \hgcmd{version} output,
  13.631 -this is usually because you haven't installed Mercurial to
  13.632 -\dirname{/usr/bin}.  Don't worry if this is the case; you don't need
  13.633 -to do that.  But you should check for a few possible problems.
  13.634 -\begin{itemize}
  13.635 -\item Is Mercurial really installed on the server at all?  I know this
  13.636 -  sounds trivial, but it's worth checking!
  13.637 -\item Maybe your shell's search path (usually set via the \envar{PATH}
  13.638 -  environment variable) is simply misconfigured.
  13.639 -\item Perhaps your \envar{PATH} environment variable is only being set
  13.640 -  to point to the location of the \command{hg} executable if the login
  13.641 -  session is interactive.  This can happen if you're setting the path
  13.642 -  in the wrong shell login script.  See your shell's documentation for
  13.643 -  details.
  13.644 -\item The \envar{PYTHONPATH} environment variable may need to contain
  13.645 -  the path to the Mercurial Python modules.  It might not be set at
  13.646 -  all; it could be incorrect; or it may be set only if the login is
  13.647 -  interactive.
  13.648 -\end{itemize}
  13.649 -
  13.650 -If you can run \hgcmd{version} over an ssh connection, well done!
  13.651 -You've got the server and client sorted out.  You should now be able
  13.652 -to use Mercurial to access repositories hosted by that username on
  13.653 -that server.  If you run into problems with Mercurial and ssh at this
  13.654 -point, try using the \hggopt{--debug} option to get a clearer picture
  13.655 -of what's going on.
  13.656 -
  13.657 -\subsection{Using compression with ssh}
  13.658 -
  13.659 -Mercurial does not compress data when it uses the ssh protocol,
  13.660 -because the ssh protocol can transparently compress data.  However,
  13.661 -the default behaviour of ssh clients is \emph{not} to request
  13.662 -compression.
  13.663 -
  13.664 -Over any network other than a fast LAN (even a wireless network),
  13.665 -using compression is likely to significantly speed up Mercurial's
  13.666 -network operations.  For example, over a WAN, someone measured
  13.667 -compression as reducing the amount of time required to clone a
  13.668 -particularly large repository from~51 minutes to~17 minutes.
  13.669 -
  13.670 -Both \command{ssh} and \command{plink} accept a \cmdopt{ssh}{-C}
  13.671 -option which turns on compression.  You can easily edit your \hgrc\ to
  13.672 -enable compression for all of Mercurial's uses of the ssh protocol.
  13.673 -\begin{codesample2}
  13.674 -  [ui]
  13.675 -  ssh = ssh -C
  13.676 -\end{codesample2}
  13.677 -
  13.678 -If you use \command{ssh}, you can configure it to always use
  13.679 -compression when talking to your server.  To do this, edit your
  13.680 -\sfilename{.ssh/config} file (which may not yet exist), as follows.
  13.681 -\begin{codesample2}
  13.682 -  Host hg
  13.683 -    Compression yes
  13.684 -    HostName hg.example.com
  13.685 -\end{codesample2}
  13.686 -This defines an alias, \texttt{hg}.  When you use it on the
  13.687 -\command{ssh} command line or in a Mercurial \texttt{ssh}-protocol
  13.688 -URL, it will cause \command{ssh} to connect to \texttt{hg.example.com}
  13.689 -and use compression.  This gives you both a shorter name to type and
  13.690 -compression, each of which is a good thing in its own right.
  13.691 -
  13.692 -\section{Serving over HTTP using CGI}
  13.693 -\label{sec:collab:cgi}
  13.694 -
  13.695 -Depending on how ambitious you are, configuring Mercurial's CGI
  13.696 -interface can take anything from a few moments to several hours.
  13.697 -
  13.698 -We'll begin with the simplest of examples, and work our way towards a
  13.699 -more complex configuration.  Even for the most basic case, you're
  13.700 -almost certainly going to need to read and modify your web server's
  13.701 -configuration.
  13.702 -
  13.703 -\begin{note}
  13.704 -  Configuring a web server is a complex, fiddly, and highly
  13.705 -  system-dependent activity.  I can't possibly give you instructions
  13.706 -  that will cover anything like all of the cases you will encounter.
  13.707 -  Please use your discretion and judgment in following the sections
  13.708 -  below.  Be prepared to make plenty of mistakes, and to spend a lot
  13.709 -  of time reading your server's error logs.
  13.710 -\end{note}
  13.711 -
  13.712 -\subsection{Web server configuration checklist}
  13.713 -
  13.714 -Before you continue, do take a few moments to check a few aspects of
  13.715 -your system's setup.
  13.716 -
  13.717 -\begin{enumerate}
  13.718 -\item Do you have a web server installed at all?  Mac OS X ships with
  13.719 -  Apache, but many other systems may not have a web server installed.
  13.720 -\item If you have a web server installed, is it actually running?  On
  13.721 -  most systems, even if one is present, it will be disabled by
  13.722 -  default.
  13.723 -\item Is your server configured to allow you to run CGI programs in
  13.724 -  the directory where you plan to do so?  Most servers default to
  13.725 -  explicitly disabling the ability to run CGI programs.
  13.726 -\end{enumerate}
  13.727 -
  13.728 -If you don't have a web server installed, and don't have substantial
  13.729 -experience configuring Apache, you should consider using the
  13.730 -\texttt{lighttpd} web server instead of Apache.  Apache has a
  13.731 -well-deserved reputation for baroque and confusing configuration.
  13.732 -While \texttt{lighttpd} is less capable in some ways than Apache, most
  13.733 -of these capabilities are not relevant to serving Mercurial
  13.734 -repositories.  And \texttt{lighttpd} is undeniably \emph{much} easier
  13.735 -to get started with than Apache.
  13.736 -
  13.737 -\subsection{Basic CGI configuration}
  13.738 -
  13.739 -On Unix-like systems, it's common for users to have a subdirectory
  13.740 -named something like \dirname{public\_html} in their home directory,
  13.741 -from which they can serve up web pages.  A file named \filename{foo}
  13.742 -in this directory will be accessible at a URL of the form
  13.743 -\texttt{http://www.example.com/\~{}username/foo}.
  13.744 -
  13.745 -To get started, find the \sfilename{hgweb.cgi} script that should be
  13.746 -present in your Mercurial installation.  If you can't quickly find a
  13.747 -local copy on your system, simply download one from the master
  13.748 -Mercurial repository at
  13.749 -\url{http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi}.
  13.750 -
  13.751 -You'll need to copy this script into your \dirname{public\_html}
  13.752 -directory, and ensure that it's executable.
  13.753 -\begin{codesample2}
  13.754 -  cp .../hgweb.cgi ~/public_html
  13.755 -  chmod 755 ~/public_html/hgweb.cgi
  13.756 -\end{codesample2}
  13.757 -The \texttt{755} argument to \command{chmod} is a little more general
  13.758 -than just making the script executable: it ensures that the script is
  13.759 -executable by anyone, and that ``group'' and ``other'' write
  13.760 -permissions are \emph{not} set.  If you were to leave those write
  13.761 -permissions enabled, Apache's \texttt{suexec} subsystem would likely
  13.762 -refuse to execute the script.  In fact, \texttt{suexec} also insists
  13.763 -that the \emph{directory} in which the script resides must not be
  13.764 -writable by others.
  13.765 -\begin{codesample2}
  13.766 -  chmod 755 ~/public_html
  13.767 -\end{codesample2}
  13.768 -
  13.769 -\subsubsection{What could \emph{possibly} go wrong?}
  13.770 -\label{sec:collab:wtf}
  13.771 -
  13.772 -Once you've copied the CGI script into place, go into a web browser,
  13.773 -and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi},
  13.774 -\emph{but} brace yourself for instant failure.  There's a high
  13.775 -probability that trying to visit this URL will fail, and there are
  13.776 -many possible reasons for this.  In fact, you're likely to stumble
  13.777 -over almost every one of the possible errors below, so please read
  13.778 -carefully.  The following are all of the problems I ran into on a
  13.779 -system running Fedora~7, with a fresh installation of Apache, and a
  13.780 -user account that I created specially to perform this exercise.
  13.781 -
  13.782 -Your web server may have per-user directories disabled.  If you're
  13.783 -using Apache, search your config file for a \texttt{UserDir}
  13.784 -directive.  If there's none present, per-user directories will be
  13.785 -disabled.  If one exists, but its value is \texttt{disabled}, then
  13.786 -per-user directories will be disabled.  Otherwise, the string after
  13.787 -\texttt{UserDir} gives the name of the subdirectory that Apache will
  13.788 -look in under your home directory, for example \dirname{public\_html}.
  13.789 -
  13.790 -Your file access permissions may be too restrictive.  The web server
  13.791 -must be able to traverse your home directory and directories under
  13.792 -your \dirname{public\_html} directory, and read files under the latter
  13.793 -too.  Here's a quick recipe to help you to make your permissions more
  13.794 -appropriate.
  13.795 -\begin{codesample2}
  13.796 -  chmod 755 ~
  13.797 -  find ~/public_html -type d -print0 | xargs -0r chmod 755
  13.798 -  find ~/public_html -type f -print0 | xargs -0r chmod 644
  13.799 -\end{codesample2}
  13.800 -
  13.801 -The other possibility with permissions is that you might get a
  13.802 -completely empty window when you try to load the script.  In this
  13.803 -case, it's likely that your access permissions are \emph{too
  13.804 -  permissive}.  Apache's \texttt{suexec} subsystem won't execute a
  13.805 -script that's group-~or world-writable, for example.
  13.806 -
  13.807 -Your web server may be configured to disallow execution of CGI
  13.808 -programs in your per-user web directory.  Here's Apache's
  13.809 -default per-user configuration from my Fedora system.
  13.810 -\begin{codesample2}
  13.811 -  <Directory /home/*/public_html>
  13.812 -      AllowOverride FileInfo AuthConfig Limit
  13.813 -      Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
  13.814 -      <Limit GET POST OPTIONS>
  13.815 -          Order allow,deny
  13.816 -          Allow from all
  13.817 -      </Limit>
  13.818 -      <LimitExcept GET POST OPTIONS>
  13.819 -          Order deny,allow
  13.820 -          Deny from all
  13.821 -      </LimitExcept>
  13.822 -  </Directory>
  13.823 -\end{codesample2}
  13.824 -If you find a similar-looking \texttt{Directory} group in your Apache
  13.825 -configuration, the directive to look at inside it is \texttt{Options}.
  13.826 -Add \texttt{ExecCGI} to the end of this list if it's missing, and
  13.827 -restart the web server.
  13.828 -
  13.829 -If you find that Apache serves you the text of the CGI script instead
  13.830 -of executing it, you may need to either uncomment (if already present)
  13.831 -or add a directive like this.
  13.832 -\begin{codesample2}
  13.833 -  AddHandler cgi-script .cgi
  13.834 -\end{codesample2}
  13.835 -
  13.836 -The next possibility is that you might be served with a colourful
  13.837 -Python backtrace claiming that it can't import a
  13.838 -\texttt{mercurial}-related module.  This is actually progress!  The
  13.839 -server is now capable of executing your CGI script.  This error is
  13.840 -only likely to occur if you're running a private installation of
  13.841 -Mercurial, instead of a system-wide version.  Remember that the web
  13.842 -server runs the CGI program without any of the environment variables
  13.843 -that you take for granted in an interactive session.  If this error
  13.844 -happens to you, edit your copy of \sfilename{hgweb.cgi} and follow the
  13.845 -directions inside it to correctly set your \envar{PYTHONPATH}
  13.846 -environment variable.
  13.847 -
  13.848 -Finally, you are \emph{certain} to by served with another colourful
  13.849 -Python backtrace: this one will complain that it can't find
  13.850 -\dirname{/path/to/repository}.  Edit your \sfilename{hgweb.cgi} script
  13.851 -and replace the \dirname{/path/to/repository} string with the complete
  13.852 -path to the repository you want to serve up.
  13.853 -
  13.854 -At this point, when you try to reload the page, you should be
  13.855 -presented with a nice HTML view of your repository's history.  Whew!
  13.856 -
  13.857 -\subsubsection{Configuring lighttpd}
  13.858 -
  13.859 -To be exhaustive in my experiments, I tried configuring the
  13.860 -increasingly popular \texttt{lighttpd} web server to serve the same
  13.861 -repository as I described with Apache above.  I had already overcome
  13.862 -all of the problems I outlined with Apache, many of which are not
  13.863 -server-specific.  As a result, I was fairly sure that my file and
  13.864 -directory permissions were good, and that my \sfilename{hgweb.cgi}
  13.865 -script was properly edited.
  13.866 -
  13.867 -Once I had Apache running, getting \texttt{lighttpd} to serve the
  13.868 -repository was a snap (in other words, even if you're trying to use
  13.869 -\texttt{lighttpd}, you should read the Apache section).  I first had
  13.870 -to edit the \texttt{mod\_access} section of its config file to enable
  13.871 -\texttt{mod\_cgi} and \texttt{mod\_userdir}, both of which were
  13.872 -disabled by default on my system.  I then added a few lines to the end
  13.873 -of the config file, to configure these modules.
  13.874 -\begin{codesample2}
  13.875 -  userdir.path = "public_html"
  13.876 -  cgi.assign = ( ".cgi" => "" )
  13.877 -\end{codesample2}
  13.878 -With this done, \texttt{lighttpd} ran immediately for me.  If I had
  13.879 -configured \texttt{lighttpd} before Apache, I'd almost certainly have
  13.880 -run into many of the same system-level configuration problems as I did
  13.881 -with Apache.  However, I found \texttt{lighttpd} to be noticeably
  13.882 -easier to configure than Apache, even though I've used Apache for over
  13.883 -a decade, and this was my first exposure to \texttt{lighttpd}.
  13.884 -
  13.885 -\subsection{Sharing multiple repositories with one CGI script}
  13.886 -
  13.887 -The \sfilename{hgweb.cgi} script only lets you publish a single
  13.888 -repository, which is an annoying restriction.  If you want to publish
  13.889 -more than one without wracking yourself with multiple copies of the
  13.890 -same script, each with different names, a better choice is to use the
  13.891 -\sfilename{hgwebdir.cgi} script.
  13.892 -
  13.893 -The procedure to configure \sfilename{hgwebdir.cgi} is only a little
  13.894 -more involved than for \sfilename{hgweb.cgi}.  First, you must obtain
  13.895 -a copy of the script.  If you don't have one handy, you can download a
  13.896 -copy from the master Mercurial repository at
  13.897 -\url{http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi}.
  13.898 -
  13.899 -You'll need to copy this script into your \dirname{public\_html}
  13.900 -directory, and ensure that it's executable.
  13.901 -\begin{codesample2}
  13.902 -  cp .../hgwebdir.cgi ~/public_html
  13.903 -  chmod 755 ~/public_html ~/public_html/hgwebdir.cgi
  13.904 -\end{codesample2}
  13.905 -With basic configuration out of the way, try to visit
  13.906 -\url{http://myhostname/~myuser/hgwebdir.cgi} in your browser.  It
  13.907 -should display an empty list of repositories.  If you get a blank
  13.908 -window or error message, try walking through the list of potential
  13.909 -problems in section~\ref{sec:collab:wtf}.
  13.910 -
  13.911 -The \sfilename{hgwebdir.cgi} script relies on an external
  13.912 -configuration file.  By default, it searches for a file named
  13.913 -\sfilename{hgweb.config} in the same directory as itself.  You'll need
  13.914 -to create this file, and make it world-readable.  The format of the
  13.915 -file is similar to a Windows ``ini'' file, as understood by Python's
  13.916 -\texttt{ConfigParser}~\cite{web:configparser} module.
  13.917 -
  13.918 -The easiest way to configure \sfilename{hgwebdir.cgi} is with a
  13.919 -section named \texttt{collections}.  This will automatically publish
  13.920 -\emph{every} repository under the directories you name.  The section
  13.921 -should look like this:
  13.922 -\begin{codesample2}
  13.923 -  [collections]
  13.924 -  /my/root = /my/root
  13.925 -\end{codesample2}
  13.926 -Mercurial interprets this by looking at the directory name on the
  13.927 -\emph{right} hand side of the ``\texttt{=}'' sign; finding
  13.928 -repositories in that directory hierarchy; and using the text on the
  13.929 -\emph{left} to strip off matching text from the names it will actually
  13.930 -list in the web interface.  The remaining component of a path after
  13.931 -this stripping has occurred is called a ``virtual path''.
  13.932 -
  13.933 -Given the example above, if we have a repository whose local path is
  13.934 -\dirname{/my/root/this/repo}, the CGI script will strip the leading
  13.935 -\dirname{/my/root} from the name, and publish the repository with a
  13.936 -virtual path of \dirname{this/repo}.  If the base URL for our CGI
  13.937 -script is \url{http://myhostname/~myuser/hgwebdir.cgi}, the complete
  13.938 -URL for that repository will be
  13.939 -\url{http://myhostname/~myuser/hgwebdir.cgi/this/repo}.
  13.940 -
  13.941 -If we replace \dirname{/my/root} on the left hand side of this example
  13.942 -with \dirname{/my}, then \sfilename{hgwebdir.cgi} will only strip off
  13.943 -\dirname{/my} from the repository name, and will give us a virtual
  13.944 -path of \dirname{root/this/repo} instead of \dirname{this/repo}.
  13.945 -
  13.946 -The \sfilename{hgwebdir.cgi} script will recursively search each
  13.947 -directory listed in the \texttt{collections} section of its
  13.948 -configuration file, but it will \texttt{not} recurse into the
  13.949 -repositories it finds.
  13.950 -
  13.951 -The \texttt{collections} mechanism makes it easy to publish many
  13.952 -repositories in a ``fire and forget'' manner.  You only need to set up
  13.953 -the CGI script and configuration file one time.  Afterwards, you can
  13.954 -publish or unpublish a repository at any time by simply moving it
  13.955 -into, or out of, the directory hierarchy in which you've configured
  13.956 -\sfilename{hgwebdir.cgi} to look.
  13.957 -
  13.958 -\subsubsection{Explicitly specifying which repositories to publish}
  13.959 -
  13.960 -In addition to the \texttt{collections} mechanism, the
  13.961 -\sfilename{hgwebdir.cgi} script allows you to publish a specific list
  13.962 -of repositories.  To do so, create a \texttt{paths} section, with
  13.963 -contents of the following form.
  13.964 -\begin{codesample2}
  13.965 -  [paths]
  13.966 -  repo1 = /my/path/to/some/repo
  13.967 -  repo2 = /some/path/to/another
  13.968 -\end{codesample2}
  13.969 -In this case, the virtual path (the component that will appear in a
  13.970 -URL) is on the left hand side of each definition, while the path to
  13.971 -the repository is on the right.  Notice that there does not need to be
  13.972 -any relationship between the virtual path you choose and the location
  13.973 -of a repository in your filesystem.
  13.974 -
  13.975 -If you wish, you can use both the \texttt{collections} and
  13.976 -\texttt{paths} mechanisms simultaneously in a single configuration
  13.977 -file.
  13.978 -
  13.979 -\begin{note}
  13.980 -  If multiple repositories have the same virtual path,
  13.981 -  \sfilename{hgwebdir.cgi} will not report an error.  Instead, it will
  13.982 -  behave unpredictably.
  13.983 -\end{note}
  13.984 -
  13.985 -\subsection{Downloading source archives}
  13.986 -
  13.987 -Mercurial's web interface lets users download an archive of any
  13.988 -revision.  This archive will contain a snapshot of the working
  13.989 -directory as of that revision, but it will not contain a copy of the
  13.990 -repository data.
  13.991 -
  13.992 -By default, this feature is not enabled.  To enable it, you'll need to
  13.993 -add an \rcitem{web}{allow\_archive} item to the \rcsection{web}
  13.994 -section of your \hgrc.
  13.995 -
  13.996 -\subsection{Web configuration options}
  13.997 -
  13.998 -Mercurial's web interfaces (the \hgcmd{serve} command, and the
  13.999 -\sfilename{hgweb.cgi} and \sfilename{hgwebdir.cgi} scripts) have a
 13.1000 -number of configuration options that you can set.  These belong in a
 13.1001 -section named \rcsection{web}.
 13.1002 -\begin{itemize}
 13.1003 -\item[\rcitem{web}{allow\_archive}] Determines which (if any) archive
 13.1004 -  download mechanisms Mercurial supports.  If you enable this
 13.1005 -  feature, users of the web interface will be able to download an
 13.1006 -  archive of whatever revision of a repository they are viewing.
 13.1007 -  To enable the archive feature, this item must take the form of a
 13.1008 -  sequence of words drawn from the list below.
 13.1009 -  \begin{itemize}
 13.1010 -  \item[\texttt{bz2}] A \command{tar} archive, compressed using
 13.1011 -    \texttt{bzip2} compression.  This has the best compression ratio,
 13.1012 -    but uses the most CPU time on the server.
 13.1013 -  \item[\texttt{gz}] A \command{tar} archive, compressed using
 13.1014 -    \texttt{gzip} compression.
 13.1015 -  \item[\texttt{zip}] A \command{zip} archive, compressed using LZW
 13.1016 -    compression.  This format has the worst compression ratio, but is
 13.1017 -    widely used in the Windows world.
 13.1018 -  \end{itemize}
 13.1019 -  If you provide an empty list, or don't have an
 13.1020 -  \rcitem{web}{allow\_archive} entry at all, this feature will be
 13.1021 -  disabled.  Here is an example of how to enable all three supported
 13.1022 -  formats.
 13.1023 -  \begin{codesample4}
 13.1024 -    [web]
 13.1025 -    allow_archive = bz2 gz zip
 13.1026 -  \end{codesample4}
 13.1027 -\item[\rcitem{web}{allowpull}] Boolean.  Determines whether the web
 13.1028 -  interface allows remote users to \hgcmd{pull} and \hgcmd{clone} this
 13.1029 -  repository over~HTTP.  If set to \texttt{no} or \texttt{false}, only
 13.1030 -  the ``human-oriented'' portion of the web interface is available.
 13.1031 -\item[\rcitem{web}{contact}] String.  A free-form (but preferably
 13.1032 -  brief) string identifying the person or group in charge of the
 13.1033 -  repository.  This often contains the name and email address of a
 13.1034 -  person or mailing list.  It often makes sense to place this entry in
 13.1035 -  a repository's own \sfilename{.hg/hgrc} file, but it can make sense
 13.1036 -  to use in a global \hgrc\ if every repository has a single
 13.1037 -  maintainer.
 13.1038 -\item[\rcitem{web}{maxchanges}] Integer.  The default maximum number
 13.1039 -  of changesets to display in a single page of output.
 13.1040 -\item[\rcitem{web}{maxfiles}] Integer.  The default maximum number
 13.1041 -  of modified files to display in a single page of output.
 13.1042 -\item[\rcitem{web}{stripes}] Integer.  If the web interface displays
 13.1043 -  alternating ``stripes'' to make it easier to visually align rows
 13.1044 -  when you are looking at a table, this number controls the number of
 13.1045 -  rows in each stripe.
 13.1046 -\item[\rcitem{web}{style}] Controls the template Mercurial uses to
 13.1047 -  display the web interface.  Mercurial ships with two web templates,
 13.1048 -  named \texttt{default} and \texttt{gitweb} (the latter is much more
 13.1049 -  visually attractive).  You can also specify a custom template of
 13.1050 -  your own; see chapter~\ref{chap:template} for details.  Here, you
 13.1051 -  can see how to enable the \texttt{gitweb} style.
 13.1052 -  \begin{codesample4}
 13.1053 -    [web]
 13.1054 -    style = gitweb
 13.1055 -  \end{codesample4}
 13.1056 -\item[\rcitem{web}{templates}] Path.  The directory in which to search
 13.1057 -  for template files.  By default, Mercurial searches in the directory
 13.1058 -  in which it was installed.
 13.1059 -\end{itemize}
 13.1060 -If you are using \sfilename{hgwebdir.cgi}, you can place a few
 13.1061 -configuration items in a \rcsection{web} section of the
 13.1062 -\sfilename{hgweb.config} file instead of a \hgrc\ file, for
 13.1063 -convenience.  These items are \rcitem{web}{motd} and
 13.1064 -\rcitem{web}{style}.
 13.1065 -
 13.1066 -\subsubsection{Options specific to an individual repository}
 13.1067 -
 13.1068 -A few \rcsection{web} configuration items ought to be placed in a
 13.1069 -repository's local \sfilename{.hg/hgrc}, rather than a user's or
 13.1070 -global \hgrc.
 13.1071 -\begin{itemize}
 13.1072 -\item[\rcitem{web}{description}] String.  A free-form (but preferably
 13.1073 -  brief) string that describes the contents or purpose of the
 13.1074 -  repository.
 13.1075 -\item[\rcitem{web}{name}] String.  The name to use for the repository
 13.1076 -  in the web interface.  This overrides the default name, which is the
 13.1077 -  last component of the repository's path.
 13.1078 -\end{itemize}
 13.1079 -
 13.1080 -\subsubsection{Options specific to the \hgcmd{serve} command}
 13.1081 -
 13.1082 -Some of the items in the \rcsection{web} section of a \hgrc\ file are
 13.1083 -only for use with the \hgcmd{serve} command.
 13.1084 -\begin{itemize}
 13.1085 -\item[\rcitem{web}{accesslog}] Path.  The name of a file into which to
 13.1086 -  write an access log.  By default, the \hgcmd{serve} command writes
 13.1087 -  this information to standard output, not to a file.  Log entries are
 13.1088 -  written in the standard ``combined'' file format used by almost all
 13.1089 -  web servers.
 13.1090 -\item[\rcitem{web}{address}] String.  The local address on which the
 13.1091 -  server should listen for incoming connections.  By default, the
 13.1092 -  server listens on all addresses.
 13.1093 -\item[\rcitem{web}{errorlog}] Path.  The name of a file into which to
 13.1094 -  write an error log.  By default, the \hgcmd{serve} command writes this
 13.1095 -  information to standard error, not to a file.
 13.1096 -\item[\rcitem{web}{ipv6}] Boolean.  Whether to use the IPv6 protocol.
 13.1097 -  By default, IPv6 is not used. 
 13.1098 -\item[\rcitem{web}{port}] Integer.  The TCP~port number on which the
 13.1099 -  server should listen.  The default port number used is~8000.
 13.1100 -\end{itemize}
 13.1101 -
 13.1102 -\subsubsection{Choosing the right \hgrc\ file to add \rcsection{web} items to}
 13.1103 -
 13.1104 -It is important to remember that a web server like Apache or
 13.1105 -\texttt{lighttpd} will run under a user~ID that is different to yours.
 13.1106 -CGI scripts run by your server, such as \sfilename{hgweb.cgi}, will
 13.1107 -usually also run under that user~ID.
 13.1108 -
 13.1109 -If you add \rcsection{web} items to your own personal \hgrc\ file, CGI
 13.1110 -scripts won't read that \hgrc\ file.  Those settings will thus only
 13.1111 -affect the behaviour of the \hgcmd{serve} command when you run it.  To
 13.1112 -cause CGI scripts to see your settings, either create a \hgrc\ file in
 13.1113 -the home directory of the user ID that runs your web server, or add
 13.1114 -those settings to a system-wide \hgrc\ file.
 13.1115 -
 13.1116 -
 13.1117 -%%% Local Variables: 
 13.1118 -%%% mode: latex
 13.1119 -%%% TeX-master: "00book"
 13.1120 -%%% End: