1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/.hgtags	Thu May 21 14:16:17 2009 +0800
     1.3 @@ -0,0 +1,1 @@
     1.4 +18131160f7ee3b81bf39ce2c58f762b8d671cef3 submitted

     2.1 --- a/en/00book.xml	Sat Apr 18 11:52:33 2009 +0800
     2.2 +++ b/en/00book.xml	Thu May 21 14:16:17 2009 +0800
     2.3 @@ -8,20 +8,21 @@
     2.4  <!-- Chapters. -->
     2.5  
     2.6  <!ENTITY ch00     SYSTEM "ch00-preface.xml">
     2.7 -<!ENTITY ch01     SYSTEM "ch01-tour-basic.xml">
     2.8 -<!ENTITY ch02     SYSTEM "ch02-tour-merge.xml">
     2.9 -<!ENTITY ch03     SYSTEM "ch03-concepts.xml">
    2.10 -<!ENTITY ch04     SYSTEM "ch04-daily.xml">
    2.11 -<!ENTITY ch05     SYSTEM "ch05-collab.xml">
    2.12 -<!ENTITY ch06     SYSTEM "ch06-filenames.xml">
    2.13 -<!ENTITY ch07     SYSTEM "ch07-branch.xml">
    2.14 -<!ENTITY ch08     SYSTEM "ch08-undo.xml">
    2.15 -<!ENTITY ch09     SYSTEM "ch09-hook.xml">
    2.16 -<!ENTITY ch10     SYSTEM "ch10-template.xml">
    2.17 -<!ENTITY ch11     SYSTEM "ch11-mq.xml">
    2.18 -<!ENTITY ch12     SYSTEM "ch12-mq-collab.xml">
    2.19 -<!ENTITY ch13     SYSTEM "ch13-hgext.xml">
    2.20 -<!ENTITY appA     SYSTEM "appA-cmdref.xml">
    2.21 +<!ENTITY ch01     SYSTEM "ch01-intro.xml">
    2.22 +<!ENTITY ch02     SYSTEM "ch02-tour-basic.xml">
    2.23 +<!ENTITY ch03     SYSTEM "ch03-tour-merge.xml">
    2.24 +<!ENTITY ch04     SYSTEM "ch04-concepts.xml">
    2.25 +<!ENTITY ch05     SYSTEM "ch05-daily.xml">
    2.26 +<!ENTITY ch06     SYSTEM "ch06-collab.xml">
    2.27 +<!ENTITY ch07     SYSTEM "ch07-filenames.xml">
    2.28 +<!ENTITY ch08     SYSTEM "ch08-branch.xml">
    2.29 +<!ENTITY ch09     SYSTEM "ch09-undo.xml">
    2.30 +<!ENTITY ch10     SYSTEM "ch10-hook.xml">
    2.31 +<!ENTITY ch11     SYSTEM "ch11-template.xml">
    2.32 +<!ENTITY ch12     SYSTEM "ch12-mq.xml">
    2.33 +<!ENTITY ch13     SYSTEM "ch13-mq-collab.xml">
    2.34 +<!ENTITY ch14     SYSTEM "ch14-hgext.xml">
    2.35 +<!ENTITY appA     SYSTEM "appA-svn.xml">
    2.36  <!ENTITY appB     SYSTEM "appB-mq-ref.xml">
    2.37  <!ENTITY appC     SYSTEM "appC-srcinstall.xml">
    2.38  <!ENTITY appD     SYSTEM "appD-license.xml">
    2.39 @@ -96,6 +97,10 @@
    2.40    &ch12;
    2.41    <!-- BEGIN ch13 -->
    2.42    &ch13;
    2.43 +  <!-- BEGIN ch14 -->
    2.44 +  &ch14;
    2.45 +  <!-- BEGIN appA -->
    2.46 +  &appA;
    2.47    <!-- BEGIN appB -->
    2.48    &appB;
    2.49    <!-- BEGIN appC -->

     3.1 --- a/en/Makefile	Sat Apr 18 11:52:33 2009 +0800
     3.2 +++ b/en/Makefile	Thu May 21 14:16:17 2009 +0800
     3.3 @@ -35,7 +35,6 @@
     3.4  	filenames \
     3.5  	hook.msglen \
     3.6  	hook.simple \
     3.7 -	hook.ws \
     3.8  	issue29 \
     3.9  	mq.guards \
    3.10  	mq.qinit-help \

     4.1 --- a/en/appA-cmdref.xml	Sat Apr 18 11:52:33 2009 +0800
     4.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.3 @@ -1,224 +0,0 @@
     4.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     4.5 -
     4.6 -<appendix id="cmdref">
     4.7 -  <?dbhtml filename="command-reference.html"?>
     4.8 -<title>Command reference</title>
     4.9 -
    4.10 -<para id="x_653">\cmdref{add}{add files at the next commit}
    4.11 -\optref{add}{I}{include}
    4.12 -\optref{add}{X}{exclude}
    4.13 -\optref{add}{n}{dry-run}</para>
    4.14 -
    4.15 -<para id="x_654">\cmdref{diff}{print changes in history or working directory}</para>
    4.16 -
    4.17 -<para id="x_655">Show differences between revisions for the specified files or
    4.18 -directories, using the unified diff format.  For a description of the
    4.19 -unified diff format, see <xref linkend="sec:mq:patch"/>.</para>
    4.20 -
    4.21 -<para id="x_656">By default, this command does not print diffs for files that Mercurial
    4.22 -considers to contain binary data.  To control this behavior, see the
    4.23 -<option role="hg-opt-diff">-a</option> and <option role="hg-opt-diff">--git</option> options.</para>
    4.24 -
    4.25 -<sect2>
    4.26 -<title>Options</title>
    4.27 -x
    4.28 -<para id="x_657">\loptref{diff}{nodates}</para>
    4.29 -
    4.30 -<para id="x_658">Omit date and time information when printing diff headers.</para>
    4.31 -
    4.32 -<para id="x_659">\optref{diff}{B}{ignore-blank-lines}</para>
    4.33 -
    4.34 -<para id="x_65a">Do not print changes that only insert or delete blank lines.  A line
    4.35 -that contains only whitespace is not considered blank.
    4.36 -</para>
    4.37 -
    4.38 -<para id="x_65b">\optref{diff}{I}{include}
    4.39 -</para>
    4.40 -
    4.41 -<para id="x_65c">Include files and directories whose names match the given patterns.
    4.42 -</para>
    4.43 -
    4.44 -<para id="x_65d">\optref{diff}{X}{exclude}
    4.45 -</para>
    4.46 -
    4.47 -<para id="x_65e">Exclude files and directories whose names match the given patterns.
    4.48 -</para>
    4.49 -
    4.50 -<para id="x_65f">\optref{diff}{a}{text}
    4.51 -</para>
    4.52 -
    4.53 -<para id="x_660">If this option is not specified, <command role="hg-cmd">hg diff</command> will refuse to print
    4.54 -diffs for files that it detects as binary. Specifying <option role="hg-opt-diff">-a</option>
    4.55 -forces <command role="hg-cmd">hg diff</command> to treat all files as text, and generate diffs for
    4.56 -all of them.
    4.57 -</para>
    4.58 -
    4.59 -<para id="x_661">This option is useful for files that are <quote>mostly text</quote> but have a
    4.60 -few embedded NUL characters.  If you use it on files that contain a
    4.61 -lot of binary data, its output will be incomprehensible.
    4.62 -</para>
    4.63 -
    4.64 -<para id="x_662">\optref{diff}{b}{ignore-space-change}
    4.65 -</para>
    4.66 -
    4.67 -<para id="x_663">Do not print a line if the only change to that line is in the amount
    4.68 -of white space it contains.
    4.69 -</para>
    4.70 -
    4.71 -<para id="x_664">\optref{diff}{g}{git}
    4.72 -</para>
    4.73 -
    4.74 -<para id="x_665">Print <command>git</command>-compatible diffs.  XXX reference a format
    4.75 -description.
    4.76 -</para>
    4.77 -
    4.78 -<para id="x_666">\optref{diff}{p}{show-function}
    4.79 -</para>
    4.80 -
    4.81 -<para id="x_667">Display the name of the enclosing function in a hunk header, using a
    4.82 -simple heuristic.  This functionality is enabled by default, so the
    4.83 -<option role="hg-opt-diff">-p</option> option has no effect unless you change the value of
    4.84 -the <envar role="rc-item-diff">showfunc</envar> config item, as in the following example.</para>
    4.85 -
    4.86 -<!-- &interaction.cmdref.diff-p; -->
    4.87 -
    4.88 -<para id="x_668">\optref{diff}{r}{rev}
    4.89 -</para>
    4.90 -
    4.91 -<para id="x_669">Specify one or more revisions to compare.  The <command role="hg-cmd">hg diff</command> command
    4.92 -accepts up to two <option role="hg-opt-diff">-r</option> options to specify the revisions to
    4.93 -compare.
    4.94 -</para>
    4.95 -
    4.96 -<orderedlist>
    4.97 -<listitem><para id="x_66a">Display the differences between the parent revision of the
    4.98 -  working directory and the working directory.
    4.99 -</para>
   4.100 -</listitem>
   4.101 -<listitem><para id="x_66b">Display the differences between the specified changeset and the
   4.102 -  working directory.
   4.103 -</para>
   4.104 -</listitem>
   4.105 -<listitem><para id="x_66c">Display the differences between the two specified changesets.
   4.106 -</para>
   4.107 -</listitem></orderedlist>
   4.108 -
   4.109 -<para id="x_66d">You can specify two revisions using either two <option role="hg-opt-diff">-r</option>
   4.110 -options or revision range notation.  For example, the two revision
   4.111 -specifications below are equivalent.
   4.112 -</para>
   4.113 -<programlisting>hg diff -r 10 -r 20
   4.114 -hg diff -r10:20</programlisting>
   4.115 -
   4.116 -<para id="x_66e">When you provide two revisions, Mercurial treats the order of those
   4.117 -revisions as significant.  Thus, <command role="hg-cmd">hg diff -r10:20</command> will
   4.118 -produce a diff that will transform files from their contents as of
   4.119 -revision 10 to their contents as of revision 20, while
   4.120 -<command role="hg-cmd">hg diff -r20:10</command> means the opposite: the diff that will
   4.121 -transform files from their revision 20 contents to their revision 10
   4.122 -contents.  You cannot reverse the ordering in this way if you are
   4.123 -diffing against the working directory.
   4.124 -</para>
   4.125 -
   4.126 -<para id="x_66f">\optref{diff}{w}{ignore-all-space}
   4.127 -</para>
   4.128 -
   4.129 -<para id="x_670">\cmdref{version}{print version and copyright information}
   4.130 -</para>
   4.131 -
   4.132 -<para id="x_671">This command displays the version of Mercurial you are running, and
   4.133 -its copyright license.  There are four kinds of version string that
   4.134 -you may see.
   4.135 -</para>
   4.136 -<itemizedlist>
   4.137 -<listitem><para id="x_672">The string <quote><literal>unknown</literal></quote>. This version of Mercurial was
   4.138 -  not built in a Mercurial repository, and cannot determine its own
   4.139 -  version.
   4.140 -</para>
   4.141 -</listitem>
   4.142 -<listitem><para id="x_673">A short numeric string, such as <quote><literal>1.1</literal></quote>. This is a
   4.143 -  build of a revision of Mercurial that was identified by a specific
   4.144 -  tag in the repository where it was built.  (This doesn't necessarily
   4.145 -  mean that you're running an official release; someone else could
   4.146 -  have added that tag to any revision in the repository where they
   4.147 -  built Mercurial.)
   4.148 -</para>
   4.149 -</listitem>
   4.150 -<listitem><para id="x_674">A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>.  This
   4.151 -  is a build of the given revision of Mercurial.
   4.152 -</para>
   4.153 -</listitem>
   4.154 -<listitem><para id="x_675">A hexadecimal string followed by a date, such as
   4.155 -  <quote><literal>875489e31abe+20070205</literal></quote>.  This is a build of the given
   4.156 -  revision of Mercurial, where the build repository contained some
   4.157 -  local changes that had not been committed.
   4.158 -</para>
   4.159 -</listitem></itemizedlist>
   4.160 -
   4.161 -</sect2>
   4.162 -<sect2>
   4.163 -<title>Tips and tricks</title>
   4.164 -
   4.165 -<sect3 id="cmdref:diff-vs-status">
   4.166 -<title>Why do the results of <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg status</command> differ?</title>
   4.167 -
   4.168 -<para id="x_676">When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files
   4.169 -that Mercurial will record changes for the next time you perform a
   4.170 -commit.  If you run the <command role="hg-cmd">hg diff</command> command, you may notice that it
   4.171 -prints diffs for only a <emphasis>subset</emphasis> of the files that <command role="hg-cmd">hg status</command>
   4.172 -listed.  There are two possible reasons for this.
   4.173 -</para>
   4.174 -
   4.175 -<para id="x_677">The first is that <command role="hg-cmd">hg status</command> prints some kinds of modifications
   4.176 -that <command role="hg-cmd">hg diff</command> doesn't normally display.  The <command role="hg-cmd">hg diff</command> command
   4.177 -normally outputs unified diffs, which don't have the ability to
   4.178 -represent some changes that Mercurial can track.  Most notably,
   4.179 -traditional diffs can't represent a change in whether or not a file is
   4.180 -executable, but Mercurial records this information.
   4.181 -</para>
   4.182 -
   4.183 -<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
   4.184 -display <command>git</command>-compatible diffs that <emphasis>can</emphasis> display this
   4.185 -extra information.
   4.186 -</para>
   4.187 -
   4.188 -<para id="x_679">The second possible reason that <command role="hg-cmd">hg diff</command> might be printing diffs
   4.189 -for a subset of the files displayed by <command role="hg-cmd">hg status</command> is that if you
   4.190 -invoke it without any arguments, <command role="hg-cmd">hg diff</command> prints diffs against the
   4.191 -first parent of the working directory.  If you have run <command role="hg-cmd">hg merge</command>
   4.192 -to merge two changesets, but you haven't yet committed the results of
   4.193 -the merge, your working directory has two parents (use <command role="hg-cmd">hg parents</command>
   4.194 -to see them).  While <command role="hg-cmd">hg status</command> prints modifications relative to
   4.195 -<emphasis>both</emphasis> parents after an uncommitted merge, <command role="hg-cmd">hg diff</command> still
   4.196 -operates relative only to the first parent.  You can get it to print
   4.197 -diffs relative to the second parent by specifying that parent with the
   4.198 -<option role="hg-opt-diff">-r</option> option.  There is no way to print diffs relative to
   4.199 -both parents.
   4.200 -</para>
   4.201 -
   4.202 -</sect3>
   4.203 -<sect3>
   4.204 -<title>Generating safe binary diffs</title>
   4.205 -
   4.206 -<para id="x_67a">If you use the <option role="hg-opt-diff">-a</option> option to force Mercurial to print
   4.207 -diffs of files that are either <quote>mostly text</quote> or contain lots of
   4.208 -binary data, those diffs cannot subsequently be applied by either
   4.209 -Mercurial's <command role="hg-cmd">hg import</command> command or the system's <command>patch</command>
   4.210 -command.
   4.211 -</para>
   4.212 -
   4.213 -<para id="x_67b">If you want to generate a diff of a binary file that is safe to use as
   4.214 -input for <command role="hg-cmd">hg import</command>, use the <command role="hg-cmd">hg diff</command>{--git} option when you
   4.215 -generate the patch.  The system <command>patch</command> command cannot handle
   4.216 -binary patches at all.
   4.217 -</para>
   4.218 -
   4.219 -</sect3>
   4.220 -</sect2>
   4.221 -</appendix>
   4.222 -
   4.223 -<!--
   4.224 -local variables: 
   4.225 -sgml-parent-document: ("00book.xml" "book" "appendix")
   4.226 -end:
   4.227 --->

     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/en/appA-svn.xml	Thu May 21 14:16:17 2009 +0800
     5.3 @@ -0,0 +1,540 @@
     5.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     5.5 +
     5.6 +<appendix id="svn">
     5.7 +  <?dbhtml filename="migrating-to-mercurial.html"?>
     5.8 +<title>Migrating to Mercurial</title>
     5.9 +
    5.10 +  <para id="x_6e1">A common way to test the waters with a new revision control
    5.11 +    tool is to experiment with switching an existing project, rather
    5.12 +    than starting a new project from scratch.</para>
    5.13 +
    5.14 +  <para id="x_6e2">In this appendix, we discuss how to import a project's history
    5.15 +    into Mercurial, and what to look out for if you are used to a
    5.16 +    different revision control system.</para>
    5.17 +
    5.18 +  <sect1>
    5.19 +    <title>Importing history from another system</title>
    5.20 +
    5.21 +    <para id="x_6e3">Mercurial ships with an extension named
    5.22 +      <literal>convert</literal>, which can import project history
    5.23 +      from most popular revision control systems.  At the time this
    5.24 +      book was written, it could import history from the following
    5.25 +      systems:</para>
    5.26 +    <itemizedlist>
    5.27 +      <listitem>
    5.28 +	<para id="x_6e4">Subversion</para>
    5.29 +      </listitem>
    5.30 +      <listitem>
    5.31 +	<para id="x_6e5">CVS</para>
    5.32 +      </listitem>
    5.33 +      <listitem>
    5.34 +	<para id="x_6e6">git</para>
    5.35 +      </listitem>
    5.36 +      <listitem>
    5.37 +	<para id="x_6e7">Darcs</para>
    5.38 +      </listitem>
    5.39 +      <listitem>
    5.40 +	<para id="x_6e8">Bazaar</para>
    5.41 +      </listitem>
    5.42 +      <listitem>
    5.43 +	<para id="x_6e9">Monotone</para>
    5.44 +      </listitem>
    5.45 +      <listitem>
    5.46 +	<para id="x_6ea">GNU Arch</para>
    5.47 +      </listitem>
    5.48 +      <listitem>
    5.49 +	<para id="x_6eb">Mercurial</para>
    5.50 +      </listitem>
    5.51 +    </itemizedlist>
    5.52 +
    5.53 +    <para id="x_6ec">(To see why Mercurial itself is supported as a source, see
    5.54 +      <xref linkend="svn.filemap"/>.)</para>
    5.55 +
    5.56 +    <para id="x_6ed">You can enable the extension in the usual way, by editing
    5.57 +      your <filename>~/.hgrc</filename> file.</para>
    5.58 +
    5.59 +    <programlisting>[extensions]
    5.60 +convert =</programlisting>
    5.61 +
    5.62 +    <para id="x_6ee">This will make a <command>hg convert</command> command
    5.63 +      available.  The command is easy to use.  For instance, this
    5.64 +      command will import the Subversion history for the Nose unit
    5.65 +      testing framework into Mercurial.</para>
    5.66 +
    5.67 +    <screen><prompt>$</prompt> <userinput>hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen>
    5.68 +
    5.69 +    <para id="x_6ef">The <literal>convert</literal> extension operates
    5.70 +      incrementally.  In other words, after you have run <command>hg
    5.71 +	convert</command> once, running it again will import any new
    5.72 +      revisions committed after the first run began.  Incremental
    5.73 +      conversion will only work if you run <command>hg
    5.74 +	convert</command> in the same Mercurial repository that you
    5.75 +      originally used, because the <literal>convert</literal>
    5.76 +      extension saves some private metadata in a
    5.77 +      non-revision-controlled file named
    5.78 +      <filename>.hg/shamap</filename> inside the target
    5.79 +      repository.</para>
    5.80 +
    5.81 +    <para id="x_707">When you want to start making changes using Mercurial, it's
    5.82 +      best to clone the tree in which you are doing your conversions,
    5.83 +      and leave the original tree for future incremental conversions.
    5.84 +      This is the safest way to let you pull and merge future commits
    5.85 +      from the source revision control system into your newly active
    5.86 +      Mercurial project.</para>
    5.87 +
    5.88 +    <sect2>
    5.89 +      <title>Converting multiple branches</title>
    5.90 +
    5.91 +      <para id="x_708">The <command>hg convert</command> command given above
    5.92 +	converts only the history of the <literal>trunk</literal>
    5.93 +	branch of the Subversion repository.  If we instead use the
    5.94 +	URL <literal>http://python-nose.googlecode.com/svn</literal>,
    5.95 +	Mercurial will automatically detect the
    5.96 +	<literal>trunk</literal>, <literal>tags</literal> and
    5.97 +	<literal>branches</literal> layout that Subversion projects
    5.98 +	usually use, and it will import each as a separate Mercurial
    5.99 +	branch.</para>
   5.100 +
   5.101 +      <para id="x_709">By default, each Subversion branch imported into Mercurial
   5.102 +	is given a branch name.  After the conversion completes, you
   5.103 +	can get a list of the active branch names in the Mercurial
   5.104 +	repository using <command>hg branches -a</command>. If you
   5.105 +	would prefer to import the Subversion branches without names,
   5.106 +	pass the <option>--config
   5.107 +	  convert.hg.usebranchnames=false</option> option to
   5.108 +	<command>hg convert</command>.</para>
   5.109 +
   5.110 +      <para id="x_70a">Once you have converted your tree, if you want to follow
   5.111 +	the usual Mercurial practice of working in a tree that
   5.112 +	contains a single branch, you can clone that single branch
   5.113 +	using <command>hg clone -r mybranchname</command>.</para>
   5.114 +    </sect2>
   5.115 +
   5.116 +    <sect2>
   5.117 +      <title>Mapping user names</title>
   5.118 +
   5.119 +      <para id="x_6f0">Some revision control tools save only short usernames with
   5.120 +	commits, and these can be difficult to interpret.  The norm
   5.121 +	with Mercurial is to save a committer's name and email
   5.122 +	address, which is much more useful for talking to them after
   5.123 +	the fact.</para>
   5.124 +
   5.125 +      <para id="x_6f1">If you are converting a tree from a revision control
   5.126 +	system that uses short names, you can map those names to
   5.127 +	longer equivalents by passing a <option>--authors</option>
   5.128 +	option to <command>hg convert</command>.  This option accepts
   5.129 +	a file name that should contain entries of the following
   5.130 +	form.</para>
   5.131 +
   5.132 +      <programlisting>arist = Aristotle &lt;aristotle@phil.example.gr&gt;
   5.133 +soc = Socrates &lt;socrates@phil.example.gr&gt;</programlisting>
   5.134 +
   5.135 +      <para id="x_6f2">Whenever <literal>convert</literal> encounters a commit
   5.136 +	with the username <literal>arist</literal> in the source
   5.137 +	repository, it will use the name <literal>Aristotle
   5.138 +	  &lt;aristotle@phil.example.gr&gt;</literal> in the converted
   5.139 +	Mercurial revision.  If no match is found for a name, it is
   5.140 +	used verbatim.</para>
   5.141 +    </sect2>
   5.142 +
   5.143 +    <sect2 id="svn.filemap">
   5.144 +      <title>Tidying up the tree</title>
   5.145 +
   5.146 +      <para id="x_6f3">Not all projects have pristine history.  There may be a
   5.147 +	directory that should never have been checked in, a file that
   5.148 +	is too big, or a whole hierarchy that needs to be
   5.149 +	refactored.</para>
   5.150 +
   5.151 +      <para id="x_6f4">The <literal>convert</literal> extension supports the idea
   5.152 +	of a <quote>file map</quote> that can reorganize the files and
   5.153 +	directories in a project as it imports the project's history.
   5.154 +	This is useful not only when importing history from other
   5.155 +	revision control systems, but also to prune or refactor a
   5.156 +	Mercurial tree.</para>
   5.157 +
   5.158 +      <para id="x_6f5">To specify a file map, use the <option>--filemap</option>
   5.159 +	option and supply a file name.  A file map contains lines of the
   5.160 +	following forms.</para>
   5.161 +
   5.162 +      <programlisting># This is a comment.
   5.163 +# Empty lines are ignored.	
   5.164 +
   5.165 +include path/to/file
   5.166 +
   5.167 +exclude path/to/file
   5.168 +
   5.169 +rename from/some/path to/some/other/place
   5.170 +</programlisting>
   5.171 +
   5.172 +      <para id="x_6f6">The <literal>include</literal> directive causes a file, or
   5.173 +	all files under a directory, to be included in the destination
   5.174 +	repository.  This also excludes all other files and dirs not
   5.175 +	explicitely included.  The <literal>exclude</literal>
   5.176 +	directive causes files or directories to be omitted, and
   5.177 +	others not explicitly mentioned to be included.</para>
   5.178 +
   5.179 +      <para id="x_6f7">To move a file or directory from one location to another,
   5.180 +	use the <literal>rename</literal> directive.  If you need to
   5.181 +	move a file or directory from a subdirectory into the root of
   5.182 +	the repository, use <literal>.</literal> as the second
   5.183 +	argument to the <literal>rename</literal> directive.</para>
   5.184 +    </sect2>
   5.185 +
   5.186 +    <sect2>
   5.187 +      <title>Improving Subversion conversion performance</title>
   5.188 +
   5.189 +      <para id="x_70b">You will often need several attempts before you hit the
   5.190 +	perfect combination of user map, file map, and other
   5.191 +	conversion parameters.  Converting a Subversion repository
   5.192 +	over an access protocol like <literal>ssh</literal> or
   5.193 +	<literal>http</literal> can proceed thousands of times more
   5.194 +	slowly than Mercurial is capable of actually operating, due to
   5.195 +	network delays.  This can make tuning that perfect conversion
   5.196 +	recipe very painful.</para>
   5.197 +
   5.198 +      <para id="x_70c">The <ulink
   5.199 +	  url="http://svn.collab.net/repos/svn/trunk/notes/svnsync.txt"><command>svnsync</command></ulink> 
   5.200 +	command can greatly speed up the conversion of a Subversion
   5.201 +	repository.  It is a read-only mirroring program for
   5.202 +	Subversion repositories.  The idea is that you create a local
   5.203 +	mirror of your Subversion tree, then convert the mirror into a
   5.204 +	Mercurial repository.</para>
   5.205 +
   5.206 +      <para id="x_70d">Suppose we want to convert the Subversion repository for
   5.207 +	the popular Memcached project into a Mercurial tree.  First,
   5.208 +	we create a local Subversion repository.</para>
   5.209 +
   5.210 +      <screen><prompt>$</prompt> <userinput>svnadmin create memcached-mirror</userinput></screen>
   5.211 +
   5.212 +      <para id="x_70e">Next, we set up a Subversion hook that
   5.213 +	<command>svnsync</command> needs.</para>
   5.214 +
   5.215 +      <screen><prompt>$</prompt> <userinput>echo '#!/bin/sh' > memcached-mirror/hooks/pre-revprop-change</userinput>
   5.216 +<prompt>$</prompt> <userinput>chmod +x memcached-mirror/hooks/pre-revprop-change</userinput></screen>
   5.217 +
   5.218 +      <para id="x_70f">We then initialize <command>svnsync</command> in this
   5.219 +	repository.</para>
   5.220 +
   5.221 +      <screen><prompt>$</prompt> <userinput>svnsync --init file://`pwd`/memcached-mirror \
   5.222 +  http://code.sixapart.com/svn/memcached</userinput></screen>
   5.223 +
   5.224 +      <para id="x_710">Our next step is to begin the <command>svnsync</command>
   5.225 +	mirroring process.</para>
   5.226 +
   5.227 +      <screen><prompt>$</prompt> <userinput>svnsync sync file://`pwd`/memcached-mirror</userinput></screen>
   5.228 +
   5.229 +      <para id="x_711">Finally, we import the history of our local Subversion
   5.230 +	mirror into Mercurial.</para>
   5.231 +
   5.232 +      <screen><prompt>$</prompt> <userinput>hg convert memcached-mirror</userinput></screen>
   5.233 +      
   5.234 +      <para id="x_712">We can use this process incrementally if the Subversion
   5.235 +	repository is still in use.  We run <command>svnsync</command>
   5.236 +	to pull new changes into our mirror, then <command>hg
   5.237 +	  convert</command> to import them into our Mercurial
   5.238 +	tree.</para>
   5.239 +
   5.240 +      <para id="x_713">There are two advantages to doing a two-stage import with
   5.241 +	<command>svnsync</command>.  The first is that it uses more
   5.242 +	efficient Subversion network syncing code than <command>hg
   5.243 +	  convert</command>, so it transfers less data over the
   5.244 +	network.  The second is that the import from a local
   5.245 +	Subversion tree is so fast that you can tweak your conversion
   5.246 +	setup repeatedly without having to sit through a painfully
   5.247 +	slow network-based conversion process each time.</para>
   5.248 +    </sect2>
   5.249 +  </sect1>
   5.250 +
   5.251 +  <sect1>
   5.252 +    <title>Migrating from Subversion</title>
   5.253 +
   5.254 +    <para id="x_6f8">Subversion is currently the most popular open source
   5.255 +      revision control system. Although there are many differences
   5.256 +      between Mercurial and Subversion, making the transition from
   5.257 +      Subversion to Mercurial is not particularly difficult.  The two
   5.258 +      have similar command sets and generally uniform
   5.259 +      interfaces.</para>
   5.260 +
   5.261 +    <sect2>
   5.262 +      <title>Philosophical differences</title>
   5.263 +
   5.264 +      <para id="x_6f9">The fundamental difference between Subversion and
   5.265 +	Mercurial is of course that Subversion is centralized, while
   5.266 +	Mercurial is distributed.  Since Mercurial stores all of a
   5.267 +	project's history on your local drive, it only needs to
   5.268 +	perform a network access when you want to explicitly
   5.269 +	communicate with another repository. In contrast, Subversion
   5.270 +	stores very little information locally, and the client must
   5.271 +	thus contact its server for many common operations.</para>
   5.272 +
   5.273 +      <para id="x_6fa">Subversion more or less gets away without a well-defined
   5.274 +	notion of a branch: which portion of a server's namespace
   5.275 +	qualifies as a branch is a matter of convention, with the
   5.276 +	software providing no enforcement.  Mercurial treats a
   5.277 +	repository as the unit of branch management.</para>
   5.278 +
   5.279 +      <sect3>
   5.280 +	<title>Scope of commands</title>
   5.281 +
   5.282 +	<para id="x_6fb">Since Subversion doesn't know what parts of its
   5.283 +	  namespace are really branches, it treats most commands as
   5.284 +	  requests to operate at and below whatever directory you are
   5.285 +	  currently visiting.  For instance, if you run <command>svn
   5.286 +	    log</command>, you'll get the history of whatever part of
   5.287 +	  the tree you're looking at, not the tree as a whole.</para>
   5.288 +
   5.289 +	<para id="x_6fc">Mercurial's commands behave differently, by defaulting
   5.290 +	  to operating over an entire repository.  Run <command>hg
   5.291 +	    log</command> and it will tell you the history of the
   5.292 +	  entire tree, no matter what part of the working directory
   5.293 +	  you're visiting at the time.  If you want the history of
   5.294 +	  just a particular file or directory, simply supply it by
   5.295 +	  name, e.g. <command>hg log src</command>.</para>
   5.296 +
   5.297 +	<para id="x_6fd">From my own experience, this difference in default
   5.298 +	  behaviors is probably the most likely to trip you up if you
   5.299 +	  have to switch back and forth frequently between the two
   5.300 +	  tools.</para>
   5.301 +      </sect3>
   5.302 +
   5.303 +      <sect3>
   5.304 +	<title>Multi-user operation and safety</title>
   5.305 +
   5.306 +	<para id="x_6fe">With Subversion, it is normal (though slightly frowned
   5.307 +	  upon) for multiple people to collaborate in a single branch.
   5.308 +	  If Alice and Bob are working together, and Alice commits
   5.309 +	  some changes to their shared branch, Bob must update his
   5.310 +	  client's view of the branch before he can commit.  Since at
   5.311 +	  this time he has no permanent record of the changes he has
   5.312 +	  made, he can corrupt or lose his modifications during and
   5.313 +	  after his update.</para>
   5.314 +
   5.315 +	<para id="x_6ff">Mercurial encourages a commit-then-merge model instead.
   5.316 +	  Bob commits his changes locally before pulling changes from,
   5.317 +	  or pushing them to, the server that he shares with Alice.
   5.318 +	  If Alice pushed her changes before Bob tries to push his, he
   5.319 +	  will not be able to push his changes until he pulls hers,
   5.320 +	  merges with them, and commits the result of the merge.  If
   5.321 +	  he makes a mistake during the merge, he still has the option
   5.322 +	  of reverting to the commit that recorded his changes.</para>
   5.323 +
   5.324 +	<para id="x_700">It is worth emphasizing that these are the common ways
   5.325 +	  of working with these tools. Subversion supports a safer
   5.326 +	  work-in-your-own-branch model, but it is cumbersome enough
   5.327 +	  in practice to not be widely used.  Mercurial can support
   5.328 +	  the less safe mode of allowing changes to be pulled in and
   5.329 +	  merged on top of uncommitted edits, but this is considered
   5.330 +	  highly unusual.</para>
   5.331 +      </sect3>
   5.332 +
   5.333 +      <sect3>
   5.334 +	<title>Published vs local changes</title>
   5.335 +
   5.336 +	<para id="x_701">A Subversion <command>svn commit</command> command
   5.337 +	  immediately publishes changes to a server, where they can be
   5.338 +	  seen by everyone who has read access.</para>
   5.339 +
   5.340 +	<para id="x_702">With Mercurial, commits are always local, and must be
   5.341 +	  published via a <command>hg push</command> command
   5.342 +	  afterwards.</para>
   5.343 +
   5.344 +	<para id="x_703">Each approach has its advantages and disadvantages.  The
   5.345 +	  Subversion model means that changes are published, and hence
   5.346 +	  reviewable and usable, immediately.  On the other hand, this
   5.347 +	  means that a user must have commit access to a repository in
   5.348 +	  order to use the software in a normal way, and commit access
   5.349 +	  is not lightly given out by most open source
   5.350 +	  projects.</para>
   5.351 +
   5.352 +	<para id="x_704">The Mercurial approach allows anyone who can clone a
   5.353 +	  repository to commit changes without the need for someone
   5.354 +	  else's permission, and they can then publish their changes
   5.355 +	  and continue to participate however they see fit.  The
   5.356 +	  distinction between committing and pushing does open up the
   5.357 +	  possibility of someone committing changes to their laptop
   5.358 +	  and walking away for a few days having forgotten to push
   5.359 +	  them, which in rare cases might leave collaborators
   5.360 +	  temporarily stuck.</para>
   5.361 +      </sect3>
   5.362 +    </sect2>
   5.363 +
   5.364 +    <sect2>
   5.365 +      <title>Quick reference</title>
   5.366 +
   5.367 +      <table>
   5.368 +	<title>Subversion commands and Mercurial equivalents</title>
   5.369 +	<tgroup cols="3">
   5.370 +	  <thead>
   5.371 +	    <row>
   5.372 +	      <entry>Subversion</entry>
   5.373 +	      <entry>Mercurial</entry>
   5.374 +	      <entry>Notes</entry>
   5.375 +	    </row>
   5.376 +	  </thead>
   5.377 +	  <tbody>
   5.378 +	    <row>
   5.379 +	      <entry><command>svn add</command></entry>
   5.380 +	      <entry><command>hg add</command></entry>
   5.381 +	      <entry></entry>
   5.382 +	    </row>
   5.383 +	    <row>
   5.384 +	      <entry><command>svn blame</command></entry>
   5.385 +	      <entry><command>hg annotate</command></entry>
   5.386 +	      <entry></entry>
   5.387 +	    </row>
   5.388 +	    <row>
   5.389 +	      <entry><command>svn cat</command></entry>
   5.390 +	      <entry><command>hg cat</command></entry>
   5.391 +	      <entry></entry>
   5.392 +	    </row>
   5.393 +	    <row>
   5.394 +	      <entry><command>svn checkout</command></entry>
   5.395 +	      <entry><command>hg clone</command></entry>
   5.396 +	      <entry></entry>
   5.397 +	    </row>
   5.398 +	    <row>
   5.399 +	      <entry><command>svn cleanup</command></entry>
   5.400 +	      <entry>n/a</entry>
   5.401 +	      <entry>No cleanup needed</entry>
   5.402 +	    </row>
   5.403 +	    <row>
   5.404 +	      <entry><command>svn commit</command></entry>
   5.405 +	      <entry><command>hg commit</command>; <command>hg
   5.406 +		  push</command></entry>
   5.407 +	      <entry><command>hg push</command> publishes after
   5.408 +		commit</entry>
   5.409 +	    </row>
   5.410 +	    <row>
   5.411 +	      <entry><command>svn copy</command></entry>
   5.412 +	      <entry><command>hg clone</command></entry>
   5.413 +	      <entry>To create a new branch</entry>
   5.414 +	    </row>
   5.415 +	    <row>
   5.416 +	      <entry><command>svn copy</command></entry>
   5.417 +	      <entry><command>hg copy</command></entry>
   5.418 +	      <entry>To copy files or directories</entry>
   5.419 +	    </row>
   5.420 +	    <row>
   5.421 +	      <entry><command>svn delete</command> (<command>svn
   5.422 +		  remove</command>)</entry>
   5.423 +	      <entry><command>hg remove</command></entry>
   5.424 +	      <entry></entry>
   5.425 +	    </row>
   5.426 +	    <row>
   5.427 +	      <entry><command>svn diff</command></entry>
   5.428 +	      <entry><command>hg diff</command></entry>
   5.429 +	      <entry></entry>
   5.430 +	    </row>
   5.431 +	    <row>
   5.432 +	      <entry><command>svn export</command></entry>
   5.433 +	      <entry><command>hg archive</command></entry>
   5.434 +	      <entry></entry>
   5.435 +	    </row>
   5.436 +	    <row>
   5.437 +	      <entry><command>svn help</command></entry>
   5.438 +	      <entry><command>hg help</command></entry>
   5.439 +	      <entry></entry>
   5.440 +	    </row>
   5.441 +	    <row>
   5.442 +	      <entry><command>svn import</command></entry>
   5.443 +	      <entry><command>hg addremove</command>; <command>hg
   5.444 +		  commit</command></entry>
   5.445 +	      <entry></entry>
   5.446 +	    </row>
   5.447 +	    <row>
   5.448 +	      <entry><command>svn info</command></entry>
   5.449 +	      <entry><command>hg parents</command></entry>
   5.450 +	      <entry>Shows what revision is checked out</entry>
   5.451 +	    </row>
   5.452 +	    <row>
   5.453 +	      <entry><command>svn info</command></entry>
   5.454 +	      <entry><command>hg showconfig
   5.455 +		  paths.parent</command></entry>
   5.456 +	      <entry>Shows what URL is checked out</entry>
   5.457 +	    </row>
   5.458 +	    <row>
   5.459 +	      <entry><command>svn list</command></entry>
   5.460 +	      <entry><command>hg manifest</command></entry>
   5.461 +	      <entry></entry>
   5.462 +	    </row>
   5.463 +	    <row>
   5.464 +	      <entry><command>svn log</command></entry>
   5.465 +	      <entry><command>hg log</command></entry>
   5.466 +	      <entry></entry>
   5.467 +	    </row>
   5.468 +	    <row>
   5.469 +	      <entry><command>svn merge</command></entry>
   5.470 +	      <entry><command>hg merge</command></entry>
   5.471 +	      <entry></entry>
   5.472 +	    </row>
   5.473 +	    <row>
   5.474 +	      <entry><command>svn mkdir</command></entry>
   5.475 +	      <entry>n/a</entry>
   5.476 +	      <entry>Mercurial does not track directories</entry>
   5.477 +	    </row>
   5.478 +	    <row>
   5.479 +	      <entry><command>svn move</command> (<command>svn
   5.480 +		  rename</command>)</entry>
   5.481 +	      <entry><command>hg rename</command></entry>
   5.482 +	      <entry></entry>
   5.483 +	    </row>
   5.484 +	    <row>
   5.485 +	      <entry><command>svn resolved</command></entry>
   5.486 +	      <entry><command>hg resolve -m</command></entry>
   5.487 +	      <entry></entry>
   5.488 +	    </row>
   5.489 +	    <row>
   5.490 +	      <entry><command>svn revert</command></entry>
   5.491 +	      <entry><command>hg revert</command></entry>
   5.492 +	      <entry></entry>
   5.493 +	    </row>
   5.494 +	    <row>
   5.495 +	      <entry><command>svn status</command></entry>
   5.496 +	      <entry><command>hg status</command></entry>
   5.497 +	      <entry></entry>
   5.498 +	    </row>
   5.499 +	    <row>
   5.500 +	      <entry><command>svn update</command></entry>
   5.501 +	      <entry><command>hg pull -u</command></entry>
   5.502 +	      <entry></entry>
   5.503 +	    </row>
   5.504 +	  </tbody>
   5.505 +	</tgroup>
   5.506 +      </table>
   5.507 +    </sect2>
   5.508 +  </sect1>
   5.509 +
   5.510 +  <sect1>
   5.511 +    <title>Useful tips for newcomers</title>
   5.512 +
   5.513 +    <para id="x_705">Under some revision control systems, printing a diff for a
   5.514 +      single committed revision can be painful. For instance, with
   5.515 +      Subversion, to see what changed in revision 104654, you must
   5.516 +      type <command>svn diff -r104653:104654</command>. Mercurial
   5.517 +      eliminates the need to type the revision ID twice in this common
   5.518 +      case. For a plain diff, <command>hg export 104654</command>. For
   5.519 +      a log message followed by a diff, <command>hg log -r104654
   5.520 +	-p</command>.</para>
   5.521 +
   5.522 +    <para id="x_706">When you run <command>hg status</command> without any
   5.523 +      arguments, it prints the status of the entire tree, with paths
   5.524 +      relative to the root of the repository.  This makes it tricky to
   5.525 +      copy a file name from the output of <command>hg status</command>
   5.526 +      into the command line.  If you supply a file or directory name
   5.527 +      to <command>hg status</command>, it will print paths relative to
   5.528 +      your current location instead.  So to get tree-wide status from
   5.529 +      <command>hg status</command>, with paths that are relative to
   5.530 +      your current directory and not the root of the repository, feed
   5.531 +      the output of <command>hg root</command> into <command>hg
   5.532 +	status</command>.  You can easily do this as follows on a
   5.533 +      Unix-like system:</para>
   5.534 +
   5.535 +    <screen><prompt>$</prompt> <userinput>hg status `hg root`</userinput></screen>
   5.536 +  </sect1>
   5.537 +</appendix>
   5.538 +
   5.539 +<!--
   5.540 +local variables: 
   5.541 +sgml-parent-document: ("00book.xml" "book" "appendix")
   5.542 +end:
   5.543 +-->

     6.1 --- a/en/appB-mq-ref.xml	Sat Apr 18 11:52:33 2009 +0800
     6.2 +++ b/en/appB-mq-ref.xml	Thu May 21 14:16:17 2009 +0800
     6.3 @@ -72,6 +72,16 @@
     6.4  
     6.5      </sect2>
     6.6      <sect2>
     6.7 +      <title><command role="hg-ext-mq">qfold</command>&emdash;move
     6.8 +	applied patches into repository history</title>
     6.9 +
    6.10 +      <para id="x_72d">The <command>hg qfinish</command> command converts the
    6.11 +	specified applied patches into permanent changes by moving
    6.12 +	them out of MQ's control so that they will be treated as
    6.13 +	normal repository history.</para>
    6.14 +    </sect2>
    6.15 +
    6.16 +    <sect2>
    6.17        <title><command role="hg-ext-mq">qfold</command>&emdash;merge
    6.18  	(<quote>fold</quote>) several patches into one</title>
    6.19  
    6.20 @@ -328,8 +338,8 @@
    6.21  	    no such text, a default commit message is used that
    6.22  	    identifies the name of the patch.</para>
    6.23  	</listitem></itemizedlist>
    6.24 -      <para id="x_615">If a patch contains a Mercurial patch header (XXX add
    6.25 -	link), the information in the patch header overrides these
    6.26 +      <para id="x_615">If a patch contains a Mercurial patch header,
    6.27 +	the information in the patch header overrides these
    6.28  	defaults.</para>
    6.29  
    6.30        <para id="x_616">Options:</para>
    6.31 @@ -435,21 +445,6 @@
    6.32  
    6.33      </sect2>
    6.34      <sect2>
    6.35 -      <title><command
    6.36 -	  role="hg-ext-mq">qrestore</command>&emdash;restore saved
    6.37 -	queue state</title>
    6.38 -
    6.39 -      <para id="x_628">XXX No idea what this does.</para>
    6.40 -
    6.41 -    </sect2>
    6.42 -    <sect2>
    6.43 -      <title><command role="hg-ext-mq">qsave</command>&emdash;save
    6.44 -	current queue state</title>
    6.45 -
    6.46 -      <para id="x_629">XXX Likewise.</para>
    6.47 -
    6.48 -    </sect2>
    6.49 -    <sect2>
    6.50        <title><command role="hg-ext-mq">qseries</command>&emdash;print
    6.51  	the entire patch series</title>
    6.52  
    6.53 @@ -501,9 +496,7 @@
    6.54  	    changesets in the backup bundle.</para>
    6.55  	</listitem>
    6.56  	<listitem><para id="x_631"><option role="hg-opt-strip">-f</option>: If a
    6.57 -	    branch has multiple heads, remove all heads. XXX This
    6.58 -	    should be renamed, and use <literal>-f</literal> to strip
    6.59 -	    revs when there are pending changes.</para>
    6.60 +	    branch has multiple heads, remove all heads.</para>
    6.61  	</listitem>
    6.62  	<listitem><para id="x_632"><option role="hg-opt-strip">-n</option>: Do
    6.63  	    not save a backup bundle.</para>

     7.1 --- a/en/ch00-preface.xml	Sat Apr 18 11:52:33 2009 +0800
     7.2 +++ b/en/ch00-preface.xml	Thu May 21 14:16:17 2009 +0800
     7.3 @@ -5,751 +5,256 @@
     7.4    <title>Preface</title>
     7.5  
     7.6    <sect1>
     7.7 -    <title>Why revision control? Why Mercurial?</title>
     7.8 -
     7.9 -    <para id="x_6d">Revision control is the process of managing multiple
    7.10 -      versions of a piece of information.  In its simplest form, this
    7.11 -      is something that many people do by hand: every time you modify
    7.12 -      a file, save it under a new name that contains a number, each
    7.13 -      one higher than the number of the preceding version.</para>
    7.14 -
    7.15 -    <para id="x_6e">Manually managing multiple versions of even a single file is
    7.16 -      an error-prone task, though, so software tools to help automate
    7.17 -      this process have long been available.  The earliest automated
    7.18 -      revision control tools were intended to help a single user to
    7.19 -      manage revisions of a single file.  Over the past few decades,
    7.20 -      the scope of revision control tools has expanded greatly; they
    7.21 -      now manage multiple files, and help multiple people to work
    7.22 -      together.  The best modern revision control tools have no
    7.23 -      problem coping with thousands of people working together on
    7.24 -      projects that consist of hundreds of thousands of files.</para>
    7.25 -
    7.26 -    <para id="x_6f">The arrival of distributed revision control is relatively
    7.27 -      recent, and so far this new field has grown due to people's
    7.28 -      willingness to explore ill-charted territory.</para>
    7.29 -
    7.30 -    <para id="x_70">I am writing a book about distributed revision control
    7.31 -      because I believe that it is an important subject that deserves
    7.32 -      a field guide. I chose to write about Mercurial because it is
    7.33 -      the easiest tool to learn the terrain with, and yet it scales to
    7.34 -      the demands of real, challenging environments where many other
    7.35 -      revision control tools buckle.</para>
    7.36 -
    7.37 -    <sect2>
    7.38 -      <title>Why use revision control?</title>
    7.39 -
    7.40 -      <para id="x_71">There are a number of reasons why you or your team might
    7.41 -	want to use an automated revision control tool for a
    7.42 -	project.</para>
    7.43 -
    7.44 -      <itemizedlist>
    7.45 -	<listitem><para id="x_72">It will track the history and evolution of
    7.46 -	    your project, so you don't have to.  For every change,
    7.47 -	    you'll have a log of <emphasis>who</emphasis> made it;
    7.48 -	    <emphasis>why</emphasis> they made it;
    7.49 -	    <emphasis>when</emphasis> they made it; and
    7.50 -	    <emphasis>what</emphasis> the change
    7.51 -	    was.</para></listitem>
    7.52 -	<listitem><para id="x_73">When you're working with other people,
    7.53 -	    revision control software makes it easier for you to
    7.54 -	    collaborate.  For example, when people more or less
    7.55 -	    simultaneously make potentially incompatible changes, the
    7.56 -	    software will help you to identify and resolve those
    7.57 -	    conflicts.</para></listitem>
    7.58 -	<listitem><para id="x_74">It can help you to recover from mistakes.  If
    7.59 -	    you make a change that later turns out to be in error, you
    7.60 -	    can revert to an earlier version of one or more files.  In
    7.61 -	    fact, a <emphasis>really</emphasis> good revision control
    7.62 -	    tool will even help you to efficiently figure out exactly
    7.63 -	    when a problem was introduced (see <xref
    7.64 -	      linkend="sec:undo:bisect"/> for details).</para></listitem>
    7.65 -	<listitem><para id="x_75">It will help you to work simultaneously on,
    7.66 -	    and manage the drift between, multiple versions of your
    7.67 -	    project.</para></listitem>
    7.68 -      </itemizedlist>
    7.69 -
    7.70 -      <para id="x_76">Most of these reasons are equally
    7.71 -	valid&emdash;at least in theory&emdash;whether you're working
    7.72 -	on a project by yourself, or with a hundred other
    7.73 -	people.</para>
    7.74 -
    7.75 -      <para id="x_77">A key question about the practicality of revision control
    7.76 -	at these two different scales (<quote>lone hacker</quote> and
    7.77 -	<quote>huge team</quote>) is how its
    7.78 -	<emphasis>benefits</emphasis> compare to its
    7.79 -	<emphasis>costs</emphasis>.  A revision control tool that's
    7.80 -	difficult to understand or use is going to impose a high
    7.81 -	cost.</para>
    7.82 -
    7.83 -      <para id="x_78">A five-hundred-person project is likely to collapse under
    7.84 -	its own weight almost immediately without a revision control
    7.85 -	tool and process. In this case, the cost of using revision
    7.86 -	control might hardly seem worth considering, since
    7.87 -	<emphasis>without</emphasis> it, failure is almost
    7.88 -	guaranteed.</para>
    7.89 -
    7.90 -      <para id="x_79">On the other hand, a one-person <quote>quick hack</quote>
    7.91 -	might seem like a poor place to use a revision control tool,
    7.92 -	because surely the cost of using one must be close to the
    7.93 -	overall cost of the project.  Right?</para>
    7.94 -
    7.95 -      <para id="x_7a">Mercurial uniquely supports <emphasis>both</emphasis> of
    7.96 -	these scales of development.  You can learn the basics in just
    7.97 -	a few minutes, and due to its low overhead, you can apply
    7.98 -	revision control to the smallest of projects with ease.  Its
    7.99 -	simplicity means you won't have a lot of abstruse concepts or
   7.100 -	command sequences competing for mental space with whatever
   7.101 -	you're <emphasis>really</emphasis> trying to do.  At the same
   7.102 -	time, Mercurial's high performance and peer-to-peer nature let
   7.103 -	you scale painlessly to handle large projects.</para>
   7.104 -
   7.105 -      <para id="x_7b">No revision control tool can rescue a poorly run project,
   7.106 -	but a good choice of tools can make a huge difference to the
   7.107 -	fluidity with which you can work on a project.</para>
   7.108 -
   7.109 -    </sect2>
   7.110 -
   7.111 -    <sect2>
   7.112 -      <title>The many names of revision control</title>
   7.113 -
   7.114 -      <para id="x_7c">Revision control is a diverse field, so much so that it is
   7.115 -	referred to by many names and acronyms.  Here are a few of the
   7.116 -	more common variations you'll encounter:</para>
   7.117 -      <itemizedlist>
   7.118 -	<listitem><para id="x_7d">Revision control (RCS)</para></listitem>
   7.119 -	<listitem><para id="x_7e">Software configuration management (SCM), or
   7.120 -	    configuration management</para></listitem>
   7.121 -	<listitem><para id="x_7f">Source code management</para></listitem>
   7.122 -	<listitem><para id="x_80">Source code control, or source
   7.123 -	    control</para></listitem>
   7.124 -	<listitem><para id="x_81">Version control
   7.125 -	    (VCS)</para></listitem></itemizedlist>
   7.126 -      <para id="x_82">Some people claim that these terms actually have different
   7.127 -	meanings, but in practice they overlap so much that there's no
   7.128 -	agreed or even useful way to tease them apart.</para>
   7.129 -
   7.130 -    </sect2>
   7.131 -  </sect1>
   7.132 -
   7.133 -  <sect1>
   7.134 -    <title>This book is a work in progress</title>
   7.135 -
   7.136 -    <para id="x_83">I am releasing this book while I am still writing it, in the
   7.137 -      hope that it will prove useful to others.  I am writing under an
   7.138 -      open license in the hope that you, my readers, will contribute
   7.139 -      feedback and perhaps content of your own.</para>
   7.140 -
   7.141 -  </sect1>
   7.142 -  <sect1>
   7.143 -    <title>About the examples in this book</title>
   7.144 -
   7.145 -    <para id="x_84">This book takes an unusual approach to code samples.  Every
   7.146 -      example is <quote>live</quote>&emdash;each one is actually the result
   7.147 -      of a shell script that executes the Mercurial commands you see.
   7.148 -      Every time an image of the book is built from its sources, all
   7.149 -      the example scripts are automatically run, and their current
   7.150 -      results compared against their expected results.</para>
   7.151 -
   7.152 -    <para id="x_85">The advantage of this approach is that the examples are
   7.153 -      always accurate; they describe <emphasis>exactly</emphasis> the
   7.154 -      behavior of the version of Mercurial that's mentioned at the
   7.155 -      front of the book.  If I update the version of Mercurial that
   7.156 -      I'm documenting, and the output of some command changes, the
   7.157 -      build fails.</para>
   7.158 -
   7.159 -    <para id="x_86">There is a small disadvantage to this approach, which is
   7.160 -      that the dates and times you'll see in examples tend to be
   7.161 -      <quote>squashed</quote> together in a way that they wouldn't be
   7.162 -      if the same commands were being typed by a human.  Where a human
   7.163 -      can issue no more than one command every few seconds, with any
   7.164 -      resulting timestamps correspondingly spread out, my automated
   7.165 -      example scripts run many commands in one second.</para>
   7.166 -
   7.167 -    <para id="x_87">As an instance of this, several consecutive commits in an
   7.168 -      example can show up as having occurred during the same second.
   7.169 -      You can see this occur in the <literal
   7.170 -	role="hg-ext">bisect</literal> example in <xref
   7.171 -	linkend="sec:undo:bisect"/>, for instance.</para>
   7.172 -
   7.173 -    <para id="x_88">So when you're reading examples, don't place too much weight
   7.174 -      on the dates or times you see in the output of commands.  But
   7.175 -      <emphasis>do</emphasis> be confident that the behavior you're
   7.176 -      seeing is consistent and reproducible.</para>
   7.177 -
   7.178 -  </sect1>
   7.179 -
   7.180 -  <sect1>
   7.181 -    <title>Trends in the field</title>
   7.182 -
   7.183 -    <para id="x_89">There has been an unmistakable trend in the development and
   7.184 -      use of revision control tools over the past four decades, as
   7.185 -      people have become familiar with the capabilities of their tools
   7.186 -      and constrained by their limitations.</para>
   7.187 -
   7.188 -    <para id="x_8a">The first generation began by managing single files on
   7.189 -      individual computers.  Although these tools represented a huge
   7.190 -      advance over ad-hoc manual revision control, their locking model
   7.191 -      and reliance on a single computer limited them to small,
   7.192 -      tightly-knit teams.</para>
   7.193 -
   7.194 -    <para id="x_8b">The second generation loosened these constraints by moving
   7.195 -      to network-centered architectures, and managing entire projects
   7.196 -      at a time.  As projects grew larger, they ran into new problems.
   7.197 -      With clients needing to talk to servers very frequently, server
   7.198 -      scaling became an issue for large projects.  An unreliable
   7.199 -      network connection could prevent remote users from being able to
   7.200 -      talk to the server at all.  As open source projects started
   7.201 -      making read-only access available anonymously to anyone, people
   7.202 -      without commit privileges found that they could not use the
   7.203 -      tools to interact with a project in a natural way, as they could
   7.204 -      not record their changes.</para>
   7.205 -
   7.206 -    <para id="x_8c">The current generation of revision control tools is
   7.207 -      peer-to-peer in nature.  All of these systems have dropped the
   7.208 -      dependency on a single central server, and allow people to
   7.209 -      distribute their revision control data to where it's actually
   7.210 -      needed.  Collaboration over the Internet has moved from
   7.211 -      constrained by technology to a matter of choice and consensus.
   7.212 -      Modern tools can operate offline indefinitely and autonomously,
   7.213 -      with a network connection only needed when syncing changes with
   7.214 -      another repository.</para>
   7.215 -
   7.216 -  </sect1>
   7.217 -  <sect1>
   7.218 -    <title>A few of the advantages of distributed revision
   7.219 -      control</title>
   7.220 -
   7.221 -    <para id="x_8d">Even though distributed revision control tools have for
   7.222 -      several years been as robust and usable as their
   7.223 -      previous-generation counterparts, people using older tools have
   7.224 -      not yet necessarily woken up to their advantages.  There are a
   7.225 -      number of ways in which distributed tools shine relative to
   7.226 -      centralised ones.</para>
   7.227 -
   7.228 -    <para id="x_8e">For an individual developer, distributed tools are almost
   7.229 -      always much faster than centralised tools.  This is for a simple
   7.230 -      reason: a centralised tool needs to talk over the network for
   7.231 -      many common operations, because most metadata is stored in a
   7.232 -      single copy on the central server.  A distributed tool stores
   7.233 -      all of its metadata locally.  All else being equal, talking over
   7.234 -      the network adds overhead to a centralised tool.  Don't
   7.235 -      underestimate the value of a snappy, responsive tool: you're
   7.236 -      going to spend a lot of time interacting with your revision
   7.237 -      control software.</para>
   7.238 -
   7.239 -    <para id="x_8f">Distributed tools are indifferent to the vagaries of your
   7.240 -      server infrastructure, again because they replicate metadata to
   7.241 -      so many locations.  If you use a centralised system and your
   7.242 -      server catches fire, you'd better hope that your backup media
   7.243 -      are reliable, and that your last backup was recent and actually
   7.244 -      worked.  With a distributed tool, you have many backups
   7.245 -      available on every contributor's computer.</para>
   7.246 -
   7.247 -    <para id="x_90">The reliability of your network will affect distributed
   7.248 -      tools far less than it will centralised tools.  You can't even
   7.249 -      use a centralised tool without a network connection, except for
   7.250 -      a few highly constrained commands.  With a distributed tool, if
   7.251 -      your network connection goes down while you're working, you may
   7.252 -      not even notice.  The only thing you won't be able to do is talk
   7.253 -      to repositories on other computers, something that is relatively
   7.254 -      rare compared with local operations.  If you have a far-flung
   7.255 -      team of collaborators, this may be significant.</para>
   7.256 -
   7.257 -    <sect2>
   7.258 -      <title>Advantages for open source projects</title>
   7.259 -
   7.260 -      <para id="x_91">If you take a shine to an open source project and decide
   7.261 -	that you would like to start hacking on it, and that project
   7.262 -	uses a distributed revision control tool, you are at once a
   7.263 -	peer with the people who consider themselves the
   7.264 -	<quote>core</quote> of that project.  If they publish their
   7.265 -	repositories, you can immediately copy their project history,
   7.266 -	start making changes, and record your work, using the same
   7.267 -	tools in the same ways as insiders.  By contrast, with a
   7.268 -	centralised tool, you must use the software in a <quote>read
   7.269 -	  only</quote> mode unless someone grants you permission to
   7.270 -	commit changes to their central server.  Until then, you won't
   7.271 -	be able to record changes, and your local modifications will
   7.272 -	be at risk of corruption any time you try to update your
   7.273 -	client's view of the repository.</para>
   7.274 -
   7.275 -      <sect3>
   7.276 -	<title>The forking non-problem</title>
   7.277 -
   7.278 -	<para id="x_92">It has been suggested that distributed revision control
   7.279 -	  tools pose some sort of risk to open source projects because
   7.280 -	  they make it easy to <quote>fork</quote> the development of
   7.281 -	  a project.  A fork happens when there are differences in
   7.282 -	  opinion or attitude between groups of developers that cause
   7.283 -	  them to decide that they can't work together any longer.
   7.284 -	  Each side takes a more or less complete copy of the
   7.285 -	  project's source code, and goes off in its own
   7.286 -	  direction.</para>
   7.287 -
   7.288 -	<para id="x_93">Sometimes the camps in a fork decide to reconcile their
   7.289 -	  differences. With a centralised revision control system, the
   7.290 -	  <emphasis>technical</emphasis> process of reconciliation is
   7.291 -	  painful, and has to be performed largely by hand.  You have
   7.292 -	  to decide whose revision history is going to
   7.293 -	  <quote>win</quote>, and graft the other team's changes into
   7.294 -	  the tree somehow. This usually loses some or all of one
   7.295 -	  side's revision history.</para>
   7.296 -
   7.297 -	<para id="x_94">What distributed tools do with respect to forking is
   7.298 -	  they make forking the <emphasis>only</emphasis> way to
   7.299 -	  develop a project.  Every single change that you make is
   7.300 -	  potentially a fork point.  The great strength of this
   7.301 -	  approach is that a distributed revision control tool has to
   7.302 -	  be really good at <emphasis>merging</emphasis> forks,
   7.303 -	  because forks are absolutely fundamental: they happen all
   7.304 -	  the time.</para>
   7.305 -
   7.306 -	<para id="x_95">If every piece of work that everybody does, all the
   7.307 -	  time, is framed in terms of forking and merging, then what
   7.308 -	  the open source world refers to as a <quote>fork</quote>
   7.309 -	  becomes <emphasis>purely</emphasis> a social issue.  If
   7.310 -	  anything, distributed tools <emphasis>lower</emphasis> the
   7.311 -	  likelihood of a fork:</para>
   7.312 -	<itemizedlist>
   7.313 -	  <listitem><para id="x_96">They eliminate the social distinction that
   7.314 -	      centralised tools impose: that between insiders (people
   7.315 -	      with commit access) and outsiders (people
   7.316 -	      without).</para></listitem>
   7.317 -	  <listitem><para id="x_97">They make it easier to reconcile after a
   7.318 -	      social fork, because all that's involved from the
   7.319 -	      perspective of the revision control software is just
   7.320 -	      another merge.</para></listitem></itemizedlist>
   7.321 -
   7.322 -	<para id="x_98">Some people resist distributed tools because they want
   7.323 -	  to retain tight control over their projects, and they
   7.324 -	  believe that centralised tools give them this control.
   7.325 -	  However, if you're of this belief, and you publish your CVS
   7.326 -	  or Subversion repositories publicly, there are plenty of
   7.327 -	  tools available that can pull out your entire project's
   7.328 -	  history (albeit slowly) and recreate it somewhere that you
   7.329 -	  don't control.  So while your control in this case is
   7.330 -	  illusory, you are forgoing the ability to fluidly
   7.331 -	  collaborate with whatever people feel compelled to mirror
   7.332 -	  and fork your history.</para>
   7.333 -
   7.334 -      </sect3>
   7.335 -    </sect2>
   7.336 -    <sect2>
   7.337 -      <title>Advantages for commercial projects</title>
   7.338 -
   7.339 -      <para id="x_99">Many commercial projects are undertaken by teams that are
   7.340 -	scattered across the globe.  Contributors who are far from a
   7.341 -	central server will see slower command execution and perhaps
   7.342 -	less reliability.  Commercial revision control systems attempt
   7.343 -	to ameliorate these problems with remote-site replication
   7.344 -	add-ons that are typically expensive to buy and cantankerous
   7.345 -	to administer.  A distributed system doesn't suffer from these
   7.346 -	problems in the first place.  Better yet, you can easily set
   7.347 -	up multiple authoritative servers, say one per site, so that
   7.348 -	there's no redundant communication between repositories over
   7.349 -	expensive long-haul network links.</para>
   7.350 -
   7.351 -      <para id="x_9a">Centralised revision control systems tend to have
   7.352 -	relatively low scalability.  It's not unusual for an expensive
   7.353 -	centralised system to fall over under the combined load of
   7.354 -	just a few dozen concurrent users.  Once again, the typical
   7.355 -	response tends to be an expensive and clunky replication
   7.356 -	facility.  Since the load on a central server&emdash;if you have
   7.357 -	one at all&emdash;is many times lower with a distributed tool
   7.358 -	(because all of the data is replicated everywhere), a single
   7.359 -	cheap server can handle the needs of a much larger team, and
   7.360 -	replication to balance load becomes a simple matter of
   7.361 -	scripting.</para>
   7.362 -
   7.363 -      <para id="x_9b">If you have an employee in the field, troubleshooting a
   7.364 -	problem at a customer's site, they'll benefit from distributed
   7.365 -	revision control. The tool will let them generate custom
   7.366 -	builds, try different fixes in isolation from each other, and
   7.367 -	search efficiently through history for the sources of bugs and
   7.368 -	regressions in the customer's environment, all without needing
   7.369 -	to connect to your company's network.</para>
   7.370 -
   7.371 -    </sect2>
   7.372 -  </sect1>
   7.373 -  <sect1>
   7.374 -    <title>Why choose Mercurial?</title>
   7.375 -
   7.376 -    <para id="x_9c">Mercurial has a unique set of properties that make it a
   7.377 -      particularly good choice as a revision control system.</para>
   7.378 -    <itemizedlist>
   7.379 -      <listitem><para id="x_9d">It is easy to learn and use.</para></listitem>
   7.380 -      <listitem><para id="x_9e">It is lightweight.</para></listitem>
   7.381 -      <listitem><para id="x_9f">It scales excellently.</para></listitem>
   7.382 -      <listitem><para id="x_a0">It is easy to
   7.383 -	  customise.</para></listitem></itemizedlist>
   7.384 -
   7.385 -    <para id="x_a1">If you are at all familiar with revision control systems,
   7.386 -      you should be able to get up and running with Mercurial in less
   7.387 -      than five minutes.  Even if not, it will take no more than a few
   7.388 -      minutes longer.  Mercurial's command and feature sets are
   7.389 -      generally uniform and consistent, so you can keep track of a few
   7.390 -      general rules instead of a host of exceptions.</para>
   7.391 -
   7.392 -    <para id="x_a2">On a small project, you can start working with Mercurial in
   7.393 -      moments. Creating new changes and branches; transferring changes
   7.394 -      around (whether locally or over a network); and history and
   7.395 -      status operations are all fast.  Mercurial attempts to stay
   7.396 -      nimble and largely out of your way by combining low cognitive
   7.397 -      overhead with blazingly fast operations.</para>
   7.398 -
   7.399 -    <para id="x_a3">The usefulness of Mercurial is not limited to small
   7.400 -      projects: it is used by projects with hundreds to thousands of
   7.401 -      contributors, each containing tens of thousands of files and
   7.402 -      hundreds of megabytes of source code.</para>
   7.403 -
   7.404 -    <para id="x_a4">If the core functionality of Mercurial is not enough for
   7.405 -      you, it's easy to build on.  Mercurial is well suited to
   7.406 -      scripting tasks, and its clean internals and implementation in
   7.407 -      Python make it easy to add features in the form of extensions.
   7.408 -      There are a number of popular and useful extensions already
   7.409 -      available, ranging from helping to identify bugs to improving
   7.410 -      performance.</para>
   7.411 -
   7.412 -  </sect1>
   7.413 -  <sect1>
   7.414 -    <title>Mercurial compared with other tools</title>
   7.415 -
   7.416 -    <para id="x_a5">Before you read on, please understand that this section
   7.417 -      necessarily reflects my own experiences, interests, and (dare I
   7.418 -      say it) biases.  I have used every one of the revision control
   7.419 -      tools listed below, in most cases for several years at a
   7.420 -      time.</para>
   7.421 -
   7.422 -
   7.423 -    <sect2>
   7.424 -      <title>Subversion</title>
   7.425 -
   7.426 -      <para id="x_a6">Subversion is a popular revision control tool, developed
   7.427 -	to replace CVS.  It has a centralised client/server
   7.428 -	architecture.</para>
   7.429 -
   7.430 -      <para id="x_a7">Subversion and Mercurial have similarly named commands for
   7.431 -	performing the same operations, so if you're familiar with
   7.432 -	one, it is easy to learn to use the other.  Both tools are
   7.433 -	portable to all popular operating systems.</para>
   7.434 -
   7.435 -      <para id="x_a8">Prior to version 1.5, Subversion had no useful support for
   7.436 -	merges. At the time of writing, its merge tracking capability
   7.437 -	is new, and known to be <ulink
   7.438 -	  url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword">complicated 
   7.439 -	  and buggy</ulink>.</para>
   7.440 -
   7.441 -      <para id="x_a9">Mercurial has a substantial performance advantage over
   7.442 -	Subversion on every revision control operation I have
   7.443 -	benchmarked.  I have measured its advantage as ranging from a
   7.444 -	factor of two to a factor of six when compared with Subversion
   7.445 -	1.4.3's <emphasis>ra_local</emphasis> file store, which is the
   7.446 -	fastest access method available.  In more realistic
   7.447 -	deployments involving a network-based store, Subversion will
   7.448 -	be at a substantially larger disadvantage.  Because many
   7.449 -	Subversion commands must talk to the server and Subversion
   7.450 -	does not have useful replication facilities, server capacity
   7.451 -	and network bandwidth become bottlenecks for modestly large
   7.452 -	projects.</para>
   7.453 -
   7.454 -      <para id="x_aa">Additionally, Subversion incurs substantial storage
   7.455 -	overhead to avoid network transactions for a few common
   7.456 -	operations, such as finding modified files
   7.457 -	(<literal>status</literal>) and displaying modifications
   7.458 -	against the current revision (<literal>diff</literal>).  As a
   7.459 -	result, a Subversion working copy is often the same size as,
   7.460 -	or larger than, a Mercurial repository and working directory,
   7.461 -	even though the Mercurial repository contains a complete
   7.462 -	history of the project.</para>
   7.463 -
   7.464 -      <para id="x_ab">Subversion is widely supported by third party tools.
   7.465 -	Mercurial currently lags considerably in this area.  This gap
   7.466 -	is closing, however, and indeed some of Mercurial's GUI tools
   7.467 -	now outshine their Subversion equivalents.  Like Mercurial,
   7.468 -	Subversion has an excellent user manual.</para>
   7.469 -
   7.470 -      <para id="x_ac">Because Subversion doesn't store revision history on the
   7.471 -	client, it is well suited to managing projects that deal with
   7.472 -	lots of large, opaque binary files.  If you check in fifty
   7.473 -	revisions to an incompressible 10MB file, Subversion's
   7.474 -	client-side space usage stays constant The space used by any
   7.475 -	distributed SCM will grow rapidly in proportion to the number
   7.476 -	of revisions, because the differences between each revision
   7.477 -	are large.</para>
   7.478 -
   7.479 -      <para id="x_ad">In addition, it's often difficult or, more usually,
   7.480 -	impossible to merge different versions of a binary file.
   7.481 -	Subversion's ability to let a user lock a file, so that they
   7.482 -	temporarily have the exclusive right to commit changes to it,
   7.483 -	can be a significant advantage to a project where binary files
   7.484 -	are widely used.</para>
   7.485 -
   7.486 -      <para id="x_ae">Mercurial can import revision history from a Subversion
   7.487 -	repository. It can also export revision history to a
   7.488 -	Subversion repository.  This makes it easy to <quote>test the
   7.489 -	  waters</quote> and use Mercurial and Subversion in parallel
   7.490 -	before deciding to switch.  History conversion is incremental,
   7.491 -	so you can perform an initial conversion, then small
   7.492 -	additional conversions afterwards to bring in new
   7.493 -	changes.</para>
   7.494 -
   7.495 -
   7.496 -    </sect2>
   7.497 -    <sect2>
   7.498 -      <title>Git</title>
   7.499 -
   7.500 -      <para id="x_af">Git is a distributed revision control tool that was
   7.501 -	developed for managing the Linux kernel source tree.  Like
   7.502 -	Mercurial, its early design was somewhat influenced by
   7.503 -	Monotone.</para>
   7.504 -
   7.505 -      <para id="x_b0">Git has a very large command set, with version 1.5.0
   7.506 -	providing 139 individual commands.  It has something of a
   7.507 -	reputation for being difficult to learn.  Compared to Git,
   7.508 -	Mercurial has a strong focus on simplicity.</para>
   7.509 -
   7.510 -      <para id="x_b1">In terms of performance, Git is extremely fast.  In
   7.511 -	several cases, it is faster than Mercurial, at least on Linux,
   7.512 -	while Mercurial performs better on other operations.  However,
   7.513 -	on Windows, the performance and general level of support that
   7.514 -	Git provides is, at the time of writing, far behind that of
   7.515 -	Mercurial.</para>
   7.516 -
   7.517 -      <para id="x_b2">While a Mercurial repository needs no maintenance, a Git
   7.518 -	repository requires frequent manual <quote>repacks</quote> of
   7.519 -	its metadata.  Without these, performance degrades, while
   7.520 -	space usage grows rapidly.  A server that contains many Git
   7.521 -	repositories that are not rigorously and frequently repacked
   7.522 -	will become heavily disk-bound during backups, and there have
   7.523 -	been instances of daily backups taking far longer than 24
   7.524 -	hours as a result.  A freshly packed Git repository is
   7.525 -	slightly smaller than a Mercurial repository, but an unpacked
   7.526 -	repository is several orders of magnitude larger.</para>
   7.527 -
   7.528 -      <para id="x_b3">The core of Git is written in C.  Many Git commands are
   7.529 -	implemented as shell or Perl scripts, and the quality of these
   7.530 -	scripts varies widely. I have encountered several instances
   7.531 -	where scripts charged along blindly in the presence of errors
   7.532 -	that should have been fatal.</para>
   7.533 -
   7.534 -      <para id="x_b4">Mercurial can import revision history from a Git
   7.535 -	repository.</para>
   7.536 -
   7.537 -
   7.538 -    </sect2>
   7.539 -    <sect2>
   7.540 -      <title>CVS</title>
   7.541 -
   7.542 -      <para id="x_b5">CVS is probably the most widely used revision control tool
   7.543 -	in the world.  Due to its age and internal untidiness, it has
   7.544 -	been only lightly maintained for many years.</para>
   7.545 -
   7.546 -      <para id="x_b6">It has a centralised client/server architecture.  It does
   7.547 -	not group related file changes into atomic commits, making it
   7.548 -	easy for people to <quote>break the build</quote>: one person
   7.549 -	can successfully commit part of a change and then be blocked
   7.550 -	by the need for a merge, causing other people to see only a
   7.551 -	portion of the work they intended to do.  This also affects
   7.552 -	how you work with project history.  If you want to see all of
   7.553 -	the modifications someone made as part of a task, you will
   7.554 -	need to manually inspect the descriptions and timestamps of
   7.555 -	the changes made to each file involved (if you even know what
   7.556 -	those files were).</para>
   7.557 -
   7.558 -      <para id="x_b7">CVS has a muddled notion of tags and branches that I will
   7.559 -	not attempt to even describe.  It does not support renaming of
   7.560 -	files or directories well, making it easy to corrupt a
   7.561 -	repository.  It has almost no internal consistency checking
   7.562 -	capabilities, so it is usually not even possible to tell
   7.563 -	whether or how a repository is corrupt.  I would not recommend
   7.564 -	CVS for any project, existing or new.</para>
   7.565 -
   7.566 -      <para id="x_b8">Mercurial can import CVS revision history.  However, there
   7.567 -	are a few caveats that apply; these are true of every other
   7.568 -	revision control tool's CVS importer, too.  Due to CVS's lack
   7.569 -	of atomic changes and unversioned filesystem hierarchy, it is
   7.570 -	not possible to reconstruct CVS history completely accurately;
   7.571 -	some guesswork is involved, and renames will usually not show
   7.572 -	up.  Because a lot of advanced CVS administration has to be
   7.573 -	done by hand and is hence error-prone, it's common for CVS
   7.574 -	importers to run into multiple problems with corrupted
   7.575 -	repositories (completely bogus revision timestamps and files
   7.576 -	that have remained locked for over a decade are just two of
   7.577 -	the less interesting problems I can recall from personal
   7.578 -	experience).</para>
   7.579 -
   7.580 -      <para id="x_b9">Mercurial can import revision history from a CVS
   7.581 -	repository.</para>
   7.582 -
   7.583 -
   7.584 -    </sect2>
   7.585 -    <sect2>
   7.586 -      <title>Commercial tools</title>
   7.587 -
   7.588 -      <para id="x_ba">Perforce has a centralised client/server architecture,
   7.589 -	with no client-side caching of any data.  Unlike modern
   7.590 -	revision control tools, Perforce requires that a user run a
   7.591 -	command to inform the server about every file they intend to
   7.592 -	edit.</para>
   7.593 -
   7.594 -      <para id="x_bb">The performance of Perforce is quite good for small teams,
   7.595 -	but it falls off rapidly as the number of users grows beyond a
   7.596 -	few dozen. Modestly large Perforce installations require the
   7.597 -	deployment of proxies to cope with the load their users
   7.598 -	generate.</para>
   7.599 -
   7.600 -
   7.601 -    </sect2>
   7.602 -    <sect2>
   7.603 -      <title>Choosing a revision control tool</title>
   7.604 -
   7.605 -      <para id="x_bc">With the exception of CVS, all of the tools listed above
   7.606 -	have unique strengths that suit them to particular styles of
   7.607 -	work.  There is no single revision control tool that is best
   7.608 -	in all situations.</para>
   7.609 -
   7.610 -      <para id="x_bd">As an example, Subversion is a good choice for working
   7.611 -	with frequently edited binary files, due to its centralised
   7.612 -	nature and support for file locking.</para>
   7.613 -
   7.614 -      <para id="x_be">I personally find Mercurial's properties of simplicity,
   7.615 -	performance, and good merge support to be a compelling
   7.616 -	combination that has served me well for several years.</para>
   7.617 -
   7.618 -
   7.619 -    </sect2>
   7.620 -  </sect1>
   7.621 -  <sect1>
   7.622 -    <title>Switching from another tool to Mercurial</title>
   7.623 -
   7.624 -    <para id="x_bf">Mercurial is bundled with an extension named <literal
   7.625 -	role="hg-ext">convert</literal>, which can incrementally
   7.626 -      import revision history from several other revision control
   7.627 -      tools.  By <quote>incremental</quote>, I mean that you can
   7.628 -      convert all of a project's history to date in one go, then rerun
   7.629 -      the conversion later to obtain new changes that happened after
   7.630 -      the initial conversion.</para>
   7.631 -
   7.632 -    <para id="x_c0">The revision control tools supported by <literal
   7.633 -	role="hg-ext">convert</literal> are as follows:</para>
   7.634 -    <itemizedlist>
   7.635 -      <listitem><para id="x_c1">Subversion</para></listitem>
   7.636 -      <listitem><para id="x_c2">CVS</para></listitem>
   7.637 -      <listitem><para id="x_c3">Git</para></listitem>
   7.638 -      <listitem><para id="x_c4">Darcs</para></listitem></itemizedlist>
   7.639 -
   7.640 -    <para id="x_c5">In addition, <literal role="hg-ext">convert</literal> can
   7.641 -      export changes from Mercurial to Subversion.  This makes it
   7.642 -      possible to try Subversion and Mercurial in parallel before
   7.643 -      committing to a switchover, without risking the loss of any
   7.644 -      work.</para>
   7.645 -
   7.646 -    <para id="x_c6">The <command role="hg-ext-convert">convert</command> command
   7.647 -      is easy to use.  Simply point it at the path or URL of the
   7.648 -      source repository, optionally give it the name of the
   7.649 -      destination repository, and it will start working.  After the
   7.650 -      initial conversion, just run the same command again to import
   7.651 -      new changes.</para>
   7.652 -  </sect1>
   7.653 -
   7.654 -  <sect1>
   7.655 -    <title>A short history of revision control</title>
   7.656 -
   7.657 -    <para id="x_c7">The best known of the old-time revision control tools is
   7.658 -      SCCS (Source Code Control System), which Marc Rochkind wrote at
   7.659 -      Bell Labs, in the early 1970s.  SCCS operated on individual
   7.660 -      files, and required every person working on a project to have
   7.661 -      access to a shared workspace on a single system.  Only one
   7.662 -      person could modify a file at any time; arbitration for access
   7.663 -      to files was via locks.  It was common for people to lock files,
   7.664 -      and later forget to unlock them, preventing anyone else from
   7.665 -      modifying those files without the help of an
   7.666 -      administrator.</para>
   7.667 -
   7.668 -    <para id="x_c8">Walter Tichy developed a free alternative to SCCS in the
   7.669 -      early 1980s; he called his program RCS (Revision Control System).
   7.670 -      Like SCCS, RCS required developers to work in a single shared
   7.671 -      workspace, and to lock files to prevent multiple people from
   7.672 -      modifying them simultaneously.</para>
   7.673 -
   7.674 -    <para id="x_c9">Later in the 1980s, Dick Grune used RCS as a building block
   7.675 -      for a set of shell scripts he initially called cmt, but then
   7.676 -      renamed to CVS (Concurrent Versions System).  The big innovation
   7.677 -      of CVS was that it let developers work simultaneously and
   7.678 -      somewhat independently in their own personal workspaces.  The
   7.679 -      personal workspaces prevented developers from stepping on each
   7.680 -      other's toes all the time, as was common with SCCS and RCS. Each
   7.681 -      developer had a copy of every project file, and could modify
   7.682 -      their copies independently.  They had to merge their edits prior
   7.683 -      to committing changes to the central repository.</para>
   7.684 -
   7.685 -    <para id="x_ca">Brian Berliner took Grune's original scripts and rewrote
   7.686 -      them in C, releasing in 1989 the code that has since developed
   7.687 -      into the modern version of CVS.  CVS subsequently acquired the
   7.688 -      ability to operate over a network connection, giving it a
   7.689 -      client/server architecture.  CVS's architecture is centralised;
   7.690 -      only the server has a copy of the history of the project. Client
   7.691 -      workspaces just contain copies of recent versions of the
   7.692 -      project's files, and a little metadata to tell them where the
   7.693 -      server is.  CVS has been enormously successful; it is probably
   7.694 -      the world's most widely used revision control system.</para>
   7.695 -
   7.696 -    <para id="x_cb">In the early 1990s, Sun Microsystems developed an early
   7.697 -      distributed revision control system, called TeamWare.  A
   7.698 -      TeamWare workspace contains a complete copy of the project's
   7.699 -      history.  TeamWare has no notion of a central repository.  (CVS
   7.700 -      relied upon RCS for its history storage; TeamWare used
   7.701 -      SCCS.)</para>
   7.702 -
   7.703 -    <para id="x_cc">As the 1990s progressed, awareness grew of a number of
   7.704 -      problems with CVS.  It records simultaneous changes to multiple
   7.705 -      files individually, instead of grouping them together as a
   7.706 -      single logically atomic operation.  It does not manage its file
   7.707 -      hierarchy well; it is easy to make a mess of a repository by
   7.708 -      renaming files and directories.  Worse, its source code is
   7.709 -      difficult to read and maintain, which made the <quote>pain
   7.710 -	level</quote> of fixing these architectural problems
   7.711 -      prohibitive.</para>
   7.712 -
   7.713 -    <para id="x_cd">In 2001, Jim Blandy and Karl Fogel, two developers who had
   7.714 -      worked on CVS, started a project to replace it with a tool that
   7.715 -      would have a better architecture and cleaner code.  The result,
   7.716 -      Subversion, does not stray from CVS's centralised client/server
   7.717 -      model, but it adds multi-file atomic commits, better namespace
   7.718 -      management, and a number of other features that make it a
   7.719 -      generally better tool than CVS. Since its initial release, it
   7.720 -      has rapidly grown in popularity.</para>
   7.721 -
   7.722 -    <para id="x_ce">More or less simultaneously, Graydon Hoare began working on
   7.723 -      an ambitious distributed revision control system that he named
   7.724 -      Monotone. While Monotone addresses many of CVS's design flaws
   7.725 -      and has a peer-to-peer architecture, it goes beyond earlier (and
   7.726 -      subsequent) revision control tools in a number of innovative
   7.727 -      ways.  It uses cryptographic hashes as identifiers, and has an
   7.728 -      integral notion of <quote>trust</quote> for code from different
   7.729 -      sources.</para>
   7.730 -
   7.731 -    <para id="x_cf">Mercurial began life in 2005.  While a few aspects of its
   7.732 -      design are influenced by Monotone, Mercurial focuses on ease of
   7.733 -      use, high performance, and scalability to very large
   7.734 +    <title>Technical storytelling</title>
   7.735 +
   7.736 +    <para id="x_72e">A few years ago, when I wanted to explain why I believed
   7.737 +      that distributed revision control is important, the field was
   7.738 +      then so new that there was almost no published literature to
   7.739 +      refer people to.</para>
   7.740 +
   7.741 +    <para id="x_72f">Although at that time I spent some time working on the
   7.742 +      internals of Mercurial itself, I switched to writing this book
   7.743 +      because that seemed like the most effective way to help the
   7.744 +      software to reach a wide audience, along with the idea that
   7.745 +      revision control ought to be distributed in nature.  I publish
   7.746 +      the book online under a liberal license for the same
   7.747 +      reason: to get the word out.</para>
   7.748 +
   7.749 +    <para id="x_730">There's a familiar rhythm to a good software book that
   7.750 +      closely resembles telling a story: What is this thing?  Why does
   7.751 +      it matter?  How will it help me?  How do I use it?  In this
   7.752 +      book, I try to answer those questions for distributed revision
   7.753 +      control in general, and for Mercurial in particular.</para>
   7.754 +  </sect1>
   7.755 +    
   7.756 +  <sect1>
   7.757 +    <title>Thank you for supporting Mercurial</title>
   7.758 +
   7.759 +    <para id="x_731">By purchasing a copy of this book, you are supporting the
   7.760 +      continued development and freedom of Mercurial in particular,
   7.761 +      and of open source and free software in general. O'Reilly Media
   7.762 +      and I are donating my royalties on the sales of this book to the
   7.763 +      Software Freedom Conservancy (<ulink
   7.764 +	url="http://www.softwarefreedom.org/">http://www.softwarefreedom.org/</ulink>) 
   7.765 +      which provides clerical and legal support to Mercurial and a
   7.766 +      number of other prominent and worthy open source software
   7.767        projects.</para>
   7.768 -
   7.769 -  </sect1>
   7.770 -
   7.771 -  <sect1>
   7.772 -    <title>Colophon&emdash;this book is Free</title>
   7.773 -
   7.774 -    <para id="x_d0">This book is licensed under the Open Publication License,
   7.775 -      and is produced entirely using Free Software tools.  It is
   7.776 -      typeset with DocBook XML.  Illustrations are drawn and rendered with
   7.777 -      <ulink url="http://www.inkscape.org/">Inkscape</ulink>.</para>
   7.778 -
   7.779 -    <para id="x_d1">The complete source code for this book is published as a
   7.780 -      Mercurial repository, at <ulink
   7.781 -	url="http://hg.serpentine.com/mercurial/book">http://hg.serpentine.com/mercurial/book</ulink>.</para>
   7.782 -
   7.783 +  </sect1>
   7.784 +
   7.785 +  <sect1>
   7.786 +    <title>Acknowledgments</title>
   7.787 +
   7.788 +    <para id="x_732">This book would not exist were it not for the efforts of
   7.789 +      Matt Mackall, the author and project lead of Mercurial.  He is
   7.790 +      ably assisted by hundreds of volunteer contributors across the
   7.791 +      world.</para>
   7.792 +
   7.793 +    <para id="x_733">My children, Cian and Ruairi, always stood ready to help me
   7.794 +      to unwind with wonderful, madcap little-boy games.  I'd also
   7.795 +      like to thank my ex-wife, Shannon, for her support.</para>
   7.796 +
   7.797 +    <para id="x_734">My colleagues and friends provided help and support in
   7.798 +      innumerable ways.  This list of people is necessarily very
   7.799 +      incomplete: Stephen Hahn, Karyn Ritter, Bonnie Corwin, James
   7.800 +      Vasile, Matt Norwood, Eben Moglen, Bradley Kuhn, Robert Walsh,
   7.801 +      Jeremy Fitzhardinge, Rachel Chalmers.</para>
   7.802 +
   7.803 +    <para id="x_735">I developed this book in the open, posting drafts of
   7.804 +      chapters to the book web site as I completed them.  Readers then
   7.805 +      submitted feedback using a web application that I developed.  By
   7.806 +      the time I finished writing the book, more than 100 people had
   7.807 +      submitted comments, an amazing number considering that the
   7.808 +      comment system was live for only about two months towards the
   7.809 +      end of the writing process.</para>
   7.810 +
   7.811 +    <para id="x_736">I would particularly like to recognize the following people,
   7.812 +      who between them contributed over a third of the total number of
   7.813 +      comments.  I would like to thank them for their care and effort
   7.814 +      in providing so much detailed feedback.</para>
   7.815 +
   7.816 +    <para id="x_737">Martin Geisler, Damien Cassou, Alexey Bakhirkin, Till Plewe,
   7.817 +      Dan Himes, Paul Sargent, Gokberk Hamurcu, Matthijs van der
   7.818 +      Vleuten, Michael Chermside, John Mulligan, Jordi Fita, Jon
   7.819 +      Parise.</para>
   7.820 +
   7.821 +    <para id="x_738">I also want to acknowledge the help of the many people who
   7.822 +      caught errors and provided helpful suggestions throughout the
   7.823 +      book.</para>
   7.824 +
   7.825 +    <para id="x_739">Jeremy W. Sherman, Brian Mearns, Vincent Furia, Iwan
   7.826 +      Luijks, Billy Edwards, Andreas Sliwka, Paweł Sołyga, Eric
   7.827 +      Hanchrow, Steve Nicolai, Michał Masłowski, Kevin Fitch, Johan
   7.828 +      Holmberg, Hal Wine, Volker Simonis, Thomas P Jakobsen, Ted
   7.829 +      Stresen-Reuter, Stephen Rasku, Raphael Das Gupta, Ned
   7.830 +      Batchelder, Lou Keeble, Li Linxiao, Kao Cardoso Félix, Joseph
   7.831 +      Wecker, Jon Prescot, Jon Maken, John Yeary, Jason Harris,
   7.832 +      Geoffrey Zheng, Fredrik Jonson, Ed Davies, David Zumbrunnen,
   7.833 +      David Mercer, David Cabana, Ben Karel, Alan Franzoni, Yousry
   7.834 +      Abdallah, Whitney Young, Vinay Sajip, Tom Towle, Tim Ottinger,
   7.835 +      Thomas Schraitle, Tero Saarni, Ted Mielczarek, Svetoslav
   7.836 +      Agafonkin, Shaun Rowland, Rocco Rutte, Polo-Francois Poli,
   7.837 +      Philip Jenvey, Petr Tesałék, Peter R. Annema, Paul Bonser,
   7.838 +      Olivier Scherler, Olivier Fournier, Nick Parker, Nick Fabry,
   7.839 +      Nicholas Guarracino, Mike Driscoll, Mike Coleman, Mietek Bák,
   7.840 +      Michael Maloney, László Nagy, Kent Johnson, Julio Nobrega, Jord
   7.841 +      Fita, Jonathan March, Jonas Nockert, Jim Tittsler, Jeduan
   7.842 +      Cornejo Legorreta, Jan Larres, James Murphy, Henri Wiechers,
   7.843 +      Hagen Möbius, Gábor Farkas, Fabien Engels, Evert Rol, Evan
   7.844 +      Willms, Eduardo Felipe Castegnaro, Dennis Decker Jensen, Deniz
   7.845 +      Dogan, David Smith, Daed Lee, Christine Slotty, Charles Merriam,
   7.846 +      Guillaume Catto, Brian Dorsey, Bob Nystrom, Benoit Boissinot,
   7.847 +      Avi Rosenschein, Andrew Watts, Andrew Donkin, Alexey Rodriguez,
   7.848 +      Ahmed Chaudhary.</para>
   7.849 +  </sect1>
   7.850 +
   7.851 +  <sect1>
   7.852 +    <title>Conventions Used in This Book</title>
   7.853 +
   7.854 +    <para id="x_73a">The following typographical conventions are used in this
   7.855 +      book:</para>
   7.856 +
   7.857 +    <variablelist>
   7.858 +      <varlistentry>
   7.859 +        <term>Italic</term>
   7.860 +
   7.861 +        <listitem>
   7.862 +          <para id="x_73b">Indicates new terms, URLs, email addresses, filenames,
   7.863 +	    and file extensions.</para>
   7.864 +        </listitem>
   7.865 +      </varlistentry>
   7.866 +
   7.867 +      <varlistentry>
   7.868 +        <term><literal>Constant width</literal></term>
   7.869 +
   7.870 +        <listitem>
   7.871 +          <para id="x_73c">Used for program listings, as well as within
   7.872 +	    paragraphs to refer to program elements such as variable
   7.873 +	    or function names, databases, data types, environment
   7.874 +	    variables, statements, and keywords.</para>
   7.875 +        </listitem>
   7.876 +      </varlistentry>
   7.877 +
   7.878 +      <varlistentry>
   7.879 +        <term><userinput>Constant width bold</userinput></term>
   7.880 +
   7.881 +        <listitem>
   7.882 +          <para id="x_73d">Shows commands or other text that should be typed
   7.883 +	    literally by the user.</para>
   7.884 +        </listitem>
   7.885 +      </varlistentry>
   7.886 +
   7.887 +      <varlistentry>
   7.888 +        <term><replaceable>Constant width italic</replaceable></term>
   7.889 +
   7.890 +        <listitem>
   7.891 +          <para id="x_73e">Shows text that should be replaced with user-supplied
   7.892 +	    values or by values determined by context.</para>
   7.893 +        </listitem>
   7.894 +      </varlistentry>
   7.895 +    </variablelist>
   7.896 +
   7.897 +    <tip>
   7.898 +      <para id="x_73f">This icon signifies a tip, suggestion, or general
   7.899 +	note.</para>
   7.900 +    </tip>
   7.901 +
   7.902 +    <caution>
   7.903 +      <para id="x_740">This icon indicates a warning or caution.</para>
   7.904 +    </caution>
   7.905 +  </sect1>
   7.906 +
   7.907 +  <sect1>
   7.908 +    <title>Using Code Examples</title>
   7.909 +
   7.910 +    <para id="x_741">This book is here to help you get your job done. In general,
   7.911 +      you may use the code in this book in your programs and
   7.912 +      documentation. You do not need to contact us for permission
   7.913 +      unless you’re reproducing a significant portion of the code. For
   7.914 +      example, writing a program that uses several chunks of code from
   7.915 +      this book does not require permission. Selling or distributing a
   7.916 +      CD-ROM of examples from O’Reilly books does require permission.
   7.917 +      Answering a question by citing this book and quoting example
   7.918 +      code does not require permission. Incorporating a significant
   7.919 +      amount of example code from this book into your product’s
   7.920 +      documentation does require permission.</para>
   7.921 +
   7.922 +    <para id="x_742">We appreciate, but do not require, attribution. An
   7.923 +      attribution usually includes the title, author, publisher, and
   7.924 +      ISBN. For example: “<emphasis>Book Title</emphasis> by Some
   7.925 +      Author. Copyright 2008 O’Reilly Media, Inc.,
   7.926 +      978-0-596-xxxx-x.”</para>
   7.927 +
   7.928 +    <para id="x_743">If you feel your use of code examples falls outside fair use
   7.929 +      or the permission given above, feel free to contact us at
   7.930 +      <email>permissions@oreilly.com</email>.</para>
   7.931 +  </sect1>
   7.932 +
   7.933 +  <sect1>
   7.934 +    <title>Safari® Books Online</title>
   7.935 +
   7.936 +    <note role="safarienabled">
   7.937 +      <para id="x_744">When you see a Safari® Books Online icon on the cover of
   7.938 +	your favorite technology book, that means the book is
   7.939 +	available online through the O’Reilly Network Safari
   7.940 +	Bookshelf.</para>
   7.941 +    </note>
   7.942 +
   7.943 +    <para id="x_745">Safari offers a solution that’s better than e-books. It’s a
   7.944 +      virtual library that lets you easily search thousands of top
   7.945 +      tech books, cut and paste code samples, download chapters, and
   7.946 +      find quick answers when you need the most accurate, current
   7.947 +      information. Try it for free at <ulink role="orm:hideurl:ital"
   7.948 +	url="http://my.safaribooksonline.com/?portal=oreilly">http://my.safaribooksonline.com</ulink>.</para>
   7.949 +  </sect1>
   7.950 +
   7.951 +  <sect1>
   7.952 +    <title>How to Contact Us</title>
   7.953 +
   7.954 +    <para id="x_746">Please address comments and questions concerning this book
   7.955 +      to the publisher:</para>
   7.956 +
   7.957 +    <simplelist type="vert">
   7.958 +      <member>O’Reilly Media, Inc.</member>
   7.959 +
   7.960 +      <member>1005 Gravenstein Highway North</member>
   7.961 +
   7.962 +      <member>Sebastopol, CA 95472</member>
   7.963 +
   7.964 +      <member>800-998-9938 (in the United States or Canada)</member>
   7.965 +
   7.966 +      <member>707-829-0515 (international or local)</member>
   7.967 +
   7.968 +      <member>707 829-0104 (fax)</member>
   7.969 +    </simplelist>
   7.970 +
   7.971 +    <para id="x_747">We have a web page for this book, where we list errata,
   7.972 +      examples, and any additional information. You can access this
   7.973 +      page at:</para>
   7.974 +
   7.975 +    <simplelist type="vert">
   7.976 +      <member><ulink url="http://www.oreilly.com/catalog/&lt;catalog
   7.977 +	  page&gt;"></ulink></member>
   7.978 +    </simplelist>
   7.979 +
   7.980 +    <remark>Don’t forget to update the &lt;url&gt; attribute,
   7.981 +      too.</remark>
   7.982 +
   7.983 +    <para id="x_748">To comment or ask technical questions about this book, send
   7.984 +      email to:</para>
   7.985 +
   7.986 +    <simplelist type="vert">
   7.987 +      <member><email>bookquestions@oreilly.com</email></member>
   7.988 +    </simplelist>
   7.989 +
   7.990 +    <para id="x_749">For more information about our books, conferences, Resource
   7.991 +      Centers, and the O’Reilly Network, see our web site at:</para>
   7.992 +
   7.993 +    <simplelist type="vert">
   7.994 +      <member><ulink url="http://www.oreilly.com"></ulink></member>
   7.995 +    </simplelist>
   7.996    </sect1>
   7.997  </preface>
   7.998 +
   7.999  <!--
  7.1000  local variables: 
  7.1001  sgml-parent-document: ("00book.xml" "book" "preface")

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

     9.1 --- a/en/ch01-tour-basic.xml	Sat Apr 18 11:52:33 2009 +0800
     9.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     9.3 @@ -1,930 +0,0 @@
     9.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     9.5 -
     9.6 -<chapter id="chap:tour-basic">
     9.7 -  <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?>
     9.8 -  <title>A tour of Mercurial: the basics</title>
     9.9 -
    9.10 -  <sect1 id="sec:tour:install">
    9.11 -    <title>Installing Mercurial on your system</title>
    9.12 -
    9.13 -    <para id="x_1">Prebuilt binary packages of Mercurial are available for
    9.14 -      every popular operating system.  These make it easy to start
    9.15 -      using Mercurial on your computer immediately.</para>
    9.16 -
    9.17 -    <sect2>
    9.18 -      <title>Windows</title>
    9.19 -
    9.20 -      <para id="x_c">The best version of Mercurial for Windows is
    9.21 -	TortoiseHg, which can be found at <ulink
    9.22 -	  url="http://bitbucket.org/tortoisehg/stable/wiki/Home">http://bitbucket.org/tortoisehg/stable/wiki/Home</ulink>. 
    9.23 -	This package has no external dependencies; it <quote>just
    9.24 -	  works</quote>.  It provides both command line and graphical
    9.25 -	user interfaces.</para>
    9.26 -
    9.27 -    </sect2>
    9.28 -
    9.29 -    <sect2>
    9.30 -      <title>Mac OS X</title>
    9.31 -
    9.32 -      <para id="x_a">Lee Cantey publishes an installer of Mercurial
    9.33 -	for Mac OS X at <ulink
    9.34 -	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para>
    9.35 -    </sect2>
    9.36 -
    9.37 -    <sect2>
    9.38 -      <title>Linux</title>
    9.39 -
    9.40 -      <para id="x_2">Because each Linux distribution has its own packaging
    9.41 -	tools, policies, and rate of development, it's difficult to
    9.42 -	give a comprehensive set of instructions on how to install
    9.43 -	Mercurial binaries.  The version of Mercurial that you will
    9.44 -	end up with can vary depending on how active the person is who
    9.45 -	maintains the package for your distribution.</para>
    9.46 -
    9.47 -      <para id="x_3">To keep things simple, I will focus on installing
    9.48 -	Mercurial from the command line under the most popular Linux
    9.49 -	distributions.  Most of these distributions provide graphical
    9.50 -	package managers that will let you install Mercurial with a
    9.51 -	single click; the package name to look for is
    9.52 -	<literal>mercurial</literal>.</para>
    9.53 -
    9.54 -      <itemizedlist>
    9.55 -	<listitem><para id="x_4">Ubuntu and Debian:</para>
    9.56 -	  <programlisting>apt-get install mercurial</programlisting></listitem>
    9.57 -	<listitem><para id="x_5">Fedora and OpenSUSE:</para>
    9.58 -	  <programlisting>yum install mercurial</programlisting></listitem>
    9.59 -	<listitem><para id="x_6">Gentoo:</para>
    9.60 -	  <programlisting>emerge mercurial</programlisting></listitem>
    9.61 -      </itemizedlist>
    9.62 -
    9.63 -    </sect2>
    9.64 -    <sect2>
    9.65 -      <title>Solaris</title>
    9.66 -
    9.67 -      <para id="x_9">SunFreeWare, at <ulink
    9.68 -	  url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 
    9.69 -	provides prebuilt packages of Mercurial.</para>
    9.70 -
    9.71 -    </sect2>
    9.72 -
    9.73 -  </sect1>
    9.74 -
    9.75 -  <sect1>
    9.76 -    <title>Getting started</title>
    9.77 -
    9.78 -    <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg
    9.79 -	version</command> command to find out whether Mercurial is
    9.80 -      actually installed properly.  The actual version information
    9.81 -      that it prints isn't so important; it's whether it prints
    9.82 -      anything at all that we care about.</para>
    9.83 -
    9.84 -    &interaction.tour.version;
    9.85 -
    9.86 -    <sect2>
    9.87 -      <title>Built-in help</title>
    9.88 -
    9.89 -      <para id="x_f">Mercurial provides a built-in help system.  This is
    9.90 -	  invaluable for those times when you find yourself stuck
    9.91 -	  trying to remember how to run a command.  If you are
    9.92 -	  completely stuck, simply run <command role="hg-cmd">hg
    9.93 -	    help</command>; it will print a brief list of commands,
    9.94 -	  along with a description of what each does.  If you ask for
    9.95 -	  help on a specific command (as below), it prints more
    9.96 -	  detailed information.</para>
    9.97 -
    9.98 -	&interaction.tour.help;
    9.99 -
   9.100 -	<para id="x_10">For a more impressive level of detail (which you won't
   9.101 -	  usually need) run <command role="hg-cmd">hg help <option
   9.102 -	      role="hg-opt-global">-v</option></command>.  The <option
   9.103 -	    role="hg-opt-global">-v</option> option is short for
   9.104 -	  <option role="hg-opt-global">--verbose</option>, and tells
   9.105 -	  Mercurial to print more information than it usually
   9.106 -	  would.</para>
   9.107 -
   9.108 -    </sect2>
   9.109 -  </sect1>
   9.110 -  <sect1>
   9.111 -    <title>Working with a repository</title>
   9.112 -
   9.113 -    <para id="x_11">In Mercurial, everything happens inside a
   9.114 -      <emphasis>repository</emphasis>.  The repository for a project
   9.115 -      contains all of the files that <quote>belong to</quote> that
   9.116 -      project, along with a historical record of the project's
   9.117 -      files.</para>
   9.118 -
   9.119 -    <para id="x_12">There's nothing particularly magical about a repository; it
   9.120 -      is simply a directory tree in your filesystem that Mercurial
   9.121 -      treats as special. You can rename or delete a repository any
   9.122 -      time you like, using either the command line or your file
   9.123 -      browser.</para>
   9.124 -
   9.125 -    <sect2>
   9.126 -      <title>Making a local copy of a repository</title>
   9.127 -
   9.128 -      <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little
   9.129 -	bit special.  While you could use a normal file copying
   9.130 -	command to make a copy of a repository, it's best to use a
   9.131 -	built-in command that Mercurial provides.  This command is
   9.132 -	called <command role="hg-cmd">hg clone</command>, because it
   9.133 -	makes an identical copy of an existing repository.</para>
   9.134 -
   9.135 -      &interaction.tour.clone;
   9.136 -
   9.137 -      <para id="x_67c">One advantage of using <command role="hg-cmd">hg
   9.138 -	  clone</command> is that, as we can see above, it lets us clone
   9.139 -	repositories over the network.  Another is that it remembers
   9.140 -	where we cloned from, which we'll find useful soon when we
   9.141 -	want to fetch new changes from another repository.</para>
   9.142 -
   9.143 -      <para id="x_14">If our clone succeeded, we should now have a local
   9.144 -	directory called <filename class="directory">hello</filename>.
   9.145 -	This directory will contain some files.</para>
   9.146 -
   9.147 -      &interaction.tour.ls;
   9.148 -
   9.149 -      <para id="x_15">These files have the same contents and history in our
   9.150 -	repository as they do in the repository we cloned.</para>
   9.151 -
   9.152 -      <para id="x_16">Every Mercurial repository is complete,
   9.153 -	self-contained, and independent.  It contains its own private
   9.154 -	copy of a project's files and history.  As we just mentioned,
   9.155 -	a cloned repository remembers the location of the repository
   9.156 -	it was cloned from, but Mercurial will not communicate with
   9.157 -	that repository, or any other, unless you tell it to.</para>
   9.158 -
   9.159 -      <para id="x_17">What this means for now is that we're free to experiment
   9.160 -	with our repository, safe in the knowledge that it's a private
   9.161 -	<quote>sandbox</quote> that won't affect anyone else.</para>
   9.162 -
   9.163 -    </sect2>
   9.164 -    <sect2>
   9.165 -      <title>What's in a repository?</title>
   9.166 -
   9.167 -      <para id="x_18">When we take a more detailed look inside a repository, we
   9.168 -	can see that it contains a directory named <filename
   9.169 -	  class="directory">.hg</filename>.  This is where Mercurial
   9.170 -	keeps all of its metadata for the repository.</para>
   9.171 -
   9.172 -      &interaction.tour.ls-a;
   9.173 -
   9.174 -      <para id="x_19">The contents of the <filename
   9.175 -	  class="directory">.hg</filename> directory and its
   9.176 -	subdirectories are private to Mercurial.  Every other file and
   9.177 -	directory in the repository is yours to do with as you
   9.178 -	please.</para>
   9.179 -
   9.180 -      <para id="x_1a">To introduce a little terminology, the <filename
   9.181 -	  class="directory">.hg</filename> directory is the
   9.182 -	<quote>real</quote> repository, and all of the files and
   9.183 -	directories that coexist with it are said to live in the
   9.184 -	<emphasis>working directory</emphasis>.  An easy way to
   9.185 -	remember the distinction is that the
   9.186 -	<emphasis>repository</emphasis> contains the
   9.187 -	<emphasis>history</emphasis> of your project, while the
   9.188 -	<emphasis>working directory</emphasis> contains a
   9.189 -	<emphasis>snapshot</emphasis> of your project at a particular
   9.190 -	point in history.</para>
   9.191 -
   9.192 -    </sect2>
   9.193 -  </sect1>
   9.194 -  <sect1>
   9.195 -    <title>A tour through history</title>
   9.196 -
   9.197 -    <para id="x_1b">One of the first things we might want to do with a new,
   9.198 -      unfamiliar repository is understand its history.  The <command
   9.199 -	role="hg-cmd">hg log</command> command gives us a view of
   9.200 -      the history of changes in the repository.</para>
   9.201 -
   9.202 -    &interaction.tour.log;
   9.203 -
   9.204 -    <para id="x_1c">By default, this command prints a brief paragraph of output
   9.205 -      for each change to the project that was recorded.  In Mercurial
   9.206 -      terminology, we call each of these recorded events a
   9.207 -      <emphasis>changeset</emphasis>, because it can contain a record
   9.208 -      of changes to several files.</para>
   9.209 -
   9.210 -    <para id="x_1d">The fields in a record of output from <command
   9.211 -	role="hg-cmd">hg log</command> are as follows.</para>
   9.212 -
   9.213 -    <itemizedlist>
   9.214 -      <listitem><para id="x_1e"><literal>changeset</literal>: This
   9.215 -	  field has the format of a number, followed by a colon,
   9.216 -	  followed by a hexadecimal (or <emphasis>hex</emphasis>)
   9.217 -	  string.  These are <emphasis>identifiers</emphasis> for the
   9.218 -	  changeset.  The hex string is a unique identifier: the same
   9.219 -	  hex string will always refer to the same changeset. The
   9.220 -	  number is shorter and easier to type than the hex string,
   9.221 -	  but it isn't unique: the same number in two different clones
   9.222 -	  of a repository may identify different changesets.  Why
   9.223 -	  provide the number at all, then?  For local
   9.224 -	  convenience.</para>
   9.225 -      </listitem>
   9.226 -      <listitem><para id="x_1f"><literal>user</literal>: The identity of the
   9.227 -	  person who created the changeset.  This is a free-form
   9.228 -	  field, but it most often contains a person's name and email
   9.229 -	  address.</para></listitem>
   9.230 -      <listitem><para id="x_20"><literal>date</literal>: The date and time on
   9.231 -	  which the changeset was created, and the timezone in which
   9.232 -	  it was created.  (The date and time are local to that
   9.233 -	  timezone; they display what time and date it was for the
   9.234 -	  person who created the changeset.)</para></listitem>
   9.235 -      <listitem><para id="x_21"><literal>summary</literal>: The first line of
   9.236 -	  the text message that the creator of the changeset entered
   9.237 -	  to describe the changeset.</para></listitem>
   9.238 -      <listitem>
   9.239 -	<para id="x_67d">Some changesets, such as the first in the list above,
   9.240 -	  have a <literal>tag</literal> field.  A tag is another way
   9.241 -	  to identify a changeset, by giving it an easy-to-remember
   9.242 -	  name. (The tag named <literal>tip</literal> is special: it
   9.243 -	  always refers to the newest change in a repository.)</para>
   9.244 -      </listitem>
   9.245 -    </itemizedlist>
   9.246 -
   9.247 -    <para id="x_22">The default output printed by <command
   9.248 -	role="hg-cmd">hg log</command> is purely a summary; it is
   9.249 -      missing a lot of detail.</para>
   9.250 -
   9.251 -    <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides
   9.252 -      a graphical representation of the history of the <filename
   9.253 -	class="directory">hello</filename> repository, to make it a
   9.254 -      little easier to see which direction history is
   9.255 -      <quote>flowing</quote> in.  We'll be returning to this figure
   9.256 -      several times in this chapter and the chapter that
   9.257 -      follows.</para>
   9.258 -
   9.259 -    <figure id="fig:tour-basic:history">
   9.260 -      <title>Graphical history of the <filename
   9.261 -	  class="directory">hello</filename> repository</title>
   9.262 -      <mediaobject>
   9.263 -	<imageobject><imagedata fileref="figs/tour-history.png"/></imageobject>
   9.264 -	<textobject><phrase>XXX add text</phrase></textobject>
   9.265 -      </mediaobject>
   9.266 -    </figure>
   9.267 -
   9.268 -    <sect2>
   9.269 -      <title>Changesets, revisions, and talking to other
   9.270 -	people</title>
   9.271 -
   9.272 -      <para id="x_25">As English is a notoriously sloppy language, and computer
   9.273 -	science has a hallowed history of terminological confusion
   9.274 -	(why use one term when four will do?), revision control has a
   9.275 -	variety of words and phrases that mean the same thing.  If you
   9.276 -	are talking about Mercurial history with other people, you
   9.277 -	will find that the word <quote>changeset</quote> is often
   9.278 -	compressed to <quote>change</quote> or (when written)
   9.279 -	<quote>cset</quote>, and sometimes a changeset is referred to
   9.280 -	as a <quote>revision</quote> or a <quote>rev</quote>.</para>
   9.281 -
   9.282 -      <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you
   9.283 -	use to refer to the concept of <quote>a changeset</quote>, the
   9.284 -	<emphasis>identifier</emphasis> that you use to refer to
   9.285 -	<quote>a <emphasis>specific</emphasis> changeset</quote> is of
   9.286 -	great importance. Recall that the <literal>changeset</literal>
   9.287 -	field in the output from <command role="hg-cmd">hg
   9.288 -	  log</command> identifies a changeset using both a number and
   9.289 -	a hexadecimal string.</para>
   9.290 -      <itemizedlist>
   9.291 -	<listitem><para id="x_27">The revision number is a handy
   9.292 -	    notation that is <emphasis>only valid in that
   9.293 -	      repository</emphasis>.</para></listitem>
   9.294 -	<listitem><para id="x_28">The hexadecimal string is the
   9.295 -	    <emphasis>permanent, unchanging identifier</emphasis> that
   9.296 -	    will always identify that exact changeset in
   9.297 -	    <emphasis>every</emphasis> copy of the
   9.298 -	    repository.</para></listitem></itemizedlist>
   9.299 -
   9.300 -      <para id="x_29">This distinction is important.  If you send
   9.301 -	someone an email talking about <quote>revision 33</quote>,
   9.302 -	there's a high likelihood that their revision 33 will
   9.303 -	<emphasis>not be the same</emphasis> as yours.  The reason for
   9.304 -	this is that a revision number depends on the order in which
   9.305 -	changes arrived in a repository, and there is no guarantee
   9.306 -	that the same changes will happen in the same order in
   9.307 -	different repositories. Three changes <literal>a,b,c</literal>
   9.308 -	can easily appear in one repository as
   9.309 -	<literal>0,1,2</literal>, while in another as
   9.310 -	<literal>0,2,1</literal>.</para>
   9.311 -
   9.312 -      <para id="x_2a">Mercurial uses revision numbers purely as a convenient
   9.313 -	shorthand.  If you need to discuss a changeset with someone,
   9.314 -	or make a record of a changeset for some other reason (for
   9.315 -	example, in a bug report), use the hexadecimal
   9.316 -	identifier.</para>
   9.317 -
   9.318 -    </sect2>
   9.319 -    <sect2>
   9.320 -      <title>Viewing specific revisions</title>
   9.321 -
   9.322 -      <para id="x_2b">To narrow the output of <command role="hg-cmd">hg
   9.323 -	  log</command> down to a single revision, use the <option
   9.324 -	  role="hg-opt-log">-r</option> (or <option
   9.325 -	  role="hg-opt-log">--rev</option>) option.  You can use
   9.326 -	either a revision number or a hexadecimal identifier,
   9.327 -	and you can provide as many revisions as you want.</para>
   9.328 -
   9.329 -      &interaction.tour.log-r;
   9.330 -
   9.331 -      <para id="x_2c">If you want to see the history of several revisions
   9.332 -	without having to list each one, you can use <emphasis>range
   9.333 -	  notation</emphasis>; this lets you express the idea <quote>I
   9.334 -	  want all revisions between <literal>abc</literal> and
   9.335 -	  <literal>def</literal>, inclusive</quote>.</para>
   9.336 -      
   9.337 -	&interaction.tour.log.range;
   9.338 -
   9.339 -      <para id="x_2d">Mercurial also honours the order in which you specify
   9.340 -	revisions, so <command role="hg-cmd">hg log -r 2:4</command>
   9.341 -	prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
   9.342 -	  4:2</command> prints 4, 3, and 2.</para>
   9.343 -
   9.344 -    </sect2>
   9.345 -    <sect2>
   9.346 -      <title>More detailed information</title>
   9.347 -
   9.348 -      <para id="x_2e">While the summary information printed by <command
   9.349 -	  role="hg-cmd">hg log</command> is useful if you already know
   9.350 -	what you're looking for, you may need to see a complete
   9.351 -	description of the change, or a list of the files changed, if
   9.352 -	you're trying to decide whether a changeset is the one you're
   9.353 -	looking for. The <command role="hg-cmd">hg log</command>
   9.354 -	command's <option role="hg-opt-global">-v</option> (or <option
   9.355 -	  role="hg-opt-global">--verbose</option>) option gives you
   9.356 -	this extra detail.</para>
   9.357 -
   9.358 -      &interaction.tour.log-v;
   9.359 -
   9.360 -      <para id="x_2f">If you want to see both the description and
   9.361 -	content of a change, add the <option
   9.362 -	  role="hg-opt-log">-p</option> (or <option
   9.363 -	  role="hg-opt-log">--patch</option>) option.  This displays
   9.364 -	the content of a change as a <emphasis>unified diff</emphasis>
   9.365 -	(if you've never seen a unified diff before, see <xref
   9.366 -	  linkend="sec:mq:patch"/> for an overview).</para>
   9.367 -
   9.368 -      &interaction.tour.log-vp;
   9.369 -
   9.370 -      <para id="x_67e">The <option role="hg-opt-log">-p</option> option is
   9.371 -	tremendously useful, so it's well worth remembering.</para>
   9.372 -
   9.373 -    </sect2>
   9.374 -  </sect1>
   9.375 -
   9.376 -  <sect1>
   9.377 -    <title>All about command options</title>
   9.378 -
   9.379 -    <para id="x_30">Let's take a brief break from exploring Mercurial commands
   9.380 -      to discuss a pattern in the way that they work; you may find
   9.381 -      this useful to keep in mind as we continue our tour.</para>
   9.382 -
   9.383 -    <para id="x_31">Mercurial has a consistent and straightforward approach to
   9.384 -      dealing with the options that you can pass to commands.  It
   9.385 -      follows the conventions for options that are common to modern
   9.386 -      Linux and Unix systems.</para>
   9.387 -
   9.388 -    <itemizedlist>
   9.389 -      <listitem>
   9.390 -	<para id="x_32">Every option has a long name.  For example, as
   9.391 -	  we've already seen, the <command role="hg-cmd">hg
   9.392 -	    log</command> command accepts a <option
   9.393 -	    role="hg-opt-log">--rev</option> option.</para>
   9.394 -      </listitem>
   9.395 -      <listitem>
   9.396 -	<para id="x_33">Most options have short names, too.  Instead
   9.397 -	  of <option role="hg-opt-log">--rev</option>, we can use
   9.398 -	  <option role="hg-opt-log">-r</option>.  (The reason that
   9.399 -	  some options don't have short names is that the options in
   9.400 -	  question are rarely used.)</para>
   9.401 -      </listitem>
   9.402 -      <listitem>
   9.403 -	<para id="x_34">Long options start with two dashes (e.g.
   9.404 -	  <option role="hg-opt-log">--rev</option>), while short
   9.405 -	  options start with one (e.g. <option
   9.406 -	    role="hg-opt-log">-r</option>).</para>
   9.407 -      </listitem>
   9.408 -      <listitem>
   9.409 -	<para id="x_35">Option naming and usage is consistent across
   9.410 -	  commands.  For example, every command that lets you specify
   9.411 -	  a changeset ID or revision number accepts both <option
   9.412 -	    role="hg-opt-log">-r</option> and <option
   9.413 -	    role="hg-opt-log">--rev</option> arguments.</para>
   9.414 -      </listitem>
   9.415 -      <listitem>
   9.416 -	<para id="x_67f">If you are using short options, you can save typing by
   9.417 -	  running them together. For example, the command <command
   9.418 -	    role="hg-cmd">hg log -v -p -r 2</command> can be written
   9.419 -	  as <command role="hg-cmd">hg log -vpr2</command>.</para>
   9.420 -      </listitem>
   9.421 -    </itemizedlist>
   9.422 -
   9.423 -    <para id="x_36">In the examples throughout this book, I use short options
   9.424 -      instead of long.  This just reflects my own preference, so don't
   9.425 -      read anything significant into it.</para>
   9.426 -
   9.427 -    <para id="x_37">Most commands that print output of some kind will print more
   9.428 -      output when passed a <option role="hg-opt-global">-v</option>
   9.429 -      (or <option role="hg-opt-global">--verbose</option>) option, and
   9.430 -      less when passed <option role="hg-opt-global">-q</option> (or
   9.431 -      <option role="hg-opt-global">--quiet</option>).</para>
   9.432 -
   9.433 -    <note>
   9.434 -      <title>Option naming consistency</title>
   9.435 -
   9.436 -      <para id="x_680">Almost always, Mercurial commands use consistent option
   9.437 -	names to refer to the same concepts.  For instance, if a
   9.438 -	command deals with changesets, you'll always identify them
   9.439 -	with <option role="hg-opt-log">--rev</option> or <option
   9.440 -	  role="hg-opt-log">-r</option>.  This consistent use of
   9.441 -	option names makes it easier to remember what options a
   9.442 -	particular command takes.</para>
   9.443 -    </note>
   9.444 -
   9.445 -  </sect1>
   9.446 -  <sect1>
   9.447 -    <title>Making and reviewing changes</title>
   9.448 -
   9.449 -    <para id="x_38">Now that we have a grasp of viewing history in Mercurial,
   9.450 -      let's take a look at making some changes and examining
   9.451 -      them.</para>
   9.452 -
   9.453 -    <para id="x_39">The first thing we'll do is isolate our experiment in a
   9.454 -      repository of its own.  We use the <command role="hg-cmd">hg
   9.455 -	clone</command> command, but we don't need to clone a copy of
   9.456 -      the remote repository.  Since we already have a copy of it
   9.457 -      locally, we can just clone that instead.  This is much faster
   9.458 -      than cloning over the network, and cloning a local repository
   9.459 -      uses less disk space in most cases, too<footnote>
   9.460 -	<para id="x_681">The saving of space arises when source and destination
   9.461 -	  repositories are on the same filesystem, in which case
   9.462 -	  Mercurial will use hardlinks to do copy-on-write sharing of
   9.463 -	  its internal metadata.  If that explanation meant nothing to
   9.464 -	  you, don't worry: everything happens transparently and
   9.465 -	  automatically, and you don't need to understand it.</para>
   9.466 -	</footnote>.</para>
   9.467 -
   9.468 -    &interaction.tour.reclone;
   9.469 -
   9.470 -    <para id="x_3a">As an aside, it's often good practice to keep a
   9.471 -      <quote>pristine</quote> copy of a remote repository around,
   9.472 -      which you can then make temporary clones of to create sandboxes
   9.473 -      for each task you want to work on.  This lets you work on
   9.474 -      multiple tasks in parallel, each isolated from the others until
   9.475 -      it's complete and you're ready to integrate it back.  Because
   9.476 -      local clones are so cheap, there's almost no overhead to cloning
   9.477 -      and destroying repositories whenever you want.</para>
   9.478 -
   9.479 -    <para id="x_3b">In our <filename class="directory">my-hello</filename>
   9.480 -      repository, we have a file <filename>hello.c</filename> that
   9.481 -      contains the classic <quote>hello, world</quote> program.</para>
   9.482 -
   9.483 -    &interaction.tour.cat1;
   9.484 -
   9.485 -    <para id="x_682">Let's edit this file so that it prints a second line of
   9.486 -      output.</para>
   9.487 -
   9.488 -    &interaction.tour.cat2;
   9.489 -
   9.490 -    <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command>
   9.491 -      command will tell us what Mercurial knows about the files in the
   9.492 -      repository.</para>
   9.493 -
   9.494 -    &interaction.tour.status;
   9.495 -
   9.496 -    <para id="x_3d">The <command role="hg-cmd">hg status</command> command
   9.497 -      prints no output for some files, but a line starting with
   9.498 -      <quote><literal>M</literal></quote> for
   9.499 -      <filename>hello.c</filename>.  Unless you tell it to, <command
   9.500 -	role="hg-cmd">hg status</command> will not print any output
   9.501 -      for files that have not been modified.</para>
   9.502 -
   9.503 -    <para id="x_3e">The <quote><literal>M</literal></quote> indicates that
   9.504 -      Mercurial has noticed that we modified
   9.505 -      <filename>hello.c</filename>.  We didn't need to
   9.506 -      <emphasis>inform</emphasis> Mercurial that we were going to
   9.507 -      modify the file before we started, or that we had modified the
   9.508 -      file after we were done; it was able to figure this out
   9.509 -      itself.</para>
   9.510 -
   9.511 -    <para id="x_3f">It's somewhat helpful to know that we've modified
   9.512 -      <filename>hello.c</filename>, but we might prefer to know
   9.513 -      exactly <emphasis>what</emphasis> changes we've made to it.  To
   9.514 -      do this, we use the <command role="hg-cmd">hg diff</command>
   9.515 -      command.</para>
   9.516 -
   9.517 -    &interaction.tour.diff;
   9.518 -
   9.519 -    <tip>
   9.520 -      <title>Understanding patches</title>
   9.521 -
   9.522 -      <para id="x_683">Remember to take a look at <xref
   9.523 -	  linkend="sec:mq:patch"/> if you don't know how to read
   9.524 -	output above.</para>
   9.525 -    </tip>
   9.526 -  </sect1>
   9.527 -  <sect1>
   9.528 -    <title>Recording changes in a new changeset</title>
   9.529 -
   9.530 -    <para id="x_40">We can modify files, build and test our changes, and use
   9.531 -      <command role="hg-cmd">hg status</command> and <command
   9.532 -	role="hg-cmd">hg diff</command> to review our changes, until
   9.533 -      we're satisfied with what we've done and arrive at a natural
   9.534 -      stopping point where we want to record our work in a new
   9.535 -      changeset.</para>
   9.536 -
   9.537 -    <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets
   9.538 -      us create a new changeset; we'll usually refer to this as
   9.539 -      <quote>making a commit</quote> or
   9.540 -      <quote>committing</quote>.</para>
   9.541 -
   9.542 -    <sect2>
   9.543 -      <title>Setting up a username</title>
   9.544 -
   9.545 -      <para id="x_42">When you try to run <command role="hg-cmd">hg
   9.546 -	  commit</command> for the first time, it is not guaranteed to
   9.547 -	succeed.  Mercurial records your name and address with each
   9.548 -	change that you commit, so that you and others will later be
   9.549 -	able to tell who made each change.  Mercurial tries to
   9.550 -	automatically figure out a sensible username to commit the
   9.551 -	change with.  It will attempt each of the following methods,
   9.552 -	in order:</para>
   9.553 -      <orderedlist>
   9.554 -	<listitem><para id="x_43">If you specify a <option
   9.555 -	      role="hg-opt-commit">-u</option> option to the <command
   9.556 -	      role="hg-cmd">hg commit</command> command on the command
   9.557 -	    line, followed by a username, this is always given the
   9.558 -	    highest precedence.</para></listitem>
   9.559 -	<listitem><para id="x_44">If you have set the <envar>HGUSER</envar>
   9.560 -	    environment variable, this is checked
   9.561 -	    next.</para></listitem>
   9.562 -	<listitem><para id="x_45">If you create a file in your home
   9.563 -	    directory called <filename
   9.564 -	      role="special">.hgrc</filename>, with a <envar
   9.565 -	      role="rc-item-ui">username</envar> entry, that will be
   9.566 -	    used next.  To see what the contents of this file should
   9.567 -	    look like, refer to <xref
   9.568 -	      linkend="sec:tour-basic:username"/>
   9.569 -	    below.</para></listitem>
   9.570 -	<listitem><para id="x_46">If you have set the <envar>EMAIL</envar>
   9.571 -	    environment variable, this will be used
   9.572 -	    next.</para></listitem>
   9.573 -	<listitem><para id="x_47">Mercurial will query your system to find out
   9.574 -	    your local user name and host name, and construct a
   9.575 -	    username from these components. Since this often results
   9.576 -	    in a username that is not very useful, it will print a
   9.577 -	    warning if it has to do
   9.578 -	    this.</para></listitem>
   9.579 -      </orderedlist>
   9.580 -      <para id="x_48">If all of these mechanisms fail, Mercurial will
   9.581 -	  fail, printing an error message.  In this case, it will not
   9.582 -	  let you commit until you set up a
   9.583 -	  username.</para>
   9.584 -      <para id="x_49">You should think of the <envar>HGUSER</envar> environment
   9.585 -	variable and the <option role="hg-opt-commit">-u</option>
   9.586 -	option to the <command role="hg-cmd">hg commit</command>
   9.587 -	command as ways to <emphasis>override</emphasis> Mercurial's
   9.588 -	default selection of username.  For normal use, the simplest
   9.589 -	and most robust way to set a username for yourself is by
   9.590 -	creating a <filename role="special">.hgrc</filename> file; see
   9.591 -	below for details.</para>
   9.592 -      <sect3 id="sec:tour-basic:username">
   9.593 -	<title>Creating a Mercurial configuration file</title>
   9.594 -
   9.595 -	<para id="x_4a">To set a user name, use your favorite editor
   9.596 -	    to create a file called <filename
   9.597 -	      role="special">.hgrc</filename> in your home directory.
   9.598 -	    Mercurial will use this file to look up your personalised
   9.599 -	    configuration settings.  The initial contents of your
   9.600 -	    <filename role="special">.hgrc</filename> should look like
   9.601 -	    this.</para>
   9.602 -
   9.603 -	<remark>Figure out what the appropriate directory is on
   9.604 -	  Windows.</remark>
   9.605 -
   9.606 -	<programlisting># This is a Mercurial configuration file.
   9.607 -[ui]
   9.608 -username = Firstname Lastname &lt;email.address@domain.net&gt;</programlisting>
   9.609 -
   9.610 -	<para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a
   9.611 -	  <emphasis>section</emphasis> of the config file, so you can
   9.612 -	  read the <quote><literal>username = ...</literal></quote>
   9.613 -	  line as meaning <quote>set the value of the
   9.614 -	    <literal>username</literal> item in the
   9.615 -	    <literal>ui</literal> section</quote>. A section continues
   9.616 -	  until a new section begins, or the end of the file.
   9.617 -	  Mercurial ignores empty lines and treats any text from
   9.618 -	  <quote><literal>#</literal></quote> to the end of a line as
   9.619 -	  a comment.</para>
   9.620 -      </sect3>
   9.621 -
   9.622 -      <sect3>
   9.623 -	<title>Choosing a user name</title>
   9.624 -
   9.625 -	<para id="x_4c">You can use any text you like as the value of
   9.626 -	    the <literal>username</literal> config item, since this
   9.627 -	    information is for reading by other people, but will not be
   9.628 -	    interpreted by Mercurial.  The convention that most
   9.629 -	    people follow is to use their name and email address, as
   9.630 -	    in the example above.</para>
   9.631 -	<note>
   9.632 -	  <para id="x_4d">Mercurial's built-in web server obfuscates
   9.633 -	      email addresses, to make it more difficult for the email
   9.634 -	      harvesting tools that spammers use. This reduces the
   9.635 -	      likelihood that you'll start receiving more junk email
   9.636 -	      if you publish a Mercurial repository on the
   9.637 -	      web.</para></note>
   9.638 -
   9.639 -      </sect3>
   9.640 -    </sect2>
   9.641 -    <sect2>
   9.642 -      <title>Writing a commit message</title>
   9.643 -
   9.644 -      <para id="x_4e">When we commit a change, Mercurial drops us into
   9.645 -	  a text editor, to enter a message that will describe the
   9.646 -	  modifications we've made in this changeset.  This is called
   9.647 -	  the <emphasis>commit message</emphasis>.  It will be a
   9.648 -	  record for readers of what we did and why, and it will be
   9.649 -	  printed by <command role="hg-cmd">hg log</command> after
   9.650 -	  we've finished committing.</para>
   9.651 -
   9.652 -       &interaction.tour.commit;
   9.653 -
   9.654 -      <para id="x_4f">The editor that the <command role="hg-cmd">hg
   9.655 -	    commit</command> command drops us into will contain an
   9.656 -	  empty line or two, followed by a number of lines starting with
   9.657 -	  <quote><literal>HG:</literal></quote>.</para>
   9.658 -
   9.659 -    <programlisting>
   9.660 -This is where I type my commit comment.
   9.661 -
   9.662 -HG: Enter commit message.  Lines beginning with 'HG:' are removed.
   9.663 -HG: --
   9.664 -HG: user: Bryan O'Sullivan &lt;bos@serpentine.com&gt;
   9.665 -HG: branch 'default'
   9.666 -HG: changed hello.c</programlisting>
   9.667 -
   9.668 -      <para id="x_50">Mercurial ignores the lines that start with
   9.669 -	  <quote><literal>HG:</literal></quote>; it uses them only to
   9.670 -	  tell us which files it's recording changes to.  Modifying or
   9.671 -	  deleting these lines has no effect.</para>
   9.672 -    </sect2>
   9.673 -    <sect2>
   9.674 -      <title>Writing a good commit message</title>
   9.675 -
   9.676 -      <para id="x_51">Since <command role="hg-cmd">hg log</command>
   9.677 -	  only prints the first line of a commit message by default,
   9.678 -	  it's best to write a commit message whose first line stands
   9.679 -	  alone.  Here's a real example of a commit message that
   9.680 -	  <emphasis>doesn't</emphasis> follow this guideline, and
   9.681 -	  hence has a summary that is not
   9.682 -	  readable.</para>
   9.683 -
   9.684 -      <programlisting>
   9.685 -changeset:   73:584af0e231be
   9.686 -user:        Censored Person &lt;censored.person@example.org&gt;
   9.687 -date:        Tue Sep 26 21:37:07 2006 -0700
   9.688 -summary:     include buildmeister/commondefs. Add exports.</programlisting>
   9.689 -
   9.690 -      <para id="x_52">As far as the remainder of the contents of the
   9.691 -	  commit message are concerned, there are no hard-and-fast
   9.692 -	  rules.  Mercurial itself doesn't interpret or care about the
   9.693 -	  contents of the commit message, though your project may have
   9.694 -	  policies that dictate a certain kind of
   9.695 -	  formatting.</para>
   9.696 -      <para id="x_53">My personal preference is for short, but
   9.697 -	  informative, commit messages that tell me something that I
   9.698 -	  can't figure out with a quick glance at the output of
   9.699 -	  <command role="hg-cmd">hg log
   9.700 -	    --patch</command>.</para>
   9.701 -    </sect2>
   9.702 -    <sect2>
   9.703 -      <title>Aborting a commit</title>
   9.704 -
   9.705 -      <para id="x_54">If you decide that you don't want to commit
   9.706 -	  while in the middle of editing a commit message, simply exit
   9.707 -	  from your editor without saving the file that it's editing.
   9.708 -	  This will cause nothing to happen to either the repository
   9.709 -	  or the working directory.</para>
   9.710 -      <para id="x_55">If we run the <command role="hg-cmd">hg
   9.711 -	    commit</command> command without any arguments, it records
   9.712 -	  all of the changes we've made, as reported by <command
   9.713 -	    role="hg-cmd">hg status</command> and <command
   9.714 -	    role="hg-cmd">hg diff</command>.</para>
   9.715 -    </sect2>
   9.716 -    <sect2>
   9.717 -      <title>Admiring our new handiwork</title>
   9.718 -
   9.719 -      <para id="x_56">Once we've finished the commit, we can use the
   9.720 -	  <command role="hg-cmd">hg tip</command> command to display
   9.721 -	  the changeset we just created.  This command produces output
   9.722 -	  that is identical to <command role="hg-cmd">hg
   9.723 -	    log</command>, but it only displays the newest revision in
   9.724 -	  the repository.</para>
   9.725 -
   9.726 -      &interaction.tour.tip;
   9.727 -
   9.728 -      <para id="x_57">We refer to the newest revision in the
   9.729 -	repository as the <emphasis>tip revision</emphasis>, or simply
   9.730 -	the <emphasis>tip</emphasis>.</para>
   9.731 -
   9.732 -      <para id="x_684">By the way, the <command role="hg-cmd">hg tip</command>
   9.733 -	command accepts many of the same options as <command
   9.734 -	  role="hg-cmd">hg log</command>, so <option
   9.735 -	  role="hg-opt-global">-v</option> above indicates <quote>be
   9.736 -	  verbose</quote>, <option role="hg-opt-tip">-p</option>
   9.737 -	specifies <quote>print a patch</quote>.  The use of <option
   9.738 -	  role="hg-opt-tip">-p</option> to print patches is another
   9.739 -	example of the consistent naming we mentioned earlier.</para>
   9.740 -    </sect2>
   9.741 -  </sect1>
   9.742 -
   9.743 -  <sect1>
   9.744 -    <title>Sharing changes</title>
   9.745 -
   9.746 -    <para id="x_58">We mentioned earlier that repositories in
   9.747 -	Mercurial are self-contained.  This means that the changeset
   9.748 -	we just created exists only in our <filename
   9.749 -	  class="directory">my-hello</filename> repository.  Let's
   9.750 -	look at a few ways that we can propagate this change into
   9.751 -	other repositories.</para>
   9.752 -
   9.753 -    <sect2 id="sec:tour:pull">
   9.754 -      <title>Pulling changes from another repository</title>
   9.755 -      <para id="x_59">To get started, let's clone our original
   9.756 -	  <filename class="directory">hello</filename> repository,
   9.757 -	  which does not contain the change we just committed.  We'll
   9.758 -	  call our temporary repository <filename
   9.759 -	    class="directory">hello-pull</filename>.</para>
   9.760 -
   9.761 -      &interaction.tour.clone-pull;
   9.762 -
   9.763 -      <para id="x_5a">We'll use the <command role="hg-cmd">hg
   9.764 -	    pull</command> command to bring changes from <filename
   9.765 -	    class="directory">my-hello</filename> into <filename
   9.766 -	    class="directory">hello-pull</filename>.  However, blindly
   9.767 -	  pulling unknown changes into a repository is a somewhat
   9.768 -	  scary prospect.  Mercurial provides the <command
   9.769 -	    role="hg-cmd">hg incoming</command> command to tell us
   9.770 -	  what changes the <command role="hg-cmd">hg pull</command>
   9.771 -	  command <emphasis>would</emphasis> pull into the repository,
   9.772 -	  without actually pulling the changes in.</para>
   9.773 -
   9.774 -      &interaction.tour.incoming;
   9.775 -
   9.776 -      <para id="x_5b">Suppose you're pulling changes from a repository
   9.777 -      on the network somewhere. While you are looking at the <command
   9.778 -	  role="hg-cmd">hg incoming</command> output, and before you
   9.779 -	pull those changes, someone might have committed something in
   9.780 -	the remote repository. This means that it's possible to pull
   9.781 -	more changes than you saw when using <command
   9.782 -	  role="hg-cmd">hg incoming</command>.</para>
   9.783 -
   9.784 -      <para id="x_5c">Bringing changes into a repository is a simple
   9.785 -	  matter of running the <command role="hg-cmd">hg
   9.786 -	    pull</command> command, and telling it which repository to
   9.787 -	  pull from.</para>
   9.788 -
   9.789 -      &interaction.tour.pull;
   9.790 -
   9.791 -      <para id="x_5d">As you can see
   9.792 -	  from the before-and-after output of <command
   9.793 -	    role="hg-cmd">hg tip</command>, we have successfully
   9.794 -	  pulled changes into our repository.  There remains one step
   9.795 -	  before we can see these changes in the working
   9.796 -	  directory.</para>
   9.797 -    </sect2>
   9.798 -    <sect2>
   9.799 -      <title>Updating the working directory</title>
   9.800 -
   9.801 -      <para id="x_5e">We have so far glossed over the relationship
   9.802 -	between a repository and its working directory.  The <command
   9.803 -	  role="hg-cmd">hg pull</command> command that we ran in
   9.804 -	<xref linkend="sec:tour:pull"/> brought changes into the
   9.805 -	repository, but if we check, there's no sign of those changes
   9.806 -	in the working directory.  This is because <command
   9.807 -	  role="hg-cmd">hg pull</command> does not (by default) touch
   9.808 -	the working directory.  Instead, we use the <command
   9.809 -	  role="hg-cmd">hg update</command> command to do this.</para>
   9.810 -
   9.811 -      &interaction.tour.update;
   9.812 -
   9.813 -      <para id="x_5f">It might seem a bit strange that <command role="hg-cmd">hg
   9.814 -	  pull</command> doesn't update the working directory
   9.815 -	automatically.  There's actually a good reason for this: you
   9.816 -	can use <command role="hg-cmd">hg update</command> to update
   9.817 -	the working directory to the state it was in at <emphasis>any
   9.818 -	  revision</emphasis> in the history of the repository.  If
   9.819 -	you had the working directory updated to an old revision&emdash;to
   9.820 -	hunt down the origin of a bug, say&emdash;and ran a <command
   9.821 -	  role="hg-cmd">hg pull</command> which automatically updated
   9.822 -	the working directory to a new revision, you might not be
   9.823 -	terribly happy.</para>
   9.824 -      <para id="x_60">However, since pull-then-update is such a common thing to
   9.825 -	do, Mercurial lets you combine the two by passing the <option
   9.826 -	  role="hg-opt-pull">-u</option> option to <command
   9.827 -	  role="hg-cmd">hg pull</command>.</para>
   9.828 -
   9.829 -      <para id="x_61">If you look back at the output of <command
   9.830 -	  role="hg-cmd">hg pull</command> in <xref
   9.831 -	    linkend="sec:tour:pull"/> when we ran it without <option
   9.832 -	  role="hg-opt-pull">-u</option>, you can see that it printed
   9.833 -	a helpful reminder that we'd have to take an explicit step to
   9.834 -	update the working directory:</para>
   9.835 -
   9.836 -      <!-- &interaction.xxx.fixme; -->
   9.837 -
   9.838 -      <para id="x_62">To find out what revision the working directory is at, use
   9.839 -	the <command role="hg-cmd">hg parents</command>
   9.840 -	command.</para>
   9.841 -
   9.842 -      &interaction.tour.parents;
   9.843 -
   9.844 -      <para id="x_63">If you look back at <xref
   9.845 -	  linkend="fig:tour-basic:history"/>,
   9.846 -	you'll see arrows connecting each changeset.  The node that
   9.847 -	the arrow leads <emphasis>from</emphasis> in each case is a
   9.848 -	parent, and the node that the arrow leads
   9.849 -	<emphasis>to</emphasis> is its child.  The working directory
   9.850 -	has a parent in just the same way; this is the changeset that
   9.851 -	the working directory currently contains.</para>
   9.852 -
   9.853 -      <para id="x_64">To update the working directory to a particular revision,
   9.854 -
   9.855 -	give a revision number or changeset ID to the <command
   9.856 -	  role="hg-cmd">hg update</command> command.</para>
   9.857 -
   9.858 -      &interaction.tour.older;
   9.859 -
   9.860 -      <para id="x_65">If you omit an explicit revision, <command
   9.861 -	  role="hg-cmd">hg update</command> will update to the tip
   9.862 -	revision, as shown by the second call to <command
   9.863 -	  role="hg-cmd">hg update</command> in the example
   9.864 -	above.</para>
   9.865 -    </sect2>
   9.866 -
   9.867 -    <sect2>
   9.868 -      <title>Pushing changes to another repository</title>
   9.869 -
   9.870 -      <para id="x_66">Mercurial lets us push changes to another
   9.871 -	  repository, from the repository we're currently visiting.
   9.872 -	  As with the example of <command role="hg-cmd">hg
   9.873 -	    pull</command> above, we'll create a temporary repository
   9.874 -	  to push our changes into.</para>
   9.875 -
   9.876 -      &interaction.tour.clone-push;
   9.877 -
   9.878 -      <para id="x_67">The <command role="hg-cmd">hg outgoing</command> command
   9.879 -	  tells us what changes would be pushed into another
   9.880 -	  repository.</para>
   9.881 -
   9.882 -      &interaction.tour.outgoing;
   9.883 -
   9.884 -      <para id="x_68">And the
   9.885 -	  <command role="hg-cmd">hg push</command> command does the
   9.886 -	  actual push.</para>
   9.887 -
   9.888 -      &interaction.tour.push;
   9.889 -
   9.890 -      <para id="x_69">As with <command role="hg-cmd">hg
   9.891 -	  pull</command>, the <command role="hg-cmd">hg push</command>
   9.892 -	command does not update the working directory in the
   9.893 -	repository that it's pushing changes into. Unlike <command
   9.894 -	  role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg
   9.895 -	  push</command> does not provide a <literal>-u</literal>
   9.896 -	option that updates the other repository's working directory.
   9.897 -	This asymmetry is deliberate: the repository we're pushing to
   9.898 -	might be on a remote server and shared between several people.
   9.899 -	If we were to update its working directory while someone was
   9.900 -	working in it, their work would be disrupted.</para>
   9.901 -
   9.902 -      <para id="x_6a">What happens if we try to pull or push changes
   9.903 -	  and the receiving repository already has those changes?
   9.904 -	  Nothing too exciting.</para>
   9.905 -
   9.906 -      &interaction.tour.push.nothing;
   9.907 -    </sect2>
   9.908 -    <sect2>
   9.909 -      <title>Sharing changes over a network</title>
   9.910 -
   9.911 -      <para id="x_6b">The commands we have covered in the previous few
   9.912 -	  sections are not limited to working with local repositories.
   9.913 -	  Each works in exactly the same fashion over a network
   9.914 -	  connection; simply pass in a URL instead of a local
   9.915 -	  path.</para>
   9.916 -	
   9.917 -      &interaction.tour.outgoing.net;
   9.918 -
   9.919 -      <para id="x_6c">In this example, we
   9.920 -	  can see what changes we could push to the remote repository,
   9.921 -	  but the repository is understandably not set up to let
   9.922 -	  anonymous users push to it.</para>
   9.923 -
   9.924 -      &interaction.tour.push.net;
   9.925 -    </sect2>
   9.926 -  </sect1>
   9.927 -</chapter>
   9.928 -
   9.929 -<!--
   9.930 -local variables: 
   9.931 -sgml-parent-document: ("00book.xml" "book" "chapter")
   9.932 -end:
   9.933 --->

    10.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    10.2 +++ b/en/ch02-tour-basic.xml	Thu May 21 14:16:17 2009 +0800
    10.3 @@ -0,0 +1,1035 @@
    10.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    10.5 +
    10.6 +<chapter id="chap:tour-basic">
    10.7 +  <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?>
    10.8 +  <title>A tour of Mercurial: the basics</title>
    10.9 +
   10.10 +  <sect1 id="sec:tour:install">
   10.11 +    <title>Installing Mercurial on your system</title>
   10.12 +
   10.13 +    <para id="x_1">Prebuilt binary packages of Mercurial are available for
   10.14 +      every popular operating system.  These make it easy to start
   10.15 +      using Mercurial on your computer immediately.</para>
   10.16 +
   10.17 +    <sect2>
   10.18 +      <title>Windows</title>
   10.19 +
   10.20 +      <para id="x_c">The best version of Mercurial for Windows is
   10.21 +	TortoiseHg, which can be found at <ulink
   10.22 +	  url="http://bitbucket.org/tortoisehg/stable/wiki/Home">http://bitbucket.org/tortoisehg/stable/wiki/Home</ulink>. 
   10.23 +	This package has no external dependencies; it <quote>just
   10.24 +	  works</quote>.  It provides both command line and graphical
   10.25 +	user interfaces.</para>
   10.26 +
   10.27 +    </sect2>
   10.28 +
   10.29 +    <sect2>
   10.30 +      <title>Mac OS X</title>
   10.31 +
   10.32 +      <para id="x_a">Lee Cantey publishes an installer of Mercurial
   10.33 +	for Mac OS X at <ulink
   10.34 +	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para>
   10.35 +    </sect2>
   10.36 +
   10.37 +    <sect2>
   10.38 +      <title>Linux</title>
   10.39 +
   10.40 +      <para id="x_2">Because each Linux distribution has its own packaging
   10.41 +	tools, policies, and rate of development, it's difficult to
   10.42 +	give a comprehensive set of instructions on how to install
   10.43 +	Mercurial binaries.  The version of Mercurial that you will
   10.44 +	end up with can vary depending on how active the person is who
   10.45 +	maintains the package for your distribution.</para>
   10.46 +
   10.47 +      <para id="x_3">To keep things simple, I will focus on installing
   10.48 +	Mercurial from the command line under the most popular Linux
   10.49 +	distributions.  Most of these distributions provide graphical
   10.50 +	package managers that will let you install Mercurial with a
   10.51 +	single click; the package name to look for is
   10.52 +	<literal>mercurial</literal>.</para>
   10.53 +
   10.54 +      <itemizedlist>
   10.55 +	<listitem><para id="x_4">Ubuntu and Debian:</para>
   10.56 +	  <programlisting>apt-get install mercurial</programlisting></listitem>
   10.57 +	<listitem><para id="x_5">Fedora:</para>
   10.58 +	  <programlisting>yum install mercurial</programlisting></listitem>
   10.59 +	<listitem><para id="x_715">OpenSUSE:</para>
   10.60 +	  <programlisting>zypper install mercurial</programlisting></listitem>
   10.61 +	<listitem><para id="x_6">Gentoo:</para>
   10.62 +	  <programlisting>emerge mercurial</programlisting></listitem>
   10.63 +      </itemizedlist>
   10.64 +
   10.65 +    </sect2>
   10.66 +    <sect2>
   10.67 +      <title>Solaris</title>
   10.68 +
   10.69 +      <para id="x_9">SunFreeWare, at <ulink
   10.70 +	  url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 
   10.71 +	provides prebuilt packages of Mercurial.</para>
   10.72 +
   10.73 +    </sect2>
   10.74 +
   10.75 +  </sect1>
   10.76 +
   10.77 +  <sect1>
   10.78 +    <title>Getting started</title>
   10.79 +
   10.80 +    <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg
   10.81 +	version</command> command to find out whether Mercurial is
   10.82 +      installed properly.  The actual version information that it
   10.83 +      prints isn't so important; we simply care whether the command
   10.84 +      runs and prints anything at all.</para>
   10.85 +
   10.86 +    &interaction.tour.version;
   10.87 +
   10.88 +    <sect2>
   10.89 +      <title>Built-in help</title>
   10.90 +
   10.91 +      <para id="x_f">Mercurial provides a built-in help system.  This is
   10.92 +	  invaluable for those times when you find yourself stuck
   10.93 +	  trying to remember how to run a command.  If you are
   10.94 +	  completely stuck, simply run <command role="hg-cmd">hg
   10.95 +	    help</command>; it will print a brief list of commands,
   10.96 +	  along with a description of what each does.  If you ask for
   10.97 +	  help on a specific command (as below), it prints more
   10.98 +	  detailed information.</para>
   10.99 +
  10.100 +	&interaction.tour.help;
  10.101 +
  10.102 +	<para id="x_10">For a more impressive level of detail (which you won't
  10.103 +	  usually need) run <command role="hg-cmd">hg help <option
  10.104 +	      role="hg-opt-global">-v</option></command>.  The <option
  10.105 +	    role="hg-opt-global">-v</option> option is short for
  10.106 +	  <option role="hg-opt-global">--verbose</option>, and tells
  10.107 +	  Mercurial to print more information than it usually
  10.108 +	  would.</para>
  10.109 +
  10.110 +    </sect2>
  10.111 +  </sect1>
  10.112 +  <sect1>
  10.113 +    <title>Working with a repository</title>
  10.114 +
  10.115 +    <para id="x_11">In Mercurial, everything happens inside a
  10.116 +      <emphasis>repository</emphasis>.  The repository for a project
  10.117 +      contains all of the files that <quote>belong to</quote> that
  10.118 +      project, along with a historical record of the project's
  10.119 +      files.</para>
  10.120 +
  10.121 +    <para id="x_12">There's nothing particularly magical about a repository; it
  10.122 +      is simply a directory tree in your filesystem that Mercurial
  10.123 +      treats as special. You can rename or delete a repository any
  10.124 +      time you like, using either the command line or your file
  10.125 +      browser.</para>
  10.126 +
  10.127 +    <sect2>
  10.128 +      <title>Making a local copy of a repository</title>
  10.129 +
  10.130 +      <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little
  10.131 +	bit special.  While you could use a normal file copying
  10.132 +	command to make a copy of a repository, it's best to use a
  10.133 +	built-in command that Mercurial provides.  This command is
  10.134 +	called <command role="hg-cmd">hg clone</command>, because it
  10.135 +	makes an identical copy of an existing repository.</para>
  10.136 +
  10.137 +      &interaction.tour.clone;
  10.138 +
  10.139 +      <para id="x_67c">One advantage of using <command role="hg-cmd">hg
  10.140 +	  clone</command> is that, as we can see above, it lets us clone
  10.141 +	repositories over the network.  Another is that it remembers
  10.142 +	where we cloned from, which we'll find useful soon when we
  10.143 +	want to fetch new changes from another repository.</para>
  10.144 +
  10.145 +      <para id="x_14">If our clone succeeded, we should now have a local
  10.146 +	directory called <filename class="directory">hello</filename>.
  10.147 +	This directory will contain some files.</para>
  10.148 +
  10.149 +      &interaction.tour.ls;
  10.150 +
  10.151 +      <para id="x_15">These files have the same contents and history in our
  10.152 +	repository as they do in the repository we cloned.</para>
  10.153 +
  10.154 +      <para id="x_16">Every Mercurial repository is complete,
  10.155 +	self-contained, and independent.  It contains its own private
  10.156 +	copy of a project's files and history.  As we just mentioned,
  10.157 +	a cloned repository remembers the location of the repository
  10.158 +	it was cloned from, but Mercurial will not communicate with
  10.159 +	that repository, or any other, unless you tell it to.</para>
  10.160 +
  10.161 +      <para id="x_17">What this means for now is that we're free to experiment
  10.162 +	with our repository, safe in the knowledge that it's a private
  10.163 +	<quote>sandbox</quote> that won't affect anyone else.</para>
  10.164 +
  10.165 +    </sect2>
  10.166 +    <sect2>
  10.167 +      <title>What's in a repository?</title>
  10.168 +
  10.169 +      <para id="x_18">When we take a more detailed look inside a repository, we
  10.170 +	can see that it contains a directory named <filename
  10.171 +	  class="directory">.hg</filename>.  This is where Mercurial
  10.172 +	keeps all of its metadata for the repository.</para>
  10.173 +
  10.174 +      &interaction.tour.ls-a;
  10.175 +
  10.176 +      <para id="x_19">The contents of the <filename
  10.177 +	  class="directory">.hg</filename> directory and its
  10.178 +	subdirectories are private to Mercurial.  Every other file and
  10.179 +	directory in the repository is yours to do with as you
  10.180 +	please.</para>
  10.181 +
  10.182 +      <para id="x_1a">To introduce a little terminology, the <filename
  10.183 +	  class="directory">.hg</filename> directory is the
  10.184 +	<quote>real</quote> repository, and all of the files and
  10.185 +	directories that coexist with it are said to live in the
  10.186 +	<emphasis>working directory</emphasis>.  An easy way to
  10.187 +	remember the distinction is that the
  10.188 +	<emphasis>repository</emphasis> contains the
  10.189 +	<emphasis>history</emphasis> of your project, while the
  10.190 +	<emphasis>working directory</emphasis> contains a
  10.191 +	<emphasis>snapshot</emphasis> of your project at a particular
  10.192 +	point in history.</para>
  10.193 +
  10.194 +    </sect2>
  10.195 +  </sect1>
  10.196 +  <sect1>
  10.197 +    <title>A tour through history</title>
  10.198 +
  10.199 +    <para id="x_1b">One of the first things we might want to do with a new,
  10.200 +      unfamiliar repository is understand its history.  The <command
  10.201 +	role="hg-cmd">hg log</command> command gives us a view of
  10.202 +      the history of changes in the repository.</para>
  10.203 +
  10.204 +    &interaction.tour.log;
  10.205 +
  10.206 +    <para id="x_1c">By default, this command prints a brief paragraph of output
  10.207 +      for each change to the project that was recorded.  In Mercurial
  10.208 +      terminology, we call each of these recorded events a
  10.209 +      <emphasis>changeset</emphasis>, because it can contain a record
  10.210 +      of changes to several files.</para>
  10.211 +
  10.212 +    <para id="x_1d">The fields in a record of output from <command
  10.213 +	role="hg-cmd">hg log</command> are as follows.</para>
  10.214 +
  10.215 +    <itemizedlist>
  10.216 +      <listitem><para id="x_1e"><literal>changeset</literal>: This
  10.217 +	  field has the format of a number, followed by a colon,
  10.218 +	  followed by a hexadecimal (or <emphasis>hex</emphasis>)
  10.219 +	  string.  These are <emphasis>identifiers</emphasis> for the
  10.220 +	  changeset.  The hex string is a unique identifier: the same
  10.221 +	  hex string will always refer to the same changeset in every
  10.222 +	  copy of this repository. The
  10.223 +	  number is shorter and easier to type than the hex string,
  10.224 +	  but it isn't unique: the same number in two different clones
  10.225 +	  of a repository may identify different changesets.</para>
  10.226 +      </listitem>
  10.227 +      <listitem><para id="x_1f"><literal>user</literal>: The identity of the
  10.228 +	  person who created the changeset.  This is a free-form
  10.229 +	  field, but it most often contains a person's name and email
  10.230 +	  address.</para></listitem>
  10.231 +      <listitem><para id="x_20"><literal>date</literal>: The date and time on
  10.232 +	  which the changeset was created, and the timezone in which
  10.233 +	  it was created.  (The date and time are local to that
  10.234 +	  timezone; they display what time and date it was for the
  10.235 +	  person who created the changeset.)</para></listitem>
  10.236 +      <listitem><para id="x_21"><literal>summary</literal>: The first line of
  10.237 +	  the text message that the creator of the changeset entered
  10.238 +	  to describe the changeset.</para></listitem>
  10.239 +      <listitem>
  10.240 +	<para id="x_67d">Some changesets, such as the first in the list above,
  10.241 +	  have a <literal>tag</literal> field.  A tag is another way
  10.242 +	  to identify a changeset, by giving it an easy-to-remember
  10.243 +	  name. (The tag named <literal>tip</literal> is special: it
  10.244 +	  always refers to the newest change in a repository.)</para>
  10.245 +      </listitem>
  10.246 +    </itemizedlist>
  10.247 +
  10.248 +    <para id="x_22">The default output printed by <command
  10.249 +	role="hg-cmd">hg log</command> is purely a summary; it is
  10.250 +      missing a lot of detail.</para>
  10.251 +
  10.252 +    <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides
  10.253 +      a graphical representation of the history of the <filename
  10.254 +	class="directory">hello</filename> repository, to make it a
  10.255 +      little easier to see which direction history is
  10.256 +      <quote>flowing</quote> in.  We'll be returning to this figure
  10.257 +      several times in this chapter and the chapter that
  10.258 +      follows.</para>
  10.259 +
  10.260 +    <figure id="fig:tour-basic:history">
  10.261 +      <title>Graphical history of the <filename
  10.262 +	  class="directory">hello</filename> repository</title>
  10.263 +      <mediaobject>
  10.264 +	<imageobject><imagedata fileref="figs/tour-history.png"/></imageobject>
  10.265 +	<textobject><phrase>XXX add text</phrase></textobject>
  10.266 +      </mediaobject>
  10.267 +    </figure>
  10.268 +
  10.269 +    <sect2>
  10.270 +      <title>Changesets, revisions, and talking to other
  10.271 +	people</title>
  10.272 +
  10.273 +      <para id="x_25">As English is a notoriously sloppy language, and computer
  10.274 +	science has a hallowed history of terminological confusion
  10.275 +	(why use one term when four will do?), revision control has a
  10.276 +	variety of words and phrases that mean the same thing.  If you
  10.277 +	are talking about Mercurial history with other people, you
  10.278 +	will find that the word <quote>changeset</quote> is often
  10.279 +	compressed to <quote>change</quote> or (when written)
  10.280 +	<quote>cset</quote>, and sometimes a changeset is referred to
  10.281 +	as a <quote>revision</quote> or a <quote>rev</quote>.</para>
  10.282 +
  10.283 +      <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you
  10.284 +	use to refer to the concept of <quote>a changeset</quote>, the
  10.285 +	<emphasis>identifier</emphasis> that you use to refer to
  10.286 +	<quote>a <emphasis>specific</emphasis> changeset</quote> is of
  10.287 +	great importance. Recall that the <literal>changeset</literal>
  10.288 +	field in the output from <command role="hg-cmd">hg
  10.289 +	  log</command> identifies a changeset using both a number and
  10.290 +	a hexadecimal string.</para>
  10.291 +      <itemizedlist>
  10.292 +	<listitem><para id="x_27">The revision number is a handy
  10.293 +	    notation that is <emphasis>only valid in that
  10.294 +	      repository</emphasis>.</para></listitem>
  10.295 +	<listitem><para id="x_28">The hexadecimal string is the
  10.296 +	    <emphasis>permanent, unchanging identifier</emphasis> that
  10.297 +	    will always identify that exact changeset in
  10.298 +	    <emphasis>every</emphasis> copy of the
  10.299 +	    repository.</para></listitem></itemizedlist>
  10.300 +
  10.301 +      <para id="x_29">This distinction is important.  If you send
  10.302 +	someone an email talking about <quote>revision 33</quote>,
  10.303 +	there's a high likelihood that their revision 33 will
  10.304 +	<emphasis>not be the same</emphasis> as yours.  The reason for
  10.305 +	this is that a revision number depends on the order in which
  10.306 +	changes arrived in a repository, and there is no guarantee
  10.307 +	that the same changes will happen in the same order in
  10.308 +	different repositories. Three changes <literal>a,b,c</literal>
  10.309 +	can easily appear in one repository as
  10.310 +	<literal>0,1,2</literal>, while in another as
  10.311 +	<literal>0,2,1</literal>.</para>
  10.312 +
  10.313 +      <para id="x_2a">Mercurial uses revision numbers purely as a convenient
  10.314 +	shorthand.  If you need to discuss a changeset with someone,
  10.315 +	or make a record of a changeset for some other reason (for
  10.316 +	example, in a bug report), use the hexadecimal
  10.317 +	identifier.</para>
  10.318 +
  10.319 +    </sect2>
  10.320 +    <sect2>
  10.321 +      <title>Viewing specific revisions</title>
  10.322 +
  10.323 +      <para id="x_2b">To narrow the output of <command role="hg-cmd">hg
  10.324 +	  log</command> down to a single revision, use the <option
  10.325 +	  role="hg-opt-log">-r</option> (or <option
  10.326 +	  role="hg-opt-log">--rev</option>) option.  You can use
  10.327 +	either a revision number or a hexadecimal identifier,
  10.328 +	and you can provide as many revisions as you want.</para>
  10.329 +
  10.330 +      &interaction.tour.log-r;
  10.331 +
  10.332 +      <para id="x_2c">If you want to see the history of several revisions
  10.333 +	without having to list each one, you can use <emphasis>range
  10.334 +	  notation</emphasis>; this lets you express the idea <quote>I
  10.335 +	  want all revisions between <literal>abc</literal> and
  10.336 +	  <literal>def</literal>, inclusive</quote>.</para>
  10.337 +      
  10.338 +	&interaction.tour.log.range;
  10.339 +
  10.340 +      <para id="x_2d">Mercurial also honours the order in which you specify
  10.341 +	revisions, so <command role="hg-cmd">hg log -r 2:4</command>
  10.342 +	prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
  10.343 +	  4:2</command> prints 4, 3, and 2.</para>
  10.344 +
  10.345 +    </sect2>
  10.346 +    <sect2>
  10.347 +      <title>More detailed information</title>
  10.348 +
  10.349 +      <para id="x_2e">While the summary information printed by <command
  10.350 +	  role="hg-cmd">hg log</command> is useful if you already know
  10.351 +	what you're looking for, you may need to see a complete
  10.352 +	description of the change, or a list of the files changed, if
  10.353 +	you're trying to decide whether a changeset is the one you're
  10.354 +	looking for. The <command role="hg-cmd">hg log</command>
  10.355 +	command's <option role="hg-opt-global">-v</option> (or <option
  10.356 +	  role="hg-opt-global">--verbose</option>) option gives you
  10.357 +	this extra detail.</para>
  10.358 +
  10.359 +      &interaction.tour.log-v;
  10.360 +
  10.361 +      <para id="x_2f">If you want to see both the description and
  10.362 +	content of a change, add the <option
  10.363 +	  role="hg-opt-log">-p</option> (or <option
  10.364 +	  role="hg-opt-log">--patch</option>) option.  This displays
  10.365 +	the content of a change as a <emphasis>unified diff</emphasis>
  10.366 +	(if you've never seen a unified diff before, see <xref
  10.367 +	  linkend="sec:mq:patch"/> for an overview).</para>
  10.368 +
  10.369 +      &interaction.tour.log-vp;
  10.370 +
  10.371 +      <para id="x_67e">The <option role="hg-opt-log">-p</option> option is
  10.372 +	tremendously useful, so it's well worth remembering.</para>
  10.373 +
  10.374 +    </sect2>
  10.375 +  </sect1>
  10.376 +
  10.377 +  <sect1>
  10.378 +    <title>All about command options</title>
  10.379 +
  10.380 +    <para id="x_30">Let's take a brief break from exploring Mercurial commands
  10.381 +      to discuss a pattern in the way that they work; you may find
  10.382 +      this useful to keep in mind as we continue our tour.</para>
  10.383 +
  10.384 +    <para id="x_31">Mercurial has a consistent and straightforward approach to
  10.385 +      dealing with the options that you can pass to commands.  It
  10.386 +      follows the conventions for options that are common to modern
  10.387 +      Linux and Unix systems.</para>
  10.388 +
  10.389 +    <itemizedlist>
  10.390 +      <listitem>
  10.391 +	<para id="x_32">Every option has a long name.  For example, as
  10.392 +	  we've already seen, the <command role="hg-cmd">hg
  10.393 +	    log</command> command accepts a <option
  10.394 +	    role="hg-opt-log">--rev</option> option.</para>
  10.395 +      </listitem>
  10.396 +      <listitem>
  10.397 +	<para id="x_33">Most options have short names, too.  Instead
  10.398 +	  of <option role="hg-opt-log">--rev</option>, we can use
  10.399 +	  <option role="hg-opt-log">-r</option>.  (The reason that
  10.400 +	  some options don't have short names is that the options in
  10.401 +	  question are rarely used.)</para>
  10.402 +      </listitem>
  10.403 +      <listitem>
  10.404 +	<para id="x_34">Long options start with two dashes (e.g.
  10.405 +	  <option role="hg-opt-log">--rev</option>), while short
  10.406 +	  options start with one (e.g. <option
  10.407 +	    role="hg-opt-log">-r</option>).</para>
  10.408 +      </listitem>
  10.409 +      <listitem>
  10.410 +	<para id="x_35">Option naming and usage is consistent across
  10.411 +	  commands.  For example, every command that lets you specify
  10.412 +	  a changeset ID or revision number accepts both <option
  10.413 +	    role="hg-opt-log">-r</option> and <option
  10.414 +	    role="hg-opt-log">--rev</option> arguments.</para>
  10.415 +      </listitem>
  10.416 +      <listitem>
  10.417 +	<para id="x_67f">If you are using short options, you can save typing by
  10.418 +	  running them together. For example, the command <command
  10.419 +	    role="hg-cmd">hg log -v -p -r 2</command> can be written
  10.420 +	  as <command role="hg-cmd">hg log -vpr2</command>.</para>
  10.421 +      </listitem>
  10.422 +    </itemizedlist>
  10.423 +
  10.424 +    <para id="x_36">In the examples throughout this book, I usually
  10.425 +      use short options instead of long.  This simply reflects my own
  10.426 +      preference, so don't read anything significant into it.</para>
  10.427 +
  10.428 +    <para id="x_37">Most commands that print output of some kind will print more
  10.429 +      output when passed a <option role="hg-opt-global">-v</option>
  10.430 +      (or <option role="hg-opt-global">--verbose</option>) option, and
  10.431 +      less when passed <option role="hg-opt-global">-q</option> (or
  10.432 +      <option role="hg-opt-global">--quiet</option>).</para>
  10.433 +
  10.434 +    <note>
  10.435 +      <title>Option naming consistency</title>
  10.436 +
  10.437 +      <para id="x_680">Almost always, Mercurial commands use consistent option
  10.438 +	names to refer to the same concepts.  For instance, if a
  10.439 +	command deals with changesets, you'll always identify them
  10.440 +	with <option role="hg-opt-log">--rev</option> or <option
  10.441 +	  role="hg-opt-log">-r</option>.  This consistent use of
  10.442 +	option names makes it easier to remember what options a
  10.443 +	particular command takes.</para>
  10.444 +    </note>
  10.445 +
  10.446 +  </sect1>
  10.447 +  <sect1>
  10.448 +    <title>Making and reviewing changes</title>
  10.449 +
  10.450 +    <para id="x_38">Now that we have a grasp of viewing history in Mercurial,
  10.451 +      let's take a look at making some changes and examining
  10.452 +      them.</para>
  10.453 +
  10.454 +    <para id="x_39">The first thing we'll do is isolate our experiment in a
  10.455 +      repository of its own.  We use the <command role="hg-cmd">hg
  10.456 +	clone</command> command, but we don't need to clone a copy of
  10.457 +      the remote repository.  Since we already have a copy of it
  10.458 +      locally, we can just clone that instead.  This is much faster
  10.459 +      than cloning over the network, and cloning a local repository
  10.460 +      uses less disk space in most cases, too<footnote>
  10.461 +	<para id="x_681">The saving of space arises when source and destination
  10.462 +	  repositories are on the same filesystem, in which case
  10.463 +	  Mercurial will use hardlinks to do copy-on-write sharing of
  10.464 +	  its internal metadata.  If that explanation meant nothing to
  10.465 +	  you, don't worry: everything happens transparently and
  10.466 +	  automatically, and you don't need to understand it.</para>
  10.467 +	</footnote>.</para>
  10.468 +
  10.469 +    &interaction.tour.reclone;
  10.470 +
  10.471 +    <para id="x_3a">As an aside, it's often good practice to keep a
  10.472 +      <quote>pristine</quote> copy of a remote repository around,
  10.473 +      which you can then make temporary clones of to create sandboxes
  10.474 +      for each task you want to work on.  This lets you work on
  10.475 +      multiple tasks in parallel, each isolated from the others until
  10.476 +      it's complete and you're ready to integrate it back.  Because
  10.477 +      local clones are so cheap, there's almost no overhead to cloning
  10.478 +      and destroying repositories whenever you want.</para>
  10.479 +
  10.480 +    <para id="x_3b">In our <filename class="directory">my-hello</filename>
  10.481 +      repository, we have a file <filename>hello.c</filename> that
  10.482 +      contains the classic <quote>hello, world</quote> program.</para>
  10.483 +
  10.484 +    &interaction.tour.cat1;
  10.485 +
  10.486 +    <para id="x_682">Let's edit this file so that it prints a second line of
  10.487 +      output.</para>
  10.488 +
  10.489 +    &interaction.tour.cat2;
  10.490 +
  10.491 +    <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command>
  10.492 +      command will tell us what Mercurial knows about the files in the
  10.493 +      repository.</para>
  10.494 +
  10.495 +    &interaction.tour.status;
  10.496 +
  10.497 +    <para id="x_3d">The <command role="hg-cmd">hg status</command> command
  10.498 +      prints no output for some files, but a line starting with
  10.499 +      <quote><literal>M</literal></quote> for
  10.500 +      <filename>hello.c</filename>.  Unless you tell it to, <command
  10.501 +	role="hg-cmd">hg status</command> will not print any output
  10.502 +      for files that have not been modified.</para>
  10.503 +
  10.504 +    <para id="x_3e">The <quote><literal>M</literal></quote> indicates that
  10.505 +      Mercurial has noticed that we modified
  10.506 +      <filename>hello.c</filename>.  We didn't need to
  10.507 +      <emphasis>inform</emphasis> Mercurial that we were going to
  10.508 +      modify the file before we started, or that we had modified the
  10.509 +      file after we were done; it was able to figure this out
  10.510 +      itself.</para>
  10.511 +
  10.512 +    <para id="x_3f">It's somewhat helpful to know that we've modified
  10.513 +      <filename>hello.c</filename>, but we might prefer to know
  10.514 +      exactly <emphasis>what</emphasis> changes we've made to it.  To
  10.515 +      do this, we use the <command role="hg-cmd">hg diff</command>
  10.516 +      command.</para>
  10.517 +
  10.518 +    &interaction.tour.diff;
  10.519 +
  10.520 +    <tip>
  10.521 +      <title>Understanding patches</title>
  10.522 +
  10.523 +      <para id="x_683">Remember to take a look at <xref
  10.524 +	  linkend="sec:mq:patch"/> if you don't know how to read
  10.525 +	output above.</para>
  10.526 +    </tip>
  10.527 +  </sect1>
  10.528 +  <sect1>
  10.529 +    <title>Recording changes in a new changeset</title>
  10.530 +
  10.531 +    <para id="x_40">We can modify files, build and test our changes, and use
  10.532 +      <command role="hg-cmd">hg status</command> and <command
  10.533 +	role="hg-cmd">hg diff</command> to review our changes, until
  10.534 +      we're satisfied with what we've done and arrive at a natural
  10.535 +      stopping point where we want to record our work in a new
  10.536 +      changeset.</para>
  10.537 +
  10.538 +    <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets
  10.539 +      us create a new changeset; we'll usually refer to this as
  10.540 +      <quote>making a commit</quote> or
  10.541 +      <quote>committing</quote>.</para>
  10.542 +
  10.543 +    <sect2>
  10.544 +      <title>Setting up a username</title>
  10.545 +
  10.546 +      <para id="x_42">When you try to run <command role="hg-cmd">hg
  10.547 +	  commit</command> for the first time, it is not guaranteed to
  10.548 +	succeed.  Mercurial records your name and address with each
  10.549 +	change that you commit, so that you and others will later be
  10.550 +	able to tell who made each change.  Mercurial tries to
  10.551 +	automatically figure out a sensible username to commit the
  10.552 +	change with.  It will attempt each of the following methods,
  10.553 +	in order:</para>
  10.554 +      <orderedlist>
  10.555 +	<listitem><para id="x_43">If you specify a <option
  10.556 +	      role="hg-opt-commit">-u</option> option to the <command
  10.557 +	      role="hg-cmd">hg commit</command> command on the command
  10.558 +	    line, followed by a username, this is always given the
  10.559 +	    highest precedence.</para></listitem>
  10.560 +	<listitem><para id="x_44">If you have set the <envar>HGUSER</envar>
  10.561 +	    environment variable, this is checked
  10.562 +	    next.</para></listitem>
  10.563 +	<listitem><para id="x_45">If you create a file in your home
  10.564 +	    directory called <filename
  10.565 +	      role="special">.hgrc</filename>, with a <envar
  10.566 +	      role="rc-item-ui">username</envar> entry, that will be
  10.567 +	    used next.  To see what the contents of this file should
  10.568 +	    look like, refer to <xref
  10.569 +	      linkend="sec:tour-basic:username"/>
  10.570 +	    below.</para></listitem>
  10.571 +	<listitem><para id="x_46">If you have set the <envar>EMAIL</envar>
  10.572 +	    environment variable, this will be used
  10.573 +	    next.</para></listitem>
  10.574 +	<listitem><para id="x_47">Mercurial will query your system to find out
  10.575 +	    your local user name and host name, and construct a
  10.576 +	    username from these components. Since this often results
  10.577 +	    in a username that is not very useful, it will print a
  10.578 +	    warning if it has to do
  10.579 +	    this.</para></listitem>
  10.580 +      </orderedlist>
  10.581 +      <para id="x_48">If all of these mechanisms fail, Mercurial will
  10.582 +	  fail, printing an error message.  In this case, it will not
  10.583 +	  let you commit until you set up a
  10.584 +	  username.</para>
  10.585 +      <para id="x_49">You should think of the <envar>HGUSER</envar> environment
  10.586 +	variable and the <option role="hg-opt-commit">-u</option>
  10.587 +	option to the <command role="hg-cmd">hg commit</command>
  10.588 +	command as ways to <emphasis>override</emphasis> Mercurial's
  10.589 +	default selection of username.  For normal use, the simplest
  10.590 +	and most robust way to set a username for yourself is by
  10.591 +	creating a <filename role="special">.hgrc</filename> file; see
  10.592 +	below for details.</para>
  10.593 +      <sect3 id="sec:tour-basic:username">
  10.594 +	<title>Creating a Mercurial configuration file</title>
  10.595 +
  10.596 +	<para id="x_4a">To set a user name, use your favorite editor
  10.597 +	  to create a file called <filename
  10.598 +	    role="special">.hgrc</filename> in your home directory.
  10.599 +	  Mercurial will use this file to look up your personalised
  10.600 +	  configuration settings.  The initial contents of your
  10.601 +	  <filename role="special">.hgrc</filename> should look like
  10.602 +	  this.</para>
  10.603 +
  10.604 +	<tip>
  10.605 +	  <title><quote>Home directory</quote> on Windows</title>
  10.606 +
  10.607 +	  <para id="x_716">When we refer to your home directory, on an English
  10.608 +	    language installation of Windows this will usually be a
  10.609 +	    folder named after your user name in
  10.610 +	    <filename>C:\Documents and Settings</filename>.  You can
  10.611 +	    find out the exact name of your home directory by opening
  10.612 +	    a command prompt window and running the following
  10.613 +	    command.</para>
  10.614 +
  10.615 +	  <screen><prompt>C:\></prompt> <userinput>echo %UserProfile%</userinput></screen>
  10.616 +	</tip>
  10.617 +
  10.618 +	<programlisting># This is a Mercurial configuration file.
  10.619 +[ui]
  10.620 +username = Firstname Lastname &lt;email.address@example.net&gt;</programlisting>
  10.621 +
  10.622 +	<para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a
  10.623 +	  <emphasis>section</emphasis> of the config file, so you can
  10.624 +	  read the <quote><literal>username = ...</literal></quote>
  10.625 +	  line as meaning <quote>set the value of the
  10.626 +	    <literal>username</literal> item in the
  10.627 +	    <literal>ui</literal> section</quote>. A section continues
  10.628 +	  until a new section begins, or the end of the file.
  10.629 +	  Mercurial ignores empty lines and treats any text from
  10.630 +	  <quote><literal>#</literal></quote> to the end of a line as
  10.631 +	  a comment.</para>
  10.632 +      </sect3>
  10.633 +
  10.634 +      <sect3>
  10.635 +	<title>Choosing a user name</title>
  10.636 +
  10.637 +	<para id="x_4c">You can use any text you like as the value of
  10.638 +	  the <literal>username</literal> config item, since this
  10.639 +	  information is for reading by other people, but will not be
  10.640 +	  interpreted by Mercurial.  The convention that most people
  10.641 +	  follow is to use their name and email address, as in the
  10.642 +	  example above.</para>
  10.643 +	<note>
  10.644 +	  <para id="x_4d">Mercurial's built-in web server obfuscates
  10.645 +	    email addresses, to make it more difficult for the email
  10.646 +	    harvesting tools that spammers use. This reduces the
  10.647 +	    likelihood that you'll start receiving more junk email if
  10.648 +	    you publish a Mercurial repository on the
  10.649 +	    web.</para></note>
  10.650 +      </sect3>
  10.651 +    </sect2>
  10.652 +    <sect2>
  10.653 +      <title>Writing a commit message</title>
  10.654 +
  10.655 +      <para id="x_4e">When we commit a change, Mercurial drops us into
  10.656 +	a text editor, to enter a message that will describe the
  10.657 +	modifications we've made in this changeset.  This is called
  10.658 +	the <emphasis>commit message</emphasis>.  It will be a record
  10.659 +	for readers of what we did and why, and it will be printed by
  10.660 +	<command role="hg-cmd">hg log</command> after we've finished
  10.661 +	committing.</para>
  10.662 +
  10.663 +       &interaction.tour.commit;
  10.664 +
  10.665 +      <para id="x_4f">The editor that the <command role="hg-cmd">hg
  10.666 +	  commit</command> command drops us into will contain an empty
  10.667 +	line or two, followed by a number of lines starting with
  10.668 +	<quote><literal>HG:</literal></quote>.</para>
  10.669 +
  10.670 +    <programlisting>
  10.671 +This is where I type my commit comment.
  10.672 +
  10.673 +HG: Enter commit message.  Lines beginning with 'HG:' are removed.
  10.674 +HG: --
  10.675 +HG: user: Bryan O'Sullivan &lt;bos@serpentine.com&gt;
  10.676 +HG: branch 'default'
  10.677 +HG: changed hello.c</programlisting>
  10.678 +
  10.679 +      <para id="x_50">Mercurial ignores the lines that start with
  10.680 +	<quote><literal>HG:</literal></quote>; it uses them only to
  10.681 +	tell us which files it's recording changes to.  Modifying or
  10.682 +	deleting these lines has no effect.</para>
  10.683 +    </sect2>
  10.684 +    <sect2>
  10.685 +      <title>Writing a good commit message</title>
  10.686 +
  10.687 +      <para id="x_51">Since <command role="hg-cmd">hg log</command>
  10.688 +	only prints the first line of a commit message by default,
  10.689 +	it's best to write a commit message whose first line stands
  10.690 +	alone.  Here's a real example of a commit message that
  10.691 +	<emphasis>doesn't</emphasis> follow this guideline, and hence
  10.692 +	has a summary that is not readable.</para>
  10.693 +
  10.694 +      <programlisting>
  10.695 +changeset:   73:584af0e231be
  10.696 +user:        Censored Person &lt;censored.person@example.org&gt;
  10.697 +date:        Tue Sep 26 21:37:07 2006 -0700
  10.698 +summary:     include buildmeister/commondefs. Add exports.</programlisting>
  10.699 +
  10.700 +      <para id="x_52">As far as the remainder of the contents of the
  10.701 +	commit message are concerned, there are no hard-and-fast
  10.702 +	rules.  Mercurial itself doesn't interpret or care about the
  10.703 +	contents of the commit message, though your project may have
  10.704 +	policies that dictate a certain kind of formatting.</para>
  10.705 +      <para id="x_53">My personal preference is for short, but
  10.706 +	informative, commit messages that tell me something that I
  10.707 +	can't figure out with a quick glance at the output of <command
  10.708 +	  role="hg-cmd">hg log --patch</command>.</para>
  10.709 +      <para id="x_55">If we run the <command role="hg-cmd">hg
  10.710 +	  commit</command> command without any arguments, it records
  10.711 +	all of the changes we've made, as reported by <command
  10.712 +	  role="hg-cmd">hg status</command> and <command
  10.713 +	  role="hg-cmd">hg diff</command>.</para>
  10.714 +
  10.715 +      <note>
  10.716 +	<title>A surprise for Subversion users</title>
  10.717 +
  10.718 +	<para id="x_717">Like other Mercurial commands, if we don't supply
  10.719 +	  explicit names to commit to the <command role="hg-cmd">hg
  10.720 +	    commit</command>, it will operate across a repository's
  10.721 +	  entire working directory.  Be wary of this if you're coming
  10.722 +	  from the Subversion or CVS world, since you might expect it
  10.723 +	  to operate only on the current directory that you happen to
  10.724 +	  be visiting and its subdirectories.</para>
  10.725 +      </note>
  10.726 +    </sect2>
  10.727 +
  10.728 +    <sect2>
  10.729 +      <title>Aborting a commit</title>
  10.730 +
  10.731 +      <para id="x_54">If you decide that you don't want to commit
  10.732 +	while in the middle of editing a commit message, simply exit
  10.733 +	from your editor without saving the file that it's editing.
  10.734 +	This will cause nothing to happen to either the repository or
  10.735 +	the working directory.</para>
  10.736 +    </sect2>
  10.737 +
  10.738 +    <sect2>
  10.739 +      <title>Admiring our new handiwork</title>
  10.740 +
  10.741 +      <para id="x_56">Once we've finished the commit, we can use the
  10.742 +	<command role="hg-cmd">hg tip</command> command to display the
  10.743 +	changeset we just created.  This command produces output that
  10.744 +	is identical to <command role="hg-cmd">hg log</command>, but
  10.745 +	it only displays the newest revision in the repository.</para>
  10.746 +
  10.747 +      &interaction.tour.tip;
  10.748 +
  10.749 +      <para id="x_57">We refer to the newest revision in the
  10.750 +	repository as the <emphasis>tip revision</emphasis>, or simply
  10.751 +	the <emphasis>tip</emphasis>.</para>
  10.752 +
  10.753 +      <para id="x_684">By the way, the <command role="hg-cmd">hg tip</command>
  10.754 +	command accepts many of the same options as <command
  10.755 +	  role="hg-cmd">hg log</command>, so <option
  10.756 +	  role="hg-opt-global">-v</option> above indicates <quote>be
  10.757 +	  verbose</quote>, <option role="hg-opt-tip">-p</option>
  10.758 +	specifies <quote>print a patch</quote>.  The use of <option
  10.759 +	  role="hg-opt-tip">-p</option> to print patches is another
  10.760 +	example of the consistent naming we mentioned earlier.</para>
  10.761 +    </sect2>
  10.762 +  </sect1>
  10.763 +
  10.764 +  <sect1>
  10.765 +    <title>Sharing changes</title>
  10.766 +
  10.767 +    <para id="x_58">We mentioned earlier that repositories in
  10.768 +      Mercurial are self-contained.  This means that the changeset we
  10.769 +      just created exists only in our <filename
  10.770 +	class="directory">my-hello</filename> repository.  Let's look
  10.771 +      at a few ways that we can propagate this change into other
  10.772 +      repositories.</para>
  10.773 +
  10.774 +    <sect2 id="sec:tour:pull">
  10.775 +      <title>Pulling changes from another repository</title>
  10.776 +
  10.777 +      <para id="x_59">To get started, let's clone our original
  10.778 +	<filename class="directory">hello</filename> repository, which
  10.779 +	does not contain the change we just committed.  We'll call our
  10.780 +	temporary repository <filename
  10.781 +	  class="directory">hello-pull</filename>.</para>
  10.782 +
  10.783 +      &interaction.tour.clone-pull;
  10.784 +
  10.785 +      <para id="x_5a">We'll use the <command role="hg-cmd">hg
  10.786 +	  pull</command> command to bring changes from <filename
  10.787 +	  class="directory">my-hello</filename> into <filename
  10.788 +	  class="directory">hello-pull</filename>.  However, blindly
  10.789 +	pulling unknown changes into a repository is a somewhat scary
  10.790 +	prospect.  Mercurial provides the <command role="hg-cmd">hg
  10.791 +	  incoming</command> command to tell us what changes the
  10.792 +	<command role="hg-cmd">hg pull</command> command
  10.793 +	<emphasis>would</emphasis> pull into the repository, without
  10.794 +	actually pulling the changes in.</para>
  10.795 +
  10.796 +      &interaction.tour.incoming;
  10.797 +
  10.798 +      <para id="x_5c">Bringing changes into a repository is a simple
  10.799 +	matter of running the <command role="hg-cmd">hg pull</command>
  10.800 +	command, and optionally telling it which repository to pull from.</para>
  10.801 +
  10.802 +      &interaction.tour.pull;
  10.803 +
  10.804 +      <para id="x_5d">As you can see from the before-and-after output
  10.805 +	of <command role="hg-cmd">hg tip</command>, we have
  10.806 +	successfully pulled changes into our repository.  However,
  10.807 +	Mercurial separates pulling changes in from updating the
  10.808 +	working directory. There remains one step before we will see
  10.809 +	the changes that we just pulled appear in the working
  10.810 +	directory.</para>
  10.811 +
  10.812 +      <tip>
  10.813 +	<title>Pulling specific changes</title>
  10.814 +
  10.815 +	<para id="x_5b">It is possible that due to the delay between
  10.816 +	  running <command role="hg-cmd">hg incoming</command> and
  10.817 +	  <command role="hg-cmd">hg pull</command>, you may not see
  10.818 +	  all changesets that will be brought from the other
  10.819 +	  repository. Suppose you're pulling changes from a repository
  10.820 +	  on the network somewhere. While you are looking at the
  10.821 +	  <command role="hg-cmd">hg incoming</command> output, and
  10.822 +	  before you pull those changes, someone might have committed
  10.823 +	  something in the remote repository. This means that it's
  10.824 +	  possible to pull more changes than you saw when using
  10.825 +	  <command role="hg-cmd">hg incoming</command>.</para>
  10.826 +
  10.827 +	<para id="x_718">If you only want to pull precisely the changes that were
  10.828 +	  listed by <command role="hg-cmd">hg incoming</command>, or
  10.829 +	  you have some other reason to pull a subset of changes,
  10.830 +	  simply identify the change that you want to pull by its
  10.831 +	  changeset ID, e.g. <command>hg pull
  10.832 +	    -r7e95bb</command>.</para>
  10.833 +      </tip>
  10.834 +    </sect2>
  10.835 +
  10.836 +    <sect2>
  10.837 +      <title>Updating the working directory</title>
  10.838 +
  10.839 +      <para id="x_5e">We have so far glossed over the relationship
  10.840 +	between a repository and its working directory.  The <command
  10.841 +	  role="hg-cmd">hg pull</command> command that we ran in
  10.842 +	<xref linkend="sec:tour:pull"/> brought changes into the
  10.843 +	repository, but if we check, there's no sign of those changes
  10.844 +	in the working directory.  This is because <command
  10.845 +	  role="hg-cmd">hg pull</command> does not (by default) touch
  10.846 +	the working directory.  Instead, we use the <command
  10.847 +	  role="hg-cmd">hg update</command> command to do this.</para>
  10.848 +
  10.849 +      &interaction.tour.update;
  10.850 +
  10.851 +      <para id="x_5f">It might seem a bit strange that <command
  10.852 +	  role="hg-cmd">hg pull</command> doesn't update the working
  10.853 +	directory automatically.  There's actually a good reason for
  10.854 +	this: you can use <command role="hg-cmd">hg update</command>
  10.855 +	to update the working directory to the state it was in at
  10.856 +	<emphasis>any revision</emphasis> in the history of the
  10.857 +	repository.  If you had the working directory updated to an
  10.858 +	old revision&emdash;to hunt down the origin of a bug,
  10.859 +	say&emdash;and ran a <command role="hg-cmd">hg pull</command>
  10.860 +	which automatically updated the working directory to a new
  10.861 +	revision, you might not be terribly happy.</para>
  10.862 +
  10.863 +      <para id="x_60">Since pull-then-update is such a common sequence
  10.864 +	of operations, Mercurial lets you combine the two by passing
  10.865 +	the <option role="hg-opt-pull">-u</option> option to <command
  10.866 +	  role="hg-cmd">hg pull</command>.</para>
  10.867 +
  10.868 +      <para id="x_61">If you look back at the output of <command
  10.869 +	  role="hg-cmd">hg pull</command> in <xref
  10.870 +	    linkend="sec:tour:pull"/> when we ran it without <option
  10.871 +	  role="hg-opt-pull">-u</option>, you can see that it printed
  10.872 +	a helpful reminder that we'd have to take an explicit step to
  10.873 +	update the working directory.</para>
  10.874 +
  10.875 +      <para id="x_62">To find out what revision the working directory
  10.876 +	is at, use the <command role="hg-cmd">hg parents</command>
  10.877 +	command.</para>
  10.878 +
  10.879 +      &interaction.tour.parents;
  10.880 +
  10.881 +      <para id="x_63">If you look back at <xref
  10.882 +	  linkend="fig:tour-basic:history"/>, you'll see arrows
  10.883 +	connecting each changeset.  The node that the arrow leads
  10.884 +	<emphasis>from</emphasis> in each case is a parent, and the
  10.885 +	node that the arrow leads <emphasis>to</emphasis> is its
  10.886 +	child.  The working directory has a parent in just the same
  10.887 +	way; this is the changeset that the working directory
  10.888 +	currently contains.</para>
  10.889 +
  10.890 +      <para id="x_64">To update the working directory to a particular
  10.891 +	revision, give a revision number or changeset ID to the
  10.892 +	<command role="hg-cmd">hg update</command> command.</para>
  10.893 +
  10.894 +      &interaction.tour.older;
  10.895 +
  10.896 +      <para id="x_65">If you omit an explicit revision, <command
  10.897 +	  role="hg-cmd">hg update</command> will update to the tip
  10.898 +	revision, as shown by the second call to <command
  10.899 +	  role="hg-cmd">hg update</command> in the example
  10.900 +	above.</para>
  10.901 +    </sect2>
  10.902 +
  10.903 +    <sect2>
  10.904 +      <title>Pushing changes to another repository</title>
  10.905 +
  10.906 +      <para id="x_66">Mercurial lets us push changes to another
  10.907 +	repository, from the repository we're currently visiting. As
  10.908 +	with the example of <command role="hg-cmd">hg pull</command>
  10.909 +	above, we'll create a temporary repository to push our changes
  10.910 +	into.</para>
  10.911 +
  10.912 +      &interaction.tour.clone-push;
  10.913 +
  10.914 +      <para id="x_67">The <command role="hg-cmd">hg outgoing</command>
  10.915 +	command tells us what changes would be pushed into another
  10.916 +	repository.</para>
  10.917 +
  10.918 +      &interaction.tour.outgoing;
  10.919 +
  10.920 +      <para id="x_68">And the <command role="hg-cmd">hg push</command>
  10.921 +	command does the actual push.</para>
  10.922 +
  10.923 +      &interaction.tour.push;
  10.924 +
  10.925 +      <para id="x_69">As with <command role="hg-cmd">hg
  10.926 +	  pull</command>, the <command role="hg-cmd">hg push</command>
  10.927 +	command does not update the working directory in the
  10.928 +	repository that it's pushing changes into. Unlike <command
  10.929 +	  role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg
  10.930 +	  push</command> does not provide a <literal>-u</literal>
  10.931 +	option that updates the other repository's working directory.
  10.932 +	This asymmetry is deliberate: the repository we're pushing to
  10.933 +	might be on a remote server and shared between several people.
  10.934 +	If we were to update its working directory while someone was
  10.935 +	working in it, their work would be disrupted.</para>
  10.936 +
  10.937 +      <para id="x_6a">What happens if we try to pull or push changes
  10.938 +	  and the receiving repository already has those changes?
  10.939 +	  Nothing too exciting.</para>
  10.940 +
  10.941 +      &interaction.tour.push.nothing;
  10.942 +    </sect2>
  10.943 +
  10.944 +    <sect2>
  10.945 +      <title>Default locations</title>
  10.946 +
  10.947 +      <para id="x_719">When we clone a repository, Mercurial records the location
  10.948 +	of the repository we cloned in the
  10.949 +	<filename>.hg/hgrc</filename> file of the new repository.  If
  10.950 +	we don't supply a location to <command>hg pull</command> from
  10.951 +	or <command>hg push</command> to, those commands will use this
  10.952 +	location as a default.  The <command>hg incoming</command>
  10.953 +	and <command>hg outgoing</command> commands do so too.</para>
  10.954 +
  10.955 +      <para id="x_71a">If you open a repository's <filename>.hg/hgrc</filename>
  10.956 +	file in a text editor, you will see contents like the
  10.957 +	following.</para>
  10.958 +
  10.959 +      <programlisting>[paths]
  10.960 +default = http://www.selenic.com/repo/hg</programlisting>
  10.961 +
  10.962 +      <para id="x_71b">It is possible&emdash;and often useful&emdash;to have the
  10.963 +	default location for <command>hg push</command> and
  10.964 +	<command>hg outgoing</command> be different from those for
  10.965 +	<command>hg pull</command> and <command>hg incoming</command>.
  10.966 +	We can do this by adding a <literal>default-push</literal>
  10.967 +	entry to the <literal>[paths]</literal> section of the
  10.968 +	<filename>.hg/hgrc</filename> file, as follows.</para>
  10.969 +
  10.970 +      <programlisting>[paths]
  10.971 +default = http://www.selenic.com/repo/hg
  10.972 +default-push = http://hg.example.com/hg</programlisting>
  10.973 +    </sect2>
  10.974 +
  10.975 +    <sect2>
  10.976 +      <title>Sharing changes over a network</title>
  10.977 +
  10.978 +      <para id="x_6b">The commands we have covered in the previous few
  10.979 +	  sections are not limited to working with local repositories.
  10.980 +	  Each works in exactly the same fashion over a network
  10.981 +	  connection; simply pass in a URL instead of a local
  10.982 +	  path.</para>
  10.983 +	
  10.984 +      &interaction.tour.outgoing.net;
  10.985 +
  10.986 +      <para id="x_6c">In this example, we can see what changes we
  10.987 +	could push to the remote repository, but the repository is
  10.988 +	understandably not set up to let anonymous users push to
  10.989 +	it.</para>
  10.990 +
  10.991 +      &interaction.tour.push.net;
  10.992 +    </sect2>
  10.993 +  </sect1>
  10.994 +
  10.995 +  <sect1>
  10.996 +    <title>Starting a new project</title>
  10.997 +
  10.998 +    <para id="x_71c">It is just as easy to begin a new project as to work on one
  10.999 +      that already exists.  The <command>hg init</command> command
 10.1000 +      creates a new, empty Mercurial repository.</para>
 10.1001 +
 10.1002 +    &interaction.ch01-new.init;
 10.1003 +
 10.1004 +    <para id="x_71d">This simply creates a repository named
 10.1005 +      <filename>myproject</filename> in the current directory.</para>
 10.1006 +
 10.1007 +    &interaction.ch01-new.ls;
 10.1008 +
 10.1009 +    <para id="x_71e">We can tell that <filename>myproject</filename> is a
 10.1010 +      Mercurial repository, because it contains a
 10.1011 +      <filename>.hg</filename> directory.</para>
 10.1012 +
 10.1013 +    &interaction.ch01-new.ls2;
 10.1014 +
 10.1015 +    <para id="x_71f">If we want to add some pre-existing files to the repository,
 10.1016 +      we copy them into place, and tell Mercurial to start tracking
 10.1017 +      them using the <command>hg add</command> command.</para>
 10.1018 +
 10.1019 +    &interaction.ch01-new.add;
 10.1020 +
 10.1021 +    <para id="x_720">Once we are satisfied that our project looks right, we
 10.1022 +      commit our changes.</para>
 10.1023 +
 10.1024 +    &interaction.ch01-new.commit;
 10.1025 +
 10.1026 +    <para id="x_721">It takes just a few moments to start using Mercurial on a
 10.1027 +      new project, which is part of its appeal. Revision control is
 10.1028 +      now so easy to work with, we can use it on the smallest of
 10.1029 +      projects that we might not have considered with a more
 10.1030 +      complicated tool.</para>
 10.1031 +  </sect1>
 10.1032 +</chapter>
 10.1033 +
 10.1034 +<!--
 10.1035 +local variables: 
 10.1036 +sgml-parent-document: ("00book.xml" "book" "chapter")
 10.1037 +end:
 10.1038 +-->