Commits

Dongsheng Song committed e8763d4 Merge

Comments (0)

Files changed (55)

+18131160f7ee3b81bf39ce2c58f762b8d671cef3 submitted
 <!-- Chapters. -->
 
 <!ENTITY ch00     SYSTEM "ch00-preface.xml">
-<!ENTITY ch01     SYSTEM "ch01-tour-basic.xml">
-<!ENTITY ch02     SYSTEM "ch02-tour-merge.xml">
-<!ENTITY ch03     SYSTEM "ch03-concepts.xml">
-<!ENTITY ch04     SYSTEM "ch04-daily.xml">
-<!ENTITY ch05     SYSTEM "ch05-collab.xml">
-<!ENTITY ch06     SYSTEM "ch06-filenames.xml">
-<!ENTITY ch07     SYSTEM "ch07-branch.xml">
-<!ENTITY ch08     SYSTEM "ch08-undo.xml">
-<!ENTITY ch09     SYSTEM "ch09-hook.xml">
-<!ENTITY ch10     SYSTEM "ch10-template.xml">
-<!ENTITY ch11     SYSTEM "ch11-mq.xml">
-<!ENTITY ch12     SYSTEM "ch12-mq-collab.xml">
-<!ENTITY ch13     SYSTEM "ch13-hgext.xml">
-<!ENTITY appA     SYSTEM "appA-cmdref.xml">
+<!ENTITY ch01     SYSTEM "ch01-intro.xml">
+<!ENTITY ch02     SYSTEM "ch02-tour-basic.xml">
+<!ENTITY ch03     SYSTEM "ch03-tour-merge.xml">
+<!ENTITY ch04     SYSTEM "ch04-concepts.xml">
+<!ENTITY ch05     SYSTEM "ch05-daily.xml">
+<!ENTITY ch06     SYSTEM "ch06-collab.xml">
+<!ENTITY ch07     SYSTEM "ch07-filenames.xml">
+<!ENTITY ch08     SYSTEM "ch08-branch.xml">
+<!ENTITY ch09     SYSTEM "ch09-undo.xml">
+<!ENTITY ch10     SYSTEM "ch10-hook.xml">
+<!ENTITY ch11     SYSTEM "ch11-template.xml">
+<!ENTITY ch12     SYSTEM "ch12-mq.xml">
+<!ENTITY ch13     SYSTEM "ch13-mq-collab.xml">
+<!ENTITY ch14     SYSTEM "ch14-hgext.xml">
+<!ENTITY appA     SYSTEM "appA-svn.xml">
 <!ENTITY appB     SYSTEM "appB-mq-ref.xml">
 <!ENTITY appC     SYSTEM "appC-srcinstall.xml">
 <!ENTITY appD     SYSTEM "appD-license.xml">
   &ch12;
   <!-- BEGIN ch13 -->
   &ch13;
+  <!-- BEGIN ch14 -->
+  &ch14;
+  <!-- BEGIN appA -->
+  &appA;
   <!-- BEGIN appB -->
   &appB;
   <!-- BEGIN appC -->
 	filenames \
 	hook.msglen \
 	hook.simple \
-	hook.ws \
 	issue29 \
 	mq.guards \
 	mq.qinit-help \

en/appA-cmdref.xml

