comparison en/ch02-tour-basic.xml @ 657:8631da51309b

Slow progress on XML conversion

656:23dc79421e06

	  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 id="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>

    <figure>

      <para>  <mediaobject><imageobject><imagedata
					  fileref="tour-history"/></imageobject><textobject><phrase>XXX 
	      add text</phrase></textobject></mediaobject>
	<caption>Graphical history of the <filename
	  class="directory">hello</filename> repository</caption>
	\label{fig:tour-basic:history}</para>
    </figure>

    <sect2>
      <title>Changesets, revisions, and talking to other
	people</title>

      <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 id="sec:mq:patch"/> for an
	overview). <!-- &interaction.tour.log-vp; --></para>

    </sect2>
  </sect1>
  <sect1>

	<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
	      id="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>
      <listitem><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></listitem>
      <listitem><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></listitem>
      <sect3>
	<title>Creating a Mercurial configuration file</title>
	<listitem><para>\label{sec:tour-basic:username}</para></listitem>
	<listitem><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></listitem><programlisting>
	  <listitem><para>  # This is a Mercurial configuration file.
	      [ui] username = Firstname Lastname
	      &lt;[e-mail]&gt;</para></listitem></programlisting>
	<listitem><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></listitem>
      </sect3>
      <sect3>
	<title>Choosing a user name</title>

	<listitem><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></listitem>
	<note>
	  <listitem><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></listitem></note>

      </sect3>
    </sect2>
    <sect2>
      <title>Writing a commit message</title>

      <listitem><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. <!-- &interaction.tour.commit;
	  --></para></listitem>
      <listitem><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></listitem><programlisting>
	<listitem><para>  <emphasis>empty line</emphasis> HG: changed
	    hello.c</para></listitem></programlisting>
      <listitem><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></listitem>
    </sect2>
    <sect2>
      <title>Writing a good commit message</title>

      <listitem><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></listitem><programlisting>
	<listitem><para>  changeset:   73:584af0e231be user: Censored
	    Person &lt;[e-mail]&gt; date: Tue Sep
	    26 21:37:07 2006 -0700 summary:     include
	    buildmeister/commondefs.   Add an exports and
	    install</para></listitem></programlisting>

      <listitem><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></listitem>
      <listitem><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></listitem>
    </sect2>
    <sect2>
      <title>Aborting a commit</title>

      <listitem><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></listitem>
      <listitem><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></listitem>
    </sect2>
    <sect2>
      <title>Admiring our new handiwork</title>

      <listitem><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. <!-- &interaction.tour.tip; --> We refer to
	  the newest revision in the repository as the tip revision,
	  or simply the tip.</para></listitem>
    </sect2>
  </sect1>
  <sect1>
    <title>Sharing changes</title>

    <listitem><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></listitem>
    <sect2>
      <title>Pulling changes from another repository</title>
      <listitem><para>\label{sec:tour:pull}</para></listitem>
      <listitem><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>. <!--
	  &interaction.tour.clone-pull; --></para></listitem>
      <listitem><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. <!--
	  &interaction.tour.incoming; --> (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></listitem>
      <listitem><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. <!-- &interaction.tour.pull; --> 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></listitem>
    </sect2>
    <sect2>
      <title>Updating the working directory</title>

      <listitem><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 id="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. <!--
	  &interaction.tour.update; --></para></listitem>
      <listitem><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></listitem>
      <listitem><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></listitem><programlisting>
	<listitem><para>  hg pull
	    -u</para></listitem></programlisting>
      <listitem><para>If you look back at the output of <command
	    role="hg-cmd">hg pull</command> in section <xref
	    id="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></listitem><programlisting>
	<listitem><para>  (run 'hg update' to get a working
	    copy)</para></listitem></programlisting>

      <listitem><para>To find out what revision the working directory
	  is at, use the <command role="hg-cmd">hg parents</command>
	  command. <!-- &interaction.tour.parents; --> If you look
	  back at figure <xref id="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></listitem>
      <listitem><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. <!--
	  &interaction.tour.older; --> 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></listitem>
    </sect2>
    <sect2>
      <title>Pushing changes to another repository</title>

      <listitem><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. <!-- &interaction.tour.clone-push;
	  --> The <command role="hg-cmd">hg outgoing</command> command
	  tells us what changes would be pushed into another
	  repository. <!-- &interaction.tour.outgoing; --> And the
	  <command role="hg-cmd">hg push</command> command does the
	  actual push. <!-- &interaction.tour.push; --> 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></listitem>
      <listitem><para>What happens if we try to pull or push changes
	  and the receiving repository already has those changes?
	  Nothing too exciting. <!-- &interaction.tour.push.nothing;
	  --></para></listitem>
    </sect2>
    <sect2>
      <title>Sharing changes over a network</title>

      <listitem><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.
	  <!-- &interaction.tour.outgoing.net; --> 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. <!-- &interaction.tour.push.net;
	  --></para></listitem>
    </sect2>
  </sect1>
</chapter>

<!--

657:8631da51309b

	  to describe the changeset.</para></listitem></itemizedlist>
    <para>The default output printed by <command role="hg-cmd">hg
	log</command> is purely a summary; it is missing a lot of
      detail.</para>

    <para>Figure <xref linkend="fig:tour-basic:history"/> provides a
      graphical representation of the history of the <filename
	class="directory">hello</filename> repository, to make it a
      little easier to see which direction history is
      <quote>flowing</quote> in.  We'll be returning to this figure
      several times in this chapter and the chapter that
      follows.</para>

    <informalfigure id="fig:tour-basic:history">
      <mediaobject>
	<imageobject><imagedata fileref="tour-history"/></imageobject>
	<textobject><phrase>XXX add text</phrase></textobject>
	<caption><para>Graphical history of the <filename
	      class="directory">hello</filename>
	    repository</para></caption>
      </mediaobject>
    </informalfigure>

    <sect2>
      <title>Changesets, revisions, and talking to other
	people</title>

      <para>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). <!-- &interaction.tour.log-vp; --></para>

    </sect2>
  </sect1>
  <sect1>

	<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. <!--
	  &interaction.tour.update; --></para>
      <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 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. <!--
	  &interaction.tour.older; --> 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>

<!--