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