bos@553: <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
bos@553: 
bos@559: <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: 
bos@559:   <sect1 id="sec:tour:install">
bos@553:     <title>Installing Mercurial on your system</title>
bos@553: 
bos@584:     <para id="x_1">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@609:       <title>Windows</title>
bos@609: 
bos@609:       <para id="x_c">The best version of Mercurial for Windows is
bos@609: 	TortoiseHg, which can be found at <ulink
bos@609: 	  url="http://bitbucket.org/tortoisehg/stable/wiki/Home">http://bitbucket.org/tortoisehg/stable/wiki/Home</ulink>. 
bos@609: 	This package has no external dependencies; it <quote>just
bos@609: 	  works</quote>.  It provides both command line and graphical
bos@609: 	user interfaces.</para>
bos@609: 
bos@609:     </sect2>
bos@609: 
bos@609:     <sect2>
bos@609:       <title>Mac OS X</title>
bos@609: 
bos@609:       <para id="x_a">Lee Cantey publishes an installer of Mercurial
bos@609: 	for Mac OS X at <ulink
bos@609: 	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para>
bos@609:     </sect2>
bos@609: 
bos@609:     <sect2>
bos@553:       <title>Linux</title>
bos@553: 
bos@584:       <para id="x_2">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@584:       <para id="x_3">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@609: 	<listitem><para id="x_4">Ubuntu and Debian:</para>
bos@579: 	  <programlisting>apt-get install mercurial</programlisting></listitem>
bos@609: 	<listitem><para id="x_5">Fedora and OpenSUSE:</para>
bos@579: 	  <programlisting>yum install mercurial</programlisting></listitem>
bos@584: 	<listitem><para id="x_6">Gentoo:</para>
bos@553: 	  <programlisting>emerge mercurial</programlisting></listitem>
bos@553:       </itemizedlist>
bos@553: 
bos@553:     </sect2>
bos@553:     <sect2>
bos@553:       <title>Solaris</title>
bos@553: 
bos@584:       <para id="x_9">SunFreeWare, at <ulink
bos@553: 	  url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 
bos@609: 	provides prebuilt packages of Mercurial.</para>
bos@609: 
bos@609:     </sect2>
bos@609: 
bos@553:   </sect1>
bos@609: 
bos@553:   <sect1>
bos@553:     <title>Getting started</title>
bos@553: 
bos@584:     <para id="x_e">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@584:       <para id="x_f">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@584: 	<para id="x_10">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@584:     <para id="x_11">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@584:     <para id="x_12">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@584:       <para id="x_13"><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@609: 	makes an identical copy of an existing repository.</para>
bos@559: 
bos@566:       &interaction.tour.clone;
bos@559: 
bos@609:       <para>One advantage of using <command role="hg-cmd">hg
bos@609: 	  clone</command> is that, as we can see above, it lets us clone
bos@609: 	repositories over the network.  Another is that it remembers
bos@609: 	where we cloned from, which we'll find useful soon when we
bos@609: 	want to fetch new changes from another repository.</para>
bos@609: 
bos@584:       <para id="x_14">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@584:       <para id="x_15">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@609:       <para id="x_16">Every Mercurial repository is complete,
bos@609: 	self-contained, and independent.  It contains its own private
bos@609: 	copy of a project's files and history.  As we just mentioned,
bos@609: 	a cloned repository remembers the location of the repository
bos@609: 	it was cloned from, but Mercurial will not communicate with
bos@609: 	that repository, or any other, unless you tell it to.</para>
bos@553: 
bos@584:       <para id="x_17">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@584:       <para id="x_18">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@584:       <para id="x_19">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@584:       <para id="x_1a">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@584:     <para id="x_1b">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@609:       the history of changes in the repository.</para>
bos@559: 
bos@566:     &interaction.tour.log;
bos@559: 
bos@584:     <para id="x_1c">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@584:     <para id="x_1d">The fields in a record of output from <command
bos@553: 	role="hg-cmd">hg log</command> are as follows.</para>
bos@609: 
bos@553:     <itemizedlist>
bos@609:       <listitem><para id="x_1e"><literal>changeset</literal>: This
bos@609: 	  field has the format of a number, followed by a colon,
bos@609: 	  followed by a hexadecimal (or <emphasis>hex</emphasis>)
bos@609: 	  string.  These are <emphasis>identifiers</emphasis> for the
bos@609: 	  changeset.  The hex string is a unique identifier: the same
bos@609: 	  hex string will always refer to the same changeset. The
bos@609: 	  number is shorter and easier to type than the hex string,
bos@609: 	  but it isn't unique: the same number in two different clones
bos@609: 	  of a repository may identify different changesets.  Why
bos@609: 	  provide the number at all, then?  For local
bos@609: 	  convenience.</para>
bos@609:       </listitem>
bos@584:       <listitem><para id="x_1f"><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@584:       <listitem><para id="x_20"><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@584:       <listitem><para id="x_21"><literal>summary</literal>: The first line of
bos@553: 	  the text message that the creator of the changeset entered
bos@609: 	  to describe the changeset.</para></listitem>
bos@609:       <listitem>
bos@609: 	<para>Some changesets, such as the first in the list above,
bos@609: 	  have a <literal>tag</literal> field.  A tag is another way
bos@609: 	  to identify a changeset, by giving it an easy-to-remember
bos@609: 	  name. (The tag named <literal>tip</literal> is special: it
bos@609: 	  always refers to the newest change in a repository.)</para>
bos@609:       </listitem>
bos@609:     </itemizedlist>
bos@609: 
bos@609:     <para id="x_22">The default output printed by <command
bos@609: 	role="hg-cmd">hg log</command> is purely a summary; it is
bos@609:       missing a lot of detail.</para>
bos@553: 
bos@592:     <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides
bos@592:       a 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: 
bos@591:     <figure id="fig:tour-basic:history">
bos@591:       <title>Graphical history of the <filename
bos@591: 	  class="directory">hello</filename> repository</title>
bos@558:       <mediaobject>
bos@594: 	<imageobject><imagedata fileref="figs/tour-history.png"/></imageobject>
bos@558: 	<textobject><phrase>XXX add text</phrase></textobject>
bos@558:       </mediaobject>
bos@591:     </figure>
bos@553: 
bos@553:     <sect2>
bos@553:       <title>Changesets, revisions, and talking to other
bos@553: 	people</title>
bos@553: 
bos@584:       <para id="x_25">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@584:       <para id="x_26">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@609: 	<listitem><para id="x_27">The revision number is a handy
bos@609: 	    notation that is <emphasis>only valid in that
bos@609: 	      repository</emphasis>.</para></listitem>
bos@609: 	<listitem><para id="x_28">The hexadecimal 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@609: 
bos@609:       <para id="x_29">This distinction is important.  If you send
bos@609: 	someone an email talking about <quote>revision 33</quote>,
bos@609: 	there's a high likelihood that their revision 33 will
bos@609: 	<emphasis>not be the same</emphasis> as yours.  The reason for
bos@609: 	this is that a revision number depends on the order in which
bos@609: 	changes arrived in a repository, and there is no guarantee
bos@609: 	that the same changes will happen in the same order in
bos@609: 	different repositories. Three changes <literal>a,b,c</literal>
bos@609: 	can easily appear in one repository as
bos@609: 	<literal>0,1,2</literal>, while in another as
bos@609: 	<literal>0,2,1</literal>.</para>
bos@553: 
bos@584:       <para id="x_2a">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@584:       <para id="x_2b">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@609: 	either a revision number or a hexadecimal 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@584:       <para id="x_2c">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@584:       <para id="x_2d">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@584:       <para id="x_2e">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@592:       <para id="x_2f">If you want to see both the description and
bos@592: 	content of a change, add the <option
bos@592: 	  role="hg-opt-log">-p</option> (or <option
bos@592: 	  role="hg-opt-log">--patch</option>) option.  This displays
bos@592: 	the content of a change as a <emphasis>unified diff</emphasis>
bos@592: 	(if you've never seen a unified diff before, see <xref
bos@592: 	  linkend="sec:mq:patch"/> for an overview).</para>
bos@559: 
bos@566:       &interaction.tour.log-vp;
bos@553: 
bos@609:       <para>The <option role="hg-opt-log">-p</option> option is
bos@609: 	tremendously useful, so it's well worth remembering.</para>
bos@609: 
bos@553:     </sect2>
bos@553:   </sect1>
bos@609: 
bos@553:   <sect1>
bos@553:     <title>All about command options</title>
bos@553: 
bos@584:     <para id="x_30">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@584:     <para id="x_31">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@609: 
bos@553:     <itemizedlist>
bos@609:       <listitem>
bos@609: 	<para id="x_32">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@609: 	    role="hg-opt-log">--rev</option> option.</para>
bos@609:       </listitem>
bos@609:       <listitem>
bos@609: 	<para id="x_33">Most options have short names, too.  Instead
bos@609: 	  of <option role="hg-opt-log">--rev</option>, we can use
bos@609: 	  <option role="hg-opt-log">-r</option>.  (The reason that
bos@609: 	  some options don't have short names is that the options in
bos@609: 	  question are rarely used.)</para>
bos@609:       </listitem>
bos@609:       <listitem>
bos@609: 	<para id="x_34">Long options start with two dashes (e.g.
bos@609: 	  <option role="hg-opt-log">--rev</option>), while short
bos@609: 	  options start with one (e.g. <option
bos@609: 	    role="hg-opt-log">-r</option>).</para>
bos@609:       </listitem>
bos@609:       <listitem>
bos@609: 	<para id="x_35">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@609: 	    role="hg-opt-log">--rev</option> arguments.</para>
bos@609:       </listitem>
bos@609:       <listitem>
bos@609: 	<para>If you are using short options, you can save typing by
bos@609: 	  running them together. For example, the command <command
bos@609: 	    role="hg-cmd">hg log -v -p -r 2</command> can be written
bos@609: 	  as <command role="hg-cmd">hg log -vpr2</command>.</para>
bos@609:       </listitem>
bos@609:     </itemizedlist>
bos@609: 
bos@584:     <para id="x_36">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@584:     <para id="x_37">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@609:     <note>
bos@609:       <title>Option naming consistency</title>
bos@609: 
bos@609:       <para>Almost always, Mercurial commands use consistent option
bos@609: 	names to refer to the same concepts.  For instance, if a
bos@609: 	command deals with changesets, you'll always identify them
bos@609: 	with <option role="hg-opt-log">--rev</option> or <option
bos@609: 	  role="hg-opt-log">-r</option>.  This consistent use of
bos@609: 	option names makes it easier to remember what options a
bos@609: 	particular command takes.</para>
bos@609:     </note>
bos@609: 
bos@553:   </sect1>
bos@553:   <sect1>
bos@553:     <title>Making and reviewing changes</title>
bos@553: 
bos@584:     <para id="x_38">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@584:     <para id="x_39">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@609:       uses less disk space in most cases, too<footnote>
bos@609: 	<para>The saving of space arises when source and destination
bos@609: 	  repositories are on the same filesystem, in which case
bos@609: 	  Mercurial will use hardlinks to do copy-on-write sharing of
bos@609: 	  its internal metadata.  If that explanation meant nothing to
bos@609: 	  you, don't worry: everything happens transparently and
bos@609: 	  automatically, and you don't need to understand it.</para>
bos@609: 	</footnote>.</para>
bos@559: 
bos@566:     &interaction.tour.reclone;
bos@559: 
bos@584:     <para id="x_3a">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@584:     <para id="x_3b">In our <filename class="directory">my-hello</filename>
bos@553:       repository, we have a file <filename>hello.c</filename> that
bos@609:       contains the classic <quote>hello, world</quote> program.</para>
bos@609: 
bos@609:     &interaction.tour.cat1;
bos@609: 
bos@609:     <para>Let's edit this file so that it prints a second line of
bos@609:       output.</para>
bos@609: 
bos@609:     &interaction.tour.cat2;
bos@553: 
bos@584:     <para id="x_3c">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@584:     <para id="x_3d">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@584:     <para id="x_3e">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@609:     <para id="x_3f">It's somewhat 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@609:     <tip>
bos@609:       <title>Understanding patches</title>
bos@609: 
bos@609:       <para>Remember to take a look at <xref
bos@609: 	  linkend="sec:mq:patch"/> if you don't know how to read
bos@609: 	output above.</para>
bos@609:     </tip>
bos@553:   </sect1>
bos@553:   <sect1>
bos@553:     <title>Recording changes in a new changeset</title>
bos@553: 
bos@584:     <para id="x_40">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@584:     <para id="x_41">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@584:       <para id="x_42">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@584: 	<listitem><para id="x_43">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@584: 	<listitem><para id="x_44">If you have set the <envar>HGUSER</envar>
bos@553: 	    environment variable, this is checked
bos@553: 	    next.</para></listitem>
bos@592: 	<listitem><para id="x_45">If you create a file in your home
bos@592: 	    directory called <filename
bos@592: 	      role="special">.hgrc</filename>, with a <envar
bos@592: 	      role="rc-item-ui">username</envar> entry, that will be
bos@592: 	    used next.  To see what the contents of this file should
bos@592: 	    look like, refer to <xref
bos@558: 	      linkend="sec:tour-basic:username"/>
bos@553: 	    below.</para></listitem>
bos@584: 	<listitem><para id="x_46">If you have set the <envar>EMAIL</envar>
bos@553: 	    environment variable, this will be used
bos@553: 	    next.</para></listitem>
bos@584: 	<listitem><para id="x_47">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@584:       <para id="x_48">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@584:       <para id="x_49">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>
bos@558:       <sect3 id="sec:tour-basic:username">
bos@553: 	<title>Creating a Mercurial configuration file</title>
bos@558: 
bos@584: 	<para id="x_4a">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@609: 
bos@609: 	<remark>Figure out what the appropriate directory is on
bos@609: 	  Windows.</remark>
bos@609: 
bos@558: 	<programlisting># This is a Mercurial configuration file.
bos@579: [ui]
bos@609: username = Firstname Lastname &lt;email.address@domain.net&gt;</programlisting>
bos@558: 
bos@584: 	<para id="x_4b">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@584: 	<para id="x_4c">You can use any text you like as the value of
bos@553: 	    the <literal>username</literal> config item, since this
bos@609: 	    information is for reading by other people, but will not be
bos@609: 	    interpreted 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@584: 	  <para id="x_4d">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@584:       <para id="x_4e">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@584:       <para id="x_4f">The editor that the <command role="hg-cmd">hg
bos@553: 	    commit</command> command drops us into will contain an
bos@609: 	  empty line or two, followed by a number of lines starting with
bos@558: 	  <quote><literal>HG:</literal></quote>.</para>
bos@558: 
bos@609:     <programlisting>
bos@609: This is where I type my commit comment.
bos@609: 
bos@609: HG: Enter commit message.  Lines beginning with 'HG:' are removed.
bos@609: HG: --
bos@609: HG: user: Bryan O'Sullivan &lt;bos@serpentine.com&gt;
bos@609: HG: branch 'default'
bos@609: HG: changed hello.c</programlisting>
bos@558: 
bos@584:       <para id="x_50">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@584:       <para id="x_51">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@584:       <para id="x_52">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@584:       <para id="x_53">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@584:       <para id="x_54">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@584:       <para id="x_55">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@584:       <para id="x_56">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@609:       <para id="x_57">We refer to the newest revision in the
bos@609: 	repository as the <emphasis>tip revision</emphasis>, or simply
bos@609: 	the <emphasis>tip</emphasis>.</para>
bos@609: 
bos@609:       <para>By the way, the <command role="hg-cmd">hg tip</command>
bos@609: 	command accepts many of the same options as <command
bos@609: 	  role="hg-cmd">hg log</command>, so <option
bos@609: 	  role="hg-opt-global">-v</option> above indicates <quote>be
bos@609: 	  verbose</quote>, <option role="hg-opt-tip">-p</option>
bos@609: 	specifies <quote>print a patch</quote>.  The use of <option
bos@609: 	  role="hg-opt-tip">-p</option> to print patches is another
bos@609: 	example of the consistent naming we mentioned earlier.</para>
bos@553:     </sect2>
bos@553:   </sect1>
bos@558: 
bos@553:   <sect1>
bos@553:     <title>Sharing changes</title>
bos@553: 
bos@584:     <para id="x_58">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: 
bos@558:     <sect2 id="sec:tour:pull">
bos@553:       <title>Pulling changes from another repository</title>
bos@584:       <para id="x_59">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@584:       <para id="x_5a">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@609:       <para id="x_5b">Suppose you're pulling changes from a repository
bos@609:       on the network somewhere. While you are looking at the <command
bos@609: 	  role="hg-cmd">hg incoming</command> output, and before you
bos@609: 	pull those changes, someone might have committed something in
bos@609: 	the remote repository. This means that it's possible to pull
bos@609: 	more changes than you saw when using <command
bos@609: 	  role="hg-cmd">hg incoming</command>.</para>
bos@558: 
bos@584:       <para id="x_5c">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@584:       <para id="x_5d">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@592:       <para id="x_5e">We have so far glossed over the relationship
bos@592: 	between a repository and its working directory.  The <command
bos@559: 	  role="hg-cmd">hg pull</command> command that we ran in
bos@592: 	<xref linkend="sec:tour:pull"/> brought changes into the
bos@592: 	repository, but if we check, there's no sign of those changes
bos@592: 	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@584:       <para id="x_5f">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@609: 	you had the working directory updated to an old revision&emdash;to
bos@609: 	hunt down the origin of a bug, say&emdash;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@584:       <para id="x_60">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@584:       <para id="x_61">If you look back at the output of <command
bos@592: 	  role="hg-cmd">hg pull</command> in <xref
bos@558: 	    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@584:       <para id="x_62">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@592:       <para id="x_63">If you look back at <xref
bos@559: 	  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@584:       <para id="x_64">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@584:       <para id="x_65">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@584:       <para id="x_66">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@584:       <para id="x_67">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@584:       <para id="x_68">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@609:       <para id="x_69">As with <command role="hg-cmd">hg
bos@609: 	  pull</command>, the <command role="hg-cmd">hg push</command>
bos@609: 	command does not update the working directory in the
bos@609: 	repository that it's pushing changes into. Unlike <command
bos@609: 	  role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg
bos@609: 	  push</command> does not provide a <literal>-u</literal>
bos@609: 	option that updates the other repository's working directory.
bos@609: 	This asymmetry is deliberate: the repository we're pushing to
bos@609: 	might be on a remote server and shared between several people.
bos@609: 	If we were to update its working directory while someone was
bos@609: 	working in it, their work would be disrupted.</para>
bos@558: 
bos@584:       <para id="x_6a">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@584:       <para id="x_6b">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@584:       <para id="x_6c">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: -->