diff en/ch01-tour-basic.xml @ 749:7e7c47481e4f

Oops, this is the real merge for my hg's oddity

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