comparison en/ch01-tour-basic.xml @ 824:c8d662d3cb40

Improve chapter 1 further, based on comments.

823:9e33729cafae

	<literal>mercurial</literal>.</para>

      <itemizedlist>
	<listitem><para id="x_4">Ubuntu and Debian:</para>
	  <programlisting>apt-get install mercurial</programlisting></listitem>
	<listitem><para id="x_5">Fedora and OpenSUSE:</para>
	  <programlisting>yum install mercurial</programlisting></listitem>
	<listitem><para id="x_6">Gentoo:</para>
	  <programlisting>emerge mercurial</programlisting></listitem>
      </itemizedlist>

    </sect2>

  <sect1>
    <title>Getting started</title>

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

      <listitem><para id="x_1e"><literal>changeset</literal>: This
	  field has the format of a number, followed by a colon,
	  followed by a hexadecimal (or <emphasis>hex</emphasis>)
	  string.  These are <emphasis>identifiers</emphasis> for the
	  changeset.  The hex string is a unique identifier: the same
	  hex string will always refer to the same changeset. The
	  number is shorter and easier to type than the hex string,
	  but it isn't unique: the same number in two different clones
	  of a repository may identify different changesets.  Why
	  provide the number at all, then?  For local
	  convenience.</para>
      </listitem>
      <listitem><para id="x_1f"><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>

	    role="hg-cmd">hg log -v -p -r 2</command> can be written
	  as <command role="hg-cmd">hg log -vpr2</command>.</para>
      </listitem>
    </itemizedlist>

    <para id="x_36">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 id="x_37">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

	below for details.</para>
      <sect3 id="sec:tour-basic:username">
	<title>Creating a Mercurial configuration file</title>

	<para id="x_4a">To set a user name, use your favorite 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>

	<remark>Figure out what the appropriate directory is on
	  Windows.</remark>

	<programlisting># This is a Mercurial configuration file.
[ui]
username = Firstname Lastname &lt;[e-mail]&gt;</programlisting>

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

      <sect3>
	<title>Choosing a user name</title>

	<para id="x_4c">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 will not be
	    interpreted by Mercurial.  The convention that most
	    people follow is to use their name and email address, as
	    in the example above.</para>
	<note>
	  <para id="x_4d">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 id="x_4e">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 id="x_4f">The editor that the <command role="hg-cmd">hg
	    commit</command> command drops us into will contain an
	  empty line or two, followed by a number of lines starting with
	  <quote><literal>HG:</literal></quote>.</para>

    <programlisting>
This is where I type my commit comment.

HG: Enter commit message.  Lines beginning with 'HG:' are removed.

HG: user: Bryan O'Sullivan <[e-mail]>
HG: branch 'default'
HG: changed hello.c</programlisting>

      <para id="x_50">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 id="x_51">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 id="x_52">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 id="x_53">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 id="x_54">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 id="x_55">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 id="x_56">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 id="x_57">We refer to the newest revision in the
	repository as the <emphasis>tip revision</emphasis>, or simply

  <sect1>
    <title>Sharing changes</title>

    <para id="x_58">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 id="x_59">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 id="x_5a">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 id="x_5b">Suppose you're pulling changes from a repository
      on the network somewhere. While you are looking at the <command
	  role="hg-cmd">hg incoming</command> output, and before you
	pull those changes, someone might have committed something in
	the remote repository. This means that it's possible to pull
	more changes than you saw when using <command
	  role="hg-cmd">hg incoming</command>.</para>

      <para id="x_5c">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 id="x_5d">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 id="x_5e">We have so far glossed over the relationship
	between a repository and its working directory.  The <command

	the working directory.  Instead, we use the <command
	  role="hg-cmd">hg update</command> command to do this.</para>

      &interaction.tour.update;

      <para id="x_5f">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&emdash;to
	hunt down the origin of a bug, say&emdash;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 id="x_60">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 id="x_61">If you look back at the output of <command
	  role="hg-cmd">hg pull</command> in <xref
	    linkend="sec:tour:pull"/> when we ran it without <option

	a helpful reminder that we'd have to take an explicit step to
	update the working directory:</para>

      <!-- &interaction.xxx.fixme; -->

      <para id="x_62">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 id="x_63">If you look back at <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 id="x_64">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 id="x_65">If you omit an explicit revision, <command
	  role="hg-cmd">hg update</command> will update to the tip

    <sect2>
      <title>Pushing changes to another repository</title>

      <para id="x_66">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 id="x_67">The <command role="hg-cmd">hg outgoing</command> command
	  tells us what changes would be pushed into another
	  repository.</para>

      &interaction.tour.outgoing;

      <para id="x_68">And the
	  <command role="hg-cmd">hg push</command> command does the
	  actual push.</para>

      &interaction.tour.push;

      <para id="x_69">As with <command role="hg-cmd">hg
	  pull</command>, the <command role="hg-cmd">hg push</command>

	  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 id="x_6b">The commands we have covered in the previous few
	  sections are not limited to working with local repositories.

	  connection; simply pass in a URL instead of a local
	  path.</para>
	
      &interaction.tour.outgoing.net;

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