-<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
-
-<appendix id="cmdref">
-  <?dbhtml filename="command-reference.html"?>
-<title>Command reference</title>
-
-<para id="x_653">\cmdref{add}{add files at the next commit}
-\optref{add}{I}{include}
-\optref{add}{X}{exclude}
-\optref{add}{n}{dry-run}</para>
-
-<para id="x_654">\cmdref{diff}{print changes in history or working directory}</para>
-
-<para id="x_655">Show differences between revisions for the specified files or
-directories, using the unified diff format.  For a description of the
-unified diff format, see <xref linkend="sec:mq:patch"/>.</para>
-
-<para id="x_656">By default, this command does not print diffs for files that Mercurial
-considers to contain binary data.  To control this behavior, see the
-<option role="hg-opt-diff">-a</option> and <option role="hg-opt-diff">--git</option> options.</para>
-
-<sect2>
-<title>Options</title>
-x
-<para id="x_657">\loptref{diff}{nodates}</para>
-
-<para id="x_658">Omit date and time information when printing diff headers.</para>
-
-<para id="x_659">\optref{diff}{B}{ignore-blank-lines}</para>
-
-<para id="x_65a">Do not print changes that only insert or delete blank lines.  A line
-that contains only whitespace is not considered blank.
-</para>
-
-<para id="x_65b">\optref{diff}{I}{include}
-</para>
-
-<para id="x_65c">Include files and directories whose names match the given patterns.
-</para>
-
-<para id="x_65d">\optref{diff}{X}{exclude}
-</para>
-
-<para id="x_65e">Exclude files and directories whose names match the given patterns.
-</para>
-
-<para id="x_65f">\optref{diff}{a}{text}
-</para>
-
-<para id="x_660">If this option is not specified, <command role="hg-cmd">hg diff</command> will refuse to print
-diffs for files that it detects as binary. Specifying <option role="hg-opt-diff">-a</option>
-forces <command role="hg-cmd">hg diff</command> to treat all files as text, and generate diffs for
-all of them.
-</para>
-
-<para id="x_661">This option is useful for files that are <quote>mostly text</quote> but have a
-few embedded NUL characters.  If you use it on files that contain a
-lot of binary data, its output will be incomprehensible.
-</para>
-
-<para id="x_662">\optref{diff}{b}{ignore-space-change}
-</para>
-
-<para id="x_663">Do not print a line if the only change to that line is in the amount
-of white space it contains.
-</para>
-
-<para id="x_664">\optref{diff}{g}{git}
-</para>
-
-<para id="x_665">Print <command>git</command>-compatible diffs.  XXX reference a format
-description.
-</para>
-
-<para id="x_666">\optref{diff}{p}{show-function}
-</para>
-
-<para id="x_667">Display the name of the enclosing function in a hunk header, using a
-simple heuristic.  This functionality is enabled by default, so the
-<option role="hg-opt-diff">-p</option> option has no effect unless you change the value of
-the <envar role="rc-item-diff">showfunc</envar> config item, as in the following example.</para>
-
-<!-- &interaction.cmdref.diff-p; -->
-
-<para id="x_668">\optref{diff}{r}{rev}
-</para>
-
-<para id="x_669">Specify one or more revisions to compare.  The <command role="hg-cmd">hg diff</command> command
-accepts up to two <option role="hg-opt-diff">-r</option> options to specify the revisions to
-compare.
-</para>
-
-<orderedlist>
-<listitem><para id="x_66a">Display the differences between the parent revision of the
-  working directory and the working directory.
-</para>
-</listitem>
-<listitem><para id="x_66b">Display the differences between the specified changeset and the
-  working directory.
-</para>
-</listitem>
-<listitem><para id="x_66c">Display the differences between the two specified changesets.
-</para>
-</listitem></orderedlist>
-
-<para id="x_66d">You can specify two revisions using either two <option role="hg-opt-diff">-r</option>
-options or revision range notation.  For example, the two revision
-specifications below are equivalent.
-</para>
-<programlisting>hg diff -r 10 -r 20
-hg diff -r10:20</programlisting>
-
-<para id="x_66e">When you provide two revisions, Mercurial treats the order of those
-revisions as significant.  Thus, <command role="hg-cmd">hg diff -r10:20</command> will
-produce a diff that will transform files from their contents as of
-revision 10 to their contents as of revision 20, while
-<command role="hg-cmd">hg diff -r20:10</command> means the opposite: the diff that will
-transform files from their revision 20 contents to their revision 10
-contents.  You cannot reverse the ordering in this way if you are
-diffing against the working directory.
-</para>
-
-<para id="x_66f">\optref{diff}{w}{ignore-all-space}
-</para>
-
-<para id="x_670">\cmdref{version}{print version and copyright information}
-</para>
-
-<para id="x_671">This command displays the version of Mercurial you are running, and
-its copyright license.  There are four kinds of version string that
-you may see.
-</para>
-<itemizedlist>
-<listitem><para id="x_672">The string <quote><literal>unknown</literal></quote>. This version of Mercurial was
-  not built in a Mercurial repository, and cannot determine its own
-  version.
-</para>
-</listitem>
-<listitem><para id="x_673">A short numeric string, such as <quote><literal>1.1</literal></quote>. This is a
-  build of a revision of Mercurial that was identified by a specific
-  tag in the repository where it was built.  (This doesn't necessarily
-  mean that you're running an official release; someone else could
-  have added that tag to any revision in the repository where they
-  built Mercurial.)
-</para>
-</listitem>
-<listitem><para id="x_674">A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>.  This
-  is a build of the given revision of Mercurial.
-</para>
-</listitem>
-<listitem><para id="x_675">A hexadecimal string followed by a date, such as
-  <quote><literal>875489e31abe+20070205</literal></quote>.  This is a build of the given
-  revision of Mercurial, where the build repository contained some
-  local changes that had not been committed.
-</para>
-</listitem></itemizedlist>
-
-</sect2>
-<sect2>
-<title>Tips and tricks</title>
-
-<sect3 id="cmdref:diff-vs-status">
-<title>Why do the results of <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg status</command> differ?</title>
-
-<para id="x_676">When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files
-that Mercurial will record changes for the next time you perform a
-commit.  If you run the <command role="hg-cmd">hg diff</command> command, you may notice that it
-prints diffs for only a <emphasis>subset</emphasis> of the files that <command role="hg-cmd">hg status</command>
-listed.  There are two possible reasons for this.
-</para>
-
-<para id="x_677">The first is that <command role="hg-cmd">hg status</command> prints some kinds of modifications
-that <command role="hg-cmd">hg diff</command> doesn't normally display.  The <command role="hg-cmd">hg diff</command> command
-normally outputs unified diffs, which don't have the ability to
-represent some changes that Mercurial can track.  Most notably,
-traditional diffs can't represent a change in whether or not a file is
-executable, but Mercurial records this information.
-</para>
-
-<para id="x_678">If you use the <option role="hg-opt-diff">--git</option> option to <command role="hg-cmd">hg diff</command>, it will
-display <command>git</command>-compatible diffs that <emphasis>can</emphasis> display this
-extra information.
-</para>
-
-<para id="x_679">The second possible reason that <command role="hg-cmd">hg diff</command> might be printing diffs
-for a subset of the files displayed by <command role="hg-cmd">hg status</command> is that if you
-invoke it without any arguments, <command role="hg-cmd">hg diff</command> prints diffs against the
-first parent of the working directory.  If you have run <command role="hg-cmd">hg merge</command>
-to merge two changesets, but you haven't yet committed the results of
-the merge, your working directory has two parents (use <command role="hg-cmd">hg parents</command>
-to see them).  While <command role="hg-cmd">hg status</command> prints modifications relative to
-<emphasis>both</emphasis> parents after an uncommitted merge, <command role="hg-cmd">hg diff</command> still
-operates relative only to the first parent.  You can get it to print
-diffs relative to the second parent by specifying that parent with the
-<option role="hg-opt-diff">-r</option> option.  There is no way to print diffs relative to
-both parents.
-</para>
-
-</sect3>
-<sect3>
-<title>Generating safe binary diffs</title>
-
-<para id="x_67a">If you use the <option role="hg-opt-diff">-a</option> option to force Mercurial to print
-diffs of files that are either <quote>mostly text</quote> or contain lots of
-binary data, those diffs cannot subsequently be applied by either
-Mercurial's <command role="hg-cmd">hg import</command> command or the system's <command>patch</command>
-command.
-</para>
-
-<para id="x_67b">If you want to generate a diff of a binary file that is safe to use as
-input for <command role="hg-cmd">hg import</command>, use the <command role="hg-cmd">hg diff</command>{--git} option when you
-generate the patch.  The system <command>patch</command> command cannot handle
-binary patches at all.
-</para>
-
-</sect3>
-</sect2>
-</appendix>
-
-<!--
-local variables: 
-sgml-parent-document: ("00book.xml" "book" "appendix")
-end:
--->
+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<appendix id="svn">
+  <?dbhtml filename="migrating-to-mercurial.html"?>
+<title>Migrating to Mercurial</title>
+
+  <para id="x_6e1">A common way to test the waters with a new revision control
+    tool is to experiment with switching an existing project, rather
+    than starting a new project from scratch.</para>
+
+  <para id="x_6e2">In this appendix, we discuss how to import a project's history
+    into Mercurial, and what to look out for if you are used to a
+    different revision control system.</para>
+
+  <sect1>
+    <title>Importing history from another system</title>
+
+    <para id="x_6e3">Mercurial ships with an extension named
+      <literal>convert</literal>, which can import project history
+      from most popular revision control systems.  At the time this
+      book was written, it could import history from the following
+      systems:</para>
+    <itemizedlist>
+      <listitem>
+	<para id="x_6e4">Subversion</para>
+      </listitem>
+      <listitem>
+	<para id="x_6e5">CVS</para>
+      </listitem>
+      <listitem>
+	<para id="x_6e6">git</para>
+      </listitem>
+      <listitem>
+	<para id="x_6e7">Darcs</para>
+      </listitem>
+      <listitem>
+	<para id="x_6e8">Bazaar</para>
+      </listitem>
+      <listitem>
+	<para id="x_6e9">Monotone</para>
+      </listitem>
+      <listitem>
+	<para id="x_6ea">GNU Arch</para>
+      </listitem>
+      <listitem>
+	<para id="x_6eb">Mercurial</para>
+      </listitem>
+    </itemizedlist>
+
+    <para id="x_6ec">(To see why Mercurial itself is supported as a source, see
+      <xref linkend="svn.filemap"/>.)</para>
+
+    <para id="x_6ed">You can enable the extension in the usual way, by editing
+      your <filename>~/.hgrc</filename> file.</para>
+
+    <programlisting>[extensions]
+convert =</programlisting>
+
+    <para id="x_6ee">This will make a <command>hg convert</command> command
+      available.  The command is easy to use.  For instance, this
+      command will import the Subversion history for the Nose unit
+      testing framework into Mercurial.</para>
+
+    <screen><prompt>$</prompt> <userinput>hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen>
+
+    <para id="x_6ef">The <literal>convert</literal> extension operates
+      incrementally.  In other words, after you have run <command>hg
+	convert</command> once, running it again will import any new
+      revisions committed after the first run began.  Incremental
+      conversion will only work if you run <command>hg
+	convert</command> in the same Mercurial repository that you
+      originally used, because the <literal>convert</literal>
+      extension saves some private metadata in a
+      non-revision-controlled file named
+      <filename>.hg/shamap</filename> inside the target
+      repository.</para>
+
+    <para id="x_707">When you want to start making changes using Mercurial, it's
+      best to clone the tree in which you are doing your conversions,
+      and leave the original tree for future incremental conversions.
+      This is the safest way to let you pull and merge future commits
+      from the source revision control system into your newly active
+      Mercurial project.</para>
+
+    <sect2>
+      <title>Converting multiple branches</title>
+
+      <para id="x_708">The <command>hg convert</command> command given above
+	converts only the history of the <literal>trunk</literal>
+	branch of the Subversion repository.  If we instead use the
+	URL <literal>http://python-nose.googlecode.com/svn</literal>,
+	Mercurial will automatically detect the
+	<literal>trunk</literal>, <literal>tags</literal> and
+	<literal>branches</literal> layout that Subversion projects
+	usually use, and it will import each as a separate Mercurial
+	branch.</para>
+
+      <para id="x_709">By default, each Subversion branch imported into Mercurial
+	is given a branch name.  After the conversion completes, you
+	can get a list of the active branch names in the Mercurial
+	repository using <command>hg branches -a</command>. If you
+	would prefer to import the Subversion branches without names,
+	pass the <option>--config
+	  convert.hg.usebranchnames=false</option> option to
+	<command>hg convert</command>.</para>
+
+      <para id="x_70a">Once you have converted your tree, if you want to follow
+	the usual Mercurial practice of working in a tree that
+	contains a single branch, you can clone that single branch
+	using <command>hg clone -r mybranchname</command>.</para>
+    </sect2>
+
+    <sect2>
+      <title>Mapping user names</title>
+
+      <para id="x_6f0">Some revision control tools save only short usernames with
+	commits, and these can be difficult to interpret.  The norm
+	with Mercurial is to save a committer's name and email
+	address, which is much more useful for talking to them after
+	the fact.</para>
+
+      <para id="x_6f1">If you are converting a tree from a revision control
+	system that uses short names, you can map those names to
+	longer equivalents by passing a <option>--authors</option>
+	option to <command>hg convert</command>.  This option accepts
+	a file name that should contain entries of the following
+	form.</para>
+
+      <programlisting>arist = Aristotle &lt;aristotle@phil.example.gr&gt;
+soc = Socrates &lt;socrates@phil.example.gr&gt;</programlisting>
+
+      <para id="x_6f2">Whenever <literal>convert</literal> encounters a commit
+	with the username <literal>arist</literal> in the source
+	repository, it will use the name <literal>Aristotle
+	  &lt;aristotle@phil.example.gr&gt;</literal> in the converted
+	Mercurial revision.  If no match is found for a name, it is
+	used verbatim.</para>
+    </sect2>
+
+    <sect2 id="svn.filemap">
+      <title>Tidying up the tree</title>
+
+      <para id="x_6f3">Not all projects have pristine history.  There may be a
+	directory that should never have been checked in, a file that
+	is too big, or a whole hierarchy that needs to be
+	refactored.</para>
+
+      <para id="x_6f4">The <literal>convert</literal> extension supports the idea
+	of a <quote>file map</quote> that can reorganize the files and
+	directories in a project as it imports the project's history.
+	This is useful not only when importing history from other
+	revision control systems, but also to prune or refactor a
+	Mercurial tree.</para>
+
+      <para id="x_6f5">To specify a file map, use the <option>--filemap</option>
+	option and supply a file name.  A file map contains lines of the
+	following forms.</para>
+
+      <programlisting># This is a comment.
+# Empty lines are ignored.	
+
+include path/to/file
+
+exclude path/to/file
+
+rename from/some/path to/some/other/place
+</programlisting>
+
+      <para id="x_6f6">The <literal>include</literal> directive causes a file, or
+	all files under a directory, to be included in the destination
+	repository.  This also excludes all other files and dirs not
+	explicitely included.  The <literal>exclude</literal>
+	directive causes files or directories to be omitted, and
+	others not explicitly mentioned to be included.</para>
+
+      <para id="x_6f7">To move a file or directory from one location to another,
+	use the <literal>rename</literal> directive.  If you need to
+	move a file or directory from a subdirectory into the root of
+	the repository, use <literal>.</literal> as the second
+	argument to the <literal>rename</literal> directive.</para>
+    </sect2>
+
+    <sect2>
+      <title>Improving Subversion conversion performance</title>
+
+      <para id="x_70b">You will often need several attempts before you hit the
+	perfect combination of user map, file map, and other
+	conversion parameters.  Converting a Subversion repository
+	over an access protocol like <literal>ssh</literal> or
+	<literal>http</literal> can proceed thousands of times more
+	slowly than Mercurial is capable of actually operating, due to
+	network delays.  This can make tuning that perfect conversion
+	recipe very painful.</para>
+
+      <para id="x_70c">The <ulink
+	  url="http://svn.collab.net/repos/svn/trunk/notes/svnsync.txt"><command>svnsync</command></ulink> 
+	command can greatly speed up the conversion of a Subversion
+	repository.  It is a read-only mirroring program for
+	Subversion repositories.  The idea is that you create a local
+	mirror of your Subversion tree, then convert the mirror into a
+	Mercurial repository.</para>
+
+      <para id="x_70d">Suppose we want to convert the Subversion repository for
+	the popular Memcached project into a Mercurial tree.  First,
+	we create a local Subversion repository.</para>
+
+      <screen><prompt>$</prompt> <userinput>svnadmin create memcached-mirror</userinput></screen>
+
+      <para id="x_70e">Next, we set up a Subversion hook that
+	<command>svnsync</command> needs.</para>
+
+      <screen><prompt>$</prompt> <userinput>echo '#!/bin/sh' > memcached-mirror/hooks/pre-revprop-change</userinput>
+<prompt>$</prompt> <userinput>chmod +x memcached-mirror/hooks/pre-revprop-change</userinput></screen>
+
+      <para id="x_70f">We then initialize <command>svnsync</command> in this
+	repository.</para>
+
+      <screen><prompt>$</prompt> <userinput>svnsync --init file://`pwd`/memcached-mirror \
+  http://code.sixapart.com/svn/memcached</userinput></screen>
+
+      <para id="x_710">Our next step is to begin the <command>svnsync</command>
+	mirroring process.</para>
+
+      <screen><prompt>$</prompt> <userinput>svnsync sync file://`pwd`/memcached-mirror</userinput></screen>
+
+      <para id="x_711">Finally, we import the history of our local Subversion
+	mirror into Mercurial.</para>
+
+      <screen><prompt>$</prompt> <userinput>hg convert memcached-mirror</userinput></screen>
+      
+      <para id="x_712">We can use this process incrementally if the Subversion
+	repository is still in use.  We run <command>svnsync</command>
+	to pull new changes into our mirror, then <command>hg
+	  convert</command> to import them into our Mercurial
+	tree.</para>
+
+      <para id="x_713">There are two advantages to doing a two-stage import with
+	<command>svnsync</command>.  The first is that it uses more
+	efficient Subversion network syncing code than <command>hg
+	  convert</command>, so it transfers less data over the
+	network.  The second is that the import from a local
+	Subversion tree is so fast that you can tweak your conversion
+	setup repeatedly without having to sit through a painfully
+	slow network-based conversion process each time.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Migrating from Subversion</title>
+
+    <para id="x_6f8">Subversion is currently the most popular open source
+      revision control system. Although there are many differences
+      between Mercurial and Subversion, making the transition from
+      Subversion to Mercurial is not particularly difficult.  The two
+      have similar command sets and generally uniform
+      interfaces.</para>
+
+    <sect2>
+      <title>Philosophical differences</title>
+
+      <para id="x_6f9">The fundamental difference between Subversion and
+	Mercurial is of course that Subversion is centralized, while
+	Mercurial is distributed.  Since Mercurial stores all of a
+	project's history on your local drive, it only needs to
+	perform a network access when you want to explicitly
+	communicate with another repository. In contrast, Subversion
+	stores very little information locally, and the client must
+	thus contact its server for many common operations.</para>
+
+      <para id="x_6fa">Subversion more or less gets away without a well-defined
+	notion of a branch: which portion of a server's namespace
+	qualifies as a branch is a matter of convention, with the
+	software providing no enforcement.  Mercurial treats a
+	repository as the unit of branch management.</para>
+
+      <sect3>
+	<title>Scope of commands</title>
+
+	<para id="x_6fb">Since Subversion doesn't know what parts of its
+	  namespace are really branches, it treats most commands as
+	  requests to operate at and below whatever directory you are
+	  currently visiting.  For instance, if you run <command>svn
+	    log</command>, you'll get the history of whatever part of
+	  the tree you're looking at, not the tree as a whole.</para>
+
+	<para id="x_6fc">Mercurial's commands behave differently, by defaulting
+	  to operating over an entire repository.  Run <command>hg
+	    log</command> and it will tell you the history of the
+	  entire tree, no matter what part of the working directory
+	  you're visiting at the time.  If you want the history of
+	  just a particular file or directory, simply supply it by
+	  name, e.g. <command>hg log src</command>.</para>
+
+	<para id="x_6fd">From my own experience, this difference in default
+	  behaviors is probably the most likely to trip you up if you
+	  have to switch back and forth frequently between the two
+	  tools.</para>
+      </sect3>
+
+      <sect3>
+	<title>Multi-user operation and safety</title>
+
+	<para id="x_6fe">With Subversion, it is normal (though slightly frowned
+	  upon) for multiple people to collaborate in a single branch.
+	  If Alice and Bob are working together, and Alice commits
+	  some changes to their shared branch, Bob must update his
+	  client's view of the branch before he can commit.  Since at
+	  this time he has no permanent record of the changes he has
+	  made, he can corrupt or lose his modifications during and
+	  after his update.</para>
+
+	<para id="x_6ff">Mercurial encourages a commit-then-merge model instead.
+	  Bob commits his changes locally before pulling changes from,
+	  or pushing them to, the server that he shares with Alice.
+	  If Alice pushed her changes before Bob tries to push his, he
+	  will not be able to push his changes until he pulls hers,
+	  merges with them, and commits the result of the merge.  If
+	  he makes a mistake during the merge, he still has the option
+	  of reverting to the commit that recorded his changes.</para>
+
+	<para id="x_700">It is worth emphasizing that these are the common ways
+	  of working with these tools. Subversion supports a safer
+	  work-in-your-own-branch model, but it is cumbersome enough
+	  in practice to not be widely used.  Mercurial can support
+	  the less safe mode of allowing changes to be pulled in and
+	  merged on top of uncommitted edits, but this is considered
+	  highly unusual.</para>
+      </sect3>
+
+      <sect3>
+	<title>Published vs local changes</title>
+
+	<para id="x_701">A Subversion <command>svn commit</command> command
+	  immediately publishes changes to a server, where they can be
+	  seen by everyone who has read access.</para>
+
+	<para id="x_702">With Mercurial, commits are always local, and must be
+	  published via a <command>hg push</command> command
+	  afterwards.</para>
+
+	<para id="x_703">Each approach has its advantages and disadvantages.  The
+	  Subversion model means that changes are published, and hence
+	  reviewable and usable, immediately.  On the other hand, this
+	  means that a user must have commit access to a repository in
+	  order to use the software in a normal way, and commit access
+	  is not lightly given out by most open source
+	  projects.</para>
+
+	<para id="x_704">The Mercurial approach allows anyone who can clone a
+	  repository to commit changes without the need for someone
+	  else's permission, and they can then publish their changes
+	  and continue to participate however they see fit.  The
+	  distinction between committing and pushing does open up the
+	  possibility of someone committing changes to their laptop
+	  and walking away for a few days having forgotten to push
+	  them, which in rare cases might leave collaborators
+	  temporarily stuck.</para>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Quick reference</title>
+
+      <table>
+	<title>Subversion commands and Mercurial equivalents</title>
+	<tgroup cols="3">
+	  <thead>
+	    <row>
+	      <entry>Subversion</entry>
+	      <entry>Mercurial</entry>
+	      <entry>Notes</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry><command>svn add</command></entry>
+	      <entry><command>hg add</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn blame</command></entry>
+	      <entry><command>hg annotate</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn cat</command></entry>
+	      <entry><command>hg cat</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn checkout</command></entry>
+	      <entry><command>hg clone</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn cleanup</command></entry>
+	      <entry>n/a</entry>
+	      <entry>No cleanup needed</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn commit</command></entry>
+	      <entry><command>hg commit</command>; <command>hg
+		  push</command></entry>
+	      <entry><command>hg push</command> publishes after
+		commit</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn copy</command></entry>
+	      <entry><command>hg clone</command></entry>
+	      <entry>To create a new branch</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn copy</command></entry>
+	      <entry><command>hg copy</command></entry>
+	      <entry>To copy files or directories</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn delete</command> (<command>svn
+		  remove</command>)</entry>
+	      <entry><command>hg remove</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn diff</command></entry>
+	      <entry><command>hg diff</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn export</command></entry>
+	      <entry><command>hg archive</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn help</command></entry>
+	      <entry><command>hg help</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn import</command></entry>
+	      <entry><command>hg addremove</command>; <command>hg
+		  commit</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn info</command></entry>
+	      <entry><command>hg parents</command></entry>
+	      <entry>Shows what revision is checked out</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn info</command></entry>
+	      <entry><command>hg showconfig
+		  paths.parent</command></entry>
+	      <entry>Shows what URL is checked out</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn list</command></entry>
+	      <entry><command>hg manifest</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn log</command></entry>
+	      <entry><command>hg log</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn merge</command></entry>
+	      <entry><command>hg merge</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn mkdir</command></entry>
+	      <entry>n/a</entry>
+	      <entry>Mercurial does not track directories</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn move</command> (<command>svn
+		  rename</command>)</entry>
+	      <entry><command>hg rename</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn resolved</command></entry>
+	      <entry><command>hg resolve -m</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn revert</command></entry>
+	      <entry><command>hg revert</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn status</command></entry>
+	      <entry><command>hg status</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn update</command></entry>
+	      <entry><command>hg pull -u</command></entry>
+	      <entry></entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Useful tips for newcomers</title>
+
+    <para id="x_705">Under some revision control systems, printing a diff for a
+      single committed revision can be painful. For instance, with
+      Subversion, to see what changed in revision 104654, you must
+      type <command>svn diff -r104653:104654</command>. Mercurial
+      eliminates the need to type the revision ID twice in this common
+      case. For a plain diff, <command>hg export 104654</command>. For
+      a log message followed by a diff, <command>hg log -r104654
+	-p</command>.</para>
+
+    <para id="x_706">When you run <command>hg status</command> without any
+      arguments, it prints the status of the entire tree, with paths
+      relative to the root of the repository.  This makes it tricky to
+      copy a file name from the output of <command>hg status</command>
+      into the command line.  If you supply a file or directory name
+      to <command>hg status</command>, it will print paths relative to
+      your current location instead.  So to get tree-wide status from
+      <command>hg status</command>, with paths that are relative to
+      your current directory and not the root of the repository, feed
+      the output of <command>hg root</command> into <command>hg
+	status</command>.  You can easily do this as follows on a
+      Unix-like system:</para>
+
+    <screen><prompt>$</prompt> <userinput>hg status `hg root`</userinput></screen>
+  </sect1>
+</appendix>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "appendix")
+end:
+-->

