Commits

Bryan O'Sullivan  committed 28b5a5b

Fold preface and intro into one

  • Participants
  • Parent commits 5bfa0df

Comments (0)

Files changed (29)

File en/00book.xml

 
 <!-- Chapters. -->
 
-<!ENTITY ch01     SYSTEM "ch01-intro.xml">
-<!ENTITY ch02     SYSTEM "ch02-tour-basic.xml">
-<!ENTITY ch03     SYSTEM "ch03-tour-merge.xml">
-<!ENTITY ch04     SYSTEM "ch04-concepts.xml">
-<!ENTITY ch05     SYSTEM "ch05-daily.xml">
-<!ENTITY ch06     SYSTEM "ch06-collab.xml">
-<!ENTITY ch07     SYSTEM "ch07-filenames.xml">
-<!ENTITY ch08     SYSTEM "ch08-branch.xml">
-<!ENTITY ch09     SYSTEM "ch09-undo.xml">
-<!ENTITY ch10     SYSTEM "ch10-hook.xml">
-<!ENTITY ch11     SYSTEM "ch11-template.xml">
-<!ENTITY ch12     SYSTEM "ch12-mq.xml">
-<!ENTITY ch13     SYSTEM "ch13-mq-collab.xml">
-<!ENTITY ch14     SYSTEM "ch14-hgext.xml">
+<!ENTITY ch00     SYSTEM "ch00-preface.xml">
+<!ENTITY ch01     SYSTEM "ch01-tour-basic.xml">
+<!ENTITY ch02     SYSTEM "ch02-tour-merge.xml">
+<!ENTITY ch03     SYSTEM "ch03-concepts.xml">
+<!ENTITY ch04     SYSTEM "ch04-daily.xml">
+<!ENTITY ch05     SYSTEM "ch05-collab.xml">
+<!ENTITY ch06     SYSTEM "ch06-filenames.xml">
+<!ENTITY ch07     SYSTEM "ch07-branch.xml">
+<!ENTITY ch08     SYSTEM "ch08-undo.xml">
+<!ENTITY ch09     SYSTEM "ch09-hook.xml">
+<!ENTITY ch10     SYSTEM "ch10-template.xml">
+<!ENTITY ch11     SYSTEM "ch11-mq.xml">
+<!ENTITY ch12     SYSTEM "ch12-mq-collab.xml">
+<!ENTITY ch13     SYSTEM "ch13-hgext.xml">
 <!ENTITY appA     SYSTEM "appA-cmdref.xml">
 <!ENTITY appB     SYSTEM "appB-mq-ref.xml">
 <!ENTITY appC     SYSTEM "appC-srcinstall.xml">
   &ch11;
   &ch12;
   &ch13;
-  &ch14;
   <!-- &appA; -->
   &appB;
   &appC;

File en/ch00-preface.xml

 <preface id="chap:preface">
   <title>Preface</title>
 
-  <para>Distributed revision control is a relatively new territory,
-    and has thus far grown due to people's willingness to strike out
-    into ill-charted territory.</para>
+  <sect1>
+    <title>Why revision control? Why Mercurial?</title>
 
-  <para>I am writing a book about distributed revision control because
-    I believe that it is an important subject that deserves a field
-    guide. I chose to write about Mercurial because it is the easiest
-    tool to learn the terrain with, and yet it scales to the demands
-    of real, challenging environments where many other revision
-    control tools fail.</para>
+    <para>Revision control is the process of managing multiple
+      versions of a piece of information.  In its simplest form, this
+      is something that many people do by hand: every time you modify
+      a file, save it under a new name that contains a number, each
+      one higher than the number of the preceding version.</para>
+
+    <para>Manually managing multiple versions of even a single file is
+      an error-prone task, though, so software tools to help automate
+      this process have long been available.  The earliest automated
+      revision control tools were intended to help a single user to
+      manage revisions of a single file.  Over the past few decades,
+      the scope of revision control tools has expanded greatly; they
+      now manage multiple files, and help multiple people to work
+      together.  The best modern revision control tools have no
+      problem coping with thousands of people working together on
+      projects that consist of hundreds of thousands of files.</para>
+
+    <para>The arrival of distributed revision control is relatively
+      recent, and so far this new field has grown due to people's
+      willingness to explore ill-charted territory.</para>
+
+    <para>I am writing a book about distributed revision control
+      because I believe that it is an important subject that deserves
+      a field guide. I chose to write about Mercurial because it is
+      the easiest tool to learn the terrain with, and yet it scales to
+      the demands of real, challenging environments where many other
+      revision control tools buckle.</para>
+
+    <sect2>
+      <title>Why use revision control?</title>
+
+      <para>There are a number of reasons why you or your team might
+	want to use an automated revision control tool for a
+	project.</para>
+
+      <itemizedlist>
+	<listitem><para>It will track the history and evolution of
+	    your project, so you don't have to.  For every change,
+	    you'll have a log of <emphasis>who</emphasis> made it;
+	    <emphasis>why</emphasis> they made it;
+	    <emphasis>when</emphasis> they made it; and
+	    <emphasis>what</emphasis> the change
+	    was.</para></listitem>
+	<listitem><para>When you're working with other people,
+	    revision control software makes it easier for you to
+	    collaborate.  For example, when people more or less
+	    simultaneously make potentially incompatible changes, the
+	    software will help you to identify and resolve those
+	    conflicts.</para></listitem>
+	<listitem><para>It can help you to recover from mistakes.  If
+	    you make a change that later turns out to be in error, you
+	    can revert to an earlier version of one or more files.  In
+	    fact, a <emphasis>really</emphasis> good revision control
+	    tool will even help you to efficiently figure out exactly
+	    when a problem was introduced (see section <xref
+	      linkend="sec:undo:bisect"/> for details).</para></listitem>
+	<listitem><para>It will help you to work simultaneously on,
+	    and manage the drift between, multiple versions of your
+	    project.</para></listitem>
+      </itemizedlist>
+
+      <para>Most of these reasons are equally valid---at least in
+	theory---whether you're working on a project by yourself, or
+	with a hundred other people.</para>
+
+      <para>A key question about the practicality of revision control
+	at these two different scales (<quote>lone hacker</quote> and
+	<quote>huge team</quote>) is how its
+	<emphasis>benefits</emphasis> compare to its
+	<emphasis>costs</emphasis>.  A revision control tool that's
+	difficult to understand or use is going to impose a high
+	cost.</para>
+
+      <para>A five-hundred-person project is likely to collapse under
+	its own weight almost immediately without a revision control
+	tool and process. In this case, the cost of using revision
+	control might hardly seem worth considering, since
+	<emphasis>without</emphasis> it, failure is almost
+	guaranteed.</para>
+
+      <para>On the other hand, a one-person <quote>quick hack</quote>
+	might seem like a poor place to use a revision control tool,
+	because surely the cost of using one must be close to the
+	overall cost of the project.  Right?</para>
+
+      <para>Mercurial uniquely supports <emphasis>both</emphasis> of
+	these scales of development.  You can learn the basics in just
+	a few minutes, and due to its low overhead, you can apply
+	revision control to the smallest of projects with ease.  Its
+	simplicity means you won't have a lot of abstruse concepts or
+	command sequences competing for mental space with whatever
+	you're <emphasis>really</emphasis> trying to do.  At the same
+	time, Mercurial's high performance and peer-to-peer nature let
+	you scale painlessly to handle large projects.</para>
+
+      <para>No revision control tool can rescue a poorly run project,
+	but a good choice of tools can make a huge difference to the
+	fluidity with which you can work on a project.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>The many names of revision control</title>
+
+      <para>Revision control is a diverse field, so much so that it is
+	referred to by many names and acronyms.  Here are a few of the
+	more common variations you'll encounter:</para>
+      <itemizedlist>
+	<listitem><para>Revision control (RCS)</para></listitem>
+	<listitem><para>Software configuration management (SCM), or
+	    configuration management</para></listitem>
+	<listitem><para>Source code management</para></listitem>
+	<listitem><para>Source code control, or source
+	    control</para></listitem>
+	<listitem><para>Version control
+	    (VCS)</para></listitem></itemizedlist>
+      <para>Some people claim that these terms actually have different
+	meanings, but in practice they overlap so much that there's no
+	agreed or even useful way to tease them apart.</para>
+
+    </sect2>
+  </sect1>
 
   <sect1>
     <title>This book is a work in progress</title>
 
     <para>I am releasing this book while I am still writing it, in the
-      hope that it will prove useful to others.  I also hope that
-      readers will contribute as they see fit.</para>
+      hope that it will prove useful to others.  I am writing under an
+      open license in the hope that you, my readers, will contribute
+      feedback and perhaps content of your own.</para>
 
   </sect1>
   <sect1>
       seeing is consistent and reproducible.</para>
 
   </sect1>
+
   <sect1>
