1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/en/ch02-tour-basic.xml	Thu May 07 21:07:35 2009 -0700
     1.3 @@ -0,0 +1,1035 @@
     1.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5 +
     1.6 +<chapter id="chap:tour-basic">
     1.7 +  <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?>
     1.8 +  <title>A tour of Mercurial: the basics</title>
     1.9 +
    1.10 +  <sect1 id="sec:tour:install">
    1.11 +    <title>Installing Mercurial on your system</title>
    1.12 +
    1.13 +    <para id="x_1">Prebuilt binary packages of Mercurial are available for
    1.14 +      every popular operating system.  These make it easy to start
    1.15 +      using Mercurial on your computer immediately.</para>
    1.16 +
    1.17 +    <sect2>
    1.18 +      <title>Windows</title>
    1.19 +
    1.20 +      <para id="x_c">The best version of Mercurial for Windows is
    1.21 +	TortoiseHg, which can be found at <ulink
    1.22 +	  url="http://bitbucket.org/tortoisehg/stable/wiki/Home">http://bitbucket.org/tortoisehg/stable/wiki/Home</ulink>. 
    1.23 +	This package has no external dependencies; it <quote>just
    1.24 +	  works</quote>.  It provides both command line and graphical
    1.25 +	user interfaces.</para>
    1.26 +
    1.27 +    </sect2>
    1.28 +
    1.29 +    <sect2>
    1.30 +      <title>Mac OS X</title>
    1.31 +
    1.32 +      <para id="x_a">Lee Cantey publishes an installer of Mercurial
    1.33 +	for Mac OS X at <ulink
    1.34 +	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para>
    1.35 +    </sect2>
    1.36 +
    1.37 +    <sect2>
    1.38 +      <title>Linux</title>
    1.39 +
    1.40 +      <para id="x_2">Because each Linux distribution has its own packaging
    1.41 +	tools, policies, and rate of development, it's difficult to
    1.42 +	give a comprehensive set of instructions on how to install
    1.43 +	Mercurial binaries.  The version of Mercurial that you will
    1.44 +	end up with can vary depending on how active the person is who
    1.45 +	maintains the package for your distribution.</para>
    1.46 +
    1.47 +      <para id="x_3">To keep things simple, I will focus on installing
    1.48 +	Mercurial from the command line under the most popular Linux
    1.49 +	distributions.  Most of these distributions provide graphical
    1.50 +	package managers that will let you install Mercurial with a
    1.51 +	single click; the package name to look for is
    1.52 +	<literal>mercurial</literal>.</para>
    1.53 +
    1.54 +      <itemizedlist>
    1.55 +	<listitem><para id="x_4">Ubuntu and Debian:</para>
    1.56 +	  <programlisting>apt-get install mercurial</programlisting></listitem>
    1.57 +	<listitem><para id="x_5">Fedora:</para>
    1.58 +	  <programlisting>yum install mercurial</programlisting></listitem>
    1.59 +	<listitem><para id="x_715">OpenSUSE:</para>
    1.60 +	  <programlisting>zypper install mercurial</programlisting></listitem>
    1.61 +	<listitem><para id="x_6">Gentoo:</para>
    1.62 +	  <programlisting>emerge mercurial</programlisting></listitem>
    1.63 +      </itemizedlist>
    1.64 +
    1.65 +    </sect2>
    1.66 +    <sect2>
    1.67 +      <title>Solaris</title>
    1.68 +
    1.69 +      <para id="x_9">SunFreeWare, at <ulink
    1.70 +	  url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 
    1.71 +	provides prebuilt packages of Mercurial.</para>
    1.72 +
    1.73 +    </sect2>
    1.74 +
    1.75 +  </sect1>
    1.76 +
    1.77 +  <sect1>
    1.78 +    <title>Getting started</title>
    1.79 +
    1.80 +    <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg
    1.81 +	version</command> command to find out whether Mercurial is
    1.82 +      installed properly.  The actual version information that it
    1.83 +      prints isn't so important; we simply care whether the command
    1.84 +      runs and prints anything at all.</para>
    1.85 +
    1.86 +    &interaction.tour.version;
    1.87 +
    1.88 +    <sect2>
    1.89 +      <title>Built-in help</title>
    1.90 +
    1.91 +      <para id="x_f">Mercurial provides a built-in help system.  This is
    1.92 +	  invaluable for those times when you find yourself stuck
    1.93 +	  trying to remember how to run a command.  If you are
    1.94 +	  completely stuck, simply run <command role="hg-cmd">hg
    1.95 +	    help</command>; it will print a brief list of commands,
    1.96 +	  along with a description of what each does.  If you ask for
    1.97 +	  help on a specific command (as below), it prints more
    1.98 +	  detailed information.</para>
    1.99 +
   1.100 +	&interaction.tour.help;
   1.101 +
   1.102 +	<para id="x_10">For a more impressive level of detail (which you won't
   1.103 +	  usually need) run <command role="hg-cmd">hg help <option
   1.104 +	      role="hg-opt-global">-v</option></command>.  The <option
   1.105 +	    role="hg-opt-global">-v</option> option is short for
   1.106 +	  <option role="hg-opt-global">--verbose</option>, and tells
   1.107 +	  Mercurial to print more information than it usually
   1.108 +	  would.</para>
   1.109 +
   1.110 +    </sect2>
   1.111 +  </sect1>
   1.112 +  <sect1>
   1.113 +    <title>Working with a repository</title>
   1.114 +
   1.115 +    <para id="x_11">In Mercurial, everything happens inside a
   1.116 +      <emphasis>repository</emphasis>.  The repository for a project
   1.117 +      contains all of the files that <quote>belong to</quote> that
   1.118 +      project, along with a historical record of the project's
   1.119 +      files.</para>
   1.120 +
   1.121 +    <para id="x_12">There's nothing particularly magical about a repository; it
   1.122 +      is simply a directory tree in your filesystem that Mercurial
   1.123 +      treats as special. You can rename or delete a repository any
   1.124 +      time you like, using either the command line or your file
   1.125 +      browser.</para>
   1.126 +
   1.127 +    <sect2>
   1.128 +      <title>Making a local copy of a repository</title>
   1.129 +
   1.130 +      <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little
   1.131 +	bit special.  While you could use a normal file copying
   1.132 +	command to make a copy of a repository, it's best to use a
   1.133 +	built-in command that Mercurial provides.  This command is
   1.134 +	called <command role="hg-cmd">hg clone</command>, because it
   1.135 +	makes an identical copy of an existing repository.</para>
   1.136 +
   1.137 +      &interaction.tour.clone;
   1.138 +
   1.139 +      <para id="x_67c">One advantage of using <command role="hg-cmd">hg
   1.140 +	  clone</command> is that, as we can see above, it lets us clone
   1.141 +	repositories over the network.  Another is that it remembers
   1.142 +	where we cloned from, which we'll find useful soon when we
   1.143 +	want to fetch new changes from another repository.</para>
   1.144 +
   1.145 +      <para id="x_14">If our clone succeeded, we should now have a local
   1.146 +	directory called <filename class="directory">hello</filename>.
   1.147 +	This directory will contain some files.</para>
   1.148 +
   1.149 +      &interaction.tour.ls;
   1.150 +
   1.151 +      <para id="x_15">These files have the same contents and history in our
   1.152 +	repository as they do in the repository we cloned.</para>
   1.153 +
   1.154 +      <para id="x_16">Every Mercurial repository is complete,
   1.155 +	self-contained, and independent.  It contains its own private
   1.156 +	copy of a project's files and history.  As we just mentioned,
   1.157 +	a cloned repository remembers the location of the repository
   1.158 +	it was cloned from, but Mercurial will not communicate with
   1.159 +	that repository, or any other, unless you tell it to.</para>
   1.160 +
   1.161 +      <para id="x_17">What this means for now is that we're free to experiment
   1.162 +	with our repository, safe in the knowledge that it's a private
   1.163 +	<quote>sandbox</quote> that won't affect anyone else.</para>
   1.164 +
   1.165 +    </sect2>
   1.166 +    <sect2>
   1.167 +      <title>What's in a repository?</title>
   1.168 +
   1.169 +      <para id="x_18">When we take a more detailed look inside a repository, we
   1.170 +	can see that it contains a directory named <filename
   1.171 +	  class="directory">.hg</filename>.  This is where Mercurial
   1.172 +	keeps all of its metadata for the repository.</para>
   1.173 +
   1.174 +      &interaction.tour.ls-a;
   1.175 +
   1.176 +      <para id="x_19">The contents of the <filename
   1.177 +	  class="directory">.hg</filename> directory and its
   1.178 +	subdirectories are private to Mercurial.  Every other file and
   1.179 +	directory in the repository is yours to do with as you
   1.180 +	please.</para>
   1.181 +
   1.182 +      <para id="x_1a">To introduce a little terminology, the <filename
   1.183 +	  class="directory">.hg</filename> directory is the
   1.184 +	<quote>real</quote> repository, and all of the files and
   1.185 +	directories that coexist with it are said to live in the
   1.186 +	<emphasis>working directory</emphasis>.  An easy way to
   1.187 +	remember the distinction is that the
   1.188 +	<emphasis>repository</emphasis> contains the
   1.189 +	<emphasis>history</emphasis> of your project, while the
   1.190 +	<emphasis>working directory</emphasis> contains a
   1.191 +	<emphasis>snapshot</emphasis> of your project at a particular
   1.192 +	point in history.</para>
   1.193 +
   1.194 +    </sect2>
   1.195 +  </sect1>
   1.196 +  <sect1>
   1.197 +    <title>A tour through history</title>
   1.198 +
   1.199 +    <para id="x_1b">One of the first things we might want to do with a new,
   1.200 +      unfamiliar repository is understand its history.  The <command
   1.201 +	role="hg-cmd">hg log</command> command gives us a view of
   1.202 +      the history of changes in the repository.</para>
   1.203 +
   1.204 +    &interaction.tour.log;
   1.205 +
   1.206 +    <para id="x_1c">By default, this command prints a brief paragraph of output
   1.207 +      for each change to the project that was recorded.  In Mercurial
   1.208 +      terminology, we call each of these recorded events a
   1.209 +      <emphasis>changeset</emphasis>, because it can contain a record
   1.210 +      of changes to several files.</para>
   1.211 +
   1.212 +    <para id="x_1d">The fields in a record of output from <command
   1.213 +	role="hg-cmd">hg log</command> are as follows.</para>
   1.214 +
   1.215 +    <itemizedlist>
   1.216 +      <listitem><para id="x_1e"><literal>changeset</literal>: This
   1.217 +	  field has the format of a number, followed by a colon,
   1.218 +	  followed by a hexadecimal (or <emphasis>hex</emphasis>)
   1.219 +	  string.  These are <emphasis>identifiers</emphasis> for the
   1.220 +	  changeset.  The hex string is a unique identifier: the same
   1.221 +	  hex string will always refer to the same changeset in every
   1.222 +	  copy of this repository. The
   1.223 +	  number is shorter and easier to type than the hex string,
   1.224 +	  but it isn't unique: the same number in two different clones
   1.225 +	  of a repository may identify different changesets.</para>
   1.226 +      </listitem>
   1.227 +      <listitem><para id="x_1f"><literal>user</literal>: The identity of the
   1.228 +	  person who created the changeset.  This is a free-form
   1.229 +	  field, but it most often contains a person's name and email
   1.230 +	  address.</para></listitem>
   1.231 +      <listitem><para id="x_20"><literal>date</literal>: The date and time on
   1.232 +	  which the changeset was created, and the timezone in which
   1.233 +	  it was created.  (The date and time are local to that
   1.234 +	  timezone; they display what time and date it was for the
   1.235 +	  person who created the changeset.)</para></listitem>
   1.236 +      <listitem><para id="x_21"><literal>summary</literal>: The first line of
   1.237 +	  the text message that the creator of the changeset entered
   1.238 +	  to describe the changeset.</para></listitem>
   1.239 +      <listitem>
   1.240 +	<para id="x_67d">Some changesets, such as the first in the list above,
   1.241 +	  have a <literal>tag</literal> field.  A tag is another way
   1.242 +	  to identify a changeset, by giving it an easy-to-remember
   1.243 +	  name. (The tag named <literal>tip</literal> is special: it
   1.244 +	  always refers to the newest change in a repository.)</para>
   1.245 +      </listitem>
   1.246 +    </itemizedlist>
   1.247 +
   1.248 +    <para id="x_22">The default output printed by <command
   1.249 +	role="hg-cmd">hg log</command> is purely a summary; it is
   1.250 +      missing a lot of detail.</para>
   1.251 +
   1.252 +    <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides
   1.253 +      a graphical representation of the history of the <filename
   1.254 +	class="directory">hello</filename> repository, to make it a
   1.255 +      little easier to see which direction history is
   1.256 +      <quote>flowing</quote> in.  We'll be returning to this figure
   1.257 +      several times in this chapter and the chapter that
   1.258 +      follows.</para>
   1.259 +
   1.260 +    <figure id="fig:tour-basic:history">
   1.261 +      <title>Graphical history of the <filename
   1.262 +	  class="directory">hello</filename> repository</title>
   1.263 +      <mediaobject>
   1.264 +	<imageobject><imagedata fileref="figs/tour-history.png"/></imageobject>
   1.265 +	<textobject><phrase>XXX add text</phrase></textobject>
   1.266 +      </mediaobject>
   1.267 +    </figure>
   1.268 +
   1.269 +    <sect2>
   1.270 +      <title>Changesets, revisions, and talking to other
   1.271 +	people</title>
   1.272 +
   1.273 +      <para id="x_25">As English is a notoriously sloppy language, and computer
   1.274 +	science has a hallowed history of terminological confusion
   1.275 +	(why use one term when four will do?), revision control has a
   1.276 +	variety of words and phrases that mean the same thing.  If you
   1.277 +	are talking about Mercurial history with other people, you
   1.278 +	will find that the word <quote>changeset</quote> is often
   1.279 +	compressed to <quote>change</quote> or (when written)
   1.280 +	<quote>cset</quote>, and sometimes a changeset is referred to
   1.281 +	as a <quote>revision</quote> or a <quote>rev</quote>.</para>
   1.282 +
   1.283 +      <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you
   1.284 +	use to refer to the concept of <quote>a changeset</quote>, the
   1.285 +	<emphasis>identifier</emphasis> that you use to refer to
   1.286 +	<quote>a <emphasis>specific</emphasis> changeset</quote> is of
   1.287 +	great importance. Recall that the <literal>changeset</literal>
   1.288 +	field in the output from <command role="hg-cmd">hg
   1.289 +	  log</command> identifies a changeset using both a number and
   1.290 +	a hexadecimal string.</para>
   1.291 +      <itemizedlist>
   1.292 +	<listitem><para id="x_27">The revision number is a handy
   1.293 +	    notation that is <emphasis>only valid in that
   1.294 +	      repository</emphasis>.</para></listitem>
   1.295 +	<listitem><para id="x_28">The hexadecimal string is the
   1.296 +	    <emphasis>permanent, unchanging identifier</emphasis> that
   1.297 +	    will always identify that exact changeset in
   1.298 +	    <emphasis>every</emphasis> copy of the
   1.299 +	    repository.</para></listitem></itemizedlist>
   1.300 +
   1.301 +      <para id="x_29">This distinction is important.  If you send
   1.302 +	someone an email talking about <quote>revision 33</quote>,
   1.303 +	there's a high likelihood that their revision 33 will
   1.304 +	<emphasis>not be the same</emphasis> as yours.  The reason for
   1.305 +	this is that a revision number depends on the order in which
   1.306 +	changes arrived in a repository, and there is no guarantee
   1.307 +	that the same changes will happen in the same order in
   1.308 +	different repositories. Three changes <literal>a,b,c</literal>
   1.309 +	can easily appear in one repository as
   1.310 +	<literal>0,1,2</literal>, while in another as
   1.311 +	<literal>0,2,1</literal>.</para>
   1.312 +
   1.313 +      <para id="x_2a">Mercurial uses revision numbers purely as a convenient
   1.314 +	shorthand.  If you need to discuss a changeset with someone,
   1.315 +	or make a record of a changeset for some other reason (for
   1.316 +	example, in a bug report), use the hexadecimal
   1.317 +	identifier.</para>
   1.318 +
   1.319 +    </sect2>
   1.320 +    <sect2>
   1.321 +      <title>Viewing specific revisions</title>
   1.322 +
   1.323 +      <para id="x_2b">To narrow the output of <command role="hg-cmd">hg
   1.324 +	  log</command> down to a single revision, use the <option
   1.325 +	  role="hg-opt-log">-r</option> (or <option
   1.326 +	  role="hg-opt-log">--rev</option>) option.  You can use
   1.327 +	either a revision number or a hexadecimal identifier,
   1.328 +	and you can provide as many revisions as you want.</para>
   1.329 +
   1.330 +      &interaction.tour.log-r;
   1.331 +
   1.332 +      <para id="x_2c">If you want to see the history of several revisions
   1.333 +	without having to list each one, you can use <emphasis>range
   1.334 +	  notation</emphasis>; this lets you express the idea <quote>I
   1.335 +	  want all revisions between <literal>abc</literal> and
   1.336 +	  <literal>def</literal>, inclusive</quote>.</para>
   1.337 +      
   1.338 +	&interaction.tour.log.range;
   1.339 +
   1.340 +      <para id="x_2d">Mercurial also honours the order in which you specify
   1.341 +	revisions, so <command role="hg-cmd">hg log -r 2:4</command>
   1.342 +	prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
   1.343 +	  4:2</command> prints 4, 3, and 2.</para>
   1.344 +
   1.345 +    </sect2>
   1.346 +    <sect2>
   1.347 +      <title>More detailed information</title>
   1.348 +
   1.349 +      <para id="x_2e">While the summary information printed by <command
   1.350 +	  role="hg-cmd">hg log</command> is useful if you already know
   1.351 +	what you're looking for, you may need to see a complete
   1.352 +	description of the change, or a list of the files changed, if
   1.353 +	you're trying to decide whether a changeset is the one you're
   1.354 +	looking for. The <command role="hg-cmd">hg log</command>
   1.355 +	command's <option role="hg-opt-global">-v</option> (or <option
   1.356 +	  role="hg-opt-global">--verbose</option>) option gives you
   1.357 +	this extra detail.</para>
   1.358 +
   1.359 +      &interaction.tour.log-v;
   1.360 +
   1.361 +      <para id="x_2f">If you want to see both the description and
   1.362 +	content of a change, add the <option
   1.363 +	  role="hg-opt-log">-p</option> (or <option
   1.364 +	  role="hg-opt-log">--patch</option>) option.  This displays
   1.365 +	the content of a change as a <emphasis>unified diff</emphasis>
   1.366 +	(if you've never seen a unified diff before, see <xref
   1.367 +	  linkend="sec:mq:patch"/> for an overview).</para>
   1.368 +
   1.369 +      &interaction.tour.log-vp;
   1.370 +
   1.371 +      <para id="x_67e">The <option role="hg-opt-log">-p</option> option is
   1.372 +	tremendously useful, so it's well worth remembering.</para>
   1.373 +
   1.374 +    </sect2>
   1.375 +  </sect1>
   1.376 +
   1.377 +  <sect1>
   1.378 +    <title>All about command options</title>
   1.379 +
   1.380 +    <para id="x_30">Let's take a brief break from exploring Mercurial commands
   1.381 +      to discuss a pattern in the way that they work; you may find
   1.382 +      this useful to keep in mind as we continue our tour.</para>
   1.383 +
   1.384 +    <para id="x_31">Mercurial has a consistent and straightforward approach to
   1.385 +      dealing with the options that you can pass to commands.  It
   1.386 +      follows the conventions for options that are common to modern
   1.387 +      Linux and Unix systems.</para>
   1.388 +
   1.389 +    <itemizedlist>
   1.390 +      <listitem>
   1.391 +	<para id="x_32">Every option has a long name.  For example, as
   1.392 +	  we've already seen, the <command role="hg-cmd">hg
   1.393 +	    log</command> command accepts a <option
   1.394 +	    role="hg-opt-log">--rev</option> option.</para>
   1.395 +      </listitem>
   1.396 +      <listitem>
   1.397 +	<para id="x_33">Most options have short names, too.  Instead
   1.398 +	  of <option role="hg-opt-log">--rev</option>, we can use
   1.399 +	  <option role="hg-opt-log">-r</option>.  (The reason that
   1.400 +	  some options don't have short names is that the options in
   1.401 +	  question are rarely used.)</para>
   1.402 +      </listitem>
   1.403 +      <listitem>
   1.404 +	<para id="x_34">Long options start with two dashes (e.g.
   1.405 +	  <option role="hg-opt-log">--rev</option>), while short
   1.406 +	  options start with one (e.g. <option
   1.407 +	    role="hg-opt-log">-r</option>).</para>
   1.408 +      </listitem>
   1.409 +      <listitem>
   1.410 +	<para id="x_35">Option naming and usage is consistent across
   1.411 +	  commands.  For example, every command that lets you specify
   1.412 +	  a changeset ID or revision number accepts both <option
   1.413 +	    role="hg-opt-log">-r</option> and <option
   1.414 +	    role="hg-opt-log">--rev</option> arguments.</para>
   1.415 +      </listitem>
   1.416 +      <listitem>
   1.417 +	<para id="x_67f">If you are using short options, you can save typing by
   1.418 +	  running them together. For example, the command <command
   1.419 +	    role="hg-cmd">hg log -v -p -r 2</command> can be written
   1.420 +	  as <command role="hg-cmd">hg log -vpr2</command>.</para>
   1.421 +      </listitem>
   1.422 +    </itemizedlist>
   1.423 +
   1.424 +    <para id="x_36">In the examples throughout this book, I usually
   1.425 +      use short options instead of long.  This simply reflects my own
   1.426 +      preference, so don't read anything significant into it.</para>
   1.427 +
   1.428 +    <para id="x_37">Most commands that print output of some kind will print more
   1.429 +      output when passed a <option role="hg-opt-global">-v</option>
   1.430 +      (or <option role="hg-opt-global">--verbose</option>) option, and
   1.431 +      less when passed <option role="hg-opt-global">-q</option> (or
   1.432 +      <option role="hg-opt-global">--quiet</option>).</para>
   1.433 +
   1.434 +    <note>
   1.435 +      <title>Option naming consistency</title>
   1.436 +
   1.437 +      <para id="x_680">Almost always, Mercurial commands use consistent option
   1.438 +	names to refer to the same concepts.  For instance, if a
   1.439 +	command deals with changesets, you'll always identify them
   1.440 +	with <option role="hg-opt-log">--rev</option> or <option
   1.441 +	  role="hg-opt-log">-r</option>.  This consistent use of
   1.442 +	option names makes it easier to remember what options a
   1.443 +	particular command takes.</para>
   1.444 +    </note>
   1.445 +
   1.446 +  </sect1>
   1.447 +  <sect1>
   1.448 +    <title>Making and reviewing changes</title>
   1.449 +
   1.450 +    <para id="x_38">Now that we have a grasp of viewing history in Mercurial,
   1.451 +      let's take a look at making some changes and examining
   1.452 +      them.</para>
   1.453 +
   1.454 +    <para id="x_39">The first thing we'll do is isolate our experiment in a
   1.455 +      repository of its own.  We use the <command role="hg-cmd">hg
   1.456 +	clone</command> command, but we don't need to clone a copy of
   1.457 +      the remote repository.  Since we already have a copy of it
   1.458 +      locally, we can just clone that instead.  This is much faster
   1.459 +      than cloning over the network, and cloning a local repository
   1.460 +      uses less disk space in most cases, too<footnote>
   1.461 +	<para id="x_681">The saving of space arises when source and destination
   1.462 +	  repositories are on the same filesystem, in which case
   1.463 +	  Mercurial will use hardlinks to do copy-on-write sharing of
   1.464 +	  its internal metadata.  If that explanation meant nothing to
   1.465 +	  you, don't worry: everything happens transparently and
   1.466 +	  automatically, and you don't need to understand it.</para>
   1.467 +	</footnote>.</para>
   1.468 +
   1.469 +    &interaction.tour.reclone;
   1.470 +
   1.471 +    <para id="x_3a">As an aside, it's often good practice to keep a
   1.472 +      <quote>pristine</quote> copy of a remote repository around,
   1.473 +      which you can then make temporary clones of to create sandboxes
   1.474 +      for each task you want to work on.  This lets you work on
   1.475 +      multiple tasks in parallel, each isolated from the others until
   1.476 +      it's complete and you're ready to integrate it back.  Because
   1.477 +      local clones are so cheap, there's almost no overhead to cloning
   1.478 +      and destroying repositories whenever you want.</para>
   1.479 +
   1.480 +    <para id="x_3b">In our <filename class="directory">my-hello</filename>
   1.481 +      repository, we have a file <filename>hello.c</filename> that
   1.482 +      contains the classic <quote>hello, world</quote> program.</para>
   1.483 +
   1.484 +    &interaction.tour.cat1;
   1.485 +
   1.486 +    <para id="x_682">Let's edit this file so that it prints a second line of
   1.487 +      output.</para>
   1.488 +
   1.489 +    &interaction.tour.cat2;
   1.490 +
   1.491 +    <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command>
   1.492 +      command will tell us what Mercurial knows about the files in the
   1.493 +      repository.</para>
   1.494 +
   1.495 +    &interaction.tour.status;
   1.496 +
   1.497 +    <para id="x_3d">The <command role="hg-cmd">hg status</command> command
   1.498 +      prints no output for some files, but a line starting with
   1.499 +      <quote><literal>M</literal></quote> for
   1.500 +      <filename>hello.c</filename>.  Unless you tell it to, <command
   1.501 +	role="hg-cmd">hg status</command> will not print any output
   1.502 +      for files that have not been modified.</para>
   1.503 +
   1.504 +    <para id="x_3e">The <quote><literal>M</literal></quote> indicates that
   1.505 +      Mercurial has noticed that we modified
   1.506 +      <filename>hello.c</filename>.  We didn't need to
   1.507 +      <emphasis>inform</emphasis> Mercurial that we were going to
   1.508 +      modify the file before we started, or that we had modified the
   1.509 +      file after we were done; it was able to figure this out
   1.510 +      itself.</para>
   1.511 +
   1.512 +    <para id="x_3f">It's somewhat helpful to know that we've modified
   1.513 +      <filename>hello.c</filename>, but we might prefer to know
   1.514 +      exactly <emphasis>what</emphasis> changes we've made to it.  To
   1.515 +      do this, we use the <command role="hg-cmd">hg diff</command>
   1.516 +      command.</para>
   1.517 +
   1.518 +    &interaction.tour.diff;
   1.519 +
   1.520 +    <tip>
   1.521 +      <title>Understanding patches</title>
   1.522 +
   1.523 +      <para id="x_683">Remember to take a look at <xref
   1.524 +	  linkend="sec:mq:patch"/> if you don't know how to read
   1.525 +	output above.</para>
   1.526 +    </tip>
   1.527 +  </sect1>
   1.528 +  <sect1>
   1.529 +    <title>Recording changes in a new changeset</title>
   1.530 +
   1.531 +    <para id="x_40">We can modify files, build and test our changes, and use
   1.532 +      <command role="hg-cmd">hg status</command> and <command
   1.533 +	role="hg-cmd">hg diff</command> to review our changes, until
   1.534 +      we're satisfied with what we've done and arrive at a natural
   1.535 +      stopping point where we want to record our work in a new
   1.536 +      changeset.</para>
   1.537 +
   1.538 +    <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets
   1.539 +      us create a new changeset; we'll usually refer to this as
   1.540 +      <quote>making a commit</quote> or
   1.541 +      <quote>committing</quote>.</para>
   1.542 +
   1.543 +    <sect2>
   1.544 +      <title>Setting up a username</title>
   1.545 +
   1.546 +      <para id="x_42">When you try to run <command role="hg-cmd">hg
   1.547 +	  commit</command> for the first time, it is not guaranteed to
   1.548 +	succeed.  Mercurial records your name and address with each
   1.549 +	change that you commit, so that you and others will later be
   1.550 +	able to tell who made each change.  Mercurial tries to
   1.551 +	automatically figure out a sensible username to commit the
   1.552 +	change with.  It will attempt each of the following methods,
   1.553 +	in order:</para>
   1.554 +      <orderedlist>
   1.555 +	<listitem><para id="x_43">If you specify a <option
   1.556 +	      role="hg-opt-commit">-u</option> option to the <command
   1.557 +	      role="hg-cmd">hg commit</command> command on the command
   1.558 +	    line, followed by a username, this is always given the
   1.559 +	    highest precedence.</para></listitem>
   1.560 +	<listitem><para id="x_44">If you have set the <envar>HGUSER</envar>
   1.561 +	    environment variable, this is checked
   1.562 +	    next.</para></listitem>
   1.563 +	<listitem><para id="x_45">If you create a file in your home
   1.564 +	    directory called <filename
   1.565 +	      role="special">.hgrc</filename>, with a <envar
   1.566 +	      role="rc-item-ui">username</envar> entry, that will be
   1.567 +	    used next.  To see what the contents of this file should
   1.568 +	    look like, refer to <xref
   1.569 +	      linkend="sec:tour-basic:username"/>
   1.570 +	    below.</para></listitem>
   1.571 +	<listitem><para id="x_46">If you have set the <envar>EMAIL</envar>
   1.572 +	    environment variable, this will be used
   1.573 +	    next.</para></listitem>
   1.574 +	<listitem><para id="x_47">Mercurial will query your system to find out
   1.575 +	    your local user name and host name, and construct a
   1.576 +	    username from these components. Since this often results
   1.577 +	    in a username that is not very useful, it will print a
   1.578 +	    warning if it has to do
   1.579 +	    this.</para></listitem>
   1.580 +      </orderedlist>
   1.581 +      <para id="x_48">If all of these mechanisms fail, Mercurial will
   1.582 +	  fail, printing an error message.  In this case, it will not
   1.583 +	  let you commit until you set up a
   1.584 +	  username.</para>
   1.585 +      <para id="x_49">You should think of the <envar>HGUSER</envar> environment
   1.586 +	variable and the <option role="hg-opt-commit">-u</option>
   1.587 +	option to the <command role="hg-cmd">hg commit</command>
   1.588 +	command as ways to <emphasis>override</emphasis> Mercurial's
   1.589 +	default selection of username.  For normal use, the simplest
   1.590 +	and most robust way to set a username for yourself is by
   1.591 +	creating a <filename role="special">.hgrc</filename> file; see
   1.592 +	below for details.</para>
   1.593 +      <sect3 id="sec:tour-basic:username">
   1.594 +	<title>Creating a Mercurial configuration file</title>
   1.595 +
   1.596 +	<para id="x_4a">To set a user name, use your favorite editor
   1.597 +	  to create a file called <filename
   1.598 +	    role="special">.hgrc</filename> in your home directory.
   1.599 +	  Mercurial will use this file to look up your personalised
   1.600 +	  configuration settings.  The initial contents of your
   1.601 +	  <filename role="special">.hgrc</filename> should look like
   1.602 +	  this.</para>
   1.603 +
   1.604 +	<tip>
   1.605 +	  <title><quote>Home directory</quote> on Windows</title>
   1.606 +
   1.607 +	  <para id="x_716">When we refer to your home directory, on an English
   1.608 +	    language installation of Windows this will usually be a
   1.609 +	    folder named after your user name in
   1.610 +	    <filename>C:\Documents and Settings</filename>.  You can
   1.611 +	    find out the exact name of your home directory by opening
   1.612 +	    a command prompt window and running the following
   1.613 +	    command.</para>
   1.614 +
   1.615 +	  <screen><prompt>C:\></prompt> <userinput>echo %UserProfile%</userinput></screen>
   1.616 +	</tip>
   1.617 +
   1.618 +	<programlisting># This is a Mercurial configuration file.
   1.619 +[ui]
   1.620 +username = Firstname Lastname &lt;email.address@example.net&gt;</programlisting>
   1.621 +
   1.622 +	<para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a
   1.623 +	  <emphasis>section</emphasis> of the config file, so you can
   1.624 +	  read the <quote><literal>username = ...</literal></quote>
   1.625 +	  line as meaning <quote>set the value of the
   1.626 +	    <literal>username</literal> item in the
   1.627 +	    <literal>ui</literal> section</quote>. A section continues
   1.628 +	  until a new section begins, or the end of the file.
   1.629 +	  Mercurial ignores empty lines and treats any text from
   1.630 +	  <quote><literal>#</literal></quote> to the end of a line as
   1.631 +	  a comment.</para>
   1.632 +      </sect3>
   1.633 +
   1.634 +      <sect3>
   1.635 +	<title>Choosing a user name</title>
   1.636 +
   1.637 +	<para id="x_4c">You can use any text you like as the value of
   1.638 +	  the <literal>username</literal> config item, since this
   1.639 +	  information is for reading by other people, but will not be
   1.640 +	  interpreted by Mercurial.  The convention that most people
   1.641 +	  follow is to use their name and email address, as in the
   1.642 +	  example above.</para>
   1.643 +	<note>
   1.644 +	  <para id="x_4d">Mercurial's built-in web server obfuscates
   1.645 +	    email addresses, to make it more difficult for the email
   1.646 +	    harvesting tools that spammers use. This reduces the
   1.647 +	    likelihood that you'll start receiving more junk email if
   1.648 +	    you publish a Mercurial repository on the
   1.649 +	    web.</para></note>
   1.650 +      </sect3>
   1.651 +    </sect2>
   1.652 +    <sect2>
   1.653 +      <title>Writing a commit message</title>
   1.654 +
   1.655 +      <para id="x_4e">When we commit a change, Mercurial drops us into
   1.656 +	a text editor, to enter a message that will describe the
   1.657 +	modifications we've made in this changeset.  This is called
   1.658 +	the <emphasis>commit message</emphasis>.  It will be a record
   1.659 +	for readers of what we did and why, and it will be printed by
   1.660 +	<command role="hg-cmd">hg log</command> after we've finished
   1.661 +	committing.</para>
   1.662 +
   1.663 +       &interaction.tour.commit;
   1.664 +
   1.665 +      <para id="x_4f">The editor that the <command role="hg-cmd">hg
   1.666 +	  commit</command> command drops us into will contain an empty
   1.667 +	line or two, followed by a number of lines starting with
   1.668 +	<quote><literal>HG:</literal></quote>.</para>
   1.669 +
   1.670 +    <programlisting>
   1.671 +This is where I type my commit comment.
   1.672 +
   1.673 +HG: Enter commit message.  Lines beginning with 'HG:' are removed.
   1.674 +HG: --
   1.675 +HG: user: Bryan O'Sullivan &lt;bos@serpentine.com&gt;
   1.676 +HG: branch 'default'
   1.677 +HG: changed hello.c</programlisting>
   1.678 +
   1.679 +      <para id="x_50">Mercurial ignores the lines that start with
   1.680 +	<quote><literal>HG:</literal></quote>; it uses them only to
   1.681 +	tell us which files it's recording changes to.  Modifying or
   1.682 +	deleting these lines has no effect.</para>
   1.683 +    </sect2>
   1.684 +    <sect2>
   1.685 +      <title>Writing a good commit message</title>
   1.686 +
   1.687 +      <para id="x_51">Since <command role="hg-cmd">hg log</command>
   1.688 +	only prints the first line of a commit message by default,
   1.689 +	it's best to write a commit message whose first line stands
   1.690 +	alone.  Here's a real example of a commit message that
   1.691 +	<emphasis>doesn't</emphasis> follow this guideline, and hence
   1.692 +	has a summary that is not readable.</para>
   1.693 +
   1.694 +      <programlisting>
   1.695 +changeset:   73:584af0e231be
   1.696 +user:        Censored Person &lt;censored.person@example.org&gt;
   1.697 +date:        Tue Sep 26 21:37:07 2006 -0700
   1.698 +summary:     include buildmeister/commondefs. Add exports.</programlisting>
   1.699 +
   1.700 +      <para id="x_52">As far as the remainder of the contents of the
   1.701 +	commit message are concerned, there are no hard-and-fast
   1.702 +	rules.  Mercurial itself doesn't interpret or care about the
   1.703 +	contents of the commit message, though your project may have
   1.704 +	policies that dictate a certain kind of formatting.</para>
   1.705 +      <para id="x_53">My personal preference is for short, but
   1.706 +	informative, commit messages that tell me something that I
   1.707 +	can't figure out with a quick glance at the output of <command
   1.708 +	  role="hg-cmd">hg log --patch</command>.</para>
   1.709 +      <para id="x_55">If we run the <command role="hg-cmd">hg
   1.710 +	  commit</command> command without any arguments, it records
   1.711 +	all of the changes we've made, as reported by <command
   1.712 +	  role="hg-cmd">hg status</command> and <command
   1.713 +	  role="hg-cmd">hg diff</command>.</para>
   1.714 +
   1.715 +      <note>
   1.716 +	<title>A surprise for Subversion users</title>
   1.717 +
   1.718 +	<para id="x_717">Like other Mercurial commands, if we don't supply
   1.719 +	  explicit names to commit to the <command role="hg-cmd">hg
   1.720 +	    commit</command>, it will operate across a repository's
   1.721 +	  entire working directory.  Be wary of this if you're coming
   1.722 +	  from the Subversion or CVS world, since you might expect it
   1.723 +	  to operate only on the current directory that you happen to
   1.724 +	  be visiting and its subdirectories.</para>
   1.725 +      </note>
   1.726 +    </sect2>
   1.727 +
   1.728 +    <sect2>
   1.729 +      <title>Aborting a commit</title>
   1.730 +
   1.731 +      <para id="x_54">If you decide that you don't want to commit
   1.732 +	while in the middle of editing a commit message, simply exit
   1.733 +	from your editor without saving the file that it's editing.
   1.734 +	This will cause nothing to happen to either the repository or
   1.735 +	the working directory.</para>
   1.736 +    </sect2>
   1.737 +
   1.738 +    <sect2>
   1.739 +      <title>Admiring our new handiwork</title>
   1.740 +
   1.741 +      <para id="x_56">Once we've finished the commit, we can use the
   1.742 +	<command role="hg-cmd">hg tip</command> command to display the
   1.743 +	changeset we just created.  This command produces output that
   1.744 +	is identical to <command role="hg-cmd">hg log</command>, but
   1.745 +	it only displays the newest revision in the repository.</para>
   1.746 +
   1.747 +      &interaction.tour.tip;
   1.748 +
   1.749 +      <para id="x_57">We refer to the newest revision in the
   1.750 +	repository as the <emphasis>tip revision</emphasis>, or simply
   1.751 +	the <emphasis>tip</emphasis>.</para>
   1.752 +
   1.753 +      <para id="x_684">By the way, the <command role="hg-cmd">hg tip</command>
   1.754 +	command accepts many of the same options as <command
   1.755 +	  role="hg-cmd">hg log</command>, so <option
   1.756 +	  role="hg-opt-global">-v</option> above indicates <quote>be
   1.757 +	  verbose</quote>, <option role="hg-opt-tip">-p</option>
   1.758 +	specifies <quote>print a patch</quote>.  The use of <option
   1.759 +	  role="hg-opt-tip">-p</option> to print patches is another
   1.760 +	example of the consistent naming we mentioned earlier.</para>
   1.761 +    </sect2>
   1.762 +  </sect1>
   1.763 +
   1.764 +  <sect1>
   1.765 +    <title>Sharing changes</title>
   1.766 +
   1.767 +    <para id="x_58">We mentioned earlier that repositories in
   1.768 +      Mercurial are self-contained.  This means that the changeset we
   1.769 +      just created exists only in our <filename
   1.770 +	class="directory">my-hello</filename> repository.  Let's look
   1.771 +      at a few ways that we can propagate this change into other
   1.772 +      repositories.</para>
   1.773 +
   1.774 +    <sect2 id="sec:tour:pull">
   1.775 +      <title>Pulling changes from another repository</title>
   1.776 +
   1.777 +      <para id="x_59">To get started, let's clone our original
   1.778 +	<filename class="directory">hello</filename> repository, which
   1.779 +	does not contain the change we just committed.  We'll call our
   1.780 +	temporary repository <filename
   1.781 +	  class="directory">hello-pull</filename>.</para>
   1.782 +
   1.783 +      &interaction.tour.clone-pull;
   1.784 +
   1.785 +      <para id="x_5a">We'll use the <command role="hg-cmd">hg
   1.786 +	  pull</command> command to bring changes from <filename
   1.787 +	  class="directory">my-hello</filename> into <filename
   1.788 +	  class="directory">hello-pull</filename>.  However, blindly
   1.789 +	pulling unknown changes into a repository is a somewhat scary
   1.790 +	prospect.  Mercurial provides the <command role="hg-cmd">hg
   1.791 +	  incoming</command> command to tell us what changes the
   1.792 +	<command role="hg-cmd">hg pull</command> command
   1.793 +	<emphasis>would</emphasis> pull into the repository, without
   1.794 +	actually pulling the changes in.</para>
   1.795 +
   1.796 +      &interaction.tour.incoming;
   1.797 +
   1.798 +      <para id="x_5c">Bringing changes into a repository is a simple
   1.799 +	matter of running the <command role="hg-cmd">hg pull</command>
   1.800 +	command, and optionally telling it which repository to pull from.</para>
   1.801 +
   1.802 +      &interaction.tour.pull;
   1.803 +
   1.804 +      <para id="x_5d">As you can see from the before-and-after output
   1.805 +	of <command role="hg-cmd">hg tip</command>, we have
   1.806 +	successfully pulled changes into our repository.  However,
   1.807 +	Mercurial separates pulling changes in from updating the
   1.808 +	working directory. There remains one step before we will see
   1.809 +	the changes that we just pulled appear in the working
   1.810 +	directory.</para>
   1.811 +
   1.812 +      <tip>
   1.813 +	<title>Pulling specific changes</title>
   1.814 +
   1.815 +	<para id="x_5b">It is possible that due to the delay between
   1.816 +	  running <command role="hg-cmd">hg incoming</command> and
   1.817 +	  <command role="hg-cmd">hg pull</command>, you may not see
   1.818 +	  all changesets that will be brought from the other
   1.819 +	  repository. Suppose you're pulling changes from a repository
   1.820 +	  on the network somewhere. While you are looking at the
   1.821 +	  <command role="hg-cmd">hg incoming</command> output, and
   1.822 +	  before you pull those changes, someone might have committed
   1.823 +	  something in the remote repository. This means that it's
   1.824 +	  possible to pull more changes than you saw when using
   1.825 +	  <command role="hg-cmd">hg incoming</command>.</para>
   1.826 +
   1.827 +	<para id="x_718">If you only want to pull precisely the changes that were
   1.828 +	  listed by <command role="hg-cmd">hg incoming</command>, or
   1.829 +	  you have some other reason to pull a subset of changes,
   1.830 +	  simply identify the change that you want to pull by its
   1.831 +	  changeset ID, e.g. <command>hg pull
   1.832 +	    -r7e95bb</command>.</para>
   1.833 +      </tip>
   1.834 +    </sect2>
   1.835 +
   1.836 +    <sect2>
   1.837 +      <title>Updating the working directory</title>
   1.838 +
   1.839 +      <para id="x_5e">We have so far glossed over the relationship
   1.840 +	between a repository and its working directory.  The <command
   1.841 +	  role="hg-cmd">hg pull</command> command that we ran in
   1.842 +	<xref linkend="sec:tour:pull"/> brought changes into the
   1.843 +	repository, but if we check, there's no sign of those changes
   1.844 +	in the working directory.  This is because <command
   1.845 +	  role="hg-cmd">hg pull</command> does not (by default) touch
   1.846 +	the working directory.  Instead, we use the <command
   1.847 +	  role="hg-cmd">hg update</command> command to do this.</para>
   1.848 +
   1.849 +      &interaction.tour.update;
   1.850 +
   1.851 +      <para id="x_5f">It might seem a bit strange that <command
   1.852 +	  role="hg-cmd">hg pull</command> doesn't update the working
   1.853 +	directory automatically.  There's actually a good reason for
   1.854 +	this: you can use <command role="hg-cmd">hg update</command>
   1.855 +	to update the working directory to the state it was in at
   1.856 +	<emphasis>any revision</emphasis> in the history of the
   1.857 +	repository.  If you had the working directory updated to an
   1.858 +	old revision&emdash;to hunt down the origin of a bug,
   1.859 +	say&emdash;and ran a <command role="hg-cmd">hg pull</command>
   1.860 +	which automatically updated the working directory to a new
   1.861 +	revision, you might not be terribly happy.</para>
   1.862 +
   1.863 +      <para id="x_60">Since pull-then-update is such a common sequence
   1.864 +	of operations, Mercurial lets you combine the two by passing
   1.865 +	the <option role="hg-opt-pull">-u</option> option to <command
   1.866 +	  role="hg-cmd">hg pull</command>.</para>
   1.867 +
   1.868 +      <para id="x_61">If you look back at the output of <command
   1.869 +	  role="hg-cmd">hg pull</command> in <xref
   1.870 +	    linkend="sec:tour:pull"/> when we ran it without <option
   1.871 +	  role="hg-opt-pull">-u</option>, you can see that it printed
   1.872 +	a helpful reminder that we'd have to take an explicit step to
   1.873 +	update the working directory.</para>
   1.874 +
   1.875 +      <para id="x_62">To find out what revision the working directory
   1.876 +	is at, use the <command role="hg-cmd">hg parents</command>
   1.877 +	command.</para>
   1.878 +
   1.879 +      &interaction.tour.parents;
   1.880 +
   1.881 +      <para id="x_63">If you look back at <xref
   1.882 +	  linkend="fig:tour-basic:history"/>, you'll see arrows
   1.883 +	connecting each changeset.  The node that the arrow leads
   1.884 +	<emphasis>from</emphasis> in each case is a parent, and the
   1.885 +	node that the arrow leads <emphasis>to</emphasis> is its
   1.886 +	child.  The working directory has a parent in just the same
   1.887 +	way; this is the changeset that the working directory
   1.888 +	currently contains.</para>
   1.889 +
   1.890 +      <para id="x_64">To update the working directory to a particular
   1.891 +	revision, give a revision number or changeset ID to the
   1.892 +	<command role="hg-cmd">hg update</command> command.</para>
   1.893 +
   1.894 +      &interaction.tour.older;
   1.895 +
   1.896 +      <para id="x_65">If you omit an explicit revision, <command
   1.897 +	  role="hg-cmd">hg update</command> will update to the tip
   1.898 +	revision, as shown by the second call to <command
   1.899 +	  role="hg-cmd">hg update</command> in the example
   1.900 +	above.</para>
   1.901 +    </sect2>
   1.902 +
   1.903 +    <sect2>
   1.904 +      <title>Pushing changes to another repository</title>
   1.905 +
   1.906 +      <para id="x_66">Mercurial lets us push changes to another
   1.907 +	repository, from the repository we're currently visiting. As
   1.908 +	with the example of <command role="hg-cmd">hg pull</command>
   1.909 +	above, we'll create a temporary repository to push our changes
   1.910 +	into.</para>
   1.911 +
   1.912 +      &interaction.tour.clone-push;
   1.913 +
   1.914 +      <para id="x_67">The <command role="hg-cmd">hg outgoing</command>
   1.915 +	command tells us what changes would be pushed into another
   1.916 +	repository.</para>
   1.917 +
   1.918 +      &interaction.tour.outgoing;
   1.919 +
   1.920 +      <para id="x_68">And the <command role="hg-cmd">hg push</command>
   1.921 +	command does the actual push.</para>
   1.922 +
   1.923 +      &interaction.tour.push;
   1.924 +
   1.925 +      <para id="x_69">As with <command role="hg-cmd">hg
   1.926 +	  pull</command>, the <command role="hg-cmd">hg push</command>
   1.927 +	command does not update the working directory in the
   1.928 +	repository that it's pushing changes into. Unlike <command
   1.929 +	  role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg
   1.930 +	  push</command> does not provide a <literal>-u</literal>
   1.931 +	option that updates the other repository's working directory.
   1.932 +	This asymmetry is deliberate: the repository we're pushing to
   1.933 +	might be on a remote server and shared between several people.
   1.934 +	If we were to update its working directory while someone was
   1.935 +	working in it, their work would be disrupted.</para>
   1.936 +
   1.937 +      <para id="x_6a">What happens if we try to pull or push changes
   1.938 +	  and the receiving repository already has those changes?
   1.939 +	  Nothing too exciting.</para>
   1.940 +
   1.941 +      &interaction.tour.push.nothing;
   1.942 +    </sect2>
   1.943 +
   1.944 +    <sect2>
   1.945 +      <title>Default locations</title>
   1.946 +
   1.947 +      <para id="x_719">When we clone a repository, Mercurial records the location
   1.948 +	of the repository we cloned in the
   1.949 +	<filename>.hg/hgrc</filename> file of the new repository.  If
   1.950 +	we don't supply a location to <command>hg pull</command> from
   1.951 +	or <command>hg push</command> to, those commands will use this
   1.952 +	location as a default.  The <command>hg incoming</command>
   1.953 +	and <command>hg outgoing</command> commands do so too.</para>
   1.954 +
   1.955 +      <para id="x_71a">If you open a repository's <filename>.hg/hgrc</filename>
   1.956 +	file in a text editor, you will see contents like the
   1.957 +	following.</para>
   1.958 +
   1.959 +      <programlisting>[paths]
   1.960 +default = http://www.selenic.com/repo/hg</programlisting>
   1.961 +
   1.962 +      <para id="x_71b">It is possible&emdash;and often useful&emdash;to have the
   1.963 +	default location for <command>hg push</command> and
   1.964 +	<command>hg outgoing</command> be different from those for
   1.965 +	<command>hg pull</command> and <command>hg incoming</command>.
   1.966 +	We can do this by adding a <literal>default-push</literal>
   1.967 +	entry to the <literal>[paths]</literal> section of the
   1.968 +	<filename>.hg/hgrc</filename> file, as follows.</para>
   1.969 +
   1.970 +      <programlisting>[paths]
   1.971 +default = http://www.selenic.com/repo/hg
   1.972 +default-push = http://hg.example.com/hg</programlisting>
   1.973 +    </sect2>
   1.974 +
   1.975 +    <sect2>
   1.976 +      <title>Sharing changes over a network</title>
   1.977 +
   1.978 +      <para id="x_6b">The commands we have covered in the previous few
   1.979 +	  sections are not limited to working with local repositories.
   1.980 +	  Each works in exactly the same fashion over a network
   1.981 +	  connection; simply pass in a URL instead of a local
   1.982 +	  path.</para>
   1.983 +	
   1.984 +      &interaction.tour.outgoing.net;
   1.985 +
   1.986 +      <para id="x_6c">In this example, we can see what changes we
   1.987 +	could push to the remote repository, but the repository is
   1.988 +	understandably not set up to let anonymous users push to
   1.989 +	it.</para>
   1.990 +
   1.991 +      &interaction.tour.push.net;
   1.992 +    </sect2>
   1.993 +  </sect1>
   1.994 +
   1.995 +  <sect1>
   1.996 +    <title>Starting a new project</title>
   1.997 +
   1.998 +    <para id="x_71c">It is just as easy to begin a new project as to work on one
   1.999 +      that already exists.  The <command>hg init</command> command
  1.1000 +      creates a new, empty Mercurial repository.</para>
  1.1001 +
  1.1002 +    &interaction.ch01-new.init;
  1.1003 +
  1.1004 +    <para id="x_71d">This simply creates a repository named
  1.1005 +      <filename>myproject</filename> in the current directory.</para>
  1.1006 +
  1.1007 +    &interaction.ch01-new.ls;
  1.1008 +
  1.1009 +    <para id="x_71e">We can tell that <filename>myproject</filename> is a
  1.1010 +      Mercurial repository, because it contains a
  1.1011 +      <filename>.hg</filename> directory.</para>
  1.1012 +
  1.1013 +    &interaction.ch01-new.ls2;
  1.1014 +
  1.1015 +    <para id="x_71f">If we want to add some pre-existing files to the repository,
  1.1016 +      we copy them into place, and tell Mercurial to start tracking
  1.1017 +      them using the <command>hg add</command> command.</para>
  1.1018 +
  1.1019 +    &interaction.ch01-new.add;
  1.1020 +
  1.1021 +    <para id="x_720">Once we are satisfied that our project looks right, we
  1.1022 +      commit our changes.</para>
  1.1023 +
  1.1024 +    &interaction.ch01-new.commit;
  1.1025 +
  1.1026 +    <para id="x_721">It takes just a few moments to start using Mercurial on a
  1.1027 +      new project, which is part of its appeal. Revision control is
  1.1028 +      now so easy to work with, we can use it on the smallest of
  1.1029 +      projects that we might not have considered with a more
  1.1030 +      complicated tool.</para>
  1.1031 +  </sect1>
  1.1032 +</chapter>
  1.1033 +
  1.1034 +<!--
  1.1035 +local variables: 
  1.1036 +sgml-parent-document: ("00book.xml" "book" "chapter")
  1.1037 +end:
  1.1038 +-->