en/appB-mq-ref.xml

 
     </sect2>
     <sect2>
+      <title><command role="hg-ext-mq">qfold</command>&emdash;move
+	applied patches into repository history</title>
+
+      <para id="x_72d">The <command>hg qfinish</command> command converts the
+	specified applied patches into permanent changes by moving
+	them out of MQ's control so that they will be treated as
+	normal repository history.</para>
+    </sect2>
+
+    <sect2>
       <title><command role="hg-ext-mq">qfold</command>&emdash;merge
 	(<quote>fold</quote>) several patches into one</title>
 
 	    no such text, a default commit message is used that
 	    identifies the name of the patch.</para>
 	</listitem></itemizedlist>
-      <para id="x_615">If a patch contains a Mercurial patch header (XXX add
-	link), the information in the patch header overrides these
+      <para id="x_615">If a patch contains a Mercurial patch header,
+	the information in the patch header overrides these
 	defaults.</para>
 
       <para id="x_616">Options:</para>
 
     </sect2>
     <sect2>
-      <title><command
-	  role="hg-ext-mq">qrestore</command>&emdash;restore saved
-	queue state</title>
-
-      <para id="x_628">XXX No idea what this does.</para>
-
-    </sect2>
-    <sect2>
-      <title><command role="hg-ext-mq">qsave</command>&emdash;save
-	current queue state</title>
-
-      <para id="x_629">XXX Likewise.</para>
-
-    </sect2>
-    <sect2>
       <title><command role="hg-ext-mq">qseries</command>&emdash;print
 	the entire patch series</title>
 
 	    changesets in the backup bundle.</para>
 	</listitem>
 	<listitem><para id="x_631"><option role="hg-opt-strip">-f</option>: If a
