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