-    <title>Colophon---this book is Free</title>
+    <title>Trends in the field</title>
+
+    <para>There has been an unmistakable trend in the development and
+      use of revision control tools over the past four decades, as
+      people have become familiar with the capabilities of their tools
+      and constrained by their limitations.</para>
+
+    <para>The first generation began by managing single files on
+      individual computers.  Although these tools represented a huge
+      advance over ad-hoc manual revision control, their locking model
+      and reliance on a single computer limited them to small,
+      tightly-knit teams.</para>
+
+    <para>The second generation loosened these constraints by moving
+      to network-centered architectures, and managing entire projects
+      at a time.  As projects grew larger, they ran into new problems.
+      With clients needing to talk to servers very frequently, server
+      scaling became an issue for large projects.  An unreliable
+      network connection could prevent remote users from being able to
+      talk to the server at all.  As open source projects started
+      making read-only access available anonymously to anyone, people
+      without commit privileges found that they could not use the
+      tools to interact with a project in a natural way, as they could
+      not record their changes.</para>
+
+    <para>The current generation of revision control tools is
+      peer-to-peer in nature.  All of these systems have dropped the
+      dependency on a single central server, and allow people to
+      distribute their revision control data to where it's actually
+      needed.  Collaboration over the Internet has moved from
+      constrained by technology to a matter of choice and consensus.
+      Modern tools can operate offline indefinitely and autonomously,
+      with a network connection only needed when syncing changes with
+      another repository.</para>
+
+  </sect1>
+  <sect1>
+    <title>A few of the advantages of distributed revision
+      control</title>
+
+    <para>Even though distributed revision control tools have for
+      several years been as robust and usable as their
+      previous-generation counterparts, people using older tools have
+      not yet necessarily woken up to their advantages.  There are a
+      number of ways in which distributed tools shine relative to
+      centralised ones.</para>
+
+    <para>For an individual developer, distributed tools are almost
+      always much faster than centralised tools.  This is for a simple
+      reason: a centralised tool needs to talk over the network for
+      many common operations, because most metadata is stored in a
+      single copy on the central server.  A distributed tool stores
+      all of its metadata locally.  All else being equal, talking over
+      the network adds overhead to a centralised tool.  Don't
+      underestimate the value of a snappy, responsive tool: you're
+      going to spend a lot of time interacting with your revision
+      control software.</para>
+
+    <para>Distributed tools are indifferent to the vagaries of your
+      server infrastructure, again because they replicate metadata to
+      so many locations.  If you use a centralised system and your
+      server catches fire, you'd better hope that your backup media
+      are reliable, and that your last backup was recent and actually
+      worked.  With a distributed tool, you have many backups
+      available on every contributor's computer.</para>
+
+    <para>The reliability of your network will affect distributed
+      tools far less than it will centralised tools.  You can't even
+      use a centralised tool without a network connection, except for
+      a few highly constrained commands.  With a distributed tool, if
+      your network connection goes down while you're working, you may
+      not even notice.  The only thing you won't be able to do is talk
+      to repositories on other computers, something that is relatively
+      rare compared with local operations.  If you have a far-flung
+      team of collaborators, this may be significant.</para>
+
+    <sect2>
+      <title>Advantages for open source projects</title>
+
+      <para>If you take a shine to an open source project and decide
+	that you would like to start hacking on it, and that project
+	uses a distributed revision control tool, you are at once a
+	peer with the people who consider themselves the
+	<quote>core</quote> of that project.  If they publish their
+	repositories, you can immediately copy their project history,
+	start making changes, and record your work, using the same
+	tools in the same ways as insiders.  By contrast, with a
+	centralised tool, you must use the software in a <quote>read
+	  only</quote> mode unless someone grants you permission to
+	commit changes to their central server.  Until then, you won't
+	be able to record changes, and your local modifications will
+	be at risk of corruption any time you try to update your
+	client's view of the repository.</para>
+
+      <sect3>
+	<title>The forking non-problem</title>
+
+	<para>It has been suggested that distributed revision control
+	  tools pose some sort of risk to open source projects because
+	  they make it easy to <quote>fork</quote> the development of
+	  a project.  A fork happens when there are differences in
+	  opinion or attitude between groups of developers that cause
+	  them to decide that they can't work together any longer.
+	  Each side takes a more or less complete copy of the
+	  project's source code, and goes off in its own
+	  direction.</para>
+
+	<para>Sometimes the camps in a fork decide to reconcile their
+	  differences. With a centralised revision control system, the
+	  <emphasis>technical</emphasis> process of reconciliation is
+	  painful, and has to be performed largely by hand.  You have
+	  to decide whose revision history is going to
+	  <quote>win</quote>, and graft the other team's changes into
+	  the tree somehow. This usually loses some or all of one
+	  side's revision history.</para>
+
+	<para>What distributed tools do with respect to forking is
+	  they make forking the <emphasis>only</emphasis> way to
+	  develop a project.  Every single change that you make is
+	  potentially a fork point.  The great strength of this
+	  approach is that a distributed revision control tool has to
+	  be really good at <emphasis>merging</emphasis> forks,
+	  because forks are absolutely fundamental: they happen all
+	  the time.</para>
+
+	<para>If every piece of work that everybody does, all the
+	  time, is framed in terms of forking and merging, then what
+	  the open source world refers to as a <quote>fork</quote>
+	  becomes <emphasis>purely</emphasis> a social issue.  If
+	  anything, distributed tools <emphasis>lower</emphasis> the
+	  likelihood of a fork:</para>
+	<itemizedlist>
+	  <listitem><para>They eliminate the social distinction that
+	      centralised tools impose: that between insiders (people
+	      with commit access) and outsiders (people
+	      without).</para></listitem>
+	  <listitem><para>They make it easier to reconcile after a
+	      social fork, because all that's involved from the
+	      perspective of the revision control software is just
+	      another merge.</para></listitem></itemizedlist>
+
+	<para>Some people resist distributed tools because they want
+	  to retain tight control over their projects, and they
+	  believe that centralised tools give them this control.
+	  However, if you're of this belief, and you publish your CVS
+	  or Subversion repositories publicly, there are plenty of
+	  tools available that can pull out your entire project's
+	  history (albeit slowly) and recreate it somewhere that you
+	  don't control.  So while your control in this case is
+	  illusory, you are forgoing the ability to fluidly
+	  collaborate with whatever people feel compelled to mirror
+	  and fork your history.</para>
+
+      </sect3>
+    </sect2>
+    <sect2>
+      <title>Advantages for commercial projects</title>
+
+      <para>Many commercial projects are undertaken by teams that are
+	scattered across the globe.  Contributors who are far from a
+	central server will see slower command execution and perhaps
+	less reliability.  Commercial revision control systems attempt
+	to ameliorate these problems with remote-site replication
+	add-ons that are typically expensive to buy and cantankerous
+	to administer.  A distributed system doesn't suffer from these
+	problems in the first place.  Better yet, you can easily set
+	up multiple authoritative servers, say one per site, so that
+	there's no redundant communication between repositories over
+	expensive long-haul network links.</para>
+
+      <para>Centralised revision control systems tend to have
+	relatively low scalability.  It's not unusual for an expensive
+	centralised system to fall over under the combined load of
+	just a few dozen concurrent users.  Once again, the typical
+	response tends to be an expensive and clunky replication
+	facility.  Since the load on a central server---if you have
+	one at all---is many times lower with a distributed tool
+	(because all of the data is replicated everywhere), a single
+	cheap server can handle the needs of a much larger team, and
+	replication to balance load becomes a simple matter of
+	scripting.</para>
+
+      <para>If you have an employee in the field, troubleshooting a
+	problem at a customer's site, they'll benefit from distributed
+	revision control. The tool will let them generate custom
+	builds, try different fixes in isolation from each other, and
+	search efficiently through history for the sources of bugs and
+	regressions in the customer's environment, all without needing
+	to connect to your company's network.</para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Why choose Mercurial?</title>
+
+    <para>Mercurial has a unique set of properties that make it a
+      particularly good choice as a revision control system.</para>
+    <itemizedlist>
+      <listitem><para>It is easy to learn and use.</para></listitem>
+      <listitem><para>It is lightweight.</para></listitem>
+      <listitem><para>It scales excellently.</para></listitem>
+      <listitem><para>It is easy to
+	  customise.</para></listitem></itemizedlist>
+
+    <para>If you are at all familiar with revision control systems,
+      you should be able to get up and running with Mercurial in less
+      than five minutes.  Even if not, it will take no more than a few
+      minutes longer.  Mercurial's command and feature sets are
+      generally uniform and consistent, so you can keep track of a few
+      general rules instead of a host of exceptions.</para>
+
+    <para>On a small project, you can start working with Mercurial in
+      moments. Creating new changes and branches; transferring changes
+      around (whether locally or over a network); and history and
+      status operations are all fast.  Mercurial attempts to stay
+      nimble and largely out of your way by combining low cognitive
+      overhead with blazingly fast operations.</para>
+
+    <para>The usefulness of Mercurial is not limited to small
+      projects: it is used by projects with hundreds to thousands of
+      contributors, each containing tens of thousands of files and
+      hundreds of megabytes of source code.</para>
+
+    <para>If the core functionality of Mercurial is not enough for
+      you, it's easy to build on.  Mercurial is well suited to
+      scripting tasks, and its clean internals and implementation in
+      Python make it easy to add features in the form of extensions.
+      There are a number of popular and useful extensions already
+      available, ranging from helping to identify bugs to improving
+      performance.</para>
+
+  </sect1>
+  <sect1>
+    <title>Mercurial compared with other tools</title>
+
+    <para>Before you read on, please understand that this section
+      necessarily reflects my own experiences, interests, and (dare I
+      say it) biases.  I have used every one of the revision control
+      tools listed below, in most cases for several years at a
+      time.</para>
+
+
+    <sect2>
+      <title>Subversion</title>
+
+      <para>Subversion is a popular revision control tool, developed
+	to replace CVS.  It has a centralised client/server
+	architecture.</para>
+
+      <para>Subversion and Mercurial have similarly named commands for
+	performing the same operations, so if you're familiar with
+	one, it is easy to learn to use the other.  Both tools are
+	portable to all popular operating systems.</para>
+
+      <para>Prior to version 1.5, Subversion had no useful support for
+	merges. At the time of writing, its merge tracking capability
+	is new, and known to be <ulink
+	  url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword">complicated 
+	  and buggy</ulink>.</para>
+
+      <para>Mercurial has a substantial performance advantage over
+	Subversion on every revision control operation I have
+	benchmarked.  I have measured its advantage as ranging from a
+	factor of two to a factor of six when compared with Subversion
+	1.4.3's <emphasis>ra_local</emphasis> file store, which is the
+	fastest access method available.  In more realistic
+	deployments involving a network-based store, Subversion will
+	be at a substantially larger disadvantage.  Because many
+	Subversion commands must talk to the server and Subversion
+	does not have useful replication facilities, server capacity
+	and network bandwidth become bottlenecks for modestly large
+	projects.</para>
+
+      <para>Additionally, Subversion incurs substantial storage
+	overhead to avoid network transactions for a few common
+	operations, such as finding modified files
+	(<literal>status</literal>) and displaying modifications
+	against the current revision (<literal>diff</literal>).  As a
+	result, a Subversion working copy is often the same size as,
+	or larger than, a Mercurial repository and working directory,
+	even though the Mercurial repository contains a complete
+	history of the project.</para>
+
+      <para>Subversion is widely supported by third party tools.
+	Mercurial currently lags considerably in this area.  This gap
+	is closing, however, and indeed some of Mercurial's GUI tools
+	now outshine their Subversion equivalents.  Like Mercurial,
+	Subversion has an excellent user manual.</para>
+
+      <para>Because Subversion doesn't store revision history on the
+	client, it is well suited to managing projects that deal with
+	lots of large, opaque binary files.  If you check in fifty
+	revisions to an incompressible 10MB file, Subversion's
+	client-side space usage stays constant The space used by any
+	distributed SCM will grow rapidly in proportion to the number
+	of revisions, because the differences between each revision
+	are large.</para>
+
+      <para>In addition, it's often difficult or, more usually,
+	impossible to merge different versions of a binary file.
+	Subversion's ability to let a user lock a file, so that they
+	temporarily have the exclusive right to commit changes to it,
+	can be a significant advantage to a project where binary files
+	are widely used.</para>
+
+      <para>Mercurial can import revision history from a Subversion
+	repository. It can also export revision history to a
+	Subversion repository.  This makes it easy to <quote>test the
+	  waters</quote> and use Mercurial and Subversion in parallel
+	before deciding to switch.  History conversion is incremental,
+	so you can perform an initial conversion, then small
+	additional conversions afterwards to bring in new
+	changes.</para>
+
+
+    </sect2>
+    <sect2>
+      <title>Git</title>
+
+      <para>Git is a distributed revision control tool that was
+	developed for managing the Linux kernel source tree.  Like
+	Mercurial, its early design was somewhat influenced by
+	Monotone.</para>
+
+      <para>Git has a very large command set, with version 1.5.0
+	providing 139 individual commands.  It has something of a
+	reputation for being difficult to learn.  Compared to Git,
+	Mercurial has a strong focus on simplicity.</para>
+
+      <para>In terms of performance, Git is extremely fast.  In
+	several cases, it is faster than Mercurial, at least on Linux,
+	while Mercurial performs better on other operations.  However,
+	on Windows, the performance and general level of support that
+	Git provides is, at the time of writing, far behind that of
+	Mercurial.</para>
+
+      <para>While a Mercurial repository needs no maintenance, a Git
+	repository requires frequent manual <quote>repacks</quote> of
+	its metadata.  Without these, performance degrades, while
+	space usage grows rapidly.  A server that contains many Git
+	repositories that are not rigorously and frequently repacked
+	will become heavily disk-bound during backups, and there have
+	been instances of daily backups taking far longer than 24
+	hours as a result.  A freshly packed Git repository is
+	slightly smaller than a Mercurial repository, but an unpacked
+	repository is several orders of magnitude larger.</para>
+
+      <para>The core of Git is written in C.  Many Git commands are
+	implemented as shell or Perl scripts, and the quality of these
+	scripts varies widely. I have encountered several instances
+	where scripts charged along blindly in the presence of errors
+	that should have been fatal.</para>
+
+      <para>Mercurial can import revision history from a Git
+	repository.</para>
+
+
+    </sect2>
+    <sect2>
+      <title>CVS</title>
+
+      <para>CVS is probably the most widely used revision control tool
+	in the world.  Due to its age and internal untidiness, it has
+	been only lightly maintained for many years.</para>
+
+      <para>It has a centralised client/server architecture.  It does
+	not group related file changes into atomic commits, making it
+	easy for people to <quote>break the build</quote>: one person
+	can successfully commit part of a change and then be blocked
+	by the need for a merge, causing other people to see only a
+	portion of the work they intended to do.  This also affects
+	how you work with project history.  If you want to see all of
+	the modifications someone made as part of a task, you will
+	need to manually inspect the descriptions and timestamps of
+	the changes made to each file involved (if you even know what
+	those files were).</para>
+
+      <para>CVS has a muddled notion of tags and branches that I will
+	not attempt to even describe.  It does not support renaming of
+	files or directories well, making it easy to corrupt a
+	repository.  It has almost no internal consistency checking
+	capabilities, so it is usually not even possible to tell
+	whether or how a repository is corrupt.  I would not recommend
+	CVS for any project, existing or new.</para>
+
+      <para>Mercurial can import CVS revision history.  However, there
+	are a few caveats that apply; these are true of every other
+	revision control tool's CVS importer, too.  Due to CVS's lack
+	of atomic changes and unversioned filesystem hierarchy, it is
+	not possible to reconstruct CVS history completely accurately;
+	some guesswork is involved, and renames will usually not show
+	up.  Because a lot of advanced CVS administration has to be
+	done by hand and is hence error-prone, it's common for CVS
+	importers to run into multiple problems with corrupted
+	repositories (completely bogus revision timestamps and files
+	that have remained locked for over a decade are just two of
+	the less interesting problems I can recall from personal
+	experience).</para>
+
+      <para>Mercurial can import revision history from a CVS
+	repository.</para>
+
+
+    </sect2>
+    <sect2>
+      <title>Commercial tools</title>
+
+      <para>Perforce has a centralised client/server architecture,
+	with no client-side caching of any data.  Unlike modern
+	revision control tools, Perforce requires that a user run a
+	command to inform the server about every file they intend to
+	edit.</para>
+
+      <para>The performance of Perforce is quite good for small teams,
+	but it falls off rapidly as the number of users grows beyond a
+	few dozen. Modestly large Perforce installations require the
+	deployment of proxies to cope with the load their users
+	generate.</para>
+
+
+    </sect2>
+    <sect2>
+      <title>Choosing a revision control tool</title>
+
+      <para>With the exception of CVS, all of the tools listed above
+	have unique strengths that suit them to particular styles of
+	work.  There is no single revision control tool that is best
+	in all situations.</para>
+
+      <para>As an example, Subversion is a good choice for working
+	with frequently edited binary files, due to its centralised
+	nature and support for file locking.</para>
+
+      <para>I personally find Mercurial's properties of simplicity,
+	performance, and good merge support to be a compelling
+	combination that has served me well for several years.</para>
+
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Switching from another tool to Mercurial</title>
+
+    <para>Mercurial is bundled with an extension named <literal
+	role="hg-ext">convert</literal>, which can incrementally
+      import revision history from several other revision control
+      tools.  By <quote>incremental</quote>, I mean that you can
+      convert all of a project's history to date in one go, then rerun
+      the conversion later to obtain new changes that happened after
+      the initial conversion.</para>
+
+    <para>The revision control tools supported by <literal
+	role="hg-ext">convert</literal> are as follows:</para>
+    <itemizedlist>
+      <listitem><para>Subversion</para></listitem>
+      <listitem><para>CVS</para></listitem>
+      <listitem><para>Git</para></listitem>
+      <listitem><para>Darcs</para></listitem></itemizedlist>
+
+    <para>In addition, <literal role="hg-ext">convert</literal> can
+      export changes from Mercurial to Subversion.  This makes it
+      possible to try Subversion and Mercurial in parallel before
+      committing to a switchover, without risking the loss of any
+      work.</para>
+
+    <para>The <command role="hg-ext-convert">convert</command> command
+      is easy to use.  Simply point it at the path or URL of the
+      source repository, optionally give it the name of the
+      destination repository, and it will start working.  After the
+      initial conversion, just run the same command again to import
+      new changes.</para>
+  </sect1>
+
+  <sect1>
+    <title>A short history of revision control</title>
+
+    <para>The best known of the old-time revision control tools is
+      SCCS (Source Code Control System), which Marc Rochkind wrote at
+      Bell Labs, in the early 1970s.  SCCS operated on individual
+      files, and required every person working on a project to have
+      access to a shared workspace on a single system.  Only one
+      person could modify a file at any time; arbitration for access
+      to files was via locks.  It was common for people to lock files,
+      and later forget to unlock them, preventing anyone else from
+      modifying those files without the help of an
+      administrator.</para>
+
+    <para>Walter Tichy developed a free alternative to SCCS in the
+      early 1980s; he called his program RCS (Revision Control System).
+      Like SCCS, RCS required developers to work in a single shared
+      workspace, and to lock files to prevent multiple people from
+      modifying them simultaneously.</para>
+
+    <para>Later in the 1980s, Dick Grune used RCS as a building block
+      for a set of shell scripts he initially called cmt, but then
+      renamed to CVS (Concurrent Versions System).  The big innovation
+      of CVS was that it let developers work simultaneously and
+      somewhat independently in their own personal workspaces.  The
+      personal workspaces prevented developers from stepping on each
+      other's toes all the time, as was common with SCCS and RCS. Each
+      developer had a copy of every project file, and could modify
+      their copies independently.  They had to merge their edits prior
+      to committing changes to the central repository.</para>
+
+    <para>Brian Berliner took Grune's original scripts and rewrote
+      them in C, releasing in 1989 the code that has since developed
+      into the modern version of CVS.  CVS subsequently acquired the
+      ability to operate over a network connection, giving it a
+      client/server architecture.  CVS's architecture is centralised;
+      only the server has a copy of the history of the project. Client
+      workspaces just contain copies of recent versions of the
+      project's files, and a little metadata to tell them where the
+      server is.  CVS has been enormously successful; it is probably
+      the world's most widely used revision control system.</para>
+
+    <para>In the early 1990s, Sun Microsystems developed an early
+      distributed revision control system, called TeamWare.  A
+      TeamWare workspace contains a complete copy of the project's
+      history.  TeamWare has no notion of a central repository.  (CVS
+      relied upon RCS for its history storage; TeamWare used
+      SCCS.)</para>
+
+    <para>As the 1990s progressed, awareness grew of a number of
+      problems with CVS.  It records simultaneous changes to multiple
+      files individually, instead of grouping them together as a
+      single logically atomic operation.  It does not manage its file
+      hierarchy well; it is easy to make a mess of a repository by
+      renaming files and directories.  Worse, its source code is
+      difficult to read and maintain, which made the <quote>pain
+	level</quote> of fixing these architectural problems
+      prohibitive.</para>
+
+    <para>In 2001, Jim Blandy and Karl Fogel, two developers who had
+      worked on CVS, started a project to replace it with a tool that
+      would have a better architecture and cleaner code.  The result,
+      Subversion, does not stray from CVS's centralised client/server
+      model, but it adds multi-file atomic commits, better namespace
+      management, and a number of other features that make it a
+      generally better tool than CVS. Since its initial release, it
+      has rapidly grown in popularity.</para>
+
+    <para>More or less simultaneously, Graydon Hoare began working on
+      an ambitious distributed revision control system that he named
+      Monotone. While Monotone addresses many of CVS's design flaws
+      and has a peer-to-peer architecture, it goes beyond earlier (and
+      subsequent) revision control tools in a number of innovative
+      ways.  It uses cryptographic hashes as identifiers, and has an
+      integral notion of <quote>trust</quote> for code from different
+      sources.</para>
+
+    <para>Mercurial began life in 2005.  While a few aspects of its
+      design are influenced by Monotone, Mercurial focuses on ease of
+      use, high performance, and scalability to very large
+      projects.</para>
+
+  </sect1>
+
+  <sect1>
+    <title>Colophon&emdash;this book is Free</title>
 
     <para>This book is licensed under the Open Publication License,
       and is produced entirely using Free Software tools.  It is

