1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/en/ch01-tour-basic.xml	Thu Mar 19 20:54:12 2009 -0700
     1.3 @@ -0,0 +1,860 @@
     1.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5 +
     1.6 +<chapter id="chap:tour-basic">
     1.7 +  <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?>
     1.8 +  <title>A tour of Mercurial: the basics</title>
     1.9 +
    1.10 +  <sect1 id="sec:tour:install">
    1.11 +    <title>Installing Mercurial on your system</title>
    1.12 +
    1.13 +    <para>Prebuilt binary packages of Mercurial are available for
    1.14 +      every popular operating system.  These make it easy to start
    1.15 +      using Mercurial on your computer immediately.</para>
    1.16 +
    1.17 +    <sect2>
    1.18 +      <title>Linux</title>
    1.19 +
    1.20 +      <para>Because each Linux distribution has its own packaging
    1.21 +	tools, policies, and rate of development, it's difficult to
    1.22 +	give a comprehensive set of instructions on how to install
    1.23 +	Mercurial binaries.  The version of Mercurial that you will
    1.24 +	end up with can vary depending on how active the person is who
    1.25 +	maintains the package for your distribution.</para>
    1.26 +
    1.27 +      <para>To keep things simple, I will focus on installing
    1.28 +	Mercurial from the command line under the most popular Linux
    1.29 +	distributions.  Most of these distributions provide graphical
    1.30 +	package managers that will let you install Mercurial with a
    1.31 +	single click; the package name to look for is
    1.32 +	<literal>mercurial</literal>.</para>
    1.33 +
    1.34 +      <itemizedlist>
    1.35 +	<listitem><para>Debian:</para>
    1.36 +	  <programlisting>apt-get install mercurial</programlisting></listitem>
    1.37 +	<listitem><para>Fedora Core:</para>
    1.38 +	  <programlisting>yum install mercurial</programlisting></listitem>
    1.39 +	<listitem><para>Gentoo:</para>
    1.40 +	  <programlisting>emerge mercurial</programlisting></listitem>
    1.41 +	<listitem><para>OpenSUSE:</para>
    1.42 +	  <programlisting>yum install mercurial</programlisting></listitem>
    1.43 +	<listitem><para>Ubuntu: Ubuntu's Mercurial package is based on
    1.44 +	    Debian's.  To install it, run the following
    1.45 +	    command.</para>
    1.46 +	  <programlisting>apt-get install mercurial</programlisting></listitem>
    1.47 +      </itemizedlist>
    1.48 +
    1.49 +    </sect2>
    1.50 +    <sect2>
    1.51 +      <title>Solaris</title>
    1.52 +
    1.53 +      <para>SunFreeWare, at <ulink
    1.54 +	  url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 
    1.55 +	is a good source for a large number of pre-built Solaris
    1.56 +	packages for 32 and 64 bit Intel and Sparc architectures,
    1.57 +	including current versions of Mercurial.</para>
    1.58 +
    1.59 +    </sect2>
    1.60 +    <sect2>
    1.61 +      <title>Mac OS X</title>
    1.62 +
    1.63 +      <para>Lee Cantey publishes an installer of Mercurial for Mac OS
    1.64 +	X at <ulink
    1.65 +	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 
    1.66 +	This package works on both Intel- and Power-based Macs. Before
    1.67 +	you can use it, you must install a compatible version of
    1.68 +	Universal MacPython <citation>web:macpython</citation>. This
    1.69 +	is easy to do; simply follow the instructions on Lee's
    1.70 +	site.</para>
    1.71 +
    1.72 +      <para>It's also possible to install Mercurial using Fink or
    1.73 +	MacPorts, two popular free package managers for Mac OS X.  If
    1.74 +	you have Fink, use <command>sudo apt-get install
    1.75 +	  mercurial-py25</command>.  If MacPorts, <command>sudo port
    1.76 +	  install mercurial</command>.</para>
    1.77 +
    1.78 +    </sect2>
    1.79 +    <sect2>
    1.80 +      <title>Windows</title>
    1.81 +
    1.82 +      <para>Lee Cantey publishes an installer of Mercurial for Windows
    1.83 +	at <ulink
    1.84 +	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 
    1.85 +	This package has no external dependencies; it <quote>just
    1.86 +	  works</quote>.</para>
    1.87 +
    1.88 +      <note>
    1.89 +	<para>  The Windows version of Mercurial does not
    1.90 +	  automatically convert line endings between Windows and Unix
    1.91 +	  styles.  If you want to share work with Unix users, you must
    1.92 +	  do a little additional configuration work. XXX Flesh this
    1.93 +	  out.</para>
    1.94 +      </note>
    1.95 +
    1.96 +    </sect2>
    1.97 +  </sect1>
    1.98 +  <sect1>
    1.99 +    <title>Getting started</title>
   1.100 +
   1.101 +    <para>To begin, we'll use the <command role="hg-cmd">hg
   1.102 +	version</command> command to find out whether Mercurial is
   1.103 +      actually installed properly.  The actual version information
   1.104 +      that it prints isn't so important; it's whether it prints
   1.105 +      anything at all that we care about.</para>
   1.106 +
   1.107 +    &interaction.tour.version;
   1.108 +
   1.109 +    <sect2>
   1.110 +      <title>Built-in help</title>
   1.111 +
   1.112 +      <para>Mercurial provides a built-in help system.  This is
   1.113 +	  invaluable for those times when you find yourself stuck
   1.114 +	  trying to remember how to run a command.  If you are
   1.115 +	  completely stuck, simply run <command role="hg-cmd">hg
   1.116 +	    help</command>; it will print a brief list of commands,
   1.117 +	  along with a description of what each does.  If you ask for
   1.118 +	  help on a specific command (as below), it prints more
   1.119 +	  detailed information.</para>
   1.120 +
   1.121 +	&interaction.tour.help;
   1.122 +
   1.123 +	<para>For a more impressive level of detail (which you won't
   1.124 +	  usually need) run <command role="hg-cmd">hg help <option
   1.125 +	      role="hg-opt-global">-v</option></command>.  The <option
   1.126 +	    role="hg-opt-global">-v</option> option is short for
   1.127 +	  <option role="hg-opt-global">--verbose</option>, and tells
   1.128 +	  Mercurial to print more information than it usually
   1.129 +	  would.</para>
   1.130 +
   1.131 +    </sect2>
   1.132 +  </sect1>
   1.133 +  <sect1>
   1.134 +    <title>Working with a repository</title>
   1.135 +
   1.136 +    <para>In Mercurial, everything happens inside a
   1.137 +      <emphasis>repository</emphasis>.  The repository for a project
   1.138 +      contains all of the files that <quote>belong to</quote> that
   1.139 +      project, along with a historical record of the project's
   1.140 +      files.</para>
   1.141 +
   1.142 +    <para>There's nothing particularly magical about a repository; it
   1.143 +      is simply a directory tree in your filesystem that Mercurial
   1.144 +      treats as special. You can rename or delete a repository any
   1.145 +      time you like, using either the command line or your file
   1.146 +      browser.</para>
   1.147 +
   1.148 +    <sect2>
   1.149 +      <title>Making a local copy of a repository</title>
   1.150 +
   1.151 +      <para><emphasis>Copying</emphasis> a repository is just a little
   1.152 +	bit special.  While you could use a normal file copying
   1.153 +	command to make a copy of a repository, it's best to use a
   1.154 +	built-in command that Mercurial provides.  This command is
   1.155 +	called <command role="hg-cmd">hg clone</command>, because it
   1.156 +	creates an identical copy of an existing repository.</para>
   1.157 +
   1.158 +      &interaction.tour.clone;
   1.159 +
   1.160 +      <para>If our clone succeeded, we should now have a local
   1.161 +	directory called <filename class="directory">hello</filename>.
   1.162 +	This directory will contain some files.</para>
   1.163 +
   1.164 +      &interaction.tour.ls;
   1.165 +
   1.166 +      <para>These files have the same contents and history in our
   1.167 +	repository as they do in the repository we cloned.</para>
   1.168 +
   1.169 +      <para>Every Mercurial repository is complete, self-contained,
   1.170 +	and independent.  It contains its own private copy of a
   1.171 +	project's files and history.  A cloned repository remembers
   1.172 +	the location of the repository it was cloned from, but it does
   1.173 +	not communicate with that repository, or any other, unless you
   1.174 +	tell it to.</para>
   1.175 +
   1.176 +      <para>What this means for now is that we're free to experiment
   1.177 +	with our repository, safe in the knowledge that it's a private
   1.178 +	<quote>sandbox</quote> that won't affect anyone else.</para>
   1.179 +
   1.180 +    </sect2>
   1.181 +    <sect2>
   1.182 +      <title>What's in a repository?</title>
   1.183 +
   1.184 +      <para>When we take a more detailed look inside a repository, we
   1.185 +	can see that it contains a directory named <filename
   1.186 +	  class="directory">.hg</filename>.  This is where Mercurial
   1.187 +	keeps all of its metadata for the repository.</para>
   1.188 +
   1.189 +      &interaction.tour.ls-a;
   1.190 +
   1.191 +      <para>The contents of the <filename
   1.192 +	  class="directory">.hg</filename> directory and its
   1.193 +	subdirectories are private to Mercurial.  Every other file and
   1.194 +	directory in the repository is yours to do with as you
   1.195 +	please.</para>
   1.196 +
   1.197 +      <para>To introduce a little terminology, the <filename
   1.198 +	  class="directory">.hg</filename> directory is the
   1.199 +	<quote>real</quote> repository, and all of the files and
   1.200 +	directories that coexist with it are said to live in the
   1.201 +	<emphasis>working directory</emphasis>.  An easy way to
   1.202 +	remember the distinction is that the
   1.203 +	<emphasis>repository</emphasis> contains the
   1.204 +	<emphasis>history</emphasis> of your project, while the
   1.205 +	<emphasis>working directory</emphasis> contains a
   1.206 +	<emphasis>snapshot</emphasis> of your project at a particular
   1.207 +	point in history.</para>
   1.208 +
   1.209 +    </sect2>
   1.210 +  </sect1>
   1.211 +  <sect1>
   1.212 +    <title>A tour through history</title>
   1.213 +
   1.214 +    <para>One of the first things we might want to do with a new,
   1.215 +      unfamiliar repository is understand its history.  The <command
   1.216 +	role="hg-cmd">hg log</command> command gives us a view of
   1.217 +      history.</para>
   1.218 +
   1.219 +    &interaction.tour.log;
   1.220 +
   1.221 +    <para>By default, this command prints a brief paragraph of output
   1.222 +      for each change to the project that was recorded.  In Mercurial
   1.223 +      terminology, we call each of these recorded events a
   1.224 +      <emphasis>changeset</emphasis>, because it can contain a record
   1.225 +      of changes to several files.</para>
   1.226 +
   1.227 +    <para>The fields in a record of output from <command
   1.228 +	role="hg-cmd">hg log</command> are as follows.</para>
   1.229 +    <itemizedlist>
   1.230 +      <listitem><para><literal>changeset</literal>: This field has the
   1.231 +	  format of a number, followed by a colon, followed by a
   1.232 +	  hexadecimal string.  These are
   1.233 +	  <emphasis>identifiers</emphasis> for the changeset.  There
   1.234 +	  are two identifiers because the number is shorter and easier
   1.235 +	  to type than the hex string.</para></listitem>
   1.236 +      <listitem><para><literal>user</literal>: The identity of the
   1.237 +	  person who created the changeset.  This is a free-form
   1.238 +	  field, but it most often contains a person's name and email
   1.239 +	  address.</para></listitem>
   1.240 +      <listitem><para><literal>date</literal>: The date and time on
   1.241 +	  which the changeset was created, and the timezone in which
   1.242 +	  it was created.  (The date and time are local to that
   1.243 +	  timezone; they display what time and date it was for the
   1.244 +	  person who created the changeset.)</para></listitem>
   1.245 +      <listitem><para><literal>summary</literal>: The first line of
   1.246 +	  the text message that the creator of the changeset entered
   1.247 +	  to describe the changeset.</para></listitem></itemizedlist>
   1.248 +    <para>The default output printed by <command role="hg-cmd">hg
   1.249 +	log</command> is purely a summary; it is missing a lot of
   1.250 +      detail.</para>
   1.251 +
   1.252 +    <para>Figure <xref linkend="fig:tour-basic:history"/> provides a
   1.253 +      graphical representation of the history of the <filename
   1.254 +	class="directory">hello</filename> repository, to make it a
   1.255 +      little easier to see which direction history is
   1.256 +      <quote>flowing</quote> in.  We'll be returning to this figure
   1.257 +      several times in this chapter and the chapter that
   1.258 +      follows.</para>
   1.259 +
   1.260 +    <informalfigure id="fig:tour-basic:history">
   1.261 +      <mediaobject>
   1.262 +	<imageobject><imagedata fileref="tour-history"/></imageobject>
   1.263 +	<textobject><phrase>XXX add text</phrase></textobject>
   1.264 +	<caption><para>Graphical history of the <filename
   1.265 +	      class="directory">hello</filename>
   1.266 +	    repository</para></caption>
   1.267 +      </mediaobject>
   1.268 +    </informalfigure>
   1.269 +
   1.270 +    <sect2>
   1.271 +      <title>Changesets, revisions, and talking to other
   1.272 +	people</title>
   1.273 +
   1.274 +      <para>As English is a notoriously sloppy language, and computer
   1.275 +	science has a hallowed history of terminological confusion
   1.276 +	(why use one term when four will do?), revision control has a
   1.277 +	variety of words and phrases that mean the same thing.  If you
   1.278 +	are talking about Mercurial history with other people, you
   1.279 +	will find that the word <quote>changeset</quote> is often
   1.280 +	compressed to <quote>change</quote> or (when written)
   1.281 +	<quote>cset</quote>, and sometimes a changeset is referred to
   1.282 +	as a <quote>revision</quote> or a <quote>rev</quote>.</para>
   1.283 +
   1.284 +      <para>While it doesn't matter what <emphasis>word</emphasis> you
   1.285 +	use to refer to the concept of <quote>a changeset</quote>, the
   1.286 +	<emphasis>identifier</emphasis> that you use to refer to
   1.287 +	<quote>a <emphasis>specific</emphasis> changeset</quote> is of
   1.288 +	great importance. Recall that the <literal>changeset</literal>
   1.289 +	field in the output from <command role="hg-cmd">hg
   1.290 +	  log</command> identifies a changeset using both a number and
   1.291 +	a hexadecimal string.</para>
   1.292 +      <itemizedlist>
   1.293 +	<listitem><para>The revision number is <emphasis>only valid in
   1.294 +	      that repository</emphasis>,</para></listitem>
   1.295 +	<listitem><para>while the hex string is the
   1.296 +	    <emphasis>permanent, unchanging identifier</emphasis> that
   1.297 +	    will always identify that exact changeset in
   1.298 +	    <emphasis>every</emphasis> copy of the
   1.299 +	    repository.</para></listitem></itemizedlist>
   1.300 +      <para>This distinction is important.  If you send someone an
   1.301 +	email talking about <quote>revision 33</quote>, there's a high
   1.302 +	likelihood that their revision 33 will <emphasis>not be the
   1.303 +	  same</emphasis> as yours.  The reason for this is that a
   1.304 +	revision number depends on the order in which changes arrived
   1.305 +	in a repository, and there is no guarantee that the same
   1.306 +	changes will happen in the same order in different
   1.307 +	repositories. Three changes $a,b,c$ can easily appear in one
   1.308 +	repository as $0,1,2$, while in another as $1,0,2$.</para>
   1.309 +
   1.310 +      <para>Mercurial uses revision numbers purely as a convenient
   1.311 +	shorthand.  If you need to discuss a changeset with someone,
   1.312 +	or make a record of a changeset for some other reason (for
   1.313 +	example, in a bug report), use the hexadecimal
   1.314 +	identifier.</para>
   1.315 +
   1.316 +    </sect2>
   1.317 +    <sect2>
   1.318 +      <title>Viewing specific revisions</title>
   1.319 +
   1.320 +      <para>To narrow the output of <command role="hg-cmd">hg
   1.321 +	  log</command> down to a single revision, use the <option
   1.322 +	  role="hg-opt-log">-r</option> (or <option
   1.323 +	  role="hg-opt-log">--rev</option>) option.  You can use
   1.324 +	either a revision number or a long-form changeset identifier,
   1.325 +	and you can provide as many revisions as you want.</para>
   1.326 +
   1.327 +      &interaction.tour.log-r;
   1.328 +
   1.329 +      <para>If you want to see the history of several revisions
   1.330 +	without having to list each one, you can use <emphasis>range
   1.331 +	  notation</emphasis>; this lets you express the idea <quote>I
   1.332 +	  want all revisions between <literal>abc</literal> and
   1.333 +	  <literal>def</literal>, inclusive</quote>.</para>
   1.334 +      
   1.335 +	&interaction.tour.log.range;
   1.336 +
   1.337 +      <para>Mercurial also honours the order in which you specify
   1.338 +	revisions, so <command role="hg-cmd">hg log -r 2:4</command>
   1.339 +	prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
   1.340 +	  4:2</command> prints 4, 3, and 2.</para>
   1.341 +
   1.342 +    </sect2>
   1.343 +    <sect2>
   1.344 +      <title>More detailed information</title>
   1.345 +
   1.346 +      <para>While the summary information printed by <command
   1.347 +	  role="hg-cmd">hg log</command> is useful if you already know
   1.348 +	what you're looking for, you may need to see a complete
   1.349 +	description of the change, or a list of the files changed, if
   1.350 +	you're trying to decide whether a changeset is the one you're
   1.351 +	looking for. The <command role="hg-cmd">hg log</command>
   1.352 +	command's <option role="hg-opt-global">-v</option> (or <option
   1.353 +	  role="hg-opt-global">--verbose</option>) option gives you
   1.354 +	this extra detail.</para>
   1.355 +
   1.356 +      &interaction.tour.log-v;
   1.357 +
   1.358 +      <para>If you want to see both the description and content of a
   1.359 +	change, add the <option role="hg-opt-log">-p</option> (or
   1.360 +	<option role="hg-opt-log">--patch</option>) option.  This
   1.361 +	displays the content of a change as a <emphasis>unified
   1.362 +	  diff</emphasis> (if you've never seen a unified diff before,
   1.363 +	see section <xref linkend="sec:mq:patch"/> for an
   1.364 +	overview).</para>
   1.365 +
   1.366 +      &interaction.tour.log-vp;
   1.367 +
   1.368 +    </sect2>
   1.369 +  </sect1>
   1.370 +  <sect1>
   1.371 +    <title>All about command options</title>
   1.372 +
   1.373 +    <para>Let's take a brief break from exploring Mercurial commands
   1.374 +      to discuss a pattern in the way that they work; you may find
   1.375 +      this useful to keep in mind as we continue our tour.</para>
   1.376 +
   1.377 +    <para>Mercurial has a consistent and straightforward approach to
   1.378 +      dealing with the options that you can pass to commands.  It
   1.379 +      follows the conventions for options that are common to modern
   1.380 +      Linux and Unix systems.</para>
   1.381 +    <itemizedlist>
   1.382 +      <listitem><para>Every option has a long name.  For example, as
   1.383 +	  we've already seen, the <command role="hg-cmd">hg
   1.384 +	    log</command> command accepts a <option
   1.385 +	    role="hg-opt-log">--rev</option> option.</para></listitem>
   1.386 +      <listitem><para>Most options have short names, too.  Instead of
   1.387 +	  <option role="hg-opt-log">--rev</option>, we can use <option
   1.388 +	    role="hg-opt-log">-r</option>.  (The reason that some
   1.389 +	  options don't have short names is that the options in
   1.390 +	  question are rarely used.)</para></listitem>
   1.391 +      <listitem><para>Long options start with two dashes (e.g. <option
   1.392 +	    role="hg-opt-log">--rev</option>), while short options
   1.393 +	  start with one (e.g. <option
   1.394 +	    role="hg-opt-log">-r</option>).</para></listitem>
   1.395 +      <listitem><para>Option naming and usage is consistent across
   1.396 +	  commands.  For example, every command that lets you specify
   1.397 +	  a changeset ID or revision number accepts both <option
   1.398 +	    role="hg-opt-log">-r</option> and <option
   1.399 +	    role="hg-opt-log">--rev</option>
   1.400 +	  arguments.</para></listitem></itemizedlist>
   1.401 +    <para>In the examples throughout this book, I use short options
   1.402 +      instead of long.  This just reflects my own preference, so don't
   1.403 +      read anything significant into it.</para>
   1.404 +
   1.405 +    <para>Most commands that print output of some kind will print more
   1.406 +      output when passed a <option role="hg-opt-global">-v</option>
   1.407 +      (or <option role="hg-opt-global">--verbose</option>) option, and
   1.408 +      less when passed <option role="hg-opt-global">-q</option> (or
   1.409 +      <option role="hg-opt-global">--quiet</option>).</para>
   1.410 +
   1.411 +  </sect1>
   1.412 +  <sect1>
   1.413 +    <title>Making and reviewing changes</title>
   1.414 +
   1.415 +    <para>Now that we have a grasp of viewing history in Mercurial,
   1.416 +      let's take a look at making some changes and examining
   1.417 +      them.</para>
   1.418 +
   1.419 +    <para>The first thing we'll do is isolate our experiment in a
   1.420 +      repository of its own.  We use the <command role="hg-cmd">hg
   1.421 +	clone</command> command, but we don't need to clone a copy of
   1.422 +      the remote repository.  Since we already have a copy of it
   1.423 +      locally, we can just clone that instead.  This is much faster
   1.424 +      than cloning over the network, and cloning a local repository
   1.425 +      uses less disk space in most cases, too.</para>
   1.426 +
   1.427 +    &interaction.tour.reclone;
   1.428 +
   1.429 +    <para>As an aside, it's often good practice to keep a
   1.430 +      <quote>pristine</quote> copy of a remote repository around,
   1.431 +      which you can then make temporary clones of to create sandboxes
   1.432 +      for each task you want to work on.  This lets you work on
   1.433 +      multiple tasks in parallel, each isolated from the others until
   1.434 +      it's complete and you're ready to integrate it back.  Because
   1.435 +      local clones are so cheap, there's almost no overhead to cloning
   1.436 +      and destroying repositories whenever you want.</para>
   1.437 +
   1.438 +    <para>In our <filename class="directory">my-hello</filename>
   1.439 +      repository, we have a file <filename>hello.c</filename> that
   1.440 +      contains the classic <quote>hello, world</quote> program. Let's
   1.441 +      use the ancient and venerable <command>sed</command> command to
   1.442 +      edit this file so that it prints a second line of output.  (I'm
   1.443 +      only using <command>sed</command> to do this because it's easy
   1.444 +      to write a scripted example this way.  Since you're not under
   1.445 +      the same constraint, you probably won't want to use
   1.446 +      <command>sed</command>; simply use your preferred text editor to
   1.447 +      do the same thing.)</para>
   1.448 +
   1.449 +    &interaction.tour.sed;
   1.450 +
   1.451 +    <para>Mercurial's <command role="hg-cmd">hg status</command>
   1.452 +      command will tell us what Mercurial knows about the files in the
   1.453 +      repository.</para>
   1.454 +
   1.455 +    &interaction.tour.status;
   1.456 +
   1.457 +    <para>The <command role="hg-cmd">hg status</command> command
   1.458 +      prints no output for some files, but a line starting with
   1.459 +      <quote><literal>M</literal></quote> for
   1.460 +      <filename>hello.c</filename>.  Unless you tell it to, <command
   1.461 +	role="hg-cmd">hg status</command> will not print any output
   1.462 +      for files that have not been modified.</para>
   1.463 +
   1.464 +    <para>The <quote><literal>M</literal></quote> indicates that
   1.465 +      Mercurial has noticed that we modified
   1.466 +      <filename>hello.c</filename>.  We didn't need to
   1.467 +      <emphasis>inform</emphasis> Mercurial that we were going to
   1.468 +      modify the file before we started, or that we had modified the
   1.469 +      file after we were done; it was able to figure this out
   1.470 +      itself.</para>
   1.471 +
   1.472 +    <para>It's a little bit helpful to know that we've modified
   1.473 +      <filename>hello.c</filename>, but we might prefer to know
   1.474 +      exactly <emphasis>what</emphasis> changes we've made to it.  To
   1.475 +      do this, we use the <command role="hg-cmd">hg diff</command>
   1.476 +      command.</para>
   1.477 +
   1.478 +    &interaction.tour.diff;
   1.479 +
   1.480 +  </sect1>
   1.481 +  <sect1>
   1.482 +    <title>Recording changes in a new changeset</title>
   1.483 +
   1.484 +    <para>We can modify files, build and test our changes, and use
   1.485 +      <command role="hg-cmd">hg status</command> and <command
   1.486 +	role="hg-cmd">hg diff</command> to review our changes, until
   1.487 +      we're satisfied with what we've done and arrive at a natural
   1.488 +      stopping point where we want to record our work in a new
   1.489 +      changeset.</para>
   1.490 +
   1.491 +    <para>The <command role="hg-cmd">hg commit</command> command lets
   1.492 +      us create a new changeset; we'll usually refer to this as
   1.493 +      <quote>making a commit</quote> or
   1.494 +      <quote>committing</quote>.</para>
   1.495 +
   1.496 +    <sect2>
   1.497 +      <title>Setting up a username</title>
   1.498 +
   1.499 +      <para>When you try to run <command role="hg-cmd">hg
   1.500 +	  commit</command> for the first time, it is not guaranteed to
   1.501 +	succeed.  Mercurial records your name and address with each
   1.502 +	change that you commit, so that you and others will later be
   1.503 +	able to tell who made each change.  Mercurial tries to
   1.504 +	automatically figure out a sensible username to commit the
   1.505 +	change with.  It will attempt each of the following methods,
   1.506 +	in order:</para>
   1.507 +      <orderedlist>
   1.508 +	<listitem><para>If you specify a <option
   1.509 +	      role="hg-opt-commit">-u</option> option to the <command
   1.510 +	      role="hg-cmd">hg commit</command> command on the command
   1.511 +	    line, followed by a username, this is always given the
   1.512 +	    highest precedence.</para></listitem>
   1.513 +	<listitem><para>If you have set the <envar>HGUSER</envar>
   1.514 +	    environment variable, this is checked
   1.515 +	    next.</para></listitem>
   1.516 +	<listitem><para>If you create a file in your home directory
   1.517 +	    called <filename role="special">.hgrc</filename>, with a
   1.518 +	    <envar role="rc-item-ui">username</envar> entry, that will
   1.519 +	    be used next.  To see what the contents of this file
   1.520 +	    should look like, refer to section <xref
   1.521 +	      linkend="sec:tour-basic:username"/>
   1.522 +	    below.</para></listitem>
   1.523 +	<listitem><para>If you have set the <envar>EMAIL</envar>
   1.524 +	    environment variable, this will be used
   1.525 +	    next.</para></listitem>
   1.526 +	<listitem><para>Mercurial will query your system to find out
   1.527 +	    your local user name and host name, and construct a
   1.528 +	    username from these components. Since this often results
   1.529 +	    in a username that is not very useful, it will print a
   1.530 +	    warning if it has to do
   1.531 +	    this.</para></listitem>
   1.532 +      </orderedlist>
   1.533 +      <para>If all of these mechanisms fail, Mercurial will
   1.534 +	  fail, printing an error message.  In this case, it will not
   1.535 +	  let you commit until you set up a
   1.536 +	  username.</para>
   1.537 +      <para>You should think of the <envar>HGUSER</envar> environment
   1.538 +	variable and the <option role="hg-opt-commit">-u</option>
   1.539 +	option to the <command role="hg-cmd">hg commit</command>
   1.540 +	command as ways to <emphasis>override</emphasis> Mercurial's
   1.541 +	default selection of username.  For normal use, the simplest
   1.542 +	and most robust way to set a username for yourself is by
   1.543 +	creating a <filename role="special">.hgrc</filename> file; see
   1.544 +	below for details.</para>
   1.545 +      <sect3 id="sec:tour-basic:username">
   1.546 +	<title>Creating a Mercurial configuration file</title>
   1.547 +
   1.548 +	<para>To set a user name, use your favourite editor
   1.549 +	    to create a file called <filename
   1.550 +	      role="special">.hgrc</filename> in your home directory.
   1.551 +	    Mercurial will use this file to look up your personalised
   1.552 +	    configuration settings.  The initial contents of your
   1.553 +	    <filename role="special">.hgrc</filename> should look like
   1.554 +	    this.</para>
   1.555 +	<programlisting># This is a Mercurial configuration file.
   1.556 +[ui]
   1.557 +username = Firstname Lastname
   1.558 +&lt;email.address@domain.net&gt;</programlisting>
   1.559 +
   1.560 +	<para>The <quote><literal>[ui]</literal></quote> line begins a
   1.561 +	  <emphasis>section</emphasis> of the config file, so you can
   1.562 +	  read the <quote><literal>username = ...</literal></quote>
   1.563 +	  line as meaning <quote>set the value of the
   1.564 +	    <literal>username</literal> item in the
   1.565 +	    <literal>ui</literal> section</quote>. A section continues
   1.566 +	  until a new section begins, or the end of the file.
   1.567 +	  Mercurial ignores empty lines and treats any text from
   1.568 +	  <quote><literal>#</literal></quote> to the end of a line as
   1.569 +	  a comment.</para>
   1.570 +      </sect3>
   1.571 +
   1.572 +      <sect3>
   1.573 +	<title>Choosing a user name</title>
   1.574 +
   1.575 +	<para>You can use any text you like as the value of
   1.576 +	    the <literal>username</literal> config item, since this
   1.577 +	    information is for reading by other people, but for
   1.578 +	    interpreting by Mercurial.  The convention that most
   1.579 +	    people follow is to use their name and email address, as
   1.580 +	    in the example above.</para>
   1.581 +	<note>
   1.582 +	  <para>Mercurial's built-in web server obfuscates
   1.583 +	      email addresses, to make it more difficult for the email
   1.584 +	      harvesting tools that spammers use. This reduces the
   1.585 +	      likelihood that you'll start receiving more junk email
   1.586 +	      if you publish a Mercurial repository on the
   1.587 +	      web.</para></note>
   1.588 +
   1.589 +      </sect3>
   1.590 +    </sect2>
   1.591 +    <sect2>
   1.592 +      <title>Writing a commit message</title>
   1.593 +
   1.594 +      <para>When we commit a change, Mercurial drops us into
   1.595 +	  a text editor, to enter a message that will describe the
   1.596 +	  modifications we've made in this changeset.  This is called
   1.597 +	  the <emphasis>commit message</emphasis>.  It will be a
   1.598 +	  record for readers of what we did and why, and it will be
   1.599 +	  printed by <command role="hg-cmd">hg log</command> after
   1.600 +	  we've finished committing.</para>
   1.601 +
   1.602 +       &interaction.tour.commit;
   1.603 +
   1.604 +      <para>The editor that the <command role="hg-cmd">hg
   1.605 +	    commit</command> command drops us into will contain an
   1.606 +	  empty line, followed by a number of lines starting with
   1.607 +	  <quote><literal>HG:</literal></quote>.</para>
   1.608 +
   1.609 +    <programlisting>XXX fix this XXX</programlisting>
   1.610 +
   1.611 +      <para>Mercurial ignores the lines that start with
   1.612 +	  <quote><literal>HG:</literal></quote>; it uses them only to
   1.613 +	  tell us which files it's recording changes to.  Modifying or
   1.614 +	  deleting these lines has no effect.</para>
   1.615 +    </sect2>
   1.616 +    <sect2>
   1.617 +      <title>Writing a good commit message</title>
   1.618 +
   1.619 +      <para>Since <command role="hg-cmd">hg log</command>
   1.620 +	  only prints the first line of a commit message by default,
   1.621 +	  it's best to write a commit message whose first line stands
   1.622 +	  alone.  Here's a real example of a commit message that
   1.623 +	  <emphasis>doesn't</emphasis> follow this guideline, and
   1.624 +	  hence has a summary that is not
   1.625 +	  readable.</para>
   1.626 +
   1.627 +      <programlisting>
   1.628 +changeset:   73:584af0e231be
   1.629 +user:        Censored Person &lt;censored.person@example.org&gt;
   1.630 +date:        Tue Sep 26 21:37:07 2006 -0700
   1.631 +summary:     include buildmeister/commondefs. Add exports.</programlisting>
   1.632 +
   1.633 +      <para>As far as the remainder of the contents of the
   1.634 +	  commit message are concerned, there are no hard-and-fast
   1.635 +	  rules.  Mercurial itself doesn't interpret or care about the
   1.636 +	  contents of the commit message, though your project may have
   1.637 +	  policies that dictate a certain kind of
   1.638 +	  formatting.</para>
   1.639 +      <para>My personal preference is for short, but
   1.640 +	  informative, commit messages that tell me something that I
   1.641 +	  can't figure out with a quick glance at the output of
   1.642 +	  <command role="hg-cmd">hg log
   1.643 +	    --patch</command>.</para>
   1.644 +    </sect2>
   1.645 +    <sect2>
   1.646 +      <title>Aborting a commit</title>
   1.647 +
   1.648 +      <para>If you decide that you don't want to commit
   1.649 +	  while in the middle of editing a commit message, simply exit
   1.650 +	  from your editor without saving the file that it's editing.
   1.651 +	  This will cause nothing to happen to either the repository
   1.652 +	  or the working directory.</para>
   1.653 +      <para>If we run the <command role="hg-cmd">hg
   1.654 +	    commit</command> command without any arguments, it records
   1.655 +	  all of the changes we've made, as reported by <command
   1.656 +	    role="hg-cmd">hg status</command> and <command
   1.657 +	    role="hg-cmd">hg diff</command>.</para>
   1.658 +    </sect2>
   1.659 +    <sect2>
   1.660 +      <title>Admiring our new handiwork</title>
   1.661 +
   1.662 +      <para>Once we've finished the commit, we can use the
   1.663 +	  <command role="hg-cmd">hg tip</command> command to display
   1.664 +	  the changeset we just created.  This command produces output
   1.665 +	  that is identical to <command role="hg-cmd">hg
   1.666 +	    log</command>, but it only displays the newest revision in
   1.667 +	  the repository.</para>
   1.668 +
   1.669 +      &interaction.tour.tip;
   1.670 +
   1.671 +      <para>We refer to
   1.672 +	  the newest revision in the repository as the tip revision,
   1.673 +	  or simply the tip.</para>
   1.674 +    </sect2>
   1.675 +  </sect1>
   1.676 +
   1.677 +  <sect1>
   1.678 +    <title>Sharing changes</title>
   1.679 +
   1.680 +    <para>We mentioned earlier that repositories in
   1.681 +	Mercurial are self-contained.  This means that the changeset
   1.682 +	we just created exists only in our <filename
   1.683 +	  class="directory">my-hello</filename> repository.  Let's
   1.684 +	look at a few ways that we can propagate this change into
   1.685 +	other repositories.</para>
   1.686 +
   1.687 +    <sect2 id="sec:tour:pull">
   1.688 +      <title>Pulling changes from another repository</title>
   1.689 +      <para>To get started, let's clone our original
   1.690 +	  <filename class="directory">hello</filename> repository,
   1.691 +	  which does not contain the change we just committed.  We'll
   1.692 +	  call our temporary repository <filename
   1.693 +	    class="directory">hello-pull</filename>.</para>
   1.694 +
   1.695 +      &interaction.tour.clone-pull;
   1.696 +
   1.697 +      <para>We'll use the <command role="hg-cmd">hg
   1.698 +	    pull</command> command to bring changes from <filename
   1.699 +	    class="directory">my-hello</filename> into <filename
   1.700 +	    class="directory">hello-pull</filename>.  However, blindly
   1.701 +	  pulling unknown changes into a repository is a somewhat
   1.702 +	  scary prospect.  Mercurial provides the <command
   1.703 +	    role="hg-cmd">hg incoming</command> command to tell us
   1.704 +	  what changes the <command role="hg-cmd">hg pull</command>
   1.705 +	  command <emphasis>would</emphasis> pull into the repository,
   1.706 +	  without actually pulling the changes in.</para>
   1.707 +
   1.708 +      &interaction.tour.incoming;
   1.709 +
   1.710 +      <para>(Of course, someone could
   1.711 +	  cause more changesets to appear in the repository that we
   1.712 +	  ran <command role="hg-cmd">hg incoming</command> in, before
   1.713 +	  we get a chance to <command role="hg-cmd">hg pull</command>
   1.714 +	  the changes, so that we could end up pulling changes that we
   1.715 +	  didn't expect.)</para>
   1.716 +
   1.717 +      <para>Bringing changes into a repository is a simple
   1.718 +	  matter of running the <command role="hg-cmd">hg
   1.719 +	    pull</command> command, and telling it which repository to
   1.720 +	  pull from.</para>
   1.721 +
   1.722 +      &interaction.tour.pull;
   1.723 +
   1.724 +      <para>As you can see
   1.725 +	  from the before-and-after output of <command
   1.726 +	    role="hg-cmd">hg tip</command>, we have successfully
   1.727 +	  pulled changes into our repository.  There remains one step
   1.728 +	  before we can see these changes in the working
   1.729 +	  directory.</para>
   1.730 +    </sect2>
   1.731 +    <sect2>
   1.732 +      <title>Updating the working directory</title>
   1.733 +
   1.734 +      <para>We have so far glossed over the relationship between a
   1.735 +	repository and its working directory.  The <command
   1.736 +	  role="hg-cmd">hg pull</command> command that we ran in
   1.737 +	section <xref linkend="sec:tour:pull"/> brought changes
   1.738 +	into the repository, but if we check, there's no sign of those
   1.739 +	changes in the working directory.  This is because <command
   1.740 +	  role="hg-cmd">hg pull</command> does not (by default) touch
   1.741 +	the working directory.  Instead, we use the <command
   1.742 +	  role="hg-cmd">hg update</command> command to do this.</para>
   1.743 +
   1.744 +      &interaction.tour.update;
   1.745 +
   1.746 +      <para>It might seem a bit strange that <command role="hg-cmd">hg
   1.747 +	  pull</command> doesn't update the working directory
   1.748 +	automatically.  There's actually a good reason for this: you
   1.749 +	can use <command role="hg-cmd">hg update</command> to update
   1.750 +	the working directory to the state it was in at <emphasis>any
   1.751 +	  revision</emphasis> in the history of the repository.  If
   1.752 +	you had the working directory updated to an old revision---to
   1.753 +	hunt down the origin of a bug, say---and ran a <command
   1.754 +	  role="hg-cmd">hg pull</command> which automatically updated
   1.755 +	the working directory to a new revision, you might not be
   1.756 +	terribly happy.</para>
   1.757 +      <para>However, since pull-then-update is such a common thing to
   1.758 +	do, Mercurial lets you combine the two by passing the <option
   1.759 +	  role="hg-opt-pull">-u</option> option to <command
   1.760 +	  role="hg-cmd">hg pull</command>.</para>
   1.761 +
   1.762 +      <para>If you look back at the output of <command
   1.763 +	  role="hg-cmd">hg pull</command> in section <xref
   1.764 +	    linkend="sec:tour:pull"/> when we ran it without <option
   1.765 +	  role="hg-opt-pull">-u</option>, you can see that it printed
   1.766 +	a helpful reminder that we'd have to take an explicit step to
   1.767 +	update the working directory:</para>
   1.768 +
   1.769 +      <!-- &interaction.xxx.fixme; -->
   1.770 +
   1.771 +      <para>To find out what revision the working directory is at, use
   1.772 +	the <command role="hg-cmd">hg parents</command>
   1.773 +	command.</para>
   1.774 +
   1.775 +      &interaction.tour.parents;
   1.776 +
   1.777 +      <para>If you look back at figure <xref
   1.778 +	  linkend="fig:tour-basic:history"/>,
   1.779 +	you'll see arrows connecting each changeset.  The node that
   1.780 +	the arrow leads <emphasis>from</emphasis> in each case is a
   1.781 +	parent, and the node that the arrow leads
   1.782 +	<emphasis>to</emphasis> is its child.  The working directory
   1.783 +	has a parent in just the same way; this is the changeset that
   1.784 +	the working directory currently contains.</para>
   1.785 +
   1.786 +      <para>To update the working directory to a particular revision,
   1.787 +
   1.788 +	give a revision number or changeset ID to the <command
   1.789 +	  role="hg-cmd">hg update</command> command.</para>
   1.790 +
   1.791 +      &interaction.tour.older;
   1.792 +
   1.793 +      <para>If you omit an explicit revision, <command
   1.794 +	  role="hg-cmd">hg update</command> will update to the tip
   1.795 +	revision, as shown by the second call to <command
   1.796 +	  role="hg-cmd">hg update</command> in the example
   1.797 +	above.</para>
   1.798 +    </sect2>
   1.799 +
   1.800 +    <sect2>
   1.801 +      <title>Pushing changes to another repository</title>
   1.802 +
   1.803 +      <para>Mercurial lets us push changes to another
   1.804 +	  repository, from the repository we're currently visiting.
   1.805 +	  As with the example of <command role="hg-cmd">hg
   1.806 +	    pull</command> above, we'll create a temporary repository
   1.807 +	  to push our changes into.</para>
   1.808 +
   1.809 +      &interaction.tour.clone-push;
   1.810 +
   1.811 +      <para>The <command role="hg-cmd">hg outgoing</command> command
   1.812 +	  tells us what changes would be pushed into another
   1.813 +	  repository.</para>
   1.814 +
   1.815 +      &interaction.tour.outgoing;
   1.816 +
   1.817 +      <para>And the
   1.818 +	  <command role="hg-cmd">hg push</command> command does the
   1.819 +	  actual push.</para>
   1.820 +
   1.821 +      &interaction.tour.push;
   1.822 +
   1.823 +      <para>As with
   1.824 +	  <command role="hg-cmd">hg pull</command>, the <command
   1.825 +	    role="hg-cmd">hg push</command> command does not update
   1.826 +	  the working directory in the repository that it's pushing
   1.827 +	  changes into. (Unlike <command role="hg-cmd">hg
   1.828 +	    pull</command>, <command role="hg-cmd">hg push</command>
   1.829 +	  does not provide a <literal>-u</literal> option that updates
   1.830 +	  the other repository's working directory.)</para>
   1.831 +
   1.832 +      <para>What happens if we try to pull or push changes
   1.833 +	  and the receiving repository already has those changes?
   1.834 +	  Nothing too exciting.</para>
   1.835 +
   1.836 +      &interaction.tour.push.nothing;
   1.837 +    </sect2>
   1.838 +    <sect2>
   1.839 +      <title>Sharing changes over a network</title>
   1.840 +
   1.841 +      <para>The commands we have covered in the previous few
   1.842 +	  sections are not limited to working with local repositories.
   1.843 +	  Each works in exactly the same fashion over a network
   1.844 +	  connection; simply pass in a URL instead of a local
   1.845 +	  path.</para>
   1.846 +	
   1.847 +      &interaction.tour.outgoing.net;
   1.848 +
   1.849 +      <para>In this example, we
   1.850 +	  can see what changes we could push to the remote repository,
   1.851 +	  but the repository is understandably not set up to let
   1.852 +	  anonymous users push to it.</para>
   1.853 +
   1.854 +      &interaction.tour.push.net;
   1.855 +    </sect2>
   1.856 +  </sect1>
   1.857 +</chapter>
   1.858 +
   1.859 +<!--
   1.860 +local variables: 
   1.861 +sgml-parent-document: ("00book.xml" "book" "chapter")
   1.862 +end:
   1.863 +-->