Mercurial > hgbook
diff en/ch01-tour-basic.xml @ 753:1c13ed2130a7
Merge with http://hg.serpentine.com/mercurial/book
author | Dongsheng Song <dongsheng.song@gmail.com> |
---|---|
date | Mon, 30 Mar 2009 16:23:33 +0800 |
parents | 7e7c47481e4f 0b45854f0b7b |
children | 3b33dd6aba87 |
line wrap: on
line diff
--- a/en/ch01-tour-basic.xml Fri Mar 20 17:17:55 2009 +0800 +++ b/en/ch01-tour-basic.xml Mon Mar 30 16:23:33 2009 +0800 @@ -1,27 +1,27 @@ <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> -<chapter id="chap.tour-basic"> +<chapter id="chap:tour-basic"> <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?> <title>A tour of Mercurial: the basics</title> - <sect1 id="sec.tour.install"> + <sect1 id="sec:tour:install"> <title>Installing Mercurial on your system</title> - <para>Prebuilt binary packages of Mercurial are available for + <para id="x_1">Prebuilt binary packages of Mercurial are available for every popular operating system. These make it easy to start using Mercurial on your computer immediately.</para> <sect2> <title>Linux</title> - <para>Because each Linux distribution has its own packaging + <para id="x_2">Because each Linux distribution has its own packaging tools, policies, and rate of development, it's difficult to give a comprehensive set of instructions on how to install Mercurial binaries. The version of Mercurial that you will end up with can vary depending on how active the person is who maintains the package for your distribution.</para> - <para>To keep things simple, I will focus on installing + <para id="x_3">To keep things simple, I will focus on installing Mercurial from the command line under the most popular Linux distributions. Most of these distributions provide graphical package managers that will let you install Mercurial with a @@ -29,15 +29,15 @@ <literal>mercurial</literal>.</para> <itemizedlist> - <listitem><para>Debian:</para> + <listitem><para id="x_4">Debian:</para> <programlisting>apt-get install mercurial</programlisting></listitem> - <listitem><para>Fedora Core:</para> + <listitem><para id="x_5">Fedora Core:</para> <programlisting>yum install mercurial</programlisting></listitem> - <listitem><para>Gentoo:</para> + <listitem><para id="x_6">Gentoo:</para> <programlisting>emerge mercurial</programlisting></listitem> - <listitem><para>OpenSUSE:</para> + <listitem><para id="x_7">OpenSUSE:</para> <programlisting>yum install mercurial</programlisting></listitem> - <listitem><para>Ubuntu: Ubuntu's Mercurial package is based on + <listitem><para id="x_8">Ubuntu: Ubuntu's Mercurial package is based on Debian's. To install it, run the following command.</para> <programlisting>apt-get install mercurial</programlisting></listitem> @@ -47,7 +47,7 @@ <sect2> <title>Solaris</title> - <para>SunFreeWare, at <ulink + <para id="x_9">SunFreeWare, at <ulink url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, is a good source for a large number of pre-built Solaris packages for 32 and 64 bit Intel and Sparc architectures, @@ -57,7 +57,7 @@ <sect2> <title>Mac OS X</title> - <para>Lee Cantey publishes an installer of Mercurial for Mac OS + <para id="x_a">Lee Cantey publishes an installer of Mercurial for Mac OS X at <ulink url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. This package works on both Intel- and Power-based Macs. Before @@ -66,7 +66,7 @@ is easy to do; simply follow the instructions on Lee's site.</para> - <para>It's also possible to install Mercurial using Fink or + <para id="x_b">It's also possible to install Mercurial using Fink or MacPorts, two popular free package managers for Mac OS X. If you have Fink, use <command>sudo apt-get install mercurial-py25</command>. If MacPorts, <command>sudo port @@ -76,14 +76,14 @@ <sect2> <title>Windows</title> - <para>Lee Cantey publishes an installer of Mercurial for Windows + <para id="x_c">Lee Cantey publishes an installer of Mercurial for Windows at <ulink url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. This package has no external dependencies; it <quote>just works</quote>.</para> <note> - <para> The Windows version of Mercurial does not + <para id="x_d"> The Windows version of Mercurial does not automatically convert line endings between Windows and Unix styles. If you want to share work with Unix users, you must do a little additional configuration work. XXX Flesh this @@ -95,7 +95,7 @@ <sect1> <title>Getting started</title> - <para>To begin, we'll use the <command role="hg-cmd">hg + <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg version</command> command to find out whether Mercurial is actually installed properly. The actual version information that it prints isn't so important; it's whether it prints @@ -106,7 +106,7 @@ <sect2> <title>Built-in help</title> - <para>Mercurial provides a built-in help system. This is + <para id="x_f">Mercurial provides a built-in help system. This is invaluable for those times when you find yourself stuck trying to remember how to run a command. If you are completely stuck, simply run <command role="hg-cmd">hg @@ -117,7 +117,7 @@ &interaction.tour.help; - <para>For a more impressive level of detail (which you won't + <para id="x_10">For a more impressive level of detail (which you won't usually need) run <command role="hg-cmd">hg help <option role="hg-opt-global">-v</option></command>. The <option role="hg-opt-global">-v</option> option is short for @@ -130,13 +130,13 @@ <sect1> <title>Working with a repository</title> - <para>In Mercurial, everything happens inside a + <para id="x_11">In Mercurial, everything happens inside a <emphasis>repository</emphasis>. The repository for a project contains all of the files that <quote>belong to</quote> that project, along with a historical record of the project's files.</para> - <para>There's nothing particularly magical about a repository; it + <para id="x_12">There's nothing particularly magical about a repository; it is simply a directory tree in your filesystem that Mercurial treats as special. You can rename or delete a repository any time you like, using either the command line or your file @@ -145,7 +145,7 @@ <sect2> <title>Making a local copy of a repository</title> - <para><emphasis>Copying</emphasis> a repository is just a little + <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little bit special. While you could use a normal file copying command to make a copy of a repository, it's best to use a built-in command that Mercurial provides. This command is @@ -154,23 +154,23 @@ &interaction.tour.clone; - <para>If our clone succeeded, we should now have a local + <para id="x_14">If our clone succeeded, we should now have a local directory called <filename class="directory">hello</filename>. This directory will contain some files.</para> &interaction.tour.ls; - <para>These files have the same contents and history in our + <para id="x_15">These files have the same contents and history in our repository as they do in the repository we cloned.</para> - <para>Every Mercurial repository is complete, self-contained, + <para id="x_16">Every Mercurial repository is complete, self-contained, and independent. It contains its own private copy of a project's files and history. A cloned repository remembers the location of the repository it was cloned from, but it does not communicate with that repository, or any other, unless you tell it to.</para> - <para>What this means for now is that we're free to experiment + <para id="x_17">What this means for now is that we're free to experiment with our repository, safe in the knowledge that it's a private <quote>sandbox</quote> that won't affect anyone else.</para> @@ -178,20 +178,20 @@ <sect2> <title>What's in a repository?</title> - <para>When we take a more detailed look inside a repository, we + <para id="x_18">When we take a more detailed look inside a repository, we can see that it contains a directory named <filename class="directory">.hg</filename>. This is where Mercurial keeps all of its metadata for the repository.</para> &interaction.tour.ls-a; - <para>The contents of the <filename + <para id="x_19">The contents of the <filename class="directory">.hg</filename> directory and its subdirectories are private to Mercurial. Every other file and directory in the repository is yours to do with as you please.</para> - <para>To introduce a little terminology, the <filename + <para id="x_1a">To introduce a little terminology, the <filename class="directory">.hg</filename> directory is the <quote>real</quote> repository, and all of the files and directories that coexist with it are said to live in the @@ -208,68 +208,66 @@ <sect1> <title>A tour through history</title> - <para>One of the first things we might want to do with a new, + <para id="x_1b">One of the first things we might want to do with a new, unfamiliar repository is understand its history. The <command role="hg-cmd">hg log</command> command gives us a view of history.</para> &interaction.tour.log; - <para>By default, this command prints a brief paragraph of output + <para id="x_1c">By default, this command prints a brief paragraph of output for each change to the project that was recorded. In Mercurial terminology, we call each of these recorded events a <emphasis>changeset</emphasis>, because it can contain a record of changes to several files.</para> - <para>The fields in a record of output from <command + <para id="x_1d">The fields in a record of output from <command role="hg-cmd">hg log</command> are as follows.</para> <itemizedlist> - <listitem><para><literal>changeset</literal>: This field has the + <listitem><para id="x_1e"><literal>changeset</literal>: This field has the format of a number, followed by a colon, followed by a hexadecimal string. These are <emphasis>identifiers</emphasis> for the changeset. There are two identifiers because the number is shorter and easier to type than the hex string.</para></listitem> - <listitem><para><literal>user</literal>: The identity of the + <listitem><para id="x_1f"><literal>user</literal>: The identity of the person who created the changeset. This is a free-form field, but it most often contains a person's name and email address.</para></listitem> - <listitem><para><literal>date</literal>: The date and time on + <listitem><para id="x_20"><literal>date</literal>: The date and time on which the changeset was created, and the timezone in which it was created. (The date and time are local to that timezone; they display what time and date it was for the person who created the changeset.)</para></listitem> - <listitem><para><literal>summary</literal>: The first line of + <listitem><para id="x_21"><literal>summary</literal>: The first line of the text message that the creator of the changeset entered to describe the changeset.</para></listitem></itemizedlist> - <para>The default output printed by <command role="hg-cmd">hg + <para id="x_22">The default output printed by <command role="hg-cmd">hg log</command> is purely a summary; it is missing a lot of detail.</para> - <para>Figure <xref endterm="fig.tour-basic.history.caption" - linkend="fig.tour-basic.history"/> provides a - graphical representation of the history of the <filename + <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides + a graphical representation of the history of the <filename class="directory">hello</filename> repository, to make it a little easier to see which direction history is <quote>flowing</quote> in. We'll be returning to this figure several times in this chapter and the chapter that follows.</para> - <informalfigure id="fig.tour-basic.history"> + <figure id="fig:tour-basic:history"> + <title>Graphical history of the <filename + class="directory">hello</filename> repository</title> <mediaobject> - <imageobject><imagedata fileref="images/tour-history.png"/></imageobject> + <imageobject><imagedata fileref="figs/tour-history.png"/></imageobject> <textobject><phrase>XXX add text</phrase></textobject> - <caption><para id="fig.tour-basic.history.caption">Graphical history of - the <filename class="directory">hello</filename> repository</para> - </caption> </mediaobject> - </informalfigure> + </figure> <sect2> <title>Changesets, revisions, and talking to other people</title> - <para>As English is a notoriously sloppy language, and computer + <para id="x_25">As English is a notoriously sloppy language, and computer science has a hallowed history of terminological confusion (why use one term when four will do?), revision control has a variety of words and phrases that mean the same thing. If you @@ -279,7 +277,7 @@ <quote>cset</quote>, and sometimes a changeset is referred to as a <quote>revision</quote> or a <quote>rev</quote>.</para> - <para>While it doesn't matter what <emphasis>word</emphasis> you + <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you use to refer to the concept of <quote>a changeset</quote>, the <emphasis>identifier</emphasis> that you use to refer to <quote>a <emphasis>specific</emphasis> changeset</quote> is of @@ -288,14 +286,14 @@ log</command> identifies a changeset using both a number and a hexadecimal string.</para> <itemizedlist> - <listitem><para>The revision number is <emphasis>only valid in + <listitem><para id="x_27">The revision number is <emphasis>only valid in that repository</emphasis>,</para></listitem> - <listitem><para>while the hex string is the + <listitem><para id="x_28">while the hex string is the <emphasis>permanent, unchanging identifier</emphasis> that will always identify that exact changeset in <emphasis>every</emphasis> copy of the repository.</para></listitem></itemizedlist> - <para>This distinction is important. If you send someone an + <para id="x_29">This distinction is important. If you send someone an email talking about <quote>revision 33</quote>, there's a high likelihood that their revision 33 will <emphasis>not be the same</emphasis> as yours. The reason for this is that a @@ -305,7 +303,7 @@ repositories. Three changes $a,b,c$ can easily appear in one repository as $0,1,2$, while in another as $1,0,2$.</para> - <para>Mercurial uses revision numbers purely as a convenient + <para id="x_2a">Mercurial uses revision numbers purely as a convenient shorthand. If you need to discuss a changeset with someone, or make a record of a changeset for some other reason (for example, in a bug report), use the hexadecimal @@ -315,7 +313,7 @@ <sect2> <title>Viewing specific revisions</title> - <para>To narrow the output of <command role="hg-cmd">hg + <para id="x_2b">To narrow the output of <command role="hg-cmd">hg log</command> down to a single revision, use the <option role="hg-opt-log">-r</option> (or <option role="hg-opt-log">--rev</option>) option. You can use @@ -324,7 +322,7 @@ &interaction.tour.log-r; - <para>If you want to see the history of several revisions + <para id="x_2c">If you want to see the history of several revisions without having to list each one, you can use <emphasis>range notation</emphasis>; this lets you express the idea <quote>I want all revisions between <literal>abc</literal> and @@ -332,7 +330,7 @@ &interaction.tour.log.range; - <para>Mercurial also honours the order in which you specify + <para id="x_2d">Mercurial also honours the order in which you specify revisions, so <command role="hg-cmd">hg log -r 2:4</command> prints 2, 3, and 4. while <command role="hg-cmd">hg log -r 4:2</command> prints 4, 3, and 2.</para> @@ -341,7 +339,7 @@ <sect2> <title>More detailed information</title> - <para>While the summary information printed by <command + <para id="x_2e">While the summary information printed by <command role="hg-cmd">hg log</command> is useful if you already know what you're looking for, you may need to see a complete description of the change, or a list of the files changed, if @@ -353,13 +351,13 @@ &interaction.tour.log-v; - <para>If you want to see both the description and content of a - change, add the <option role="hg-opt-log">-p</option> (or - <option role="hg-opt-log">--patch</option>) option. This - displays the content of a change as a <emphasis>unified - diff</emphasis> (if you've never seen a unified diff before, - see section <xref linkend="sec.mq.patch"/> for an - overview).</para> + <para id="x_2f">If you want to see both the description and + content of a change, add the <option + role="hg-opt-log">-p</option> (or <option + role="hg-opt-log">--patch</option>) option. This displays + the content of a change as a <emphasis>unified diff</emphasis> + (if you've never seen a unified diff before, see <xref + linkend="sec:mq:patch"/> for an overview).</para> &interaction.tour.log-vp; @@ -368,39 +366,39 @@ <sect1> <title>All about command options</title> - <para>Let's take a brief break from exploring Mercurial commands + <para id="x_30">Let's take a brief break from exploring Mercurial commands to discuss a pattern in the way that they work; you may find this useful to keep in mind as we continue our tour.</para> - <para>Mercurial has a consistent and straightforward approach to + <para id="x_31">Mercurial has a consistent and straightforward approach to dealing with the options that you can pass to commands. It follows the conventions for options that are common to modern Linux and Unix systems.</para> <itemizedlist> - <listitem><para>Every option has a long name. For example, as + <listitem><para id="x_32">Every option has a long name. For example, as we've already seen, the <command role="hg-cmd">hg log</command> command accepts a <option role="hg-opt-log">--rev</option> option.</para></listitem> - <listitem><para>Most options have short names, too. Instead of + <listitem><para id="x_33">Most options have short names, too. Instead of <option role="hg-opt-log">--rev</option>, we can use <option role="hg-opt-log">-r</option>. (The reason that some options don't have short names is that the options in question are rarely used.)</para></listitem> - <listitem><para>Long options start with two dashes (e.g. <option + <listitem><para id="x_34">Long options start with two dashes (e.g. <option role="hg-opt-log">--rev</option>), while short options start with one (e.g. <option role="hg-opt-log">-r</option>).</para></listitem> - <listitem><para>Option naming and usage is consistent across + <listitem><para id="x_35">Option naming and usage is consistent across commands. For example, every command that lets you specify a changeset ID or revision number accepts both <option role="hg-opt-log">-r</option> and <option role="hg-opt-log">--rev</option> arguments.</para></listitem></itemizedlist> - <para>In the examples throughout this book, I use short options + <para id="x_36">In the examples throughout this book, I use short options instead of long. This just reflects my own preference, so don't read anything significant into it.</para> - <para>Most commands that print output of some kind will print more + <para id="x_37">Most commands that print output of some kind will print more output when passed a <option role="hg-opt-global">-v</option> (or <option role="hg-opt-global">--verbose</option>) option, and less when passed <option role="hg-opt-global">-q</option> (or @@ -410,11 +408,11 @@ <sect1> <title>Making and reviewing changes</title> - <para>Now that we have a grasp of viewing history in Mercurial, + <para id="x_38">Now that we have a grasp of viewing history in Mercurial, let's take a look at making some changes and examining them.</para> - <para>The first thing we'll do is isolate our experiment in a + <para id="x_39">The first thing we'll do is isolate our experiment in a repository of its own. We use the <command role="hg-cmd">hg clone</command> command, but we don't need to clone a copy of the remote repository. Since we already have a copy of it @@ -424,7 +422,7 @@ &interaction.tour.reclone; - <para>As an aside, it's often good practice to keep a + <para id="x_3a">As an aside, it's often good practice to keep a <quote>pristine</quote> copy of a remote repository around, which you can then make temporary clones of to create sandboxes for each task you want to work on. This lets you work on @@ -433,7 +431,7 @@ local clones are so cheap, there's almost no overhead to cloning and destroying repositories whenever you want.</para> - <para>In our <filename class="directory">my-hello</filename> + <para id="x_3b">In our <filename class="directory">my-hello</filename> repository, we have a file <filename>hello.c</filename> that contains the classic <quote>hello, world</quote> program. Let's use the ancient and venerable <command>sed</command> command to @@ -446,20 +444,20 @@ &interaction.tour.sed; - <para>Mercurial's <command role="hg-cmd">hg status</command> + <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command> command will tell us what Mercurial knows about the files in the repository.</para> &interaction.tour.status; - <para>The <command role="hg-cmd">hg status</command> command + <para id="x_3d">The <command role="hg-cmd">hg status</command> command prints no output for some files, but a line starting with <quote><literal>M</literal></quote> for <filename>hello.c</filename>. Unless you tell it to, <command role="hg-cmd">hg status</command> will not print any output for files that have not been modified.</para> - <para>The <quote><literal>M</literal></quote> indicates that + <para id="x_3e">The <quote><literal>M</literal></quote> indicates that Mercurial has noticed that we modified <filename>hello.c</filename>. We didn't need to <emphasis>inform</emphasis> Mercurial that we were going to @@ -467,7 +465,7 @@ file after we were done; it was able to figure this out itself.</para> - <para>It's a little bit helpful to know that we've modified + <para id="x_3f">It's a little bit helpful to know that we've modified <filename>hello.c</filename>, but we might prefer to know exactly <emphasis>what</emphasis> changes we've made to it. To do this, we use the <command role="hg-cmd">hg diff</command> @@ -479,14 +477,14 @@ <sect1> <title>Recording changes in a new changeset</title> - <para>We can modify files, build and test our changes, and use + <para id="x_40">We can modify files, build and test our changes, and use <command role="hg-cmd">hg status</command> and <command role="hg-cmd">hg diff</command> to review our changes, until we're satisfied with what we've done and arrive at a natural stopping point where we want to record our work in a new changeset.</para> - <para>The <command role="hg-cmd">hg commit</command> command lets + <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets us create a new changeset; we'll usually refer to this as <quote>making a commit</quote> or <quote>committing</quote>.</para> @@ -494,7 +492,7 @@ <sect2> <title>Setting up a username</title> - <para>When you try to run <command role="hg-cmd">hg + <para id="x_42">When you try to run <command role="hg-cmd">hg commit</command> for the first time, it is not guaranteed to succeed. Mercurial records your name and address with each change that you commit, so that you and others will later be @@ -503,36 +501,37 @@ change with. It will attempt each of the following methods, in order:</para> <orderedlist> - <listitem><para>If you specify a <option + <listitem><para id="x_43">If you specify a <option role="hg-opt-commit">-u</option> option to the <command role="hg-cmd">hg commit</command> command on the command line, followed by a username, this is always given the highest precedence.</para></listitem> - <listitem><para>If you have set the <envar>HGUSER</envar> + <listitem><para id="x_44">If you have set the <envar>HGUSER</envar> environment variable, this is checked next.</para></listitem> - <listitem><para>If you create a file in your home directory - called <filename role="special">.hgrc</filename>, with a - <envar role="rc-item-ui">username</envar> entry, that will - be used next. To see what the contents of this file - should look like, refer to section <xref - linkend="sec.tour-basic.username"/> + <listitem><para id="x_45">If you create a file in your home + directory called <filename + role="special">.hgrc</filename>, with a <envar + role="rc-item-ui">username</envar> entry, that will be + used next. To see what the contents of this file should + look like, refer to <xref + linkend="sec:tour-basic:username"/> below.</para></listitem> - <listitem><para>If you have set the <envar>EMAIL</envar> + <listitem><para id="x_46">If you have set the <envar>EMAIL</envar> environment variable, this will be used next.</para></listitem> - <listitem><para>Mercurial will query your system to find out + <listitem><para id="x_47">Mercurial will query your system to find out your local user name and host name, and construct a username from these components. Since this often results in a username that is not very useful, it will print a warning if it has to do this.</para></listitem> </orderedlist> - <para>If all of these mechanisms fail, Mercurial will + <para id="x_48">If all of these mechanisms fail, Mercurial will fail, printing an error message. In this case, it will not let you commit until you set up a username.</para> - <para>You should think of the <envar>HGUSER</envar> environment + <para id="x_49">You should think of the <envar>HGUSER</envar> environment variable and the <option role="hg-opt-commit">-u</option> option to the <command role="hg-cmd">hg commit</command> command as ways to <emphasis>override</emphasis> Mercurial's @@ -540,10 +539,10 @@ and most robust way to set a username for yourself is by creating a <filename role="special">.hgrc</filename> file; see below for details.</para> - <sect3 id="sec.tour-basic.username"> + <sect3 id="sec:tour-basic:username"> <title>Creating a Mercurial configuration file</title> - <para>To set a user name, use your favourite editor + <para id="x_4a">To set a user name, use your favourite editor to create a file called <filename role="special">.hgrc</filename> in your home directory. Mercurial will use this file to look up your personalised @@ -555,7 +554,7 @@ username = Firstname Lastname <email.address@domain.net></programlisting> - <para>The <quote><literal>[ui]</literal></quote> line begins a + <para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a <emphasis>section</emphasis> of the config file, so you can read the <quote><literal>username = ...</literal></quote> line as meaning <quote>set the value of the @@ -570,14 +569,14 @@ <sect3> <title>Choosing a user name</title> - <para>You can use any text you like as the value of + <para id="x_4c">You can use any text you like as the value of the <literal>username</literal> config item, since this information is for reading by other people, but for interpreting by Mercurial. The convention that most people follow is to use their name and email address, as in the example above.</para> <note> - <para>Mercurial's built-in web server obfuscates + <para id="x_4d">Mercurial's built-in web server obfuscates email addresses, to make it more difficult for the email harvesting tools that spammers use. This reduces the likelihood that you'll start receiving more junk email @@ -589,7 +588,7 @@ <sect2> <title>Writing a commit message</title> - <para>When we commit a change, Mercurial drops us into + <para id="x_4e">When we commit a change, Mercurial drops us into a text editor, to enter a message that will describe the modifications we've made in this changeset. This is called the <emphasis>commit message</emphasis>. It will be a @@ -599,14 +598,14 @@ &interaction.tour.commit; - <para>The editor that the <command role="hg-cmd">hg + <para id="x_4f">The editor that the <command role="hg-cmd">hg commit</command> command drops us into will contain an empty line, followed by a number of lines starting with <quote><literal>HG:</literal></quote>.</para> <programlisting>XXX fix this XXX</programlisting> - <para>Mercurial ignores the lines that start with + <para id="x_50">Mercurial ignores the lines that start with <quote><literal>HG:</literal></quote>; it uses them only to tell us which files it's recording changes to. Modifying or deleting these lines has no effect.</para> @@ -614,7 +613,7 @@ <sect2> <title>Writing a good commit message</title> - <para>Since <command role="hg-cmd">hg log</command> + <para id="x_51">Since <command role="hg-cmd">hg log</command> only prints the first line of a commit message by default, it's best to write a commit message whose first line stands alone. Here's a real example of a commit message that @@ -628,13 +627,13 @@ date: Tue Sep 26 21:37:07 2006 -0700 summary: include buildmeister/commondefs. Add exports.</programlisting> - <para>As far as the remainder of the contents of the + <para id="x_52">As far as the remainder of the contents of the commit message are concerned, there are no hard-and-fast rules. Mercurial itself doesn't interpret or care about the contents of the commit message, though your project may have policies that dictate a certain kind of formatting.</para> - <para>My personal preference is for short, but + <para id="x_53">My personal preference is for short, but informative, commit messages that tell me something that I can't figure out with a quick glance at the output of <command role="hg-cmd">hg log @@ -643,12 +642,12 @@ <sect2> <title>Aborting a commit</title> - <para>If you decide that you don't want to commit + <para id="x_54">If you decide that you don't want to commit while in the middle of editing a commit message, simply exit from your editor without saving the file that it's editing. This will cause nothing to happen to either the repository or the working directory.</para> - <para>If we run the <command role="hg-cmd">hg + <para id="x_55">If we run the <command role="hg-cmd">hg commit</command> command without any arguments, it records all of the changes we've made, as reported by <command role="hg-cmd">hg status</command> and <command @@ -657,7 +656,7 @@ <sect2> <title>Admiring our new handiwork</title> - <para>Once we've finished the commit, we can use the + <para id="x_56">Once we've finished the commit, we can use the <command role="hg-cmd">hg tip</command> command to display the changeset we just created. This command produces output that is identical to <command role="hg-cmd">hg @@ -666,7 +665,7 @@ &interaction.tour.tip; - <para>We refer to + <para id="x_57">We refer to the newest revision in the repository as the tip revision, or simply the tip.</para> </sect2> @@ -675,16 +674,16 @@ <sect1> <title>Sharing changes</title> - <para>We mentioned earlier that repositories in + <para id="x_58">We mentioned earlier that repositories in Mercurial are self-contained. This means that the changeset we just created exists only in our <filename class="directory">my-hello</filename> repository. Let's look at a few ways that we can propagate this change into other repositories.</para> - <sect2 id="sec.tour.pull"> + <sect2 id="sec:tour:pull"> <title>Pulling changes from another repository</title> - <para>To get started, let's clone our original + <para id="x_59">To get started, let's clone our original <filename class="directory">hello</filename> repository, which does not contain the change we just committed. We'll call our temporary repository <filename @@ -692,7 +691,7 @@ &interaction.tour.clone-pull; - <para>We'll use the <command role="hg-cmd">hg + <para id="x_5a">We'll use the <command role="hg-cmd">hg pull</command> command to bring changes from <filename class="directory">my-hello</filename> into <filename class="directory">hello-pull</filename>. However, blindly @@ -705,21 +704,21 @@ &interaction.tour.incoming; - <para>(Of course, someone could + <para id="x_5b">(Of course, someone could cause more changesets to appear in the repository that we ran <command role="hg-cmd">hg incoming</command> in, before we get a chance to <command role="hg-cmd">hg pull</command> the changes, so that we could end up pulling changes that we didn't expect.)</para> - <para>Bringing changes into a repository is a simple + <para id="x_5c">Bringing changes into a repository is a simple matter of running the <command role="hg-cmd">hg pull</command> command, and telling it which repository to pull from.</para> &interaction.tour.pull; - <para>As you can see + <para id="x_5d">As you can see from the before-and-after output of <command role="hg-cmd">hg tip</command>, we have successfully pulled changes into our repository. There remains one step @@ -729,19 +728,19 @@ <sect2> <title>Updating the working directory</title> - <para>We have so far glossed over the relationship between a - repository and its working directory. The <command + <para id="x_5e">We have so far glossed over the relationship + between a repository and its working directory. The <command role="hg-cmd">hg pull</command> command that we ran in - section <xref linkend="sec.tour.pull"/> brought changes - into the repository, but if we check, there's no sign of those - changes in the working directory. This is because <command + <xref linkend="sec:tour:pull"/> brought changes into the + repository, but if we check, there's no sign of those changes + in the working directory. This is because <command role="hg-cmd">hg pull</command> does not (by default) touch the working directory. Instead, we use the <command role="hg-cmd">hg update</command> command to do this.</para> &interaction.tour.update; - <para>It might seem a bit strange that <command role="hg-cmd">hg + <para id="x_5f">It might seem a bit strange that <command role="hg-cmd">hg pull</command> doesn't update the working directory automatically. There's actually a good reason for this: you can use <command role="hg-cmd">hg update</command> to update @@ -752,29 +751,28 @@ role="hg-cmd">hg pull</command> which automatically updated the working directory to a new revision, you might not be terribly happy.</para> - <para>However, since pull-then-update is such a common thing to + <para id="x_60">However, since pull-then-update is such a common thing to do, Mercurial lets you combine the two by passing the <option role="hg-opt-pull">-u</option> option to <command role="hg-cmd">hg pull</command>.</para> - <para>If you look back at the output of <command - role="hg-cmd">hg pull</command> in section <xref - linkend="sec.tour.pull"/> when we ran it without <option + <para id="x_61">If you look back at the output of <command + role="hg-cmd">hg pull</command> in <xref + linkend="sec:tour:pull"/> when we ran it without <option role="hg-opt-pull">-u</option>, you can see that it printed a helpful reminder that we'd have to take an explicit step to update the working directory:</para> <!-- &interaction.xxx.fixme; --> - <para>To find out what revision the working directory is at, use + <para id="x_62">To find out what revision the working directory is at, use the <command role="hg-cmd">hg parents</command> command.</para> &interaction.tour.parents; - <para>If you look back at figure <xref - endterm="fig.tour-basic.history.caption" - linkend="fig.tour-basic.history"/>, + <para id="x_63">If you look back at <xref + linkend="fig:tour-basic:history"/>, you'll see arrows connecting each changeset. The node that the arrow leads <emphasis>from</emphasis> in each case is a parent, and the node that the arrow leads @@ -782,14 +780,14 @@ has a parent in just the same way; this is the changeset that the working directory currently contains.</para> - <para>To update the working directory to a particular revision, + <para id="x_64">To update the working directory to a particular revision, give a revision number or changeset ID to the <command role="hg-cmd">hg update</command> command.</para> &interaction.tour.older; - <para>If you omit an explicit revision, <command + <para id="x_65">If you omit an explicit revision, <command role="hg-cmd">hg update</command> will update to the tip revision, as shown by the second call to <command role="hg-cmd">hg update</command> in the example @@ -799,7 +797,7 @@ <sect2> <title>Pushing changes to another repository</title> - <para>Mercurial lets us push changes to another + <para id="x_66">Mercurial lets us push changes to another repository, from the repository we're currently visiting. As with the example of <command role="hg-cmd">hg pull</command> above, we'll create a temporary repository @@ -807,19 +805,19 @@ &interaction.tour.clone-push; - <para>The <command role="hg-cmd">hg outgoing</command> command + <para id="x_67">The <command role="hg-cmd">hg outgoing</command> command tells us what changes would be pushed into another repository.</para> &interaction.tour.outgoing; - <para>And the + <para id="x_68">And the <command role="hg-cmd">hg push</command> command does the actual push.</para> &interaction.tour.push; - <para>As with + <para id="x_69">As with <command role="hg-cmd">hg pull</command>, the <command role="hg-cmd">hg push</command> command does not update the working directory in the repository that it's pushing @@ -828,7 +826,7 @@ does not provide a <literal>-u</literal> option that updates the other repository's working directory.)</para> - <para>What happens if we try to pull or push changes + <para id="x_6a">What happens if we try to pull or push changes and the receiving repository already has those changes? Nothing too exciting.</para> @@ -837,7 +835,7 @@ <sect2> <title>Sharing changes over a network</title> - <para>The commands we have covered in the previous few + <para id="x_6b">The commands we have covered in the previous few sections are not limited to working with local repositories. Each works in exactly the same fashion over a network connection; simply pass in a URL instead of a local @@ -845,7 +843,7 @@ &interaction.tour.outgoing.net; - <para>In this example, we + <para id="x_6c">In this example, we can see what changes we could push to the remote repository, but the repository is understandably not set up to let anonymous users push to it.</para>