File en/ch01-intro.xml

-<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
-
-<chapter id="chap:intro">
-  <?dbhtml filename="introduction.html"?>
-  <title>Introduction</title>
-
-  <sect1>
-    <title>About revision control</title>
-
-    <para>Revision control is the process of managing multiple
-      versions of a piece of information.  In its simplest form, this
-      is something that many people do by hand: every time you modify
-      a file, save it under a new name that contains a number, each
-      one higher than the number of the preceding version.</para>
-
-    <para>Manually managing multiple versions of even a single file is
-      an error-prone task, though, so software tools to help automate
-      this process have long been available.  The earliest automated
-      revision control tools were intended to help a single user to
-      manage revisions of a single file.  Over the past few decades,
-      the scope of revision control tools has expanded greatly; they
-      now manage multiple files, and help multiple people to work
-      together.  The best modern revision control tools have no
-      problem coping with thousands of people working together on
-      projects that consist of hundreds of thousands of files.</para>
-
-    <sect2>
-      <title>Why use revision control?</title>
-
-      <para>There are a number of reasons why you or your team might
-	want to use an automated revision control tool for a
-	project.</para>
-      <itemizedlist>
-	<listitem><para>It will track the history and evolution of
-	    your project, so you don't have to.  For every change,
-	    you'll have a log of <emphasis>who</emphasis> made it;
-	    <emphasis>why</emphasis> they made it;
-	    <emphasis>when</emphasis> they made it; and
-	    <emphasis>what</emphasis> the change
-	    was.</para></listitem>
-	<listitem><para>When you're working with other people,
-	    revision control software makes it easier for you to
-	    collaborate.  For example, when people more or less
-	    simultaneously make potentially incompatible changes, the
-	    software will help you to identify and resolve those
-	    conflicts.</para></listitem>
-	<listitem><para>It can help you to recover from mistakes.  If
-	    you make a change that later turns out to be in error, you
-	    can revert to an earlier version of one or more files.  In
-	    fact, a <emphasis>really</emphasis> good revision control
-	    tool will even help you to efficiently figure out exactly
-	    when a problem was introduced (see section <xref
-	      linkend="sec:undo:bisect"/> for details).</para></listitem>
-	<listitem><para>It will help you to work simultaneously on,
-	    and manage the drift between, multiple versions of your
-	    project.</para></listitem></itemizedlist>
-      <para>Most of these reasons are equally valid---at least in
-	theory---whether you're working on a project by yourself, or
-	with a hundred other people.</para>
-
-      <para>A key question about the practicality of revision control
-	at these two different scales (<quote>lone hacker</quote> and
-	<quote>huge team</quote>) is how its
-	<emphasis>benefits</emphasis> compare to its
-	<emphasis>costs</emphasis>.  A revision control tool that's
-	difficult to understand or use is going to impose a high
-	cost.</para>
-
-      <para>A five-hundred-person project is likely to collapse under
-	its own weight almost immediately without a revision control
-	tool and process. In this case, the cost of using revision
-	control might hardly seem worth considering, since
-	<emphasis>without</emphasis> it, failure is almost
-	guaranteed.</para>
-
-      <para>On the other hand, a one-person <quote>quick hack</quote>
-	might seem like a poor place to use a revision control tool,
-	because surely the cost of using one must be close to the
-	overall cost of the project.  Right?</para>
-
-      <para>Mercurial uniquely supports <emphasis>both</emphasis> of
-	these scales of development.  You can learn the basics in just
-	a few minutes, and due to its low overhead, you can apply
-	revision control to the smallest of projects with ease.  Its
-	simplicity means you won't have a lot of abstruse concepts or
-	command sequences competing for mental space with whatever
-	you're <emphasis>really</emphasis> trying to do.  At the same
-	time, Mercurial's high performance and peer-to-peer nature let
-	you scale painlessly to handle large projects.</para>
-
-      <para>No revision control tool can rescue a poorly run project,
-	but a good choice of tools can make a huge difference to the
-	fluidity with which you can work on a project.</para>
-
-    </sect2>
-    <sect2>
-      <title>The many names of revision control</title>
-
-      <para>Revision control is a diverse field, so much so that it
-	doesn't actually have a single name or acronym.  Here are a
-	few of the more common names and acronyms you'll
-	encounter:</para>
-      <itemizedlist>
-	<listitem><para>Revision control (RCS)</para></listitem>
-	<listitem><para>Software configuration management (SCM), or
-	    configuration management</para></listitem>
-	<listitem><para>Source code management</para></listitem>
-	<listitem><para>Source code control, or source
-	    control</para></listitem>
-	<listitem><para>Version control
-	    (VCS)</para></listitem></itemizedlist>
-      <para>Some people claim that these terms actually have different
-	meanings, but in practice they overlap so much that there's no
-	agreed or even useful way to tease them apart.</para>
-
-    </sect2>
-  </sect1>
-  <sect1>
-    <title>A short history of revision control</title>
-
-    <para>The best known of the old-time revision control tools is
-      SCCS (Source Code Control System), which Marc Rochkind wrote at
-      Bell Labs, in the early 1970s.  SCCS operated on individual
-      files, and required every person working on a project to have
-      access to a shared workspace on a single system.  Only one
-      person could modify a file at any time; arbitration for access
-      to files was via locks.  It was common for people to lock files,
-      and later forget to unlock them, preventing anyone else from
-      modifying those files without the help of an
-      administrator.</para>
-
-    <para>Walter Tichy developed a free alternative to SCCS in the
-      early 1980s; he called his program RCS (Revision Control System).
-      Like SCCS, RCS required developers to work in a single shared
-      workspace, and to lock files to prevent multiple people from
-      modifying them simultaneously.</para>
-
-    <para>Later in the 1980s, Dick Grune used RCS as a building block
-      for a set of shell scripts he initially called cmt, but then
-      renamed to CVS (Concurrent Versions System).  The big innovation
-      of CVS was that it let developers work simultaneously and
-      somewhat independently in their own personal workspaces.  The
-      personal workspaces prevented developers from stepping on each
-      other's toes all the time, as was common with SCCS and RCS. Each
-      developer had a copy of every project file, and could modify
-      their copies independently.  They had to merge their edits prior
-      to committing changes to the central repository.</para>
-
-    <para>Brian Berliner took Grune's original scripts and rewrote
-      them in C, releasing in 1989 the code that has since developed
-      into the modern version of CVS.  CVS subsequently acquired the
-      ability to operate over a network connection, giving it a
-      client/server architecture.  CVS's architecture is centralised;
-      only the server has a copy of the history of the project. Client
-      workspaces just contain copies of recent versions of the
-      project's files, and a little metadata to tell them where the
-      server is.  CVS has been enormously successful; it is probably
-      the world's most widely used revision control system.</para>
-
-    <para>In the early 1990s, Sun Microsystems developed an early
-      distributed revision control system, called TeamWare.  A
-      TeamWare workspace contains a complete copy of the project's
-      history.  TeamWare has no notion of a central repository.  (CVS
-      relied upon RCS for its history storage; TeamWare used
-      SCCS.)</para>
-
-    <para>As the 1990s progressed, awareness grew of a number of
-      problems with CVS.  It records simultaneous changes to multiple
-      files individually, instead of grouping them together as a
-      single logically atomic operation.  It does not manage its file
-      hierarchy well; it is easy to make a mess of a repository by
-      renaming files and directories.  Worse, its source code is
-      difficult to read and maintain, which made the <quote>pain
-	level</quote> of fixing these architectural problems
-      prohibitive.</para>
-
-    <para>In 2001, Jim Blandy and Karl Fogel, two developers who had
-      worked on CVS, started a project to replace it with a tool that
-      would have a better architecture and cleaner code.  The result,
-      Subversion, does not stray from CVS's centralised client/server
-      model, but it adds multi-file atomic commits, better namespace
-      management, and a number of other features that make it a
-      generally better tool than CVS. Since its initial release, it
-      has rapidly grown in popularity.</para>
-
-    <para>More or less simultaneously, Graydon Hoare began working on
-      an ambitious distributed revision control system that he named
-      Monotone. While Monotone addresses many of CVS's design flaws
-      and has a peer-to-peer architecture, it goes beyond earlier (and
-      subsequent) revision control tools in a number of innovative
-      ways.  It uses cryptographic hashes as identifiers, and has an
-      integral notion of <quote>trust</quote> for code from different
-      sources.</para>
-
-    <para>Mercurial began life in 2005.  While a few aspects of its
-      design are influenced by Monotone, Mercurial focuses on ease of
-      use, high performance, and scalability to very large
-      projects.</para>
-
-  </sect1>
-  <sect1>
-    <title>Trends in revision control</title>
-
-    <para>There has been an unmistakable trend in the development and
-      use of revision control tools over the past four decades, as
-      people have become familiar with the capabilities of their tools
-      and constrained by their limitations.</para>
-
-    <para>The first generation began by managing single files on
-      individual computers.  Although these tools represented a huge
-      advance over ad-hoc manual revision control, their locking model
-      and reliance on a single computer limited them to small,
-      tightly-knit teams.</para>
-
-    <para>The second generation loosened these constraints by moving
-      to network-centered architectures, and managing entire projects
-      at a time.  As projects grew larger, they ran into new problems.
-      With clients needing to talk to servers very frequently, server
-      scaling became an issue for large projects.  An unreliable
-      network connection could prevent remote users from being able to
-      talk to the server at all.  As open source projects started
-      making read-only access available anonymously to anyone, people
-      without commit privileges found that they could not use the
-      tools to interact with a project in a natural way, as they could
-      not record their changes.</para>
-
-    <para>The current generation of revision control tools is
-      peer-to-peer in nature.  All of these systems have dropped the
-      dependency on a single central server, and allow people to
-      distribute their revision control data to where it's actually
-      needed.  Collaboration over the Internet has moved from
-      constrained by technology to a matter of choice and consensus.
-      Modern tools can operate offline indefinitely and autonomously,
-      with a network connection only needed when syncing changes with
-      another repository.</para>
-
-  </sect1>
-  <sect1>
-    <title>A few of the advantages of distributed revision
-      control</title>
-
-    <para>Even though distributed revision control tools have for
-      several years been as robust and usable as their
-      previous-generation counterparts, people using older tools have
-      not yet necessarily woken up to their advantages.  There are a
-      number of ways in which distributed tools shine relative to
-      centralised ones.</para>
-
-    <para>For an individual developer, distributed tools are almost
-      always much faster than centralised tools.  This is for a simple
-      reason: a centralised tool needs to talk over the network for
-      many common operations, because most metadata is stored in a
-      single copy on the central server.  A distributed tool stores
-      all of its metadata locally.  All else being equal, talking over
-      the network adds overhead to a centralised tool.  Don't
-      underestimate the value of a snappy, responsive tool: you're
-      going to spend a lot of time interacting with your revision
-      control software.</para>
-
-    <para>Distributed tools are indifferent to the vagaries of your
-      server infrastructure, again because they replicate metadata to
-      so many locations.  If you use a centralised system and your
-      server catches fire, you'd better hope that your backup media
-      are reliable, and that your last backup was recent and actually
-      worked.  With a distributed tool, you have many backups
-      available on every contributor's computer.</para>
-
-    <para>The reliability of your network will affect distributed
-      tools far less than it will centralised tools.  You can't even
-      use a centralised tool without a network connection, except for
-      a few highly constrained commands.  With a distributed tool, if
-      your network connection goes down while you're working, you may
-      not even notice.  The only thing you won't be able to do is talk
-      to repositories on other computers, something that is relatively
-      rare compared with local operations.  If you have a far-flung
-      team of collaborators, this may be significant.</para>
-
-    <sect2>
-      <title>Advantages for open source projects</title>
-
-      <para>If you take a shine to an open source project and decide
-	that you would like to start hacking on it, and that project
-	uses a distributed revision control tool, you are at once a
-	peer with the people who consider themselves the
-	<quote>core</quote> of that project.  If they publish their
-	repositories, you can immediately copy their project history,
-	start making changes, and record your work, using the same
-	tools in the same ways as insiders.  By contrast, with a
-	centralised tool, you must use the software in a <quote>read
-	  only</quote> mode unless someone grants you permission to
-	commit changes to their central server.  Until then, you won't
-	be able to record changes, and your local modifications will
-	be at risk of corruption any time you try to update your
-	client's view of the repository.</para>
-
-      <sect3>
-	<title>The forking non-problem</title>
-
-	<para>It has been suggested that distributed revision control
-	  tools pose some sort of risk to open source projects because
-	  they make it easy to <quote>fork</quote> the development of
-	  a project.  A fork happens when there are differences in
-	  opinion or attitude between groups of developers that cause
-	  them to decide that they can't work together any longer.
-	  Each side takes a more or less complete copy of the
-	  project's source code, and goes off in its own
-	  direction.</para>
-
-	<para>Sometimes the camps in a fork decide to reconcile their
-	  differences. With a centralised revision control system, the
-	  <emphasis>technical</emphasis> process of reconciliation is
-	  painful, and has to be performed largely by hand.  You have
-	  to decide whose revision history is going to
-	  <quote>win</quote>, and graft the other team's changes into
-	  the tree somehow. This usually loses some or all of one
-	  side's revision history.</para>
-
-	<para>What distributed tools do with respect to forking is
-	  they make forking the <emphasis>only</emphasis> way to
-	  develop a project.  Every single change that you make is
-	  potentially a fork point.  The great strength of this
-	  approach is that a distributed revision control tool has to
-	  be really good at <emphasis>merging</emphasis> forks,
-	  because forks are absolutely fundamental: they happen all
-	  the time.</para>
-
-	<para>If every piece of work that everybody does, all the
-	  time, is framed in terms of forking and merging, then what
-	  the open source world refers to as a <quote>fork</quote>
-	  becomes <emphasis>purely</emphasis> a social issue.  If
-	  anything, distributed tools <emphasis>lower</emphasis> the
-	  likelihood of a fork:</para>
-	<itemizedlist>
-	  <listitem><para>They eliminate the social distinction that
-	      centralised tools impose: that between insiders (people
-	      with commit access) and outsiders (people
-	      without).</para></listitem>
-	  <listitem><para>They make it easier to reconcile after a
-	      social fork, because all that's involved from the
-	      perspective of the revision control software is just
-	      another merge.</para></listitem></itemizedlist>
-
-	<para>Some people resist distributed tools because they want
-	  to retain tight control over their projects, and they
-	  believe that centralised tools give them this control.
-	  However, if you're of this belief, and you publish your CVS
-	  or Subversion repositories publicly, there are plenty of
-	  tools available that can pull out your entire project's
-	  history (albeit slowly) and recreate it somewhere that you
-	  don't control.  So while your control in this case is
-	  illusory, you are forgoing the ability to fluidly
-	  collaborate with whatever people feel compelled to mirror
-	  and fork your history.</para>
-
-      </sect3>
-    </sect2>
-    <sect2>
-      <title>Advantages for commercial projects</title>
-
-      <para>Many commercial projects are undertaken by teams that are
-	scattered across the globe.  Contributors who are far from a
-	central server will see slower command execution and perhaps
-	less reliability.  Commercial revision control systems attempt
-	to ameliorate these problems with remote-site replication
-	add-ons that are typically expensive to buy and cantankerous
-	to administer.  A distributed system doesn't suffer from these
-	problems in the first place.  Better yet, you can easily set
-	up multiple authoritative servers, say one per site, so that
-	there's no redundant communication between repositories over
-	expensive long-haul network links.</para>
-
-      <para>Centralised revision control systems tend to have
-	relatively low scalability.  It's not unusual for an expensive
-	centralised system to fall over under the combined load of
-	just a few dozen concurrent users.  Once again, the typical
-	response tends to be an expensive and clunky replication
-	facility.  Since the load on a central server---if you have
-	one at all---is many times lower with a distributed tool
-	(because all of the data is replicated everywhere), a single
-	cheap server can handle the needs of a much larger team, and
-	replication to balance load becomes a simple matter of
-	scripting.</para>
-
-      <para>If you have an employee in the field, troubleshooting a
-	problem at a customer's site, they'll benefit from distributed
-	revision control. The tool will let them generate custom
-	builds, try different fixes in isolation from each other, and
-	search efficiently through history for the sources of bugs and
-	regressions in the customer's environment, all without needing
-	to connect to your company's network.</para>
-
-    </sect2>
-  </sect1>
-  <sect1>
-    <title>Why choose Mercurial?</title>
-
-    <para>Mercurial has a unique set of properties that make it a
-      particularly good choice as a revision control system.</para>
-    <itemizedlist>
-      <listitem><para>It is easy to learn and use.</para></listitem>
-      <listitem><para>It is lightweight.</para></listitem>
-      <listitem><para>It scales excellently.</para></listitem>
-      <listitem><para>It is easy to
-	  customise.</para></listitem></itemizedlist>
-
-    <para>If you are at all familiar with revision control systems,
-      you should be able to get up and running with Mercurial in less
-      than five minutes.  Even if not, it will take no more than a few
-      minutes longer.  Mercurial's command and feature sets are
-      generally uniform and consistent, so you can keep track of a few
-      general rules instead of a host of exceptions.</para>
-
-    <para>On a small project, you can start working with Mercurial in
-      moments. Creating new changes and branches; transferring changes
-      around (whether locally or over a network); and history and
-      status operations are all fast.  Mercurial attempts to stay
-      nimble and largely out of your way by combining low cognitive
-      overhead with blazingly fast operations.</para>
-
-    <para>The usefulness of Mercurial is not limited to small
-      projects: it is used by projects with hundreds to thousands of
-      contributors, each containing tens of thousands of files and
-      hundreds of megabytes of source code.</para>
-
-    <para>If the core functionality of Mercurial is not enough for
-      you, it's easy to build on.  Mercurial is well suited to
-      scripting tasks, and its clean internals and implementation in
-      Python make it easy to add features in the form of extensions.
-      There are a number of popular and useful extensions already
-      available, ranging from helping to identify bugs to improving
-      performance.</para>
-
-  </sect1>
-  <sect1>
-    <title>Mercurial compared with other tools</title>
-
-    <para>Before you read on, please understand that this section
-      necessarily reflects my own experiences, interests, and (dare I
-      say it) biases.  I have used every one of the revision control
-      tools listed below, in most cases for several years at a
-      time.</para>
-
-
-    <sect2>
-      <title>Subversion</title>
-
-      <para>Subversion is a popular revision control tool, developed
-	to replace CVS.  It has a centralised client/server
-	architecture.</para>
-
-      <para>Subversion and Mercurial have similarly named commands for
-	performing the same operations, so if you're familiar with
-	one, it is easy to learn to use the other.  Both tools are
-	portable to all popular operating systems.</para>
-
-      <para>Prior to version 1.5, Subversion had no useful support for
-	merges. At the time of writing, its merge tracking capability
-	is new, and known to be <ulink
-	  url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword">complicated 
-	  and buggy</ulink>.</para>
-
-      <para>Mercurial has a substantial performance advantage over
-	Subversion on every revision control operation I have
-	benchmarked.  I have measured its advantage as ranging from a
-	factor of two to a factor of six when compared with Subversion
-	1.4.3's <emphasis>ra_local</emphasis> file store, which is the
-	fastest access method available.  In more realistic
-	deployments involving a network-based store, Subversion will
-	be at a substantially larger disadvantage.  Because many
-	Subversion commands must talk to the server and Subversion
-	does not have useful replication facilities, server capacity
-	and network bandwidth become bottlenecks for modestly large
-	projects.</para>
-
-      <para>Additionally, Subversion incurs substantial storage
-	overhead to avoid network transactions for a few common
-	operations, such as finding modified files
-	(<literal>status</literal>) and displaying modifications
-	against the current revision (<literal>diff</literal>).  As a
-	result, a Subversion working copy is often the same size as,
-	or larger than, a Mercurial repository and working directory,
-	even though the Mercurial repository contains a complete
-	history of the project.</para>
-
-      <para>Subversion is widely supported by third party tools.
-	Mercurial currently lags considerably in this area.  This gap
-	is closing, however, and indeed some of Mercurial's GUI tools
-	now outshine their Subversion equivalents.  Like Mercurial,
-	Subversion has an excellent user manual.</para>
-
-      <para>Because Subversion doesn't store revision history on the
-	client, it is well suited to managing projects that deal with
-	lots of large, opaque binary files.  If you check in fifty
-	revisions to an incompressible 10MB file, Subversion's
-	client-side space usage stays constant The space used by any
-	distributed SCM will grow rapidly in proportion to the number
-	of revisions, because the differences between each revision
-	are large.</para>
-
-      <para>In addition, it's often difficult or, more usually,
-	impossible to merge different versions of a binary file.
-	Subversion's ability to let a user lock a file, so that they
-	temporarily have the exclusive right to commit changes to it,
-	can be a significant advantage to a project where binary files
-	are widely used.</para>
-
-      <para>Mercurial can import revision history from a Subversion
-	repository. It can also export revision history to a
-	Subversion repository.  This makes it easy to <quote>test the
-	  waters</quote> and use Mercurial and Subversion in parallel
-	before deciding to switch.  History conversion is incremental,
-	so you can perform an initial conversion, then small
-	additional conversions afterwards to bring in new
-	changes.</para>
-
-
-    </sect2>
-    <sect2>
-      <title>Git</title>
-
-      <para>Git is a distributed revision control tool that was
-	developed for managing the Linux kernel source tree.  Like
-	Mercurial, its early design was somewhat influenced by
-	Monotone.</para>
-
-      <para>Git has a very large command set, with version 1.5.0
-	providing 139 individual commands.  It has something of a
-	reputation for being difficult to learn.  Compared to Git,
-	Mercurial has a strong focus on simplicity.</para>
-
-      <para>In terms of performance, Git is extremely fast.  In
-	several cases, it is faster than Mercurial, at least on Linux,
-	while Mercurial performs better on other operations.  However,
-	on Windows, the performance and general level of support that
-	Git provides is, at the time of writing, far behind that of
-	Mercurial.</para>
-
-      <para>While a Mercurial repository needs no maintenance, a Git
-	repository requires frequent manual <quote>repacks</quote> of
-	its metadata.  Without these, performance degrades, while
-	space usage grows rapidly.  A server that contains many Git
-	repositories that are not rigorously and frequently repacked
-	will become heavily disk-bound during backups, and there have
-	been instances of daily backups taking far longer than 24
-	hours as a result.  A freshly packed Git repository is
-	slightly smaller than a Mercurial repository, but an unpacked
-	repository is several orders of magnitude larger.</para>
-
-      <para>The core of Git is written in C.  Many Git commands are
-	implemented as shell or Perl scripts, and the quality of these
-	scripts varies widely. I have encountered several instances
-	where scripts charged along blindly in the presence of errors
-	that should have been fatal.</para>
-
-      <para>Mercurial can import revision history from a Git
-	repository.</para>
-
-
-    </sect2>
-    <sect2>
-      <title>CVS</title>
-
-      <para>CVS is probably the most widely used revision control tool
-	in the world.  Due to its age and internal untidiness, it has
-	been only lightly maintained for many years.</para>
-
-      <para>It has a centralised client/server architecture.  It does
-	not group related file changes into atomic commits, making it
-	easy for people to <quote>break the build</quote>: one person
-	can successfully commit part of a change and then be blocked
-	by the need for a merge, causing other people to see only a
-	portion of the work they intended to do.  This also affects
-	how you work with project history.  If you want to see all of
-	the modifications someone made as part of a task, you will
-	need to manually inspect the descriptions and timestamps of
-	the changes made to each file involved (if you even know what
-	those files were).</para>
-
-      <para>CVS has a muddled notion of tags and branches that I will
-	not attempt to even describe.  It does not support renaming of
-	files or directories well, making it easy to corrupt a
-	repository.  It has almost no internal consistency checking
-	capabilities, so it is usually not even possible to tell
-	whether or how a repository is corrupt.  I would not recommend
-	CVS for any project, existing or new.</para>
-
-      <para>Mercurial can import CVS revision history.  However, there
-	are a few caveats that apply; these are true of every other
-	revision control tool's CVS importer, too.  Due to CVS's lack
-	of atomic changes and unversioned filesystem hierarchy, it is
-	not possible to reconstruct CVS history completely accurately;
-	some guesswork is involved, and renames will usually not show
-	up.  Because a lot of advanced CVS administration has to be
-	done by hand and is hence error-prone, it's common for CVS
-	importers to run into multiple problems with corrupted
-	repositories (completely bogus revision timestamps and files
-	that have remained locked for over a decade are just two of
-	the less interesting problems I can recall from personal
-	experience).</para>
-
-      <para>Mercurial can import revision history from a CVS
-	repository.</para>
-
-
-    </sect2>
-    <sect2>
-      <title>Commercial tools</title>
-
-      <para>Perforce has a centralised client/server architecture,
-	with no client-side caching of any data.  Unlike modern
-	revision control tools, Perforce requires that a user run a
-	command to inform the server about every file they intend to
-	edit.</para>
-
-      <para>The performance of Perforce is quite good for small teams,
-	but it falls off rapidly as the number of users grows beyond a
-	few dozen. Modestly large Perforce installations require the
-	deployment of proxies to cope with the load their users
-	generate.</para>
-
-
-    </sect2>
-    <sect2>
-      <title>Choosing a revision control tool</title>
-
-      <para>With the exception of CVS, all of the tools listed above
-	have unique strengths that suit them to particular styles of
-	work.  There is no single revision control tool that is best
-	in all situations.</para>
-
-      <para>As an example, Subversion is a good choice for working
-	with frequently edited binary files, due to its centralised
-	nature and support for file locking.</para>
-
-      <para>I personally find Mercurial's properties of simplicity,
-	performance, and good merge support to be a compelling
-	combination that has served me well for several years.</para>
-
-
-    </sect2>
-  </sect1>
-  <sect1>
-    <title>Switching from another tool to Mercurial</title>
-
-    <para>Mercurial is bundled with an extension named <literal
-	role="hg-ext">convert</literal>, which can incrementally
-      import revision history from several other revision control
-      tools.  By <quote>incremental</quote>, I mean that you can
-      convert all of a project's history to date in one go, then rerun
-      the conversion later to obtain new changes that happened after
-      the initial conversion.</para>
-
-    <para>The revision control tools supported by <literal
-	role="hg-ext">convert</literal> are as follows:</para>
-    <itemizedlist>
-      <listitem><para>Subversion</para></listitem>
-      <listitem><para>CVS</para></listitem>
-      <listitem><para>Git</para></listitem>
-      <listitem><para>Darcs</para></listitem></itemizedlist>
-
-    <para>In addition, <literal role="hg-ext">convert</literal> can
-      export changes from Mercurial to Subversion.  This makes it
-      possible to try Subversion and Mercurial in parallel before
-      committing to a switchover, without risking the loss of any
-      work.</para>
-
-    <para>The <command role="hg-ext-conver">convert</command> command
-      is easy to use.  Simply point it at the path or URL of the
-      source repository, optionally give it the name of the
-      destination repository, and it will start working.  After the
-      initial conversion, just run the same command again to import
-      new changes.</para>
-  </sect1>
-</chapter>
-
-<!--
-local variables: 
-sgml-parent-document: ("00book.xml" "book" "chapter")
-end:
--->