824:c8d662d3cb40

	<literal>mercurial</literal>.</para>

      <itemizedlist>
	<listitem><para id="x_4">Ubuntu and Debian:</para>
	  <programlisting>apt-get install mercurial</programlisting></listitem>
	<listitem><para id="x_5">Fedora:</para>
	  <programlisting>yum install mercurial</programlisting></listitem>
	<listitem><para>OpenSUSE:</para>
	  <programlisting>zypper install mercurial</programlisting></listitem>
	<listitem><para id="x_6">Gentoo:</para>
	  <programlisting>emerge mercurial</programlisting></listitem>
      </itemizedlist>

    </sect2>

  <sect1>
    <title>Getting started</title>

    <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg
	version</command> command to find out whether Mercurial is
      installed properly.  The actual version information that it
      prints isn't so important; we simply care whether the command
      runs and prints anything at all.</para>

    &interaction.tour.version;

    <sect2>
      <title>Built-in help</title>

      <listitem><para id="x_1e"><literal>changeset</literal>: This
	  field has the format of a number, followed by a colon,
	  followed by a hexadecimal (or <emphasis>hex</emphasis>)
	  string.  These are <emphasis>identifiers</emphasis> for the
	  changeset.  The hex string is a unique identifier: the same
	  hex string will always refer to the same changeset in every
	  copy of this repository. The
	  number is shorter and easier to type than the hex string,
	  but it isn't unique: the same number in two different clones
	  of a repository may identify different changesets.</para>
      </listitem>
      <listitem><para id="x_1f"><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>

	    role="hg-cmd">hg log -v -p -r 2</command> can be written
	  as <command role="hg-cmd">hg log -vpr2</command>.</para>
      </listitem>
    </itemizedlist>

    <para id="x_36">In the examples throughout this book, I usually
      use short options instead of long.  This simply reflects my own
      preference, so don't read anything significant into it.</para>

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

	below for details.</para>
      <sect3 id="sec:tour-basic:username">
	<title>Creating a Mercurial configuration file</title>

	<para id="x_4a">To set a user name, use your favorite 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>

	<tip>
	  <title><quote>Home directory</quote> on Windows</title>

	  <para>When we refer to your home directory, on an English
	    language installation of Windows this will usually be a
	    folder named after your user name in
	    <filename>C:\Documents and Settings</filename>.  You can
	    find out the exact name of your home directory by opening
	    a command prompt window and running the following
	    command.</para>

	  <screen><prompt>C:\></prompt> <userinput>echo %UserProfile%</userinput></screen>
	</tip>

	<programlisting># This is a Mercurial configuration file.
[ui]
username = Firstname Lastname &lt;[e-mail]&gt;</programlisting>

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

      <sect3>
	<title>Choosing a user name</title>

	<para id="x_4c">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 will not be
	  interpreted by Mercurial.  The convention that most people
	  follow is to use their name and email address, as in the
	  example above.</para>
	<note>
	  <para id="x_4d">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 id="x_4e">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 id="x_4f">The editor that the <command role="hg-cmd">hg
	  commit</command> command drops us into will contain an empty
	line or two, followed by a number of lines starting with
	<quote><literal>HG:</literal></quote>.</para>

    <programlisting>
This is where I type my commit comment.

HG: Enter commit message.  Lines beginning with 'HG:' are removed.

