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