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