HG: user: Bryan O'Sullivan <[e-mail]>
HG: branch 'default'
HG: changed hello.c</programlisting>

      <para id="x_50">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 id="x_51">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 id="x_52">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 id="x_53">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>
      <para id="x_55">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>

      <note>
	<title>A surprise for Subversion users</title>

	<para>Like other Mercurial commands, if we don't supply
	  explicit names to commit to the <command role="hg-cmd">hg
	    commit</command>, it will operate across a repository's
	  entire working directory.  Be wary of this if you're coming
	  from the Subversion or CVS world, since you might expect it
	  to operate only on the current directory that you happen to
	  be visiting and its subdirectories.</para>
      </note>
    </sect2>

    <sect2>
      <title>Aborting a commit</title>

      <para id="x_54">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>
    </sect2>

    <sect2>
      <title>Admiring our new handiwork</title>

      <para id="x_56">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 id="x_57">We refer to the newest revision in the
	repository as the <emphasis>tip revision</emphasis>, or simply

  <sect1>
    <title>Sharing changes</title>

    <para id="x_58">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 id="x_59">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 id="x_5a">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 id="x_5c">Bringing changes into a repository is a simple
	matter of running the <command role="hg-cmd">hg pull</command>
	command, and optionally telling it which repository to pull from.</para>

      &interaction.tour.pull;

      <para id="x_5d">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.  However,
	Mercurial separates pulling changes in from updating the
	working directory. There remains one step before we will see
	the changes that we just pulled appear in the working
	directory.</para>

      <tip>
	<title>Pulling specific changes</title>

	<para id="x_5b">It is possible that due to the delay between
	  running <command role="hg-cmd">hg incoming</command> and
	  <command role="hg-cmd">hg pull</command>, you may not see
	  all changesets that will be brought from the other
	  repository. Suppose you're pulling changes from a repository
	  on the network somewhere. While you are looking at the
	  <command role="hg-cmd">hg incoming</command> output, and
	  before you pull those changes, someone might have committed
	  something in the remote repository. This means that it's
	  possible to pull more changes than you saw when using
	  <command role="hg-cmd">hg incoming</command>.</para>

	<para>If you only want to pull precisely the changes that were
	  listed by <command role="hg-cmd">hg incoming</command>, or
	  you have some other reason to pull a subset of changes,
	  simply identify the change that you want to pull by its
	  changeset ID, e.g. <command>hg pull
	    -r7e95bb</command>.</para>
      </tip>
    </sect2>

    <sect2>
      <title>Updating the working directory</title>

      <para id="x_5e">We have so far glossed over the relationship
	between a repository and its working directory.  The <command

	the working directory.  Instead, we use the <command
	  role="hg-cmd">hg update</command> command to do this.</para>

      &interaction.tour.update;

      <para id="x_5f">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&emdash;to hunt down the origin of a bug,
	say&emdash;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 id="x_60">Since pull-then-update is such a common sequence
	of operations, 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 id="x_61">If you look back at the output of <command
	  role="hg-cmd">hg pull</command> in <xref
	    linkend="sec:tour:pull"/> when we ran it without <option

	a helpful reminder that we'd have to take an explicit step to
	update the working directory:</para>

      <!-- &interaction.xxx.fixme; -->

      <para id="x_62">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 id="x_63">If you look back at <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 id="x_64">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 id="x_65">If you omit an explicit revision, <command
	  role="hg-cmd">hg update</command> will update to the tip

    <sect2>
      <title>Pushing changes to another repository</title>

      <para id="x_66">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 id="x_67">The <command role="hg-cmd">hg outgoing</command>
	command tells us what changes would be pushed into another
	repository.</para>

      &interaction.tour.outgoing;

      <para id="x_68">And the <command role="hg-cmd">hg push</command>
	command does the actual push.</para>

      &interaction.tour.push;

      <para id="x_69">As with <command role="hg-cmd">hg
	  pull</command>, the <command role="hg-cmd">hg push</command>

	  and the receiving repository already has those changes?
	  Nothing too exciting.</para>

      &interaction.tour.push.nothing;
    </sect2>

    <sect2>
      <title>Default locations</title>

      <para>When we clone a repository, Mercurial records the location
	of the repository we cloned in the
	<filename>.hg/hgrc</filename> file of the new repository.  If
	we don't supply a location to <command>hg pull</command> from
	or <command>hg push</command> to, those commands will use this
	location as a default.  The <command>hg incoming</command>
	and <command>hg outgoing</command> commands do so too.</para>

      <para>If you open a repository's <filename>.hg/hgrc</filename>
	file in a text editor, you will see contents like the
	following.</para>

      <programlisting>[paths]
default = http://www.selenic.com/repo/hg</programlisting>

      <para>It is possible&emdash;and often useful&emdash;to have the
	default location for <command>hg push</command> and
	<command>hg outgoing</command> be different from those for
	<command>hg pull</command> and <command>hg incoming</command>.
	We can do this by adding a <literal>default-push</literal>
	entry to the <literal>[paths]</literal> section of the
	<filename>.hg/hgrc</filename> file, as follows.</para>

      <programlisting>[paths]
default = http://www.selenic.com/repo/hg
default-push = http://hg.example.com/hg</programlisting>
    </sect2>

    <sect2>
      <title>Sharing changes over a network</title>

      <para id="x_6b">The commands we have covered in the previous few
	  sections are not limited to working with local repositories.

	  connection; simply pass in a URL instead of a local
	  path.</para>
	
      &interaction.tour.outgoing.net;

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