File en/ch01-tour-basic.xml

+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<chapter id="chap:tour-basic">
+  <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?>
+  <title>A tour of Mercurial: the basics</title>
+
+  <sect1 id="sec:tour:install">
+    <title>Installing Mercurial on your system</title>
+
+    <para>Prebuilt binary packages of Mercurial are available for
+      every popular operating system.  These make it easy to start
+      using Mercurial on your computer immediately.</para>
+
+    <sect2>
+      <title>Linux</title>
+
+      <para>Because each Linux distribution has its own packaging
+	tools, policies, and rate of development, it's difficult to
+	give a comprehensive set of instructions on how to install
+	Mercurial binaries.  The version of Mercurial that you will
+	end up with can vary depending on how active the person is who
+	maintains the package for your distribution.</para>
+
+      <para>To keep things simple, I will focus on installing
+	Mercurial from the command line under the most popular Linux
+	distributions.  Most of these distributions provide graphical
+	package managers that will let you install Mercurial with a
+	single click; the package name to look for is
+	<literal>mercurial</literal>.</para>
+
+      <itemizedlist>
+	<listitem><para>Debian:</para>
+	  <programlisting>apt-get install mercurial</programlisting></listitem>
+	<listitem><para>Fedora Core:</para>
+	  <programlisting>yum install mercurial</programlisting></listitem>
+	<listitem><para>Gentoo:</para>
+	  <programlisting>emerge mercurial</programlisting></listitem>
+	<listitem><para>OpenSUSE:</para>
+	  <programlisting>yum install mercurial</programlisting></listitem>
+	<listitem><para>Ubuntu: Ubuntu's Mercurial package is based on
+	    Debian's.  To install it, run the following
+	    command.</para>
+	  <programlisting>apt-get install mercurial</programlisting></listitem>
+      </itemizedlist>
+
+    </sect2>
+    <sect2>
+      <title>Solaris</title>
+
+      <para>SunFreeWare, at <ulink
+	  url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 
+	is a good source for a large number of pre-built Solaris
+	packages for 32 and 64 bit Intel and Sparc architectures,
+	including current versions of Mercurial.</para>
+
+    </sect2>
+    <sect2>
+      <title>Mac OS X</title>
+
+      <para>Lee Cantey publishes an installer of Mercurial for Mac OS
+	X at <ulink
+	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 
+	This package works on both Intel- and Power-based Macs. Before
+	you can use it, you must install a compatible version of
+	Universal MacPython <citation>web:macpython</citation>. This
+	is easy to do; simply follow the instructions on Lee's
+	site.</para>
+
+      <para>It's also possible to install Mercurial using Fink or
+	MacPorts, two popular free package managers for Mac OS X.  If
+	you have Fink, use <command>sudo apt-get install
+	  mercurial-py25</command>.  If MacPorts, <command>sudo port
+	  install mercurial</command>.</para>
+
+    </sect2>
+    <sect2>
+      <title>Windows</title>
+
+      <para>Lee Cantey publishes an installer of Mercurial for Windows
+	at <ulink
+	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 
+	This package has no external dependencies; it <quote>just
+	  works</quote>.</para>
+
+      <note>
+	<para>  The Windows version of Mercurial does not
+	  automatically convert line endings between Windows and Unix
+	  styles.  If you want to share work with Unix users, you must
+	  do a little additional configuration work. XXX Flesh this
+	  out.</para>
+      </note>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Getting started</title>
+
+    <para>To begin, we'll use the <command role="hg-cmd">hg
+	version</command> command to find out whether Mercurial is
+      actually installed properly.  The actual version information
+      that it prints isn't so important; it's whether it prints
+      anything at all that we care about.</para>
+
+    &interaction.tour.version;
+
+    <sect2>
+      <title>Built-in help</title>
+
+      <para>Mercurial provides a built-in help system.  This is
+	  invaluable for those times when you find yourself stuck
+	  trying to remember how to run a command.  If you are
+	  completely stuck, simply run <command role="hg-cmd">hg
+	    help</command>; it will print a brief list of commands,
+	  along with a description of what each does.  If you ask for
+	  help on a specific command (as below), it prints more
+	  detailed information.</para>
+
+	&interaction.tour.help;
+
+	<para>For a more impressive level of detail (which you won't
+	  usually need) run <command role="hg-cmd">hg help <option
+	      role="hg-opt-global">-v</option></command>.  The <option
+	    role="hg-opt-global">-v</option> option is short for
+	  <option role="hg-opt-global">--verbose</option>, and tells
+	  Mercurial to print more information than it usually
+	  would.</para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>Working with a repository</title>
+
+    <para>In Mercurial, everything happens inside a
+      <emphasis>repository</emphasis>.  The repository for a project
+      contains all of the files that <quote>belong to</quote> that
+      project, along with a historical record of the project's
+      files.</para>
+
+    <para>There's nothing particularly magical about a repository; it
+      is simply a directory tree in your filesystem that Mercurial
+      treats as special. You can rename or delete a repository any
+      time you like, using either the command line or your file
+      browser.</para>
+
+    <sect2>
+      <title>Making a local copy of a repository</title>
+
+      <para><emphasis>Copying</emphasis> a repository is just a little
+	bit special.  While you could use a normal file copying
+	command to make a copy of a repository, it's best to use a
+	built-in command that Mercurial provides.  This command is
+	called <command role="hg-cmd">hg clone</command>, because it
+	creates an identical copy of an existing repository.</para>
+
+      &interaction.tour.clone;
+
+      <para>If our clone succeeded, we should now have a local
+	directory called <filename class="directory">hello</filename>.
+	This directory will contain some files.</para>
+
+      &interaction.tour.ls;
+
+      <para>These files have the same contents and history in our
+	repository as they do in the repository we cloned.</para>
+
+      <para>Every Mercurial repository is complete, self-contained,
+	and independent.  It contains its own private copy of a
+	project's files and history.  A cloned repository remembers
+	the location of the repository it was cloned from, but it does
+	not communicate with that repository, or any other, unless you
+	tell it to.</para>
+
+      <para>What this means for now is that we're free to experiment
+	with our repository, safe in the knowledge that it's a private
+	<quote>sandbox</quote> that won't affect anyone else.</para>
+
+    </sect2>
+    <sect2>
+      <title>What's in a repository?</title>
+
+      <para>When we take a more detailed look inside a repository, we
+	can see that it contains a directory named <filename
+	  class="directory">.hg</filename>.  This is where Mercurial
+	keeps all of its metadata for the repository.</para>
+
+      &interaction.tour.ls-a;
+
+      <para>The contents of the <filename
+	  class="directory">.hg</filename> directory and its
+	subdirectories are private to Mercurial.  Every other file and
+	directory in the repository is yours to do with as you
+	please.</para>
+
+      <para>To introduce a little terminology, the <filename
+	  class="directory">.hg</filename> directory is the
+	<quote>real</quote> repository, and all of the files and
+	directories that coexist with it are said to live in the
+	<emphasis>working directory</emphasis>.  An easy way to
+	remember the distinction is that the
+	<emphasis>repository</emphasis> contains the
+	<emphasis>history</emphasis> of your project, while the
+	<emphasis>working directory</emphasis> contains a
+	<emphasis>snapshot</emphasis> of your project at a particular
+	point in history.</para>
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>A tour through history</title>
+
+    <para>One of the first things we might want to do with a new,
+      unfamiliar repository is understand its history.  The <command
+	role="hg-cmd">hg log</command> command gives us a view of
+      history.</para>
+
+    &interaction.tour.log;
+
+    <para>By default, this command prints a brief paragraph of output
+      for each change to the project that was recorded.  In Mercurial
+      terminology, we call each of these recorded events a
+      <emphasis>changeset</emphasis>, because it can contain a record
+      of changes to several files.</para>
+
+    <para>The fields in a record of output from <command
+	role="hg-cmd">hg log</command> are as follows.</para>
+    <itemizedlist>
+      <listitem><para><literal>changeset</literal>: This field has the
+	  format of a number, followed by a colon, followed by a
+	  hexadecimal string.  These are
+	  <emphasis>identifiers</emphasis> for the changeset.  There
+	  are two identifiers because the number is shorter and easier
+	  to type than the hex string.</para></listitem>
+      <listitem><para><literal>user</literal>: The identity of the
+	  person who created the changeset.  This is a free-form
+	  field, but it most often contains a person's name and email
+	  address.</para></listitem>
+      <listitem><para><literal>date</literal>: The date and time on
+	  which the changeset was created, and the timezone in which
+	  it was created.  (The date and time are local to that
+	  timezone; they display what time and date it was for the
+	  person who created the changeset.)</para></listitem>
+      <listitem><para><literal>summary</literal>: The first line of
+	  the text message that the creator of the changeset entered
+	  to describe the changeset.</para></listitem></itemizedlist>
+    <para>The default output printed by <command role="hg-cmd">hg
+	log</command> is purely a summary; it is missing a lot of
+      detail.</para>
+
+    <para>Figure <xref linkend="fig:tour-basic:history"/> provides a
+      graphical representation of the history of the <filename
+	class="directory">hello</filename> repository, to make it a
+      little easier to see which direction history is
+      <quote>flowing</quote> in.  We'll be returning to this figure
+      several times in this chapter and the chapter that
+      follows.</para>
+
+    <informalfigure id="fig:tour-basic:history">
+      <mediaobject>
+	<imageobject><imagedata fileref="tour-history"/></imageobject>
+	<textobject><phrase>XXX add text</phrase></textobject>
+	<caption><para>Graphical history of the <filename
+	      class="directory">hello</filename>
+	    repository</para></caption>
+      </mediaobject>
+    </informalfigure>
+
+    <sect2>
+      <title>Changesets, revisions, and talking to other
+	people</title>
+
+      <para>As English is a notoriously sloppy language, and computer
+	science has a hallowed history of terminological confusion
+	(why use one term when four will do?), revision control has a
+	variety of words and phrases that mean the same thing.  If you
+	are talking about Mercurial history with other people, you
+	will find that the word <quote>changeset</quote> is often
+	compressed to <quote>change</quote> or (when written)
+	<quote>cset</quote>, and sometimes a changeset is referred to
+	as a <quote>revision</quote> or a <quote>rev</quote>.</para>
+
+      <para>While it doesn't matter what <emphasis>word</emphasis> you
+	use to refer to the concept of <quote>a changeset</quote>, the
+	<emphasis>identifier</emphasis> that you use to refer to
+	<quote>a <emphasis>specific</emphasis> changeset</quote> is of
+	great importance. Recall that the <literal>changeset</literal>
+	field in the output from <command role="hg-cmd">hg
+	  log</command> identifies a changeset using both a number and
+	a hexadecimal string.</para>
+      <itemizedlist>
+	<listitem><para>The revision number is <emphasis>only valid in
+	      that repository</emphasis>,</para></listitem>
+	<listitem><para>while the hex string is the
+	    <emphasis>permanent, unchanging identifier</emphasis> that
+	    will always identify that exact changeset in
+	    <emphasis>every</emphasis> copy of the
+	    repository.</para></listitem></itemizedlist>
+      <para>This distinction is important.  If you send someone an
+	email talking about <quote>revision 33</quote>, there's a high
+	likelihood that their revision 33 will <emphasis>not be the
+	  same</emphasis> as yours.  The reason for this is that a
+	revision number depends on the order in which changes arrived
+	in a repository, and there is no guarantee that the same
+	changes will happen in the same order in different
+	repositories. Three changes $a,b,c$ can easily appear in one
+	repository as $0,1,2$, while in another as $1,0,2$.</para>
+
+      <para>Mercurial uses revision numbers purely as a convenient
+	shorthand.  If you need to discuss a changeset with someone,
+	or make a record of a changeset for some other reason (for
+	example, in a bug report), use the hexadecimal
+	identifier.</para>
+
+    </sect2>
+    <sect2>
+      <title>Viewing specific revisions</title>
+
+      <para>To narrow the output of <command role="hg-cmd">hg
+	  log</command> down to a single revision, use the <option
+	  role="hg-opt-log">-r</option> (or <option
+	  role="hg-opt-log">--rev</option>) option.  You can use
+	either a revision number or a long-form changeset identifier,
+	and you can provide as many revisions as you want.</para>
+
+      &interaction.tour.log-r;
+
+      <para>If you want to see the history of several revisions
+	without having to list each one, you can use <emphasis>range
+	  notation</emphasis>; this lets you express the idea <quote>I
+	  want all revisions between <literal>abc</literal> and
+	  <literal>def</literal>, inclusive</quote>.</para>
+      
+	&interaction.tour.log.range;
+
+      <para>Mercurial also honours the order in which you specify
+	revisions, so <command role="hg-cmd">hg log -r 2:4</command>
+	prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
+	  4:2</command> prints 4, 3, and 2.</para>
+
+    </sect2>
+    <sect2>
+      <title>More detailed information</title>
+
+      <para>While the summary information printed by <command
+	  role="hg-cmd">hg log</command> is useful if you already know
+	what you're looking for, you may need to see a complete
+	description of the change, or a list of the files changed, if
+	you're trying to decide whether a changeset is the one you're
+	looking for. The <command role="hg-cmd">hg log</command>
+	command's <option role="hg-opt-global">-v</option> (or <option
+	  role="hg-opt-global">--verbose</option>) option gives you
+	this extra detail.</para>
+
+      &interaction.tour.log-v;
+
+      <para>If you want to see both the description and content of a
+	change, add the <option role="hg-opt-log">-p</option> (or
+	<option role="hg-opt-log">--patch</option>) option.  This
+	displays the content of a change as a <emphasis>unified
+	  diff</emphasis> (if you've never seen a unified diff before,
+	see section <xref linkend="sec:mq:patch"/> for an
+	overview).</para>
+
+      &interaction.tour.log-vp;
+
+    </sect2>
+  </sect1>
+  <sect1>
+    <title>All about command options</title>
+
+    <para>Let's take a brief break from exploring Mercurial commands
+      to discuss a pattern in the way that they work; you may find
+      this useful to keep in mind as we continue our tour.</para>
+
+    <para>Mercurial has a consistent and straightforward approach to
+      dealing with the options that you can pass to commands.  It
+      follows the conventions for options that are common to modern
+      Linux and Unix systems.</para>
+    <itemizedlist>
+      <listitem><para>Every option has a long name.  For example, as
+	  we've already seen, the <command role="hg-cmd">hg
+	    log</command> command accepts a <option
+	    role="hg-opt-log">--rev</option> option.</para></listitem>
+      <listitem><para>Most options have short names, too.  Instead of
+	  <option role="hg-opt-log">--rev</option>, we can use <option
+	    role="hg-opt-log">-r</option>.  (The reason that some
+	  options don't have short names is that the options in
+	  question are rarely used.)</para></listitem>
+      <listitem><para>Long options start with two dashes (e.g. <option
+	    role="hg-opt-log">--rev</option>), while short options
+	  start with one (e.g. <option
+	    role="hg-opt-log">-r</option>).</para></listitem>
+      <listitem><para>Option naming and usage is consistent across
+	  commands.  For example, every command that lets you specify
+	  a changeset ID or revision number accepts both <option
+	    role="hg-opt-log">-r</option> and <option
+	    role="hg-opt-log">--rev</option>
+	  arguments.</para></listitem></itemizedlist>
+    <para>In the examples throughout this book, I use short options
+      instead of long.  This just reflects my own preference, so don't
+      read anything significant into it.</para>
+
+    <para>Most commands that print output of some kind will print more
+      output when passed a <option role="hg-opt-global">-v</option>
+      (or <option role="hg-opt-global">--verbose</option>) option, and
+      less when passed <option role="hg-opt-global">-q</option> (or
+      <option role="hg-opt-global">--quiet</option>).</para>
+
+  </sect1>
+  <sect1>
+    <title>Making and reviewing changes</title>
+
+    <para>Now that we have a grasp of viewing history in Mercurial,
+      let's take a look at making some changes and examining
+      them.</para>
+
+    <para>The first thing we'll do is isolate our experiment in a
+      repository of its own.  We use the <command role="hg-cmd">hg
+	clone</command> command, but we don't need to clone a copy of
+      the remote repository.  Since we already have a copy of it
+      locally, we can just clone that instead.  This is much faster
+      than cloning over the network, and cloning a local repository
+      uses less disk space in most cases, too.</para>
+
+    &interaction.tour.reclone;
+
+    <para>As an aside, it's often good practice to keep a
+      <quote>pristine</quote> copy of a remote repository around,
+      which you can then make temporary clones of to create sandboxes
+      for each task you want to work on.  This lets you work on
+      multiple tasks in parallel, each isolated from the others until
+      it's complete and you're ready to integrate it back.  Because
+      local clones are so cheap, there's almost no overhead to cloning
+      and destroying repositories whenever you want.</para>
+
+    <para>In our <filename class="directory">my-hello</filename>
+      repository, we have a file <filename>hello.c</filename> that
+      contains the classic <quote>hello, world</quote> program. Let's
+      use the ancient and venerable <command>sed</command> command to
+      edit this file so that it prints a second line of output.  (I'm
+      only using <command>sed</command> to do this because it's easy
+      to write a scripted example this way.  Since you're not under
+      the same constraint, you probably won't want to use
+      <command>sed</command>; simply use your preferred text editor to
+      do the same thing.)</para>
+
+    &interaction.tour.sed;
+
+    <para>Mercurial's <command role="hg-cmd">hg status</command>
+      command will tell us what Mercurial knows about the files in the
+      repository.</para>
+
+    &interaction.tour.status;
+
+    <para>The <command role="hg-cmd">hg status</command> command
+      prints no output for some files, but a line starting with
+      <quote><literal>M</literal></quote> for
+      <filename>hello.c</filename>.  Unless you tell it to, <command
+	role="hg-cmd">hg status</command> will not print any output
+      for files that have not been modified.</para>
+
+    <para>The <quote><literal>M</literal></quote> indicates that
+      Mercurial has noticed that we modified
+      <filename>hello.c</filename>.  We didn't need to
+      <emphasis>inform</emphasis> Mercurial that we were going to
+      modify the file before we started, or that we had modified the
+      file after we were done; it was able to figure this out
+      itself.</para>
+
+    <para>It's a little bit helpful to know that we've modified
+      <filename>hello.c</filename>, but we might prefer to know
+      exactly <emphasis>what</emphasis> changes we've made to it.  To
+      do this, we use the <command role="hg-cmd">hg diff</command>
+      command.</para>
+
+    &interaction.tour.diff;
+
+  </sect1>
+  <sect1>
+    <title>Recording changes in a new changeset</title>
+
+    <para>We can modify files, build and test our changes, and use
+      <command role="hg-cmd">hg status</command> and <command
+	role="hg-cmd">hg diff</command> to review our changes, until
+      we're satisfied with what we've done and arrive at a natural
+      stopping point where we want to record our work in a new
+      changeset.</para>
+
+    <para>The <command role="hg-cmd">hg commit</command> command lets
+      us create a new changeset; we'll usually refer to this as
+      <quote>making a commit</quote> or
+      <quote>committing</quote>.</para>
+
+    <sect2>
+      <title>Setting up a username</title>
+
+      <para>When you try to run <command role="hg-cmd">hg
+	  commit</command> for the first time, it is not guaranteed to
+	succeed.  Mercurial records your name and address with each
+	change that you commit, so that you and others will later be
+	able to tell who made each change.  Mercurial tries to
+	automatically figure out a sensible username to commit the
+	change with.  It will attempt each of the following methods,
+	in order:</para>
+      <orderedlist>
+	<listitem><para>If you specify a <option
+	      role="hg-opt-commit">-u</option> option to the <command
+	      role="hg-cmd">hg commit</command> command on the command
+	    line, followed by a username, this is always given the
+	    highest precedence.</para></listitem>
+	<listitem><para>If you have set the <envar>HGUSER</envar>
+	    environment variable, this is checked
+	    next.</para></listitem>
+	<listitem><para>If you create a file in your home directory
+	    called <filename role="special">.hgrc</filename>, with a
+	    <envar role="rc-item-ui">username</envar> entry, that will
+	    be used next.  To see what the contents of this file
+	    should look like, refer to section <xref
+	      linkend="sec:tour-basic:username"/>
+	    below.</para></listitem>
+	<listitem><para>If you have set the <envar>EMAIL</envar>
+	    environment variable, this will be used
+	    next.</para></listitem>
+	<listitem><para>Mercurial will query your system to find out
+	    your local user name and host name, and construct a
+	    username from these components. Since this often results
+	    in a username that is not very useful, it will print a
+	    warning if it has to do
+	    this.</para></listitem>
+      </orderedlist>
+      <para>If all of these mechanisms fail, Mercurial will
+	  fail, printing an error message.  In this case, it will not
+	  let you commit until you set up a
+	  username.</para>
+      <para>You should think of the <envar>HGUSER</envar> environment
+	variable and the <option role="hg-opt-commit">-u</option>
+	option to the <command role="hg-cmd">hg commit</command>
+	command as ways to <emphasis>override</emphasis> Mercurial's
+	default selection of username.  For normal use, the simplest
+	and most robust way to set a username for yourself is by
+	creating a <filename role="special">.hgrc</filename> file; see
+	below for details.</para>
+      <sect3 id="sec:tour-basic:username">
+	<title>Creating a Mercurial configuration file</title>
+
+	<para>To set a user name, use your favourite editor
+	    to create a file called <filename
+	      role="special">.hgrc</filename> in your home directory.
+	    Mercurial will use this file to look up your personalised
+	    configuration settings.  The initial contents of your
+	    <filename role="special">.hgrc</filename> should look like
+	    this.</para>
+	<programlisting># This is a Mercurial configuration file.
+[ui]
+username = Firstname Lastname
+&lt;email.address@domain.net&gt;</programlisting>
+
+	<para>The <quote><literal>[ui]</literal></quote> line begins a
+	  <emphasis>section</emphasis> of the config file, so you can
+	  read the <quote><literal>username = ...</literal></quote>
+	  line as meaning <quote>set the value of the
+	    <literal>username</literal> item in the
+	    <literal>ui</literal> section</quote>. A section continues
+	  until a new section begins, or the end of the file.
+	  Mercurial ignores empty lines and treats any text from
+	  <quote><literal>#</literal></quote> to the end of a line as
+	  a comment.</para>
+      </sect3>
+
+      <sect3>
+	<title>Choosing a user name</title>
+
+	<para>You can use any text you like as the value of
+	    the <literal>username</literal> config item, since this
+	    information is for reading by other people, but for
+	    interpreting by Mercurial.  The convention that most
+	    people follow is to use their name and email address, as
+	    in the example above.</para>
+	<note>
+	  <para>Mercurial's built-in web server obfuscates
+	      email addresses, to make it more difficult for the email
+	      harvesting tools that spammers use. This reduces the
+	      likelihood that you'll start receiving more junk email
+	      if you publish a Mercurial repository on the
+	      web.</para></note>
+
+      </sect3>
+    </sect2>
+    <sect2>
+      <title>Writing a commit message</title>
+
+      <para>When we commit a change, Mercurial drops us into
+	  a text editor, to enter a message that will describe the
+	  modifications we've made in this changeset.  This is called
+	  the <emphasis>commit message</emphasis>.  It will be a
+	  record for readers of what we did and why, and it will be
+	  printed by <command role="hg-cmd">hg log</command> after
+	  we've finished committing.</para>
+
+       &interaction.tour.commit;
+
+      <para>The editor that the <command role="hg-cmd">hg
+	    commit</command> command drops us into will contain an
+	  empty line, followed by a number of lines starting with
+	  <quote><literal>HG:</literal></quote>.</para>
+
+    <programlisting>XXX fix this XXX</programlisting>
+
+      <para>Mercurial ignores the lines that start with
+	  <quote><literal>HG:</literal></quote>; it uses them only to
+	  tell us which files it's recording changes to.  Modifying or
+	  deleting these lines has no effect.</para>
+    </sect2>
+    <sect2>