1.1 --- a/en/00book.xml	Wed Mar 18 00:08:22 2009 -0700
     1.2 +++ b/en/00book.xml	Thu Mar 19 20:54:12 2009 -0700
     1.3 @@ -7,20 +7,20 @@
     1.4  
     1.5  <!-- Chapters. -->
     1.6  
     1.7 -<!ENTITY ch01     SYSTEM "ch01-intro.xml">
     1.8 -<!ENTITY ch02     SYSTEM "ch02-tour-basic.xml">
     1.9 -<!ENTITY ch03     SYSTEM "ch03-tour-merge.xml">
    1.10 -<!ENTITY ch04     SYSTEM "ch04-concepts.xml">
    1.11 -<!ENTITY ch05     SYSTEM "ch05-daily.xml">
    1.12 -<!ENTITY ch06     SYSTEM "ch06-collab.xml">
    1.13 -<!ENTITY ch07     SYSTEM "ch07-filenames.xml">
    1.14 -<!ENTITY ch08     SYSTEM "ch08-branch.xml">
    1.15 -<!ENTITY ch09     SYSTEM "ch09-undo.xml">
    1.16 -<!ENTITY ch10     SYSTEM "ch10-hook.xml">
    1.17 -<!ENTITY ch11     SYSTEM "ch11-template.xml">
    1.18 -<!ENTITY ch12     SYSTEM "ch12-mq.xml">
    1.19 -<!ENTITY ch13     SYSTEM "ch13-mq-collab.xml">
    1.20 -<!ENTITY ch14     SYSTEM "ch14-hgext.xml">
    1.21 +<!ENTITY ch00     SYSTEM "ch00-preface.xml">
    1.22 +<!ENTITY ch01     SYSTEM "ch01-tour-basic.xml">
    1.23 +<!ENTITY ch02     SYSTEM "ch02-tour-merge.xml">
    1.24 +<!ENTITY ch03     SYSTEM "ch03-concepts.xml">
    1.25 +<!ENTITY ch04     SYSTEM "ch04-daily.xml">
    1.26 +<!ENTITY ch05     SYSTEM "ch05-collab.xml">
    1.27 +<!ENTITY ch06     SYSTEM "ch06-filenames.xml">
    1.28 +<!ENTITY ch07     SYSTEM "ch07-branch.xml">
    1.29 +<!ENTITY ch08     SYSTEM "ch08-undo.xml">
    1.30 +<!ENTITY ch09     SYSTEM "ch09-hook.xml">
    1.31 +<!ENTITY ch10     SYSTEM "ch10-template.xml">
    1.32 +<!ENTITY ch11     SYSTEM "ch11-mq.xml">
    1.33 +<!ENTITY ch12     SYSTEM "ch12-mq-collab.xml">
    1.34 +<!ENTITY ch13     SYSTEM "ch13-hgext.xml">
    1.35  <!ENTITY appA     SYSTEM "appA-cmdref.xml">
    1.36  <!ENTITY appB     SYSTEM "appB-mq-ref.xml">
    1.37  <!ENTITY appC     SYSTEM "appC-srcinstall.xml">
    1.38 @@ -74,7 +74,6 @@
    1.39    &ch11;
    1.40    &ch12;
    1.41    &ch13;
    1.42 -  &ch14;
    1.43    <!-- &appA; -->
    1.44    &appB;
    1.45    &appC;

     2.1 --- a/en/ch00-preface.xml	Wed Mar 18 00:08:22 2009 -0700
     2.2 +++ b/en/ch00-preface.xml	Thu Mar 19 20:54:12 2009 -0700
     2.3 @@ -3,23 +3,139 @@
     2.4  <preface id="chap:preface">
     2.5    <title>Preface</title>
     2.6  
     2.7 -  <para>Distributed revision control is a relatively new territory,
     2.8 -    and has thus far grown due to people's willingness to strike out
     2.9 -    into ill-charted territory.</para>
    2.10 -
    2.11 -  <para>I am writing a book about distributed revision control because
    2.12 -    I believe that it is an important subject that deserves a field
    2.13 -    guide. I chose to write about Mercurial because it is the easiest
    2.14 -    tool to learn the terrain with, and yet it scales to the demands
    2.15 -    of real, challenging environments where many other revision
    2.16 -    control tools fail.</para>
    2.17 +  <sect1>
    2.18 +    <title>Why revision control? Why Mercurial?</title>
    2.19 +
    2.20 +    <para>Revision control is the process of managing multiple
    2.21 +      versions of a piece of information.  In its simplest form, this
    2.22 +      is something that many people do by hand: every time you modify
    2.23 +      a file, save it under a new name that contains a number, each
    2.24 +      one higher than the number of the preceding version.</para>
    2.25 +
    2.26 +    <para>Manually managing multiple versions of even a single file is
    2.27 +      an error-prone task, though, so software tools to help automate
    2.28 +      this process have long been available.  The earliest automated
    2.29 +      revision control tools were intended to help a single user to
    2.30 +      manage revisions of a single file.  Over the past few decades,
    2.31 +      the scope of revision control tools has expanded greatly; they
    2.32 +      now manage multiple files, and help multiple people to work
    2.33 +      together.  The best modern revision control tools have no
    2.34 +      problem coping with thousands of people working together on
    2.35 +      projects that consist of hundreds of thousands of files.</para>
    2.36 +
    2.37 +    <para>The arrival of distributed revision control is relatively
    2.38 +      recent, and so far this new field has grown due to people's
    2.39 +      willingness to explore ill-charted territory.</para>
    2.40 +
    2.41 +    <para>I am writing a book about distributed revision control
    2.42 +      because I believe that it is an important subject that deserves
    2.43 +      a field guide. I chose to write about Mercurial because it is
    2.44 +      the easiest tool to learn the terrain with, and yet it scales to
    2.45 +      the demands of real, challenging environments where many other
    2.46 +      revision control tools buckle.</para>
    2.47 +
    2.48 +    <sect2>
    2.49 +      <title>Why use revision control?</title>
    2.50 +
    2.51 +      <para>There are a number of reasons why you or your team might
    2.52 +	want to use an automated revision control tool for a
    2.53 +	project.</para>
    2.54 +
    2.55 +      <itemizedlist>
    2.56 +	<listitem><para>It will track the history and evolution of
    2.57 +	    your project, so you don't have to.  For every change,
    2.58 +	    you'll have a log of <emphasis>who</emphasis> made it;
    2.59 +	    <emphasis>why</emphasis> they made it;
    2.60 +	    <emphasis>when</emphasis> they made it; and
    2.61 +	    <emphasis>what</emphasis> the change
    2.62 +	    was.</para></listitem>
    2.63 +	<listitem><para>When you're working with other people,
    2.64 +	    revision control software makes it easier for you to
    2.65 +	    collaborate.  For example, when people more or less
    2.66 +	    simultaneously make potentially incompatible changes, the
    2.67 +	    software will help you to identify and resolve those
    2.68 +	    conflicts.</para></listitem>
    2.69 +	<listitem><para>It can help you to recover from mistakes.  If
    2.70 +	    you make a change that later turns out to be in error, you
    2.71 +	    can revert to an earlier version of one or more files.  In
    2.72 +	    fact, a <emphasis>really</emphasis> good revision control
    2.73 +	    tool will even help you to efficiently figure out exactly
    2.74 +	    when a problem was introduced (see section <xref
    2.75 +	      linkend="sec:undo:bisect"/> for details).</para></listitem>
    2.76 +	<listitem><para>It will help you to work simultaneously on,
    2.77 +	    and manage the drift between, multiple versions of your
    2.78 +	    project.</para></listitem>
    2.79 +      </itemizedlist>
    2.80 +
    2.81 +      <para>Most of these reasons are equally valid---at least in
    2.82 +	theory---whether you're working on a project by yourself, or
    2.83 +	with a hundred other people.</para>
    2.84 +
    2.85 +      <para>A key question about the practicality of revision control
    2.86 +	at these two different scales (<quote>lone hacker</quote> and
    2.87 +	<quote>huge team</quote>) is how its
    2.88 +	<emphasis>benefits</emphasis> compare to its
    2.89 +	<emphasis>costs</emphasis>.  A revision control tool that's
    2.90 +	difficult to understand or use is going to impose a high
    2.91 +	cost.</para>
    2.92 +
    2.93 +      <para>A five-hundred-person project is likely to collapse under
    2.94 +	its own weight almost immediately without a revision control
    2.95 +	tool and process. In this case, the cost of using revision
    2.96 +	control might hardly seem worth considering, since
    2.97 +	<emphasis>without</emphasis> it, failure is almost
    2.98 +	guaranteed.</para>
    2.99 +
   2.100 +      <para>On the other hand, a one-person <quote>quick hack</quote>
   2.101 +	might seem like a poor place to use a revision control tool,
   2.102 +	because surely the cost of using one must be close to the
   2.103 +	overall cost of the project.  Right?</para>
   2.104 +
   2.105 +      <para>Mercurial uniquely supports <emphasis>both</emphasis> of
   2.106 +	these scales of development.  You can learn the basics in just
   2.107 +	a few minutes, and due to its low overhead, you can apply
   2.108 +	revision control to the smallest of projects with ease.  Its
   2.109 +	simplicity means you won't have a lot of abstruse concepts or
   2.110 +	command sequences competing for mental space with whatever
   2.111 +	you're <emphasis>really</emphasis> trying to do.  At the same
   2.112 +	time, Mercurial's high performance and peer-to-peer nature let
   2.113 +	you scale painlessly to handle large projects.</para>
   2.114 +
   2.115 +      <para>No revision control tool can rescue a poorly run project,
   2.116 +	but a good choice of tools can make a huge difference to the
   2.117 +	fluidity with which you can work on a project.</para>
   2.118 +
   2.119 +    </sect2>
   2.120 +
   2.121 +    <sect2>
   2.122 +      <title>The many names of revision control</title>
   2.123 +
   2.124 +      <para>Revision control is a diverse field, so much so that it is
   2.125 +	referred to by many names and acronyms.  Here are a few of the
   2.126 +	more common variations you'll encounter:</para>
   2.127 +      <itemizedlist>
   2.128 +	<listitem><para>Revision control (RCS)</para></listitem>
   2.129 +	<listitem><para>Software configuration management (SCM), or
   2.130 +	    configuration management</para></listitem>
   2.131 +	<listitem><para>Source code management</para></listitem>
   2.132 +	<listitem><para>Source code control, or source
   2.133 +	    control</para></listitem>
   2.134 +	<listitem><para>Version control
   2.135 +	    (VCS)</para></listitem></itemizedlist>
   2.136 +      <para>Some people claim that these terms actually have different
   2.137 +	meanings, but in practice they overlap so much that there's no
   2.138 +	agreed or even useful way to tease them apart.</para>
   2.139 +
   2.140 +    </sect2>
   2.141 +  </sect1>
   2.142  
   2.143    <sect1>
   2.144      <title>This book is a work in progress</title>
   2.145  
   2.146      <para>I am releasing this book while I am still writing it, in the
   2.147 -      hope that it will prove useful to others.  I also hope that
   2.148 -      readers will contribute as they see fit.</para>
   2.149 +      hope that it will prove useful to others.  I am writing under an
   2.150 +      open license in the hope that you, my readers, will contribute
   2.151 +      feedback and perhaps content of your own.</para>
   2.152  
   2.153    </sect1>
   2.154    <sect1>
   2.155 @@ -59,8 +175,567 @@
   2.156        seeing is consistent and reproducible.</para>
   2.157  
   2.158    </sect1>
   2.159 -  <sect1>
   2.160 -    <title>Colophon---this book is Free</title>
   2.161 +
   2.162 +  <sect1>
   2.163 +    <title>Trends in the field</title>
   2.164 +
   2.165 +    <para>There has been an unmistakable trend in the development and
   2.166 +      use of revision control tools over the past four decades, as
   2.167 +      people have become familiar with the capabilities of their tools
   2.168 +      and constrained by their limitations.</para>
   2.169 +
   2.170 +    <para>The first generation began by managing single files on
   2.171 +      individual computers.  Although these tools represented a huge
   2.172 +      advance over ad-hoc manual revision control, their locking model
   2.173 +      and reliance on a single computer limited them to small,
   2.174 +      tightly-knit teams.</para>
   2.175 +
   2.176 +    <para>The second generation loosened these constraints by moving
   2.177 +      to network-centered architectures, and managing entire projects
   2.178 +      at a time.  As projects grew larger, they ran into new problems.
   2.179 +      With clients needing to talk to servers very frequently, server
   2.180 +      scaling became an issue for large projects.  An unreliable
   2.181 +      network connection could prevent remote users from being able to
   2.182 +      talk to the server at all.  As open source projects started
   2.183 +      making read-only access available anonymously to anyone, people
   2.184 +      without commit privileges found that they could not use the
   2.185 +      tools to interact with a project in a natural way, as they could
   2.186 +      not record their changes.</para>
   2.187 +
   2.188 +    <para>The current generation of revision control tools is
   2.189 +      peer-to-peer in nature.  All of these systems have dropped the
   2.190 +      dependency on a single central server, and allow people to
   2.191 +      distribute their revision control data to where it's actually
   2.192 +      needed.  Collaboration over the Internet has moved from
   2.193 +      constrained by technology to a matter of choice and consensus.
   2.194 +      Modern tools can operate offline indefinitely and autonomously,
   2.195 +      with a network connection only needed when syncing changes with
   2.196 +      another repository.</para>
   2.197 +
   2.198 +  </sect1>
   2.199 +  <sect1>
   2.200 +    <title>A few of the advantages of distributed revision
   2.201 +      control</title>
   2.202 +
   2.203 +    <para>Even though distributed revision control tools have for
   2.204 +      several years been as robust and usable as their
   2.205 +      previous-generation counterparts, people using older tools have
   2.206 +      not yet necessarily woken up to their advantages.  There are a
   2.207 +      number of ways in which distributed tools shine relative to
   2.208 +      centralised ones.</para>
   2.209 +
   2.210 +    <para>For an individual developer, distributed tools are almost
   2.211 +      always much faster than centralised tools.  This is for a simple
   2.212 +      reason: a centralised tool needs to talk over the network for
   2.213 +      many common operations, because most metadata is stored in a
   2.214 +      single copy on the central server.  A distributed tool stores
   2.215 +      all of its metadata locally.  All else being equal, talking over
   2.216 +      the network adds overhead to a centralised tool.  Don't
   2.217 +      underestimate the value of a snappy, responsive tool: you're
   2.218 +      going to spend a lot of time interacting with your revision
   2.219 +      control software.</para>
   2.220 +
   2.221 +    <para>Distributed tools are indifferent to the vagaries of your
   2.222 +      server infrastructure, again because they replicate metadata to
   2.223 +      so many locations.  If you use a centralised system and your
   2.224 +      server catches fire, you'd better hope that your backup media
   2.225 +      are reliable, and that your last backup was recent and actually
   2.226 +      worked.  With a distributed tool, you have many backups
   2.227 +      available on every contributor's computer.</para>
   2.228 +
   2.229 +    <para>The reliability of your network will affect distributed
   2.230 +      tools far less than it will centralised tools.  You can't even
   2.231 +      use a centralised tool without a network connection, except for
   2.232 +      a few highly constrained commands.  With a distributed tool, if
   2.233 +      your network connection goes down while you're working, you may
   2.234 +      not even notice.  The only thing you won't be able to do is talk
   2.235 +      to repositories on other computers, something that is relatively
   2.236 +      rare compared with local operations.  If you have a far-flung
   2.237 +      team of collaborators, this may be significant.</para>
   2.238 +
   2.239 +    <sect2>
   2.240 +      <title>Advantages for open source projects</title>
   2.241 +
   2.242 +      <para>If you take a shine to an open source project and decide
   2.243 +	that you would like to start hacking on it, and that project
   2.244 +	uses a distributed revision control tool, you are at once a
   2.245 +	peer with the people who consider themselves the
   2.246 +	<quote>core</quote> of that project.  If they publish their
   2.247 +	repositories, you can immediately copy their project history,
   2.248 +	start making changes, and record your work, using the same
   2.249 +	tools in the same ways as insiders.  By contrast, with a
   2.250 +	centralised tool, you must use the software in a <quote>read
   2.251 +	  only</quote> mode unless someone grants you permission to
   2.252 +	commit changes to their central server.  Until then, you won't
   2.253 +	be able to record changes, and your local modifications will
   2.254 +	be at risk of corruption any time you try to update your
   2.255 +	client's view of the repository.</para>
   2.256 +
   2.257 +      <sect3>
   2.258 +	<title>The forking non-problem</title>
   2.259 +
   2.260 +	<para>It has been suggested that distributed revision control
   2.261 +	  tools pose some sort of risk to open source projects because
   2.262 +	  they make it easy to <quote>fork</quote> the development of
   2.263 +	  a project.  A fork happens when there are differences in
   2.264 +	  opinion or attitude between groups of developers that cause
   2.265 +	  them to decide that they can't work together any longer.
   2.266 +	  Each side takes a more or less complete copy of the
   2.267 +	  project's source code, and goes off in its own
   2.268 +	  direction.</para>
   2.269 +
   2.270 +	<para>Sometimes the camps in a fork decide to reconcile their
   2.271 +	  differences. With a centralised revision control system, the
   2.272 +	  <emphasis>technical</emphasis> process of reconciliation is
   2.273 +	  painful, and has to be performed largely by hand.  You have
   2.274 +	  to decide whose revision history is going to
   2.275 +	  <quote>win</quote>, and graft the other team's changes into
   2.276 +	  the tree somehow. This usually loses some or all of one
   2.277 +	  side's revision history.</para>
   2.278 +
   2.279 +	<para>What distributed tools do with respect to forking is
   2.280 +	  they make forking the <emphasis>only</emphasis> way to
   2.281 +	  develop a project.  Every single change that you make is
   2.282 +	  potentially a fork point.  The great strength of this
   2.283 +	  approach is that a distributed revision control tool has to
   2.284 +	  be really good at <emphasis>merging</emphasis> forks,
   2.285 +	  because forks are absolutely fundamental: they happen all
   2.286 +	  the time.</para>
   2.287 +
   2.288 +	<para>If every piece of work that everybody does, all the
   2.289 +	  time, is framed in terms of forking and merging, then what
   2.290 +	  the open source world refers to as a <quote>fork</quote>
   2.291 +	  becomes <emphasis>purely</emphasis> a social issue.  If
   2.292 +	  anything, distributed tools <emphasis>lower</emphasis> the
   2.293 +	  likelihood of a fork:</para>
   2.294 +	<itemizedlist>
   2.295 +	  <listitem><para>They eliminate the social distinction that
   2.296 +	      centralised tools impose: that between insiders (people
   2.297 +	      with commit access) and outsiders (people
   2.298 +	      without).</para></listitem>
   2.299 +	  <listitem><para>They make it easier to reconcile after a
   2.300 +	      social fork, because all that's involved from the
   2.301 +	      perspective of the revision control software is just
   2.302 +	      another merge.</para></listitem></itemizedlist>
   2.303 +
   2.304 +	<para>Some people resist distributed tools because they want
   2.305 +	  to retain tight control over their projects, and they
   2.306 +	  believe that centralised tools give them this control.
   2.307 +	  However, if you're of this belief, and you publish your CVS
   2.308 +	  or Subversion repositories publicly, there are plenty of
   2.309 +	  tools available that can pull out your entire project's
   2.310 +	  history (albeit slowly) and recreate it somewhere that you
   2.311 +	  don't control.  So while your control in this case is
   2.312 +	  illusory, you are forgoing the ability to fluidly
   2.313 +	  collaborate with whatever people feel compelled to mirror
   2.314 +	  and fork your history.</para>
   2.315 +
   2.316 +      </sect3>
   2.317 +    </sect2>
   2.318 +    <sect2>
   2.319 +      <title>Advantages for commercial projects</title>
   2.320 +
   2.321 +      <para>Many commercial projects are undertaken by teams that are
   2.322 +	scattered across the globe.  Contributors who are far from a
   2.323 +	central server will see slower command execution and perhaps
   2.324 +	less reliability.  Commercial revision control systems attempt
   2.325 +	to ameliorate these problems with remote-site replication
   2.326 +	add-ons that are typically expensive to buy and cantankerous
   2.327 +	to administer.  A distributed system doesn't suffer from these
   2.328 +	problems in the first place.  Better yet, you can easily set
   2.329 +	up multiple authoritative servers, say one per site, so that
   2.330 +	there's no redundant communication between repositories over
   2.331 +	expensive long-haul network links.</para>
   2.332 +
   2.333 +      <para>Centralised revision control systems tend to have
   2.334 +	relatively low scalability.  It's not unusual for an expensive
   2.335 +	centralised system to fall over under the combined load of
   2.336 +	just a few dozen concurrent users.  Once again, the typical
   2.337 +	response tends to be an expensive and clunky replication
   2.338 +	facility.  Since the load on a central server---if you have
   2.339 +	one at all---is many times lower with a distributed tool
   2.340 +	(because all of the data is replicated everywhere), a single
   2.341 +	cheap server can handle the needs of a much larger team, and
   2.342 +	replication to balance load becomes a simple matter of
   2.343 +	scripting.</para>
   2.344 +
   2.345 +      <para>If you have an employee in the field, troubleshooting a
   2.346 +	problem at a customer's site, they'll benefit from distributed
   2.347 +	revision control. The tool will let them generate custom
   2.348 +	builds, try different fixes in isolation from each other, and
   2.349 +	search efficiently through history for the sources of bugs and
   2.350 +	regressions in the customer's environment, all without needing
   2.351 +	to connect to your company's network.</para>
   2.352 +
   2.353 +    </sect2>
   2.354 +  </sect1>
   2.355 +  <sect1>
   2.356 +    <title>Why choose Mercurial?</title>
   2.357 +
   2.358 +    <para>Mercurial has a unique set of properties that make it a
   2.359 +      particularly good choice as a revision control system.</para>
   2.360 +    <itemizedlist>
   2.361 +      <listitem><para>It is easy to learn and use.</para></listitem>
   2.362 +      <listitem><para>It is lightweight.</para></listitem>
   2.363 +      <listitem><para>It scales excellently.</para></listitem>
   2.364 +      <listitem><para>It is easy to
   2.365 +	  customise.</para></listitem></itemizedlist>
   2.366 +
   2.367 +    <para>If you are at all familiar with revision control systems,
   2.368 +      you should be able to get up and running with Mercurial in less
   2.369 +      than five minutes.  Even if not, it will take no more than a few
   2.370 +      minutes longer.  Mercurial's command and feature sets are
   2.371 +      generally uniform and consistent, so you can keep track of a few
   2.372 +      general rules instead of a host of exceptions.</para>
   2.373 +
   2.374 +    <para>On a small project, you can start working with Mercurial in
   2.375 +      moments. Creating new changes and branches; transferring changes
   2.376 +      around (whether locally or over a network); and history and
   2.377 +      status operations are all fast.  Mercurial attempts to stay
   2.378 +      nimble and largely out of your way by combining low cognitive
   2.379 +      overhead with blazingly fast operations.</para>
   2.380 +
   2.381 +    <para>The usefulness of Mercurial is not limited to small
   2.382 +      projects: it is used by projects with hundreds to thousands of
   2.383 +      contributors, each containing tens of thousands of files and
   2.384 +      hundreds of megabytes of source code.</para>
   2.385 +
   2.386 +    <para>If the core functionality of Mercurial is not enough for
   2.387 +      you, it's easy to build on.  Mercurial is well suited to
   2.388 +      scripting tasks, and its clean internals and implementation in
   2.389 +      Python make it easy to add features in the form of extensions.
   2.390 +      There are a number of popular and useful extensions already
   2.391 +      available, ranging from helping to identify bugs to improving
   2.392 +      performance.</para>
   2.393 +
   2.394 +  </sect1>
   2.395 +  <sect1>
   2.396 +    <title>Mercurial compared with other tools</title>
   2.397 +
   2.398 +    <para>Before you read on, please understand that this section
   2.399 +      necessarily reflects my own experiences, interests, and (dare I
   2.400 +      say it) biases.  I have used every one of the revision control
   2.401 +      tools listed below, in most cases for several years at a
   2.402 +      time.</para>
   2.403 +
   2.404 +
   2.405 +    <sect2>
   2.406 +      <title>Subversion</title>
   2.407 +
   2.408 +      <para>Subversion is a popular revision control tool, developed
   2.409 +	to replace CVS.  It has a centralised client/server
   2.410 +	architecture.</para>
   2.411 +
   2.412 +      <para>Subversion and Mercurial have similarly named commands for
   2.413 +	performing the same operations, so if you're familiar with
   2.414 +	one, it is easy to learn to use the other.  Both tools are
   2.415 +	portable to all popular operating systems.</para>
   2.416 +
   2.417 +      <para>Prior to version 1.5, Subversion had no useful support for
   2.418 +	merges. At the time of writing, its merge tracking capability
   2.419 +	is new, and known to be <ulink
   2.420 +	  url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword">complicated 
   2.421 +	  and buggy</ulink>.</para>
   2.422 +
   2.423 +      <para>Mercurial has a substantial performance advantage over
   2.424 +	Subversion on every revision control operation I have
   2.425 +	benchmarked.  I have measured its advantage as ranging from a
   2.426 +	factor of two to a factor of six when compared with Subversion
   2.427 +	1.4.3's <emphasis>ra_local</emphasis> file store, which is the
   2.428 +	fastest access method available.  In more realistic
   2.429 +	deployments involving a network-based store, Subversion will
   2.430 +	be at a substantially larger disadvantage.  Because many
   2.431 +	Subversion commands must talk to the server and Subversion
   2.432 +	does not have useful replication facilities, server capacity
   2.433 +	and network bandwidth become bottlenecks for modestly large
   2.434 +	projects.</para>
   2.435 +
   2.436 +      <para>Additionally, Subversion incurs substantial storage
   2.437 +	overhead to avoid network transactions for a few common
   2.438 +	operations, such as finding modified files
   2.439 +	(<literal>status</literal>) and displaying modifications
   2.440 +	against the current revision (<literal>diff</literal>).  As a
   2.441 +	result, a Subversion working copy is often the same size as,
   2.442 +	or larger than, a Mercurial repository and working directory,
   2.443 +	even though the Mercurial repository contains a complete
   2.444 +	history of the project.</para>
   2.445 +
   2.446 +      <para>Subversion is widely supported by third party tools.
   2.447 +	Mercurial currently lags considerably in this area.  This gap
   2.448 +	is closing, however, and indeed some of Mercurial's GUI tools
   2.449 +	now outshine their Subversion equivalents.  Like Mercurial,
   2.450 +	Subversion has an excellent user manual.</para>
   2.451 +
   2.452 +      <para>Because Subversion doesn't store revision history on the
   2.453 +	client, it is well suited to managing projects that deal with
   2.454 +	lots of large, opaque binary files.  If you check in fifty
   2.455 +	revisions to an incompressible 10MB file, Subversion's
   2.456 +	client-side space usage stays constant The space used by any
   2.457 +	distributed SCM will grow rapidly in proportion to the number
   2.458 +	of revisions, because the differences between each revision
   2.459 +	are large.</para>
   2.460 +
   2.461 +      <para>In addition, it's often difficult or, more usually,
   2.462 +	impossible to merge different versions of a binary file.
   2.463 +	Subversion's ability to let a user lock a file, so that they
   2.464 +	temporarily have the exclusive right to commit changes to it,
   2.465 +	can be a significant advantage to a project where binary files
   2.466 +	are widely used.</para>
   2.467 +
   2.468 +      <para>Mercurial can import revision history from a Subversion
   2.469 +	repository. It can also export revision history to a
   2.470 +	Subversion repository.  This makes it easy to <quote>test the
   2.471 +	  waters</quote> and use Mercurial and Subversion in parallel
   2.472 +	before deciding to switch.  History conversion is incremental,
   2.473 +	so you can perform an initial conversion, then small
   2.474 +	additional conversions afterwards to bring in new
   2.475 +	changes.</para>
   2.476 +
   2.477 +
   2.478 +    </sect2>
   2.479 +    <sect2>
   2.480 +      <title>Git</title>
   2.481 +
   2.482 +      <para>Git is a distributed revision control tool that was
   2.483 +	developed for managing the Linux kernel source tree.  Like
   2.484 +	Mercurial, its early design was somewhat influenced by
   2.485 +	Monotone.</para>
   2.486 +
   2.487 +      <para>Git has a very large command set, with version 1.5.0
   2.488 +	providing 139 individual commands.  It has something of a
   2.489 +	reputation for being difficult to learn.  Compared to Git,
   2.490 +	Mercurial has a strong focus on simplicity.</para>
   2.491 +
   2.492 +      <para>In terms of performance, Git is extremely fast.  In
   2.493 +	several cases, it is faster than Mercurial, at least on Linux,
   2.494 +	while Mercurial performs better on other operations.  However,
   2.495 +	on Windows, the performance and general level of support that
   2.496 +	Git provides is, at the time of writing, far behind that of
   2.497 +	Mercurial.</para>
   2.498 +
   2.499 +      <para>While a Mercurial repository needs no maintenance, a Git
   2.500 +	repository requires frequent manual <quote>repacks</quote> of
   2.501 +	its metadata.  Without these, performance degrades, while
   2.502 +	space usage grows rapidly.  A server that contains many Git
   2.503 +	repositories that are not rigorously and frequently repacked
   2.504 +	will become heavily disk-bound during backups, and there have
   2.505 +	been instances of daily backups taking far longer than 24
   2.506 +	hours as a result.  A freshly packed Git repository is
   2.507 +	slightly smaller than a Mercurial repository, but an unpacked
   2.508 +	repository is several orders of magnitude larger.</para>
   2.509 +
   2.510 +      <para>The core of Git is written in C.  Many Git commands are
   2.511 +	implemented as shell or Perl scripts, and the quality of these
   2.512 +	scripts varies widely. I have encountered several instances
   2.513 +	where scripts charged along blindly in the presence of errors
   2.514 +	that should have been fatal.</para>
   2.515 +
   2.516 +      <para>Mercurial can import revision history from a Git
   2.517 +	repository.</para>
   2.518 +
   2.519 +
   2.520 +    </sect2>
   2.521 +    <sect2>
   2.522 +      <title>CVS</title>
   2.523 +
   2.524 +      <para>CVS is probably the most widely used revision control tool
   2.525 +	in the world.  Due to its age and internal untidiness, it has
   2.526 +	been only lightly maintained for many years.</para>
   2.527 +
   2.528 +      <para>It has a centralised client/server architecture.  It does
   2.529 +	not group related file changes into atomic commits, making it
   2.530 +	easy for people to <quote>break the build</quote>: one person
   2.531 +	can successfully commit part of a change and then be blocked
   2.532 +	by the need for a merge, causing other people to see only a
   2.533 +	portion of the work they intended to do.  This also affects
   2.534 +	how you work with project history.  If you want to see all of
   2.535 +	the modifications someone made as part of a task, you will
   2.536 +	need to manually inspect the descriptions and timestamps of
   2.537 +	the changes made to each file involved (if you even know what
   2.538 +	those files were).</para>
   2.539 +
   2.540 +      <para>CVS has a muddled notion of tags and branches that I will
   2.541 +	not attempt to even describe.  It does not support renaming of
   2.542 +	files or directories well, making it easy to corrupt a
   2.543 +	repository.  It has almost no internal consistency checking
   2.544 +	capabilities, so it is usually not even possible to tell
   2.545 +	whether or how a repository is corrupt.  I would not recommend
   2.546 +	CVS for any project, existing or new.</para>
   2.547 +
   2.548 +      <para>Mercurial can import CVS revision history.  However, there
   2.549 +	are a few caveats that apply; these are true of every other
   2.550 +	revision control tool's CVS importer, too.  Due to CVS's lack
   2.551 +	of atomic changes and unversioned filesystem hierarchy, it is
   2.552 +	not possible to reconstruct CVS history completely accurately;
   2.553 +	some guesswork is involved, and renames will usually not show
   2.554 +	up.  Because a lot of advanced CVS administration has to be
   2.555 +	done by hand and is hence error-prone, it's common for CVS
   2.556 +	importers to run into multiple problems with corrupted
   2.557 +	repositories (completely bogus revision timestamps and files
   2.558 +	that have remained locked for over a decade are just two of
   2.559 +	the less interesting problems I can recall from personal
   2.560 +	experience).</para>
   2.561 +
   2.562 +      <para>Mercurial can import revision history from a CVS
   2.563 +	repository.</para>
   2.564 +
   2.565 +
   2.566 +    </sect2>
   2.567 +    <sect2>
   2.568 +      <title>Commercial tools</title>
   2.569 +
   2.570 +      <para>Perforce has a centralised client/server architecture,
   2.571 +	with no client-side caching of any data.  Unlike modern
   2.572 +	revision control tools, Perforce requires that a user run a
   2.573 +	command to inform the server about every file they intend to
   2.574 +	edit.</para>
   2.575 +
   2.576 +      <para>The performance of Perforce is quite good for small teams,
   2.577 +	but it falls off rapidly as the number of users grows beyond a
   2.578 +	few dozen. Modestly large Perforce installations require the
   2.579 +	deployment of proxies to cope with the load their users
   2.580 +	generate.</para>
   2.581 +
   2.582 +
   2.583 +    </sect2>
   2.584 +    <sect2>
   2.585 +      <title>Choosing a revision control tool</title>
   2.586 +
   2.587 +      <para>With the exception of CVS, all of the tools listed above
   2.588 +	have unique strengths that suit them to particular styles of
   2.589 +	work.  There is no single revision control tool that is best
   2.590 +	in all situations.</para>
   2.591 +
   2.592 +      <para>As an example, Subversion is a good choice for working
   2.593 +	with frequently edited binary files, due to its centralised
   2.594 +	nature and support for file locking.</para>
   2.595 +
   2.596 +      <para>I personally find Mercurial's properties of simplicity,
   2.597 +	performance, and good merge support to be a compelling
   2.598 +	combination that has served me well for several years.</para>
   2.599 +
   2.600 +
   2.601 +    </sect2>
   2.602 +  </sect1>
   2.603 +  <sect1>
   2.604 +    <title>Switching from another tool to Mercurial</title>
   2.605 +
   2.606 +    <para>Mercurial is bundled with an extension named <literal
   2.607 +	role="hg-ext">convert</literal>, which can incrementally
   2.608 +      import revision history from several other revision control
   2.609 +      tools.  By <quote>incremental</quote>, I mean that you can
   2.610 +      convert all of a project's history to date in one go, then rerun
   2.611 +      the conversion later to obtain new changes that happened after
   2.612 +      the initial conversion.</para>
   2.613 +
   2.614 +    <para>The revision control tools supported by <literal
   2.615 +	role="hg-ext">convert</literal> are as follows:</para>
   2.616 +    <itemizedlist>
   2.617 +      <listitem><para>Subversion</para></listitem>
   2.618 +      <listitem><para>CVS</para></listitem>
   2.619 +      <listitem><para>Git</para></listitem>
   2.620 +      <listitem><para>Darcs</para></listitem></itemizedlist>
   2.621 +
   2.622 +    <para>In addition, <literal role="hg-ext">convert</literal> can
   2.623 +      export changes from Mercurial to Subversion.  This makes it
   2.624 +      possible to try Subversion and Mercurial in parallel before
   2.625 +      committing to a switchover, without risking the loss of any
   2.626 +      work.</para>
   2.627 +
   2.628 +    <para>The <command role="hg-ext-convert">convert</command> command
   2.629 +      is easy to use.  Simply point it at the path or URL of the
   2.630 +      source repository, optionally give it the name of the
   2.631 +      destination repository, and it will start working.  After the
   2.632 +      initial conversion, just run the same command again to import
   2.633 +      new changes.</para>
   2.634 +  </sect1>
   2.635 +
   2.636 +  <sect1>
   2.637 +    <title>A short history of revision control</title>
   2.638 +
   2.639 +    <para>The best known of the old-time revision control tools is
   2.640 +      SCCS (Source Code Control System), which Marc Rochkind wrote at
   2.641 +      Bell Labs, in the early 1970s.  SCCS operated on individual
   2.642 +      files, and required every person working on a project to have
   2.643 +      access to a shared workspace on a single system.  Only one
   2.644 +      person could modify a file at any time; arbitration for access
   2.645 +      to files was via locks.  It was common for people to lock files,
   2.646 +      and later forget to unlock them, preventing anyone else from
   2.647 +      modifying those files without the help of an
   2.648 +      administrator.</para>
   2.649 +
   2.650 +    <para>Walter Tichy developed a free alternative to SCCS in the
   2.651 +      early 1980s; he called his program RCS (Revision Control System).
   2.652 +      Like SCCS, RCS required developers to work in a single shared
   2.653 +      workspace, and to lock files to prevent multiple people from
   2.654 +      modifying them simultaneously.</para>
   2.655 +
   2.656 +    <para>Later in the 1980s, Dick Grune used RCS as a building block
   2.657 +      for a set of shell scripts he initially called cmt, but then
   2.658 +      renamed to CVS (Concurrent Versions System).  The big innovation
   2.659 +      of CVS was that it let developers work simultaneously and
   2.660 +      somewhat independently in their own personal workspaces.  The
   2.661 +      personal workspaces prevented developers from stepping on each
   2.662 +      other's toes all the time, as was common with SCCS and RCS. Each
   2.663 +      developer had a copy of every project file, and could modify
   2.664 +      their copies independently.  They had to merge their edits prior
   2.665 +      to committing changes to the central repository.</para>
   2.666 +
   2.667 +    <para>Brian Berliner took Grune's original scripts and rewrote
   2.668 +      them in C, releasing in 1989 the code that has since developed
   2.669 +      into the modern version of CVS.  CVS subsequently acquired the
   2.670 +      ability to operate over a network connection, giving it a
   2.671 +      client/server architecture.  CVS's architecture is centralised;
   2.672 +      only the server has a copy of the history of the project. Client
   2.673 +      workspaces just contain copies of recent versions of the
   2.674 +      project's files, and a little metadata to tell them where the
   2.675 +      server is.  CVS has been enormously successful; it is probably
   2.676 +      the world's most widely used revision control system.</para>
   2.677 +
   2.678 +    <para>In the early 1990s, Sun Microsystems developed an early
   2.679 +      distributed revision control system, called TeamWare.  A
   2.680 +      TeamWare workspace contains a complete copy of the project's
   2.681 +      history.  TeamWare has no notion of a central repository.  (CVS
   2.682 +      relied upon RCS for its history storage; TeamWare used
   2.683 +      SCCS.)</para>
   2.684 +
   2.685 +    <para>As the 1990s progressed, awareness grew of a number of
   2.686 +      problems with CVS.  It records simultaneous changes to multiple
   2.687 +      files individually, instead of grouping them together as a
   2.688 +      single logically atomic operation.  It does not manage its file
   2.689 +      hierarchy well; it is easy to make a mess of a repository by
   2.690 +      renaming files and directories.  Worse, its source code is
   2.691 +      difficult to read and maintain, which made the <quote>pain
   2.692 +	level</quote> of fixing these architectural problems
   2.693 +      prohibitive.</para>
   2.694 +
   2.695 +    <para>In 2001, Jim Blandy and Karl Fogel, two developers who had
   2.696 +      worked on CVS, started a project to replace it with a tool that
   2.697 +      would have a better architecture and cleaner code.  The result,
   2.698 +      Subversion, does not stray from CVS's centralised client/server
   2.699 +      model, but it adds multi-file atomic commits, better namespace
   2.700 +      management, and a number of other features that make it a
   2.701 +      generally better tool than CVS. Since its initial release, it
   2.702 +      has rapidly grown in popularity.</para>
   2.703 +
   2.704 +    <para>More or less simultaneously, Graydon Hoare began working on
   2.705 +      an ambitious distributed revision control system that he named
   2.706 +      Monotone. While Monotone addresses many of CVS's design flaws
   2.707 +      and has a peer-to-peer architecture, it goes beyond earlier (and
   2.708 +      subsequent) revision control tools in a number of innovative
   2.709 +      ways.  It uses cryptographic hashes as identifiers, and has an
   2.710 +      integral notion of <quote>trust</quote> for code from different
   2.711 +      sources.</para>
   2.712 +
   2.713 +    <para>Mercurial began life in 2005.  While a few aspects of its
   2.714 +      design are influenced by Monotone, Mercurial focuses on ease of
   2.715 +      use, high performance, and scalability to very large
   2.716 +      projects.</para>
   2.717 +
   2.718 +  </sect1>
   2.719 +
   2.720 +  <sect1>
   2.721 +    <title>Colophon&emdash;this book is Free</title>
   2.722  
   2.723      <para>This book is licensed under the Open Publication License,
   2.724        and is produced entirely using Free Software tools.  It is

     3.1 --- a/en/ch01-intro.xml	Wed Mar 18 00:08:22 2009 -0700
     3.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.3 @@ -1,680 +0,0 @@
     3.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     3.5 -
     3.6 -<chapter id="chap:intro">
     3.7 -  <?dbhtml filename="introduction.html"?>
     3.8 -  <title>Introduction</title>
     3.9 -
    3.10 -  <sect1>
    3.11 -    <title>About revision control</title>
    3.12 -
    3.13 -    <para>Revision control is the process of managing multiple
    3.14 -      versions of a piece of information.  In its simplest form, this
    3.15 -      is something that many people do by hand: every time you modify
    3.16 -      a file, save it under a new name that contains a number, each
    3.17 -      one higher than the number of the preceding version.</para>
    3.18 -
    3.19 -    <para>Manually managing multiple versions of even a single file is
    3.20 -      an error-prone task, though, so software tools to help automate
    3.21 -      this process have long been available.  The earliest automated
    3.22 -      revision control tools were intended to help a single user to
    3.23 -      manage revisions of a single file.  Over the past few decades,
    3.24 -      the scope of revision control tools has expanded greatly; they
    3.25 -      now manage multiple files, and help multiple people to work
    3.26 -      together.  The best modern revision control tools have no
    3.27 -      problem coping with thousands of people working together on
    3.28 -      projects that consist of hundreds of thousands of files.</para>
    3.29 -
    3.30 -    <sect2>
    3.31 -      <title>Why use revision control?</title>
    3.32 -
    3.33 -      <para>There are a number of reasons why you or your team might
    3.34 -	want to use an automated revision control tool for a
    3.35 -	project.</para>
    3.36 -      <itemizedlist>
    3.37 -	<listitem><para>It will track the history and evolution of
    3.38 -	    your project, so you don't have to.  For every change,
    3.39 -	    you'll have a log of <emphasis>who</emphasis> made it;
    3.40 -	    <emphasis>why</emphasis> they made it;
    3.41 -	    <emphasis>when</emphasis> they made it; and
    3.42 -	    <emphasis>what</emphasis> the change
    3.43 -	    was.</para></listitem>
    3.44 -	<listitem><para>When you're working with other people,
    3.45 -	    revision control software makes it easier for you to
    3.46 -	    collaborate.  For example, when people more or less
    3.47 -	    simultaneously make potentially incompatible changes, the
    3.48 -	    software will help you to identify and resolve those
    3.49 -	    conflicts.</para></listitem>
    3.50 -	<listitem><para>It can help you to recover from mistakes.  If
    3.51 -	    you make a change that later turns out to be in error, you
    3.52 -	    can revert to an earlier version of one or more files.  In
    3.53 -	    fact, a <emphasis>really</emphasis> good revision control
    3.54 -	    tool will even help you to efficiently figure out exactly
    3.55 -	    when a problem was introduced (see section <xref
    3.56 -	      linkend="sec:undo:bisect"/> for details).</para></listitem>
    3.57 -	<listitem><para>It will help you to work simultaneously on,
    3.58 -	    and manage the drift between, multiple versions of your
    3.59 -	    project.</para></listitem></itemizedlist>
    3.60 -      <para>Most of these reasons are equally valid---at least in
    3.61 -	theory---whether you're working on a project by yourself, or
    3.62 -	with a hundred other people.</para>
    3.63 -
    3.64 -      <para>A key question about the practicality of revision control
    3.65 -	at these two different scales (<quote>lone hacker</quote> and
    3.66 -	<quote>huge team</quote>) is how its
    3.67 -	<emphasis>benefits</emphasis> compare to its
    3.68 -	<emphasis>costs</emphasis>.  A revision control tool that's
    3.69 -	difficult to understand or use is going to impose a high
    3.70 -	cost.</para>
    3.71 -
    3.72 -      <para>A five-hundred-person project is likely to collapse under
    3.73 -	its own weight almost immediately without a revision control
    3.74 -	tool and process. In this case, the cost of using revision
    3.75 -	control might hardly seem worth considering, since
    3.76 -	<emphasis>without</emphasis> it, failure is almost
    3.77 -	guaranteed.</para>
    3.78 -
    3.79 -      <para>On the other hand, a one-person <quote>quick hack</quote>
    3.80 -	might seem like a poor place to use a revision control tool,
    3.81 -	because surely the cost of using one must be close to the
    3.82 -	overall cost of the project.  Right?</para>
    3.83 -
    3.84 -      <para>Mercurial uniquely supports <emphasis>both</emphasis> of
    3.85 -	these scales of development.  You can learn the basics in just
    3.86 -	a few minutes, and due to its low overhead, you can apply
    3.87 -	revision control to the smallest of projects with ease.  Its
    3.88 -	simplicity means you won't have a lot of abstruse concepts or
    3.89 -	command sequences competing for mental space with whatever
    3.90 -	you're <emphasis>really</emphasis> trying to do.  At the same
    3.91 -	time, Mercurial's high performance and peer-to-peer nature let
    3.92 -	you scale painlessly to handle large projects.</para>
    3.93 -
    3.94 -      <para>No revision control tool can rescue a poorly run project,
    3.95 -	but a good choice of tools can make a huge difference to the
    3.96 -	fluidity with which you can work on a project.</para>
    3.97 -
    3.98 -    </sect2>
    3.99 -    <sect2>
   3.100 -      <title>The many names of revision control</title>
   3.101 -
   3.102 -      <para>Revision control is a diverse field, so much so that it
   3.103 -	doesn't actually have a single name or acronym.  Here are a
   3.104 -	few of the more common names and acronyms you'll
   3.105 -	encounter:</para>
   3.106 -      <itemizedlist>
   3.107 -	<listitem><para>Revision control (RCS)</para></listitem>
   3.108 -	<listitem><para>Software configuration management (SCM), or
   3.109 -	    configuration management</para></listitem>
   3.110 -	<listitem><para>Source code management</para></listitem>
   3.111 -	<listitem><para>Source code control, or source
   3.112 -	    control</para></listitem>
   3.113 -	<listitem><para>Version control
   3.114 -	    (VCS)</para></listitem></itemizedlist>
   3.115 -      <para>Some people claim that these terms actually have different
   3.116 -	meanings, but in practice they overlap so much that there's no
   3.117 -	agreed or even useful way to tease them apart.</para>
   3.118 -
   3.119 -    </sect2>
   3.120 -  </sect1>
   3.121 -  <sect1>
   3.122 -    <title>A short history of revision control</title>
   3.123 -
   3.124 -    <para>The best known of the old-time revision control tools is
   3.125 -      SCCS (Source Code Control System), which Marc Rochkind wrote at
   3.126 -      Bell Labs, in the early 1970s.  SCCS operated on individual
   3.127 -      files, and required every person working on a project to have
   3.128 -      access to a shared workspace on a single system.  Only one
   3.129 -      person could modify a file at any time; arbitration for access
   3.130 -      to files was via locks.  It was common for people to lock files,
   3.131 -      and later forget to unlock them, preventing anyone else from
   3.132 -      modifying those files without the help of an
   3.133 -      administrator.</para>
   3.134 -
   3.135 -    <para>Walter Tichy developed a free alternative to SCCS in the
   3.136 -      early 1980s; he called his program RCS (Revision Control System).
   3.137 -      Like SCCS, RCS required developers to work in a single shared
   3.138 -      workspace, and to lock files to prevent multiple people from
   3.139 -      modifying them simultaneously.</para>
   3.140 -
   3.141 -    <para>Later in the 1980s, Dick Grune used RCS as a building block
   3.142 -      for a set of shell scripts he initially called cmt, but then
   3.143 -      renamed to CVS (Concurrent Versions System).  The big innovation
   3.144 -      of CVS was that it let developers work simultaneously and
   3.145 -      somewhat independently in their own personal workspaces.  The
   3.146 -      personal workspaces prevented developers from stepping on each
   3.147 -      other's toes all the time, as was common with SCCS and RCS. Each
   3.148 -      developer had a copy of every project file, and could modify
   3.149 -      their copies independently.  They had to merge their edits prior
   3.150 -      to committing changes to the central repository.</para>
   3.151 -
   3.152 -    <para>Brian Berliner took Grune's original scripts and rewrote
   3.153 -      them in C, releasing in 1989 the code that has since developed
   3.154 -      into the modern version of CVS.  CVS subsequently acquired the
   3.155 -      ability to operate over a network connection, giving it a
   3.156 -      client/server architecture.  CVS's architecture is centralised;
   3.157 -      only the server has a copy of the history of the project. Client
   3.158 -      workspaces just contain copies of recent versions of the
   3.159 -      project's files, and a little metadata to tell them where the
   3.160 -      server is.  CVS has been enormously successful; it is probably
   3.161 -      the world's most widely used revision control system.</para>
   3.162 -
   3.163 -    <para>In the early 1990s, Sun Microsystems developed an early
   3.164 -      distributed revision control system, called TeamWare.  A
   3.165 -      TeamWare workspace contains a complete copy of the project's
   3.166 -      history.  TeamWare has no notion of a central repository.  (CVS
   3.167 -      relied upon RCS for its history storage; TeamWare used
   3.168 -      SCCS.)</para>
   3.169 -
   3.170 -    <para>As the 1990s progressed, awareness grew of a number of
   3.171 -      problems with CVS.  It records simultaneous changes to multiple
   3.172 -      files individually, instead of grouping them together as a
   3.173 -      single logically atomic operation.  It does not manage its file
   3.174 -      hierarchy well; it is easy to make a mess of a repository by
   3.175 -      renaming files and directories.  Worse, its source code is
   3.176 -      difficult to read and maintain, which made the <quote>pain
   3.177 -	level</quote> of fixing these architectural problems
   3.178 -      prohibitive.</para>
   3.179 -
   3.180 -    <para>In 2001, Jim Blandy and Karl Fogel, two developers who had
   3.181 -      worked on CVS, started a project to replace it with a tool that
   3.182 -      would have a better architecture and cleaner code.  The result,
   3.183 -      Subversion, does not stray from CVS's centralised client/server
   3.184 -      model, but it adds multi-file atomic commits, better namespace
   3.185 -      management, and a number of other features that make it a
   3.186 -      generally better tool than CVS. Since its initial release, it
   3.187 -      has rapidly grown in popularity.</para>
   3.188 -
   3.189 -    <para>More or less simultaneously, Graydon Hoare began working on
   3.190 -      an ambitious distributed revision control system that he named
   3.191 -      Monotone. While Monotone addresses many of CVS's design flaws
   3.192 -      and has a peer-to-peer architecture, it goes beyond earlier (and
   3.193 -      subsequent) revision control tools in a number of innovative
   3.194 -      ways.  It uses cryptographic hashes as identifiers, and has an
   3.195 -      integral notion of <quote>trust</quote> for code from different
   3.196 -      sources.</para>
   3.197 -
   3.198 -    <para>Mercurial began life in 2005.  While a few aspects of its
   3.199 -      design are influenced by Monotone, Mercurial focuses on ease of
   3.200 -      use, high performance, and scalability to very large
   3.201 -      projects.</para>
   3.202 -
   3.203 -  </sect1>
   3.204 -  <sect1>
   3.205 -    <title>Trends in revision control</title>
   3.206 -
   3.207 -    <para>There has been an unmistakable trend in the development and
   3.208 -      use of revision control tools over the past four decades, as
   3.209 -      people have become familiar with the capabilities of their tools
   3.210 -      and constrained by their limitations.</para>
   3.211 -
   3.212 -    <para>The first generation began by managing single files on
   3.213 -      individual computers.  Although these tools represented a huge
   3.214 -      advance over ad-hoc manual revision control, their locking model
   3.215 -      and reliance on a single computer limited them to small,
   3.216 -      tightly-knit teams.</para>
   3.217 -
   3.218 -    <para>The second generation loosened these constraints by moving
   3.219 -      to network-centered architectures, and managing entire projects
   3.220 -      at a time.  As projects grew larger, they ran into new problems.
   3.221 -      With clients needing to talk to servers very frequently, server
   3.222 -      scaling became an issue for large projects.  An unreliable
   3.223 -      network connection could prevent remote users from being able to
   3.224 -      talk to the server at all.  As open source projects started
   3.225 -      making read-only access available anonymously to anyone, people
   3.226 -      without commit privileges found that they could not use the
   3.227 -      tools to interact with a project in a natural way, as they could
   3.228 -      not record their changes.</para>
   3.229 -
   3.230 -    <para>The current generation of revision control tools is
   3.231 -      peer-to-peer in nature.  All of these systems have dropped the
   3.232 -      dependency on a single central server, and allow people to
   3.233 -      distribute their revision control data to where it's actually
   3.234 -      needed.  Collaboration over the Internet has moved from
   3.235 -      constrained by technology to a matter of choice and consensus.
   3.236 -      Modern tools can operate offline indefinitely and autonomously,
   3.237 -      with a network connection only needed when syncing changes with
   3.238 -      another repository.</para>
   3.239 -
   3.240 -  </sect1>
   3.241 -  <sect1>
   3.242 -    <title>A few of the advantages of distributed revision
   3.243 -      control</title>
   3.244 -
   3.245 -    <para>Even though distributed revision control tools have for
   3.246 -      several years been as robust and usable as their
   3.247 -      previous-generation counterparts, people using older tools have
   3.248 -      not yet necessarily woken up to their advantages.  There are a
   3.249 -      number of ways in which distributed tools shine relative to
   3.250 -      centralised ones.</para>
   3.251 -
   3.252 -    <para>For an individual developer, distributed tools are almost
   3.253 -      always much faster than centralised tools.  This is for a simple
   3.254 -      reason: a centralised tool needs to talk over the network for
   3.255 -      many common operations, because most metadata is stored in a
   3.256 -      single copy on the central server.  A distributed tool stores
   3.257 -      all of its metadata locally.  All else being equal, talking over
   3.258 -      the network adds overhead to a centralised tool.  Don't
   3.259 -      underestimate the value of a snappy, responsive tool: you're
   3.260 -      going to spend a lot of time interacting with your revision
   3.261 -      control software.</para>
   3.262 -
   3.263 -    <para>Distributed tools are indifferent to the vagaries of your
   3.264 -      server infrastructure, again because they replicate metadata to
   3.265 -      so many locations.  If you use a centralised system and your
   3.266 -      server catches fire, you'd better hope that your backup media
   3.267 -      are reliable, and that your last backup was recent and actually
   3.268 -      worked.  With a distributed tool, you have many backups
   3.269 -      available on every contributor's computer.</para>
   3.270 -
   3.271 -    <para>The reliability of your network will affect distributed
   3.272 -      tools far less than it will centralised tools.  You can't even
   3.273 -      use a centralised tool without a network connection, except for
   3.274 -      a few highly constrained commands.  With a distributed tool, if
   3.275 -      your network connection goes down while you're working, you may
   3.276 -      not even notice.  The only thing you won't be able to do is talk
   3.277 -      to repositories on other computers, something that is relatively
   3.278 -      rare compared with local operations.  If you have a far-flung
   3.279 -      team of collaborators, this may be significant.</para>
   3.280 -
   3.281 -    <sect2>
   3.282 -      <title>Advantages for open source projects</title>
   3.283 -
   3.284 -      <para>If you take a shine to an open source project and decide
   3.285 -	that you would like to start hacking on it, and that project
   3.286 -	uses a distributed revision control tool, you are at once a
   3.287 -	peer with the people who consider themselves the
   3.288 -	<quote>core</quote> of that project.  If they publish their
   3.289 -	repositories, you can immediately copy their project history,
   3.290 -	start making changes, and record your work, using the same
   3.291 -	tools in the same ways as insiders.  By contrast, with a
   3.292 -	centralised tool, you must use the software in a <quote>read
   3.293 -	  only</quote> mode unless someone grants you permission to
   3.294 -	commit changes to their central server.  Until then, you won't
   3.295 -	be able to record changes, and your local modifications will
   3.296 -	be at risk of corruption any time you try to update your
   3.297 -	client's view of the repository.</para>
   3.298 -
   3.299 -      <sect3>
   3.300 -	<title>The forking non-problem</title>
   3.301 -
   3.302 -	<para>It has been suggested that distributed revision control
   3.303 -	  tools pose some sort of risk to open source projects because
   3.304 -	  they make it easy to <quote>fork</quote> the development of
   3.305 -	  a project.  A fork happens when there are differences in
   3.306 -	  opinion or attitude between groups of developers that cause
   3.307 -	  them to decide that they can't work together any longer.
   3.308 -	  Each side takes a more or less complete copy of the
   3.309 -	  project's source code, and goes off in its own
   3.310 -	  direction.</para>
   3.311 -
   3.312 -	<para>Sometimes the camps in a fork decide to reconcile their
   3.313 -	  differences. With a centralised revision control system, the
   3.314 -	  <emphasis>technical</emphasis> process of reconciliation is
   3.315 -	  painful, and has to be performed largely by hand.  You have
   3.316 -	  to decide whose revision history is going to
   3.317 -	  <quote>win</quote>, and graft the other team's changes into
   3.318 -	  the tree somehow. This usually loses some or all of one
   3.319 -	  side's revision history.</para>
   3.320 -
   3.321 -	<para>What distributed tools do with respect to forking is
   3.322 -	  they make forking the <emphasis>only</emphasis> way to
   3.323 -	  develop a project.  Every single change that you make is
   3.324 -	  potentially a fork point.  The great strength of this
   3.325 -	  approach is that a distributed revision control tool has to
   3.326 -	  be really good at <emphasis>merging</emphasis> forks,
   3.327 -	  because forks are absolutely fundamental: they happen all
   3.328 -	  the time.</para>
   3.329 -
   3.330 -	<para>If every piece of work that everybody does, all the
   3.331 -	  time, is framed in terms of forking and merging, then what
   3.332 -	  the open source world refers to as a <quote>fork</quote>
   3.333 -	  becomes <emphasis>purely</emphasis> a social issue.  If
   3.334 -	  anything, distributed tools <emphasis>lower</emphasis> the
   3.335 -	  likelihood of a fork:</para>
   3.336 -	<itemizedlist>
   3.337 -	  <listitem><para>They eliminate the social distinction that
   3.338 -	      centralised tools impose: that between insiders (people
   3.339 -	      with commit access) and outsiders (people
   3.340 -	      without).</para></listitem>
   3.341 -	  <listitem><para>They make it easier to reconcile after a
   3.342 -	      social fork, because all that's involved from the
   3.343 -	      perspective of the revision control software is just
   3.344 -	      another merge.</para></listitem></itemizedlist>
   3.345 -
   3.346 -	<para>Some people resist distributed tools because they want
   3.347 -	  to retain tight control over their projects, and they
   3.348 -	  believe that centralised tools give them this control.
   3.349 -	  However, if you're of this belief, and you publish your CVS
   3.350 -	  or Subversion repositories publicly, there are plenty of
   3.351 -	  tools available that can pull out your entire project's
   3.352 -	  history (albeit slowly) and recreate it somewhere that you
   3.353 -	  don't control.  So while your control in this case is
   3.354 -	  illusory, you are forgoing the ability to fluidly
   3.355 -	  collaborate with whatever people feel compelled to mirror
   3.356 -	  and fork your history.</para>
   3.357 -
   3.358 -      </sect3>
   3.359 -    </sect2>
   3.360 -    <sect2>
   3.361 -      <title>Advantages for commercial projects</title>
   3.362 -
   3.363 -      <para>Many commercial projects are undertaken by teams that are
   3.364 -	scattered across the globe.  Contributors who are far from a
   3.365 -	central server will see slower command execution and perhaps
   3.366 -	less reliability.  Commercial revision control systems attempt
   3.367 -	to ameliorate these problems with remote-site replication
   3.368 -	add-ons that are typically expensive to buy and cantankerous
   3.369 -	to administer.  A distributed system doesn't suffer from these
   3.370 -	problems in the first place.  Better yet, you can easily set
   3.371 -	up multiple authoritative servers, say one per site, so that
   3.372 -	there's no redundant communication between repositories over
   3.373 -	expensive long-haul network links.</para>
   3.374 -
   3.375 -      <para>Centralised revision control systems tend to have
   3.376 -	relatively low scalability.  It's not unusual for an expensive
   3.377 -	centralised system to fall over under the combined load of
   3.378 -	just a few dozen concurrent users.  Once again, the typical
   3.379 -	response tends to be an expensive and clunky replication
   3.380 -	facility.  Since the load on a central server---if you have
   3.381 -	one at all---is many times lower with a distributed tool
   3.382 -	(because all of the data is replicated everywhere), a single
   3.383 -	cheap server can handle the needs of a much larger team, and
   3.384 -	replication to balance load becomes a simple matter of
   3.385 -	scripting.</para>
   3.386 -
   3.387 -      <para>If you have an employee in the field, troubleshooting a
   3.388 -	problem at a customer's site, they'll benefit from distributed
   3.389 -	revision control. The tool will let them generate custom
   3.390 -	builds, try different fixes in isolation from each other, and
   3.391 -	search efficiently through history for the sources of bugs and
   3.392 -	regressions in the customer's environment, all without needing
   3.393 -	to connect to your company's network.</para>
   3.394 -
   3.395 -    </sect2>
   3.396 -  </sect1>
   3.397 -  <sect1>
   3.398 -    <title>Why choose Mercurial?</title>
   3.399 -
   3.400 -    <para>Mercurial has a unique set of properties that make it a
   3.401 -      particularly good choice as a revision control system.</para>
   3.402 -    <itemizedlist>
   3.403 -      <listitem><para>It is easy to learn and use.</para></listitem>
   3.404 -      <listitem><para>It is lightweight.</para></listitem>
   3.405 -      <listitem><para>It scales excellently.</para></listitem>
   3.406 -      <listitem><para>It is easy to
   3.407 -	  customise.</para></listitem></itemizedlist>
   3.408 -
   3.409 -    <para>If you are at all familiar with revision control systems,
   3.410 -      you should be able to get up and running with Mercurial in less
   3.411 -      than five minutes.  Even if not, it will take no more than a few
   3.412 -      minutes longer.  Mercurial's command and feature sets are
   3.413 -      generally uniform and consistent, so you can keep track of a few
   3.414 -      general rules instead of a host of exceptions.</para>
   3.415 -
   3.416 -    <para>On a small project, you can start working with Mercurial in
   3.417 -      moments. Creating new changes and branches; transferring changes
   3.418 -      around (whether locally or over a network); and history and
   3.419 -      status operations are all fast.  Mercurial attempts to stay
   3.420 -      nimble and largely out of your way by combining low cognitive
   3.421 -      overhead with blazingly fast operations.</para>
   3.422 -
   3.423 -    <para>The usefulness of Mercurial is not limited to small
   3.424 -      projects: it is used by projects with hundreds to thousands of
   3.425 -      contributors, each containing tens of thousands of files and
   3.426 -      hundreds of megabytes of source code.</para>
   3.427 -
   3.428 -    <para>If the core functionality of Mercurial is not enough for
   3.429 -      you, it's easy to build on.  Mercurial is well suited to
   3.430 -      scripting tasks, and its clean internals and implementation in
   3.431 -      Python make it easy to add features in the form of extensions.
   3.432 -      There are a number of popular and useful extensions already
   3.433 -      available, ranging from helping to identify bugs to improving
   3.434 -      performance.</para>
   3.435 -
   3.436 -  </sect1>
   3.437 -  <sect1>
   3.438 -    <title>Mercurial compared with other tools</title>
   3.439 -
   3.440 -    <para>Before you read on, please understand that this section
   3.441 -      necessarily reflects my own experiences, interests, and (dare I
   3.442 -      say it) biases.  I have used every one of the revision control
   3.443 -      tools listed below, in most cases for several years at a
   3.444 -      time.</para>
   3.445 -
   3.446 -
   3.447 -    <sect2>
   3.448 -      <title>Subversion</title>
   3.449 -
   3.450 -      <para>Subversion is a popular revision control tool, developed
   3.451 -	to replace CVS.  It has a centralised client/server
   3.452 -	architecture.</para>
   3.453 -
   3.454 -      <para>Subversion and Mercurial have similarly named commands for
   3.455 -	performing the same operations, so if you're familiar with
   3.456 -	one, it is easy to learn to use the other.  Both tools are
   3.457 -	portable to all popular operating systems.</para>
   3.458 -
   3.459 -      <para>Prior to version 1.5, Subversion had no useful support for
   3.460 -	merges. At the time of writing, its merge tracking capability
   3.461 -	is new, and known to be <ulink
   3.462 -	  url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword">complicated 
   3.463 -	  and buggy</ulink>.</para>
   3.464 -
   3.465 -      <para>Mercurial has a substantial performance advantage over
   3.466 -	Subversion on every revision control operation I have
   3.467 -	benchmarked.  I have measured its advantage as ranging from a
   3.468 -	factor of two to a factor of six when compared with Subversion
   3.469 -	1.4.3's <emphasis>ra_local</emphasis> file store, which is the
   3.470 -	fastest access method available.  In more realistic
   3.471 -	deployments involving a network-based store, Subversion will
   3.472 -	be at a substantially larger disadvantage.  Because many
   3.473 -	Subversion commands must talk to the server and Subversion
   3.474 -	does not have useful replication facilities, server capacity
   3.475 -	and network bandwidth become bottlenecks for modestly large
   3.476 -	projects.</para>
   3.477 -
   3.478 -      <para>Additionally, Subversion incurs substantial storage
   3.479 -	overhead to avoid network transactions for a few common
   3.480 -	operations, such as finding modified files
   3.481 -	(<literal>status</literal>) and displaying modifications
   3.482 -	against the current revision (<literal>diff</literal>).  As a
   3.483 -	result, a Subversion working copy is often the same size as,
   3.484 -	or larger than, a Mercurial repository and working directory,
   3.485 -	even though the Mercurial repository contains a complete
   3.486 -	history of the project.</para>
   3.487 -
   3.488 -      <para>Subversion is widely supported by third party tools.
   3.489 -	Mercurial currently lags considerably in this area.  This gap
   3.490 -	is closing, however, and indeed some of Mercurial's GUI tools
   3.491 -	now outshine their Subversion equivalents.  Like Mercurial,
   3.492 -	Subversion has an excellent user manual.</para>
   3.493 -
   3.494 -      <para>Because Subversion doesn't store revision history on the
   3.495 -	client, it is well suited to managing projects that deal with
   3.496 -	lots of large, opaque binary files.  If you check in fifty
   3.497 -	revisions to an incompressible 10MB file, Subversion's
   3.498 -	client-side space usage stays constant The space used by any
   3.499 -	distributed SCM will grow rapidly in proportion to the number
   3.500 -	of revisions, because the differences between each revision
   3.501 -	are large.</para>
   3.502 -
   3.503 -      <para>In addition, it's often difficult or, more usually,
   3.504 -	impossible to merge different versions of a binary file.
   3.505 -	Subversion's ability to let a user lock a file, so that they
   3.506 -	temporarily have the exclusive right to commit changes to it,
   3.507 -	can be a significant advantage to a project where binary files
   3.508 -	are widely used.</para>
   3.509 -
   3.510 -      <para>Mercurial can import revision history from a Subversion
   3.511 -	repository. It can also export revision history to a
   3.512 -	Subversion repository.  This makes it easy to <quote>test the
   3.513 -	  waters</quote> and use Mercurial and Subversion in parallel
   3.514 -	before deciding to switch.  History conversion is incremental,
   3.515 -	so you can perform an initial conversion, then small
   3.516 -	additional conversions afterwards to bring in new
   3.517 -	changes.</para>
   3.518 -
   3.519 -
   3.520 -    </sect2>
   3.521 -    <sect2>
   3.522 -      <title>Git</title>
   3.523 -
   3.524 -      <para>Git is a distributed revision control tool that was
   3.525 -	developed for managing the Linux kernel source tree.  Like
   3.526 -	Mercurial, its early design was somewhat influenced by
   3.527 -	Monotone.</para>
   3.528 -
   3.529 -      <para>Git has a very large command set, with version 1.5.0
   3.530 -	providing 139 individual commands.  It has something of a
   3.531 -	reputation for being difficult to learn.  Compared to Git,
   3.532 -	Mercurial has a strong focus on simplicity.</para>
   3.533 -
   3.534 -      <para>In terms of performance, Git is extremely fast.  In
   3.535 -	several cases, it is faster than Mercurial, at least on Linux,
   3.536 -	while Mercurial performs better on other operations.  However,
   3.537 -	on Windows, the performance and general level of support that
   3.538 -	Git provides is, at the time of writing, far behind that of
   3.539 -	Mercurial.</para>
   3.540 -
   3.541 -      <para>While a Mercurial repository needs no maintenance, a Git
   3.542 -	repository requires frequent manual <quote>repacks</quote> of
   3.543 -	its metadata.  Without these, performance degrades, while
   3.544 -	space usage grows rapidly.  A server that contains many Git
   3.545 -	repositories that are not rigorously and frequently repacked
   3.546 -	will become heavily disk-bound during backups, and there have
   3.547 -	been instances of daily backups taking far longer than 24
   3.548 -	hours as a result.  A freshly packed Git repository is
   3.549 -	slightly smaller than a Mercurial repository, but an unpacked
   3.550 -	repository is several orders of magnitude larger.</para>
   3.551 -
   3.552 -      <para>The core of Git is written in C.  Many Git commands are
   3.553 -	implemented as shell or Perl scripts, and the quality of these
   3.554 -	scripts varies widely. I have encountered several instances
   3.555 -	where scripts charged along blindly in the presence of errors
   3.556 -	that should have been fatal.</para>
   3.557 -
   3.558 -      <para>Mercurial can import revision history from a Git
   3.559 -	repository.</para>
   3.560 -
   3.561 -
   3.562 -    </sect2>
   3.563 -    <sect2>
   3.564 -      <title>CVS</title>
   3.565 -
   3.566 -      <para>CVS is probably the most widely used revision control tool
   3.567 -	in the world.  Due to its age and internal untidiness, it has
   3.568 -	been only lightly maintained for many years.</para>
   3.569 -
   3.570 -      <para>It has a centralised client/server architecture.  It does
   3.571 -	not group related file changes into atomic commits, making it
   3.572 -	easy for people to <quote>break the build</quote>: one person
   3.573 -	can successfully commit part of a change and then be blocked
   3.574 -	by the need for a merge, causing other people to see only a
   3.575 -	portion of the work they intended to do.  This also affects
   3.576 -	how you work with project history.  If you want to see all of
   3.577 -	the modifications someone made as part of a task, you will
   3.578 -	need to manually inspect the descriptions and timestamps of
   3.579 -	the changes made to each file involved (if you even know what
   3.580 -	those files were).</para>
   3.581 -
   3.582 -      <para>CVS has a muddled notion of tags and branches that I will
   3.583 -	not attempt to even describe.  It does not support renaming of
   3.584 -	files or directories well, making it easy to corrupt a
   3.585 -	repository.  It has almost no internal consistency checking
   3.586 -	capabilities, so it is usually not even possible to tell
   3.587 -	whether or how a repository is corrupt.  I would not recommend
   3.588 -	CVS for any project, existing or new.</para>
   3.589 -
   3.590 -      <para>Mercurial can import CVS revision history.  However, there
   3.591 -	are a few caveats that apply; these are true of every other
   3.592 -	revision control tool's CVS importer, too.  Due to CVS's lack
   3.593 -	of atomic changes and unversioned filesystem hierarchy, it is
   3.594 -	not possible to reconstruct CVS history completely accurately;
   3.595 -	some guesswork is involved, and renames will usually not show
   3.596 -	up.  Because a lot of advanced CVS administration has to be
   3.597 -	done by hand and is hence error-prone, it's common for CVS
   3.598 -	importers to run into multiple problems with corrupted
   3.599 -	repositories (completely bogus revision timestamps and files
   3.600 -	that have remained locked for over a decade are just two of
   3.601 -	the less interesting problems I can recall from personal
   3.602 -	experience).</para>
   3.603 -
   3.604 -      <para>Mercurial can import revision history from a CVS
   3.605 -	repository.</para>
   3.606 -
   3.607 -
   3.608 -    </sect2>
   3.609 -    <sect2>
   3.610 -      <title>Commercial tools</title>
   3.611 -
   3.612 -      <para>Perforce has a centralised client/server architecture,
   3.613 -	with no client-side caching of any data.  Unlike modern
   3.614 -	revision control tools, Perforce requires that a user run a
   3.615 -	command to inform the server about every file they intend to
   3.616 -	edit.</para>
   3.617 -
   3.618 -      <para>The performance of Perforce is quite good for small teams,
   3.619 -	but it falls off rapidly as the number of users grows beyond a
   3.620 -	few dozen. Modestly large Perforce installations require the
   3.621 -	deployment of proxies to cope with the load their users
   3.622 -	generate.</para>
   3.623 -
   3.624 -
   3.625 -    </sect2>
   3.626 -    <sect2>
   3.627 -      <title>Choosing a revision control tool</title>
   3.628 -
   3.629 -      <para>With the exception of CVS, all of the tools listed above
   3.630 -	have unique strengths that suit them to particular styles of
   3.631 -	work.  There is no single revision control tool that is best
   3.632 -	in all situations.</para>
   3.633 -
   3.634 -      <para>As an example, Subversion is a good choice for working
   3.635 -	with frequently edited binary files, due to its centralised
   3.636 -	nature and support for file locking.</para>
   3.637 -
   3.638 -      <para>I personally find Mercurial's properties of simplicity,
   3.639 -	performance, and good merge support to be a compelling
   3.640 -	combination that has served me well for several years.</para>
   3.641 -
   3.642 -
   3.643 -    </sect2>
   3.644 -  </sect1>
   3.645 -  <sect1>
   3.646 -    <title>Switching from another tool to Mercurial</title>
   3.647 -
   3.648 -    <para>Mercurial is bundled with an extension named <literal
   3.649 -	role="hg-ext">convert</literal>, which can incrementally
   3.650 -      import revision history from several other revision control
   3.651 -      tools.  By <quote>incremental</quote>, I mean that you can
   3.652 -      convert all of a project's history to date in one go, then rerun
   3.653 -      the conversion later to obtain new changes that happened after
   3.654 -      the initial conversion.</para>
   3.655 -
   3.656 -    <para>The revision control tools supported by <literal
   3.657 -	role="hg-ext">convert</literal> are as follows:</para>
   3.658 -    <itemizedlist>
   3.659 -      <listitem><para>Subversion</para></listitem>
   3.660 -      <listitem><para>CVS</para></listitem>
   3.661 -      <listitem><para>Git</para></listitem>
   3.662 -      <listitem><para>Darcs</para></listitem></itemizedlist>
   3.663 -
   3.664 -    <para>In addition, <literal role="hg-ext">convert</literal> can
   3.665 -      export changes from Mercurial to Subversion.  This makes it
   3.666 -      possible to try Subversion and Mercurial in parallel before
   3.667 -      committing to a switchover, without risking the loss of any
   3.668 -      work.</para>
   3.669 -
   3.670 -    <para>The <command role="hg-ext-conver">convert</command> command
   3.671 -      is easy to use.  Simply point it at the path or URL of the
   3.672 -      source repository, optionally give it the name of the
   3.673 -      destination repository, and it will start working.  After the
   3.674 -      initial conversion, just run the same command again to import
   3.675 -      new changes.</para>
   3.676 -  </sect1>
   3.677 -</chapter>
   3.678 -
   3.679 -<!--
   3.680 -local variables: 
   3.681 -sgml-parent-document: ("00book.xml" "book" "chapter")
   3.682 -end:
   3.683 --->

     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/en/ch01-tour-basic.xml	Thu Mar 19 20:54:12 2009 -0700
     4.3 @@ -0,0 +1,860 @@
     4.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     4.5 +
     4.6 +<chapter id="chap:tour-basic">
     4.7 +  <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?>
     4.8 +  <title>A tour of Mercurial: the basics</title>
     4.9 +
    4.10 +  <sect1 id="sec:tour:install">
    4.11 +    <title>Installing Mercurial on your system</title>
    4.12 +
    4.13 +    <para>Prebuilt binary packages of Mercurial are available for
    4.14 +      every popular operating system.  These make it easy to start
    4.15 +      using Mercurial on your computer immediately.</para>
    4.16 +
    4.17 +    <sect2>
    4.18 +      <title>Linux</title>
    4.19 +
    4.20 +      <para>Because each Linux distribution has its own packaging
    4.21 +	tools, policies, and rate of development, it's difficult to
    4.22 +	give a comprehensive set of instructions on how to install
    4.23 +	Mercurial binaries.  The version of Mercurial that you will
    4.24 +	end up with can vary depending on how active the person is who
    4.25 +	maintains the package for your distribution.</para>
    4.26 +
    4.27 +      <para>To keep things simple, I will focus on installing
    4.28 +	Mercurial from the command line under the most popular Linux
    4.29 +	distributions.  Most of these distributions provide graphical
    4.30 +	package managers that will let you install Mercurial with a
    4.31 +	single click; the package name to look for is
    4.32 +	<literal>mercurial</literal>.</para>
    4.33 +
    4.34 +      <itemizedlist>
    4.35 +	<listitem><para>Debian:</para>
    4.36 +	  <programlisting>apt-get install mercurial</programlisting></listitem>
    4.37 +	<listitem><para>Fedora Core:</para>
    4.38 +	  <programlisting>yum install mercurial</programlisting></listitem>
    4.39 +	<listitem><para>Gentoo:</para>
    4.40 +	  <programlisting>emerge mercurial</programlisting></listitem>
    4.41 +	<listitem><para>OpenSUSE:</para>
    4.42 +	  <programlisting>yum install mercurial</programlisting></listitem>
    4.43 +	<listitem><para>Ubuntu: Ubuntu's Mercurial package is based on
    4.44 +	    Debian's.  To install it, run the following
    4.45 +	    command.</para>
    4.46 +	  <programlisting>apt-get install mercurial</programlisting></listitem>
    4.47 +      </itemizedlist>
    4.48 +
    4.49 +    </sect2>
    4.50 +    <sect2>
    4.51 +      <title>Solaris</title>
    4.52 +
    4.53 +      <para>SunFreeWare, at <ulink
    4.54 +	  url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 
    4.55 +	is a good source for a large number of pre-built Solaris
    4.56 +	packages for 32 and 64 bit Intel and Sparc architectures,
    4.57 +	including current versions of Mercurial.</para>
    4.58 +
    4.59 +    </sect2>
    4.60 +    <sect2>
    4.61 +      <title>Mac OS X</title>
    4.62 +
    4.63 +      <para>Lee Cantey publishes an installer of Mercurial for Mac OS
    4.64 +	X at <ulink
    4.65 +	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 
    4.66 +	This package works on both Intel- and Power-based Macs. Before
    4.67 +	you can use it, you must install a compatible version of
    4.68 +	Universal MacPython <citation>web:macpython</citation>. This
    4.69 +	is easy to do; simply follow the instructions on Lee's
    4.70 +	site.</para>
    4.71 +
    4.72 +      <para>It's also possible to install Mercurial using Fink or
    4.73 +	MacPorts, two popular free package managers for Mac OS X.  If
    4.74 +	you have Fink, use <command>sudo apt-get install
    4.75 +	  mercurial-py25</command>.  If MacPorts, <command>sudo port
    4.76 +	  install mercurial</command>.</para>
    4.77 +
    4.78 +    </sect2>
    4.79 +    <sect2>
    4.80 +      <title>Windows</title>
    4.81 +
    4.82 +      <para>Lee Cantey publishes an installer of Mercurial for Windows
    4.83 +	at <ulink
    4.84 +	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 
    4.85 +	This package has no external dependencies; it <quote>just
    4.86 +	  works</quote>.</para>
    4.87 +
    4.88 +      <note>
    4.89 +	<para>  The Windows version of Mercurial does not
    4.90 +	  automatically convert line endings between Windows and Unix
    4.91 +	  styles.  If you want to share work with Unix users, you must
    4.92 +	  do a little additional configuration work. XXX Flesh this
    4.93 +	  out.</para>
    4.94 +      </note>
    4.95 +
    4.96 +    </sect2>
    4.97 +  </sect1>
    4.98 +  <sect1>
    4.99 +    <title>Getting started</title>
   4.100 +
   4.101 +    <para>To begin, we'll use the <command role="hg-cmd">hg
   4.102 +	version</command> command to find out whether Mercurial is
   4.103 +      actually installed properly.  The actual version information
   4.104 +      that it prints isn't so important; it's whether it prints
   4.105 +      anything at all that we care about.</para>
   4.106 +
   4.107 +    &interaction.tour.version;
   4.108 +
   4.109 +    <sect2>
   4.110 +      <title>Built-in help</title>
   4.111 +
   4.112 +      <para>Mercurial provides a built-in help system.  This is
   4.113 +	  invaluable for those times when you find yourself stuck
   4.114 +	  trying to remember how to run a command.  If you are
   4.115 +	  completely stuck, simply run <command role="hg-cmd">hg
   4.116 +	    help</command>; it will print a brief list of commands,
   4.117 +	  along with a description of what each does.  If you ask for
   4.118 +	  help on a specific command (as below), it prints more
   4.119 +	  detailed information.</para>
   4.120 +
   4.121 +	&interaction.tour.help;
   4.122 +
   4.123 +	<para>For a more impressive level of detail (which you won't
   4.124 +	  usually need) run <command role="hg-cmd">hg help <option
   4.125 +	      role="hg-opt-global">-v</option></command>.  The <option
   4.126 +	    role="hg-opt-global">-v</option> option is short for
   4.127 +	  <option role="hg-opt-global">--verbose</option>, and tells
   4.128 +	  Mercurial to print more information than it usually
   4.129 +	  would.</para>
   4.130 +
   4.131 +    </sect2>
   4.132 +  </sect1>
   4.133 +  <sect1>
   4.134 +    <title>Working with a repository</title>
   4.135 +
   4.136 +    <para>In Mercurial, everything happens inside a
   4.137 +      <emphasis>repository</emphasis>.  The repository for a project
   4.138 +      contains all of the files that <quote>belong to</quote> that
   4.139 +      project, along with a historical record of the project's
   4.140 +      files.</para>
   4.141 +
   4.142 +    <para>There's nothing particularly magical about a repository; it
   4.143 +      is simply a directory tree in your filesystem that Mercurial
   4.144 +      treats as special. You can rename or delete a repository any
   4.145 +      time you like, using either the command line or your file
   4.146 +      browser.</para>
   4.147 +
   4.148 +    <sect2>
   4.149 +      <title>Making a local copy of a repository</title>
   4.150 +
   4.151 +      <para><emphasis>Copying</emphasis> a repository is just a little
   4.152 +	bit special.  While you could use a normal file copying
   4.153 +	command to make a copy of a repository, it's best to use a
   4.154 +	built-in command that Mercurial provides.  This command is
   4.155 +	called <command role="hg-cmd">hg clone</command>, because it
   4.156 +	creates an identical copy of an existing repository.</para>
   4.157 +
   4.158 +      &interaction.tour.clone;
   4.159 +
   4.160 +      <para>If our clone succeeded, we should now have a local
   4.161 +	directory called <filename class="directory">hello</filename>.
   4.162 +	This directory will contain some files.</para>
   4.163 +
   4.164 +      &interaction.tour.ls;
   4.165 +
   4.166 +      <para>These files have the same contents and history in our
   4.167 +	repository as they do in the repository we cloned.</para>
   4.168 +
   4.169 +      <para>Every Mercurial repository is complete, self-contained,
   4.170 +	and independent.  It contains its own private copy of a
   4.171 +	project's files and history.  A cloned repository remembers
   4.172 +	the location of the repository it was cloned from, but it does
   4.173 +	not communicate with that repository, or any other, unless you
   4.174 +	tell it to.</para>
   4.175 +
   4.176 +      <para>What this means for now is that we're free to experiment
   4.177 +	with our repository, safe in the knowledge that it's a private
   4.178 +	<quote>sandbox</quote> that won't affect anyone else.</para>
   4.179 +
   4.180 +    </sect2>
   4.181 +    <sect2>
   4.182 +      <title>What's in a repository?</title>
   4.183 +
   4.184 +      <para>When we take a more detailed look inside a repository, we
   4.185 +	can see that it contains a directory named <filename
   4.186 +	  class="directory">.hg</filename>.  This is where Mercurial
   4.187 +	keeps all of its metadata for the repository.</para>
   4.188 +
   4.189 +      &interaction.tour.ls-a;
   4.190 +
   4.191 +      <para>The contents of the <filename
   4.192 +	  class="directory">.hg</filename> directory and its
   4.193 +	subdirectories are private to Mercurial.  Every other file and
   4.194 +	directory in the repository is yours to do with as you
   4.195 +	please.</para>
   4.196 +
   4.197 +      <para>To introduce a little terminology, the <filename
   4.198 +	  class="directory">.hg</filename> directory is the
   4.199 +	<quote>real</quote> repository, and all of the files and
   4.200 +	directories that coexist with it are said to live in the
   4.201 +	<emphasis>working directory</emphasis>.  An easy way to
   4.202 +	remember the distinction is that the
   4.203 +	<emphasis>repository</emphasis> contains the
   4.204 +	<emphasis>history</emphasis> of your project, while the
   4.205 +	<emphasis>working directory</emphasis> contains a
   4.206 +	<emphasis>snapshot</emphasis> of your project at a particular
   4.207 +	point in history.</para>
   4.208 +
   4.209 +    </sect2>
   4.210 +  </sect1>
   4.211 +  <sect1>
   4.212 +    <title>A tour through history</title>
   4.213 +
   4.214 +    <para>One of the first things we might want to do with a new,
   4.215 +      unfamiliar repository is understand its history.  The <command
   4.216 +	role="hg-cmd">hg log</command> command gives us a view of
   4.217 +      history.</para>
   4.218 +
   4.219 +    &interaction.tour.log;
   4.220 +
   4.221 +    <para>By default, this command prints a brief paragraph of output
   4.222 +      for each change to the project that was recorded.  In Mercurial
   4.223 +      terminology, we call each of these recorded events a
   4.224 +      <emphasis>changeset</emphasis>, because it can contain a record
   4.225 +      of changes to several files.</para>
   4.226 +
   4.227 +    <para>The fields in a record of output from <command
   4.228 +	role="hg-cmd">hg log</command> are as follows.</para>
   4.229 +    <itemizedlist>
   4.230 +      <listitem><para><literal>changeset</literal>: This field has the
   4.231 +	  format of a number, followed by a colon, followed by a
   4.232 +	  hexadecimal string.  These are
   4.233 +	  <emphasis>identifiers</emphasis> for the changeset.  There
   4.234 +	  are two identifiers because the number is shorter and easier
   4.235 +	  to type than the hex string.</para></listitem>
   4.236 +      <listitem><para><literal>user</literal>: The identity of the
   4.237 +	  person who created the changeset.  This is a free-form
   4.238 +	  field, but it most often contains a person's name and email
   4.239 +	  address.</para></listitem>
   4.240 +      <listitem><para><literal>date</literal>: The date and time on
   4.241 +	  which the changeset was created, and the timezone in which
   4.242 +	  it was created.  (The date and time are local to that
   4.243 +	  timezone; they display what time and date it was for the
   4.244 +	  person who created the changeset.)</para></listitem>
   4.245 +      <listitem><para><literal>summary</literal>: The first line of
   4.246 +	  the text message that the creator of the changeset entered
   4.247 +	  to describe the changeset.</para></listitem></itemizedlist>
   4.248 +    <para>The default output printed by <command role="hg-cmd">hg
   4.249 +	log</command> is purely a summary; it is missing a lot of
   4.250 +      detail.</para>
   4.251 +
   4.252 +    <para>Figure <xref linkend="fig:tour-basic:history"/> provides a
   4.253 +      graphical representation of the history of the <filename
   4.254 +	class="directory">hello</filename> repository, to make it a
   4.255 +      little easier to see which direction history is
   4.256 +      <quote>flowing</quote> in.  We'll be returning to this figure
   4.257 +      several times in this chapter and the chapter that
   4.258 +      follows.</para>
   4.259 +
   4.260 +    <informalfigure id="fig:tour-basic:history">
   4.261 +      <mediaobject>
   4.262 +	<imageobject><imagedata fileref="tour-history"/></imageobject>
   4.263 +	<textobject><phrase>XXX add text</phrase></textobject>
   4.264 +	<caption><para>Graphical history of the <filename
   4.265 +	      class="directory">hello</filename>
   4.266 +	    repository</para></caption>
   4.267 +      </mediaobject>
   4.268 +    </informalfigure>
   4.269 +
   4.270 +    <sect2>
   4.271 +      <title>Changesets, revisions, and talking to other
   4.272 +	people</title>
   4.273 +
   4.274 +      <para>As English is a notoriously sloppy language, and computer
   4.275 +	science has a hallowed history of terminological confusion
   4.276 +	(why use one term when four will do?), revision control has a
   4.277 +	variety of words and phrases that mean the same thing.  If you
   4.278 +	are talking about Mercurial history with other people, you
   4.279 +	will find that the word <quote>changeset</quote> is often
   4.280 +	compressed to <quote>change</quote> or (when written)
   4.281 +	<quote>cset</quote>, and sometimes a changeset is referred to
   4.282 +	as a <quote>revision</quote> or a <quote>rev</quote>.</para>
   4.283 +
   4.284 +      <para>While it doesn't matter what <emphasis>word</emphasis> you
   4.285 +	use to refer to the concept of <quote>a changeset</quote>, the
   4.286 +	<emphasis>identifier</emphasis> that you use to refer to
   4.287 +	<quote>a <emphasis>specific</emphasis> changeset</quote> is of
   4.288 +	great importance. Recall that the <literal>changeset</literal>
   4.289 +	field in the output from <command role="hg-cmd">hg
   4.290 +	  log</command> identifies a changeset using both a number and
   4.291 +	a hexadecimal string.</para>
   4.292 +      <itemizedlist>
   4.293 +	<listitem><para>The revision number is <emphasis>only valid in
   4.294 +	      that repository</emphasis>,</para></listitem>
   4.295 +	<listitem><para>while the hex string is the
   4.296 +	    <emphasis>permanent, unchanging identifier</emphasis> that
   4.297 +	    will always identify that exact changeset in
   4.298 +	    <emphasis>every</emphasis> copy of the
   4.299 +	    repository.</para></listitem></itemizedlist>
   4.300 +      <para>This distinction is important.  If you send someone an
   4.301 +	email talking about <quote>revision 33</quote>, there's a high
   4.302 +	likelihood that their revision 33 will <emphasis>not be the
   4.303 +	  same</emphasis> as yours.  The reason for this is that a
   4.304 +	revision number depends on the order in which changes arrived
   4.305 +	in a repository, and there is no guarantee that the same
   4.306 +	changes will happen in the same order in different
   4.307 +	repositories. Three changes $a,b,c$ can easily appear in one
   4.308 +	repository as $0,1,2$, while in another as $1,0,2$.</para>
   4.309 +
   4.310 +      <para>Mercurial uses revision numbers purely as a convenient
   4.311 +	shorthand.  If you need to discuss a changeset with someone,
   4.312 +	or make a record of a changeset for some other reason (for
   4.313 +	example, in a bug report), use the hexadecimal
   4.314 +	identifier.</para>
   4.315 +
   4.316 +    </sect2>
   4.317 +    <sect2>
   4.318 +      <title>Viewing specific revisions</title>
   4.319 +
   4.320 +      <para>To narrow the output of <command role="hg-cmd">hg
   4.321 +	  log</command> down to a single revision, use the <option
   4.322 +	  role="hg-opt-log">-r</option> (or <option
   4.323 +	  role="hg-opt-log">--rev</option>) option.  You can use
   4.324 +	either a revision number or a long-form changeset identifier,
   4.325 +	and you can provide as many revisions as you want.</para>
   4.326 +
   4.327 +      &interaction.tour.log-r;
   4.328 +
   4.329 +      <para>If you want to see the history of several revisions
   4.330 +	without having to list each one, you can use <emphasis>range
   4.331 +	  notation</emphasis>; this lets you express the idea <quote>I
   4.332 +	  want all revisions between <literal>abc</literal> and
   4.333 +	  <literal>def</literal>, inclusive</quote>.</para>
   4.334 +      
   4.335 +	&interaction.tour.log.range;
   4.336 +
   4.337 +      <para>Mercurial also honours the order in which you specify
   4.338 +	revisions, so <command role="hg-cmd">hg log -r 2:4</command>
   4.339 +	prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
   4.340 +	  4:2</command> prints 4, 3, and 2.</para>
   4.341 +
   4.342 +    </sect2>
   4.343 +    <sect2>
   4.344 +      <title>More detailed information</title>
   4.345 +
   4.346 +      <para>While the summary information printed by <command
   4.347 +	  role="hg-cmd">hg log</command> is useful if you already know
   4.348 +	what you're looking for, you may need to see a complete
   4.349 +	description of the change, or a list of the files changed, if
   4.350 +	you're trying to decide whether a changeset is the one you're
   4.351 +	looking for. The <command role="hg-cmd">hg log</command>
   4.352 +	command's <option role="hg-opt-global">-v</option> (or <option
   4.353 +	  role="hg-opt-global">--verbose</option>) option gives you
   4.354 +	this extra detail.</para>
   4.355 +
   4.356 +      &interaction.tour.log-v;
   4.357 +
   4.358 +      <para>If you want to see both the description and content of a
   4.359 +	change, add the <option role="hg-opt-log">-p</option> (or
   4.360 +	<option role="hg-opt-log">--patch</option>) option.  This
   4.361 +	displays the content of a change as a <emphasis>unified
   4.362 +	  diff</emphasis> (if you've never seen a unified diff before,
   4.363 +	see section <xref linkend="sec:mq:patch"/> for an
   4.364 +	overview).</para>
   4.365 +
   4.366 +      &interaction.tour.log-vp;
   4.367 +
   4.368 +    </sect2>
   4.369 +  </sect1>
   4.370 +  <sect1>
   4.371 +    <title>All about command options</title>
   4.372 +
   4.373 +    <para>Let's take a brief break from exploring Mercurial commands
   4.374 +      to discuss a pattern in the way that they work; you may find
   4.375 +      this useful to keep in mind as we continue our tour.</para>
   4.376 +
   4.377 +    <para>Mercurial has a consistent and straightforward approach to
   4.378 +      dealing with the options that you can pass to commands.  It
   4.379 +      follows the conventions for options that are common to modern
   4.380 +      Linux and Unix systems.</para>
   4.381 +    <itemizedlist>
   4.382 +      <listitem><para>Every option has a long name.  For example, as
   4.383 +	  we've already seen, the <command role="hg-cmd">hg
   4.384 +	    log</command> command accepts a <option
   4.385 +	    role="hg-opt-log">--rev</option> option.</para></listitem>
   4.386 +      <listitem><para>Most options have short names, too.  Instead of
   4.387 +	  <option role="hg-opt-log">--rev</option>, we can use <option
   4.388 +	    role="hg-opt-log">-r</option>.  (The reason that some
   4.389 +	  options don't have short names is that the options in
   4.390 +	  question are rarely used.)</para></listitem>
   4.391 +      <listitem><para>Long options start with two dashes (e.g. <option
   4.392 +	    role="hg-opt-log">--rev</option>), while short options
   4.393 +	  start with one (e.g. <option
   4.394 +	    role="hg-opt-log">-r</option>).</para></listitem>
   4.395 +      <listitem><para>Option naming and usage is consistent across
   4.396 +	  commands.  For example, every command that lets you specify
   4.397 +	  a changeset ID or revision number accepts both <option
   4.398 +	    role="hg-opt-log">-r</option> and <option
   4.399 +	    role="hg-opt-log">--rev</option>
   4.400 +	  arguments.</para></listitem></itemizedlist>
   4.401 +    <para>In the examples throughout this book, I use short options
   4.402 +      instead of long.  This just reflects my own preference, so don't
   4.403 +      read anything significant into it.</para>
   4.404 +
   4.405 +    <para>Most commands that print output of some kind will print more
   4.406 +      output when passed a <option role="hg-opt-global">-v</option>
   4.407 +      (or <option role="hg-opt-global">--verbose</option>) option, and
   4.408 +      less when passed <option role="hg-opt-global">-q</option> (or
   4.409 +      <option role="hg-opt-global">--quiet</option>).</para>
   4.410 +
   4.411 +  </sect1>
   4.412 +  <sect1>
   4.413 +    <title>Making and reviewing changes</title>
   4.414 +
   4.415 +    <para>Now that we have a grasp of viewing history in Mercurial,
   4.416 +      let's take a look at making some changes and examining
   4.417 +      them.</para>
   4.418 +
   4.419 +    <para>The first thing we'll do is isolate our experiment in a
   4.420 +      repository of its own.  We use the <command role="hg-cmd">hg
   4.421 +	clone</command> command, but we don't need to clone a copy of
   4.422 +      the remote repository.  Since we already have a copy of it
   4.423 +      locally, we can just clone that instead.  This is much faster
   4.424 +      than cloning over the network, and cloning a local repository
   4.425 +      uses less disk space in most cases, too.</para>
   4.426 +
   4.427 +    &interaction.tour.reclone;
   4.428 +
   4.429 +    <para>As an aside, it's often good practice to keep a
   4.430 +      <quote>pristine</quote> copy of a remote repository around,
   4.431 +      which you can then make temporary clones of to create sandboxes
   4.432 +      for each task you want to work on.  This lets you work on
   4.433 +      multiple tasks in parallel, each isolated from the others until
   4.434 +      it's complete and you're ready to integrate it back.  Because
   4.435 +      local clones are so cheap, there's almost no overhead to cloning
   4.436 +      and destroying repositories whenever you want.</para>
   4.437 +
   4.438 +    <para>In our <filename class="directory">my-hello</filename>
   4.439 +      repository, we have a file <filename>hello.c</filename> that
   4.440 +      contains the classic <quote>hello, world</quote> program. Let's
   4.441 +      use the ancient and venerable <command>sed</command> command to
   4.442 +      edit this file so that it prints a second line of output.  (I'm
   4.443 +      only using <command>sed</command> to do this because it's easy
   4.444 +      to write a scripted example this way.  Since you're not under
   4.445 +      the same constraint, you probably won't want to use
   4.446 +      <command>sed</command>; simply use your preferred text editor to
   4.447 +      do the same thing.)</para>
   4.448 +
   4.449 +    &interaction.tour.sed;
   4.450 +
   4.451 +    <para>Mercurial's <command role="hg-cmd">hg status</command>
   4.452 +      command will tell us what Mercurial knows about the files in the
   4.453 +      repository.</para>
   4.454 +
   4.455 +    &interaction.tour.status;
   4.456 +
   4.457 +    <para>The <command role="hg-cmd">hg status</command> command
   4.458 +      prints no output for some files, but a line starting with
   4.459 +      <quote><literal>M</literal></quote> for
   4.460 +      <filename>hello.c</filename>.  Unless you tell it to, <command
   4.461 +	role="hg-cmd">hg status</command> will not print any output
   4.462 +      for files that have not been modified.</para>
   4.463 +
   4.464 +    <para>The <quote><literal>M</literal></quote> indicates that
   4.465 +      Mercurial has noticed that we modified
   4.466 +      <filename>hello.c</filename>.  We didn't need to
   4.467 +      <emphasis>inform</emphasis> Mercurial that we were going to
   4.468 +      modify the file before we started, or that we had modified the
   4.469 +      file after we were done; it was able to figure this out
   4.470 +      itself.</para>
   4.471 +
   4.472 +    <para>It's a little bit helpful to know that we've modified
   4.473 +      <filename>hello.c</filename>, but we might prefer to know
   4.474 +      exactly <emphasis>what</emphasis> changes we've made to it.  To
   4.475 +      do this, we use the <command role="hg-cmd">hg diff</command>
   4.476 +      command.</para>
   4.477 +
   4.478 +    &interaction.tour.diff;
   4.479 +
   4.480 +  </sect1>
   4.481 +  <sect1>
   4.482 +    <title>Recording changes in a new changeset</title>
   4.483 +
   4.484 +    <para>We can modify files, build and test our changes, and use
   4.485 +      <command role="hg-cmd">hg status</command> and <command
   4.486 +	role="hg-cmd">hg diff</command> to review our changes, until
   4.487 +      we're satisfied with what we've done and arrive at a natural
   4.488 +      stopping point where we want to record our work in a new
   4.489 +      changeset.</para>
   4.490 +
   4.491 +    <para>The <command role="hg-cmd">hg commit</command> command lets
   4.492 +      us create a new changeset; we'll usually refer to this as
   4.493 +      <quote>making a commit</quote> or
   4.494 +      <quote>committing</quote>.</para>
   4.495 +
   4.496 +    <sect2>
   4.497 +      <title>Setting up a username</title>
   4.498 +
   4.499 +      <para>When you try to run <command role="hg-cmd">hg
   4.500 +	  commit</command> for the first time, it is not guaranteed to
   4.501 +	succeed.  Mercurial records your name and address with each
   4.502 +	change that you commit, so that you and others will later be
   4.503 +	able to tell who made each change.  Mercurial tries to
   4.504 +	automatically figure out a sensible username to commit the
   4.505 +	change with.  It will attempt each of the following methods,
   4.506 +	in order:</para>
   4.507 +      <orderedlist>
   4.508 +	<listitem><para>If you specify a <option
   4.509 +	      role="hg-opt-commit">-u</option> option to the <command
   4.510 +	      role="hg-cmd">hg commit</command> command on the command
   4.511 +	    line, followed by a username, this is always given the
   4.512 +	    highest precedence.</para></listitem>
   4.513 +	<listitem><para>If you have set the <envar>HGUSER</envar>
   4.514 +	    environment variable, this is checked
   4.515 +	    next.</para></listitem>
   4.516 +	<listitem><para>If you create a file in your home directory
   4.517 +	    called <filename role="special">.hgrc</filename>, with a
   4.518 +	    <envar role="rc-item-ui">username</envar> entry, that will
   4.519 +	    be used next.  To see what the contents of this file
   4.520 +	    should look like, refer to section <xref
   4.521 +	      linkend="sec:tour-basic:username"/>
   4.522 +	    below.</para></listitem>
   4.523 +	<listitem><para>If you have set the <envar>EMAIL</envar>
   4.524 +	    environment variable, this will be used
   4.525 +	    next.</para></listitem>
   4.526 +	<listitem><para>Mercurial will query your system to find out
   4.527 +	    your local user name and host name, and construct a
   4.528 +	    username from these components. Since this often results
   4.529 +	    in a username that is not very useful, it will print a
   4.530 +	    warning if it has to do
   4.531 +	    this.</para></listitem>
   4.532 +      </orderedlist>
   4.533 +      <para>If all of these mechanisms fail, Mercurial will
   4.534 +	  fail, printing an error message.  In this case, it will not
   4.535 +	  let you commit until you set up a
   4.536 +	  username.</para>
   4.537 +      <para>You should think of the <envar>HGUSER</envar> environment
   4.538 +	variable and the <option role="hg-opt-commit">-u</option>
   4.539 +	option to the <command role="hg-cmd">hg commit</command>
   4.540 +	command as ways to <emphasis>override</emphasis> Mercurial's
   4.541 +	default selection of username.  For normal use, the simplest
   4.542 +	and most robust way to set a username for yourself is by
   4.543 +	creating a <filename role="special">.hgrc</filename> file; see
   4.544 +	below for details.</para>
   4.545 +      <sect3 id="sec:tour-basic:username">
   4.546 +	<title>Creating a Mercurial configuration file</title>
   4.547 +
   4.548 +	<para>To set a user name, use your favourite editor
   4.549 +	    to create a file called <filename
   4.550 +	      role="special">.hgrc</filename> in your home directory.
   4.551 +	    Mercurial will use this file to look up your personalised
   4.552 +	    configuration settings.  The initial contents of your
   4.553 +	    <filename role="special">.hgrc</filename> should look like
   4.554 +	    this.</para>
   4.555 +	<programlisting># This is a Mercurial configuration file.
   4.556 +[ui]
   4.557 +username = Firstname Lastname
   4.558 +&lt;email.address@domain.net&gt;</programlisting>
   4.559 +
   4.560 +	<para>The <quote><literal>[ui]</literal></quote> line begins a
   4.561 +	  <emphasis>section</emphasis> of the config file, so you can
   4.562 +	  read the <quote><literal>username = ...</literal></quote>
   4.563 +	  line as meaning <quote>set the value of the
   4.564 +	    <literal>username</literal> item in the
   4.565 +	    <literal>ui</literal> section</quote>. A section continues
   4.566 +	  until a new section begins, or the end of the file.
   4.567 +	  Mercurial ignores empty lines and treats any text from
   4.568 +	  <quote><literal>#</literal></quote> to the end of a line as
   4.569 +	  a comment.</para>
   4.570 +      </sect3>
   4.571 +
   4.572 +      <sect3>
   4.573 +	<title>Choosing a user name</title>
   4.574 +
   4.575 +	<para>You can use any text you like as the value of
   4.576 +	    the <literal>username</literal> config item, since this
   4.577 +	    information is for reading by other people, but for
   4.578 +	    interpreting by Mercurial.  The convention that most
   4.579 +	    people follow is to use their name and email address, as
   4.580 +	    in the example above.</para>
   4.581 +	<note>
   4.582 +	  <para>Mercurial's built-in web server obfuscates
   4.583 +	      email addresses, to make it more difficult for the email
   4.584 +	      harvesting tools that spammers use. This reduces the
   4.585 +	      likelihood that you'll start receiving more junk email
   4.586 +	      if you publish a Mercurial repository on the
   4.587 +	      web.</para></note>
   4.588 +
   4.589 +      </sect3>
   4.590 +    </sect2>
   4.591 +    <sect2>
   4.592 +      <title>Writing a commit message</title>
   4.593 +
   4.594 +      <para>When we commit a change, Mercurial drops us into
   4.595 +	  a text editor, to enter a message that will describe the
   4.596 +	  modifications we've made in this changeset.  This is called
   4.597 +	  the <emphasis>commit message</emphasis>.  It will be a
   4.598 +	  record for readers of what we did and why, and it will be
   4.599 +	  printed by <command role="hg-cmd">hg log</command> after
   4.600 +	  we've finished committing.</para>
   4.601 +
   4.602 +       &interaction.tour.commit;
   4.603 +
   4.604 +      <para>The editor that the <command role="hg-cmd">hg
   4.605 +	    commit</command> command drops us into will contain an
   4.606 +	  empty line, followed by a number of lines starting with
   4.607 +	  <quote><literal>HG:</literal></quote>.</para>
   4.608 +
   4.609 +    <programlisting>XXX fix this XXX</programlisting>
   4.610 +
   4.611 +      <para>Mercurial ignores the lines that start with
   4.612 +	  <quote><literal>HG:</literal></quote>; it uses them only to
   4.613 +	  tell us which files it's recording changes to.  Modifying or
   4.614 +	  deleting these lines has no effect.</para>
   4.615 +    </sect2>
   4.616 +    <sect2>
   4.617 +      <title>Writing a good commit message</title>
   4.618 +
   4.619 +      <para>Since <command role="hg-cmd">hg log</command>
   4.620 +	  only prints the first line of a commit message by default,
   4.621 +	  it's best to write a commit message whose first line stands
   4.622 +	  alone.  Here's a real example of a commit message that
   4.623 +	  <emphasis>doesn't</emphasis> follow this guideline, and
   4.624 +	  hence has a summary that is not
   4.625 +	  readable.</para>
   4.626 +
   4.627 +      <programlisting>
   4.628 +changeset:   73:584af0e231be
   4.629 +user:        Censored Person &lt;censored.person@example.org&gt;
   4.630 +date:        Tue Sep 26 21:37:07 2006 -0700
   4.631 +summary:     include buildmeister/commondefs. Add exports.</programlisting>
   4.632 +
   4.633 +      <para>As far as the remainder of the contents of the
   4.634 +	  commit message are concerned, there are no hard-and-fast
   4.635 +	  rules.  Mercurial itself doesn't interpret or care about the
   4.636 +	  contents of the commit message, though your project may have
   4.637 +	  policies that dictate a certain kind of
   4.638 +	  formatting.</para>
   4.639 +      <para>My personal preference is for short, but
   4.640 +	  informative, commit messages that tell me something that I
   4.641 +	  can't figure out with a quick glance at the output of
   4.642 +	  <command role="hg-cmd">hg log
   4.643 +	    --patch</command>.</para>
   4.644 +    </sect2>
   4.645 +    <sect2>
   4.646 +      <title>Aborting a commit</title>
   4.647 +
   4.648 +      <para>If you decide that you don't want to commit
   4.649 +	  while in the middle of editing a commit message, simply exit
   4.650 +	  from your editor without saving the file that it's editing.
   4.651 +	  This will cause nothing to happen to either the repository
   4.652 +	  or the working directory.</para>
   4.653 +      <para>If we run the <command role="hg-cmd">hg
   4.654 +	    commit</command> command without any arguments, it records
   4.655 +	  all of the changes we've made, as reported by <command
   4.656 +	    role="hg-cmd">hg status</command> and <command
   4.657 +	    role="hg-cmd">hg diff</command>.</para>
   4.658 +    </sect2>
   4.659 +    <sect2>
   4.660 +      <title>Admiring our new handiwork</title>
   4.661 +
   4.662 +      <para>Once we've finished the commit, we can use the
   4.663 +	  <command role="hg-cmd">hg tip</command> command to display
   4.664 +	  the changeset we just created.  This command produces output
   4.665 +	  that is identical to <command role="hg-cmd">hg
   4.666 +	    log</command>, but it only displays the newest revision in
   4.667 +	  the repository.</para>
   4.668 +
   4.669 +      &interaction.tour.tip;
   4.670 +
   4.671 +      <para>We refer to
   4.672 +	  the newest revision in the repository as the tip revision,
   4.673 +	  or simply the tip.</para>
   4.674 +    </sect2>
   4.675 +  </sect1>
   4.676 +
   4.677 +  <sect1>
   4.678 +    <title>Sharing changes</title>
   4.679 +
   4.680 +    <para>We mentioned earlier that repositories in
   4.681 +	Mercurial are self-contained.  This means that the changeset
   4.682 +	we just created exists only in our <filename
   4.683 +	  class="directory">my-hello</filename> repository.  Let's
   4.684 +	look at a few ways that we can propagate this change into
   4.685 +	other repositories.</para>
   4.686 +
   4.687 +    <sect2 id="sec:tour:pull">
   4.688 +      <title>Pulling changes from another repository</title>
   4.689 +      <para>To get started, let's clone our original
   4.690 +	  <filename class="directory">hello</filename> repository,
   4.691 +	  which does not contain the change we just committed.  We'll
   4.692 +	  call our temporary repository <filename
   4.693 +	    class="directory">hello-pull</filename>.</para>
   4.694 +
   4.695 +      &interaction.tour.clone-pull;
   4.696 +
   4.697 +      <para>We'll use the <command role="hg-cmd">hg
   4.698 +	    pull</command> command to bring changes from <filename
   4.699 +	    class="directory">my-hello</filename> into <filename
   4.700 +	    class="directory">hello-pull</filename>.  However, blindly
   4.701 +	  pulling unknown changes into a repository is a somewhat
   4.702 +	  scary prospect.  Mercurial provides the <command
   4.703 +	    role="hg-cmd">hg incoming</command> command to tell us
   4.704 +	  what changes the <command role="hg-cmd">hg pull</command>
   4.705 +	  command <emphasis>would</emphasis> pull into the repository,
   4.706 +	  without actually pulling the changes in.</para>
   4.707 +
   4.708 +      &interaction.tour.incoming;
   4.709 +
   4.710 +      <para>(Of course, someone could
   4.711 +	  cause more changesets to appear in the repository that we
   4.712 +	  ran <command role="hg-cmd">hg incoming</command> in, before
   4.713 +	  we get a chance to <command role="hg-cmd">hg pull</command>
   4.714 +	  the changes, so that we could end up pulling changes that we
   4.715 +	  didn't expect.)</para>
   4.716 +
   4.717 +      <para>Bringing changes into a repository is a simple
   4.718 +	  matter of running the <command role="hg-cmd">hg
   4.719 +	    pull</command> command, and telling it which repository to
   4.720 +	  pull from.</para>
   4.721 +
   4.722 +      &interaction.tour.pull;
   4.723 +
   4.724 +      <para>As you can see
   4.725 +	  from the before-and-after output of <command
   4.726 +	    role="hg-cmd">hg tip</command>, we have successfully
   4.727 +	  pulled changes into our repository.  There remains one step
   4.728 +	  before we can see these changes in the working
   4.729 +	  directory.</para>
   4.730 +    </sect2>
   4.731 +    <sect2>
   4.732 +      <title>Updating the working directory</title>
   4.733 +
   4.734 +      <para>We have so far glossed over the relationship between a
   4.735 +	repository and its working directory.  The <command
   4.736 +	  role="hg-cmd">hg pull</command> command that we ran in
   4.737 +	section <xref linkend="sec:tour:pull"/> brought changes
   4.738 +	into the repository, but if we check, there's no sign of those
   4.739 +	changes in the working directory.  This is because <command
   4.740 +	  role="hg-cmd">hg pull</command> does not (by default) touch
   4.741 +	the working directory.  Instead, we use the <command
   4.742 +	  role="hg-cmd">hg update</command> command to do this.</para>
   4.743 +
   4.744 +      &interaction.tour.update;
   4.745 +
   4.746 +      <para>It might seem a bit strange that <command role="hg-cmd">hg
   4.747 +	  pull</command> doesn't update the working directory
   4.748 +	automatically.  There's actually a good reason for this: you
   4.749 +	can use <command role="hg-cmd">hg update</command> to update
   4.750 +	the working directory to the state it was in at <emphasis>any
   4.751 +	  revision</emphasis> in the history of the repository.  If
   4.752 +	you had the working directory updated to an old revision---to
   4.753 +	hunt down the origin of a bug, say---and ran a <command
   4.754 +	  role="hg-cmd">hg pull</command> which automatically updated
   4.755 +	the working directory to a new revision, you might not be
   4.756 +	terribly happy.</para>
   4.757 +      <para>However, since pull-then-update is such a common thing to
   4.758 +	do, Mercurial lets you combine the two by passing the <option
   4.759 +	  role="hg-opt-pull">-u</option> option to <command
   4.760 +	  role="hg-cmd">hg pull</command>.</para>
   4.761 +
   4.762 +      <para>If you look back at the output of <command
   4.763 +	  role="hg-cmd">hg pull</command> in section <xref
   4.764 +	    linkend="sec:tour:pull"/> when we ran it without <option
   4.765 +	  role="hg-opt-pull">-u</option>, you can see that it printed
   4.766 +	a helpful reminder that we'd have to take an explicit step to
   4.767 +	update the working directory:</para>
   4.768 +
   4.769 +      <!-- &interaction.xxx.fixme; -->
   4.770 +
   4.771 +      <para>To find out what revision the working directory is at, use
   4.772 +	the <command role="hg-cmd">hg parents</command>
   4.773 +	command.</para>
   4.774 +
   4.775 +      &interaction.tour.parents;
   4.776 +
   4.777 +      <para>If you look back at figure <xref
   4.778 +	  linkend="fig:tour-basic:history"/>,
   4.779 +	you'll see arrows connecting each changeset.  The node that
   4.780 +	the arrow leads <emphasis>from</emphasis> in each case is a
   4.781 +	parent, and the node that the arrow leads
   4.782 +	<emphasis>to</emphasis> is its child.  The working directory
   4.783 +	has a parent in just the same way; this is the changeset that
   4.784 +	the working directory currently contains.</para>
   4.785 +
   4.786 +      <para>To update the working directory to a particular revision,
   4.787 +
   4.788 +	give a revision number or changeset ID to the <command
   4.789 +	  role="hg-cmd">hg update</command> command.</para>
   4.790 +
   4.791 +      &interaction.tour.older;
   4.792 +
   4.793 +      <para>If you omit an explicit revision, <command
   4.794 +	  role="hg-cmd">hg update</command> will update to the tip
   4.795 +	revision, as shown by the second call to <command
   4.796 +	  role="hg-cmd">hg update</command> in the example
   4.797 +	above.</para>
   4.798 +    </sect2>
   4.799 +
   4.800 +    <sect2>
   4.801 +      <title>Pushing changes to another repository</title>
   4.802 +
   4.803 +      <para>Mercurial lets us push changes to another
   4.804 +	  repository, from the repository we're currently visiting.
   4.805 +	  As with the example of <command role="hg-cmd">hg
   4.806 +	    pull</command> above, we'll create a temporary repository
   4.807 +	  to push our changes into.</para>
   4.808 +
   4.809 +      &interaction.tour.clone-push;
   4.810 +
   4.811 +      <para>The <command role="hg-cmd">hg outgoing</command> command
   4.812 +	  tells us what changes would be pushed into another
   4.813 +	  repository.</para>
   4.814 +
   4.815 +      &interaction.tour.outgoing;
   4.816 +
   4.817 +      <para>And the
   4.818 +	  <command role="hg-cmd">hg push</command> command does the
   4.819 +	  actual push.</para>
   4.820 +
   4.821 +      &interaction.tour.push;
   4.822 +
   4.823 +      <para>As with
   4.824 +	  <command role="hg-cmd">hg pull</command>, the <command
   4.825 +	    role="hg-cmd">hg push</command> command does not update
   4.826 +	  the working directory in the repository that it's pushing
   4.827 +	  changes into. (Unlike <command role="hg-cmd">hg
   4.828 +	    pull</command>, <command role="hg-cmd">hg push</command>
   4.829 +	  does not provide a <literal>-u</literal> option that updates
   4.830 +	  the other repository's working directory.)</para>
   4.831 +
   4.832 +      <para>What happens if we try to pull or push changes
   4.833 +	  and the receiving repository already has those changes?
   4.834 +	  Nothing too exciting.</para>
   4.835 +
   4.836 +      &interaction.tour.push.nothing;
   4.837 +    </sect2>
   4.838 +    <sect2>
   4.839 +      <title>Sharing changes over a network</title>
   4.840 +
   4.841 +      <para>The commands we have covered in the previous few
   4.842 +	  sections are not limited to working with local repositories.
   4.843 +	  Each works in exactly the same fashion over a network
   4.844 +	  connection; simply pass in a URL instead of a local
   4.845 +	  path.</para>
   4.846 +	
   4.847 +      &interaction.tour.outgoing.net;
   4.848 +
   4.849 +      <para>In this example, we
   4.850 +	  can see what changes we could push to the remote repository,
   4.851 +	  but the repository is understandably not set up to let
   4.852 +	  anonymous users push to it.</para>
   4.853 +
   4.854 +      &interaction.tour.push.net;
   4.855 +    </sect2>
   4.856 +  </sect1>
   4.857 +</chapter>
   4.858 +
   4.859 +<!--
   4.860 +local variables: 
   4.861 +sgml-parent-document: ("00book.xml" "book" "chapter")
   4.862 +end:
   4.863 +-->

     5.1 --- a/en/ch02-tour-basic.xml	Wed Mar 18 00:08:22 2009 -0700
     5.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.3 @@ -1,860 +0,0 @@
     5.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     5.5 -
     5.6 -<chapter id="chap:tour-basic">
     5.7 -  <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?>
     5.8 -  <title>A tour of Mercurial: the basics</title>
     5.9 -
    5.10 -  <sect1 id="sec:tour:install">
    5.11 -    <title>Installing Mercurial on your system</title>
    5.12 -
    5.13 -    <para>Prebuilt binary packages of Mercurial are available for
    5.14 -      every popular operating system.  These make it easy to start
    5.15 -      using Mercurial on your computer immediately.</para>
    5.16 -
    5.17 -    <sect2>
    5.18 -      <title>Linux</title>
    5.19 -
    5.20 -      <para>Because each Linux distribution has its own packaging
    5.21 -	tools, policies, and rate of development, it's difficult to
    5.22 -	give a comprehensive set of instructions on how to install
    5.23 -	Mercurial binaries.  The version of Mercurial that you will
    5.24 -	end up with can vary depending on how active the person is who
    5.25 -	maintains the package for your distribution.</para>
    5.26 -
    5.27 -      <para>To keep things simple, I will focus on installing
    5.28 -	Mercurial from the command line under the most popular Linux
    5.29 -	distributions.  Most of these distributions provide graphical
    5.30 -	package managers that will let you install Mercurial with a
    5.31 -	single click; the package name to look for is
    5.32 -	<literal>mercurial</literal>.</para>
    5.33 -
    5.34 -      <itemizedlist>
    5.35 -	<listitem><para>Debian:</para>
    5.36 -	  <programlisting>apt-get install mercurial</programlisting></listitem>
    5.37 -	<listitem><para>Fedora Core:</para>
    5.38 -	  <programlisting>yum install mercurial</programlisting></listitem>
    5.39 -	<listitem><para>Gentoo:</para>
    5.40 -	  <programlisting>emerge mercurial</programlisting></listitem>
    5.41 -	<listitem><para>OpenSUSE:</para>
    5.42 -	  <programlisting>yum install mercurial</programlisting></listitem>
    5.43 -	<listitem><para>Ubuntu: Ubuntu's Mercurial package is based on
    5.44 -	    Debian's.  To install it, run the following
    5.45 -	    command.</para>
    5.46 -	  <programlisting>apt-get install mercurial</programlisting></listitem>
    5.47 -      </itemizedlist>
    5.48 -
    5.49 -    </sect2>
    5.50 -    <sect2>
    5.51 -      <title>Solaris</title>
    5.52 -
    5.53 -      <para>SunFreeWare, at <ulink
    5.54 -	  url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 
    5.55 -	is a good source for a large number of pre-built Solaris
    5.56 -	packages for 32 and 64 bit Intel and Sparc architectures,
    5.57 -	including current versions of Mercurial.</para>
    5.58 -
    5.59 -    </sect2>
    5.60 -    <sect2>
    5.61 -      <title>Mac OS X</title>
    5.62 -
    5.63 -      <para>Lee Cantey publishes an installer of Mercurial for Mac OS
    5.64 -	X at <ulink
    5.65 -	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 
    5.66 -	This package works on both Intel- and Power-based Macs. Before
    5.67 -	you can use it, you must install a compatible version of
    5.68 -	Universal MacPython <citation>web:macpython</citation>. This
    5.69 -	is easy to do; simply follow the instructions on Lee's
    5.70 -	site.</para>
    5.71 -
    5.72 -      <para>It's also possible to install Mercurial using Fink or
    5.73 -	MacPorts, two popular free package managers for Mac OS X.  If
    5.74 -	you have Fink, use <command>sudo apt-get install
    5.75 -	  mercurial-py25</command>.  If MacPorts, <command>sudo port
    5.76 -	  install mercurial</command>.</para>
    5.77 -
    5.78 -    </sect2>
    5.79 -    <sect2>
    5.80 -      <title>Windows</title>
    5.81 -
    5.82 -      <para>Lee Cantey publishes an installer of Mercurial for Windows
    5.83 -	at <ulink
    5.84 -	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 
    5.85 -	This package has no external dependencies; it <quote>just
    5.86 -	  works</quote>.</para>
    5.87 -
    5.88 -      <note>
    5.89 -	<para>  The Windows version of Mercurial does not
    5.90 -	  automatically convert line endings between Windows and Unix
    5.91 -	  styles.  If you want to share work with Unix users, you must
    5.92 -	  do a little additional configuration work. XXX Flesh this
    5.93 -	  out.</para>
    5.94 -      </note>
    5.95 -
    5.96 -    </sect2>
    5.97 -  </sect1>
    5.98 -  <sect1>
    5.99 -    <title>Getting started</title>
   5.100 -
   5.101 -    <para>To begin, we'll use the <command role="hg-cmd">hg
   5.102 -	version</command> command to find out whether Mercurial is
   5.103 -      actually installed properly.  The actual version information
   5.104 -      that it prints isn't so important; it's whether it prints
   5.105 -      anything at all that we care about.</para>
   5.106 -
   5.107 -    &interaction.tour.version;
   5.108 -
   5.109 -    <sect2>
   5.110 -      <title>Built-in help</title>
   5.111 -
   5.112 -      <para>Mercurial provides a built-in help system.  This is
   5.113 -	  invaluable for those times when you find yourself stuck
   5.114 -	  trying to remember how to run a command.  If you are
   5.115 -	  completely stuck, simply run <command role="hg-cmd">hg
   5.116 -	    help</command>; it will print a brief list of commands,
   5.117 -	  along with a description of what each does.  If you ask for
   5.118 -	  help on a specific command (as below), it prints more
   5.119 -	  detailed information.</para>
   5.120 -
   5.121 -	&interaction.tour.help;
   5.122 -
   5.123 -	<para>For a more impressive level of detail (which you won't
   5.124 -	  usually need) run <command role="hg-cmd">hg help <option
   5.125 -	      role="hg-opt-global">-v</option></command>.  The <option
   5.126 -	    role="hg-opt-global">-v</option> option is short for
   5.127 -	  <option role="hg-opt-global">--verbose</option>, and tells
   5.128 -	  Mercurial to print more information than it usually
   5.129 -	  would.</para>
   5.130 -
   5.131 -    </sect2>
   5.132 -  </sect1>
   5.133 -  <sect1>
   5.134 -    <title>Working with a repository</title>
   5.135 -
   5.136 -    <para>In Mercurial, everything happens inside a
   5.137 -      <emphasis>repository</emphasis>.  The repository for a project
   5.138 -      contains all of the files that <quote>belong to</quote> that
   5.139 -      project, along with a historical record of the project's
   5.140 -      files.</para>
   5.141 -
   5.142 -    <para>There's nothing particularly magical about a repository; it
   5.143 -      is simply a directory tree in your filesystem that Mercurial
   5.144 -      treats as special. You can rename or delete a repository any
   5.145 -      time you like, using either the command line or your file
   5.146 -      browser.</para>
   5.147 -
   5.148 -    <sect2>
   5.149 -      <title>Making a local copy of a repository</title>
   5.150 -
   5.151 -      <para><emphasis>Copying</emphasis> a repository is just a little
   5.152 -	bit special.  While you could use a normal file copying
   5.153 -	command to make a copy of a repository, it's best to use a
   5.154 -	built-in command that Mercurial provides.  This command is
   5.155 -	called <command role="hg-cmd">hg clone</command>, because it
   5.156 -	creates an identical copy of an existing repository.</para>
   5.157 -
   5.158 -      &interaction.tour.clone;
   5.159 -
   5.160 -      <para>If our clone succeeded, we should now have a local
   5.161 -	directory called <filename class="directory">hello</filename>.
   5.162 -	This directory will contain some files.</para>
   5.163 -
   5.164 -      &interaction.tour.ls;
   5.165 -
   5.166 -      <para>These files have the same contents and history in our
   5.167 -	repository as they do in the repository we cloned.</para>
   5.168 -
   5.169 -      <para>Every Mercurial repository is complete, self-contained,
   5.170 -	and independent.  It contains its own private copy of a
   5.171 -	project's files and history.  A cloned repository remembers
   5.172 -	the location of the repository it was cloned from, but it does
   5.173 -	not communicate with that repository, or any other, unless you
   5.174 -	tell it to.</para>
   5.175 -
   5.176 -      <para>What this means for now is that we're free to experiment
   5.177 -	with our repository, safe in the knowledge that it's a private
   5.178 -	<quote>sandbox</quote> that won't affect anyone else.</para>
   5.179 -
   5.180 -    </sect2>
   5.181 -    <sect2>
   5.182 -      <title>What's in a repository?</title>
   5.183 -
   5.184 -      <para>When we take a more detailed look inside a repository, we
   5.185 -	can see that it contains a directory named <filename
   5.186 -	  class="directory">.hg</filename>.  This is where Mercurial
   5.187 -	keeps all of its metadata for the repository.</para>
   5.188 -
   5.189 -      &interaction.tour.ls-a;
   5.190 -
   5.191 -      <para>The contents of the <filename
   5.192 -	  class="directory">.hg</filename> directory and its
   5.193 -	subdirectories are private to Mercurial.  Every other file and
   5.194 -	directory in the repository is yours to do with as you
   5.195 -	please.</para>
   5.196 -
   5.197 -      <para>To introduce a little terminology, the <filename
   5.198 -	  class="directory">.hg</filename> directory is the
   5.199 -	<quote>real</quote> repository, and all of the files and
   5.200 -	directories that coexist with it are said to live in the
   5.201 -	<emphasis>working directory</emphasis>.  An easy way to
   5.202 -	remember the distinction is that the
   5.203 -	<emphasis>repository</emphasis> contains the
   5.204 -	<emphasis>history</emphasis> of your project, while the
   5.205 -	<emphasis>working directory</emphasis> contains a
   5.206 -	<emphasis>snapshot</emphasis> of your project at a particular
   5.207 -	point in history.</para>
   5.208 -
   5.209 -    </sect2>
   5.210 -  </sect1>
   5.211 -  <sect1>
   5.212 -    <title>A tour through history</title>
   5.213 -
   5.214 -    <para>One of the first things we might want to do with a new,
   5.215 -      unfamiliar repository is understand its history.  The <command
   5.216 -	role="hg-cmd">hg log</command> command gives us a view of
   5.217 -      history.</para>
   5.218 -
   5.219 -    &interaction.tour.log;
   5.220 -
   5.221 -    <para>By default, this command prints a brief paragraph of output
   5.222 -      for each change to the project that was recorded.  In Mercurial
   5.223 -      terminology, we call each of these recorded events a
   5.224 -      <emphasis>changeset</emphasis>, because it can contain a record
   5.225 -      of changes to several files.</para>
   5.226 -
   5.227 -    <para>The fields in a record of output from <command
   5.228 -	role="hg-cmd">hg log</command> are as follows.</para>
   5.229 -    <itemizedlist>
   5.230 -      <listitem><para><literal>changeset</literal>: This field has the
   5.231 -	  format of a number, followed by a colon, followed by a
   5.232 -	  hexadecimal string.  These are
   5.233 -	  <emphasis>identifiers</emphasis> for the changeset.  There
   5.234 -	  are two identifiers because the number is shorter and easier
   5.235 -	  to type than the hex string.</para></listitem>
   5.236 -      <listitem><para><literal>user</literal>: The identity of the
   5.237 -	  person who created the changeset.  This is a free-form
   5.238 -	  field, but it most often contains a person's name and email
   5.239 -	  address.</para></listitem>
   5.240 -      <listitem><para><literal>date</literal>: The date and time on
   5.241 -	  which the changeset was created, and the timezone in which
   5.242 -	  it was created.  (The date and time are local to that
   5.243 -	  timezone; they display what time and date it was for the
   5.244 -	  person who created the changeset.)</para></listitem>
   5.245 -      <listitem><para><literal>summary</literal>: The first line of
   5.246 -	  the text message that the creator of the changeset entered
   5.247 -	  to describe the changeset.</para></listitem></itemizedlist>
   5.248 -    <para>The default output printed by <command role="hg-cmd">hg
   5.249 -	log</command> is purely a summary; it is missing a lot of
   5.250 -      detail.</para>
   5.251 -
   5.252 -    <para>Figure <xref linkend="fig:tour-basic:history"/> provides a
   5.253 -      graphical representation of the history of the <filename
   5.254 -	class="directory">hello</filename> repository, to make it a
   5.255 -      little easier to see which direction history is
   5.256 -      <quote>flowing</quote> in.  We'll be returning to this figure
   5.257 -      several times in this chapter and the chapter that
   5.258 -      follows.</para>
   5.259 -
   5.260 -    <informalfigure id="fig:tour-basic:history">
   5.261 -      <mediaobject>
   5.262 -	<imageobject><imagedata fileref="tour-history"/></imageobject>
   5.263 -	<textobject><phrase>XXX add text</phrase></textobject>
   5.264 -	<caption><para>Graphical history of the <filename
   5.265 -	      class="directory">hello</filename>
   5.266 -	    repository</para></caption>
   5.267 -      </mediaobject>
   5.268 -    </informalfigure>
   5.269 -
   5.270 -    <sect2>
   5.271 -      <title>Changesets, revisions, and talking to other
   5.272 -	people</title>
   5.273 -
   5.274 -      <para>As English is a notoriously sloppy language, and computer
   5.275 -	science has a hallowed history of terminological confusion
   5.276 -	(why use one term when four will do?), revision control has a
   5.277 -	variety of words and phrases that mean the same thing.  If you
   5.278 -	are talking about Mercurial history with other people, you
   5.279 -	will find that the word <quote>changeset</quote> is often
   5.280 -	compressed to <quote>change</quote> or (when written)
   5.281 -	<quote>cset</quote>, and sometimes a changeset is referred to
   5.282 -	as a <quote>revision</quote> or a <quote>rev</quote>.</para>
   5.283 -
   5.284 -      <para>While it doesn't matter what <emphasis>word</emphasis> you
   5.285 -	use to refer to the concept of <quote>a changeset</quote>, the
   5.286 -	<emphasis>identifier</emphasis> that you use to refer to
   5.287 -	<quote>a <emphasis>specific</emphasis> changeset</quote> is of
   5.288 -	great importance. Recall that the <literal>changeset</literal>
   5.289 -	field in the output from <command role="hg-cmd">hg
   5.290 -	  log</command> identifies a changeset using both a number and
   5.291 -	a hexadecimal string.</para>
   5.292 -      <itemizedlist>
   5.293 -	<listitem><para>The revision number is <emphasis>only valid in
   5.294 -	      that repository</emphasis>,</para></listitem>
   5.295 -	<listitem><para>while the hex string is the
   5.296 -	    <emphasis>permanent, unchanging identifier</emphasis> that
   5.297 -	    will always identify that exact changeset in
   5.298 -	    <emphasis>every</emphasis> copy of the
   5.299 -	    repository.</para></listitem></itemizedlist>
   5.300 -      <para>This distinction is important.  If you send someone an
   5.301 -	email talking about <quote>revision 33</quote>, there's a high
   5.302 -	likelihood that their revision 33 will <emphasis>not be the
   5.303 -	  same</emphasis> as yours.  The reason for this is that a
   5.304 -	revision number depends on the order in which changes arrived
   5.305 -	in a repository, and there is no guarantee that the same
   5.306 -	changes will happen in the same order in different
   5.307 -	repositories. Three changes $a,b,c$ can easily appear in one
   5.308 -	repository as $0,1,2$, while in another as $1,0,2$.</para>
   5.309 -
   5.310 -      <para>Mercurial uses revision numbers purely as a convenient
   5.311 -	shorthand.  If you need to discuss a changeset with someone,
   5.312 -	or make a record of a changeset for some other reason (for
   5.313 -	example, in a bug report), use the hexadecimal
   5.314 -	identifier.</para>
   5.315 -
   5.316 -    </sect2>
   5.317 -    <sect2>
   5.318 -      <title>Viewing specific revisions</title>
   5.319 -
   5.320 -      <para>To narrow the output of <command role="hg-cmd">hg
   5.321 -	  log</command> down to a single revision, use the <option
   5.322 -	  role="hg-opt-log">-r</option> (or <option
   5.323 -	  role="hg-opt-log">--rev</option>) option.  You can use
   5.324 -	either a revision number or a long-form changeset identifier,
   5.325 -	and you can provide as many revisions as you want.</para>
   5.326 -
   5.327 -      &interaction.tour.log-r;
   5.328 -
   5.329 -      <para>If you want to see the history of several revisions
   5.330 -	without having to list each one, you can use <emphasis>range
   5.331 -	  notation</emphasis>; this lets you express the idea <quote>I
   5.332 -	  want all revisions between <literal>abc</literal> and
   5.333 -	  <literal>def</literal>, inclusive</quote>.</para>
   5.334 -      
   5.335 -	&interaction.tour.log.range;
   5.336 -
   5.337 -      <para>Mercurial also honours the order in which you specify
   5.338 -	revisions, so <command role="hg-cmd">hg log -r 2:4</command>
   5.339 -	prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
   5.340 -	  4:2</command> prints 4, 3, and 2.</para>
   5.341 -
   5.342 -    </sect2>
   5.343 -    <sect2>
   5.344 -      <title>More detailed information</title>
   5.345 -
   5.346 -      <para>While the summary information printed by <command
   5.347 -	  role="hg-cmd">hg log</command> is useful if you already know
   5.348 -	what you're looking for, you may need to see a complete
   5.349 -	description of the change, or a list of the files changed, if
   5.350 -	you're trying to decide whether a changeset is the one you're
   5.351 -	looking for. The <command role="hg-cmd">hg log</command>
   5.352 -	command's <option role="hg-opt-global">-v</option> (or <option
   5.353 -	  role="hg-opt-global">--verbose</option>) option gives you
   5.354 -	this extra detail.</para>
   5.355 -
   5.356 -      &interaction.tour.log-v;
   5.357 -
   5.358 -      <para>If you want to see both the description and content of a
   5.359 -	change, add the <option role="hg-opt-log">-p</option> (or
   5.360 -	<option role="hg-opt-log">--patch</option>) option.  This
   5.361 -	displays the content of a change as a <emphasis>unified
   5.362 -	  diff</emphasis> (if you've never seen a unified diff before,
   5.363 -	see section <xref linkend="sec:mq:patch"/> for an
   5.364 -	overview).</para>
   5.365 -
   5.366 -      &interaction.tour.log-vp;
   5.367 -
   5.368 -    </sect2>
   5.369 -  </sect1>
   5.370 -  <sect1>
   5.371 -    <title>All about command options</title>
   5.372 -
   5.373 -    <para>Let's take a brief break from exploring Mercurial commands
   5.374 -      to discuss a pattern in the way that they work; you may find
   5.375 -      this useful to keep in mind as we continue our tour.</para>
   5.376 -
   5.377 -    <para>Mercurial has a consistent and straightforward approach to
   5.378 -      dealing with the options that you can pass to commands.  It
   5.379 -      follows the conventions for options that are common to modern
   5.380 -      Linux and Unix systems.</para>
   5.381 -    <itemizedlist>
   5.382 -      <listitem><para>Every option has a long name.  For example, as
   5.383 -	  we've already seen, the <command role="hg-cmd">hg
   5.384 -	    log</command> command accepts a <option
   5.385 -	    role="hg-opt-log">--rev</option> option.</para></listitem>
   5.386 -      <listitem><para>Most options have short names, too.  Instead of
   5.387 -	  <option role="hg-opt-log">--rev</option>, we can use <option
   5.388 -	    role="hg-opt-log">-r</option>.  (The reason that some
   5.389 -	  options don't have short names is that the options in
   5.390 -	  question are rarely used.)</para></listitem>
   5.391 -      <listitem><para>Long options start with two dashes (e.g. <option
   5.392 -	    role="hg-opt-log">--rev</option>), while short options
   5.393 -	  start with one (e.g. <option
   5.394 -	    role="hg-opt-log">-r</option>).</para></listitem>
   5.395 -      <listitem><para>Option naming and usage is consistent across
   5.396 -	  commands.  For example, every command that lets you specify
   5.397 -	  a changeset ID or revision number accepts both <option
   5.398 -	    role="hg-opt-log">-r</option> and <option
   5.399 -	    role="hg-opt-log">--rev</option>
   5.400 -	  arguments.</para></listitem></itemizedlist>
   5.401 -    <para>In the examples throughout this book, I use short options
   5.402 -      instead of long.  This just reflects my own preference, so don't
   5.403 -      read anything significant into it.</para>
   5.404 -
   5.405 -    <para>Most commands that print output of some kind will print more
   5.406 -      output when passed a <option role="hg-opt-global">-v</option>
   5.407 -      (or <option role="hg-opt-global">--verbose</option>) option, and
   5.408 -      less when passed <option role="hg-opt-global">-q</option> (or
   5.409 -      <option role="hg-opt-global">--quiet</option>).</para>
   5.410 -
   5.411 -  </sect1>
   5.412 -  <sect1>
   5.413 -    <title>Making and reviewing changes</title>
   5.414 -
   5.415 -    <para>Now that we have a grasp of viewing history in Mercurial,
   5.416 -      let's take a look at making some changes and examining
   5.417 -      them.</para>
   5.418 -
   5.419 -    <para>The first thing we'll do is isolate our experiment in a
   5.420 -      repository of its own.  We use the <command role="hg-cmd">hg
   5.421 -	clone</command> command, but we don't need to clone a copy of
   5.422 -      the remote repository.  Since we already have a copy of it
   5.423 -      locally, we can just clone that instead.  This is much faster
   5.424 -      than cloning over the network, and cloning a local repository
   5.425 -      uses less disk space in most cases, too.</para>
   5.426 -
   5.427 -    &interaction.tour.reclone;
   5.428 -
   5.429 -    <para>As an aside, it's often good practice to keep a
   5.430 -      <quote>pristine</quote> copy of a remote repository around,
   5.431 -      which you can then make temporary clones of to create sandboxes
   5.432 -      for each task you want to work on.  This lets you work on
   5.433 -      multiple tasks in parallel, each isolated from the others until
   5.434 -      it's complete and you're ready to integrate it back.  Because
   5.435 -      local clones are so cheap, there's almost no overhead to cloning
   5.436 -      and destroying repositories whenever you want.</para>
   5.437 -
   5.438 -    <para>In our <filename class="directory">my-hello</filename>
   5.439 -      repository, we have a file <filename>hello.c</filename> that
   5.440 -      contains the classic <quote>hello, world</quote> program. Let's
   5.441 -      use the ancient and venerable <command>sed</command> command to
   5.442 -      edit this file so that it prints a second line of output.  (I'm
   5.443 -      only using <command>sed</command> to do this because it's easy
   5.444 -      to write a scripted example this way.  Since you're not under
   5.445 -      the same constraint, you probably won't want to use
   5.446 -      <command>sed</command>; simply use your preferred text editor to
   5.447 -      do the same thing.)</para>
   5.448 -
   5.449 -    &interaction.tour.sed;
   5.450 -
   5.451 -    <para>Mercurial's <command role="hg-cmd">hg status</command>
   5.452 -      command will tell us what Mercurial knows about the files in the
   5.453 -      repository.</para>
   5.454 -
   5.455 -    &interaction.tour.status;
   5.456 -
   5.457 -    <para>The <command role="hg-cmd">hg status</command> command
   5.458 -      prints no output for some files, but a line starting with
   5.459 -      <quote><literal>M</literal></quote> for
   5.460 -      <filename>hello.c</filename>.  Unless you tell it to, <command
   5.461 -	role="hg-cmd">hg status</command> will not print any output
   5.462 -      for files that have not been modified.</para>
   5.463 -
   5.464 -    <para>The <quote><literal>M</literal></quote> indicates that
   5.465 -      Mercurial has noticed that we modified
   5.466 -      <filename>hello.c</filename>.  We didn't need to
   5.467 -      <emphasis>inform</emphasis> Mercurial that we were going to
   5.468 -      modify the file before we started, or that we had modified the
   5.469 -      file after we were done; it was able to figure this out
   5.470 -      itself.</para>
   5.471 -
   5.472 -    <para>It's a little bit helpful to know that we've modified
   5.473 -      <filename>hello.c</filename>, but we might prefer to know
   5.474 -      exactly <emphasis>what</emphasis> changes we've made to it.  To
   5.475 -      do this, we use the <command role="hg-cmd">hg diff</command>
   5.476 -      command.</para>
   5.477 -
   5.478 -    &interaction.tour.diff;
   5.479 -
   5.480 -  </sect1>
   5.481 -  <sect1>
   5.482 -    <title>Recording changes in a new changeset</title>
   5.483 -
   5.484 -    <para>We can modify files, build and test our changes, and use
   5.485 -      <command role="hg-cmd">hg status</command> and <command
   5.486 -	role="hg-cmd">hg diff</command> to review our changes, until
   5.487 -      we're satisfied with what we've done and arrive at a natural
   5.488 -      stopping point where we want to record our work in a new
   5.489 -      changeset.</para>
   5.490 -
   5.491 -    <para>The <command role="hg-cmd">hg commit</command> command lets
   5.492 -      us create a new changeset; we'll usually refer to this as
   5.493 -      <quote>making a commit</quote> or
   5.494 -      <quote>committing</quote>.</para>
   5.495 -
   5.496 -    <sect2>
   5.497 -      <title>Setting up a username</title>
   5.498 -
   5.499 -      <para>When you try to run <command role="hg-cmd">hg
   5.500 -	  commit</command> for the first time, it is not guaranteed to
   5.501 -	succeed.  Mercurial records your name and address with each
   5.502 -	change that you commit, so that you and others will later be
   5.503 -	able to tell who made each change.  Mercurial tries to
   5.504 -	automatically figure out a sensible username to commit the
   5.505 -	change with.  It will attempt each of the following methods,
   5.506 -	in order:</para>
   5.507 -      <orderedlist>
   5.508 -	<listitem><para>If you specify a <option
   5.509 -	      role="hg-opt-commit">-u</option> option to the <command
   5.510 -	      role="hg-cmd">hg commit</command> command on the command
   5.511 -	    line, followed by a username, this is always given the
   5.512 -	    highest precedence.</para></listitem>
   5.513 -	<listitem><para>If you have set the <envar>HGUSER</envar>
   5.514 -	    environment variable, this is checked
   5.515 -	    next.</para></listitem>
   5.516 -	<listitem><para>If you create a file in your home directory
   5.517 -	    called <filename role="special">.hgrc</filename>, with a
   5.518 -	    <envar role="rc-item-ui">username</envar> entry, that will
   5.519 -	    be used next.  To see what the contents of this file
   5.520 -	    should look like, refer to section <xref
   5.521 -	      linkend="sec:tour-basic:username"/>
   5.522 -	    below.</para></listitem>
   5.523 -	<listitem><para>If you have set the <envar>EMAIL</envar>
   5.524 -	    environment variable, this will be used
   5.525 -	    next.</para></listitem>
   5.526 -	<listitem><para>Mercurial will query your system to find out
   5.527 -	    your local user name and host name, and construct a
   5.528 -	    username from these components. Since this often results
   5.529 -	    in a username that is not very useful, it will print a
   5.530 -	    warning if it has to do
   5.531 -	    this.</para></listitem>
   5.532 -      </orderedlist>
   5.533 -      <para>If all of these mechanisms fail, Mercurial will
   5.534 -	  fail, printing an error message.  In this case, it will not
   5.535 -	  let you commit until you set up a
   5.536 -	  username.</para>
   5.537 -      <para>You should think of the <envar>HGUSER</envar> environment
   5.538 -	variable and the <option role="hg-opt-commit">-u</option>
   5.539 -	option to the <command role="hg-cmd">hg commit</command>
   5.540 -	command as ways to <emphasis>override</emphasis> Mercurial's
   5.541 -	default selection of username.  For normal use, the simplest
   5.542 -	and most robust way to set a username for yourself is by
   5.543 -	creating a <filename role="special">.hgrc</filename> file; see
   5.544 -	below for details.</para>
   5.545 -      <sect3 id="sec:tour-basic:username">
   5.546 -	<title>Creating a Mercurial configuration file</title>
   5.547 -
   5.548 -	<para>To set a user name, use your favourite editor
   5.549 -	    to create a file called <filename
   5.550 -	      role="special">.hgrc</filename> in your home directory.
   5.551 -	    Mercurial will use this file to look up your personalised
   5.552 -	    configuration settings.  The initial contents of your
   5.553 -	    <filename role="special">.hgrc</filename> should look like
   5.554 -	    this.</para>
   5.555 -	<programlisting># This is a Mercurial configuration file.
   5.556 -[ui]
   5.557 -username = Firstname Lastname
   5.558 -&lt;email.address@domain.net&gt;</programlisting>
   5.559 -
   5.560 -	<para>The <quote><literal>[ui]</literal></quote> line begins a
   5.561 -	  <emphasis>section</emphasis> of the config file, so you can
   5.562 -	  read the <quote><literal>username = ...</literal></quote>
   5.563 -	  line as meaning <quote>set the value of the
   5.564 -	    <literal>username</literal> item in the
   5.565 -	    <literal>ui</literal> section</quote>. A section continues
   5.566 -	  until a new section begins, or the end of the file.
   5.567 -	  Mercurial ignores empty lines and treats any text from
   5.568 -	  <quote><literal>#</literal></quote> to the end of a line as
   5.569 -	  a comment.</para>
   5.570 -      </sect3>
   5.571 -
   5.572 -      <sect3>
   5.573 -	<title>Choosing a user name</title>
   5.574 -
   5.575 -	<para>You can use any text you like as the value of
   5.576 -	    the <literal>username</literal> config item, since this
   5.577 -	    information is for reading by other people, but for
   5.578 -	    interpreting by Mercurial.  The convention that most
   5.579 -	    people follow is to use their name and email address, as
   5.580 -	    in the example above.</para>
   5.581 -	<note>
   5.582 -	  <para>Mercurial's built-in web server obfuscates
   5.583 -	      email addresses, to make it more difficult for the email
   5.584 -	      harvesting tools that spammers use. This reduces the
   5.585 -	      likelihood that you'll start receiving more junk email
   5.586 -	      if you publish a Mercurial repository on the
   5.587 -	      web.</para></note>
   5.588 -
   5.589 -      </sect3>
   5.590 -    </sect2>
   5.591 -    <sect2>
   5.592 -      <title>Writing a commit message</title>
   5.593 -
   5.594 -      <para>When we commit a change, Mercurial drops us into
   5.595 -	  a text editor, to enter a message that will describe the
   5.596 -	  modifications we've made in this changeset.  This is called
   5.597 -	  the <emphasis>commit message</emphasis>.  It will be a
   5.598 -	  record for readers of what we did and why, and it will be
   5.599 -	  printed by <command role="hg-cmd">hg log</command> after
   5.600 -	  we've finished committing.</para>
   5.601 -
   5.602 -       &interaction.tour.commit;
   5.603 -
   5.604 -      <para>The editor that the <command role="hg-cmd">hg
   5.605 -	    commit</command> command drops us into will contain an
   5.606 -	  empty line, followed by a number of lines starting with
   5.607 -	  <quote><literal>HG:</literal></quote>.</para>
   5.608 -
   5.609 -    <programlisting>XXX fix this XXX</programlisting>
   5.610 -
   5.611 -      <para>Mercurial ignores the lines that start with
   5.612 -	  <quote><literal>HG:</literal></quote>; it uses them only to
   5.613 -	  tell us which files it's recording changes to.  Modifying or
   5.614 -	  deleting these lines has no effect.</para>
   5.615 -    </sect2>
   5.616 -    <sect2>
   5.617 -      <title>Writing a good commit message</title>
   5.618 -
   5.619 -      <para>Since <command role="hg-cmd">hg log</command>
   5.620 -	  only prints the first line of a commit message by default,
   5.621 -	  it's best to write a commit message whose first line stands
   5.622 -	  alone.  Here's a real example of a commit message that
   5.623 -	  <emphasis>doesn't</emphasis> follow this guideline, and
   5.624 -	  hence has a summary that is not
   5.625 -	  readable.</para>
   5.626 -
   5.627 -      <programlisting>
   5.628 -changeset:   73:584af0e231be
   5.629 -user:        Censored Person &lt;censored.person@example.org&gt;
   5.630 -date:        Tue Sep 26 21:37:07 2006 -0700
   5.631 -summary:     include buildmeister/commondefs. Add exports.</programlisting>
   5.632 -
   5.633 -      <para>As far as the remainder of the contents of the
   5.634 -	  commit message are concerned, there are no hard-and-fast
   5.635 -	  rules.  Mercurial itself doesn't interpret or care about the
   5.636 -	  contents of the commit message, though your project may have
   5.637 -	  policies that dictate a certain kind of
   5.638 -	  formatting.</para>
   5.639 -      <para>My personal preference is for short, but
   5.640 -	  informative, commit messages that tell me something that I
   5.641 -	  can't figure out with a quick glance at the output of
   5.642 -	  <command role="hg-cmd">hg log
   5.643 -	    --patch</command>.</para>
   5.644 -    </sect2>
   5.645 -    <sect2>
   5.646 -      <title>Aborting a commit</title>
   5.647 -
   5.648 -      <para>If you decide that you don't want to commit
   5.649 -	  while in the middle of editing a commit message, simply exit
   5.650 -	  from your editor without saving the file that it's editing.
   5.651 -	  This will cause nothing to happen to either the repository
   5.652 -	  or the working directory.</para>
   5.653 -      <para>If we run the <command role="hg-cmd">hg
   5.654 -	    commit</command> command without any arguments, it records
   5.655 -	  all of the changes we've made, as reported by <command
   5.656 -	    role="hg-cmd">hg status</command> and <command
   5.657 -	    role="hg-cmd">hg diff</command>.</para>
   5.658 -    </sect2>
   5.659 -    <sect2>
   5.660 -      <title>Admiring our new handiwork</title>
   5.661 -
   5.662 -      <para>Once we've finished the commit, we can use the
   5.663 -	  <command role="hg-cmd">hg tip</command> command to display
   5.664 -	  the changeset we just created.  This command produces output
   5.665 -	  that is identical to <command role="hg-cmd">hg
   5.666 -	    log</command>, but it only displays the newest revision in
   5.667 -	  the repository.</para>
   5.668 -
   5.669 -      &interaction.tour.tip;
   5.670 -
   5.671 -      <para>We refer to
   5.672 -	  the newest revision in the repository as the tip revision,
   5.673 -	  or simply the tip.</para>
   5.674 -    </sect2>
   5.675 -  </sect1>
   5.676 -
   5.677 -  <sect1>
   5.678 -    <title>Sharing changes</title>
   5.679 -
   5.680 -    <para>We mentioned earlier that repositories in
   5.681 -	Mercurial are self-contained.  This means that the changeset
   5.682 -	we just created exists only in our <filename
   5.683 -	  class="directory">my-hello</filename> repository.  Let's
   5.684 -	look at a few ways that we can propagate this change into
   5.685 -	other repositories.</para>
   5.686 -
   5.687 -    <sect2 id="sec:tour:pull">
   5.688 -      <title>Pulling changes from another repository</title>
   5.689 -      <para>To get started, let's clone our original
   5.690 -	  <filename class="directory">hello</filename> repository,
   5.691 -	  which does not contain the change we just committed.  We'll
   5.692 -	  call our temporary repository <filename
   5.693 -	    class="directory">hello-pull</filename>.</para>
   5.694 -
   5.695 -      &interaction.tour.clone-pull;
   5.696 -
   5.697 -      <para>We'll use the <command role="hg-cmd">hg
   5.698 -	    pull</command> command to bring changes from <filename
   5.699 -	    class="directory">my-hello</filename> into <filename
   5.700 -	    class="directory">hello-pull</filename>.  However, blindly
   5.701 -	  pulling unknown changes into a repository is a somewhat
   5.702 -	  scary prospect.  Mercurial provides the <command
   5.703 -	    role="hg-cmd">hg incoming</command> command to tell us
   5.704 -	  what changes the <command role="hg-cmd">hg pull</command>
   5.705 -	  command <emphasis>would</emphasis> pull into the repository,
   5.706 -	  without actually pulling the changes in.</para>
   5.707 -
   5.708 -      &interaction.tour.incoming;
   5.709 -
   5.710 -      <para>(Of course, someone could
   5.711 -	  cause more changesets to appear in the repository that we
   5.712 -	  ran <command role="hg-cmd">hg incoming</command> in, before
   5.713 -	  we get a chance to <command role="hg-cmd">hg pull</command>
   5.714 -	  the changes, so that we could end up pulling changes that we
   5.715 -	  didn't expect.)</para>
   5.716 -
   5.717 -      <para>Bringing changes into a repository is a simple
   5.718 -	  matter of running the <command role="hg-cmd">hg
   5.719 -	    pull</command> command, and telling it which repository to
   5.720 -	  pull from.</para>
   5.721 -
   5.722 -      &interaction.tour.pull;
   5.723 -
   5.724 -      <para>As you can see
   5.725 -	  from the before-and-after output of <command
   5.726 -	    role="hg-cmd">hg tip</command>, we have successfully
   5.727 -	  pulled changes into our repository.  There remains one step
   5.728 -	  before we can see these changes in the working
   5.729 -	  directory.</para>
   5.730 -    </sect2>
   5.731 -    <sect2>
   5.732 -      <title>Updating the working directory</title>
   5.733 -
   5.734 -      <para>We have so far glossed over the relationship between a
   5.735 -	repository and its working directory.  The <command
   5.736 -	  role="hg-cmd">hg pull</command> command that we ran in
   5.737 -	section <xref linkend="sec:tour:pull"/> brought changes
   5.738 -	into the repository, but if we check, there's no sign of those
   5.739 -	changes in the working directory.  This is because <command
   5.740 -	  role="hg-cmd">hg pull</command> does not (by default) touch
   5.741 -	the working directory.  Instead, we use the <command
   5.742 -	  role="hg-cmd">hg update</command> command to do this.</para>
   5.743 -
   5.744 -      &interaction.tour.update;
   5.745 -
   5.746 -      <para>It might seem a bit strange that <command role="hg-cmd">hg
   5.747 -	  pull</command> doesn't update the working directory
   5.748 -	automatically.  There's actually a good reason for this: you
   5.749 -	can use <command role="hg-cmd">hg update</command> to update
   5.750 -	the working directory to the state it was in at <emphasis>any
   5.751 -	  revision</emphasis> in the history of the repository.  If
   5.752 -	you had the working directory updated to an old revision---to
   5.753 -	hunt down the origin of a bug, say---and ran a <command
   5.754 -	  role="hg-cmd">hg pull</command> which automatically updated
   5.755 -	the working directory to a new revision, you might not be
   5.756 -	terribly happy.</para>
   5.757 -      <para>However, since pull-then-update is such a common thing to
   5.758 -	do, Mercurial lets you combine the two by passing the <option
   5.759 -	  role="hg-opt-pull">-u</option> option to <command
   5.760 -	  role="hg-cmd">hg pull</command>.</para>
   5.761 -
   5.762 -      <para>If you look back at the output of <command
   5.763 -	  role="hg-cmd">hg pull</command> in section <xref
   5.764 -	    linkend="sec:tour:pull"/> when we ran it without <option
   5.765 -	  role="hg-opt-pull">-u</option>, you can see that it printed
   5.766 -	a helpful reminder that we'd have to take an explicit step to
   5.767 -	update the working directory:</para>
   5.768 -
   5.769 -      <!-- &interaction.xxx.fixme; -->
   5.770 -
   5.771 -      <para>To find out what revision the working directory is at, use
   5.772 -	the <command role="hg-cmd">hg parents</command>
   5.773 -	command.</para>
   5.774 -
   5.775 -      &interaction.tour.parents;
   5.776 -
   5.777 -      <para>If you look back at figure <xref
   5.778 -	  linkend="fig:tour-basic:history"/>,
   5.779 -	you'll see arrows connecting each changeset.  The node that
   5.780 -	the arrow leads <emphasis>from</emphasis> in each case is a
   5.781 -	parent, and the node that the arrow leads
   5.782 -	<emphasis>to</emphasis> is its child.  The working directory
   5.783 -	has a parent in just the same way; this is the changeset that
   5.784 -	the working directory currently contains.</para>
   5.785 -
   5.786 -      <para>To update the working directory to a particular revision,
   5.787 -
   5.788 -	give a revision number or changeset ID to the <command
   5.789 -	  role="hg-cmd">hg update</command> command.</para>
   5.790 -
   5.791 -      &interaction.tour.older;
   5.792 -
   5.793 -      <para>If you omit an explicit revision, <command
   5.794 -	  role="hg-cmd">hg update</command> will update to the tip
   5.795 -	revision, as shown by the second call to <command
   5.796 -	  role="hg-cmd">hg update</command> in the example
   5.797 -	above.</para>
   5.798 -    </sect2>
   5.799 -
   5.800 -    <sect2>
   5.801 -      <title>Pushing changes to another repository</title>
   5.802 -
   5.803 -      <para>Mercurial lets us push changes to another
   5.804 -	  repository, from the repository we're currently visiting.
   5.805 -	  As with the example of <command role="hg-cmd">hg
   5.806 -	    pull</command> above, we'll create a temporary repository
   5.807 -	  to push our changes into.</para>
   5.808 -
   5.809 -      &interaction.tour.clone-push;
   5.810 -
   5.811 -      <para>The <command role="hg-cmd">hg outgoing</command> command
   5.812 -	  tells us what changes would be pushed into another
   5.813 -	  repository.</para>
   5.814 -
   5.815 -      &interaction.tour.outgoing;
   5.816 -
   5.817 -      <para>And the
   5.818 -	  <command role="hg-cmd">hg push</command> command does the
   5.819 -	  actual push.</para>
   5.820 -
   5.821 -      &interaction.tour.push;
   5.822 -
   5.823 -      <para>As with
   5.824 -	  <command role="hg-cmd">hg pull</command>, the <command
   5.825 -	    role="hg-cmd">hg push</command> command does not update
   5.826 -	  the working directory in the repository that it's pushing
   5.827 -	  changes into. (Unlike <command role="hg-cmd">hg
   5.828 -	    pull</command>, <command role="hg-cmd">hg push</command>
   5.829 -	  does not provide a <literal>-u</literal> option that updates
   5.830 -	  the other repository's working directory.)</para>
   5.831 -
   5.832 -      <para>What happens if we try to pull or push changes
   5.833 -	  and the receiving repository already has those changes?
   5.834 -	  Nothing too exciting.</para>
   5.835 -
   5.836 -      &interaction.tour.push.nothing;
   5.837 -    </sect2>
   5.838 -    <sect2>
   5.839 -      <title>Sharing changes over a network</title>
   5.840 -
   5.841 -      <para>The commands we have covered in the previous few
   5.842 -	  sections are not limited to working with local repositories.
   5.843 -	  Each works in exactly the same fashion over a network
   5.844 -	  connection; simply pass in a URL instead of a local
   5.845 -	  path.</para>
   5.846 -	
   5.847 -      &interaction.tour.outgoing.net;
   5.848 -
   5.849 -      <para>In this example, we
   5.850 -	  can see what changes we could push to the remote repository,
   5.851 -	  but the repository is understandably not set up to let
   5.852 -	  anonymous users push to it.</para>
   5.853 -
   5.854 -      &interaction.tour.push.net;
   5.855 -    </sect2>
   5.856 -  </sect1>
   5.857 -</chapter>
   5.858 -
   5.859 -<!--
   5.860 -local variables: 
   5.861 -sgml-parent-document: ("00book.xml" "book" "chapter")
   5.862 -end:
   5.863 --->

     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/en/ch02-tour-merge.xml	Thu Mar 19 20:54:12 2009 -0700
     6.3 @@ -0,0 +1,394 @@
     6.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     6.5 +
     6.6 +<chapter id="chap:tour-merge">
     6.7 +  <?dbhtml filename="a-tour-of-mercurial-merging-work.html"?>
     6.8 +  <title>A tour of Mercurial: merging work</title>
     6.9 +
    6.10 +  <para>We've now covered cloning a repository, making changes in a
    6.11 +    repository, and pulling or pushing changes from one repository
    6.12 +    into another.  Our next step is <emphasis>merging</emphasis>
    6.13 +    changes from separate repositories.</para>
    6.14 +
    6.15 +  <sect1>
    6.16 +    <title>Merging streams of work</title>
    6.17 +
    6.18 +    <para>Merging is a fundamental part of working with a distributed
    6.19 +      revision control tool.</para>
    6.20 +    <itemizedlist>
    6.21 +      <listitem><para>Alice and Bob each have a personal copy of a
    6.22 +	  repository for a project they're collaborating on.  Alice
    6.23 +	  fixes a bug in her repository; Bob adds a new feature in
    6.24 +	  his.  They want the shared repository to contain both the
    6.25 +	  bug fix and the new feature.</para>
    6.26 +      </listitem>
    6.27 +      <listitem><para>I frequently work on several different tasks for
    6.28 +	  a single project at once, each safely isolated in its own
    6.29 +	  repository. Working this way means that I often need to
    6.30 +	  merge one piece of my own work with another.</para>
    6.31 +      </listitem></itemizedlist>
    6.32 +
    6.33 +    <para>Because merging is such a common thing to need to do,
    6.34 +      Mercurial makes it easy.  Let's walk through the process.  We'll
    6.35 +      begin by cloning yet another repository (see how often they
    6.36 +      spring up?) and making a change in it.</para>
    6.37 +
    6.38 +    &interaction.tour.merge.clone;
    6.39 +
    6.40 +    <para>We should now have two copies of
    6.41 +      <filename>hello.c</filename> with different contents.  The
    6.42 +      histories of the two repositories have also diverged, as
    6.43 +      illustrated in figure <xref
    6.44 +	linkend="fig:tour-merge:sep-repos"/>.</para>
    6.45 +
    6.46 +    &interaction.tour.merge.cat;
    6.47 +
    6.48 +    <informalfigure id="fig:tour-merge:sep-repos">
    6.49 +      <mediaobject>
    6.50 +	<imageobject><imagedata fileref="tour-merge-sep-repos"/></imageobject>
    6.51 +	<textobject><phrase>XXX add text</phrase></textobject>
    6.52 +	<caption><para>Divergent recent histories of the <filename
    6.53 +	      class="directory">my-hello</filename> and <filename
    6.54 +	      class="directory">my-new-hello</filename>
    6.55 +	    repositories</para></caption>
    6.56 +      </mediaobject>
    6.57 +    </informalfigure>
    6.58 +
    6.59 +    <para>We already know that pulling changes from our <filename
    6.60 +	class="directory">my-hello</filename> repository will have no
    6.61 +      effect on the working directory.</para>
    6.62 +
    6.63 +    &interaction.tour.merge.pull;
    6.64 +
    6.65 +    <para>However, the <command role="hg-cmd">hg pull</command>
    6.66 +      command says something about <quote>heads</quote>.</para>
    6.67 +
    6.68 +    <sect2>
    6.69 +      <title>Head changesets</title>
    6.70 +
    6.71 +      <para>A head is a change that has no descendants, or children,
    6.72 +	as they're also known.  The tip revision is thus a head,
    6.73 +	because the newest revision in a repository doesn't have any
    6.74 +	children, but a repository can contain more than one
    6.75 +	head.</para>
    6.76 +
    6.77 +      <informalfigure id="fig:tour-merge:pull">
    6.78 +	<mediaobject><imageobject><imagedata
    6.79 +				    fileref="tour-merge-pull"/></imageobject><textobject><phrase>XXX 
    6.80 +	      add text</phrase></textobject>
    6.81 +	  <caption><para>Repository contents after pulling from
    6.82 +	      <filename class="directory">my-hello</filename> into
    6.83 +	      <filename
    6.84 +		class="directory">my-new-hello</filename></para></caption>
    6.85 +	</mediaobject>
    6.86 +      </informalfigure>
    6.87 +
    6.88 +      <para>In figure <xref linkend="fig:tour-merge:pull"/>, you can
    6.89 +	see the effect of the pull from <filename
    6.90 +	  class="directory">my-hello</filename> into <filename
    6.91 +	  class="directory">my-new-hello</filename>.  The history that
    6.92 +	was already present in <filename
    6.93 +	  class="directory">my-new-hello</filename> is untouched, but
    6.94 +	a new revision has been added.  By referring to figure <xref
    6.95 +	  linkend="fig:tour-merge:sep-repos"/>, we can see that the
    6.96 +	<emphasis>changeset ID</emphasis> remains the same in the new
    6.97 +	repository, but the <emphasis>revision number</emphasis> has
    6.98 +	changed.  (This, incidentally, is a fine example of why it's
    6.99 +	not safe to use revision numbers when discussing changesets.)
   6.100 +	We can view the heads in a repository using the <command
   6.101 +	  role="hg-cmd">hg heads</command> command.</para>
   6.102 +
   6.103 +      &interaction.tour.merge.heads;
   6.104 +
   6.105 +    </sect2>
   6.106 +    <sect2>
   6.107 +      <title>Performing the merge</title>
   6.108 +
   6.109 +      <para>What happens if we try to use the normal <command
   6.110 +	  role="hg-cmd">hg update</command> command to update to the
   6.111 +	new tip?</para>
   6.112 +
   6.113 +      &interaction.tour.merge.update;
   6.114 +
   6.115 +      <para>Mercurial is telling us that the <command role="hg-cmd">hg
   6.116 +	  update</command> command won't do a merge; it won't update
   6.117 +	the working directory when it thinks we might be wanting to do
   6.118 +	a merge, unless we force it to do so.  Instead, we use the
   6.119 +	<command role="hg-cmd">hg merge</command> command to merge the
   6.120 +	two heads.</para>
   6.121 +
   6.122 +      &interaction.tour.merge.merge;
   6.123 +
   6.124 +      <informalfigure id="fig:tour-merge:merge">
   6.125 +
   6.126 +	<mediaobject><imageobject><imagedata
   6.127 +				    fileref="tour-merge-merge"/></imageobject><textobject><phrase>XXX 
   6.128 +	      add text</phrase></textobject>
   6.129 +	  <caption><para>Working directory and repository during
   6.130 +	      merge, and following commit</para></caption>
   6.131 +	</mediaobject>
   6.132 +      </informalfigure>
   6.133 +
   6.134 +      <para>This updates the working directory so that it contains
   6.135 +	changes from <emphasis>both</emphasis> heads, which is
   6.136 +	reflected in both the output of <command role="hg-cmd">hg
   6.137 +	  parents</command> and the contents of
   6.138 +	<filename>hello.c</filename>.</para>
   6.139 +
   6.140 +      &interaction.tour.merge.parents;
   6.141 +
   6.142 +    </sect2>
   6.143 +    <sect2>
   6.144 +      <title>Committing the results of the merge</title>
   6.145 +
   6.146 +      <para>Whenever we've done a merge, <command role="hg-cmd">hg
   6.147 +	  parents</command> will display two parents until we <command
   6.148 +	  role="hg-cmd">hg commit</command> the results of the
   6.149 +	  merge.</para>
   6.150 +
   6.151 +	&interaction.tour.merge.commit;
   6.152 +
   6.153 +      <para>We now have a new tip revision; notice that it has
   6.154 +	<emphasis>both</emphasis> of our former heads as its parents.
   6.155 +	These are the same revisions that were previously displayed by
   6.156 +	<command role="hg-cmd">hg parents</command>.</para>
   6.157 +
   6.158 +      &interaction.tour.merge.tip;
   6.159 +
   6.160 +      <para>In figure <xref
   6.161 +	  linkend="fig:tour-merge:merge"/>, you can see a
   6.162 +	representation of what happens to the working directory during
   6.163 +	the merge, and how this affects the repository when the commit
   6.164 +	happens.  During the merge, the working directory has two
   6.165 +	parent changesets, and these become the parents of the new
   6.166 +	changeset.</para>
   6.167 +
   6.168 +    </sect2>
   6.169 +  </sect1>
   6.170 +  <sect1>
   6.171 +    <title>Merging conflicting changes</title>
   6.172 +
   6.173 +    <para>Most merges are simple affairs, but sometimes you'll find
   6.174 +      yourself merging changes where each modifies the same portions
   6.175 +      of the same files.  Unless both modifications are identical,
   6.176 +      this results in a <emphasis>conflict</emphasis>, where you have
   6.177 +      to decide how to reconcile the different changes into something
   6.178 +      coherent.</para>
   6.179 +
   6.180 +    <informalfigure>
   6.181 +
   6.182 +      <mediaobject id="fig:tour-merge:conflict">
   6.183 +	<imageobject><imagedata fileref="tour-merge-conflict"/></imageobject>
   6.184 +	<textobject><phrase>XXX add text</phrase></textobject>
   6.185 +	<caption><para>Conflicting changes to a
   6.186 +	    document</para></caption>      </mediaobject>
   6.187 +    </informalfigure>
   6.188 +
   6.189 +    <para>Figure <xref linkend="fig:tour-merge:conflict"/> illustrates
   6.190 +      an instance of two conflicting changes to a document.  We
   6.191 +      started with a single version of the file; then we made some
   6.192 +      changes; while someone else made different changes to the same
   6.193 +      text.  Our task in resolving the conflicting changes is to
   6.194 +      decide what the file should look like.</para>
   6.195 +
   6.196 +    <para>Mercurial doesn't have a built-in facility for handling
   6.197 +      conflicts. Instead, it runs an external program called
   6.198 +      <command>hgmerge</command>.  This is a shell script that is
   6.199 +      bundled with Mercurial; you can change it to behave however you
   6.200 +      please.  What it does by default is try to find one of several
   6.201 +      different merging tools that are likely to be installed on your
   6.202 +      system.  It first tries a few fully automatic merging tools; if
   6.203 +      these don't succeed (because the resolution process requires
   6.204 +      human guidance) or aren't present, the script tries a few
   6.205 +      different graphical merging tools.</para>
   6.206 +
   6.207 +    <para>It's also possible to get Mercurial to run another program
   6.208 +      or script instead of <command>hgmerge</command>, by setting the
   6.209 +      <envar>HGMERGE</envar> environment variable to the name of your
   6.210 +      preferred program.</para>
   6.211 +
   6.212 +    <sect2>
   6.213 +      <title>Using a graphical merge tool</title>
   6.214 +
   6.215 +      <para>My preferred graphical merge tool is
   6.216 +	<command>kdiff3</command>, which I'll use to describe the
   6.217 +	features that are common to graphical file merging tools.  You
   6.218 +	can see a screenshot of <command>kdiff3</command> in action in
   6.219 +	figure <xref linkend="fig:tour-merge:kdiff3"/>.  The kind of
   6.220 +	merge it is performing is called a <emphasis>three-way
   6.221 +	  merge</emphasis>, because there are three different versions
   6.222 +	of the file of interest to us.  The tool thus splits the upper
   6.223 +	portion of the window into three panes:</para>
   6.224 +      <itemizedlist>
   6.225 +	<listitem><para>At the left is the <emphasis>base</emphasis>
   6.226 +	    version of the file, i.e. the most recent version from
   6.227 +	    which the two versions we're trying to merge are
   6.228 +	    descended.</para>
   6.229 +	</listitem>
   6.230 +	<listitem><para>In the middle is <quote>our</quote> version of
   6.231 +	    the file, with the contents that we modified.</para>
   6.232 +	</listitem>
   6.233 +	<listitem><para>On the right is <quote>their</quote> version
   6.234 +	    of the file, the one that from the changeset that we're
   6.235 +	    trying to merge with.</para>
   6.236 +	</listitem></itemizedlist>
   6.237 +      <para>In the pane below these is the current
   6.238 +	<emphasis>result</emphasis> of the merge. Our task is to
   6.239 +	replace all of the red text, which indicates unresolved
   6.240 +	conflicts, with some sensible merger of the
   6.241 +	<quote>ours</quote> and <quote>theirs</quote> versions of the
   6.242 +	file.</para>
   6.243 +
   6.244 +      <para>All four of these panes are <emphasis>locked
   6.245 +	  together</emphasis>; if we scroll vertically or horizontally
   6.246 +	in any of them, the others are updated to display the
   6.247 +	corresponding sections of their respective files.</para>
   6.248 +
   6.249 +      <informalfigure id="fig:tour-merge:kdiff3">
   6.250 +	<mediaobject><imageobject><imagedata
   6.251 +				    fileref="kdiff3"/></imageobject><textobject><phrase>XXX 
   6.252 +	      add text</phrase></textobject>
   6.253 +	  <caption><para>Using <command>kdiff3</command> to merge
   6.254 +	      versions of a file</para></caption>
   6.255 +	</mediaobject>
   6.256 +      </informalfigure>
   6.257 +
   6.258 +      <para>For each conflicting portion of the file, we can choose to
   6.259 +	resolve the conflict using some combination of text from the
   6.260 +	base version, ours, or theirs.  We can also manually edit the
   6.261 +	merged file at any time, in case we need to make further
   6.262 +	modifications.</para>
   6.263 +
   6.264 +      <para>There are <emphasis>many</emphasis> file merging tools
   6.265 +	available, too many to cover here.  They vary in which
   6.266 +	platforms they are available for, and in their particular
   6.267 +	strengths and weaknesses.  Most are tuned for merging files
   6.268 +	containing plain text, while a few are aimed at specialised
   6.269 +	file formats (generally XML).</para>
   6.270 +
   6.271 +    </sect2>
   6.272 +    <sect2>
   6.273 +      <title>A worked example</title>
   6.274 +
   6.275 +      <para>In this example, we will reproduce the file modification
   6.276 +	history of figure <xref linkend="fig:tour-merge:conflict"/>
   6.277 +	above.  Let's begin by creating a repository with a base
   6.278 +	version of our document.</para>
   6.279 +
   6.280 +      &interaction.tour-merge-conflict.wife;
   6.281 +
   6.282 +      <para>We'll clone the repository and make a change to the
   6.283 +	file.</para>
   6.284 +
   6.285 +      &interaction.tour-merge-conflict.cousin;
   6.286 +
   6.287 +      <para>And another clone, to simulate someone else making a
   6.288 +	change to the file. (This hints at the idea that it's not all
   6.289 +	that unusual to merge with yourself when you isolate tasks in
   6.290 +	separate repositories, and indeed to find and resolve
   6.291 +	conflicts while doing so.)</para>
   6.292 +
   6.293 +      &interaction.tour-merge-conflict.son;
   6.294 +
   6.295 +      <para>Having created two
   6.296 +	different versions of the file, we'll set up an environment
   6.297 +	suitable for running our merge.</para>
   6.298 +
   6.299 +      &interaction.tour-merge-conflict.pull;
   6.300 +
   6.301 +      <para>In this example, I won't use Mercurial's normal
   6.302 +	<command>hgmerge</command> program to do the merge, because it
   6.303 +	would drop my nice automated example-running tool into a
   6.304 +	graphical user interface.  Instead, I'll set
   6.305 +	<envar>HGMERGE</envar> to tell Mercurial to use the
   6.306 +	non-interactive <command>merge</command> command.  This is
   6.307 +	bundled with many Unix-like systems. If you're following this
   6.308 +	example on your computer, don't bother setting
   6.309 +	<envar>HGMERGE</envar>.</para>
   6.310 +
   6.311 +      <para><emphasis role="bold">XXX FIX THIS
   6.312 +	  EXAMPLE.</emphasis></para>
   6.313 +
   6.314 +      &interaction.tour-merge-conflict.merge;
   6.315 +
   6.316 +      <para>Because <command>merge</command> can't resolve the
   6.317 +	conflicting changes, it leaves <emphasis>merge
   6.318 +	  markers</emphasis> inside the file that has conflicts,
   6.319 +	indicating which lines have conflicts, and whether they came
   6.320 +	from our version of the file or theirs.</para>
   6.321 +
   6.322 +      <para>Mercurial can tell from the way <command>merge</command>
   6.323 +	exits that it wasn't able to merge successfully, so it tells
   6.324 +	us what commands we'll need to run if we want to redo the
   6.325 +	merging operation.  This could be useful if, for example, we
   6.326 +	were running a graphical merge tool and quit because we were
   6.327 +	confused or realised we had made a mistake.</para>
   6.328 +
   6.329 +      <para>If automatic or manual merges fail, there's nothing to
   6.330 +	prevent us from <quote>fixing up</quote> the affected files
   6.331 +	ourselves, and committing the results of our merge:</para>
   6.332 +
   6.333 +      &interaction.tour-merge-conflict.commit;
   6.334 +
   6.335 +    </sect2>
   6.336 +  </sect1>
   6.337 +  <sect1 id="sec:tour-merge:fetch">
   6.338 +    <title>Simplifying the pull-merge-commit sequence</title>
   6.339 +
   6.340 +    <para>The process of merging changes as outlined above is
   6.341 +      straightforward, but requires running three commands in
   6.342 +      sequence.</para>
   6.343 +    <programlisting>hg pull
   6.344 +hg merge
   6.345 +hg commit -m 'Merged remote changes'</programlisting>
   6.346 +    <para>In the case of the final commit, you also need to enter a
   6.347 +      commit message, which is almost always going to be a piece of
   6.348 +      uninteresting <quote>boilerplate</quote> text.</para>
   6.349 +
   6.350 +    <para>It would be nice to reduce the number of steps needed, if
   6.351 +      this were possible.  Indeed, Mercurial is distributed with an
   6.352 +      extension called <literal role="hg-ext">fetch</literal> that
   6.353 +      does just this.</para>
   6.354 +
   6.355 +    <para>Mercurial provides a flexible extension mechanism that lets
   6.356 +      people extend its functionality, while keeping the core of
   6.357 +      Mercurial small and easy to deal with.  Some extensions add new
   6.358 +      commands that you can use from the command line, while others
   6.359 +      work <quote>behind the scenes,</quote> for example adding
   6.360 +      capabilities to the server.</para>
   6.361 +
   6.362 +    <para>The <literal role="hg-ext">fetch</literal> extension adds a
   6.363 +      new command called, not surprisingly, <command role="hg-cmd">hg
   6.364 +	fetch</command>.  This extension acts as a combination of
   6.365 +      <command role="hg-cmd">hg pull</command>, <command
   6.366 +	role="hg-cmd">hg update</command> and <command
   6.367 +	role="hg-cmd">hg merge</command>.  It begins by pulling
   6.368 +      changes from another repository into the current repository.  If
   6.369 +      it finds that the changes added a new head to the repository, it
   6.370 +      begins a merge, then commits the result of the merge with an
   6.371 +      automatically-generated commit message.  If no new heads were
   6.372 +      added, it updates the working directory to the new tip
   6.373 +      changeset.</para>
   6.374 +
   6.375 +    <para>Enabling the <literal role="hg-ext">fetch</literal>
   6.376 +      extension is easy.  Edit your <filename
   6.377 +	role="special">.hgrc</filename>, and either go to the <literal
   6.378 +	role="rc-extensions">extensions</literal> section or create an
   6.379 +      <literal role="rc-extensions">extensions</literal> section. Then
   6.380 +      add a line that simply reads <quote><literal>fetch
   6.381 +	</literal></quote>.</para>
   6.382 +    <programlisting>[extensions]
   6.383 +fetch =</programlisting>
   6.384 +    <para>(Normally, on the right-hand side of the
   6.385 +      <quote><literal>=</literal></quote> would appear the location of
   6.386 +      the extension, but since the <literal
   6.387 +	role="hg-ext">fetch</literal> extension is in the standard
   6.388 +      distribution, Mercurial knows where to search for it.)</para>
   6.389 +
   6.390 +  </sect1>
   6.391 +</chapter>
   6.392 +
   6.393 +<!--
   6.394 +local variables: 
   6.395 +sgml-parent-document: ("00book.xml" "book" "chapter")
   6.396 +end:
   6.397 +-->

     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/en/ch03-concepts.xml	Thu Mar 19 20:54:12 2009 -0700
     7.3 @@ -0,0 +1,726 @@
     7.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     7.5 +
     7.6 +<chapter id="chap:concepts">
     7.7 +  <?dbhtml filename="behind-the-scenes.html"?>
     7.8 +  <title>Behind the scenes</title>
     7.9 +
    7.10 +  <para>Unlike many revision control systems, the concepts upon which
    7.11 +    Mercurial is built are simple enough that it's easy to understand
    7.12 +    how the software really works.  Knowing this certainly isn't
    7.13 +    necessary, but I find it useful to have a <quote>mental
    7.14 +      model</quote> of what's going on.</para>
    7.15 +
    7.16 +  <para>This understanding gives me confidence that Mercurial has been
    7.17 +    carefully designed to be both <emphasis>safe</emphasis> and
    7.18 +    <emphasis>efficient</emphasis>.  And just as importantly, if it's
    7.19 +    easy for me to retain a good idea of what the software is doing
    7.20 +    when I perform a revision control task, I'm less likely to be
    7.21 +    surprised by its behaviour.</para>
    7.22 +
    7.23 +  <para>In this chapter, we'll initially cover the core concepts
    7.24 +    behind Mercurial's design, then continue to discuss some of the
    7.25 +    interesting details of its implementation.</para>
    7.26 +
    7.27 +  <sect1>
    7.28 +    <title>Mercurial's historical record</title>
    7.29 +
    7.30 +    <sect2>
    7.31 +      <title>Tracking the history of a single file</title>
    7.32 +
    7.33 +      <para>When Mercurial tracks modifications to a file, it stores
    7.34 +	the history of that file in a metadata object called a
    7.35 +	<emphasis>filelog</emphasis>.  Each entry in the filelog
    7.36 +	contains enough information to reconstruct one revision of the
    7.37 +	file that is being tracked.  Filelogs are stored as files in
    7.38 +	the <filename role="special"
    7.39 +	  class="directory">.hg/store/data</filename> directory.  A
    7.40 +	filelog contains two kinds of information: revision data, and
    7.41 +	an index to help Mercurial to find a revision
    7.42 +	efficiently.</para>
    7.43 +
    7.44 +      <para>A file that is large, or has a lot of history, has its
    7.45 +	filelog stored in separate data
    7.46 +	(<quote><literal>.d</literal></quote> suffix) and index
    7.47 +	(<quote><literal>.i</literal></quote> suffix) files.  For
    7.48 +	small files without much history, the revision data and index
    7.49 +	are combined in a single <quote><literal>.i</literal></quote>
    7.50 +	file.  The correspondence between a file in the working
    7.51 +	directory and the filelog that tracks its history in the
    7.52 +	repository is illustrated in figure <xref
    7.53 +	  linkend="fig:concepts:filelog"/>.</para>
    7.54 +
    7.55 +      <informalfigure id="fig:concepts:filelog">
    7.56 +	<mediaobject><imageobject><imagedata
    7.57 +				    fileref="filelog"/></imageobject><textobject><phrase>XXX 
    7.58 +	      add text</phrase></textobject>
    7.59 +	  <caption><para>Relationships between files in working
    7.60 +	      directory and filelogs in
    7.61 +	      repository</para></caption></mediaobject>
    7.62 +      </informalfigure>
    7.63 +
    7.64 +    </sect2>
    7.65 +    <sect2>
    7.66 +      <title>Managing tracked files</title>
    7.67 +
    7.68 +      <para>Mercurial uses a structure called a
    7.69 +	<emphasis>manifest</emphasis> to collect together information
    7.70 +	about the files that it tracks.  Each entry in the manifest
    7.71 +	contains information about the files present in a single
    7.72 +	changeset.  An entry records which files are present in the
    7.73 +	changeset, the revision of each file, and a few other pieces
    7.74 +	of file metadata.</para>
    7.75 +
    7.76 +    </sect2>
    7.77 +    <sect2>
    7.78 +      <title>Recording changeset information</title>
    7.79 +
    7.80 +      <para>The <emphasis>changelog</emphasis> contains information
    7.81 +	about each changeset.  Each revision records who committed a
    7.82 +	change, the changeset comment, other pieces of
    7.83 +	changeset-related information, and the revision of the
    7.84 +	manifest to use.</para>
    7.85 +
    7.86 +    </sect2>
    7.87 +    <sect2>
    7.88 +      <title>Relationships between revisions</title>
    7.89 +
    7.90 +      <para>Within a changelog, a manifest, or a filelog, each
    7.91 +	revision stores a pointer to its immediate parent (or to its
    7.92 +	two parents, if it's a merge revision).  As I mentioned above,
    7.93 +	there are also relationships between revisions
    7.94 +	<emphasis>across</emphasis> these structures, and they are
    7.95 +	hierarchical in nature.</para>
    7.96 +
    7.97 +      <para>For every changeset in a repository, there is exactly one
    7.98 +	revision stored in the changelog.  Each revision of the
    7.99 +	changelog contains a pointer to a single revision of the
   7.100 +	manifest.  A revision of the manifest stores a pointer to a
   7.101 +	single revision of each filelog tracked when that changeset
   7.102 +	was created.  These relationships are illustrated in figure
   7.103 +	<xref linkend="fig:concepts:metadata"/>.</para>
   7.104 +
   7.105 +      <informalfigure id="fig:concepts:metadata">
   7.106 +	<mediaobject><imageobject><imagedata
   7.107 +				    fileref="metadata"/></imageobject><textobject><phrase>XXX 
   7.108 +	      add text</phrase></textobject><caption><para>Metadata
   7.109 +	      relationships</para></caption>
   7.110 +	</mediaobject>
   7.111 +      </informalfigure>
   7.112 +
   7.113 +      <para>As the illustration shows, there is
   7.114 +	<emphasis>not</emphasis> a <quote>one to one</quote>
   7.115 +	relationship between revisions in the changelog, manifest, or
   7.116 +	filelog. If the manifest hasn't changed between two
   7.117 +	changesets, the changelog entries for those changesets will
   7.118 +	point to the same revision of the manifest.  If a file that
   7.119 +	Mercurial tracks hasn't changed between two changesets, the
   7.120 +	entry for that file in the two revisions of the manifest will
   7.121 +	point to the same revision of its filelog.</para>
   7.122 +
   7.123 +    </sect2>
   7.124 +  </sect1>
   7.125 +  <sect1>
   7.126 +    <title>Safe, efficient storage</title>
   7.127 +
   7.128 +    <para>The underpinnings of changelogs, manifests, and filelogs are
   7.129 +      provided by a single structure called the
   7.130 +      <emphasis>revlog</emphasis>.</para>
   7.131 +
   7.132 +    <sect2>
   7.133 +      <title>Efficient storage</title>
   7.134 +
   7.135 +      <para>The revlog provides efficient storage of revisions using a
   7.136 +	<emphasis>delta</emphasis> mechanism.  Instead of storing a
   7.137 +	complete copy of a file for each revision, it stores the
   7.138 +	changes needed to transform an older revision into the new
   7.139 +	revision.  For many kinds of file data, these deltas are
   7.140 +	typically a fraction of a percent of the size of a full copy
   7.141 +	of a file.</para>
   7.142 +
   7.143 +      <para>Some obsolete revision control systems can only work with
   7.144 +	deltas of text files.  They must either store binary files as
   7.145 +	complete snapshots or encoded into a text representation, both
   7.146 +	of which are wasteful approaches.  Mercurial can efficiently
   7.147 +	handle deltas of files with arbitrary binary contents; it
   7.148 +	doesn't need to treat text as special.</para>
   7.149 +
   7.150 +    </sect2>
   7.151 +    <sect2 id="sec:concepts:txn">
   7.152 +      <title>Safe operation</title>
   7.153 +
   7.154 +      <para>Mercurial only ever <emphasis>appends</emphasis> data to
   7.155 +	the end of a revlog file. It never modifies a section of a
   7.156 +	file after it has written it.  This is both more robust and
   7.157 +	efficient than schemes that need to modify or rewrite
   7.158 +	data.</para>
   7.159 +
   7.160 +      <para>In addition, Mercurial treats every write as part of a
   7.161 +	<emphasis>transaction</emphasis> that can span a number of
   7.162 +	files.  A transaction is <emphasis>atomic</emphasis>: either
   7.163 +	the entire transaction succeeds and its effects are all
   7.164 +	visible to readers in one go, or the whole thing is undone.
   7.165 +	This guarantee of atomicity means that if you're running two
   7.166 +	copies of Mercurial, where one is reading data and one is
   7.167 +	writing it, the reader will never see a partially written
   7.168 +	result that might confuse it.</para>
   7.169 +
   7.170 +      <para>The fact that Mercurial only appends to files makes it
   7.171 +	easier to provide this transactional guarantee.  The easier it
   7.172 +	is to do stuff like this, the more confident you should be
   7.173 +	that it's done correctly.</para>
   7.174 +
   7.175 +    </sect2>
   7.176 +    <sect2>
   7.177 +      <title>Fast retrieval</title>
   7.178 +
   7.179 +      <para>Mercurial cleverly avoids a pitfall common to all earlier
   7.180 +	revision control systems: the problem of <emphasis>inefficient
   7.181 +	  retrieval</emphasis>. Most revision control systems store
   7.182 +	the contents of a revision as an incremental series of
   7.183 +	modifications against a <quote>snapshot</quote>.  To
   7.184 +	reconstruct a specific revision, you must first read the
   7.185 +	snapshot, and then every one of the revisions between the
   7.186 +	snapshot and your target revision.  The more history that a
   7.187 +	file accumulates, the more revisions you must read, hence the
   7.188 +	longer it takes to reconstruct a particular revision.</para>
   7.189 +
   7.190 +      <informalfigure id="fig:concepts:snapshot">
   7.191 +	<mediaobject><imageobject><imagedata
   7.192 +				    fileref="snapshot"/></imageobject><textobject><phrase>XXX 
   7.193 +	      add text</phrase></textobject><caption><para>Snapshot of
   7.194 +	      a revlog, with incremental
   7.195 +	      deltas</para></caption></mediaobject>
   7.196 +      </informalfigure>
   7.197 +
   7.198 +      <para>The innovation that Mercurial applies to this problem is
   7.199 +	simple but effective.  Once the cumulative amount of delta
   7.200 +	information stored since the last snapshot exceeds a fixed
   7.201 +	threshold, it stores a new snapshot (compressed, of course),
   7.202 +	instead of another delta.  This makes it possible to
   7.203 +	reconstruct <emphasis>any</emphasis> revision of a file
   7.204 +	quickly.  This approach works so well that it has since been
   7.205 +	copied by several other revision control systems.</para>
   7.206 +
   7.207 +      <para>Figure <xref linkend="fig:concepts:snapshot"/> illustrates
   7.208 +	the idea.  In an entry in a revlog's index file, Mercurial
   7.209 +	stores the range of entries from the data file that it must
   7.210 +	read to reconstruct a particular revision.</para>
   7.211 +
   7.212 +      <sect3>
   7.213 +	<title>Aside: the influence of video compression</title>
   7.214 +
   7.215 +	<para>If you're familiar with video compression or have ever
   7.216 +	  watched a TV feed through a digital cable or satellite
   7.217 +	  service, you may know that most video compression schemes
   7.218 +	  store each frame of video as a delta against its predecessor
   7.219 +	  frame.  In addition, these schemes use <quote>lossy</quote>
   7.220 +	  compression techniques to increase the compression ratio, so
   7.221 +	  visual errors accumulate over the course of a number of
   7.222 +	  inter-frame deltas.</para>
   7.223 +
   7.224 +	<para>Because it's possible for a video stream to <quote>drop
   7.225 +	    out</quote> occasionally due to signal glitches, and to
   7.226 +	  limit the accumulation of artefacts introduced by the lossy
   7.227 +	  compression process, video encoders periodically insert a
   7.228 +	  complete frame (called a <quote>key frame</quote>) into the
   7.229 +	  video stream; the next delta is generated against that
   7.230 +	  frame.  This means that if the video signal gets
   7.231 +	  interrupted, it will resume once the next key frame is
   7.232 +	  received.  Also, the accumulation of encoding errors
   7.233 +	  restarts anew with each key frame.</para>
   7.234 +
   7.235 +      </sect3>
   7.236 +    </sect2>
   7.237 +    <sect2>
   7.238 +      <title>Identification and strong integrity</title>
   7.239 +
   7.240 +      <para>Along with delta or snapshot information, a revlog entry
   7.241 +	contains a cryptographic hash of the data that it represents.
   7.242 +	This makes it difficult to forge the contents of a revision,
   7.243 +	and easy to detect accidental corruption.</para>
   7.244 +
   7.245 +      <para>Hashes provide more than a mere check against corruption;
   7.246 +	they are used as the identifiers for revisions.  The changeset
   7.247 +	identification hashes that you see as an end user are from
   7.248 +	revisions of the changelog.  Although filelogs and the
   7.249 +	manifest also use hashes, Mercurial only uses these behind the
   7.250 +	scenes.</para>
   7.251 +
   7.252 +      <para>Mercurial verifies that hashes are correct when it
   7.253 +	retrieves file revisions and when it pulls changes from
   7.254 +	another repository.  If it encounters an integrity problem, it
   7.255 +	will complain and stop whatever it's doing.</para>
   7.256 +
   7.257 +      <para>In addition to the effect it has on retrieval efficiency,
   7.258 +	Mercurial's use of periodic snapshots makes it more robust
   7.259 +	against partial data corruption.  If a revlog becomes partly
   7.260 +	corrupted due to a hardware error or system bug, it's often
   7.261 +	possible to reconstruct some or most revisions from the
   7.262 +	uncorrupted sections of the revlog, both before and after the
   7.263 +	corrupted section.  This would not be possible with a
   7.264 +	delta-only storage model.</para>
   7.265 +
   7.266 +    </sect2>
   7.267 +  </sect1>
   7.268 +  <sect1>
   7.269 +    <title>Revision history, branching, and merging</title>
   7.270 +
   7.271 +    <para>Every entry in a Mercurial revlog knows the identity of its
   7.272 +      immediate ancestor revision, usually referred to as its
   7.273 +      <emphasis>parent</emphasis>.  In fact, a revision contains room
   7.274 +      for not one parent, but two.  Mercurial uses a special hash,
   7.275 +      called the <quote>null ID</quote>, to represent the idea
   7.276 +      <quote>there is no parent here</quote>.  This hash is simply a
   7.277 +      string of zeroes.</para>
   7.278 +
   7.279 +    <para>In figure <xref linkend="fig:concepts:revlog"/>, you can see
   7.280 +      an example of the conceptual structure of a revlog.  Filelogs,
   7.281 +      manifests, and changelogs all have this same structure; they
   7.282 +      differ only in the kind of data stored in each delta or
   7.283 +      snapshot.</para>
   7.284 +
   7.285 +    <para>The first revision in a revlog (at the bottom of the image)
   7.286 +      has the null ID in both of its parent slots.  For a
   7.287 +      <quote>normal</quote> revision, its first parent slot contains
   7.288 +      the ID of its parent revision, and its second contains the null
   7.289 +      ID, indicating that the revision has only one real parent.  Any
   7.290 +      two revisions that have the same parent ID are branches.  A
   7.291 +      revision that represents a merge between branches has two normal
   7.292 +      revision IDs in its parent slots.</para>
   7.293 +
   7.294 +    <informalfigure id="fig:concepts:revlog">
   7.295 +      <mediaobject><imageobject><imagedata
   7.296 +				  fileref="revlog"/></imageobject><textobject><phrase>XXX 
   7.297 +	    add text</phrase></textobject></mediaobject>
   7.298 +    </informalfigure>
   7.299 +
   7.300 +  </sect1>
   7.301 +  <sect1>
   7.302 +    <title>The working directory</title>
   7.303 +
   7.304 +    <para>In the working directory, Mercurial stores a snapshot of the
   7.305 +      files from the repository as of a particular changeset.</para>
   7.306 +
   7.307 +    <para>The working directory <quote>knows</quote> which changeset
   7.308 +      it contains.  When you update the working directory to contain a
   7.309 +      particular changeset, Mercurial looks up the appropriate
   7.310 +      revision of the manifest to find out which files it was tracking
   7.311 +      at the time that changeset was committed, and which revision of
   7.312 +      each file was then current.  It then recreates a copy of each of
   7.313 +      those files, with the same contents it had when the changeset
   7.314 +      was committed.</para>
   7.315 +
   7.316 +    <para>The <emphasis>dirstate</emphasis> contains Mercurial's
   7.317 +      knowledge of the working directory.  This details which
   7.318 +      changeset the working directory is updated to, and all of the
   7.319 +      files that Mercurial is tracking in the working
   7.320 +      directory.</para>
   7.321 +
   7.322 +    <para>Just as a revision of a revlog has room for two parents, so
   7.323 +      that it can represent either a normal revision (with one parent)
   7.324 +      or a merge of two earlier revisions, the dirstate has slots for
   7.325 +      two parents.  When you use the <command role="hg-cmd">hg
   7.326 +	update</command> command, the changeset that you update to is
   7.327 +      stored in the <quote>first parent</quote> slot, and the null ID
   7.328 +      in the second. When you <command role="hg-cmd">hg
   7.329 +	merge</command> with another changeset, the first parent
   7.330 +      remains unchanged, and the second parent is filled in with the
   7.331 +      changeset you're merging with.  The <command role="hg-cmd">hg
   7.332 +	parents</command> command tells you what the parents of the
   7.333 +      dirstate are.</para>
   7.334 +
   7.335 +    <sect2>
   7.336 +      <title>What happens when you commit</title>
   7.337 +
   7.338 +      <para>The dirstate stores parent information for more than just
   7.339 +	book-keeping purposes.  Mercurial uses the parents of the
   7.340 +	dirstate as <emphasis>the parents of a new
   7.341 +	  changeset</emphasis> when you perform a commit.</para>
   7.342 +
   7.343 +      <informalfigure id="fig:concepts:wdir">
   7.344 +	<mediaobject><imageobject><imagedata
   7.345 +				    fileref="wdir"/></imageobject><textobject><phrase>XXX 
   7.346 +	      add text</phrase></textobject><caption><para>The working
   7.347 +	      directory can have two
   7.348 +	      parents</para></caption></mediaobject>
   7.349 +      </informalfigure>
   7.350 +
   7.351 +      <para>Figure <xref linkend="fig:concepts:wdir"/> shows the
   7.352 +	normal state of the working directory, where it has a single
   7.353 +	changeset as parent.  That changeset is the
   7.354 +	<emphasis>tip</emphasis>, the newest changeset in the
   7.355 +	repository that has no children.</para>
   7.356 +
   7.357 +      <informalfigure id="fig:concepts:wdir-after-commit">
   7.358 +	<mediaobject><imageobject><imagedata
   7.359 +				    fileref="wdir-after-commit"/></imageobject><textobject><phrase>XXX 
   7.360 +	      add text</phrase></textobject><caption><para>The working
   7.361 +	      directory gains new parents after a
   7.362 +	      commit</para></caption></mediaobject>
   7.363 +      </informalfigure>
   7.364 +
   7.365 +      <para>It's useful to think of the working directory as
   7.366 +	<quote>the changeset I'm about to commit</quote>.  Any files
   7.367 +	that you tell Mercurial that you've added, removed, renamed,
   7.368 +	or copied will be reflected in that changeset, as will
   7.369 +	modifications to any files that Mercurial is already tracking;
   7.370 +	the new changeset will have the parents of the working
   7.371 +	directory as its parents.</para>
   7.372 +
   7.373 +      <para>After a commit, Mercurial will update the parents of the
   7.374 +	working directory, so that the first parent is the ID of the
   7.375 +	new changeset, and the second is the null ID.  This is shown
   7.376 +	in figure <xref linkend="fig:concepts:wdir-after-commit"/>.
   7.377 +	Mercurial
   7.378 +	doesn't touch any of the files in the working directory when
   7.379 +	you commit; it just modifies the dirstate to note its new
   7.380 +	parents.</para>
   7.381 +
   7.382 +    </sect2>
   7.383 +    <sect2>
   7.384 +      <title>Creating a new head</title>
   7.385 +
   7.386 +      <para>It's perfectly normal to update the working directory to a
   7.387 +	changeset other than the current tip.  For example, you might
   7.388 +	want to know what your project looked like last Tuesday, or
   7.389 +	you could be looking through changesets to see which one
   7.390 +	introduced a bug.  In cases like this, the natural thing to do
   7.391 +	is update the working directory to the changeset you're
   7.392 +	interested in, and then examine the files in the working
   7.393 +	directory directly to see their contents as they were when you
   7.394 +	committed that changeset.  The effect of this is shown in
   7.395 +	figure <xref linkend="fig:concepts:wdir-pre-branch"/>.</para>
   7.396 +
   7.397 +      <informalfigure id="fig:concepts:wdir-pre-branch">
   7.398 +	<mediaobject><imageobject><imagedata
   7.399 +				    fileref="wdir-pre-branch"/></imageobject><textobject><phrase>XXX 
   7.400 +	      add text</phrase></textobject><caption><para>The working
   7.401 +	      directory, updated to an older
   7.402 +	      changeset</para></caption></mediaobject>
   7.403 +      </informalfigure>
   7.404 +
   7.405 +      <para>Having updated the working directory to an older
   7.406 +	changeset, what happens if you make some changes, and then
   7.407 +	commit?  Mercurial behaves in the same way as I outlined
   7.408 +	above.  The parents of the working directory become the
   7.409 +	parents of the new changeset.  This new changeset has no
   7.410 +	children, so it becomes the new tip.  And the repository now
   7.411 +	contains two changesets that have no children; we call these
   7.412 +	<emphasis>heads</emphasis>.  You can see the structure that
   7.413 +	this creates in figure <xref
   7.414 +	  linkend="fig:concepts:wdir-branch"/>.</para>
   7.415 +
   7.416 +      <informalfigure id="fig:concepts:wdir-branch">
   7.417 +	<mediaobject><imageobject><imagedata
   7.418 +				    fileref="wdir-branch"/></imageobject><textobject><phrase>XXX 
   7.419 +	      add text</phrase></textobject><caption><para>After a
   7.420 +	      commit made while synced to an older
   7.421 +	      changeset</para></caption></mediaobject>
   7.422 +      </informalfigure>
   7.423 +
   7.424 +      <note>
   7.425 +	<para>  If you're new to Mercurial, you should keep in mind a
   7.426 +	  common <quote>error</quote>, which is to use the <command
   7.427 +	    role="hg-cmd">hg pull</command> command without any
   7.428 +	  options.  By default, the <command role="hg-cmd">hg
   7.429 +	    pull</command> command <emphasis>does not</emphasis>
   7.430 +	  update the working directory, so you'll bring new changesets
   7.431 +	  into your repository, but the working directory will stay
   7.432 +	  synced at the same changeset as before the pull.  If you
   7.433 +	  make some changes and commit afterwards, you'll thus create
   7.434 +	  a new head, because your working directory isn't synced to
   7.435 +	  whatever the current tip is.</para>
   7.436 +
   7.437 +	<para>  I put the word <quote>error</quote> in quotes because
   7.438 +	  all that you need to do to rectify this situation is
   7.439 +	  <command role="hg-cmd">hg merge</command>, then <command
   7.440 +	    role="hg-cmd">hg commit</command>.  In other words, this
   7.441 +	  almost never has negative consequences; it just surprises
   7.442 +	  people.  I'll discuss other ways to avoid this behaviour,
   7.443 +	  and why Mercurial behaves in this initially surprising way,
   7.444 +	  later on.</para>
   7.445 +      </note>
   7.446 +
   7.447 +    </sect2>
   7.448 +    <sect2>
   7.449 +      <title>Merging heads</title>
   7.450 +
   7.451 +      <para>When you run the <command role="hg-cmd">hg merge</command>
   7.452 +	command, Mercurial leaves the first parent of the working
   7.453 +	directory unchanged, and sets the second parent to the
   7.454 +	changeset you're merging with, as shown in figure <xref
   7.455 +	  linkend="fig:concepts:wdir-merge"/>.</para>
   7.456 +
   7.457 +      <informalfigure id="fig:concepts:wdir-merge">
   7.458 +	<mediaobject><imageobject><imagedata
   7.459 +				    fileref="wdir-merge"/></imageobject><textobject><phrase>XXX 
   7.460 +	      add text</phrase></textobject><caption><para>Merging two
   7.461 +	      heads</para></caption></mediaobject>
   7.462 +      </informalfigure>
   7.463 +
   7.464 +      <para>Mercurial also has to modify the working directory, to
   7.465 +	merge the files managed in the two changesets.  Simplified a
   7.466 +	little, the merging process goes like this, for every file in
   7.467 +	the manifests of both changesets.</para>
   7.468 +      <itemizedlist>
   7.469 +	<listitem><para>If neither changeset has modified a file, do
   7.470 +	    nothing with that file.</para>
   7.471 +	</listitem>
   7.472 +	<listitem><para>If one changeset has modified a file, and the
   7.473 +	    other hasn't, create the modified copy of the file in the
   7.474 +	    working directory.</para>
   7.475 +	</listitem>
   7.476 +	<listitem><para>If one changeset has removed a file, and the
   7.477 +	    other hasn't (or has also deleted it), delete the file
   7.478 +	    from the working directory.</para>
   7.479 +	</listitem>
   7.480 +	<listitem><para>If one changeset has removed a file, but the
   7.481 +	    other has modified the file, ask the user what to do: keep
   7.482 +	    the modified file, or remove it?</para>
   7.483 +	</listitem>
   7.484 +	<listitem><para>If both changesets have modified a file,
   7.485 +	    invoke an external merge program to choose the new
   7.486 +	    contents for the merged file.  This may require input from
   7.487 +	    the user.</para>
   7.488 +	</listitem>
   7.489 +	<listitem><para>If one changeset has modified a file, and the
   7.490 +	    other has renamed or copied the file, make sure that the
   7.491 +	    changes follow the new name of the file.</para>
   7.492 +	</listitem></itemizedlist>
   7.493 +      <para>There are more details&emdash;merging has plenty of corner
   7.494 +	cases&emdash;but these are the most common choices that are
   7.495 +	involved in a merge.  As you can see, most cases are
   7.496 +	completely automatic, and indeed most merges finish
   7.497 +	automatically, without requiring your input to resolve any
   7.498 +	conflicts.</para>
   7.499 +
   7.500 +      <para>When you're thinking about what happens when you commit
   7.501 +	after a merge, once again the working directory is <quote>the
   7.502 +	  changeset I'm about to commit</quote>.  After the <command
   7.503 +	  role="hg-cmd">hg merge</command> command completes, the
   7.504 +	working directory has two parents; these will become the
   7.505 +	parents of the new changeset.</para>
   7.506 +
   7.507 +      <para>Mercurial lets you perform multiple merges, but you must
   7.508 +	commit the results of each individual merge as you go.  This
   7.509 +	is necessary because Mercurial only tracks two parents for
   7.510 +	both revisions and the working directory.  While it would be
   7.511 +	technically possible to merge multiple changesets at once, the
   7.512 +	prospect of user confusion and making a terrible mess of a
   7.513 +	merge immediately becomes overwhelming.</para>
   7.514 +
   7.515 +    </sect2>
   7.516 +  </sect1>
   7.517 +  <sect1>
   7.518 +    <title>Other interesting design features</title>
   7.519 +
   7.520 +    <para>In the sections above, I've tried to highlight some of the
   7.521 +      most important aspects of Mercurial's design, to illustrate that
   7.522 +      it pays careful attention to reliability and performance.
   7.523 +      However, the attention to detail doesn't stop there.  There are
   7.524 +      a number of other aspects of Mercurial's construction that I
   7.525 +      personally find interesting.  I'll detail a few of them here,
   7.526 +      separate from the <quote>big ticket</quote> items above, so that
   7.527 +      if you're interested, you can gain a better idea of the amount
   7.528 +      of thinking that goes into a well-designed system.</para>
   7.529 +
   7.530 +    <sect2>
   7.531 +      <title>Clever compression</title>
   7.532 +
   7.533 +      <para>When appropriate, Mercurial will store both snapshots and
   7.534 +	deltas in compressed form.  It does this by always
   7.535 +	<emphasis>trying to</emphasis> compress a snapshot or delta,
   7.536 +	but only storing the compressed version if it's smaller than
   7.537 +	the uncompressed version.</para>
   7.538 +
   7.539 +      <para>This means that Mercurial does <quote>the right
   7.540 +	  thing</quote> when storing a file whose native form is
   7.541 +	compressed, such as a <literal>zip</literal> archive or a JPEG
   7.542 +	image.  When these types of files are compressed a second
   7.543 +	time, the resulting file is usually bigger than the
   7.544 +	once-compressed form, and so Mercurial will store the plain
   7.545 +	<literal>zip</literal> or JPEG.</para>
   7.546 +
   7.547 +      <para>Deltas between revisions of a compressed file are usually
   7.548 +	larger than snapshots of the file, and Mercurial again does
   7.549 +	<quote>the right thing</quote> in these cases.  It finds that
   7.550 +	such a delta exceeds the threshold at which it should store a
   7.551 +	complete snapshot of the file, so it stores the snapshot,
   7.552 +	again saving space compared to a naive delta-only
   7.553 +	approach.</para>
   7.554 +
   7.555 +      <sect3>
   7.556 +	<title>Network recompression</title>
   7.557 +
   7.558 +	<para>When storing revisions on disk, Mercurial uses the
   7.559 +	  <quote>deflate</quote> compression algorithm (the same one
   7.560 +	  used by the popular <literal>zip</literal> archive format),
   7.561 +	  which balances good speed with a respectable compression
   7.562 +	  ratio.  However, when transmitting revision data over a
   7.563 +	  network connection, Mercurial uncompresses the compressed
   7.564 +	  revision data.</para>
   7.565 +
   7.566 +	<para>If the connection is over HTTP, Mercurial recompresses
   7.567 +	  the entire stream of data using a compression algorithm that
   7.568 +	  gives a better compression ratio (the Burrows-Wheeler
   7.569 +	  algorithm from the widely used <literal>bzip2</literal>
   7.570 +	  compression package).  This combination of algorithm and
   7.571 +	  compression of the entire stream (instead of a revision at a
   7.572 +	  time) substantially reduces the number of bytes to be
   7.573 +	  transferred, yielding better network performance over almost
   7.574 +	  all kinds of network.</para>
   7.575 +
   7.576 +	<para>(If the connection is over <command>ssh</command>,
   7.577 +	  Mercurial <emphasis>doesn't</emphasis> recompress the
   7.578 +	  stream, because <command>ssh</command> can already do this
   7.579 +	  itself.)</para>
   7.580 +
   7.581 +      </sect3>
   7.582 +    </sect2>
   7.583 +    <sect2>
   7.584 +      <title>Read/write ordering and atomicity</title>
   7.585 +
   7.586 +      <para>Appending to files isn't the whole story when it comes to
   7.587 +	guaranteeing that a reader won't see a partial write.  If you
   7.588 +	recall figure <xref linkend="fig:concepts:metadata"/>,
   7.589 +	revisions in the
   7.590 +	changelog point to revisions in the manifest, and revisions in
   7.591 +	the manifest point to revisions in filelogs.  This hierarchy
   7.592 +	is deliberate.</para>
   7.593 +
   7.594 +      <para>A writer starts a transaction by writing filelog and
   7.595 +	manifest data, and doesn't write any changelog data until
   7.596 +	those are finished.  A reader starts by reading changelog
   7.597 +	data, then manifest data, followed by filelog data.</para>
   7.598 +
   7.599 +      <para>Since the writer has always finished writing filelog and
   7.600 +	manifest data before it writes to the changelog, a reader will
   7.601 +	never read a pointer to a partially written manifest revision
   7.602 +	from the changelog, and it will never read a pointer to a
   7.603 +	partially written filelog revision from the manifest.</para>
   7.604 +
   7.605 +    </sect2>
   7.606 +    <sect2>
   7.607 +      <title>Concurrent access</title>
   7.608 +
   7.609 +      <para>The read/write ordering and atomicity guarantees mean that
   7.610 +	Mercurial never needs to <emphasis>lock</emphasis> a
   7.611 +	repository when it's reading data, even if the repository is
   7.612 +	being written to while the read is occurring. This has a big
   7.613 +	effect on scalability; you can have an arbitrary number of
   7.614 +	Mercurial processes safely reading data from a repository
   7.615 +	safely all at once, no matter whether it's being written to or
   7.616 +	not.</para>
   7.617 +
   7.618 +      <para>The lockless nature of reading means that if you're
   7.619 +	sharing a repository on a multi-user system, you don't need to
   7.620 +	grant other local users permission to
   7.621 +	<emphasis>write</emphasis> to your repository in order for
   7.622 +	them to be able to clone it or pull changes from it; they only
   7.623 +	need <emphasis>read</emphasis> permission.  (This is
   7.624 +	<emphasis>not</emphasis> a common feature among revision
   7.625 +	control systems, so don't take it for granted!  Most require
   7.626 +	readers to be able to lock a repository to access it safely,
   7.627 +	and this requires write permission on at least one directory,
   7.628 +	which of course makes for all kinds of nasty and annoying
   7.629 +	security and administrative problems.)</para>
   7.630 +
   7.631 +      <para>Mercurial uses locks to ensure that only one process can
   7.632 +	write to a repository at a time (the locking mechanism is safe
   7.633 +	even over filesystems that are notoriously hostile to locking,
   7.634 +	such as NFS).  If a repository is locked, a writer will wait
   7.635 +	for a while to retry if the repository becomes unlocked, but
   7.636 +	if the repository remains locked for too long, the process
   7.637 +	attempting to write will time out after a while. This means
   7.638 +	that your daily automated scripts won't get stuck forever and
   7.639 +	pile up if a system crashes unnoticed, for example.  (Yes, the
   7.640 +	timeout is configurable, from zero to infinity.)</para>
   7.641 +
   7.642 +      <sect3>
   7.643 +	<title>Safe dirstate access</title>
   7.644 +
   7.645 +	<para>As with revision data, Mercurial doesn't take a lock to
   7.646 +	  read the dirstate file; it does acquire a lock to write it.
   7.647 +	  To avoid the possibility of reading a partially written copy
   7.648 +	  of the dirstate file, Mercurial writes to a file with a
   7.649 +	  unique name in the same directory as the dirstate file, then
   7.650 +	  renames the temporary file atomically to
   7.651 +	  <filename>dirstate</filename>.  The file named
   7.652 +	  <filename>dirstate</filename> is thus guaranteed to be
   7.653 +	  complete, not partially written.</para>
   7.654 +
   7.655 +      </sect3>
   7.656 +    </sect2>
   7.657 +    <sect2>
   7.658 +      <title>Avoiding seeks</title>
   7.659 +
   7.660 +      <para>Critical to Mercurial's performance is the avoidance of
   7.661 +	seeks of the disk head, since any seek is far more expensive
   7.662 +	than even a comparatively large read operation.</para>
   7.663 +
   7.664 +      <para>This is why, for example, the dirstate is stored in a
   7.665 +	single file.  If there were a dirstate file per directory that
   7.666 +	Mercurial tracked, the disk would seek once per directory.
   7.667 +	Instead, Mercurial reads the entire single dirstate file in
   7.668 +	one step.</para>
   7.669 +
   7.670 +      <para>Mercurial also uses a <quote>copy on write</quote> scheme
   7.671 +	when cloning a repository on local storage.  Instead of
   7.672 +	copying every revlog file from the old repository into the new
   7.673 +	repository, it makes a <quote>hard link</quote>, which is a
   7.674 +	shorthand way to say <quote>these two names point to the same
   7.675 +	  file</quote>.  When Mercurial is about to write to one of a
   7.676 +	revlog's files, it checks to see if the number of names
   7.677 +	pointing at the file is greater than one.  If it is, more than
   7.678 +	one repository is using the file, so Mercurial makes a new
   7.679 +	copy of the file that is private to this repository.</para>
   7.680 +
   7.681 +      <para>A few revision control developers have pointed out that
   7.682 +	this idea of making a complete private copy of a file is not
   7.683 +	very efficient in its use of storage.  While this is true,
   7.684 +	storage is cheap, and this method gives the highest
   7.685 +	performance while deferring most book-keeping to the operating
   7.686 +	system.  An alternative scheme would most likely reduce
   7.687 +	performance and increase the complexity of the software, each
   7.688 +	of which is much more important to the <quote>feel</quote> of
   7.689 +	day-to-day use.</para>
   7.690 +
   7.691 +    </sect2>
   7.692 +    <sect2>
   7.693 +      <title>Other contents of the dirstate</title>
   7.694 +
   7.695 +      <para>Because Mercurial doesn't force you to tell it when you're
   7.696 +	modifying a file, it uses the dirstate to store some extra
   7.697 +	information so it can determine efficiently whether you have
   7.698 +	modified a file.  For each file in the working directory, it
   7.699 +	stores the time that it last modified the file itself, and the
   7.700 +	size of the file at that time.</para>
   7.701 +
   7.702 +      <para>When you explicitly <command role="hg-cmd">hg
   7.703 +	  add</command>, <command role="hg-cmd">hg remove</command>,
   7.704 +	<command role="hg-cmd">hg rename</command> or <command
   7.705 +	  role="hg-cmd">hg copy</command> files, Mercurial updates the
   7.706 +	dirstate so that it knows what to do with those files when you
   7.707 +	commit.</para>
   7.708 +
   7.709 +      <para>When Mercurial is checking the states of files in the
   7.710 +	working directory, it first checks a file's modification time.
   7.711 +	If that has not changed, the file must not have been modified.
   7.712 +	If the file's size has changed, the file must have been
   7.713 +	modified.  If the modification time has changed, but the size
   7.714 +	has not, only then does Mercurial need to read the actual
   7.715 +	contents of the file to see if they've changed. Storing these
   7.716 +	few extra pieces of information dramatically reduces the
   7.717 +	amount of data that Mercurial needs to read, which yields
   7.718 +	large performance improvements compared to other revision
   7.719 +	control systems.</para>
   7.720 +
   7.721 +    </sect2>
   7.722 +  </sect1>
   7.723 +</chapter>
   7.724 +
   7.725 +<!--
   7.726 +local variables: 
   7.727 +sgml-parent-document: ("00book.xml" "book" "chapter")
   7.728 +end:
   7.729 +-->