-	    branch has multiple heads, remove all heads. XXX This
-	    should be renamed, and use <literal>-f</literal> to strip
-	    revs when there are pending changes.</para>
+	    branch has multiple heads, remove all heads.</para>
 	</listitem>
 	<listitem><para id="x_632"><option role="hg-opt-strip">-n</option>: Do
 	    not save a backup bundle.</para>

en/ch00-preface.xml

   <title>Preface</title>
 
   <sect1>
-    <title>Why revision control? Why Mercurial?</title>
+    <title>Technical storytelling</title>
 
-    <para id="x_6d">Revision control is the process of managing multiple
-      versions of a piece of information.  In its simplest form, this
-      is something that many people do by hand: every time you modify
-      a file, save it under a new name that contains a number, each
-      one higher than the number of the preceding version.</para>
+    <para id="x_72e">A few years ago, when I wanted to explain why I believed
+      that distributed revision control is important, the field was
+      then so new that there was almost no published literature to
+      refer people to.</para>
 
-    <para id="x_6e">Manually managing multiple versions of even a single file is
-      an error-prone task, though, so software tools to help automate
-      this process have long been available.  The earliest automated
-      revision control tools were intended to help a single user to
-      manage revisions of a single file.  Over the past few decades,
-      the scope of revision control tools has expanded greatly; they
-      now manage multiple files, and help multiple people to work
-      together.  The best modern revision control tools have no
-      problem coping with thousands of people working together on
-      projects that consist of hundreds of thousands of files.</para>
+    <para id="x_72f">Although at that time I spent some time working on the
+      internals of Mercurial itself, I switched to writing this book
+      because that seemed like the most effective way to help the
+      software to reach a wide audience, along with the idea that
+      revision control ought to be distributed in nature.  I publish
+      the book online under a liberal license for the same
+      reason: to get the word out.</para>
 
-    <para id="x_6f">The arrival of distributed revision control is relatively
-      recent, and so far this new field has grown due to people's
-      willingness to explore ill-charted territory.</para>
+    <para id="x_730">There's a familiar rhythm to a good software book that
+      closely resembles telling a story: What is this thing?  Why does
+      it matter?  How will it help me?  How do I use it?  In this
+      book, I try to answer those questions for distributed revision
+      control in general, and for Mercurial in particular.</para>
+  </sect1>
+    
+  <sect1>
+    <title>Thank you for supporting Mercurial</title>
 
