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

     2.1 --- a/en/ch00-preface.xml	Thu May 07 21:06:49 2009 -0700
     2.2 +++ b/en/ch00-preface.xml	Thu May 07 21:07:35 2009 -0700
     2.3 @@ -5,751 +5,153 @@
     2.4    <title>Preface</title>
     2.5  
     2.6    <sect1>
     2.7 -    <title>Why revision control? Why Mercurial?</title>
     2.8 +    <title>Conventions Used in This Book</title>
     2.9  
    2.10 -    <para id="x_6d">Revision control is the process of managing multiple
    2.11 -      versions of a piece of information.  In its simplest form, this
    2.12 -      is something that many people do by hand: every time you modify
    2.13 -      a file, save it under a new name that contains a number, each
    2.14 -      one higher than the number of the preceding version.</para>
    2.15 +    <para>The following typographical conventions are used in this
    2.16 +      book:</para>
    2.17  
    2.18 -    <para id="x_6e">Manually managing multiple versions of even a single file is
    2.19 -      an error-prone task, though, so software tools to help automate
    2.20 -      this process have long been available.  The earliest automated
    2.21 -      revision control tools were intended to help a single user to
    2.22 -      manage revisions of a single file.  Over the past few decades,
    2.23 -      the scope of revision control tools has expanded greatly; they
    2.24 -      now manage multiple files, and help multiple people to work
    2.25 -      together.  The best modern revision control tools have no
    2.26 -      problem coping with thousands of people working together on
    2.27 -      projects that consist of hundreds of thousands of files.</para>
    2.28 +    <variablelist>
    2.29 +      <varlistentry>
    2.30 +        <term>Italic</term>
    2.31  
    2.32 -    <para id="x_6f">The arrival of distributed revision control is relatively
    2.33 -      recent, and so far this new field has grown due to people's
    2.34 -      willingness to explore ill-charted territory.</para>
    2.35 +        <listitem>
    2.36 +          <para>Indicates new terms, URLs, email addresses, filenames,
    2.37 +	    and file extensions.</para>
    2.38 +        </listitem>
    2.39 +      </varlistentry>
    2.40  
    2.41 -    <para id="x_70">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 +      <varlistentry>
    2.48 +        <term><literal>Constant width</literal></term>
    2.49  
    2.50 -    <sect2>
    2.51 -      <title>Why use revision control?</title>
    2.52 +        <listitem>
    2.53 +          <para>Used for program listings, as well as within
    2.54 +	    paragraphs to refer to program elements such as variable
    2.55 +	    or function names, databases, data types, environment
    2.56 +	    variables, statements, and keywords.</para>
    2.57 +        </listitem>
    2.58 +      </varlistentry>
    2.59  
    2.60 -      <para id="x_71">There are a number of reasons why you or your team might
    2.61 -	want to use an automated revision control tool for a
    2.62 -	project.</para>
    2.63 +      <varlistentry>
    2.64 +        <term><userinput>Constant width bold</userinput></term>
    2.65  
    2.66 -      <itemizedlist>
    2.67 -	<listitem><para id="x_72">It will track the history and evolution of
    2.68 -	    your project, so you don't have to.  For every change,
    2.69 -	    you'll have a log of <emphasis>who</emphasis> made it;
    2.70 -	    <emphasis>why</emphasis> they made it;
    2.71 -	    <emphasis>when</emphasis> they made it; and
    2.72 -	    <emphasis>what</emphasis> the change
    2.73 -	    was.</para></listitem>
    2.74 -	<listitem><para id="x_73">When you're working with other people,
    2.75 -	    revision control software makes it easier for you to
    2.76 -	    collaborate.  For example, when people more or less
    2.77 -	    simultaneously make potentially incompatible changes, the
    2.78 -	    software will help you to identify and resolve those
    2.79 -	    conflicts.</para></listitem>
    2.80 -	<listitem><para id="x_74">It can help you to recover from mistakes.  If
    2.81 -	    you make a change that later turns out to be in error, you
    2.82 -	    can revert to an earlier version of one or more files.  In
    2.83 -	    fact, a <emphasis>really</emphasis> good revision control
    2.84 -	    tool will even help you to efficiently figure out exactly
    2.85 -	    when a problem was introduced (see <xref
    2.86 -	      linkend="sec:undo:bisect"/> for details).</para></listitem>
    2.87 -	<listitem><para id="x_75">It will help you to work simultaneously on,
    2.88 -	    and manage the drift between, multiple versions of your
    2.89 -	    project.</para></listitem>
    2.90 -      </itemizedlist>
    2.91 +        <listitem>
    2.92 +          <para>Shows commands or other text that should be typed
    2.93 +	    literally by the user.</para>
    2.94 +        </listitem>
    2.95 +      </varlistentry>
    2.96  
    2.97 -      <para id="x_76">Most of these reasons are equally
    2.98 -	valid&emdash;at least in theory&emdash;whether you're working
    2.99 -	on a project by yourself, or with a hundred other
   2.100 -	people.</para>
   2.101 +      <varlistentry>
   2.102 +        <term><replaceable>Constant width italic</replaceable></term>
   2.103  
   2.104 -      <para id="x_77">A key question about the practicality of revision control
   2.105 -	at these two different scales (<quote>lone hacker</quote> and
   2.106 -	<quote>huge team</quote>) is how its
   2.107 -	<emphasis>benefits</emphasis> compare to its
   2.108 -	<emphasis>costs</emphasis>.  A revision control tool that's
   2.109 -	difficult to understand or use is going to impose a high
   2.110 -	cost.</para>
   2.111 +        <listitem>
   2.112 +          <para>Shows text that should be replaced with user-supplied
   2.113 +	    values or by values determined by context.</para>
   2.114 +        </listitem>
   2.115 +      </varlistentry>
   2.116 +    </variablelist>
   2.117  
   2.118 -      <para id="x_78">A five-hundred-person project is likely to collapse under
   2.119 -	its own weight almost immediately without a revision control
   2.120 -	tool and process. In this case, the cost of using revision
   2.121 -	control might hardly seem worth considering, since
   2.122 -	<emphasis>without</emphasis> it, failure is almost
   2.123 -	guaranteed.</para>
   2.124 +    <tip>
   2.125 +      <para>This icon signifies a tip, suggestion, or general
   2.126 +	note.</para>
   2.127 +    </tip>
   2.128  
   2.129 -      <para id="x_79">On the other hand, a one-person <quote>quick hack</quote>
   2.130 -	might seem like a poor place to use a revision control tool,
   2.131 -	because surely the cost of using one must be close to the
   2.132 -	overall cost of the project.  Right?</para>
   2.133 -
   2.134 -      <para id="x_7a">Mercurial uniquely supports <emphasis>both</emphasis> of
   2.135 -	these scales of development.  You can learn the basics in just
   2.136 -	a few minutes, and due to its low overhead, you can apply
   2.137 -	revision control to the smallest of projects with ease.  Its
   2.138 -	simplicity means you won't have a lot of abstruse concepts or
   2.139 -	command sequences competing for mental space with whatever
   2.140 -	you're <emphasis>really</emphasis> trying to do.  At the same
   2.141 -	time, Mercurial's high performance and peer-to-peer nature let
   2.142 -	you scale painlessly to handle large projects.</para>
   2.143 -
   2.144 -      <para id="x_7b">No revision control tool can rescue a poorly run project,
   2.145 -	but a good choice of tools can make a huge difference to the
   2.146 -	fluidity with which you can work on a project.</para>
   2.147 -
   2.148 -    </sect2>
   2.149 -
   2.150 -    <sect2>
   2.151 -      <title>The many names of revision control</title>
   2.152 -
   2.153 -      <para id="x_7c">Revision control is a diverse field, so much so that it is
   2.154 -	referred to by many names and acronyms.  Here are a few of the
   2.155 -	more common variations you'll encounter:</para>
   2.156 -      <itemizedlist>
   2.157 -	<listitem><para id="x_7d">Revision control (RCS)</para></listitem>
   2.158 -	<listitem><para id="x_7e">Software configuration management (SCM), or
   2.159 -	    configuration management</para></listitem>
   2.160 -	<listitem><para id="x_7f">Source code management</para></listitem>
   2.161 -	<listitem><para id="x_80">Source code control, or source
   2.162 -	    control</para></listitem>
   2.163 -	<listitem><para id="x_81">Version control
   2.164 -	    (VCS)</para></listitem></itemizedlist>
   2.165 -      <para id="x_82">Some people claim that these terms actually have different
   2.166 -	meanings, but in practice they overlap so much that there's no
   2.167 -	agreed or even useful way to tease them apart.</para>
   2.168 -
   2.169 -    </sect2>
   2.170 +    <caution>
   2.171 +      <para>This icon indicates a warning or caution.</para>
   2.172 +    </caution>
   2.173    </sect1>
   2.174  
   2.175    <sect1>
   2.176 -    <title>This book is a work in progress</title>
   2.177 +    <title>Using Code Examples</title>
   2.178  
   2.179 -    <para id="x_83">I am releasing this book while I am still writing it, in the
   2.180 -      hope that it will prove useful to others.  I am writing under an
   2.181 -      open license in the hope that you, my readers, will contribute
   2.182 -      feedback and perhaps content of your own.</para>
   2.183 +    <para>This book is here to help you get your job done. In general,
   2.184 +      you may use the code in this book in your programs and
   2.185 +      documentation. You do not need to contact us for permission
   2.186 +      unless you’re reproducing a significant portion of the code. For
   2.187 +      example, writing a program that uses several chunks of code from
   2.188 +      this book does not require permission. Selling or distributing a
   2.189 +      CD-ROM of examples from O’Reilly books does require permission.
   2.190 +      Answering a question by citing this book and quoting example
   2.191 +      code does not require permission. Incorporating a significant
   2.192 +      amount of example code from this book into your product’s
   2.193 +      documentation does require permission.</para>
   2.194  
   2.195 -  </sect1>
   2.196 -  <sect1>
   2.197 -    <title>About the examples in this book</title>
   2.198 +    <para>We appreciate, but do not require, attribution. An
   2.199 +      attribution usually includes the title, author, publisher, and
   2.200 +      ISBN. For example: “<emphasis>Book Title</emphasis> by Some
   2.201 +      Author. Copyright 2008 O’Reilly Media, Inc.,
   2.202 +      978-0-596-xxxx-x.”</para>
   2.203  
   2.204 -    <para id="x_84">This book takes an unusual approach to code samples.  Every
   2.205 -      example is <quote>live</quote>&emdash;each one is actually the result
   2.206 -      of a shell script that executes the Mercurial commands you see.
   2.207 -      Every time an image of the book is built from its sources, all
   2.208 -      the example scripts are automatically run, and their current
   2.209 -      results compared against their expected results.</para>
   2.210 -
   2.211 -    <para id="x_85">The advantage of this approach is that the examples are
   2.212 -      always accurate; they describe <emphasis>exactly</emphasis> the
   2.213 -      behavior of the version of Mercurial that's mentioned at the
   2.214 -      front of the book.  If I update the version of Mercurial that
   2.215 -      I'm documenting, and the output of some command changes, the
   2.216 -      build fails.</para>
   2.217 -
   2.218 -    <para id="x_86">There is a small disadvantage to this approach, which is
   2.219 -      that the dates and times you'll see in examples tend to be
   2.220 -      <quote>squashed</quote> together in a way that they wouldn't be
   2.221 -      if the same commands were being typed by a human.  Where a human
   2.222 -      can issue no more than one command every few seconds, with any
   2.223 -      resulting timestamps correspondingly spread out, my automated
   2.224 -      example scripts run many commands in one second.</para>
   2.225 -
   2.226 -    <para id="x_87">As an instance of this, several consecutive commits in an
   2.227 -      example can show up as having occurred during the same second.
   2.228 -      You can see this occur in the <literal
   2.229 -	role="hg-ext">bisect</literal> example in <xref
   2.230 -	linkend="sec:undo:bisect"/>, for instance.</para>
   2.231 -
   2.232 -    <para id="x_88">So when you're reading examples, don't place too much weight
   2.233 -      on the dates or times you see in the output of commands.  But
   2.234 -      <emphasis>do</emphasis> be confident that the behavior you're
   2.235 -      seeing is consistent and reproducible.</para>
   2.236 -
   2.237 +    <para>If you feel your use of code examples falls outside fair use
   2.238 +      or the permission given above, feel free to contact us at
   2.239 +      <email>permissions@oreilly.com</email>.</para>
   2.240    </sect1>
   2.241  
   2.242    <sect1>
   2.243 -    <title>Trends in the field</title>
   2.244 +    <title>Safari® Books Online</title>
   2.245  
   2.246 -    <para id="x_89">There has been an unmistakable trend in the development and
   2.247 -      use of revision control tools over the past four decades, as
   2.248 -      people have become familiar with the capabilities of their tools
   2.249 -      and constrained by their limitations.</para>
   2.250 +    <note role="safarienabled">
   2.251 +      <para>When you see a Safari® Books Online icon on the cover of
   2.252 +	your favorite technology book, that means the book is
   2.253 +	available online through the O’Reilly Network Safari
   2.254 +	Bookshelf.</para>
   2.255 +    </note>
   2.256  
   2.257 -    <para id="x_8a">The first generation began by managing single files on
   2.258 -      individual computers.  Although these tools represented a huge
   2.259 -      advance over ad-hoc manual revision control, their locking model
   2.260 -      and reliance on a single computer limited them to small,
   2.261 -      tightly-knit teams.</para>
   2.262 -
   2.263 -    <para id="x_8b">The second generation loosened these constraints by moving
   2.264 -      to network-centered architectures, and managing entire projects
   2.265 -      at a time.  As projects grew larger, they ran into new problems.
   2.266 -      With clients needing to talk to servers very frequently, server
   2.267 -      scaling became an issue for large projects.  An unreliable
   2.268 -      network connection could prevent remote users from being able to
   2.269 -      talk to the server at all.  As open source projects started
   2.270 -      making read-only access available anonymously to anyone, people
   2.271 -      without commit privileges found that they could not use the
   2.272 -      tools to interact with a project in a natural way, as they could
   2.273 -      not record their changes.</para>
   2.274 -
   2.275 -    <para id="x_8c">The current generation of revision control tools is
   2.276 -      peer-to-peer in nature.  All of these systems have dropped the
   2.277 -      dependency on a single central server, and allow people to
   2.278 -      distribute their revision control data to where it's actually
   2.279 -      needed.  Collaboration over the Internet has moved from
   2.280 -      constrained by technology to a matter of choice and consensus.
   2.281 -      Modern tools can operate offline indefinitely and autonomously,
   2.282 -      with a network connection only needed when syncing changes with
   2.283 -      another repository.</para>
   2.284 -
   2.285 -  </sect1>
   2.286 -  <sect1>
   2.287 -    <title>A few of the advantages of distributed revision
   2.288 -      control</title>
   2.289 -
   2.290 -    <para id="x_8d">Even though distributed revision control tools have for
   2.291 -      several years been as robust and usable as their
   2.292 -      previous-generation counterparts, people using older tools have
   2.293 -      not yet necessarily woken up to their advantages.  There are a
   2.294 -      number of ways in which distributed tools shine relative to
   2.295 -      centralised ones.</para>
   2.296 -
   2.297 -    <para id="x_8e">For an individual developer, distributed tools are almost
   2.298 -      always much faster than centralised tools.  This is for a simple
   2.299 -      reason: a centralised tool needs to talk over the network for
   2.300 -      many common operations, because most metadata is stored in a
   2.301 -      single copy on the central server.  A distributed tool stores
   2.302 -      all of its metadata locally.  All else being equal, talking over
   2.303 -      the network adds overhead to a centralised tool.  Don't
   2.304 -      underestimate the value of a snappy, responsive tool: you're
   2.305 -      going to spend a lot of time interacting with your revision
   2.306 -      control software.</para>
   2.307 -
   2.308 -    <para id="x_8f">Distributed tools are indifferent to the vagaries of your
   2.309 -      server infrastructure, again because they replicate metadata to
   2.310 -      so many locations.  If you use a centralised system and your
   2.311 -      server catches fire, you'd better hope that your backup media
   2.312 -      are reliable, and that your last backup was recent and actually
   2.313 -      worked.  With a distributed tool, you have many backups
   2.314 -      available on every contributor's computer.</para>
   2.315 -
   2.316 -    <para id="x_90">The reliability of your network will affect distributed
   2.317 -      tools far less than it will centralised tools.  You can't even
   2.318 -      use a centralised tool without a network connection, except for
   2.319 -      a few highly constrained commands.  With a distributed tool, if
   2.320 -      your network connection goes down while you're working, you may
   2.321 -      not even notice.  The only thing you won't be able to do is talk
   2.322 -      to repositories on other computers, something that is relatively
   2.323 -      rare compared with local operations.  If you have a far-flung
   2.324 -      team of collaborators, this may be significant.</para>
   2.325 -
   2.326 -    <sect2>
   2.327 -      <title>Advantages for open source projects</title>
   2.328 -
   2.329 -      <para id="x_91">If you take a shine to an open source project and decide
   2.330 -	that you would like to start hacking on it, and that project
   2.331 -	uses a distributed revision control tool, you are at once a
   2.332 -	peer with the people who consider themselves the
   2.333 -	<quote>core</quote> of that project.  If they publish their
   2.334 -	repositories, you can immediately copy their project history,
   2.335 -	start making changes, and record your work, using the same
   2.336 -	tools in the same ways as insiders.  By contrast, with a
   2.337 -	centralised tool, you must use the software in a <quote>read
   2.338 -	  only</quote> mode unless someone grants you permission to
   2.339 -	commit changes to their central server.  Until then, you won't
   2.340 -	be able to record changes, and your local modifications will
   2.341 -	be at risk of corruption any time you try to update your
   2.342 -	client's view of the repository.</para>
   2.343 -
   2.344 -      <sect3>
   2.345 -	<title>The forking non-problem</title>
   2.346 -
   2.347 -	<para id="x_92">It has been suggested that distributed revision control
   2.348 -	  tools pose some sort of risk to open source projects because
   2.349 -	  they make it easy to <quote>fork</quote> the development of
   2.350 -	  a project.  A fork happens when there are differences in
   2.351 -	  opinion or attitude between groups of developers that cause
   2.352 -	  them to decide that they can't work together any longer.
   2.353 -	  Each side takes a more or less complete copy of the
   2.354 -	  project's source code, and goes off in its own
   2.355 -	  direction.</para>
   2.356 -
   2.357 -	<para id="x_93">Sometimes the camps in a fork decide to reconcile their
   2.358 -	  differences. With a centralised revision control system, the
   2.359 -	  <emphasis>technical</emphasis> process of reconciliation is
   2.360 -	  painful, and has to be performed largely by hand.  You have
   2.361 -	  to decide whose revision history is going to
   2.362 -	  <quote>win</quote>, and graft the other team's changes into
   2.363 -	  the tree somehow. This usually loses some or all of one
   2.364 -	  side's revision history.</para>
   2.365 -
   2.366 -	<para id="x_94">What distributed tools do with respect to forking is
   2.367 -	  they make forking the <emphasis>only</emphasis> way to
   2.368 -	  develop a project.  Every single change that you make is
   2.369 -	  potentially a fork point.  The great strength of this
   2.370 -	  approach is that a distributed revision control tool has to
   2.371 -	  be really good at <emphasis>merging</emphasis> forks,
   2.372 -	  because forks are absolutely fundamental: they happen all
   2.373 -	  the time.</para>
   2.374 -
   2.375 -	<para id="x_95">If every piece of work that everybody does, all the
   2.376 -	  time, is framed in terms of forking and merging, then what
   2.377 -	  the open source world refers to as a <quote>fork</quote>
   2.378 -	  becomes <emphasis>purely</emphasis> a social issue.  If
   2.379 -	  anything, distributed tools <emphasis>lower</emphasis> the
   2.380 -	  likelihood of a fork:</para>
   2.381 -	<itemizedlist>
   2.382 -	  <listitem><para id="x_96">They eliminate the social distinction that
   2.383 -	      centralised tools impose: that between insiders (people
   2.384 -	      with commit access) and outsiders (people
   2.385 -	      without).</para></listitem>
   2.386 -	  <listitem><para id="x_97">They make it easier to reconcile after a
   2.387 -	      social fork, because all that's involved from the
   2.388 -	      perspective of the revision control software is just
   2.389 -	      another merge.</para></listitem></itemizedlist>
   2.390 -
   2.391 -	<para id="x_98">Some people resist distributed tools because they want
   2.392 -	  to retain tight control over their projects, and they
   2.393 -	  believe that centralised tools give them this control.
   2.394 -	  However, if you're of this belief, and you publish your CVS
   2.395 -	  or Subversion repositories publicly, there are plenty of
   2.396 -	  tools available that can pull out your entire project's
   2.397 -	  history (albeit slowly) and recreate it somewhere that you
   2.398 -	  don't control.  So while your control in this case is
   2.399 -	  illusory, you are forgoing the ability to fluidly
   2.400 -	  collaborate with whatever people feel compelled to mirror
   2.401 -	  and fork your history.</para>
   2.402 -
   2.403 -      </sect3>
   2.404 -    </sect2>
   2.405 -    <sect2>
   2.406 -      <title>Advantages for commercial projects</title>
   2.407 -
   2.408 -      <para id="x_99">Many commercial projects are undertaken by teams that are
   2.409 -	scattered across the globe.  Contributors who are far from a
   2.410 -	central server will see slower command execution and perhaps
   2.411 -	less reliability.  Commercial revision control systems attempt
   2.412 -	to ameliorate these problems with remote-site replication
   2.413 -	add-ons that are typically expensive to buy and cantankerous
   2.414 -	to administer.  A distributed system doesn't suffer from these
   2.415 -	problems in the first place.  Better yet, you can easily set
   2.416 -	up multiple authoritative servers, say one per site, so that
   2.417 -	there's no redundant communication between repositories over
   2.418 -	expensive long-haul network links.</para>
   2.419 -
   2.420 -      <para id="x_9a">Centralised revision control systems tend to have
   2.421 -	relatively low scalability.  It's not unusual for an expensive
   2.422 -	centralised system to fall over under the combined load of
   2.423 -	just a few dozen concurrent users.  Once again, the typical
   2.424 -	response tends to be an expensive and clunky replication
   2.425 -	facility.  Since the load on a central server&emdash;if you have
   2.426 -	one at all&emdash;is many times lower with a distributed tool
   2.427 -	(because all of the data is replicated everywhere), a single
   2.428 -	cheap server can handle the needs of a much larger team, and
   2.429 -	replication to balance load becomes a simple matter of
   2.430 -	scripting.</para>
   2.431 -
   2.432 -      <para id="x_9b">If you have an employee in the field, troubleshooting a
   2.433 -	problem at a customer's site, they'll benefit from distributed
   2.434 -	revision control. The tool will let them generate custom
   2.435 -	builds, try different fixes in isolation from each other, and
   2.436 -	search efficiently through history for the sources of bugs and
   2.437 -	regressions in the customer's environment, all without needing
   2.438 -	to connect to your company's network.</para>
   2.439 -
   2.440 -    </sect2>
   2.441 -  </sect1>
   2.442 -  <sect1>
   2.443 -    <title>Why choose Mercurial?</title>
   2.444 -
   2.445 -    <para id="x_9c">Mercurial has a unique set of properties that make it a
   2.446 -      particularly good choice as a revision control system.</para>
   2.447 -    <itemizedlist>
   2.448 -      <listitem><para id="x_9d">It is easy to learn and use.</para></listitem>
   2.449 -      <listitem><para id="x_9e">It is lightweight.</para></listitem>
   2.450 -      <listitem><para id="x_9f">It scales excellently.</para></listitem>
   2.451 -      <listitem><para id="x_a0">It is easy to
   2.452 -	  customise.</para></listitem></itemizedlist>
   2.453 -
   2.454 -    <para id="x_a1">If you are at all familiar with revision control systems,
   2.455 -      you should be able to get up and running with Mercurial in less
   2.456 -      than five minutes.  Even if not, it will take no more than a few
   2.457 -      minutes longer.  Mercurial's command and feature sets are
   2.458 -      generally uniform and consistent, so you can keep track of a few
   2.459 -      general rules instead of a host of exceptions.</para>
   2.460 -
   2.461 -    <para id="x_a2">On a small project, you can start working with Mercurial in
   2.462 -      moments. Creating new changes and branches; transferring changes
   2.463 -      around (whether locally or over a network); and history and
   2.464 -      status operations are all fast.  Mercurial attempts to stay
   2.465 -      nimble and largely out of your way by combining low cognitive
   2.466 -      overhead with blazingly fast operations.</para>
   2.467 -
   2.468 -    <para id="x_a3">The usefulness of Mercurial is not limited to small
   2.469 -      projects: it is used by projects with hundreds to thousands of
   2.470 -      contributors, each containing tens of thousands of files and
   2.471 -      hundreds of megabytes of source code.</para>
   2.472 -
   2.473 -    <para id="x_a4">If the core functionality of Mercurial is not enough for
   2.474 -      you, it's easy to build on.  Mercurial is well suited to
   2.475 -      scripting tasks, and its clean internals and implementation in
   2.476 -      Python make it easy to add features in the form of extensions.
   2.477 -      There are a number of popular and useful extensions already
   2.478 -      available, ranging from helping to identify bugs to improving
   2.479 -      performance.</para>
   2.480 -
   2.481 -  </sect1>
   2.482 -  <sect1>
   2.483 -    <title>Mercurial compared with other tools</title>
   2.484 -
   2.485 -    <para id="x_a5">Before you read on, please understand that this section
   2.486 -      necessarily reflects my own experiences, interests, and (dare I
   2.487 -      say it) biases.  I have used every one of the revision control
   2.488 -      tools listed below, in most cases for several years at a
   2.489 -      time.</para>
   2.490 -
   2.491 -
   2.492 -    <sect2>
   2.493 -      <title>Subversion</title>
   2.494 -
   2.495 -      <para id="x_a6">Subversion is a popular revision control tool, developed
   2.496 -	to replace CVS.  It has a centralised client/server
   2.497 -	architecture.</para>
   2.498 -
   2.499 -      <para id="x_a7">Subversion and Mercurial have similarly named commands for
   2.500 -	performing the same operations, so if you're familiar with
   2.501 -	one, it is easy to learn to use the other.  Both tools are
   2.502 -	portable to all popular operating systems.</para>
   2.503 -
   2.504 -      <para id="x_a8">Prior to version 1.5, Subversion had no useful support for
   2.505 -	merges. At the time of writing, its merge tracking capability
   2.506 -	is new, and known to be <ulink
   2.507 -	  url="http://svnbook.red-bean.com/nightly/en/svn.branchmerge.advanced.html#svn.branchmerge.advanced.finalword">complicated 
   2.508 -	  and buggy</ulink>.</para>
   2.509 -
   2.510 -      <para id="x_a9">Mercurial has a substantial performance advantage over
   2.511 -	Subversion on every revision control operation I have
   2.512 -	benchmarked.  I have measured its advantage as ranging from a
   2.513 -	factor of two to a factor of six when compared with Subversion
   2.514 -	1.4.3's <emphasis>ra_local</emphasis> file store, which is the
   2.515 -	fastest access method available.  In more realistic
   2.516 -	deployments involving a network-based store, Subversion will
   2.517 -	be at a substantially larger disadvantage.  Because many
   2.518 -	Subversion commands must talk to the server and Subversion
   2.519 -	does not have useful replication facilities, server capacity
   2.520 -	and network bandwidth become bottlenecks for modestly large
   2.521 -	projects.</para>
   2.522 -
   2.523 -      <para id="x_aa">Additionally, Subversion incurs substantial storage
   2.524 -	overhead to avoid network transactions for a few common
   2.525 -	operations, such as finding modified files
   2.526 -	(<literal>status</literal>) and displaying modifications
   2.527 -	against the current revision (<literal>diff</literal>).  As a
   2.528 -	result, a Subversion working copy is often the same size as,
   2.529 -	or larger than, a Mercurial repository and working directory,
   2.530 -	even though the Mercurial repository contains a complete
   2.531 -	history of the project.</para>
   2.532 -
   2.533 -      <para id="x_ab">Subversion is widely supported by third party tools.
   2.534 -	Mercurial currently lags considerably in this area.  This gap
   2.535 -	is closing, however, and indeed some of Mercurial's GUI tools
   2.536 -	now outshine their Subversion equivalents.  Like Mercurial,
   2.537 -	Subversion has an excellent user manual.</para>
   2.538 -
   2.539 -      <para id="x_ac">Because Subversion doesn't store revision history on the
   2.540 -	client, it is well suited to managing projects that deal with
   2.541 -	lots of large, opaque binary files.  If you check in fifty
   2.542 -	revisions to an incompressible 10MB file, Subversion's
   2.543 -	client-side space usage stays constant The space used by any
   2.544 -	distributed SCM will grow rapidly in proportion to the number
   2.545 -	of revisions, because the differences between each revision
   2.546 -	are large.</para>
   2.547 -
   2.548 -      <para id="x_ad">In addition, it's often difficult or, more usually,
   2.549 -	impossible to merge different versions of a binary file.
   2.550 -	Subversion's ability to let a user lock a file, so that they
   2.551 -	temporarily have the exclusive right to commit changes to it,
   2.552 -	can be a significant advantage to a project where binary files
   2.553 -	are widely used.</para>
   2.554 -
   2.555 -      <para id="x_ae">Mercurial can import revision history from a Subversion
   2.556 -	repository. It can also export revision history to a
   2.557 -	Subversion repository.  This makes it easy to <quote>test the
   2.558 -	  waters</quote> and use Mercurial and Subversion in parallel
   2.559 -	before deciding to switch.  History conversion is incremental,
   2.560 -	so you can perform an initial conversion, then small
   2.561 -	additional conversions afterwards to bring in new
   2.562 -	changes.</para>
   2.563 -
   2.564 -
   2.565 -    </sect2>
   2.566 -    <sect2>
   2.567 -      <title>Git</title>
   2.568 -
   2.569 -      <para id="x_af">Git is a distributed revision control tool that was
   2.570 -	developed for managing the Linux kernel source tree.  Like
   2.571 -	Mercurial, its early design was somewhat influenced by
   2.572 -	Monotone.</para>
   2.573 -
   2.574 -      <para id="x_b0">Git has a very large command set, with version 1.5.0
   2.575 -	providing 139 individual commands.  It has something of a
   2.576 -	reputation for being difficult to learn.  Compared to Git,
   2.577 -	Mercurial has a strong focus on simplicity.</para>
   2.578 -
   2.579 -      <para id="x_b1">In terms of performance, Git is extremely fast.  In
   2.580 -	several cases, it is faster than Mercurial, at least on Linux,
   2.581 -	while Mercurial performs better on other operations.  However,
   2.582 -	on Windows, the performance and general level of support that
   2.583 -	Git provides is, at the time of writing, far behind that of
   2.584 -	Mercurial.</para>
   2.585 -
   2.586 -      <para id="x_b2">While a Mercurial repository needs no maintenance, a Git
   2.587 -	repository requires frequent manual <quote>repacks</quote> of
   2.588 -	its metadata.  Without these, performance degrades, while
   2.589 -	space usage grows rapidly.  A server that contains many Git
   2.590 -	repositories that are not rigorously and frequently repacked
   2.591 -	will become heavily disk-bound during backups, and there have
   2.592 -	been instances of daily backups taking far longer than 24
   2.593 -	hours as a result.  A freshly packed Git repository is
   2.594 -	slightly smaller than a Mercurial repository, but an unpacked
   2.595 -	repository is several orders of magnitude larger.</para>
   2.596 -
   2.597 -      <para id="x_b3">The core of Git is written in C.  Many Git commands are
   2.598 -	implemented as shell or Perl scripts, and the quality of these
   2.599 -	scripts varies widely. I have encountered several instances
   2.600 -	where scripts charged along blindly in the presence of errors
   2.601 -	that should have been fatal.</para>
   2.602 -
   2.603 -      <para id="x_b4">Mercurial can import revision history from a Git
   2.604 -	repository.</para>
   2.605 -
   2.606 -
   2.607 -    </sect2>
   2.608 -    <sect2>
   2.609 -      <title>CVS</title>
   2.610 -
   2.611 -      <para id="x_b5">CVS is probably the most widely used revision control tool
   2.612 -	in the world.  Due to its age and internal untidiness, it has
   2.613 -	been only lightly maintained for many years.</para>
   2.614 -
   2.615 -      <para id="x_b6">It has a centralised client/server architecture.  It does
   2.616 -	not group related file changes into atomic commits, making it
   2.617 -	easy for people to <quote>break the build</quote>: one person
   2.618 -	can successfully commit part of a change and then be blocked
   2.619 -	by the need for a merge, causing other people to see only a
   2.620 -	portion of the work they intended to do.  This also affects
   2.621 -	how you work with project history.  If you want to see all of
   2.622 -	the modifications someone made as part of a task, you will
   2.623 -	need to manually inspect the descriptions and timestamps of
   2.624 -	the changes made to each file involved (if you even know what
   2.625 -	those files were).</para>
   2.626 -
   2.627 -      <para id="x_b7">CVS has a muddled notion of tags and branches that I will
   2.628 -	not attempt to even describe.  It does not support renaming of
   2.629 -	files or directories well, making it easy to corrupt a
   2.630 -	repository.  It has almost no internal consistency checking
   2.631 -	capabilities, so it is usually not even possible to tell
   2.632 -	whether or how a repository is corrupt.  I would not recommend
   2.633 -	CVS for any project, existing or new.</para>
   2.634 -
   2.635 -      <para id="x_b8">Mercurial can import CVS revision history.  However, there
   2.636 -	are a few caveats that apply; these are true of every other
   2.637 -	revision control tool's CVS importer, too.  Due to CVS's lack
   2.638 -	of atomic changes and unversioned filesystem hierarchy, it is
   2.639 -	not possible to reconstruct CVS history completely accurately;
   2.640 -	some guesswork is involved, and renames will usually not show
   2.641 -	up.  Because a lot of advanced CVS administration has to be
   2.642 -	done by hand and is hence error-prone, it's common for CVS
   2.643 -	importers to run into multiple problems with corrupted
   2.644 -	repositories (completely bogus revision timestamps and files
   2.645 -	that have remained locked for over a decade are just two of
   2.646 -	the less interesting problems I can recall from personal
   2.647 -	experience).</para>
   2.648 -
   2.649 -      <para id="x_b9">Mercurial can import revision history from a CVS
   2.650 -	repository.</para>
   2.651 -
   2.652 -
   2.653 -    </sect2>
   2.654 -    <sect2>
   2.655 -      <title>Commercial tools</title>
   2.656 -
   2.657 -      <para id="x_ba">Perforce has a centralised client/server architecture,
   2.658 -	with no client-side caching of any data.  Unlike modern
   2.659 -	revision control tools, Perforce requires that a user run a
   2.660 -	command to inform the server about every file they intend to
   2.661 -	edit.</para>
   2.662 -
   2.663 -      <para id="x_bb">The performance of Perforce is quite good for small teams,
   2.664 -	but it falls off rapidly as the number of users grows beyond a
   2.665 -	few dozen. Modestly large Perforce installations require the
   2.666 -	deployment of proxies to cope with the load their users
   2.667 -	generate.</para>
   2.668 -
   2.669 -
   2.670 -    </sect2>
   2.671 -    <sect2>
   2.672 -      <title>Choosing a revision control tool</title>
   2.673 -
   2.674 -      <para id="x_bc">With the exception of CVS, all of the tools listed above
   2.675 -	have unique strengths that suit them to particular styles of
   2.676 -	work.  There is no single revision control tool that is best
   2.677 -	in all situations.</para>
   2.678 -
   2.679 -      <para id="x_bd">As an example, Subversion is a good choice for working
   2.680 -	with frequently edited binary files, due to its centralised
   2.681 -	nature and support for file locking.</para>
   2.682 -
   2.683 -      <para id="x_be">I personally find Mercurial's properties of simplicity,
   2.684 -	performance, and good merge support to be a compelling
   2.685 -	combination that has served me well for several years.</para>
   2.686 -
   2.687 -
   2.688 -    </sect2>
   2.689 -  </sect1>
   2.690 -  <sect1>
   2.691 -    <title>Switching from another tool to Mercurial</title>
   2.692 -
   2.693 -    <para id="x_bf">Mercurial is bundled with an extension named <literal
   2.694 -	role="hg-ext">convert</literal>, which can incrementally
   2.695 -      import revision history from several other revision control
   2.696 -      tools.  By <quote>incremental</quote>, I mean that you can
   2.697 -      convert all of a project's history to date in one go, then rerun
   2.698 -      the conversion later to obtain new changes that happened after
   2.699 -      the initial conversion.</para>
   2.700 -
   2.701 -    <para id="x_c0">The revision control tools supported by <literal
   2.702 -	role="hg-ext">convert</literal> are as follows:</para>
   2.703 -    <itemizedlist>
   2.704 -      <listitem><para id="x_c1">Subversion</para></listitem>
   2.705 -      <listitem><para id="x_c2">CVS</para></listitem>
   2.706 -      <listitem><para id="x_c3">Git</para></listitem>
   2.707 -      <listitem><para id="x_c4">Darcs</para></listitem></itemizedlist>
   2.708 -
   2.709 -    <para id="x_c5">In addition, <literal role="hg-ext">convert</literal> can
   2.710 -      export changes from Mercurial to Subversion.  This makes it
   2.711 -      possible to try Subversion and Mercurial in parallel before
   2.712 -      committing to a switchover, without risking the loss of any
   2.713 -      work.</para>
   2.714 -
   2.715 -    <para id="x_c6">The <command role="hg-ext-convert">convert</command> command
   2.716 -      is easy to use.  Simply point it at the path or URL of the
   2.717 -      source repository, optionally give it the name of the
   2.718 -      destination repository, and it will start working.  After the
   2.719 -      initial conversion, just run the same command again to import
   2.720 -      new changes.</para>
   2.721 +    <para>Safari offers a solution that’s better than e-books. It’s a
   2.722 +      virtual library that lets you easily search thousands of top
   2.723 +      tech books, cut and paste code samples, download chapters, and
   2.724 +      find quick answers when you need the most accurate, current
   2.725 +      information. Try it for free at <ulink role="orm:hideurl:ital"
   2.726 +	url="http://my.safaribooksonline.com/?portal=oreilly">http://my.safaribooksonline.com</ulink>.</para>
   2.727    </sect1>
   2.728  
   2.729    <sect1>
   2.730 -    <title>A short history of revision control</title>
   2.731 +    <title>How to Contact Us</title>
   2.732  
   2.733 -    <para id="x_c7">The best known of the old-time revision control tools is
   2.734 -      SCCS (Source Code Control System), which Marc Rochkind wrote at
   2.735 -      Bell Labs, in the early 1970s.  SCCS operated on individual
   2.736 -      files, and required every person working on a project to have
   2.737 -      access to a shared workspace on a single system.  Only one
   2.738 -      person could modify a file at any time; arbitration for access
   2.739 -      to files was via locks.  It was common for people to lock files,
   2.740 -      and later forget to unlock them, preventing anyone else from
   2.741 -      modifying those files without the help of an
   2.742 -      administrator.</para>
   2.743 +    <para>Please address comments and questions concerning this book
   2.744 +      to the publisher:</para>
   2.745  
   2.746 -    <para id="x_c8">Walter Tichy developed a free alternative to SCCS in the
   2.747 -      early 1980s; he called his program RCS (Revision Control System).
   2.748 -      Like SCCS, RCS required developers to work in a single shared
   2.749 -      workspace, and to lock files to prevent multiple people from
   2.750 -      modifying them simultaneously.</para>
   2.751 +    <simplelist type="vert">
   2.752 +      <member>O’Reilly Media, Inc.</member>
   2.753  
   2.754 -    <para id="x_c9">Later in the 1980s, Dick Grune used RCS as a building block
   2.755 -      for a set of shell scripts he initially called cmt, but then
   2.756 -      renamed to CVS (Concurrent Versions System).  The big innovation
   2.757 -      of CVS was that it let developers work simultaneously and
   2.758 -      somewhat independently in their own personal workspaces.  The
   2.759 -      personal workspaces prevented developers from stepping on each
   2.760 -      other's toes all the time, as was common with SCCS and RCS. Each
   2.761 -      developer had a copy of every project file, and could modify
   2.762 -      their copies independently.  They had to merge their edits prior
   2.763 -      to committing changes to the central repository.</para>
   2.764 +      <member>1005 Gravenstein Highway North</member>
   2.765  
   2.766 -    <para id="x_ca">Brian Berliner took Grune's original scripts and rewrote
   2.767 -      them in C, releasing in 1989 the code that has since developed
   2.768 -      into the modern version of CVS.  CVS subsequently acquired the
   2.769 -      ability to operate over a network connection, giving it a
   2.770 -      client/server architecture.  CVS's architecture is centralised;
   2.771 -      only the server has a copy of the history of the project. Client
   2.772 -      workspaces just contain copies of recent versions of the
   2.773 -      project's files, and a little metadata to tell them where the
   2.774 -      server is.  CVS has been enormously successful; it is probably
   2.775 -      the world's most widely used revision control system.</para>
   2.776 +      <member>Sebastopol, CA 95472</member>
   2.777  
   2.778 -    <para id="x_cb">In the early 1990s, Sun Microsystems developed an early
   2.779 -      distributed revision control system, called TeamWare.  A
   2.780 -      TeamWare workspace contains a complete copy of the project's
   2.781 -      history.  TeamWare has no notion of a central repository.  (CVS
   2.782 -      relied upon RCS for its history storage; TeamWare used
   2.783 -      SCCS.)</para>
   2.784 +      <member>800-998-9938 (in the United States or Canada)</member>
   2.785  
   2.786 -    <para id="x_cc">As the 1990s progressed, awareness grew of a number of
   2.787 -      problems with CVS.  It records simultaneous changes to multiple
   2.788 -      files individually, instead of grouping them together as a
   2.789 -      single logically atomic operation.  It does not manage its file
   2.790 -      hierarchy well; it is easy to make a mess of a repository by
   2.791 -      renaming files and directories.  Worse, its source code is
   2.792 -      difficult to read and maintain, which made the <quote>pain
   2.793 -	level</quote> of fixing these architectural problems
   2.794 -      prohibitive.</para>
   2.795 +      <member>707-829-0515 (international or local)</member>
   2.796  
   2.797 -    <para id="x_cd">In 2001, Jim Blandy and Karl Fogel, two developers who had
   2.798 -      worked on CVS, started a project to replace it with a tool that
   2.799 -      would have a better architecture and cleaner code.  The result,
   2.800 -      Subversion, does not stray from CVS's centralised client/server
   2.801 -      model, but it adds multi-file atomic commits, better namespace
   2.802 -      management, and a number of other features that make it a
   2.803 -      generally better tool than CVS. Since its initial release, it
   2.804 -      has rapidly grown in popularity.</para>
   2.805 +      <member>707 829-0104 (fax)</member>
   2.806 +    </simplelist>
   2.807  
   2.808 -    <para id="x_ce">More or less simultaneously, Graydon Hoare began working on
   2.809 -      an ambitious distributed revision control system that he named
   2.810 -      Monotone. While Monotone addresses many of CVS's design flaws
   2.811 -      and has a peer-to-peer architecture, it goes beyond earlier (and
   2.812 -      subsequent) revision control tools in a number of innovative
   2.813 -      ways.  It uses cryptographic hashes as identifiers, and has an
   2.814 -      integral notion of <quote>trust</quote> for code from different
   2.815 -      sources.</para>
   2.816 +    <para>We have a web page for this book, where we list errata,
   2.817 +      examples, and any additional information. You can access this
   2.818 +      page at:</para>
   2.819  
   2.820 -    <para id="x_cf">Mercurial began life in 2005.  While a few aspects of its
   2.821 -      design are influenced by Monotone, Mercurial focuses on ease of
   2.822 -      use, high performance, and scalability to very large
   2.823 -      projects.</para>
   2.824 +    <simplelist type="vert">
   2.825 +      <member><ulink url="http://www.oreilly.com/catalog/&lt;catalog
   2.826 +	  page&gt;"></ulink></member>
   2.827 +    </simplelist>
   2.828  
   2.829 -  </sect1>
   2.830 +    <remark>Don’t forget to update the &lt;url&gt; attribute,
   2.831 +      too.</remark>
   2.832  
   2.833 -  <sect1>
   2.834 -    <title>Colophon&emdash;this book is Free</title>
   2.835 +    <para>To comment or ask technical questions about this book, send
   2.836 +      email to:</para>
   2.837  
   2.838 -    <para id="x_d0">This book is licensed under the Open Publication License,
   2.839 -      and is produced entirely using Free Software tools.  It is
   2.840 -      typeset with DocBook XML.  Illustrations are drawn and rendered with
   2.841 -      <ulink url="http://www.inkscape.org/">Inkscape</ulink>.</para>
   2.842 +    <simplelist type="vert">
   2.843 +      <member><email>bookquestions@oreilly.com</email></member>
   2.844 +    </simplelist>
   2.845  
   2.846 -    <para id="x_d1">The complete source code for this book is published as a
   2.847 -      Mercurial repository, at <ulink
   2.848 -	url="http://hg.serpentine.com/mercurial/book">http://hg.serpentine.com/mercurial/book</ulink>.</para>
   2.849 +    <para>For more information about our books, conferences, Resource
   2.850 +      Centers, and the O’Reilly Network, see our web site at:</para>
   2.851  
   2.852 +    <simplelist type="vert">
   2.853 +      <member><ulink url="http://www.oreilly.com"></ulink></member>
   2.854 +    </simplelist>
   2.855    </sect1>
   2.856  </preface>
   2.857 +
   2.858  <!--
   2.859  local variables: 
   2.860  sgml-parent-document: ("00book.xml" "book" "preface")

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

     4.1 --- a/en/ch01-tour-basic.xml	Thu May 07 21:06:49 2009 -0700
     4.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.3 @@ -1,1035 +0,0 @@
     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 id="x_1">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>Windows</title>
    4.19 -
    4.20 -      <para id="x_c">The best version of Mercurial for Windows is
    4.21 -	TortoiseHg, which can be found at <ulink
    4.22 -	  url="http://bitbucket.org/tortoisehg/stable/wiki/Home">http://bitbucket.org/tortoisehg/stable/wiki/Home</ulink>. 
    4.23 -	This package has no external dependencies; it <quote>just
    4.24 -	  works</quote>.  It provides both command line and graphical
    4.25 -	user interfaces.</para>
    4.26 -
    4.27 -    </sect2>
    4.28 -
    4.29 -    <sect2>
    4.30 -      <title>Mac OS X</title>
    4.31 -
    4.32 -      <para id="x_a">Lee Cantey publishes an installer of Mercurial
    4.33 -	for Mac OS X at <ulink
    4.34 -	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para>
    4.35 -    </sect2>
    4.36 -
    4.37 -    <sect2>
    4.38 -      <title>Linux</title>
    4.39 -
    4.40 -      <para id="x_2">Because each Linux distribution has its own packaging
    4.41 -	tools, policies, and rate of development, it's difficult to
    4.42 -	give a comprehensive set of instructions on how to install
    4.43 -	Mercurial binaries.  The version of Mercurial that you will
    4.44 -	end up with can vary depending on how active the person is who
    4.45 -	maintains the package for your distribution.</para>
    4.46 -
    4.47 -      <para id="x_3">To keep things simple, I will focus on installing
    4.48 -	Mercurial from the command line under the most popular Linux
    4.49 -	distributions.  Most of these distributions provide graphical
    4.50 -	package managers that will let you install Mercurial with a
    4.51 -	single click; the package name to look for is
    4.52 -	<literal>mercurial</literal>.</para>
    4.53 -
    4.54 -      <itemizedlist>
    4.55 -	<listitem><para id="x_4">Ubuntu and Debian:</para>
    4.56 -	  <programlisting>apt-get install mercurial</programlisting></listitem>
    4.57 -	<listitem><para id="x_5">Fedora:</para>
    4.58 -	  <programlisting>yum install mercurial</programlisting></listitem>
    4.59 -	<listitem><para id="x_715">OpenSUSE:</para>
    4.60 -	  <programlisting>zypper install mercurial</programlisting></listitem>
    4.61 -	<listitem><para id="x_6">Gentoo:</para>
    4.62 -	  <programlisting>emerge mercurial</programlisting></listitem>
    4.63 -      </itemizedlist>
    4.64 -
    4.65 -    </sect2>
    4.66 -    <sect2>
    4.67 -      <title>Solaris</title>
    4.68 -
    4.69 -      <para id="x_9">SunFreeWare, at <ulink
    4.70 -	  url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 
    4.71 -	provides prebuilt packages of Mercurial.</para>
    4.72 -
    4.73 -    </sect2>
    4.74 -
    4.75 -  </sect1>
    4.76 -
    4.77 -  <sect1>
    4.78 -    <title>Getting started</title>
    4.79 -
    4.80 -    <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg
    4.81 -	version</command> command to find out whether Mercurial is
    4.82 -      installed properly.  The actual version information that it
    4.83 -      prints isn't so important; we simply care whether the command
    4.84 -      runs and prints anything at all.</para>
    4.85 -
    4.86 -    &interaction.tour.version;
    4.87 -
    4.88 -    <sect2>
    4.89 -      <title>Built-in help</title>
    4.90 -
    4.91 -      <para id="x_f">Mercurial provides a built-in help system.  This is
    4.92 -	  invaluable for those times when you find yourself stuck
    4.93 -	  trying to remember how to run a command.  If you are
    4.94 -	  completely stuck, simply run <command role="hg-cmd">hg
    4.95 -	    help</command>; it will print a brief list of commands,
    4.96 -	  along with a description of what each does.  If you ask for
    4.97 -	  help on a specific command (as below), it prints more
    4.98 -	  detailed information.</para>
    4.99 -
   4.100 -	&interaction.tour.help;
   4.101 -
   4.102 -	<para id="x_10">For a more impressive level of detail (which you won't
   4.103 -	  usually need) run <command role="hg-cmd">hg help <option
   4.104 -	      role="hg-opt-global">-v</option></command>.  The <option
   4.105 -	    role="hg-opt-global">-v</option> option is short for
   4.106 -	  <option role="hg-opt-global">--verbose</option>, and tells
   4.107 -	  Mercurial to print more information than it usually
   4.108 -	  would.</para>
   4.109 -
   4.110 -    </sect2>
   4.111 -  </sect1>
   4.112 -  <sect1>
   4.113 -    <title>Working with a repository</title>
   4.114 -
   4.115 -    <para id="x_11">In Mercurial, everything happens inside a
   4.116 -      <emphasis>repository</emphasis>.  The repository for a project
   4.117 -      contains all of the files that <quote>belong to</quote> that
   4.118 -      project, along with a historical record of the project's
   4.119 -      files.</para>
   4.120 -
   4.121 -    <para id="x_12">There's nothing particularly magical about a repository; it
   4.122 -      is simply a directory tree in your filesystem that Mercurial
   4.123 -      treats as special. You can rename or delete a repository any
   4.124 -      time you like, using either the command line or your file
   4.125 -      browser.</para>
   4.126 -
   4.127 -    <sect2>
   4.128 -      <title>Making a local copy of a repository</title>
   4.129 -
   4.130 -      <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little
   4.131 -	bit special.  While you could use a normal file copying
   4.132 -	command to make a copy of a repository, it's best to use a
   4.133 -	built-in command that Mercurial provides.  This command is
   4.134 -	called <command role="hg-cmd">hg clone</command>, because it
   4.135 -	makes an identical copy of an existing repository.</para>
   4.136 -
   4.137 -      &interaction.tour.clone;
   4.138 -
   4.139 -      <para id="x_67c">One advantage of using <command role="hg-cmd">hg
   4.140 -	  clone</command> is that, as we can see above, it lets us clone
   4.141 -	repositories over the network.  Another is that it remembers
   4.142 -	where we cloned from, which we'll find useful soon when we
   4.143 -	want to fetch new changes from another repository.</para>
   4.144 -
   4.145 -      <para id="x_14">If our clone succeeded, we should now have a local
   4.146 -	directory called <filename class="directory">hello</filename>.
   4.147 -	This directory will contain some files.</para>
   4.148 -
   4.149 -      &interaction.tour.ls;
   4.150 -
   4.151 -      <para id="x_15">These files have the same contents and history in our
   4.152 -	repository as they do in the repository we cloned.</para>
   4.153 -
   4.154 -      <para id="x_16">Every Mercurial repository is complete,
   4.155 -	self-contained, and independent.  It contains its own private
   4.156 -	copy of a project's files and history.  As we just mentioned,
   4.157 -	a cloned repository remembers the location of the repository
   4.158 -	it was cloned from, but Mercurial will not communicate with
   4.159 -	that repository, or any other, unless you tell it to.</para>
   4.160 -
   4.161 -      <para id="x_17">What this means for now is that we're free to experiment
   4.162 -	with our repository, safe in the knowledge that it's a private
   4.163 -	<quote>sandbox</quote> that won't affect anyone else.</para>
   4.164 -
   4.165 -    </sect2>
   4.166 -    <sect2>
   4.167 -      <title>What's in a repository?</title>
   4.168 -
   4.169 -      <para id="x_18">When we take a more detailed look inside a repository, we
   4.170 -	can see that it contains a directory named <filename
   4.171 -	  class="directory">.hg</filename>.  This is where Mercurial
   4.172 -	keeps all of its metadata for the repository.</para>
   4.173 -
   4.174 -      &interaction.tour.ls-a;
   4.175 -
   4.176 -      <para id="x_19">The contents of the <filename
   4.177 -	  class="directory">.hg</filename> directory and its
   4.178 -	subdirectories are private to Mercurial.  Every other file and
   4.179 -	directory in the repository is yours to do with as you
   4.180 -	please.</para>
   4.181 -
   4.182 -      <para id="x_1a">To introduce a little terminology, the <filename
   4.183 -	  class="directory">.hg</filename> directory is the
   4.184 -	<quote>real</quote> repository, and all of the files and
   4.185 -	directories that coexist with it are said to live in the
   4.186 -	<emphasis>working directory</emphasis>.  An easy way to
   4.187 -	remember the distinction is that the
   4.188 -	<emphasis>repository</emphasis> contains the
   4.189 -	<emphasis>history</emphasis> of your project, while the
   4.190 -	<emphasis>working directory</emphasis> contains a
   4.191 -	<emphasis>snapshot</emphasis> of your project at a particular
   4.192 -	point in history.</para>
   4.193 -
   4.194 -    </sect2>
   4.195 -  </sect1>
   4.196 -  <sect1>
   4.197 -    <title>A tour through history</title>
   4.198 -
   4.199 -    <para id="x_1b">One of the first things we might want to do with a new,
   4.200 -      unfamiliar repository is understand its history.  The <command
   4.201 -	role="hg-cmd">hg log</command> command gives us a view of
   4.202 -      the history of changes in the repository.</para>
   4.203 -
   4.204 -    &interaction.tour.log;
   4.205 -
   4.206 -    <para id="x_1c">By default, this command prints a brief paragraph of output
   4.207 -      for each change to the project that was recorded.  In Mercurial
   4.208 -      terminology, we call each of these recorded events a
   4.209 -      <emphasis>changeset</emphasis>, because it can contain a record
   4.210 -      of changes to several files.</para>
   4.211 -
   4.212 -    <para id="x_1d">The fields in a record of output from <command
   4.213 -	role="hg-cmd">hg log</command> are as follows.</para>
   4.214 -
   4.215 -    <itemizedlist>
   4.216 -      <listitem><para id="x_1e"><literal>changeset</literal>: This
   4.217 -	  field has the format of a number, followed by a colon,
   4.218 -	  followed by a hexadecimal (or <emphasis>hex</emphasis>)
   4.219 -	  string.  These are <emphasis>identifiers</emphasis> for the
   4.220 -	  changeset.  The hex string is a unique identifier: the same
   4.221 -	  hex string will always refer to the same changeset in every
   4.222 -	  copy of this repository. The
   4.223 -	  number is shorter and easier to type than the hex string,
   4.224 -	  but it isn't unique: the same number in two different clones
   4.225 -	  of a repository may identify different changesets.</para>
   4.226 -      </listitem>
   4.227 -      <listitem><para id="x_1f"><literal>user</literal>: The identity of the
   4.228 -	  person who created the changeset.  This is a free-form
   4.229 -	  field, but it most often contains a person's name and email
   4.230 -	  address.</para></listitem>
   4.231 -      <listitem><para id="x_20"><literal>date</literal>: The date and time on
   4.232 -	  which the changeset was created, and the timezone in which
   4.233 -	  it was created.  (The date and time are local to that
   4.234 -	  timezone; they display what time and date it was for the
   4.235 -	  person who created the changeset.)</para></listitem>
   4.236 -      <listitem><para id="x_21"><literal>summary</literal>: The first line of
   4.237 -	  the text message that the creator of the changeset entered
   4.238 -	  to describe the changeset.</para></listitem>
   4.239 -      <listitem>
   4.240 -	<para id="x_67d">Some changesets, such as the first in the list above,
   4.241 -	  have a <literal>tag</literal> field.  A tag is another way
   4.242 -	  to identify a changeset, by giving it an easy-to-remember
   4.243 -	  name. (The tag named <literal>tip</literal> is special: it
   4.244 -	  always refers to the newest change in a repository.)</para>
   4.245 -      </listitem>
   4.246 -    </itemizedlist>
   4.247 -
   4.248 -    <para id="x_22">The default output printed by <command
   4.249 -	role="hg-cmd">hg log</command> is purely a summary; it is
   4.250 -      missing a lot of detail.</para>
   4.251 -
   4.252 -    <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides
   4.253 -      a 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 -    <figure id="fig:tour-basic:history">
   4.261 -      <title>Graphical history of the <filename
   4.262 -	  class="directory">hello</filename> repository</title>
   4.263 -      <mediaobject>
   4.264 -	<imageobject><imagedata fileref="figs/tour-history.png"/></imageobject>
   4.265 -	<textobject><phrase>XXX add text</phrase></textobject>
   4.266 -      </mediaobject>
   4.267 -    </figure>
   4.268 -
   4.269 -    <sect2>
   4.270 -      <title>Changesets, revisions, and talking to other
   4.271 -	people</title>
   4.272 -
   4.273 -      <para id="x_25">As English is a notoriously sloppy language, and computer
   4.274 -	science has a hallowed history of terminological confusion
   4.275 -	(why use one term when four will do?), revision control has a
   4.276 -	variety of words and phrases that mean the same thing.  If you
   4.277 -	are talking about Mercurial history with other people, you
   4.278 -	will find that the word <quote>changeset</quote> is often
   4.279 -	compressed to <quote>change</quote> or (when written)
   4.280 -	<quote>cset</quote>, and sometimes a changeset is referred to
   4.281 -	as a <quote>revision</quote> or a <quote>rev</quote>.</para>
   4.282 -
   4.283 -      <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you
   4.284 -	use to refer to the concept of <quote>a changeset</quote>, the
   4.285 -	<emphasis>identifier</emphasis> that you use to refer to
   4.286 -	<quote>a <emphasis>specific</emphasis> changeset</quote> is of
   4.287 -	great importance. Recall that the <literal>changeset</literal>
   4.288 -	field in the output from <command role="hg-cmd">hg
   4.289 -	  log</command> identifies a changeset using both a number and
   4.290 -	a hexadecimal string.</para>
   4.291 -      <itemizedlist>
   4.292 -	<listitem><para id="x_27">The revision number is a handy
   4.293 -	    notation that is <emphasis>only valid in that
   4.294 -	      repository</emphasis>.</para></listitem>
   4.295 -	<listitem><para id="x_28">The hexadecimal 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 -
   4.301 -      <para id="x_29">This distinction is important.  If you send
   4.302 -	someone an email talking about <quote>revision 33</quote>,
   4.303 -	there's a high likelihood that their revision 33 will
   4.304 -	<emphasis>not be the same</emphasis> as yours.  The reason for
   4.305 -	this is that a revision number depends on the order in which
   4.306 -	changes arrived in a repository, and there is no guarantee
   4.307 -	that the same changes will happen in the same order in
   4.308 -	different repositories. Three changes <literal>a,b,c</literal>
   4.309 -	can easily appear in one repository as
   4.310 -	<literal>0,1,2</literal>, while in another as
   4.311 -	<literal>0,2,1</literal>.</para>
   4.312 -
   4.313 -      <para id="x_2a">Mercurial uses revision numbers purely as a convenient
   4.314 -	shorthand.  If you need to discuss a changeset with someone,
   4.315 -	or make a record of a changeset for some other reason (for
   4.316 -	example, in a bug report), use the hexadecimal
   4.317 -	identifier.</para>
   4.318 -
   4.319 -    </sect2>
   4.320 -    <sect2>
   4.321 -      <title>Viewing specific revisions</title>
   4.322 -
   4.323 -      <para id="x_2b">To narrow the output of <command role="hg-cmd">hg
   4.324 -	  log</command> down to a single revision, use the <option
   4.325 -	  role="hg-opt-log">-r</option> (or <option
   4.326 -	  role="hg-opt-log">--rev</option>) option.  You can use
   4.327 -	either a revision number or a hexadecimal identifier,
   4.328 -	and you can provide as many revisions as you want.</para>
   4.329 -
   4.330 -      &interaction.tour.log-r;
   4.331 -
   4.332 -      <para id="x_2c">If you want to see the history of several revisions
   4.333 -	without having to list each one, you can use <emphasis>range
   4.334 -	  notation</emphasis>; this lets you express the idea <quote>I
   4.335 -	  want all revisions between <literal>abc</literal> and
   4.336 -	  <literal>def</literal>, inclusive</quote>.</para>
   4.337 -      
   4.338 -	&interaction.tour.log.range;
   4.339 -
   4.340 -      <para id="x_2d">Mercurial also honours the order in which you specify
   4.341 -	revisions, so <command role="hg-cmd">hg log -r 2:4</command>
   4.342 -	prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
   4.343 -	  4:2</command> prints 4, 3, and 2.</para>
   4.344 -
   4.345 -    </sect2>
   4.346 -    <sect2>
   4.347 -      <title>More detailed information</title>
   4.348 -
   4.349 -      <para id="x_2e">While the summary information printed by <command
   4.350 -	  role="hg-cmd">hg log</command> is useful if you already know
   4.351 -	what you're looking for, you may need to see a complete
   4.352 -	description of the change, or a list of the files changed, if
   4.353 -	you're trying to decide whether a changeset is the one you're
   4.354 -	looking for. The <command role="hg-cmd">hg log</command>
   4.355 -	command's <option role="hg-opt-global">-v</option> (or <option
   4.356 -	  role="hg-opt-global">--verbose</option>) option gives you
   4.357 -	this extra detail.</para>
   4.358 -
   4.359 -      &interaction.tour.log-v;
   4.360 -
   4.361 -      <para id="x_2f">If you want to see both the description and
   4.362 -	content of a change, add the <option
   4.363 -	  role="hg-opt-log">-p</option> (or <option
   4.364 -	  role="hg-opt-log">--patch</option>) option.  This displays
   4.365 -	the content of a change as a <emphasis>unified diff</emphasis>
   4.366 -	(if you've never seen a unified diff before, see <xref
   4.367 -	  linkend="sec:mq:patch"/> for an overview).</para>
   4.368 -
   4.369 -      &interaction.tour.log-vp;
   4.370 -
   4.371 -      <para id="x_67e">The <option role="hg-opt-log">-p</option> option is
   4.372 -	tremendously useful, so it's well worth remembering.</para>
   4.373 -
   4.374 -    </sect2>
   4.375 -  </sect1>
   4.376 -
   4.377 -  <sect1>
   4.378 -    <title>All about command options</title>
   4.379 -
   4.380 -    <para id="x_30">Let's take a brief break from exploring Mercurial commands
   4.381 -      to discuss a pattern in the way that they work; you may find
   4.382 -      this useful to keep in mind as we continue our tour.</para>
   4.383 -
   4.384 -    <para id="x_31">Mercurial has a consistent and straightforward approach to
   4.385 -      dealing with the options that you can pass to commands.  It
   4.386 -      follows the conventions for options that are common to modern
   4.387 -      Linux and Unix systems.</para>
   4.388 -
   4.389 -    <itemizedlist>
   4.390 -      <listitem>
   4.391 -	<para id="x_32">Every option has a long name.  For example, as
   4.392 -	  we've already seen, the <command role="hg-cmd">hg
   4.393 -	    log</command> command accepts a <option
   4.394 -	    role="hg-opt-log">--rev</option> option.</para>
   4.395 -      </listitem>
   4.396 -      <listitem>
   4.397 -	<para id="x_33">Most options have short names, too.  Instead
   4.398 -	  of <option role="hg-opt-log">--rev</option>, we can use
   4.399 -	  <option role="hg-opt-log">-r</option>.  (The reason that
   4.400 -	  some options don't have short names is that the options in
   4.401 -	  question are rarely used.)</para>
   4.402 -      </listitem>
   4.403 -      <listitem>
   4.404 -	<para id="x_34">Long options start with two dashes (e.g.
   4.405 -	  <option role="hg-opt-log">--rev</option>), while short
   4.406 -	  options start with one (e.g. <option
   4.407 -	    role="hg-opt-log">-r</option>).</para>
   4.408 -      </listitem>
   4.409 -      <listitem>
   4.410 -	<para id="x_35">Option naming and usage is consistent across
   4.411 -	  commands.  For example, every command that lets you specify
   4.412 -	  a changeset ID or revision number accepts both <option
   4.413 -	    role="hg-opt-log">-r</option> and <option
   4.414 -	    role="hg-opt-log">--rev</option> arguments.</para>
   4.415 -      </listitem>
   4.416 -      <listitem>
   4.417 -	<para id="x_67f">If you are using short options, you can save typing by
   4.418 -	  running them together. For example, the command <command
   4.419 -	    role="hg-cmd">hg log -v -p -r 2</command> can be written
   4.420 -	  as <command role="hg-cmd">hg log -vpr2</command>.</para>
   4.421 -      </listitem>
   4.422 -    </itemizedlist>
   4.423 -
   4.424 -    <para id="x_36">In the examples throughout this book, I usually
   4.425 -      use short options instead of long.  This simply reflects my own
   4.426 -      preference, so don't read anything significant into it.</para>
   4.427 -
   4.428 -    <para id="x_37">Most commands that print output of some kind will print more
   4.429 -      output when passed a <option role="hg-opt-global">-v</option>
   4.430 -      (or <option role="hg-opt-global">--verbose</option>) option, and
   4.431 -      less when passed <option role="hg-opt-global">-q</option> (or
   4.432 -      <option role="hg-opt-global">--quiet</option>).</para>
   4.433 -
   4.434 -    <note>
   4.435 -      <title>Option naming consistency</title>
   4.436 -
   4.437 -      <para id="x_680">Almost always, Mercurial commands use consistent option
   4.438 -	names to refer to the same concepts.  For instance, if a
   4.439 -	command deals with changesets, you'll always identify them
   4.440 -	with <option role="hg-opt-log">--rev</option> or <option
   4.441 -	  role="hg-opt-log">-r</option>.  This consistent use of
   4.442 -	option names makes it easier to remember what options a
   4.443 -	particular command takes.</para>
   4.444 -    </note>
   4.445 -
   4.446 -  </sect1>
   4.447 -  <sect1>
   4.448 -    <title>Making and reviewing changes</title>
   4.449 -
   4.450 -    <para id="x_38">Now that we have a grasp of viewing history in Mercurial,
   4.451 -      let's take a look at making some changes and examining
   4.452 -      them.</para>
   4.453 -
   4.454 -    <para id="x_39">The first thing we'll do is isolate our experiment in a
   4.455 -      repository of its own.  We use the <command role="hg-cmd">hg
   4.456 -	clone</command> command, but we don't need to clone a copy of
   4.457 -      the remote repository.  Since we already have a copy of it
   4.458 -      locally, we can just clone that instead.  This is much faster
   4.459 -      than cloning over the network, and cloning a local repository
   4.460 -      uses less disk space in most cases, too<footnote>
   4.461 -	<para id="x_681">The saving of space arises when source and destination
   4.462 -	  repositories are on the same filesystem, in which case
   4.463 -	  Mercurial will use hardlinks to do copy-on-write sharing of
   4.464 -	  its internal metadata.  If that explanation meant nothing to
   4.465 -	  you, don't worry: everything happens transparently and
   4.466 -	  automatically, and you don't need to understand it.</para>
   4.467 -	</footnote>.</para>
   4.468 -
   4.469 -    &interaction.tour.reclone;
   4.470 -
   4.471 -    <para id="x_3a">As an aside, it's often good practice to keep a
   4.472 -      <quote>pristine</quote> copy of a remote repository around,
   4.473 -      which you can then make temporary clones of to create sandboxes
   4.474 -      for each task you want to work on.  This lets you work on
   4.475 -      multiple tasks in parallel, each isolated from the others until
   4.476 -      it's complete and you're ready to integrate it back.  Because
   4.477 -      local clones are so cheap, there's almost no overhead to cloning
   4.478 -      and destroying repositories whenever you want.</para>
   4.479 -
   4.480 -    <para id="x_3b">In our <filename class="directory">my-hello</filename>
   4.481 -      repository, we have a file <filename>hello.c</filename> that
   4.482 -      contains the classic <quote>hello, world</quote> program.</para>
   4.483 -
   4.484 -    &interaction.tour.cat1;
   4.485 -
   4.486 -    <para id="x_682">Let's edit this file so that it prints a second line of
   4.487 -      output.</para>
   4.488 -
   4.489 -    &interaction.tour.cat2;
   4.490 -
   4.491 -    <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command>
   4.492 -      command will tell us what Mercurial knows about the files in the
   4.493 -      repository.</para>
   4.494 -
   4.495 -    &interaction.tour.status;
   4.496 -
   4.497 -    <para id="x_3d">The <command role="hg-cmd">hg status</command> command
   4.498 -      prints no output for some files, but a line starting with
   4.499 -      <quote><literal>M</literal></quote> for
   4.500 -      <filename>hello.c</filename>.  Unless you tell it to, <command
   4.501 -	role="hg-cmd">hg status</command> will not print any output
   4.502 -      for files that have not been modified.</para>
   4.503 -
   4.504 -    <para id="x_3e">The <quote><literal>M</literal></quote> indicates that
   4.505 -      Mercurial has noticed that we modified
   4.506 -      <filename>hello.c</filename>.  We didn't need to
   4.507 -      <emphasis>inform</emphasis> Mercurial that we were going to
   4.508 -      modify the file before we started, or that we had modified the
   4.509 -      file after we were done; it was able to figure this out
   4.510 -      itself.</para>
   4.511 -
   4.512 -    <para id="x_3f">It's somewhat helpful to know that we've modified
   4.513 -      <filename>hello.c</filename>, but we might prefer to know
   4.514 -      exactly <emphasis>what</emphasis> changes we've made to it.  To
   4.515 -      do this, we use the <command role="hg-cmd">hg diff</command>
   4.516 -      command.</para>
   4.517 -
   4.518 -    &interaction.tour.diff;
   4.519 -
   4.520 -    <tip>
   4.521 -      <title>Understanding patches</title>
   4.522 -
   4.523 -      <para id="x_683">Remember to take a look at <xref
   4.524 -	  linkend="sec:mq:patch"/> if you don't know how to read
   4.525 -	output above.</para>
   4.526 -    </tip>
   4.527 -  </sect1>
   4.528 -  <sect1>
   4.529 -    <title>Recording changes in a new changeset</title>
   4.530 -
   4.531 -    <para id="x_40">We can modify files, build and test our changes, and use
   4.532 -      <command role="hg-cmd">hg status</command> and <command
   4.533 -	role="hg-cmd">hg diff</command> to review our changes, until
   4.534 -      we're satisfied with what we've done and arrive at a natural
   4.535 -      stopping point where we want to record our work in a new
   4.536 -      changeset.</para>
   4.537 -
   4.538 -    <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets
   4.539 -      us create a new changeset; we'll usually refer to this as
   4.540 -      <quote>making a commit</quote> or
   4.541 -      <quote>committing</quote>.</para>
   4.542 -
   4.543 -    <sect2>
   4.544 -      <title>Setting up a username</title>
   4.545 -
   4.546 -      <para id="x_42">When you try to run <command role="hg-cmd">hg
   4.547 -	  commit</command> for the first time, it is not guaranteed to
   4.548 -	succeed.  Mercurial records your name and address with each
   4.549 -	change that you commit, so that you and others will later be
   4.550 -	able to tell who made each change.  Mercurial tries to
   4.551 -	automatically figure out a sensible username to commit the
   4.552 -	change with.  It will attempt each of the following methods,
   4.553 -	in order:</para>
   4.554 -      <orderedlist>
   4.555 -	<listitem><para id="x_43">If you specify a <option
   4.556 -	      role="hg-opt-commit">-u</option> option to the <command
   4.557 -	      role="hg-cmd">hg commit</command> command on the command
   4.558 -	    line, followed by a username, this is always given the
   4.559 -	    highest precedence.</para></listitem>
   4.560 -	<listitem><para id="x_44">If you have set the <envar>HGUSER</envar>
   4.561 -	    environment variable, this is checked
   4.562 -	    next.</para></listitem>
   4.563 -	<listitem><para id="x_45">If you create a file in your home
   4.564 -	    directory called <filename
   4.565 -	      role="special">.hgrc</filename>, with a <envar
   4.566 -	      role="rc-item-ui">username</envar> entry, that will be
   4.567 -	    used next.  To see what the contents of this file should
   4.568 -	    look like, refer to <xref
   4.569 -	      linkend="sec:tour-basic:username"/>
   4.570 -	    below.</para></listitem>
   4.571 -	<listitem><para id="x_46">If you have set the <envar>EMAIL</envar>
   4.572 -	    environment variable, this will be used
   4.573 -	    next.</para></listitem>
   4.574 -	<listitem><para id="x_47">Mercurial will query your system to find out
   4.575 -	    your local user name and host name, and construct a
   4.576 -	    username from these components. Since this often results
   4.577 -	    in a username that is not very useful, it will print a
   4.578 -	    warning if it has to do
   4.579 -	    this.</para></listitem>
   4.580 -      </orderedlist>
   4.581 -      <para id="x_48">If all of these mechanisms fail, Mercurial will
   4.582 -	  fail, printing an error message.  In this case, it will not
   4.583 -	  let you commit until you set up a
   4.584 -	  username.</para>
   4.585 -      <para id="x_49">You should think of the <envar>HGUSER</envar> environment
   4.586 -	variable and the <option role="hg-opt-commit">-u</option>
   4.587 -	option to the <command role="hg-cmd">hg commit</command>
   4.588 -	command as ways to <emphasis>override</emphasis> Mercurial's
   4.589 -	default selection of username.  For normal use, the simplest
   4.590 -	and most robust way to set a username for yourself is by
   4.591 -	creating a <filename role="special">.hgrc</filename> file; see
   4.592 -	below for details.</para>
   4.593 -      <sect3 id="sec:tour-basic:username">
   4.594 -	<title>Creating a Mercurial configuration file</title>
   4.595 -
   4.596 -	<para id="x_4a">To set a user name, use your favorite editor
   4.597 -	  to create a file called <filename
   4.598 -	    role="special">.hgrc</filename> in your home directory.
   4.599 -	  Mercurial will use this file to look up your personalised
   4.600 -	  configuration settings.  The initial contents of your
   4.601 -	  <filename role="special">.hgrc</filename> should look like
   4.602 -	  this.</para>
   4.603 -
   4.604 -	<tip>
   4.605 -	  <title><quote>Home directory</quote> on Windows</title>
   4.606 -
   4.607 -	  <para id="x_716">When we refer to your home directory, on an English
   4.608 -	    language installation of Windows this will usually be a
   4.609 -	    folder named after your user name in
   4.610 -	    <filename>C:\Documents and Settings</filename>.  You can
   4.611 -	    find out the exact name of your home directory by opening
   4.612 -	    a command prompt window and running the following
   4.613 -	    command.</para>
   4.614 -
   4.615 -	  <screen><prompt>C:\></prompt> <userinput>echo %UserProfile%</userinput></screen>
   4.616 -	</tip>
   4.617 -
   4.618 -	<programlisting># This is a Mercurial configuration file.
   4.619 -[ui]
   4.620 -username = Firstname Lastname &lt;email.address@example.net&gt;</programlisting>
   4.621 -
   4.622 -	<para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a
   4.623 -	  <emphasis>section</emphasis> of the config file, so you can
   4.624 -	  read the <quote><literal>username = ...</literal></quote>
   4.625 -	  line as meaning <quote>set the value of the
   4.626 -	    <literal>username</literal> item in the
   4.627 -	    <literal>ui</literal> section</quote>. A section continues
   4.628 -	  until a new section begins, or the end of the file.
   4.629 -	  Mercurial ignores empty lines and treats any text from
   4.630 -	  <quote><literal>#</literal></quote> to the end of a line as
   4.631 -	  a comment.</para>
   4.632 -      </sect3>
   4.633 -
   4.634 -      <sect3>
   4.635 -	<title>Choosing a user name</title>
   4.636 -
   4.637 -	<para id="x_4c">You can use any text you like as the value of
   4.638 -	  the <literal>username</literal> config item, since this
   4.639 -	  information is for reading by other people, but will not be
   4.640 -	  interpreted by Mercurial.  The convention that most people
   4.641 -	  follow is to use their name and email address, as in the
   4.642 -	  example above.</para>
   4.643 -	<note>
   4.644 -	  <para id="x_4d">Mercurial's built-in web server obfuscates
   4.645 -	    email addresses, to make it more difficult for the email
   4.646 -	    harvesting tools that spammers use. This reduces the
   4.647 -	    likelihood that you'll start receiving more junk email if
   4.648 -	    you publish a Mercurial repository on the
   4.649 -	    web.</para></note>
   4.650 -      </sect3>
   4.651 -    </sect2>
   4.652 -    <sect2>
   4.653 -      <title>Writing a commit message</title>
   4.654 -
   4.655 -      <para id="x_4e">When we commit a change, Mercurial drops us into
   4.656 -	a text editor, to enter a message that will describe the
   4.657 -	modifications we've made in this changeset.  This is called
   4.658 -	the <emphasis>commit message</emphasis>.  It will be a record
   4.659 -	for readers of what we did and why, and it will be printed by
   4.660 -	<command role="hg-cmd">hg log</command> after we've finished
   4.661 -	committing.</para>
   4.662 -
   4.663 -       &interaction.tour.commit;
   4.664 -
   4.665 -      <para id="x_4f">The editor that the <command role="hg-cmd">hg
   4.666 -	  commit</command> command drops us into will contain an empty
   4.667 -	line or two, followed by a number of lines starting with
   4.668 -	<quote><literal>HG:</literal></quote>.</para>
   4.669 -
   4.670 -    <programlisting>
   4.671 -This is where I type my commit comment.
   4.672 -
   4.673 -HG: Enter commit message.  Lines beginning with 'HG:' are removed.
   4.674 -HG: --
   4.675 -HG: user: Bryan O'Sullivan &lt;bos@serpentine.com&gt;
   4.676 -HG: branch 'default'
   4.677 -HG: changed hello.c</programlisting>
   4.678 -
   4.679 -      <para id="x_50">Mercurial ignores the lines that start with
   4.680 -	<quote><literal>HG:</literal></quote>; it uses them only to
   4.681 -	tell us which files it's recording changes to.  Modifying or
   4.682 -	deleting these lines has no effect.</para>
   4.683 -    </sect2>
   4.684 -    <sect2>
   4.685 -      <title>Writing a good commit message</title>
   4.686 -
   4.687 -      <para id="x_51">Since <command role="hg-cmd">hg log</command>
   4.688 -	only prints the first line of a commit message by default,
   4.689 -	it's best to write a commit message whose first line stands
   4.690 -	alone.  Here's a real example of a commit message that
   4.691 -	<emphasis>doesn't</emphasis> follow this guideline, and hence
   4.692 -	has a summary that is not readable.</para>
   4.693 -
   4.694 -      <programlisting>
   4.695 -changeset:   73:584af0e231be
   4.696 -user:        Censored Person &lt;censored.person@example.org&gt;
   4.697 -date:        Tue Sep 26 21:37:07 2006 -0700
   4.698 -summary:     include buildmeister/commondefs. Add exports.</programlisting>
   4.699 -
   4.700 -      <para id="x_52">As far as the remainder of the contents of the
   4.701 -	commit message are concerned, there are no hard-and-fast
   4.702 -	rules.  Mercurial itself doesn't interpret or care about the
   4.703 -	contents of the commit message, though your project may have
   4.704 -	policies that dictate a certain kind of formatting.</para>
   4.705 -      <para id="x_53">My personal preference is for short, but
   4.706 -	informative, commit messages that tell me something that I
   4.707 -	can't figure out with a quick glance at the output of <command
   4.708 -	  role="hg-cmd">hg log --patch</command>.</para>
   4.709 -      <para id="x_55">If we run the <command role="hg-cmd">hg
   4.710 -	  commit</command> command without any arguments, it records
   4.711 -	all of the changes we've made, as reported by <command
   4.712 -	  role="hg-cmd">hg status</command> and <command
   4.713 -	  role="hg-cmd">hg diff</command>.</para>
   4.714 -
   4.715 -      <note>
   4.716 -	<title>A surprise for Subversion users</title>
   4.717 -
   4.718 -	<para id="x_717">Like other Mercurial commands, if we don't supply
   4.719 -	  explicit names to commit to the <command role="hg-cmd">hg
   4.720 -	    commit</command>, it will operate across a repository's
   4.721 -	  entire working directory.  Be wary of this if you're coming
   4.722 -	  from the Subversion or CVS world, since you might expect it
   4.723 -	  to operate only on the current directory that you happen to
   4.724 -	  be visiting and its subdirectories.</para>
   4.725 -      </note>
   4.726 -    </sect2>
   4.727 -
   4.728 -    <sect2>
   4.729 -      <title>Aborting a commit</title>
   4.730 -
   4.731 -      <para id="x_54">If you decide that you don't want to commit
   4.732 -	while in the middle of editing a commit message, simply exit
   4.733 -	from your editor without saving the file that it's editing.
   4.734 -	This will cause nothing to happen to either the repository or
   4.735 -	the working directory.</para>
   4.736 -    </sect2>
   4.737 -
   4.738 -    <sect2>
   4.739 -      <title>Admiring our new handiwork</title>
   4.740 -
   4.741 -      <para id="x_56">Once we've finished the commit, we can use the
   4.742 -	<command role="hg-cmd">hg tip</command> command to display the
   4.743 -	changeset we just created.  This command produces output that
   4.744 -	is identical to <command role="hg-cmd">hg log</command>, but
   4.745 -	it only displays the newest revision in the repository.</para>
   4.746 -
   4.747 -      &interaction.tour.tip;
   4.748 -
   4.749 -      <para id="x_57">We refer to the newest revision in the
   4.750 -	repository as the <emphasis>tip revision</emphasis>, or simply
   4.751 -	the <emphasis>tip</emphasis>.</para>
   4.752 -
   4.753 -      <para id="x_684">By the way, the <command role="hg-cmd">hg tip</command>
   4.754 -	command accepts many of the same options as <command
   4.755 -	  role="hg-cmd">hg log</command>, so <option
   4.756 -	  role="hg-opt-global">-v</option> above indicates <quote>be
   4.757 -	  verbose</quote>, <option role="hg-opt-tip">-p</option>
   4.758 -	specifies <quote>print a patch</quote>.  The use of <option
   4.759 -	  role="hg-opt-tip">-p</option> to print patches is another
   4.760 -	example of the consistent naming we mentioned earlier.</para>
   4.761 -    </sect2>
   4.762 -  </sect1>
   4.763 -
   4.764 -  <sect1>
   4.765 -    <title>Sharing changes</title>
   4.766 -
   4.767 -    <para id="x_58">We mentioned earlier that repositories in
   4.768 -      Mercurial are self-contained.  This means that the changeset we
   4.769 -      just created exists only in our <filename
   4.770 -	class="directory">my-hello</filename> repository.  Let's look
   4.771 -      at a few ways that we can propagate this change into other
   4.772 -      repositories.</para>
   4.773 -
   4.774 -    <sect2 id="sec:tour:pull">
   4.775 -      <title>Pulling changes from another repository</title>
   4.776 -
   4.777 -      <para id="x_59">To get started, let's clone our original
   4.778 -	<filename class="directory">hello</filename> repository, which
   4.779 -	does not contain the change we just committed.  We'll call our
   4.780 -	temporary repository <filename
   4.781 -	  class="directory">hello-pull</filename>.</para>
   4.782 -
   4.783 -      &interaction.tour.clone-pull;
   4.784 -
   4.785 -      <para id="x_5a">We'll use the <command role="hg-cmd">hg
   4.786 -	  pull</command> command to bring changes from <filename
   4.787 -	  class="directory">my-hello</filename> into <filename
   4.788 -	  class="directory">hello-pull</filename>.  However, blindly
   4.789 -	pulling unknown changes into a repository is a somewhat scary
   4.790 -	prospect.  Mercurial provides the <command role="hg-cmd">hg
   4.791 -	  incoming</command> command to tell us what changes the
   4.792 -	<command role="hg-cmd">hg pull</command> command
   4.793 -	<emphasis>would</emphasis> pull into the repository, without
   4.794 -	actually pulling the changes in.</para>
   4.795 -
   4.796 -      &interaction.tour.incoming;
   4.797 -
   4.798 -      <para id="x_5c">Bringing changes into a repository is a simple
   4.799 -	matter of running the <command role="hg-cmd">hg pull</command>
   4.800 -	command, and optionally telling it which repository to pull from.</para>
   4.801 -
   4.802 -      &interaction.tour.pull;
   4.803 -
   4.804 -      <para id="x_5d">As you can see from the before-and-after output
   4.805 -	of <command role="hg-cmd">hg tip</command>, we have
   4.806 -	successfully pulled changes into our repository.  However,
   4.807 -	Mercurial separates pulling changes in from updating the
   4.808 -	working directory. There remains one step before we will see
   4.809 -	the changes that we just pulled appear in the working
   4.810 -	directory.</para>
   4.811 -
   4.812 -      <tip>
   4.813 -	<title>Pulling specific changes</title>
   4.814 -
   4.815 -	<para id="x_5b">It is possible that due to the delay between
   4.816 -	  running <command role="hg-cmd">hg incoming</command> and
   4.817 -	  <command role="hg-cmd">hg pull</command>, you may not see
   4.818 -	  all changesets that will be brought from the other
   4.819 -	  repository. Suppose you're pulling changes from a repository
   4.820 -	  on the network somewhere. While you are looking at the
   4.821 -	  <command role="hg-cmd">hg incoming</command> output, and
   4.822 -	  before you pull those changes, someone might have committed
   4.823 -	  something in the remote repository. This means that it's
   4.824 -	  possible to pull more changes than you saw when using
   4.825 -	  <command role="hg-cmd">hg incoming</command>.</para>
   4.826 -
   4.827 -	<para id="x_718">If you only want to pull precisely the changes that were
   4.828 -	  listed by <command role="hg-cmd">hg incoming</command>, or
   4.829 -	  you have some other reason to pull a subset of changes,
   4.830 -	  simply identify the change that you want to pull by its
   4.831 -	  changeset ID, e.g. <command>hg pull
   4.832 -	    -r7e95bb</command>.</para>
   4.833 -      </tip>
   4.834 -    </sect2>
   4.835 -
   4.836 -    <sect2>
   4.837 -      <title>Updating the working directory</title>
   4.838 -
   4.839 -      <para id="x_5e">We have so far glossed over the relationship
   4.840 -	between a repository and its working directory.  The <command
   4.841 -	  role="hg-cmd">hg pull</command> command that we ran in
   4.842 -	<xref linkend="sec:tour:pull"/> brought changes into the
   4.843 -	repository, but if we check, there's no sign of those changes
   4.844 -	in the working directory.  This is because <command
   4.845 -	  role="hg-cmd">hg pull</command> does not (by default) touch
   4.846 -	the working directory.  Instead, we use the <command
   4.847 -	  role="hg-cmd">hg update</command> command to do this.</para>
   4.848 -
   4.849 -      &interaction.tour.update;
   4.850 -
   4.851 -      <para id="x_5f">It might seem a bit strange that <command
   4.852 -	  role="hg-cmd">hg pull</command> doesn't update the working
   4.853 -	directory automatically.  There's actually a good reason for
   4.854 -	this: you can use <command role="hg-cmd">hg update</command>
   4.855 -	to update the working directory to the state it was in at
   4.856 -	<emphasis>any revision</emphasis> in the history of the
   4.857 -	repository.  If you had the working directory updated to an
   4.858 -	old revision&emdash;to hunt down the origin of a bug,
   4.859 -	say&emdash;and ran a <command role="hg-cmd">hg pull</command>
   4.860 -	which automatically updated the working directory to a new
   4.861 -	revision, you might not be terribly happy.</para>
   4.862 -
   4.863 -      <para id="x_60">Since pull-then-update is such a common sequence
   4.864 -	of operations, Mercurial lets you combine the two by passing
   4.865 -	the <option role="hg-opt-pull">-u</option> option to <command
   4.866 -	  role="hg-cmd">hg pull</command>.</para>
   4.867 -
   4.868 -      <para id="x_61">If you look back at the output of <command
   4.869 -	  role="hg-cmd">hg pull</command> in <xref
   4.870 -	    linkend="sec:tour:pull"/> when we ran it without <option
   4.871 -	  role="hg-opt-pull">-u</option>, you can see that it printed
   4.872 -	a helpful reminder that we'd have to take an explicit step to
   4.873 -	update the working directory.</para>
   4.874 -
   4.875 -      <para id="x_62">To find out what revision the working directory
   4.876 -	is at, use the <command role="hg-cmd">hg parents</command>
   4.877 -	command.</para>
   4.878 -
   4.879 -      &interaction.tour.parents;
   4.880 -
   4.881 -      <para id="x_63">If you look back at <xref
   4.882 -	  linkend="fig:tour-basic:history"/>, you'll see arrows
   4.883 -	connecting each changeset.  The node that the arrow leads
   4.884 -	<emphasis>from</emphasis> in each case is a parent, and the
   4.885 -	node that the arrow leads <emphasis>to</emphasis> is its
   4.886 -	child.  The working directory has a parent in just the same
   4.887 -	way; this is the changeset that the working directory
   4.888 -	currently contains.</para>
   4.889 -
   4.890 -      <para id="x_64">To update the working directory to a particular
   4.891 -	revision, give a revision number or changeset ID to the
   4.892 -	<command role="hg-cmd">hg update</command> command.</para>
   4.893 -
   4.894 -      &interaction.tour.older;
   4.895 -
   4.896 -      <para id="x_65">If you omit an explicit revision, <command
   4.897 -	  role="hg-cmd">hg update</command> will update to the tip
   4.898 -	revision, as shown by the second call to <command
   4.899 -	  role="hg-cmd">hg update</command> in the example
   4.900 -	above.</para>
   4.901 -    </sect2>
   4.902 -
   4.903 -    <sect2>
   4.904 -      <title>Pushing changes to another repository</title>
   4.905 -
   4.906 -      <para id="x_66">Mercurial lets us push changes to another
   4.907 -	repository, from the repository we're currently visiting. As
   4.908 -	with the example of <command role="hg-cmd">hg pull</command>
   4.909 -	above, we'll create a temporary repository to push our changes
   4.910 -	into.</para>
   4.911 -
   4.912 -      &interaction.tour.clone-push;
   4.913 -
   4.914 -      <para id="x_67">The <command role="hg-cmd">hg outgoing</command>
   4.915 -	command tells us what changes would be pushed into another
   4.916 -	repository.</para>
   4.917 -
   4.918 -      &interaction.tour.outgoing;
   4.919 -
   4.920 -      <para id="x_68">And the <command role="hg-cmd">hg push</command>
   4.921 -	command does the actual push.</para>
   4.922 -
   4.923 -      &interaction.tour.push;
   4.924 -
   4.925 -      <para id="x_69">As with <command role="hg-cmd">hg
   4.926 -	  pull</command>, the <command role="hg-cmd">hg push</command>
   4.927 -	command does not update the working directory in the
   4.928 -	repository that it's pushing changes into. Unlike <command
   4.929 -	  role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg
   4.930 -	  push</command> does not provide a <literal>-u</literal>
   4.931 -	option that updates the other repository's working directory.
   4.932 -	This asymmetry is deliberate: the repository we're pushing to
   4.933 -	might be on a remote server and shared between several people.
   4.934 -	If we were to update its working directory while someone was
   4.935 -	working in it, their work would be disrupted.</para>
   4.936 -
   4.937 -      <para id="x_6a">What happens if we try to pull or push changes
   4.938 -	  and the receiving repository already has those changes?
   4.939 -	  Nothing too exciting.</para>
   4.940 -
   4.941 -      &interaction.tour.push.nothing;
   4.942 -    </sect2>
   4.943 -
   4.944 -    <sect2>
   4.945 -      <title>Default locations</title>
   4.946 -
   4.947 -      <para id="x_719">When we clone a repository, Mercurial records the location
   4.948 -	of the repository we cloned in the
   4.949 -	<filename>.hg/hgrc</filename> file of the new repository.  If
   4.950 -	we don't supply a location to <command>hg pull</command> from
   4.951 -	or <command>hg push</command> to, those commands will use this
   4.952 -	location as a default.  The <command>hg incoming</command>
   4.953 -	and <command>hg outgoing</command> commands do so too.</para>
   4.954 -
   4.955 -      <para id="x_71a">If you open a repository's <filename>.hg/hgrc</filename>
   4.956 -	file in a text editor, you will see contents like the
   4.957 -	following.</para>
   4.958 -
   4.959 -      <programlisting>[paths]
   4.960 -default = http://www.selenic.com/repo/hg</programlisting>
   4.961 -
   4.962 -      <para id="x_71b">It is possible&emdash;and often useful&emdash;to have the
   4.963 -	default location for <command>hg push</command> and
   4.964 -	<command>hg outgoing</command> be different from those for
   4.965 -	<command>hg pull</command> and <command>hg incoming</command>.
   4.966 -	We can do this by adding a <literal>default-push</literal>
   4.967 -	entry to the <literal>[paths]</literal> section of the
   4.968 -	<filename>.hg/hgrc</filename> file, as follows.</para>
   4.969 -
   4.970 -      <programlisting>[paths]
   4.971 -default = http://www.selenic.com/repo/hg
   4.972 -default-push = http://hg.example.com/hg</programlisting>
   4.973 -    </sect2>
   4.974 -
   4.975 -    <sect2>
   4.976 -      <title>Sharing changes over a network</title>
   4.977 -
   4.978 -      <para id="x_6b">The commands we have covered in the previous few
   4.979 -	  sections are not limited to working with local repositories.
   4.980 -	  Each works in exactly the same fashion over a network
   4.981 -	  connection; simply pass in a URL instead of a local
   4.982 -	  path.</para>
   4.983 -	
   4.984 -      &interaction.tour.outgoing.net;
   4.985 -
   4.986 -      <para id="x_6c">In this example, we can see what changes we
   4.987 -	could push to the remote repository, but the repository is
   4.988 -	understandably not set up to let anonymous users push to
   4.989 -	it.</para>
   4.990 -
   4.991 -      &interaction.tour.push.net;
   4.992 -    </sect2>
   4.993 -  </sect1>
   4.994 -
   4.995 -  <sect1>
   4.996 -    <title>Starting a new project</title>
   4.997 -
   4.998 -    <para id="x_71c">It is just as easy to begin a new project as to work on one
   4.999 -      that already exists.  The <command>hg init</command> command
  4.1000 -      creates a new, empty Mercurial repository.</para>
  4.1001 -
  4.1002 -    &interaction.ch01-new.init;
  4.1003 -
  4.1004 -    <para id="x_71d">This simply creates a repository named
  4.1005 -      <filename>myproject</filename> in the current directory.</para>
  4.1006 -
  4.1007 -    &interaction.ch01-new.ls;
  4.1008 -
  4.1009 -    <para id="x_71e">We can tell that <filename>myproject</filename> is a
  4.1010 -      Mercurial repository, because it contains a
  4.1011 -      <filename>.hg</filename> directory.</para>
  4.1012 -
  4.1013 -    &interaction.ch01-new.ls2;
  4.1014 -
  4.1015 -    <para id="x_71f">If we want to add some pre-existing files to the repository,
  4.1016 -      we copy them into place, and tell Mercurial to start tracking
  4.1017 -      them using the <command>hg add</command> command.</para>
  4.1018 -
  4.1019 -    &interaction.ch01-new.add;
  4.1020 -
  4.1021 -    <para id="x_720">Once we are satisfied that our project looks right, we
  4.1022 -      commit our changes.</para>
  4.1023 -
  4.1024 -    &interaction.ch01-new.commit;
  4.1025 -
  4.1026 -    <para id="x_721">It takes just a few moments to start using Mercurial on a
  4.1027 -      new project, which is part of its appeal. Revision control is
  4.1028 -      now so easy to work with, we can use it on the smallest of
  4.1029 -      projects that we might not have considered with a more
  4.1030 -      complicated tool.</para>
  4.1031 -  </sect1>
  4.1032 -</chapter>
  4.1033 -
  4.1034 -<!--
  4.1035 -local variables: 
  4.1036 -sgml-parent-document: ("00book.xml" "book" "chapter")
  4.1037 -end:
  4.1038 --->

     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/en/ch02-tour-basic.xml	Thu May 07 21:07:35 2009 -0700
     5.3 @@ -0,0 +1,1035 @@
     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 id="x_1">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>Windows</title>
    5.19 +
    5.20 +      <para id="x_c">The best version of Mercurial for Windows is
    5.21 +	TortoiseHg, which can be found at <ulink
    5.22 +	  url="http://bitbucket.org/tortoisehg/stable/wiki/Home">http://bitbucket.org/tortoisehg/stable/wiki/Home</ulink>. 
    5.23 +	This package has no external dependencies; it <quote>just
    5.24 +	  works</quote>.  It provides both command line and graphical
    5.25 +	user interfaces.</para>
    5.26 +
    5.27 +    </sect2>
    5.28 +
    5.29 +    <sect2>
    5.30 +      <title>Mac OS X</title>
    5.31 +
    5.32 +      <para id="x_a">Lee Cantey publishes an installer of Mercurial
    5.33 +	for Mac OS X at <ulink
    5.34 +	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para>
    5.35 +    </sect2>
    5.36 +
    5.37 +    <sect2>
    5.38 +      <title>Linux</title>
    5.39 +
    5.40 +      <para id="x_2">Because each Linux distribution has its own packaging
    5.41 +	tools, policies, and rate of development, it's difficult to
    5.42 +	give a comprehensive set of instructions on how to install
    5.43 +	Mercurial binaries.  The version of Mercurial that you will
    5.44 +	end up with can vary depending on how active the person is who
    5.45 +	maintains the package for your distribution.</para>
    5.46 +
    5.47 +      <para id="x_3">To keep things simple, I will focus on installing
    5.48 +	Mercurial from the command line under the most popular Linux
    5.49 +	distributions.  Most of these distributions provide graphical
    5.50 +	package managers that will let you install Mercurial with a
    5.51 +	single click; the package name to look for is
    5.52 +	<literal>mercurial</literal>.</para>
    5.53 +
    5.54 +      <itemizedlist>
    5.55 +	<listitem><para id="x_4">Ubuntu and Debian:</para>
    5.56 +	  <programlisting>apt-get install mercurial</programlisting></listitem>
    5.57 +	<listitem><para id="x_5">Fedora:</para>
    5.58 +	  <programlisting>yum install mercurial</programlisting></listitem>
    5.59 +	<listitem><para id="x_715">OpenSUSE:</para>
    5.60 +	  <programlisting>zypper install mercurial</programlisting></listitem>
    5.61 +	<listitem><para id="x_6">Gentoo:</para>
    5.62 +	  <programlisting>emerge mercurial</programlisting></listitem>
    5.63 +      </itemizedlist>
    5.64 +
    5.65 +    </sect2>
    5.66 +    <sect2>
    5.67 +      <title>Solaris</title>
    5.68 +
    5.69 +      <para id="x_9">SunFreeWare, at <ulink
    5.70 +	  url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 
    5.71 +	provides prebuilt packages of Mercurial.</para>
    5.72 +
    5.73 +    </sect2>
    5.74 +
    5.75 +  </sect1>
    5.76 +
    5.77 +  <sect1>
    5.78 +    <title>Getting started</title>
    5.79 +
    5.80 +    <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg
    5.81 +	version</command> command to find out whether Mercurial is
    5.82 +      installed properly.  The actual version information that it
    5.83 +      prints isn't so important; we simply care whether the command
    5.84 +      runs and prints anything at all.</para>
    5.85 +
    5.86 +    &interaction.tour.version;
    5.87 +
    5.88 +    <sect2>
    5.89 +      <title>Built-in help</title>
    5.90 +
    5.91 +      <para id="x_f">Mercurial provides a built-in help system.  This is
    5.92 +	  invaluable for those times when you find yourself stuck
    5.93 +	  trying to remember how to run a command.  If you are
    5.94 +	  completely stuck, simply run <command role="hg-cmd">hg
    5.95 +	    help</command>; it will print a brief list of commands,
    5.96 +	  along with a description of what each does.  If you ask for
    5.97 +	  help on a specific command (as below), it prints more
    5.98 +	  detailed information.</para>
    5.99 +
   5.100 +	&interaction.tour.help;
   5.101 +
   5.102 +	<para id="x_10">For a more impressive level of detail (which you won't
   5.103 +	  usually need) run <command role="hg-cmd">hg help <option
   5.104 +	      role="hg-opt-global">-v</option></command>.  The <option
   5.105 +	    role="hg-opt-global">-v</option> option is short for
   5.106 +	  <option role="hg-opt-global">--verbose</option>, and tells
   5.107 +	  Mercurial to print more information than it usually
   5.108 +	  would.</para>
   5.109 +
   5.110 +    </sect2>
   5.111 +  </sect1>
   5.112 +  <sect1>
   5.113 +    <title>Working with a repository</title>
   5.114 +
   5.115 +    <para id="x_11">In Mercurial, everything happens inside a
   5.116 +      <emphasis>repository</emphasis>.  The repository for a project
   5.117 +      contains all of the files that <quote>belong to</quote> that
   5.118 +      project, along with a historical record of the project's
   5.119 +      files.</para>
   5.120 +
   5.121 +    <para id="x_12">There's nothing particularly magical about a repository; it
   5.122 +      is simply a directory tree in your filesystem that Mercurial
   5.123 +      treats as special. You can rename or delete a repository any
   5.124 +      time you like, using either the command line or your file
   5.125 +      browser.</para>
   5.126 +
   5.127 +    <sect2>
   5.128 +      <title>Making a local copy of a repository</title>
   5.129 +
   5.130 +      <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little
   5.131 +	bit special.  While you could use a normal file copying
   5.132 +	command to make a copy of a repository, it's best to use a
   5.133 +	built-in command that Mercurial provides.  This command is
   5.134 +	called <command role="hg-cmd">hg clone</command>, because it
   5.135 +	makes an identical copy of an existing repository.</para>
   5.136 +
   5.137 +      &interaction.tour.clone;
   5.138 +
   5.139 +      <para id="x_67c">One advantage of using <command role="hg-cmd">hg
   5.140 +	  clone</command> is that, as we can see above, it lets us clone
   5.141 +	repositories over the network.  Another is that it remembers
   5.142 +	where we cloned from, which we'll find useful soon when we
   5.143 +	want to fetch new changes from another repository.</para>
   5.144 +
   5.145 +      <para id="x_14">If our clone succeeded, we should now have a local
   5.146 +	directory called <filename class="directory">hello</filename>.
   5.147 +	This directory will contain some files.</para>
   5.148 +
   5.149 +      &interaction.tour.ls;
   5.150 +
   5.151 +      <para id="x_15">These files have the same contents and history in our
   5.152 +	repository as they do in the repository we cloned.</para>
   5.153 +
   5.154 +      <para id="x_16">Every Mercurial repository is complete,
   5.155 +	self-contained, and independent.  It contains its own private
   5.156 +	copy of a project's files and history.  As we just mentioned,
   5.157 +	a cloned repository remembers the location of the repository
   5.158 +	it was cloned from, but Mercurial will not communicate with
   5.159 +	that repository, or any other, unless you tell it to.</para>
   5.160 +
   5.161 +      <para id="x_17">What this means for now is that we're free to experiment
   5.162 +	with our repository, safe in the knowledge that it's a private
   5.163 +	<quote>sandbox</quote> that won't affect anyone else.</para>
   5.164 +
   5.165 +    </sect2>
   5.166 +    <sect2>
   5.167 +      <title>What's in a repository?</title>
   5.168 +
   5.169 +      <para id="x_18">When we take a more detailed look inside a repository, we
   5.170 +	can see that it contains a directory named <filename
   5.171 +	  class="directory">.hg</filename>.  This is where Mercurial
   5.172 +	keeps all of its metadata for the repository.</para>
   5.173 +
   5.174 +      &interaction.tour.ls-a;
   5.175 +
   5.176 +      <para id="x_19">The contents of the <filename
   5.177 +	  class="directory">.hg</filename> directory and its
   5.178 +	subdirectories are private to Mercurial.  Every other file and
   5.179 +	directory in the repository is yours to do with as you
   5.180 +	please.</para>
   5.181 +
   5.182 +      <para id="x_1a">To introduce a little terminology, the <filename
   5.183 +	  class="directory">.hg</filename> directory is the
   5.184 +	<quote>real</quote> repository, and all of the files and
   5.185 +	directories that coexist with it are said to live in the
   5.186 +	<emphasis>working directory</emphasis>.  An easy way to
   5.187 +	remember the distinction is that the
   5.188 +	<emphasis>repository</emphasis> contains the
   5.189 +	<emphasis>history</emphasis> of your project, while the
   5.190 +	<emphasis>working directory</emphasis> contains a
   5.191 +	<emphasis>snapshot</emphasis> of your project at a particular
   5.192 +	point in history.</para>
   5.193 +
   5.194 +    </sect2>
   5.195 +  </sect1>
   5.196 +  <sect1>
   5.197 +    <title>A tour through history</title>
   5.198 +
   5.199 +    <para id="x_1b">One of the first things we might want to do with a new,
   5.200 +      unfamiliar repository is understand its history.  The <command
   5.201 +	role="hg-cmd">hg log</command> command gives us a view of
   5.202 +      the history of changes in the repository.</para>
   5.203 +
   5.204 +    &interaction.tour.log;
   5.205 +
   5.206 +    <para id="x_1c">By default, this command prints a brief paragraph of output
   5.207 +      for each change to the project that was recorded.  In Mercurial
   5.208 +      terminology, we call each of these recorded events a
   5.209 +      <emphasis>changeset</emphasis>, because it can contain a record
   5.210 +      of changes to several files.</para>
   5.211 +
   5.212 +    <para id="x_1d">The fields in a record of output from <command
   5.213 +	role="hg-cmd">hg log</command> are as follows.</para>
   5.214 +
   5.215 +    <itemizedlist>
   5.216 +      <listitem><para id="x_1e"><literal>changeset</literal>: This
   5.217 +	  field has the format of a number, followed by a colon,
   5.218 +	  followed by a hexadecimal (or <emphasis>hex</emphasis>)
   5.219 +	  string.  These are <emphasis>identifiers</emphasis> for the
   5.220 +	  changeset.  The hex string is a unique identifier: the same
   5.221 +	  hex string will always refer to the same changeset in every
   5.222 +	  copy of this repository. The
   5.223 +	  number is shorter and easier to type than the hex string,
   5.224 +	  but it isn't unique: the same number in two different clones
   5.225 +	  of a repository may identify different changesets.</para>
   5.226 +      </listitem>
   5.227 +      <listitem><para id="x_1f"><literal>user</literal>: The identity of the
   5.228 +	  person who created the changeset.  This is a free-form
   5.229 +	  field, but it most often contains a person's name and email
   5.230 +	  address.</para></listitem>
   5.231 +      <listitem><para id="x_20"><literal>date</literal>: The date and time on
   5.232 +	  which the changeset was created, and the timezone in which
   5.233 +	  it was created.  (The date and time are local to that
   5.234 +	  timezone; they display what time and date it was for the
   5.235 +	  person who created the changeset.)</para></listitem>
   5.236 +      <listitem><para id="x_21"><literal>summary</literal>: The first line of
   5.237 +	  the text message that the creator of the changeset entered
   5.238 +	  to describe the changeset.</para></listitem>
   5.239 +      <listitem>
   5.240 +	<para id="x_67d">Some changesets, such as the first in the list above,
   5.241 +	  have a <literal>tag</literal> field.  A tag is another way
   5.242 +	  to identify a changeset, by giving it an easy-to-remember
   5.243 +	  name. (The tag named <literal>tip</literal> is special: it
   5.244 +	  always refers to the newest change in a repository.)</para>
   5.245 +      </listitem>
   5.246 +    </itemizedlist>
   5.247 +
   5.248 +    <para id="x_22">The default output printed by <command
   5.249 +	role="hg-cmd">hg log</command> is purely a summary; it is
   5.250 +      missing a lot of detail.</para>
   5.251 +
   5.252 +    <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides
   5.253 +      a 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 +    <figure id="fig:tour-basic:history">
   5.261 +      <title>Graphical history of the <filename
   5.262 +	  class="directory">hello</filename> repository</title>
   5.263 +      <mediaobject>
   5.264 +	<imageobject><imagedata fileref="figs/tour-history.png"/></imageobject>
   5.265 +	<textobject><phrase>XXX add text</phrase></textobject>
   5.266 +      </mediaobject>
   5.267 +    </figure>
   5.268 +
   5.269 +    <sect2>
   5.270 +      <title>Changesets, revisions, and talking to other
   5.271 +	people</title>
   5.272 +
   5.273 +      <para id="x_25">As English is a notoriously sloppy language, and computer
   5.274 +	science has a hallowed history of terminological confusion
   5.275 +	(why use one term when four will do?), revision control has a
   5.276 +	variety of words and phrases that mean the same thing.  If you
   5.277 +	are talking about Mercurial history with other people, you
   5.278 +	will find that the word <quote>changeset</quote> is often
   5.279 +	compressed to <quote>change</quote> or (when written)
   5.280 +	<quote>cset</quote>, and sometimes a changeset is referred to
   5.281 +	as a <quote>revision</quote> or a <quote>rev</quote>.</para>
   5.282 +
   5.283 +      <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you
   5.284 +	use to refer to the concept of <quote>a changeset</quote>, the
   5.285 +	<emphasis>identifier</emphasis> that you use to refer to
   5.286 +	<quote>a <emphasis>specific</emphasis> changeset</quote> is of
   5.287 +	great importance. Recall that the <literal>changeset</literal>
   5.288 +	field in the output from <command role="hg-cmd">hg
   5.289 +	  log</command> identifies a changeset using both a number and
   5.290 +	a hexadecimal string.</para>
   5.291 +      <itemizedlist>
   5.292 +	<listitem><para id="x_27">The revision number is a handy
   5.293 +	    notation that is <emphasis>only valid in that
   5.294 +	      repository</emphasis>.</para></listitem>
   5.295 +	<listitem><para id="x_28">The hexadecimal 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 +
   5.301 +      <para id="x_29">This distinction is important.  If you send
   5.302 +	someone an email talking about <quote>revision 33</quote>,
   5.303 +	there's a high likelihood that their revision 33 will
   5.304 +	<emphasis>not be the same</emphasis> as yours.  The reason for
   5.305 +	this is that a revision number depends on the order in which
   5.306 +	changes arrived in a repository, and there is no guarantee
   5.307 +	that the same changes will happen in the same order in
   5.308 +	different repositories. Three changes <literal>a,b,c</literal>
   5.309 +	can easily appear in one repository as
   5.310 +	<literal>0,1,2</literal>, while in another as
   5.311 +	<literal>0,2,1</literal>.</para>
   5.312 +
   5.313 +      <para id="x_2a">Mercurial uses revision numbers purely as a convenient
   5.314 +	shorthand.  If you need to discuss a changeset with someone,
   5.315 +	or make a record of a changeset for some other reason (for
   5.316 +	example, in a bug report), use the hexadecimal
   5.317 +	identifier.</para>
   5.318 +
   5.319 +    </sect2>
   5.320 +    <sect2>
   5.321 +      <title>Viewing specific revisions</title>
   5.322 +
   5.323 +      <para id="x_2b">To narrow the output of <command role="hg-cmd">hg
   5.324 +	  log</command> down to a single revision, use the <option
   5.325 +	  role="hg-opt-log">-r</option> (or <option
   5.326 +	  role="hg-opt-log">--rev</option>) option.  You can use
   5.327 +	either a revision number or a hexadecimal identifier,
   5.328 +	and you can provide as many revisions as you want.</para>
   5.329 +
   5.330 +      &interaction.tour.log-r;
   5.331 +
   5.332 +      <para id="x_2c">If you want to see the history of several revisions
   5.333 +	without having to list each one, you can use <emphasis>range
   5.334 +	  notation</emphasis>; this lets you express the idea <quote>I
   5.335 +	  want all revisions between <literal>abc</literal> and
   5.336 +	  <literal>def</literal>, inclusive</quote>.</para>
   5.337 +      
   5.338 +	&interaction.tour.log.range;
   5.339 +
   5.340 +      <para id="x_2d">Mercurial also honours the order in which you specify
   5.341 +	revisions, so <command role="hg-cmd">hg log -r 2:4</command>
   5.342 +	prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
   5.343 +	  4:2</command> prints 4, 3, and 2.</para>
   5.344 +
   5.345 +    </sect2>
   5.346 +    <sect2>
   5.347 +      <title>More detailed information</title>
   5.348 +
   5.349 +      <para id="x_2e">While the summary information printed by <command
   5.350 +	  role="hg-cmd">hg log</command> is useful if you already know
   5.351 +	what you're looking for, you may need to see a complete
   5.352 +	description of the change, or a list of the files changed, if
   5.353 +	you're trying to decide whether a changeset is the one you're
   5.354 +	looking for. The <command role="hg-cmd">hg log</command>
   5.355 +	command's <option role="hg-opt-global">-v</option> (or <option
   5.356 +	  role="hg-opt-global">--verbose</option>) option gives you
   5.357 +	this extra detail.</para>
   5.358 +
   5.359 +      &interaction.tour.log-v;
   5.360 +
   5.361 +      <para id="x_2f">If you want to see both the description and
   5.362 +	content of a change, add the <option
   5.363 +	  role="hg-opt-log">-p</option> (or <option
   5.364 +	  role="hg-opt-log">--patch</option>) option.  This displays
   5.365 +	the content of a change as a <emphasis>unified diff</emphasis>
   5.366 +	(if you've never seen a unified diff before, see <xref
   5.367 +	  linkend="sec:mq:patch"/> for an overview).</para>
   5.368 +
   5.369 +      &interaction.tour.log-vp;
   5.370 +
   5.371 +      <para id="x_67e">The <option role="hg-opt-log">-p</option> option is
   5.372 +	tremendously useful, so it's well worth remembering.</para>
   5.373 +
   5.374 +    </sect2>
   5.375 +  </sect1>
   5.376 +
   5.377 +  <sect1>
   5.378 +    <title>All about command options</title>
   5.379 +
   5.380 +    <para id="x_30">Let's take a brief break from exploring Mercurial commands
   5.381 +      to discuss a pattern in the way that they work; you may find
   5.382 +      this useful to keep in mind as we continue our tour.</para>
   5.383 +
   5.384 +    <para id="x_31">Mercurial has a consistent and straightforward approach to
   5.385 +      dealing with the options that you can pass to commands.  It
   5.386 +      follows the conventions for options that are common to modern
   5.387 +      Linux and Unix systems.</para>
   5.388 +
   5.389 +    <itemizedlist>
   5.390 +      <listitem>
   5.391 +	<para id="x_32">Every option has a long name.  For example, as
   5.392 +	  we've already seen, the <command role="hg-cmd">hg
   5.393 +	    log</command> command accepts a <option
   5.394 +	    role="hg-opt-log">--rev</option> option.</para>
   5.395 +      </listitem>
   5.396 +      <listitem>
   5.397 +	<para id="x_33">Most options have short names, too.  Instead
   5.398 +	  of <option role="hg-opt-log">--rev</option>, we can use
   5.399 +	  <option role="hg-opt-log">-r</option>.  (The reason that
   5.400 +	  some options don't have short names is that the options in
   5.401 +	  question are rarely used.)</para>
   5.402 +      </listitem>
   5.403 +      <listitem>
   5.404 +	<para id="x_34">Long options start with two dashes (e.g.
   5.405 +	  <option role="hg-opt-log">--rev</option>), while short
   5.406 +	  options start with one (e.g. <option
   5.407 +	    role="hg-opt-log">-r</option>).</para>
   5.408 +      </listitem>
   5.409 +      <listitem>
   5.410 +	<para id="x_35">Option naming and usage is consistent across
   5.411 +	  commands.  For example, every command that lets you specify
   5.412 +	  a changeset ID or revision number accepts both <option
   5.413 +	    role="hg-opt-log">-r</option> and <option
   5.414 +	    role="hg-opt-log">--rev</option> arguments.</para>
   5.415 +      </listitem>
   5.416 +      <listitem>
   5.417 +	<para id="x_67f">If you are using short options, you can save typing by
   5.418 +	  running them together. For example, the command <command
   5.419 +	    role="hg-cmd">hg log -v -p -r 2</command> can be written
   5.420 +	  as <command role="hg-cmd">hg log -vpr2</command>.</para>
   5.421 +      </listitem>
   5.422 +    </itemizedlist>
   5.423 +
   5.424 +    <para id="x_36">In the examples throughout this book, I usually
   5.425 +      use short options instead of long.  This simply reflects my own
   5.426 +      preference, so don't read anything significant into it.</para>
   5.427 +
   5.428 +    <para id="x_37">Most commands that print output of some kind will print more
   5.429 +      output when passed a <option role="hg-opt-global">-v</option>
   5.430 +      (or <option role="hg-opt-global">--verbose</option>) option, and
   5.431 +      less when passed <option role="hg-opt-global">-q</option> (or
   5.432 +      <option role="hg-opt-global">--quiet</option>).</para>
   5.433 +
   5.434 +    <note>
   5.435 +      <title>Option naming consistency</title>
   5.436 +
   5.437 +      <para id="x_680">Almost always, Mercurial commands use consistent option
   5.438 +	names to refer to the same concepts.  For instance, if a
   5.439 +	command deals with changesets, you'll always identify them
   5.440 +	with <option role="hg-opt-log">--rev</option> or <option
   5.441 +	  role="hg-opt-log">-r</option>.  This consistent use of
   5.442 +	option names makes it easier to remember what options a
   5.443 +	particular command takes.</para>
   5.444 +    </note>
   5.445 +
   5.446 +  </sect1>
   5.447 +  <sect1>
   5.448 +    <title>Making and reviewing changes</title>
   5.449 +
   5.450 +    <para id="x_38">Now that we have a grasp of viewing history in Mercurial,
   5.451 +      let's take a look at making some changes and examining
   5.452 +      them.</para>
   5.453 +
   5.454 +    <para id="x_39">The first thing we'll do is isolate our experiment in a
   5.455 +      repository of its own.  We use the <command role="hg-cmd">hg
   5.456 +	clone</command> command, but we don't need to clone a copy of
   5.457 +      the remote repository.  Since we already have a copy of it
   5.458 +      locally, we can just clone that instead.  This is much faster
   5.459 +      than cloning over the network, and cloning a local repository
   5.460 +      uses less disk space in most cases, too<footnote>
   5.461 +	<para id="x_681">The saving of space arises when source and destination
   5.462 +	  repositories are on the same filesystem, in which case
   5.463 +	  Mercurial will use hardlinks to do copy-on-write sharing of
   5.464 +	  its internal metadata.  If that explanation meant nothing to
   5.465 +	  you, don't worry: everything happens transparently and
   5.466 +	  automatically, and you don't need to understand it.</para>
   5.467 +	</footnote>.</para>
   5.468 +
   5.469 +    &interaction.tour.reclone;
   5.470 +
   5.471 +    <para id="x_3a">As an aside, it's often good practice to keep a
   5.472 +      <quote>pristine</quote> copy of a remote repository around,
   5.473 +      which you can then make temporary clones of to create sandboxes
   5.474 +      for each task you want to work on.  This lets you work on
   5.475 +      multiple tasks in parallel, each isolated from the others until
   5.476 +      it's complete and you're ready to integrate it back.  Because
   5.477 +      local clones are so cheap, there's almost no overhead to cloning
   5.478 +      and destroying repositories whenever you want.</para>
   5.479 +
   5.480 +    <para id="x_3b">In our <filename class="directory">my-hello</filename>
   5.481 +      repository, we have a file <filename>hello.c</filename> that
   5.482 +      contains the classic <quote>hello, world</quote> program.</para>
   5.483 +
   5.484 +    &interaction.tour.cat1;
   5.485 +
   5.486 +    <para id="x_682">Let's edit this file so that it prints a second line of
   5.487 +      output.</para>
   5.488 +
   5.489 +    &interaction.tour.cat2;
   5.490 +
   5.491 +    <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command>
   5.492 +      command will tell us what Mercurial knows about the files in the
   5.493 +      repository.</para>
   5.494 +
   5.495 +    &interaction.tour.status;
   5.496 +
   5.497 +    <para id="x_3d">The <command role="hg-cmd">hg status</command> command
   5.498 +      prints no output for some files, but a line starting with
   5.499 +      <quote><literal>M</literal></quote> for
   5.500 +      <filename>hello.c</filename>.  Unless you tell it to, <command
   5.501 +	role="hg-cmd">hg status</command> will not print any output
   5.502 +      for files that have not been modified.</para>
   5.503 +
   5.504 +    <para id="x_3e">The <quote><literal>M</literal></quote> indicates that
   5.505 +      Mercurial has noticed that we modified
   5.506 +      <filename>hello.c</filename>.  We didn't need to
   5.507 +      <emphasis>inform</emphasis> Mercurial that we were going to
   5.508 +      modify the file before we started, or that we had modified the
   5.509 +      file after we were done; it was able to figure this out
   5.510 +      itself.</para>
   5.511 +
   5.512 +    <para id="x_3f">It's somewhat helpful to know that we've modified
   5.513 +      <filename>hello.c</filename>, but we might prefer to know
   5.514 +      exactly <emphasis>what</emphasis> changes we've made to it.  To
   5.515 +      do this, we use the <command role="hg-cmd">hg diff</command>
   5.516 +      command.</para>
   5.517 +
   5.518 +    &interaction.tour.diff;
   5.519 +
   5.520 +    <tip>
   5.521 +      <title>Understanding patches</title>
   5.522 +
   5.523 +      <para id="x_683">Remember to take a look at <xref
   5.524 +	  linkend="sec:mq:patch"/> if you don't know how to read
   5.525 +	output above.</para>
   5.526 +    </tip>
   5.527 +  </sect1>
   5.528 +  <sect1>
   5.529 +    <title>Recording changes in a new changeset</title>
   5.530 +
   5.531 +    <para id="x_40">We can modify files, build and test our changes, and use
   5.532 +      <command role="hg-cmd">hg status</command> and <command
   5.533 +	role="hg-cmd">hg diff</command> to review our changes, until
   5.534 +      we're satisfied with what we've done and arrive at a natural
   5.535 +      stopping point where we want to record our work in a new
   5.536 +      changeset.</para>
   5.537 +
   5.538 +    <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets
   5.539 +      us create a new changeset; we'll usually refer to this as
   5.540 +      <quote>making a commit</quote> or
   5.541 +      <quote>committing</quote>.</para>
   5.542 +
   5.543 +    <sect2>
   5.544 +      <title>Setting up a username</title>
   5.545 +
   5.546 +      <para id="x_42">When you try to run <command role="hg-cmd">hg
   5.547 +	  commit</command> for the first time, it is not guaranteed to
   5.548 +	succeed.  Mercurial records your name and address with each
   5.549 +	change that you commit, so that you and others will later be
   5.550 +	able to tell who made each change.  Mercurial tries to
   5.551 +	automatically figure out a sensible username to commit the
   5.552 +	change with.  It will attempt each of the following methods,
   5.553 +	in order:</para>
   5.554 +      <orderedlist>
   5.555 +	<listitem><para id="x_43">If you specify a <option
   5.556 +	      role="hg-opt-commit">-u</option> option to the <command
   5.557 +	      role="hg-cmd">hg commit</command> command on the command
   5.558 +	    line, followed by a username, this is always given the
   5.559 +	    highest precedence.</para></listitem>
   5.560 +	<listitem><para id="x_44">If you have set the <envar>HGUSER</envar>
   5.561 +	    environment variable, this is checked
   5.562 +	    next.</para></listitem>
   5.563 +	<listitem><para id="x_45">If you create a file in your home
   5.564 +	    directory called <filename
   5.565 +	      role="special">.hgrc</filename>, with a <envar
   5.566 +	      role="rc-item-ui">username</envar> entry, that will be
   5.567 +	    used next.  To see what the contents of this file should
   5.568 +	    look like, refer to <xref
   5.569 +	      linkend="sec:tour-basic:username"/>
   5.570 +	    below.</para></listitem>
   5.571 +	<listitem><para id="x_46">If you have set the <envar>EMAIL</envar>
   5.572 +	    environment variable, this will be used
   5.573 +	    next.</para></listitem>
   5.574 +	<listitem><para id="x_47">Mercurial will query your system to find out
   5.575 +	    your local user name and host name, and construct a
   5.576 +	    username from these components. Since this often results
   5.577 +	    in a username that is not very useful, it will print a
   5.578 +	    warning if it has to do
   5.579 +	    this.</para></listitem>
   5.580 +      </orderedlist>
   5.581 +      <para id="x_48">If all of these mechanisms fail, Mercurial will
   5.582 +	  fail, printing an error message.  In this case, it will not
   5.583 +	  let you commit until you set up a
   5.584 +	  username.</para>
   5.585 +      <para id="x_49">You should think of the <envar>HGUSER</envar> environment
   5.586 +	variable and the <option role="hg-opt-commit">-u</option>
   5.587 +	option to the <command role="hg-cmd">hg commit</command>
   5.588 +	command as ways to <emphasis>override</emphasis> Mercurial's
   5.589 +	default selection of username.  For normal use, the simplest
   5.590 +	and most robust way to set a username for yourself is by
   5.591 +	creating a <filename role="special">.hgrc</filename> file; see
   5.592 +	below for details.</para>
   5.593 +      <sect3 id="sec:tour-basic:username">
   5.594 +	<title>Creating a Mercurial configuration file</title>
   5.595 +
   5.596 +	<para id="x_4a">To set a user name, use your favorite editor
   5.597 +	  to create a file called <filename
   5.598 +	    role="special">.hgrc</filename> in your home directory.
   5.599 +	  Mercurial will use this file to look up your personalised
   5.600 +	  configuration settings.  The initial contents of your
   5.601 +	  <filename role="special">.hgrc</filename> should look like
   5.602 +	  this.</para>
   5.603 +
   5.604 +	<tip>
   5.605 +	  <title><quote>Home directory</quote> on Windows</title>
   5.606 +
   5.607 +	  <para id="x_716">When we refer to your home directory, on an English
   5.608 +	    language installation of Windows this will usually be a
   5.609 +	    folder named after your user name in
   5.610 +	    <filename>C:\Documents and Settings</filename>.  You can
   5.611 +	    find out the exact name of your home directory by opening
   5.612 +	    a command prompt window and running the following
   5.613 +	    command.</para>
   5.614 +
   5.615 +	  <screen><prompt>C:\></prompt> <userinput>echo %UserProfile%</userinput></screen>
   5.616 +	</tip>
   5.617 +
   5.618 +	<programlisting># This is a Mercurial configuration file.
   5.619 +[ui]
   5.620 +username = Firstname Lastname &lt;email.address@example.net&gt;</programlisting>
   5.621 +
   5.622 +	<para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a
   5.623 +	  <emphasis>section</emphasis> of the config file, so you can
   5.624 +	  read the <quote><literal>username = ...</literal></quote>
   5.625 +	  line as meaning <quote>set the value of the
   5.626 +	    <literal>username</literal> item in the
   5.627 +	    <literal>ui</literal> section</quote>. A section continues
   5.628 +	  until a new section begins, or the end of the file.
   5.629 +	  Mercurial ignores empty lines and treats any text from
   5.630 +	  <quote><literal>#</literal></quote> to the end of a line as
   5.631 +	  a comment.</para>
   5.632 +      </sect3>
   5.633 +
   5.634 +      <sect3>
   5.635 +	<title>Choosing a user name</title>
   5.636 +
   5.637 +	<para id="x_4c">You can use any text you like as the value of
   5.638 +	  the <literal>username</literal> config item, since this
   5.639 +	  information is for reading by other people, but will not be
   5.640 +	  interpreted by Mercurial.  The convention that most people
   5.641 +	  follow is to use their name and email address, as in the
   5.642 +	  example above.</para>
   5.643 +	<note>
   5.644 +	  <para id="x_4d">Mercurial's built-in web server obfuscates
   5.645 +	    email addresses, to make it more difficult for the email
   5.646 +	    harvesting tools that spammers use. This reduces the
   5.647 +	    likelihood that you'll start receiving more junk email if
   5.648 +	    you publish a Mercurial repository on the
   5.649 +	    web.</para></note>
   5.650 +      </sect3>
   5.651 +    </sect2>
   5.652 +    <sect2>
   5.653 +      <title>Writing a commit message</title>
   5.654 +
   5.655 +      <para id="x_4e">When we commit a change, Mercurial drops us into
   5.656 +	a text editor, to enter a message that will describe the
   5.657 +	modifications we've made in this changeset.  This is called
   5.658 +	the <emphasis>commit message</emphasis>.  It will be a record
   5.659 +	for readers of what we did and why, and it will be printed by
   5.660 +	<command role="hg-cmd">hg log</command> after we've finished
   5.661 +	committing.</para>
   5.662 +
   5.663 +       &interaction.tour.commit;
   5.664 +
   5.665 +      <para id="x_4f">The editor that the <command role="hg-cmd">hg
   5.666 +	  commit</command> command drops us into will contain an empty
   5.667 +	line or two, followed by a number of lines starting with
   5.668 +	<quote><literal>HG:</literal></quote>.</para>
   5.669 +
   5.670 +    <programlisting>
   5.671 +This is where I type my commit comment.
   5.672 +
   5.673 +HG: Enter commit message.  Lines beginning with 'HG:' are removed.
   5.674 +HG: --
   5.675 +HG: user: Bryan O'Sullivan &lt;bos@serpentine.com&gt;
   5.676 +HG: branch 'default'
   5.677 +HG: changed hello.c</programlisting>
   5.678 +
   5.679 +      <para id="x_50">Mercurial ignores the lines that start with
   5.680 +	<quote><literal>HG:</literal></quote>; it uses them only to
   5.681 +	tell us which files it's recording changes to.  Modifying or
   5.682 +	deleting these lines has no effect.</para>
   5.683 +    </sect2>
   5.684 +    <sect2>
   5.685 +      <title>Writing a good commit message</title>
   5.686 +
   5.687 +      <para id="x_51">Since <command role="hg-cmd">hg log</command>
   5.688 +	only prints the first line of a commit message by default,
   5.689 +	it's best to write a commit message whose first line stands
   5.690 +	alone.  Here's a real example of a commit message that
   5.691 +	<emphasis>doesn't</emphasis> follow this guideline, and hence
   5.692 +	has a summary that is not readable.</para>
   5.693 +
   5.694 +      <programlisting>
   5.695 +changeset:   73:584af0e231be
   5.696 +user:        Censored Person &lt;censored.person@example.org&gt;
   5.697 +date:        Tue Sep 26 21:37:07 2006 -0700
   5.698 +summary:     include buildmeister/commondefs. Add exports.</programlisting>
   5.699 +
   5.700 +      <para id="x_52">As far as the remainder of the contents of the
   5.701 +	commit message are concerned, there are no hard-and-fast
   5.702 +	rules.  Mercurial itself doesn't interpret or care about the
   5.703 +	contents of the commit message, though your project may have
   5.704 +	policies that dictate a certain kind of formatting.</para>
   5.705 +      <para id="x_53">My personal preference is for short, but
   5.706 +	informative, commit messages that tell me something that I
   5.707 +	can't figure out with a quick glance at the output of <command
   5.708 +	  role="hg-cmd">hg log --patch</command>.</para>
   5.709 +      <para id="x_55">If we run the <command role="hg-cmd">hg
   5.710 +	  commit</command> command without any arguments, it records
   5.711 +	all of the changes we've made, as reported by <command
   5.712 +	  role="hg-cmd">hg status</command> and <command
   5.713 +	  role="hg-cmd">hg diff</command>.</para>
   5.714 +
   5.715 +      <note>
   5.716 +	<title>A surprise for Subversion users</title>
   5.717 +
   5.718 +	<para id="x_717">Like other Mercurial commands, if we don't supply
   5.719 +	  explicit names to commit to the <command role="hg-cmd">hg
   5.720 +	    commit</command>, it will operate across a repository's
   5.721 +	  entire working directory.  Be wary of this if you're coming
   5.722 +	  from the Subversion or CVS world, since you might expect it
   5.723 +	  to operate only on the current directory that you happen to
   5.724 +	  be visiting and its subdirectories.</para>
   5.725 +      </note>
   5.726 +    </sect2>
   5.727 +
   5.728 +    <sect2>
   5.729 +      <title>Aborting a commit</title>
   5.730 +
   5.731 +      <para id="x_54">If you decide that you don't want to commit
   5.732 +	while in the middle of editing a commit message, simply exit
   5.733 +	from your editor without saving the file that it's editing.
   5.734 +	This will cause nothing to happen to either the repository or
   5.735 +	the working directory.</para>
   5.736 +    </sect2>
   5.737 +
   5.738 +    <sect2>
   5.739 +      <title>Admiring our new handiwork</title>
   5.740 +
   5.741 +      <para id="x_56">Once we've finished the commit, we can use the
   5.742 +	<command role="hg-cmd">hg tip</command> command to display the
   5.743 +	changeset we just created.  This command produces output that
   5.744 +	is identical to <command role="hg-cmd">hg log</command>, but
   5.745 +	it only displays the newest revision in the repository.</para>
   5.746 +
   5.747 +      &interaction.tour.tip;
   5.748 +
   5.749 +      <para id="x_57">We refer to the newest revision in the
   5.750 +	repository as the <emphasis>tip revision</emphasis>, or simply
   5.751 +	the <emphasis>tip</emphasis>.</para>
   5.752 +
   5.753 +      <para id="x_684">By the way, the <command role="hg-cmd">hg tip</command>
   5.754 +	command accepts many of the same options as <command
   5.755 +	  role="hg-cmd">hg log</command>, so <option
   5.756 +	  role="hg-opt-global">-v</option> above indicates <quote>be
   5.757 +	  verbose</quote>, <option role="hg-opt-tip">-p</option>
   5.758 +	specifies <quote>print a patch</quote>.  The use of <option
   5.759 +	  role="hg-opt-tip">-p</option> to print patches is another
   5.760 +	example of the consistent naming we mentioned earlier.</para>
   5.761 +    </sect2>
   5.762 +  </sect1>
   5.763 +
   5.764 +  <sect1>
   5.765 +    <title>Sharing changes</title>
   5.766 +
   5.767 +    <para id="x_58">We mentioned earlier that repositories in
   5.768 +      Mercurial are self-contained.  This means that the changeset we
   5.769 +      just created exists only in our <filename
   5.770 +	class="directory">my-hello</filename> repository.  Let's look
   5.771 +      at a few ways that we can propagate this change into other
   5.772 +      repositories.</para>
   5.773 +
   5.774 +    <sect2 id="sec:tour:pull">
   5.775 +      <title>Pulling changes from another repository</title>
   5.776 +
   5.777 +      <para id="x_59">To get started, let's clone our original
   5.778 +	<filename class="directory">hello</filename> repository, which
   5.779 +	does not contain the change we just committed.  We'll call our
   5.780 +	temporary repository <filename
   5.781 +	  class="directory">hello-pull</filename>.</para>
   5.782 +
   5.783 +      &interaction.tour.clone-pull;
   5.784 +
   5.785 +      <para id="x_5a">We'll use the <command role="hg-cmd">hg
   5.786 +	  pull</command> command to bring changes from <filename
   5.787 +	  class="directory">my-hello</filename> into <filename
   5.788 +	  class="directory">hello-pull</filename>.  However, blindly
   5.789 +	pulling unknown changes into a repository is a somewhat scary
   5.790 +	prospect.  Mercurial provides the <command role="hg-cmd">hg
   5.791 +	  incoming</command> command to tell us what changes the
   5.792 +	<command role="hg-cmd">hg pull</command> command
   5.793 +	<emphasis>would</emphasis> pull into the repository, without
   5.794 +	actually pulling the changes in.</para>
   5.795 +
   5.796 +      &interaction.tour.incoming;
   5.797 +
   5.798 +      <para id="x_5c">Bringing changes into a repository is a simple
   5.799 +	matter of running the <command role="hg-cmd">hg pull</command>
   5.800 +	command, and optionally telling it which repository to pull from.</para>
   5.801 +
   5.802 +      &interaction.tour.pull;
   5.803 +
   5.804 +      <para id="x_5d">As you can see from the before-and-after output
   5.805 +	of <command role="hg-cmd">hg tip</command>, we have
   5.806 +	successfully pulled changes into our repository.  However,
   5.807 +	Mercurial separates pulling changes in from updating the
   5.808 +	working directory. There remains one step before we will see
   5.809 +	the changes that we just pulled appear in the working
   5.810 +	directory.</para>
   5.811 +
   5.812 +      <tip>
   5.813 +	<title>Pulling specific changes</title>
   5.814 +
   5.815 +	<para id="x_5b">It is possible that due to the delay between
   5.816 +	  running <command role="hg-cmd">hg incoming</command> and
   5.817 +	  <command role="hg-cmd">hg pull</command>, you may not see
   5.818 +	  all changesets that will be brought from the other
   5.819 +	  repository. Suppose you're pulling changes from a repository
   5.820 +	  on the network somewhere. While you are looking at the
   5.821 +	  <command role="hg-cmd">hg incoming</command> output, and
   5.822 +	  before you pull those changes, someone might have committed
   5.823 +	  something in the remote repository. This means that it's
   5.824 +	  possible to pull more changes than you saw when using
   5.825 +	  <command role="hg-cmd">hg incoming</command>.</para>
   5.826 +
   5.827 +	<para id="x_718">If you only want to pull precisely the changes that were
   5.828 +	  listed by <command role="hg-cmd">hg incoming</command>, or
   5.829 +	  you have some other reason to pull a subset of changes,
   5.830 +	  simply identify the change that you want to pull by its
   5.831 +	  changeset ID, e.g. <command>hg pull
   5.832 +	    -r7e95bb</command>.</para>
   5.833 +      </tip>
   5.834 +    </sect2>
   5.835 +
   5.836 +    <sect2>
   5.837 +      <title>Updating the working directory</title>
   5.838 +
   5.839 +      <para id="x_5e">We have so far glossed over the relationship
   5.840 +	between a repository and its working directory.  The <command
   5.841 +	  role="hg-cmd">hg pull</command> command that we ran in
   5.842 +	<xref linkend="sec:tour:pull"/> brought changes into the
   5.843 +	repository, but if we check, there's no sign of those changes
   5.844 +	in the working directory.  This is because <command
   5.845 +	  role="hg-cmd">hg pull</command> does not (by default) touch
   5.846 +	the working directory.  Instead, we use the <command
   5.847 +	  role="hg-cmd">hg update</command> command to do this.</para>
   5.848 +
   5.849 +      &interaction.tour.update;
   5.850 +
   5.851 +      <para id="x_5f">It might seem a bit strange that <command
   5.852 +	  role="hg-cmd">hg pull</command> doesn't update the working
   5.853 +	directory automatically.  There's actually a good reason for
   5.854 +	this: you can use <command role="hg-cmd">hg update</command>
   5.855 +	to update the working directory to the state it was in at
   5.856 +	<emphasis>any revision</emphasis> in the history of the
   5.857 +	repository.  If you had the working directory updated to an
   5.858 +	old revision&emdash;to hunt down the origin of a bug,
   5.859 +	say&emdash;and ran a <command role="hg-cmd">hg pull</command>
   5.860 +	which automatically updated the working directory to a new
   5.861 +	revision, you might not be terribly happy.</para>
   5.862 +
   5.863 +      <para id="x_60">Since pull-then-update is such a common sequence
   5.864 +	of operations, Mercurial lets you combine the two by passing
   5.865 +	the <option role="hg-opt-pull">-u</option> option to <command
   5.866 +	  role="hg-cmd">hg pull</command>.</para>
   5.867 +
   5.868 +      <para id="x_61">If you look back at the output of <command
   5.869 +	  role="hg-cmd">hg pull</command> in <xref
   5.870 +	    linkend="sec:tour:pull"/> when we ran it without <option
   5.871 +	  role="hg-opt-pull">-u</option>, you can see that it printed
   5.872 +	a helpful reminder that we'd have to take an explicit step to
   5.873 +	update the working directory.</para>
   5.874 +
   5.875 +      <para id="x_62">To find out what revision the working directory
   5.876 +	is at, use the <command role="hg-cmd">hg parents</command>
   5.877 +	command.</para>
   5.878 +
   5.879 +      &interaction.tour.parents;
   5.880 +
   5.881 +      <para id="x_63">If you look back at <xref
   5.882 +	  linkend="fig:tour-basic:history"/>, you'll see arrows
   5.883 +	connecting each changeset.  The node that the arrow leads
   5.884 +	<emphasis>from</emphasis> in each case is a parent, and the
   5.885 +	node that the arrow leads <emphasis>to</emphasis> is its
   5.886 +	child.  The working directory has a parent in just the same
   5.887 +	way; this is the changeset that the working directory
   5.888 +	currently contains.</para>
   5.889 +
   5.890 +      <para id="x_64">To update the working directory to a particular
   5.891 +	revision, give a revision number or changeset ID to the
   5.892 +	<command role="hg-cmd">hg update</command> command.</para>
   5.893 +
   5.894 +      &interaction.tour.older;
   5.895 +
   5.896 +      <para id="x_65">If you omit an explicit revision, <command
   5.897 +	  role="hg-cmd">hg update</command> will update to the tip
   5.898 +	revision, as shown by the second call to <command
   5.899 +	  role="hg-cmd">hg update</command> in the example
   5.900 +	above.</para>
   5.901 +    </sect2>
   5.902 +
   5.903 +    <sect2>
   5.904 +      <title>Pushing changes to another repository</title>
   5.905 +
   5.906 +      <para id="x_66">Mercurial lets us push changes to another
   5.907 +	repository, from the repository we're currently visiting. As
   5.908 +	with the example of <command role="hg-cmd">hg pull</command>
   5.909 +	above, we'll create a temporary repository to push our changes
   5.910 +	into.</para>
   5.911 +
   5.912 +      &interaction.tour.clone-push;
   5.913 +
   5.914 +      <para id="x_67">The <command role="hg-cmd">hg outgoing</command>
   5.915 +	command tells us what changes would be pushed into another
   5.916 +	repository.</para>
   5.917 +
   5.918 +      &interaction.tour.outgoing;
   5.919 +
   5.920 +      <para id="x_68">And the <command role="hg-cmd">hg push</command>
   5.921 +	command does the actual push.</para>
   5.922 +
   5.923 +      &interaction.tour.push;
   5.924 +
   5.925 +      <para id="x_69">As with <command role="hg-cmd">hg
   5.926 +	  pull</command>, the <command role="hg-cmd">hg push</command>
   5.927 +	command does not update the working directory in the
   5.928 +	repository that it's pushing changes into. Unlike <command
   5.929 +	  role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg
   5.930 +	  push</command> does not provide a <literal>-u</literal>
   5.931 +	option that updates the other repository's working directory.
   5.932 +	This asymmetry is deliberate: the repository we're pushing to
   5.933 +	might be on a remote server and shared between several people.
   5.934 +	If we were to update its working directory while someone was
   5.935 +	working in it, their work would be disrupted.</para>
   5.936 +
   5.937 +      <para id="x_6a">What happens if we try to pull or push changes
   5.938 +	  and the receiving repository already has those changes?
   5.939 +	  Nothing too exciting.</para>
   5.940 +
   5.941 +      &interaction.tour.push.nothing;
   5.942 +    </sect2>
   5.943 +
   5.944 +    <sect2>
   5.945 +      <title>Default locations</title>
   5.946 +
   5.947 +      <para id="x_719">When we clone a repository, Mercurial records the location
   5.948 +	of the repository we cloned in the
   5.949 +	<filename>.hg/hgrc</filename> file of the new repository.  If
   5.950 +	we don't supply a location to <command>hg pull</command> from
   5.951 +	or <command>hg push</command> to, those commands will use this
   5.952 +	location as a default.  The <command>hg incoming</command>
   5.953 +	and <command>hg outgoing</command> commands do so too.</para>
   5.954 +
   5.955 +      <para id="x_71a">If you open a repository's <filename>.hg/hgrc</filename>
   5.956 +	file in a text editor, you will see contents like the
   5.957 +	following.</para>
   5.958 +
   5.959 +      <programlisting>[paths]
   5.960 +default = http://www.selenic.com/repo/hg</programlisting>
   5.961 +
   5.962 +      <para id="x_71b">It is possible&emdash;and often useful&emdash;to have the
   5.963 +	default location for <command>hg push</command> and
   5.964 +	<command>hg outgoing</command> be different from those for
   5.965 +	<command>hg pull</command> and <command>hg incoming</command>.
   5.966 +	We can do this by adding a <literal>default-push</literal>
   5.967 +	entry to the <literal>[paths]</literal> section of the
   5.968 +	<filename>.hg/hgrc</filename> file, as follows.</para>
   5.969 +
   5.970 +      <programlisting>[paths]
   5.971 +default = http://www.selenic.com/repo/hg
   5.972 +default-push = http://hg.example.com/hg</programlisting>
   5.973 +    </sect2>
   5.974 +
   5.975 +    <sect2>
   5.976 +      <title>Sharing changes over a network</title>
   5.977 +
   5.978 +      <para id="x_6b">The commands we have covered in the previous few
   5.979 +	  sections are not limited to working with local repositories.
   5.980 +	  Each works in exactly the same fashion over a network
   5.981 +	  connection; simply pass in a URL instead of a local
   5.982 +	  path.</para>
   5.983 +	
   5.984 +      &interaction.tour.outgoing.net;
   5.985 +
   5.986 +      <para id="x_6c">In this example, we can see what changes we
   5.987 +	could push to the remote repository, but the repository is
   5.988 +	understandably not set up to let anonymous users push to
   5.989 +	it.</para>
   5.990 +
   5.991 +      &interaction.tour.push.net;
   5.992 +    </sect2>
   5.993 +  </sect1>
   5.994 +
   5.995 +  <sect1>
   5.996 +    <title>Starting a new project</title>
   5.997 +
   5.998 +    <para id="x_71c">It is just as easy to begin a new project as to work on one
   5.999 +      that already exists.  The <command>hg init</command> command
  5.1000 +      creates a new, empty Mercurial repository.</para>
  5.1001 +
  5.1002 +    &interaction.ch01-new.init;
  5.1003 +
  5.1004 +    <para id="x_71d">This simply creates a repository named
  5.1005 +      <filename>myproject</filename> in the current directory.</para>
  5.1006 +
  5.1007 +    &interaction.ch01-new.ls;
  5.1008 +
  5.1009 +    <para id="x_71e">We can tell that <filename>myproject</filename> is a
  5.1010 +      Mercurial repository, because it contains a
  5.1011 +      <filename>.hg</filename> directory.</para>
  5.1012 +
  5.1013 +    &interaction.ch01-new.ls2;
  5.1014 +
  5.1015 +    <para id="x_71f">If we want to add some pre-existing files to the repository,
  5.1016 +      we copy them into place, and tell Mercurial to start tracking
  5.1017 +      them using the <command>hg add</command> command.</para>
  5.1018 +
  5.1019 +    &interaction.ch01-new.add;
  5.1020 +
  5.1021 +    <para id="x_720">Once we are satisfied that our project looks right, we
  5.1022 +      commit our changes.</para>
  5.1023 +
  5.1024 +    &interaction.ch01-new.commit;
  5.1025 +
  5.1026 +    <para id="x_721">It takes just a few moments to start using Mercurial on a
  5.1027 +      new project, which is part of its appeal. Revision control is
  5.1028 +      now so easy to work with, we can use it on the smallest of
  5.1029 +      projects that we might not have considered with a more
  5.1030 +      complicated tool.</para>
  5.1031 +  </sect1>
  5.1032 +</chapter>
  5.1033 +
  5.1034 +<!--
  5.1035 +local variables: 
  5.1036 +sgml-parent-document: ("00book.xml" "book" "chapter")
  5.1037 +end:
  5.1038 +-->

     6.1 --- a/en/ch02-tour-merge.xml	Thu May 07 21:06:49 2009 -0700
     6.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.3 @@ -1,454 +0,0 @@
     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 id="x_338">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 id="x_339">Merging is a fundamental part of working with a distributed
    6.19 -      revision control tool.  Here are a few cases in which the need
    6.20 -      to merge work arises.</para>
    6.21 -    <itemizedlist>
    6.22 -      <listitem>
    6.23 -	<para id="x_33a">Alice and Bob each have a personal copy of a
    6.24 -	  repository for a project they're collaborating on.  Alice
    6.25 -	  fixes a bug in her repository; Bob adds a new feature in
    6.26 -	  his.  They want the shared repository to contain both the
    6.27 -	  bug fix and the new feature.</para>
    6.28 -      </listitem>
    6.29 -      <listitem>
    6.30 -	<para id="x_33b">Cynthia frequently works on several different
    6.31 -	  tasks for a single project at once, each safely isolated in
    6.32 -	  its own repository. Working this way means that she often
    6.33 -	  needs to merge one piece of her own work with
    6.34 -	  another.</para>
    6.35 -      </listitem>
    6.36 -    </itemizedlist>
    6.37 -
    6.38 -    <para id="x_33c">Because we need to merge often, Mercurial makes
    6.39 -      the process easy.  Let's walk through a merge.  We'll begin by
    6.40 -      cloning yet another repository (see how often they spring up?)
    6.41 -      and making a change in it.</para>
    6.42 -
    6.43 -    &interaction.tour.merge.clone;
    6.44 -
    6.45 -    <para id="x_33d">We should now have two copies of
    6.46 -      <filename>hello.c</filename> with different contents.  The
    6.47 -      histories of the two repositories have also diverged, as
    6.48 -      illustrated in <xref
    6.49 -	linkend="fig:tour-merge:sep-repos"/>.  Here is a copy of our
    6.50 -      file from one repository.</para>
    6.51 -
    6.52 -    &interaction.tour.merge.cat1;
    6.53 -
    6.54 -    <para id="x_722">And here is our slightly different version from the other
    6.55 -      repository.</para>
    6.56 -
    6.57 -    &interaction.tour.merge.cat2;
    6.58 -
    6.59 -    <figure id="fig:tour-merge:sep-repos">
    6.60 -      <title>Divergent recent histories of the <filename
    6.61 -	  class="directory">my-hello</filename> and <filename
    6.62 -	  class="directory">my-new-hello</filename>
    6.63 -	repositories</title>
    6.64 -      <mediaobject>
    6.65 -	<imageobject><imagedata fileref="figs/tour-merge-sep-repos.png"/></imageobject>
    6.66 -	<textobject><phrase>XXX add text</phrase></textobject>
    6.67 -      </mediaobject>
    6.68 -    </figure>
    6.69 -
    6.70 -    <para id="x_33f">We already know that pulling changes from our <filename
    6.71 -	class="directory">my-hello</filename> repository will have no
    6.72 -      effect on the working directory.</para>
    6.73 -
    6.74 -    &interaction.tour.merge.pull;
    6.75 -
    6.76 -    <para id="x_340">However, the <command role="hg-cmd">hg pull</command>
    6.77 -      command says something about <quote>heads</quote>.</para>
    6.78 -
    6.79 -    <sect2>
    6.80 -      <title>Head changesets</title>
    6.81 -
    6.82 -      <para id="x_341">Remember that Mercurial records what the parent
    6.83 -	of each change is.  If a change has a parent, we call it a
    6.84 -	child or descendant of the parent.  A head is a change that
    6.85 -	has no children.  The tip revision is thus a head, because the
    6.86 -	newest revision in a repository doesn't have any children.
    6.87 -	There are times when a repository can contain more than one
    6.88 -	head.</para>
    6.89 -
    6.90 -      <figure id="fig:tour-merge:pull">
    6.91 -	<title>Repository contents after pulling from <filename
    6.92 -	    class="directory">my-hello</filename> into <filename
    6.93 -	    class="directory">my-new-hello</filename></title>
    6.94 -	<mediaobject>
    6.95 -	  <imageobject>
    6.96 -	    <imagedata fileref="figs/tour-merge-pull.png"/>
    6.97 -	  </imageobject>
    6.98 -	  <textobject><phrase>XXX add text</phrase></textobject>
    6.99 -	</mediaobject>
   6.100 -      </figure>
   6.101 -
   6.102 -      <para id="x_343">In <xref linkend="fig:tour-merge:pull"/>, you can
   6.103 -	see the effect of the pull from <filename
   6.104 -	  class="directory">my-hello</filename> into <filename
   6.105 -	  class="directory">my-new-hello</filename>.  The history that
   6.106 -	was already present in <filename
   6.107 -	  class="directory">my-new-hello</filename> is untouched, but
   6.108 -	a new revision has been added.  By referring to <xref
   6.109 -	  linkend="fig:tour-merge:sep-repos"/>, we can see that the
   6.110 -	<emphasis>changeset ID</emphasis> remains the same in the new
   6.111 -	repository, but the <emphasis>revision number</emphasis> has
   6.112 -	changed.  (This, incidentally, is a fine example of why it's
   6.113 -	not safe to use revision numbers when discussing changesets.)
   6.114 -	We can view the heads in a repository using the <command
   6.115 -	  role="hg-cmd">hg heads</command> command.</para>
   6.116 -
   6.117 -      &interaction.tour.merge.heads;
   6.118 -    </sect2>
   6.119 -
   6.120 -    <sect2>
   6.121 -      <title>Performing the merge</title>
   6.122 -
   6.123 -      <para id="x_344">What happens if we try to use the normal <command
   6.124 -	  role="hg-cmd">hg update</command> command to update to the
   6.125 -	new tip?</para>
   6.126 -
   6.127 -      &interaction.tour.merge.update;
   6.128 -
   6.129 -      <para id="x_345">Mercurial is telling us that the <command
   6.130 -	  role="hg-cmd">hg update</command> command won't do a merge;
   6.131 -	it won't update the working directory when it thinks we might
   6.132 -	want to do a merge, unless we force it to do so.
   6.133 -	(Incidentally, forcing the update with <command>hg update
   6.134 -	  -C</command> would revert any uncommitted changes in the
   6.135 -	working directory.)</para>
   6.136 -
   6.137 -      <para id="x_723">To start a merge between the two heads, we use the
   6.138 -	<command role="hg-cmd">hg merge</command> command.</para>
   6.139 -
   6.140 -      &interaction.tour.merge.merge;
   6.141 -
   6.142 -      <para id="x_347">We resolve the contents of <filename>hello.c</filename>
   6.143 -
   6.144 -This updates the working directory so that it
   6.145 -	contains changes from <emphasis>both</emphasis> heads, which
   6.146 -	is reflected in both the output of <command role="hg-cmd">hg
   6.147 -	  parents</command> and the contents of
   6.148 -	<filename>hello.c</filename>.</para>
   6.149 -
   6.150 -      &interaction.tour.merge.parents;
   6.151 -    </sect2>
   6.152 -
   6.153 -    <sect2>
   6.154 -      <title>Committing the results of the merge</title>
   6.155 -
   6.156 -      <para id="x_348">Whenever we've done a merge, <command role="hg-cmd">hg
   6.157 -	  parents</command> will display two parents until we <command
   6.158 -	  role="hg-cmd">hg commit</command> the results of the
   6.159 -	  merge.</para>
   6.160 -
   6.161 -	&interaction.tour.merge.commit;
   6.162 -
   6.163 -      <para id="x_349">We now have a new tip revision; notice that it has
   6.164 -	<emphasis>both</emphasis> of our former heads as its parents.
   6.165 -	These are the same revisions that were previously displayed by
   6.166 -	<command role="hg-cmd">hg parents</command>.</para>
   6.167 -
   6.168 -      &interaction.tour.merge.tip;
   6.169 -
   6.170 -      <para id="x_34a">In <xref
   6.171 -	  linkend="fig:tour-merge:merge"/>, you can see a
   6.172 -	representation of what happens to the working directory during
   6.173 -	the merge, and how this affects the repository when the commit
   6.174 -	happens.  During the merge, the working directory has two
   6.175 -	parent changesets, and these become the parents of the new
   6.176 -	changeset.</para>
   6.177 -
   6.178 -      <figure id="fig:tour-merge:merge">
   6.179 -	<title>Working directory and repository during merge, and
   6.180 -	  following commit</title>
   6.181 -	<mediaobject>
   6.182 -	  <imageobject>
   6.183 -	    <imagedata fileref="figs/tour-merge-merge.png"/>
   6.184 -	  </imageobject>
   6.185 -	  <textobject><phrase>XXX add text</phrase></textobject>
   6.186 -	</mediaobject>
   6.187 -      </figure>
   6.188 -
   6.189 -      <para id="x_69c">We sometimes talk about a merge having
   6.190 -	<emphasis>sides</emphasis>: the left side is the first parent
   6.191 -	in the output of <command role="hg-cmd">hg parents</command>,
   6.192 -	and the right side is the second.  If the working directory
   6.193 -	was at e.g. revision 5 before we began a merge, that revision
   6.194 -	will become the left side of the merge.</para>
   6.195 -    </sect2>
   6.196 -  </sect1>
   6.197 -
   6.198 -  <sect1>
   6.199 -    <title>Merging conflicting changes</title>
   6.200 -
   6.201 -    <para id="x_34b">Most merges are simple affairs, but sometimes you'll find
   6.202 -      yourself merging changes where each side modifies the same portions
   6.203 -      of the same files.  Unless both modifications are identical,
   6.204 -      this results in a <emphasis>conflict</emphasis>, where you have
   6.205 -      to decide how to reconcile the different changes into something
   6.206 -      coherent.</para>
   6.207 -
   6.208 -    <figure id="fig:tour-merge:conflict">
   6.209 -      <title>Conflicting changes to a document</title>
   6.210 -      <mediaobject>
   6.211 -	<imageobject><imagedata fileref="figs/tour-merge-conflict.png"/></imageobject>
   6.212 -	<textobject><phrase>XXX add text</phrase></textobject>
   6.213 -      </mediaobject>
   6.214 -    </figure>
   6.215 -
   6.216 -    <para id="x_34d"><xref linkend="fig:tour-merge:conflict"/> illustrates
   6.217 -      an instance of two conflicting changes to a document.  We
   6.218 -      started with a single version of the file; then we made some
   6.219 -      changes; while someone else made different changes to the same
   6.220 -      text.  Our task in resolving the conflicting changes is to
   6.221 -      decide what the file should look like.</para>
   6.222 -
   6.223 -    <para id="x_34e">Mercurial doesn't have a built-in facility for handling
   6.224 -      conflicts. Instead, it runs an external program, usually one
   6.225 -      that displays some kind of graphical conflict resolution
   6.226 -      interface.  By default, Mercurial tries to find one of several
   6.227 -      different merging tools that are likely to be installed on your
   6.228 -      system.  It first tries a few fully automatic merging tools; if
   6.229 -      these don't succeed (because the resolution process requires
   6.230 -      human guidance) or aren't present, it tries a few
   6.231 -      different graphical merging tools.</para>
   6.232 -
   6.233 -    <para id="x_34f">It's also possible to get Mercurial to run a
   6.234 -      specific program or script, by setting the
   6.235 -      <envar>HGMERGE</envar> environment variable to the name of your
   6.236 -      preferred program.</para>
   6.237 -
   6.238 -    <sect2>
   6.239 -      <title>Using a graphical merge tool</title>
   6.240 -
   6.241 -      <para id="x_350">My preferred graphical merge tool is
   6.242 -	<command>kdiff3</command>, which I'll use to describe the
   6.243 -	features that are common to graphical file merging tools.  You
   6.244 -	can see a screenshot of <command>kdiff3</command> in action in
   6.245 -	<xref linkend="fig:tour-merge:kdiff3"/>.  The kind of
   6.246 -	merge it is performing is called a <emphasis>three-way
   6.247 -	  merge</emphasis>, because there are three different versions
   6.248 -	of the file of interest to us.  The tool thus splits the upper
   6.249 -	portion of the window into three panes:</para>
   6.250 -      <itemizedlist>
   6.251 -	<listitem><para id="x_351">At the left is the <emphasis>base</emphasis>
   6.252 -	    version of the file, i.e. the most recent version from
   6.253 -	    which the two versions we're trying to merge are
   6.254 -	    descended.</para>
   6.255 -	</listitem>
   6.256 -	<listitem><para id="x_352">In the middle is <quote>our</quote> version of
   6.257 -	    the file, with the contents that we modified.</para>
   6.258 -	</listitem>
   6.259 -	<listitem><para id="x_353">On the right is <quote>their</quote> version
   6.260 -	    of the file, the one that from the changeset that we're
   6.261 -	    trying to merge with.</para>
   6.262 -	</listitem></itemizedlist>
   6.263 -      <para id="x_354">In the pane below these is the current
   6.264 -	<emphasis>result</emphasis> of the merge. Our task is to
   6.265 -	replace all of the red text, which indicates unresolved
   6.266 -	conflicts, with some sensible merger of the
   6.267 -	<quote>ours</quote> and <quote>theirs</quote> versions of the
   6.268 -	file.</para>
   6.269 -
   6.270 -      <para id="x_355">All four of these panes are <emphasis>locked
   6.271 -	  together</emphasis>; if we scroll vertically or horizontally
   6.272 -	in any of them, the others are updated to display the
   6.273 -	corresponding sections of their respective files.</para>
   6.274 -
   6.275 -      <figure id="fig:tour-merge:kdiff3">
   6.276 -	<title>Using <command>kdiff3</command> to merge versions of a
   6.277 -	  file</title>
   6.278 -	<mediaobject>
   6.279 -	  <imageobject>
   6.280 -	    <imagedata width="100%" fileref="figs/kdiff3.png"/></imageobject>
   6.281 -	  <textobject>
   6.282 -	    <phrase>XXX add text</phrase>
   6.283 -	  </textobject>
   6.284 -	</mediaobject>
   6.285 -      </figure>
   6.286 -
   6.287 -      <para id="x_357">For each conflicting portion of the file, we can choose to
   6.288 -	resolve the conflict using some combination of text from the
   6.289 -	base version, ours, or theirs.  We can also manually edit the
   6.290 -	merged file at any time, in case we need to make further
   6.291 -	modifications.</para>
   6.292 -
   6.293 -      <para id="x_358">There are <emphasis>many</emphasis> file merging tools
   6.294 -	available, too many to cover here.  They vary in which
   6.295 -	platforms they are available for, and in their particular
   6.296 -	strengths and weaknesses.  Most are tuned for merging files
   6.297 -	containing plain text, while a few are aimed at specialised
   6.298 -	file formats (generally XML).</para>
   6.299 -    </sect2>
   6.300 -
   6.301 -    <sect2>
   6.302 -      <title>A worked example</title>
   6.303 -
   6.304 -      <para id="x_359">In this example, we will reproduce the file modification
   6.305 -	history of <xref linkend="fig:tour-merge:conflict"/>
   6.306 -	above.  Let's begin by creating a repository with a base
   6.307 -	version of our document.</para>
   6.308 -
   6.309 -      &interaction.tour-merge-conflict.wife;
   6.310 -
   6.311 -      <para id="x_35a">We'll clone the repository and make a change to the
   6.312 -	file.</para>
   6.313 -
   6.314 -      &interaction.tour-merge-conflict.cousin;
   6.315 -
   6.316 -      <para id="x_35b">And another clone, to simulate someone else making a
   6.317 -	change to the file. (This hints at the idea that it's not all
   6.318 -	that unusual to merge with yourself when you isolate tasks in
   6.319 -	separate repositories, and indeed to find and resolve
   6.320 -	conflicts while doing so.)</para>
   6.321 -
   6.322 -      &interaction.tour-merge-conflict.son;
   6.323 -
   6.324 -      <para id="x_35c">Having created two
   6.325 -	different versions of the file, we'll set up an environment
   6.326 -	suitable for running our merge.</para>
   6.327 -
   6.328 -      &interaction.tour-merge-conflict.pull;
   6.329 -
   6.330 -      <para id="x_35d">In this example, I'll set
   6.331 -	<envar>HGMERGE</envar> to tell Mercurial to use the
   6.332 -	non-interactive <command>merge</command> command.  This is
   6.333 -	bundled with many Unix-like systems. (If you're following this
   6.334 -	example on your computer, don't bother setting
   6.335 -	<envar>HGMERGE</envar>.  You'll get dropped into a GUI file
   6.336 -	merge tool instead, which is much preferable.)</para>
   6.337 -
   6.338 -      &interaction.tour-merge-conflict.merge;
   6.339 -
   6.340 -      <para id="x_35f">Because <command>merge</command> can't resolve the
   6.341 -	conflicting changes, it leaves <emphasis>merge
   6.342 -	  markers</emphasis> inside the file that has conflicts,
   6.343 -	indicating which lines have conflicts, and whether they came
   6.344 -	from our version of the file or theirs.</para>
   6.345 -
   6.346 -      <para id="x_360">Mercurial can tell from the way <command>merge</command>
   6.347 -	exits that it wasn't able to merge successfully, so it tells
   6.348 -	us what commands we'll need to run if we want to redo the
   6.349 -	merging operation.  This could be useful if, for example, we
   6.350 -	were running a graphical merge tool and quit because we were
   6.351 -	confused or realised we had made a mistake.</para>
   6.352 -
   6.353 -      <para id="x_361">If automatic or manual merges fail, there's nothing to
   6.354 -	prevent us from <quote>fixing up</quote> the affected files
   6.355 -	ourselves, and committing the results of our merge:</para>
   6.356 -
   6.357 -      &interaction.tour-merge-conflict.commit;
   6.358 -
   6.359 -      <note>
   6.360 -	<title>Where is the <command>hg resolve</command> command?</title>
   6.361 -
   6.362 -	<para id="x_724">The <command>hg resolve</command> command was introduced
   6.363 -	  in Mercurial 1.1, which was released in December 2008. If
   6.364 -	  you are using an older version of Mercurial (run <command>hg
   6.365 -	    version</command> to see), this command will not be
   6.366 -	  present.  If your version of Mercurial is older than 1.1,
   6.367 -	  you should strongly consider upgrading to a newer version
   6.368 -	  before trying to tackle complicated merges.</para>
   6.369 -      </note>
   6.370 -    </sect2>
   6.371 -  </sect1>
   6.372 -
   6.373 -  <sect1 id="sec:tour-merge:fetch">
   6.374 -    <title>Simplifying the pull-merge-commit sequence</title>
   6.375 -
   6.376 -    <para id="x_362">The process of merging changes as outlined above is
   6.377 -      straightforward, but requires running three commands in
   6.378 -      sequence.</para>
   6.379 -    <programlisting>hg pull -u
   6.380 -hg merge
   6.381 -hg commit -m 'Merged remote changes'</programlisting>
   6.382 -    <para id="x_363">In the case of the final commit, you also need to enter a
   6.383 -      commit message, which is almost always going to be a piece of
   6.384 -      uninteresting <quote>boilerplate</quote> text.</para>
   6.385 -
   6.386 -    <para id="x_364">It would be nice to reduce the number of steps needed, if
   6.387 -      this were possible.  Indeed, Mercurial is distributed with an
   6.388 -      extension called <literal role="hg-ext">fetch</literal> that
   6.389 -      does just this.</para>
   6.390 -
   6.391 -    <para id="x_365">Mercurial provides a flexible extension mechanism that lets
   6.392 -      people extend its functionality, while keeping the core of
   6.393 -      Mercurial small and easy to deal with.  Some extensions add new
   6.394 -      commands that you can use from the command line, while others
   6.395 -      work <quote>behind the scenes,</quote> for example adding
   6.396 -      capabilities to Mercurial's built-in server mode.</para>
   6.397 -
   6.398 -    <para id="x_366">The <literal role="hg-ext">fetch</literal>
   6.399 -      extension adds a new command called, not surprisingly, <command
   6.400 -	role="hg-cmd">hg fetch</command>.  This extension acts as a
   6.401 -      combination of <command role="hg-cmd">hg pull -u</command>,
   6.402 -      <command role="hg-cmd">hg merge</command> and <command
   6.403 -	role="hg-cmd">hg commit</command>.  It begins by pulling
   6.404 -      changes from another repository into the current repository.  If
   6.405 -      it finds that the changes added a new head to the repository, it
   6.406 -      updates to the new head, begins a merge, then (if the merge
   6.407 -      succeeded) commits the result of the merge with an
   6.408 -      automatically-generated commit message.  If no new heads were
   6.409 -      added, it updates the working directory to the new tip
   6.410 -      changeset.</para>
   6.411 -
   6.412 -    <para id="x_367">Enabling the <literal
   6.413 -	role="hg-ext">fetch</literal> extension is easy.  Edit the
   6.414 -      <filename role="special">.hgrc</filename> file in your home
   6.415 -      directory, and either go to the <literal
   6.416 -	role="rc-extensions">extensions</literal> section or create an
   6.417 -      <literal role="rc-extensions">extensions</literal> section. Then
   6.418 -      add a line that simply reads
   6.419 -      <quote><literal>fetch=</literal></quote>.</para>
   6.420 -
   6.421 -    <programlisting>[extensions]
   6.422 -fetch =</programlisting>
   6.423 -
   6.424 -    <para id="x_368">(Normally, the right-hand side of the
   6.425 -      <quote><literal>=</literal></quote> would indicate where to find
   6.426 -      the extension, but since the <literal
   6.427 -	role="hg-ext">fetch</literal> extension is in the standard
   6.428 -      distribution, Mercurial knows where to search for it.)</para>
   6.429 -  </sect1>
   6.430 -
   6.431 -  <sect1>
   6.432 -    <title>Renaming, copying, and merging</title>
   6.433 -
   6.434 -    <para id="x_729">During the life of a project, we will often want to change
   6.435 -      the layout of its files and directories. This can be as simple
   6.436 -      as renaming a single file, or as complex as restructuring the
   6.437 -      entire hierarchy of files within the project.</para>
   6.438 -
   6.439 -    <para id="x_72a">Mercurial supports these kinds of complex changes fluently,
   6.440 -      provided we tell it what we're doing.  If we want to rename a
   6.441 -      file, we should use the <command>hg rename</command><footnote>
   6.442 -	<para id="x_72b">If you're a Unix user, you'll be glad to know that the
   6.443 -	  <command>hg rename</command> command can be abbreviated as
   6.444 -	  <command>hg mv</command>.</para>
   6.445 -      </footnote> command to rename it, so that Mercurial can do the
   6.446 -      right thing later when we merge.</para>
   6.447 -
   6.448 -    <para id="x_72c">We will cover the use of these commands in more detail in
   6.449 -      <xref linkend="chap:daily.copy"/>.</para>
   6.450 -  </sect1>
   6.451 -</chapter>
   6.452 -
   6.453 -<!--
   6.454 -local variables: 
   6.455 -sgml-parent-document: ("00book.xml" "book" "chapter")
   6.456 -end:
   6.457 --->