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