-    <para id="x_70">I am writing a book about distributed revision control
-      because I believe that it is an important subject that deserves
-      a field guide. I chose to write about Mercurial because it is
-      the easiest tool to learn the terrain with, and yet it scales to
-      the demands of real, challenging environments where many other
-      revision control tools buckle.</para>
-
-    <sect2>
-      <title>Why use revision control?</title>
-
-      <para id="x_71">There are a number of reasons why you or your team might
-	want to use an automated revision control tool for a
-	project.</para>
-
-      <itemizedlist>
-	<listitem><para id="x_72">It will track the history and evolution of
-	    your project, so you don't have to.  For every change,
-	    you'll have a log of <emphasis>who</emphasis> made it;
-	    <emphasis>why</emphasis> they made it;
-	    <emphasis>when</emphasis> they made it; and
-	    <emphasis>what</emphasis> the change
-	    was.</para></listitem>
-	<listitem><para id="x_73">When you're working with other people,
-	    revision control software makes it easier for you to
-	    collaborate.  For example, when people more or less
-	    simultaneously make potentially incompatible changes, the
-	    software will help you to identify and resolve those
-	    conflicts.</para></listitem>
-	<listitem><para id="x_74">It can help you to recover from mistakes.  If
-	    you make a change that later turns out to be in error, you
-	    can revert to an earlier version of one or more files.  In
-	    fact, a <emphasis>really</emphasis> good revision control
-	    tool will even help you to efficiently figure out exactly
-	    when a problem was introduced (see <xref
-	      linkend="sec:undo:bisect"/> for details).</para></listitem>
-	<listitem><para id="x_75">It will help you to work simultaneously on,
-	    and manage the drift between, multiple versions of your
-	    project.</para></listitem>
-      </itemizedlist>
-
-      <para id="x_76">Most of these reasons are equally
-	valid&emdash;at least in theory&emdash;whether you're working
-	on a project by yourself, or with a hundred other
-	people.</para>
-
-      <para id="x_77">A key question about the practicality of revision control
-	at these two different scales (<quote>lone hacker</quote> and
-	<quote>huge team</quote>) is how its
-	<emphasis>benefits</emphasis> compare to its
-	<emphasis>costs</emphasis>.  A revision control tool that's
-	difficult to understand or use is going to impose a high
-	cost.</para>
-
-      <para id="x_78">A five-hundred-person project is likely to collapse under
-	its own weight almost immediately without a revision control
-	tool and process. In this case, the cost of using revision
-	control might hardly seem worth considering, since
-	<emphasis>without</emphasis> it, failure is almost
-	guaranteed.</para>
-
-      <para id="x_79">On the other hand, a one-person <quote>quick hack</quote>
-	might seem like a poor place to use a revision control tool,
-	because surely the cost of using one must be close to the
-	overall cost of the project.  Right?</para>
-
-      <para id="x_7a">Mercurial uniquely supports <emphasis>both</emphasis> of
-	these scales of development.  You can learn the basics in just
-	a few minutes, and due to its low overhead, you can apply
-	revision control to the smallest of projects with ease.  Its
-	simplicity means you won't have a lot of abstruse concepts or
-	command sequences competing for mental space with whatever
-	you're <emphasis>really</emphasis> trying to do.  At the same
-	time, Mercurial's high performance and peer-to-peer nature let
-	you scale painlessly to handle large projects.</para>
-
-      <para id="x_7b">No revision control tool can rescue a poorly run project,
-	but a good choice of tools can make a huge difference to the
-	fluidity with which you can work on a project.</para>
-
-    </sect2>
-
-    <sect2>
-      <title>The many names of revision control</title>
-
-      <para id="x_7c">Revision control is a diverse field, so much so that it is
-	referred to by many names and acronyms.  Here are a few of the
-	more common variations you'll encounter:</para>
-      <itemizedlist>
-	<listitem><para id="x_7d">Revision control (RCS)</para></listitem>
-	<listitem><para id="x_7e">Software configuration management (SCM), or
-	    configuration management</para></listitem>
-	<listitem><para id="x_7f">Source code management</para></listitem>
-	<listitem><para id="x_80">Source code control, or source
-	    control</para></listitem>
-	<listitem><para id="x_81">Version control
-	    (VCS)</para></listitem></itemizedlist>
-      <para id="x_82">Some people claim that these terms actually have different
-	meanings, but in practice they overlap so much that there's no
-	agreed or even useful way to tease them apart.</para>
-
-    </sect2>
+    <para id="x_731">By purchasing a copy of this book, you are supporting the
+      continued development and freedom of Mercurial in particular,
+      and of open source and free software in general. O'Reilly Media
+      and I are donating my royalties on the sales of this book to the
+      Software Freedom Conservancy (<ulink
+	url="http://www.softwarefreedom.org/">http://www.softwarefreedom.org/</ulink>) 
+      which provides clerical and legal support to Mercurial and a
+      number of other prominent and worthy open source software
+      projects.</para>
   </sect1>
 
   <sect1>
-    <title>This book is a work in progress</title>
+    <title>Acknowledgments</title>
 
-    <para id="x_83">I am releasing this book while I am still writing it, in the
-      hope that it will prove useful to others.  I am writing under an
-      open license in the hope that you, my readers, will contribute
-      feedback and perhaps content of your own.</para>
+    <para id="x_732">This book would not exist were it not for the efforts of
+      Matt Mackall, the author and project lead of Mercurial.  He is
+      ably assisted by hundreds of volunteer contributors across the
+      world.</para>
 
-  </sect1>
-  <sect1>
-    <title>About the examples in this book</title>
+    <para id="x_733">My children, Cian and Ruairi, always stood ready to help me
+      to unwind with wonderful, madcap little-boy games.  I'd also
+      like to thank my ex-wife, Shannon, for her support.</para>
 
-    <para id="x_84">This book takes an unusual approach to code samples.  Every
-      example is <quote>live</quote>&emdash;each one is actually the result
-      of a shell script that executes the Mercurial commands you see.
-      Every time an image of the book is built from its sources, all
-      the example scripts are automatically run, and their current
-      results compared against their expected results.</para>
+    <para id="x_734">My colleagues and friends provided help and support in
+      innumerable ways.  This list of people is necessarily very
+      incomplete: Stephen Hahn, Karyn Ritter, Bonnie Corwin, James
+      Vasile, Matt Norwood, Eben Moglen, Bradley Kuhn, Robert Walsh,
+      Jeremy Fitzhardinge, Rachel Chalmers.</para>
 
-    <para id="x_85">The advantage of this approach is that the examples are
-      always accurate; they describe <emphasis>exactly</emphasis> the
-      behavior of the version of Mercurial that's mentioned at the
-      front of the book.  If I update the version of Mercurial that
-      I'm documenting, and the output of some command changes, the
-      build fails.</para>
+    <para id="x_735">I developed this book in the open, posting drafts of
+      chapters to the book web site as I completed them.  Readers then
+      submitted feedback using a web application that I developed.  By
+      the time I finished writing the book, more than 100 people had
+      submitted comments, an amazing number considering that the
+      comment system was live for only about two months towards the
+      end of the writing process.</para>
 
-    <para id="x_86">There is a small disadvantage to this approach, which is
-      that the dates and times you'll see in examples tend to be
-      <quote>squashed</quote> together in a way that they wouldn't be
-      if the same commands were being typed by a human.  Where a human
-      can issue no more than one command every few seconds, with any
-      resulting timestamps correspondingly spread out, my automated
-      example scripts run many commands in one second.</para>
+    <para id="x_736">I would particularly like to recognize the following people,
+      who between them contributed over a third of the total number of
+      comments.  I would like to thank them for their care and effort
+      in providing so much detailed feedback.</para>
 
-    <para id="x_87">As an instance of this, several consecutive commits in an
-      example can show up as having occurred during the same second.
-      You can see this occur in the <literal
-	role="hg-ext">bisect</literal> example in <xref
-	linkend="sec:undo:bisect"/>, for instance.</para>
+    <para id="x_737">Martin Geisler, Damien Cassou, Alexey Bakhirkin, Till Plewe,
+      Dan Himes, Paul Sargent, Gokberk Hamurcu, Matthijs van der
+      Vleuten, Michael Chermside, John Mulligan, Jordi Fita, Jon
+      Parise.</para>
 
-    <para id="x_88">So when you're reading examples, don't place too much weight
-      on the dates or times you see in the output of commands.  But
-      <emphasis>do</emphasis> be confident that the behavior you're
-      seeing is consistent and reproducible.</para>
+    <para id="x_738">I also want to acknowledge the help of the many people who
+      caught errors and provided helpful suggestions throughout the
+      book.</para>
 
+    <para id="x_739">Jeremy W. Sherman, Brian Mearns, Vincent Furia, Iwan
+      Luijks, Billy Edwards, Andreas Sliwka, Paweł Sołyga, Eric
+      Hanchrow, Steve Nicolai, Michał Masłowski, Kevin Fitch, Johan
+      Holmberg, Hal Wine, Volker Simonis, Thomas P Jakobsen, Ted
+      Stresen-Reuter, Stephen Rasku, Raphael Das Gupta, Ned
+      Batchelder, Lou Keeble, Li Linxiao, Kao Cardoso Félix, Joseph
+      Wecker, Jon Prescot, Jon Maken, John Yeary, Jason Harris,
+      Geoffrey Zheng, Fredrik Jonson, Ed Davies, David Zumbrunnen,
+      David Mercer, David Cabana, Ben Karel, Alan Franzoni, Yousry
+      Abdallah, Whitney Young, Vinay Sajip, Tom Towle, Tim Ottinger,
+      Thomas Schraitle, Tero Saarni, Ted Mielczarek, Svetoslav
+      Agafonkin, Shaun Rowland, Rocco Rutte, Polo-Francois Poli,
+      Philip Jenvey, Petr Tesałék, Peter R. Annema, Paul Bonser,
+      Olivier Scherler, Olivier Fournier, Nick Parker, Nick Fabry,
+      Nicholas Guarracino, Mike Driscoll, Mike Coleman, Mietek Bák,
+      Michael Maloney, László Nagy, Kent Johnson, Julio Nobrega, Jord
+      Fita, Jonathan March, Jonas Nockert, Jim Tittsler, Jeduan
+      Cornejo Legorreta, Jan Larres, James Murphy, Henri Wiechers,
+      Hagen Möbius, Gábor Farkas, Fabien Engels, Evert Rol, Evan
+      Willms, Eduardo Felipe Castegnaro, Dennis Decker Jensen, Deniz
+      Dogan, David Smith, Daed Lee, Christine Slotty, Charles Merriam,
+      Guillaume Catto, Brian Dorsey, Bob Nystrom, Benoit Boissinot,
+      Avi Rosenschein, Andrew Watts, Andrew Donkin, Alexey Rodriguez,
+      Ahmed Chaudhary.</para>
   </sect1>
 
   <sect1>
-    <title>Trends in the field</title>
+    <title>Conventions Used in This Book</title>
 
-    <para id="x_89">There has been an unmistakable trend in the development and
-      use of revision control tools over the past four decades, as
-      people have become familiar with the capabilities of their tools
-      and constrained by their limitations.</para>
+    <para id="x_73a">The following typographical conventions are used in this
+      book:</para>
 
-    <para id="x_8a">The first generation began by managing single files on
-      individual computers.  Although these tools represented a huge
-      advance over ad-hoc manual revision control, their locking model
-      and reliance on a single computer limited them to small,
-      tightly-knit teams.</para>
+    <variablelist>
+      <varlistentry>
+        <term>Italic</term>
 
-    <para id="x_8b">The second generation loosened these constraints by moving
-      to network-centered architectures, and managing entire projects
-      at a time.  As projects grew larger, they ran into new problems.
-      With clients needing to talk to servers very frequently, server
-      scaling became an issue for large projects.  An unreliable
-      network connection could prevent remote users from being able to
-      talk to the server at all.  As open source projects started
-      making read-only access available anonymously to anyone, people
-      without commit privileges found that they could not use the
-      tools to interact with a project in a natural way, as they could
-      not record their changes.</para>
+        <listitem>
+          <para id="x_73b">Indicates new terms, URLs, email addresses, filenames,
+	    and file extensions.</para>
+        </listitem>
+      </varlistentry>
 
-    <para id="x_8c">The current generation of revision control tools is
-      peer-to-peer in nature.  All of these systems have dropped the
-      dependency on a single central server, and allow people to
-      distribute their revision control data to where it's actually
-      needed.  Collaboration over the Internet has moved from
-      constrained by technology to a matter of choice and consensus.
-      Modern tools can operate offline indefinitely and autonomously,
-      with a network connection only needed when syncing changes with
-      another repository.</para>
+      <varlistentry>
+        <term><literal>Constant width</literal></term>
 
-  </sect1>
-  <sect1>
-    <title>A few of the advantages of distributed revision
-      control</title>
+        <listitem>
+          <para id="x_73c">Used for program listings, as well as within
+	    paragraphs to refer to program elements such as variable
+	    or function names, databases, data types, environment
+	    variables, statements, and keywords.</para>
+        </listitem>
+      </varlistentry>
 
-    <para id="x_8d">Even though distributed revision control tools have for
-      several years been as robust and usable as their
-      previous-generation counterparts, people using older tools have
-      not yet necessarily woken up to their advantages.  There are a
-      number of ways in which distributed tools shine relative to
-      centralised ones.</para>
+      <varlistentry>
+        <term><userinput>Constant width bold</userinput></term>
 
-    <para id="x_8e">For an individual developer, distributed tools are almost
-      always much faster than centralised tools.  This is for a simple
-      reason: a centralised tool needs to talk over the network for
-      many common operations, because most metadata is stored in a
-      single copy on the central server.  A distributed tool stores
-      all of its metadata locally.  All else being equal, talking over
-      the network adds overhead to a centralised tool.  Don't
-      underestimate the value of a snappy, responsive tool: you're
-      going to spend a lot of time interacting with your revision
-      control software.</para>
+        <listitem>
+          <para id="x_73d">Shows commands or other text that should be typed
+	    literally by the user.</para>
+        </listitem>
+      </varlistentry>
 
-    <para id="x_8f">Distributed tools are indifferent to the vagaries of your
-      server infrastructure, again because they replicate metadata to
-      so many locations.  If you use a centralised system and your
-      server catches fire, you'd better hope that your backup media
-      are reliable, and that your last backup was recent and actually
-      worked.  With a distributed tool, you have many backups
-      available on every contributor's computer.</para>
+      <varlistentry>
+        <term><replaceable>Constant width italic</replaceable></term>
 
-    <para id="x_90">The reliability of your network will affect distributed
-      tools far less than it will centralised tools.  You can't even
-      use a centralised tool without a network connection, except for
-      a few highly constrained commands.  With a distributed tool, if
-      your network connection goes down while you're working, you may
-      not even notice.  The only thing you won't be able to do is talk
-      to repositories on other computers, something that is relatively
-      rare compared with local operations.  If you have a far-flung
-      team of collaborators, this may be significant.</para>
+        <listitem>
+          <para id="x_73e">Shows text that should be replaced with user-supplied
+	    values or by values determined by context.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
 
-    <sect2>
-      <title>Advantages for open source projects</title>
+    <tip>
+      <para id="x_73f">This icon signifies a tip, suggestion, or general
+	note.</para>
+    </tip>
 
-      <para id="x_91">If you take a shine to an open source project and decide
-	that you would like to start hacking on it, and that project
-	uses a distributed revision control tool, you are at once a
-	peer with the people who consider themselves the
-	<quote>core</quote> of that project.  If they publish their
-	repositories, you can immediately copy their project history,
-	start making changes, and record your work, using the same
-	tools in the same ways as insiders.  By contrast, with a
-	centralised tool, you must use the software in a <quote>read
-	  only</quote> mode unless someone grants you permission to
-	commit changes to their central server.  Until then, you won't
-	be able to record changes, and your local modifications will
-	be at risk of corruption any time you try to update your
-	client's view of the repository.</para>
-
-      <sect3>
-	<title>The forking non-problem</title>
-
-	<para id="x_92">It has been suggested that distributed revision control
-	  tools pose some sort of risk to open source projects because
-	  they make it easy to <quote>fork</quote> the development of
-	  a project.  A fork happens when there are differences in
-	  opinion or attitude between groups of developers that cause
-	  them to decide that they can't work together any longer.
-	  Each side takes a more or less complete copy of the
-	  project's source code, and goes off in its own
-	  direction.</para>
-
-	<para id="x_93">Sometimes the camps in a fork decide to reconcile their
-	  differences. With a centralised revision control system, the
-	  <emphasis>technical</emphasis> process of reconciliation is
-	  painful, and has to be performed largely by hand.  You have
-	  to decide whose revision history is going to
-	  <quote>win</quote>, and graft the other team's changes into
-	  the tree somehow. This usually loses some or all of one
-	  side's revision history.</para>
-
-	<para id="x_94">What distributed tools do with respect to forking is
-	  they make forking the <emphasis>only</emphasis> way to
-	  develop a project.  Every single change that you make is
-	  potentially a fork point.  The great strength of this
-	  approach is that a distributed revision control tool has to
-	  be really good at <emphasis>merging</emphasis> forks,
-	  because forks are absolutely fundamental: they happen all
-	  the time.</para>
-
-	<para id="x_95">If every piece of work that everybody does, all the
-	  time, is framed in terms of forking and merging, then what
-	  the open source world refers to as a <quote>fork</quote>
-	  becomes <emphasis>purely</emphasis> a social issue.  If
-	  anything, distributed tools <emphasis>lower</emphasis> the
-	  likelihood of a fork:</para>
-	<itemizedlist>
-	  <listitem><para id="x_96">They eliminate the social distinction that
-	      centralised tools impose: that between insiders (people
-	      with commit access) and outsiders (people
-	      without).</para></listitem>
-	  <listitem><para id="x_97">They make it easier to reconcile after a
-	      social fork, because all that's involved from the
-	      perspective of the revision control software is just
-	      another merge.</para></listitem></itemizedlist>
-
-	<para id="x_98">Some people resist distributed tools because they want
-	  to retain tight control over their projects, and they
-	  believe that centralised tools give them this control.
-	  However, if you're of this belief, and you publish your CVS
-	  or Subversion repositories publicly, there are plenty of
-	  tools available that can pull out your entire project's
-	  history (albeit slowly) and recreate it somewhere that you
-	  don't control.  So while your control in this case is
-	  illusory, you are forgoing the ability to fluidly
-	  collaborate with whatever people feel compelled to mirror
-	  and fork your history.</para>
-
-      </sect3>
-    </sect2>
-    <sect2>
-      <title>Advantages for commercial projects</title>
-
-      <para id="x_99">Many commercial projects are undertaken by teams that are
-	scattered across the globe.  Contributors who are far from a
-	central server will see slower command execution and perhaps
-	less reliability.  Commercial revision control systems attempt
-	to ameliorate these problems with remote-site replication
-	add-ons that are typically expensive to buy and cantankerous
-	to administer.  A distributed system doesn't suffer from these
-	problems in the first place.  Better yet, you can easily set
-	up multiple authoritative servers, say one per site, so that
-	there's no redundant communication between repositories over
-	expensive long-haul network links.</para>
-
-      <para id="x_9a">Centralised revision control systems tend to have
-	relatively low scalability.  It's not unusual for an expensive
-	centralised system to fall over under the combined load of
-	just a few dozen concurrent users.  Once again, the typical
-	response tends to be an expensive and clunky replication
-	facility.  Since the load on a central server&emdash;if you have
-	one at all&emdash;is many times lower with a distributed tool
-	(because all of the data is replicated everywhere), a single
-	cheap server can handle the needs of a much larger team, and
-	replication to balance load becomes a simple matter of
-	scripting.</para>
-
-      <para id="x_9b">If you have an employee in the field, troubleshooting a
-	problem at a customer's site, they'll benefit from distributed
-	revision control. The tool will let them generate custom
-	builds, try different fixes in isolation from each other, and
-	search efficiently through history for the sources of bugs and
-	regressions in the customer's environment, all without needing
-	to connect to your company's network.</para>
-
-    </sect2>
-  </sect1>
-  <sect1>
-    <title>Why choose Mercurial?</title>
-
-    <para id="x_9c">Mercurial has a unique set of properties that make it a
-      particularly good choice as a revision control system.</para>
-    <itemizedlist>
-      <listitem><para id="x_9d">It is easy to learn and use.</para></listitem>
-      <listitem><para id="x_9e">It is lightweight.</para></listitem>
-      <listitem><para id="x_9f">It scales excellently.</para></listitem>
-      <listitem><para id="x_a0">It is easy to
-	  customise.</para></listitem></itemizedlist>
-
-    <para id="x_a1">If you are at all familiar with revision control systems,
-      you should be able to get up and running with Mercurial in less
-      than five minutes.  Even if not, it will take no more than a few
-      minutes longer.  Mercurial's command and feature sets are
-      generally uniform and consistent, so you can keep track of a few
-      general rules instead of a host of exceptions.</para>
-
-    <para id="x_a2">On a small project, you can start working with Mercurial in
-      moments. Creating new changes and branches; transferring changes
-      around (whether locally or over a network); and history and
-      status operations are all fast.  Mercurial attempts to stay
-      nimble and largely out of your way by combining low cognitive
-      overhead with blazingly fast operations.</para>
-
-    <para id="x_a3">The usefulness of Mercurial is not limited to small
-      projects: it is used by projects with hundreds to thousands of
-      contributors, each containing tens of thousands of files and
-      hundreds of megabytes of source code.</para>
-
-    <para id="x_a4">If the core functionality of Mercurial is not enough for
-      you, it's easy to build on.  Mercurial is well suited to
-      scripting tasks, and its clean internals and implementation in
-      Python make it easy to add features in the form of extensions.
-      There are a number of popular and useful extensions already
-      available, ranging from helping to identify bugs to improving
-      performance.</para>
-
-  </sect1>
-  <sect1>
-    <title>Mercurial compared with other tools</title>
-
-    <para id="x_a5">Before you read on, please understand that this section
-      necessarily reflects my own experiences, interests, and (dare I
-      say it) biases.  I have used every one of the revision control
-      tools listed below, in most cases for several years at a
-      time.</para>
-
-
-    <sect2>
-      <title>Subversion</title>
-
-      <para id="x_a6">Subversion is a popular revision control tool, developed
-	to replace CVS.  It has a centralised client/server
-	architecture.</para>
-
-      <para id="x_a7">Subversion and Mercurial have similarly named commands for
-	performing the same operations, so if you're familiar with
-	one, it is easy to learn to use the other.  Both tools are
-	portable to all popular operating systems.</para>
-
-      <para id="x_a8">Prior to version 1.5, Subversion had no useful support for
-	merges. At the time of writing, its merge tracking capability
-	is new, and known to be <ulink
-	  url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword">complicated 
-	  and buggy</ulink>.</para>
-
-      <para id="x_a9">Mercurial has a substantial performance advantage over
-	Subversion on every revision control operation I have
-	benchmarked.  I have measured its advantage as ranging from a
-	factor of two to a factor of six when compared with Subversion
-	1.4.3's <emphasis>ra_local</emphasis> file store, which is the
-	fastest access method available.  In more realistic
-	deployments involving a network-based store, Subversion will
-	be at a substantially larger disadvantage.  Because many
-	Subversion commands must talk to the server and Subversion
-	does not have useful replication facilities, server capacity
-	and network bandwidth become bottlenecks for modestly large
-	projects.</para>
-
-      <para id="x_aa">Additionally, Subversion incurs substantial storage
-	overhead to avoid network transactions for a few common
-	operations, such as finding modified files
-	(<literal>status</literal>) and displaying modifications
-	against the current revision (<literal>diff</literal>).  As a
-	result, a Subversion working copy is often the same size as,
-	or larger than, a Mercurial repository and working directory,
-	even though the Mercurial repository contains a complete
-	history of the project.</para>
-
-      <para id="x_ab">Subversion is widely supported by third party tools.
-	Mercurial currently lags considerably in this area.  This gap
-	is closing, however, and indeed some of Mercurial's GUI tools
-	now outshine their Subversion equivalents.  Like Mercurial,
-	Subversion has an excellent user manual.</para>
-
-      <para id="x_ac">Because Subversion doesn't store revision history on the
-	client, it is well suited to managing projects that deal with
-	lots of large, opaque binary files.  If you check in fifty
-	revisions to an incompressible 10MB file, Subversion's
-	client-side space usage stays constant The space used by any
-	distributed SCM will grow rapidly in proportion to the number
-	of revisions, because the differences between each revision
-	are large.</para>
-
-      <para id="x_ad">In addition, it's often difficult or, more usually,
-	impossible to merge different versions of a binary file.
-	Subversion's ability to let a user lock a file, so that they
-	temporarily have the exclusive right to commit changes to it,
-	can be a significant advantage to a project where binary files
-	are widely used.</para>
-
-      <para id="x_ae">Mercurial can import revision history from a Subversion
-	repository. It can also export revision history to a
-	Subversion repository.  This makes it easy to <quote>test the
-	  waters</quote> and use Mercurial and Subversion in parallel
-	before deciding to switch.  History conversion is incremental,
-	so you can perform an initial conversion, then small
-	additional conversions afterwards to bring in new
-	changes.</para>
-
-
-    </sect2>
-    <sect2>
-      <title>Git</title>
-
-      <para id="x_af">Git is a distributed revision control tool that was
-	developed for managing the Linux kernel source tree.  Like
-	Mercurial, its early design was somewhat influenced by
-	Monotone.</para>
-
-      <para id="x_b0">Git has a very large command set, with version 1.5.0
-	providing 139 individual commands.  It has something of a
-	reputation for being difficult to learn.  Compared to Git,
-	Mercurial has a strong focus on simplicity.</para>
-
-      <para id="x_b1">In terms of performance, Git is extremely fast.  In
-	several cases, it is faster than Mercurial, at least on Linux,
-	while Mercurial performs better on other operations.  However,
-	on Windows, the performance and general level of support that
-	Git provides is, at the time of writing, far behind that of
-	Mercurial.</para>
-
-      <para id="x_b2">While a Mercurial repository needs no maintenance, a Git
-	repository requires frequent manual <quote>repacks</quote> of
-	its metadata.  Without these, performance degrades, while
-	space usage grows rapidly.  A server that contains many Git
-	repositories that are not rigorously and frequently repacked
-	will become heavily disk-bound during backups, and there have
-	been instances of daily backups taking far longer than 24
-	hours as a result.  A freshly packed Git repository is
-	slightly smaller than a Mercurial repository, but an unpacked
-	repository is several orders of magnitude larger.</para>
-
-      <para id="x_b3">The core of Git is written in C.  Many Git commands are
-	implemented as shell or Perl scripts, and the quality of these
-	scripts varies widely. I have encountered several instances
-	where scripts charged along blindly in the presence of errors
-	that should have been fatal.</para>
-
-      <para id="x_b4">Mercurial can import revision history from a Git
-	repository.</para>
-
-
-    </sect2>
-    <sect2>
-      <title>CVS</title>
-
-      <para id="x_b5">CVS is probably the most widely used revision control tool
-	in the world.  Due to its age and internal untidiness, it has
-	been only lightly maintained for many years.</para>
-
-      <para id="x_b6">It has a centralised client/server architecture.  It does
-	not group related file changes into atomic commits, making it
-	easy for people to <quote>break the build</quote>: one person
-	can successfully commit part of a change and then be blocked
-	by the need for a merge, causing other people to see only a
-	portion of the work they intended to do.  This also affects
-	how you work with project history.  If you want to see all of
-	the modifications someone made as part of a task, you will
-	need to manually inspect the descriptions and timestamps of
-	the changes made to each file involved (if you even know what
-	those files were).</para>
-
-      <para id="x_b7">CVS has a muddled notion of tags and branches that I will
-	not attempt to even describe.  It does not support renaming of
-	files or directories well, making it easy to corrupt a
-	repository.  It has almost no internal consistency checking
-	capabilities, so it is usually not even possible to tell
-	whether or how a repository is corrupt.  I would not recommend
-	CVS for any project, existing or new.</para>
-
-      <para id="x_b8">Mercurial can import CVS revision history.  However, there
-	are a few caveats that apply; these are true of every other
-	revision control tool's CVS importer, too.  Due to CVS's lack
-	of atomic changes and unversioned filesystem hierarchy, it is
-	not possible to reconstruct CVS history completely accurately;
-	some guesswork is involved, and renames will usually not show
-	up.  Because a lot of advanced CVS administration has to be
-	done by hand and is hence error-prone, it's common for CVS
-	importers to run into multiple problems with corrupted
-	repositories (completely bogus revision timestamps and files
-	that have remained locked for over a decade are just two of
-	the less interesting problems I can recall from personal
-	experience).</para>
-
-      <para id="x_b9">Mercurial can import revision history from a CVS
-	repository.</para>
-
-
-    </sect2>
-    <sect2>
-      <title>Commercial tools</title>
-
-      <para id="x_ba">Perforce has a centralised client/server architecture,
-	with no client-side caching of any data.  Unlike modern
-	revision control tools, Perforce requires that a user run a
-	command to inform the server about every file they intend to
-	edit.</para>
-
-      <para id="x_bb">The performance of Perforce is quite good for small teams,
-	but it falls off rapidly as the number of users grows beyond a
-	few dozen. Modestly large Perforce installations require the
-	deployment of proxies to cope with the load their users
-	generate.</para>
-
-
-    </sect2>
-    <sect2>
-      <title>Choosing a revision control tool</title>
-
-      <para id="x_bc">With the exception of CVS, all of the tools listed above
-	have unique strengths that suit them to particular styles of
-	work.  There is no single revision control tool that is best
-	in all situations.</para>
-
-      <para id="x_bd">As an example, Subversion is a good choice for working
-	with frequently edited binary files, due to its centralised
-	nature and support for file locking.</para>
-
-      <para id="x_be">I personally find Mercurial's properties of simplicity,
-	performance, and good merge support to be a compelling
-	combination that has served me well for several years.</para>
-
-
-    </sect2>
-  </sect1>
-  <sect1>
-    <title>Switching from another tool to Mercurial</title>
-
-    <para id="x_bf">Mercurial is bundled with an extension named <literal
-	role="hg-ext">convert</literal>, which can incrementally
-      import revision history from several other revision control
-      tools.  By <quote>incremental</quote>, I mean that you can
-      convert all of a project's history to date in one go, then rerun
-      the conversion later to obtain new changes that happened after
-      the initial conversion.</para>
-
-    <para id="x_c0">The revision control tools supported by <literal
-	role="hg-ext">convert</literal> are as follows:</para>
-    <itemizedlist>
-      <listitem><para id="x_c1">Subversion</para></listitem>
-      <listitem><para id="x_c2">CVS</para></listitem>
-      <listitem><para id="x_c3">Git</para></listitem>
-      <listitem><para id="x_c4">Darcs</para></listitem></itemizedlist>
-
-    <para id="x_c5">In addition, <literal role="hg-ext">convert</literal> can
-      export changes from Mercurial to Subversion.  This makes it
-      possible to try Subversion and Mercurial in parallel before
-      committing to a switchover, without risking the loss of any
-      work.</para>
-
-    <para id="x_c6">The <command role="hg-ext-convert">convert</command> command
-      is easy to use.  Simply point it at the path or URL of the
-      source repository, optionally give it the name of the
-      destination repository, and it will start working.  After the
-      initial conversion, just run the same command again to import
-      new changes.</para>
+    <caution>
+      <para id="x_740">This icon indicates a warning or caution.</para>
+    </caution>
   </sect1>
 
   <sect1>
-    <title>A short history of revision control</title>
+    <title>Using Code Examples</title>
 
-    <para id="x_c7">The best known of the old-time revision control tools is
-      SCCS (Source Code Control System), which Marc Rochkind wrote at
-      Bell Labs, in the early 1970s.  SCCS operated on individual
-      files, and required every person working on a project to have
-      access to a shared workspace on a single system.  Only one
-      person could modify a file at any time; arbitration for access
-      to files was via locks.  It was common for people to lock files,
-      and later forget to unlock them, preventing anyone else from
-      modifying those files without the help of an
-      administrator.</para>
+    <para id="x_741">This book is here to help you get your job done. In general,
+      you may use the code in this book in your programs and
+      documentation. You do not need to contact us for permission
+      unless you’re reproducing a significant portion of the code. For
+      example, writing a program that uses several chunks of code from
+      this book does not require permission. Selling or distributing a
+      CD-ROM of examples from O’Reilly books does require permission.
+      Answering a question by citing this book and quoting example
+      code does not require permission. Incorporating a significant
+      amount of example code from this book into your product’s
+      documentation does require permission.</para>
 
-    <para id="x_c8">Walter Tichy developed a free alternative to SCCS in the
-      early 1980s; he called his program RCS (Revision Control System).
-      Like SCCS, RCS required developers to work in a single shared
-      workspace, and to lock files to prevent multiple people from
-      modifying them simultaneously.</para>
+    <para id="x_742">We appreciate, but do not require, attribution. An
+      attribution usually includes the title, author, publisher, and
+      ISBN. For example: “<emphasis>Book Title</emphasis> by Some
+      Author. Copyright 2008 O’Reilly Media, Inc.,
+      978-0-596-xxxx-x.”</para>
 
-    <para id="x_c9">Later in the 1980s, Dick Grune used RCS as a building block
-      for a set of shell scripts he initially called cmt, but then
-      renamed to CVS (Concurrent Versions System).  The big innovation
-      of CVS was that it let developers work simultaneously and
-      somewhat independently in their own personal workspaces.  The
-      personal workspaces prevented developers from stepping on each
-      other's toes all the time, as was common with SCCS and RCS. Each
-      developer had a copy of every project file, and could modify
-      their copies independently.  They had to merge their edits prior
-      to committing changes to the central repository.</para>
-
-    <para id="x_ca">Brian Berliner took Grune's original scripts and rewrote
-      them in C, releasing in 1989 the code that has since developed
-      into the modern version of CVS.  CVS subsequently acquired the
-      ability to operate over a network connection, giving it a
-      client/server architecture.  CVS's architecture is centralised;
-      only the server has a copy of the history of the project. Client
-      workspaces just contain copies of recent versions of the
-      project's files, and a little metadata to tell them where the
-      server is.  CVS has been enormously successful; it is probably
-      the world's most widely used revision control system.</para>
-
-    <para id="x_cb">In the early 1990s, Sun Microsystems developed an early
-      distributed revision control system, called TeamWare.  A
-      TeamWare workspace contains a complete copy of the project's
-      history.  TeamWare has no notion of a central repository.  (CVS
-      relied upon RCS for its history storage; TeamWare used
-      SCCS.)</para>
-
-    <para id="x_cc">As the 1990s progressed, awareness grew of a number of
-      problems with CVS.  It records simultaneous changes to multiple
-      files individually, instead of grouping them together as a
-      single logically atomic operation.  It does not manage its file
-      hierarchy well; it is easy to make a mess of a repository by
-      renaming files and directories.  Worse, its source code is
-      difficult to read and maintain, which made the <quote>pain
-	level</quote> of fixing these architectural problems
-      prohibitive.</para>
-
-    <para id="x_cd">In 2001, Jim Blandy and Karl Fogel, two developers who had
-      worked on CVS, started a project to replace it with a tool that
-      would have a better architecture and cleaner code.  The result,
-      Subversion, does not stray from CVS's centralised client/server
-      model, but it adds multi-file atomic commits, better namespace
-      management, and a number of other features that make it a
-      generally better tool than CVS. Since its initial release, it
-      has rapidly grown in popularity.</para>
-
-    <para id="x_ce">More or less simultaneously, Graydon Hoare began working on
-      an ambitious distributed revision control system that he named
-      Monotone. While Monotone addresses many of CVS's design flaws
-      and has a peer-to-peer architecture, it goes beyond earlier (and
-      subsequent) revision control tools in a number of innovative
-      ways.  It uses cryptographic hashes as identifiers, and has an
-      integral notion of <quote>trust</quote> for code from different
-      sources.</para>
-
-    <para id="x_cf">Mercurial began life in 2005.  While a few aspects of its
-      design are influenced by Monotone, Mercurial focuses on ease of
-      use, high performance, and scalability to very large
-      projects.</para>
-
+    <para id="x_743">If you feel your use of code examples falls outside fair use
+      or the permission given above, feel free to contact us at
+      <email>permissions@oreilly.com</email>.</para>
   </sect1>
 
   <sect1>
-    <title>Colophon&emdash;this book is Free</title>
+    <title>Safari® Books Online</title>
 
-    <para id="x_d0">This book is licensed under the Open Publication License,
-      and is produced entirely using Free Software tools.  It is
-      typeset with DocBook XML.  Illustrations are drawn and rendered with
-      <ulink url="http://www.inkscape.org/">Inkscape</ulink>.</para>
+    <note role="safarienabled">
+      <para id="x_744">When you see a Safari® Books Online icon on the cover of
+	your favorite technology book, that means the book is
+	available online through the O’Reilly Network Safari
+	Bookshelf.</para>
+    </note>
 
-    <para id="x_d1">The complete source code for this book is published as a
-      Mercurial repository, at <ulink
-	url="http://hg.serpentine.com/mercurial/book">http://hg.serpentine.com/mercurial/book</ulink>.</para>
+    <para id="x_745">Safari offers a solution that’s better than e-books. It’s a
+      virtual library that lets you easily search thousands of top
+      tech books, cut and paste code samples, download chapters, and
+      find quick answers when you need the most accurate, current
+      information. Try it for free at <ulink role="orm:hideurl:ital"
+	url="http://my.safaribooksonline.com/?portal=oreilly">http://my.safaribooksonline.com</ulink>.</para>
+  </sect1>
 
+  <sect1>
+    <title>How to Contact Us</title>
+
+    <para id="x_746">Please address comments and questions concerning this book
+      to the publisher:</para>
+
+    <simplelist type="vert">
+      <member>O’Reilly Media, Inc.</member>
+
+      <member>1005 Gravenstein Highway North</member>
+
+      <member>Sebastopol, CA 95472</member>
+
+      <member>800-998-9938 (in the United States or Canada)</member>
+
+      <member>707-829-0515 (international or local)</member>
+
+      <member>707 829-0104 (fax)</member>
+    </simplelist>
+
+    <para id="x_747">We have a web page for this book, where we list errata,
+      examples, and any additional information. You can access this
+      page at:</para>
+
+    <simplelist type="vert">
+      <member><ulink url="http://www.oreilly.com/catalog/&lt;catalog
+	  page&gt;"></ulink></member>
+    </simplelist>
+
+    <remark>Don’t forget to update the &lt;url&gt; attribute,
+      too.</remark>
+
+    <para id="x_748">To comment or ask technical questions about this book, send
+      email to:</para>
+
+    <simplelist type="vert">
+      <member><email>bookquestions@oreilly.com</email></member>
+    </simplelist>
+
+    <para id="x_749">For more information about our books, conferences, Resource
+      Centers, and the O’Reilly Network, see our web site at:</para>
+
+    <simplelist type="vert">
+      <member><ulink url="http://www.oreilly.com"></ulink></member>
+    </simplelist>
   </sect1>
 </preface>
+
 <!--
 local variables: 
 sgml-parent-document: ("00book.xml" "book" "preface")

en/ch01-intro.xml

+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:intro">
+  <?dbhtml filename="how-did-we-get-here.html"?>
+  <title>How did we get here?</title>
+
+  <sect1>
+    <title>Why revision control? Why Mercurial?</title>
+
+    <para id="x_6d">Revision control is the process of managing multiple
+      versions of a piece of information.  In its simplest form, this
+      is something that many people do by hand: every time you modify
+      a file, save it under a new name that contains a number, each
+      one higher than the number of the preceding version.</para>
+
+    <para id="x_6e">Manually managing multiple versions of even a single file is
+      an error-prone task, though, so software tools to help automate
+      this process have long been available.  The earliest automated
+      revision control tools were intended to help a single user to
+      manage revisions of a single file.  Over the past few decades,
+      the scope of revision control tools has expanded greatly; they
+      now manage multiple files, and help multiple people to work
+      together.  The best modern revision control tools have no
+      problem coping with thousands of people working together on
+      projects that consist of hundreds of thousands of files.</para>
+
+    <para id="x_6f">The arrival of distributed revision control is relatively
+      recent, and so far this new field has grown due to people's
+      willingness to explore ill-charted territory.</para>
+
+    <para id="x_70">I am writing a book about distributed revision control
+      because I believe that it is an important subject that deserves
+      a field guide. I chose to write about Mercurial because it is
+      the easiest tool to learn the terrain with, and yet it scales to
+      the demands of real, challenging environments where many other
+      revision control tools buckle.</para>
+
+    <sect2>
+      <title>Why use revision control?</title>
+
+      <para id="x_71">There are a number of reasons why you or your team might
+	want to use an automated revision control tool for a
+	project.</para>
+
+      <itemizedlist>
+	<listitem><para id="x_72">It will track the history and evolution of
+	    your project, so you don't have to.  For every change,
+	    you'll have a log of <emphasis>who</emphasis> made it;
+	    <emphasis>why</emphasis> they made it;
+	    <emphasis>when</emphasis> they made it; and
+	    <emphasis>what</emphasis> the change
+	    was.</para></listitem>
+	<listitem><para id="x_73">When you're working with other people,
+	    revision control software makes it easier for you to
+	    collaborate.  For example, when people more or less
+	    simultaneously make potentially incompatible changes, the
+	    software will help you to identify and resolve those
+	    conflicts.</para></listitem>
+	<listitem><para id="x_74">It can help you to recover from mistakes.  If
+	    you make a change that later turns out to be in error, you
+	    can revert to an earlier version of one or more files.  In
+	    fact, a <emphasis>really</emphasis> good revision control
+	    tool will even help you to efficiently figure out exactly
+	    when a problem was introduced (see <xref
+	      linkend="sec:undo:bisect"/> for details).</para></listitem>
+	<listitem><para id="x_75">It will help you to work simultaneously on,
+	    and manage the drift between, multiple versions of your
+	    project.</para></listitem>
+      </itemizedlist>
+
+      <para id="x_76">Most of these reasons are equally
+	valid&emdash;at least in theory&emdash;whether you're working
+	on a project by yourself, or with a hundred other
+	people.</para>
+
+      <para id="x_77">A key question about the practicality of revision control
+	at these two different scales (<quote>lone hacker</quote> and
+	<quote>huge team</quote>) is how its
+	<emphasis>benefits</emphasis> compare to its
+	<emphasis>costs</emphasis>.  A revision control tool that's
+	difficult to understand or use is going to impose a high
+	cost.</para>
+
+      <para id="x_78">A five-hundred-person project is likely to collapse under
+	its own weight almost immediately without a revision control
+	tool and process. In this case, the cost of using revision
+	control might hardly seem worth considering, since
+	<emphasis>without</emphasis> it, failure is almost
+	guaranteed.</para>
+
+      <para id="x_79">On the other hand, a one-person <quote>quick hack</quote>
+	might seem like a poor place to use a revision control tool,
+	because surely the cost of using one must be close to the
+	overall cost of the project.  Right?</para>
+
+      <para id="x_7a">Mercurial uniquely supports <emphasis>both</emphasis> of
+	these scales of development.  You can learn the basics in just
+	a few minutes, and due to its low overhead, you can apply
+	revision control to the smallest of projects with ease.  Its
+	simplicity means you won't have a lot of abstruse concepts or
+	command sequences competing for mental space with whatever
+	you're <emphasis>really</emphasis> trying to do.  At the same
+	time, Mercurial's high performance and peer-to-peer nature let
+	you scale painlessly to handle large projects.</para>
+
+      <para id="x_7b">No revision control tool can rescue a poorly run project,
+	but a good choice of tools can make a huge difference to the
+	fluidity with which you can work on a project.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>The many names of revision control</title>
+
+      <para id="x_7c">Revision control is a diverse field, so much so that it is
+	referred to by many names and acronyms.  Here are a few of the
+	more common variations you'll encounter:</para>
+      <itemizedlist>
+	<listitem><para id="x_7d">Revision control (RCS)</para></listitem>
+	<listitem><para id="x_7e">Software configuration management (SCM), or
+	    configuration management</para></listitem>
+	<listitem><para id="x_7f">Source code management</para></listitem>
+	<listitem><para id="x_80">Source code control, or source
+	    control</para></listitem>
+	<listitem><para id="x_81">Version control
+	    (VCS)</para></listitem></itemizedlist>
+      <para id="x_82">Some people claim that these terms actually have different
+	meanings, but in practice they overlap so much that there's no
+	agreed or even useful way to tease them apart.</para>
+
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>About the examples in this book</title>
+
+    <para id="x_84">This book takes an unusual approach to code samples.  Every
+      example is <quote>live</quote>&emdash;each one is actually the result
+      of a shell script that executes the Mercurial commands you see.
+      Every time an image of the book is built from its sources, all
+      the example scripts are automatically run, and their current
+      results compared against their expected results.</para>
+
+    <para id="x_85">The advantage of this approach is that the examples are
+      always accurate; they describe <emphasis>exactly</emphasis> the
+      behavior of the version of Mercurial that's mentioned at the
+      front of the book.  If I update the version of Mercurial that
+      I'm documenting, and the output of some command changes, the
+      build fails.</para>
+
+    <para id="x_86">There is a small disadvantage to this approach, which is
+      that the dates and times you'll see in examples tend to be
+      <quote>squashed</quote> together in a way that they wouldn't be
+      if the same commands were being typed by a human.  Where a human
+      can issue no more than one command every few seconds, with any
+      resulting timestamps correspondingly spread out, my automated
+      example scripts run many commands in one second.</para>
+
+    <para id="x_87">As an instance of this, several consecutive commits in an
+      example can show up as having occurred during the same second.
+      You can see this occur in the <literal
+	role="hg-ext">bisect</literal> example in <xref
+	linkend="sec:undo:bisect"/>, for instance.</para>
+
+    <para id="x_88">So when you're reading examples, don't place too much weight
+      on the dates or times you see in the output of commands.  But
+      <emphasis>do</emphasis> be confident that the behavior you're
+      seeing is consistent and reproducible.</para>
+
+  </sect1>
+
+  <sect1>
+    <title>Trends in the field</title>
+
+    <para id="x_89">There has been an unmistakable trend in the development and
+      use of revision control tools over the past four decades, as
+      people have become familiar with the capabilities of their tools
+      and constrained by their limitations.</para>
+
+    <para id="x_8a">The first generation began by managing single files on
+      individual computers.  Although these tools represented a huge
+      advance over ad-hoc manual revision control, their locking model
+      and reliance on a single computer limited them to small,
+      tightly-knit teams.</para>
+
+    <para id="x_8b">The second generation loosened these constraints by moving
+      to network-centered architectures, and managing entire projects
+      at a time.  As projects grew larger, they ran into new problems.
+      With clients needing to talk to servers very frequently, server
+      scaling became an issue for large projects.  An unreliable
+      network connection could prevent remote users from being able to
+      talk to the server at all.  As open source projects started
+      making read-only access available anonymously to anyone, people
+      without commit privileges found that they could not use the
+      tools to interact with a project in a natural way, as they could
+      not record their changes.</para>
+
+    <para id="x_8c">The current generation of revision control tools is
+      peer-to-peer in nature.  All of these systems have dropped the
+      dependency on a single central server, and allow people to
+      distribute their revision control data to where it's actually
+      needed.  Collaboration over the Internet has moved from
+      constrained by technology to a matter of choice and consensus.
+      Modern tools can operate offline indefinitely and autonomously,
+      with a network connection only needed when syncing changes with
+      another repository.</para>
+
+  </sect1>
+  <sect1>
+    <title>A few of the advantages of distributed revision
+      control</title>
+
+    <para id="x_8d">Even though distributed revision control tools have for
+      several years been as robust and usable as their
+      previous-generation counterparts, people using older tools have
+      not yet necessarily woken up to their advantages.  There are a
+      number of ways in which distributed tools shine relative to
+      centralised ones.</para>
+
+    <para id="x_8e">For an individual developer, distributed tools are almost
+      always much faster than centralised tools.  This is for a simple
+      reason: a centralised tool needs to talk over the network for
+      many common operations, because most metadata is stored in a
+      single copy on the central server.  A distributed tool stores
+      all of its metadata locally.  All else being equal, talking over
+      the network adds overhead to a centralised tool.  Don't
+      underestimate the value of a snappy, responsive tool: you're
+      going to spend a lot of time interacting with your revision
+      control software.</para>
+
+    <para id="x_8f">Distributed tools are indifferent to the vagaries of your
+      server infrastructure, again because they replicate metadata to
+      so many locations.  If you use a centralised system and your
+      server catches fire, you'd better hope that your backup media
+      are reliable, and that your last backup was recent and actually
+      worked.  With a distributed tool, you have many backups
+      available on every contributor's computer.</para>
+
+    <para id="x_90">The reliability of your network will affect distributed
+      tools far less than it will centralised tools.  You can't even
+      use a centralised tool without a network connection, except for
+      a few highly constrained commands.  With a distributed tool, if
+      your network connection goes down while you're working, you may
+      not even notice.  The only thing you won't be able to do is talk
+      to repositories on other computers, something that is relatively
+      rare compared with local operations.  If you have a far-flung
+      team of collaborators, this may be significant.</para>
+