hgbook
view 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 source
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
3 <chapter>
4 <title>A tour of Mercurial: the basics</title>
5 <para>\label{chap:tour-basic}</para>
7 <sect1>
8 <title>Installing Mercurial on your system</title>
9 <para>\label{sec:tour:install}</para>
11 <para>Prebuilt binary packages of Mercurial are available for
12 every popular operating system. These make it easy to start
13 using Mercurial on your computer immediately.</para>
15 <sect2>
16 <title>Linux</title>
18 <para>Because each Linux distribution has its own packaging
19 tools, policies, and rate of development, it's difficult to
20 give a comprehensive set of instructions on how to install
21 Mercurial binaries. The version of Mercurial that you will
22 end up with can vary depending on how active the person is who
23 maintains the package for your distribution.</para>
25 <para>To keep things simple, I will focus on installing
26 Mercurial from the command line under the most popular Linux
27 distributions. Most of these distributions provide graphical
28 package managers that will let you install Mercurial with a
29 single click; the package name to look for is
30 <literal>mercurial</literal>.</para>
32 <itemizedlist>
33 <listitem><para>Debian:</para>
34 <programlisting>apt-get install
35 mercurial</programlisting></listitem>
36 <listitem><para>Fedora Core:</para>
37 <programlisting>yum install
38 mercurial</programlisting></listitem>
39 <listitem><para>Gentoo:</para>
40 <programlisting>emerge mercurial</programlisting></listitem>
41 <listitem><para>OpenSUSE:</para>
42 <programlisting>yum install
43 mercurial</programlisting></listitem>
44 <listitem><para>Ubuntu: Ubuntu's Mercurial package is based on
45 Debian's. To install it, run the following
46 command.</para>
47 <programlisting>apt-get install
48 mercurial</programlisting></listitem>
49 </itemizedlist>
51 </sect2>
52 <sect2>
53 <title>Solaris</title>
55 <para>SunFreeWare, at <ulink
56 url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>,
57 is a good source for a large number of pre-built Solaris
58 packages for 32 and 64 bit Intel and Sparc architectures,
59 including current versions of Mercurial.</para>
61 </sect2>
62 <sect2>
63 <title>Mac OS X</title>
65 <para>Lee Cantey publishes an installer of Mercurial for Mac OS
66 X at <ulink
67 url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.
68 This package works on both Intel- and Power-based Macs.
69 Before you can use it, you must install a compatible version
70 of Universal MacPython <citation>web:macpython</citation>.
71 This is easy to do; simply follow the instructions on Lee's
72 site.</para>
74 <para>It's also possible to install Mercurial using Fink or
75 MacPorts, two popular free package managers for Mac OS X. If
76 you have Fink, use <command>sudo apt-get install
77 mercurial-py25</command>. If MacPorts, <command>sudo port
78 install mercurial</command>.</para>
80 </sect2>
81 <sect2>
82 <title>Windows</title>
84 <para>Lee Cantey publishes an installer of Mercurial for Windows
85 at <ulink
86 url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.
87 This package has no external dependencies; it <quote>just
88 works</quote>.</para>
90 <note>
91 <para> The Windows version of Mercurial does not
92 automatically convert line endings between Windows and Unix
93 styles. If you want to share work with Unix users, you must
94 do a little additional configuration work. XXX Flesh this
95 out.</para>
96 </note>
98 </sect2>
99 </sect1>
100 <sect1>
101 <title>Getting started</title>
103 <para>To begin, we'll use the <command role="hg-cmd">hg
104 version</command> command to find out whether Mercurial is
105 actually installed properly. The actual version information
106 that it prints isn't so important; it's whether it prints
107 anything at all that we care about. <!--
108 &interaction.tour.version; --></para>
110 <sect2>
111 <title>Built-in help</title>
113 <para>Mercurial provides a built-in help system. This is
114 invaluable for those times when you find yourself stuck trying
115 to remember how to run a command. If you are completely
116 stuck, simply run <command role="hg-cmd">hg help</command>; it
117 will print a brief list of commands, along with a description
118 of what each does. If you ask for help on a specific command
119 (as below), it prints more detailed information. <!--
120 &interaction.tour.help; --> For a more impressive level of
121 detail (which you won't usually need) run <command
122 role="hg-cmd">hg help <option
123 role="hg-opt-global">-v</option></command>. The <option
124 role="hg-opt-global">-v</option> option is short for <option
125 role="hg-opt-global">--verbose</option>, and tells Mercurial
126 to print more information than it usually would.</para>
128 </sect2>
129 </sect1>
130 <sect1>
131 <title>Working with a repository</title>
133 <para>In Mercurial, everything happens inside a
134 <emphasis>repository</emphasis>. The repository for a project
135 contains all of the files that <quote>belong to</quote> that
136 project, along with a historical record of the project's
137 files.</para>
139 <para>There's nothing particularly magical about a repository; it
140 is simply a directory tree in your filesystem that Mercurial
141 treats as special. You can rename or delete a repository any
142 time you like, using either the command line or your file
143 browser.</para>
145 <sect2>
146 <title>Making a local copy of a repository</title>
148 <para><emphasis>Copying</emphasis> a repository is just a little
149 bit special. While you could use a normal file copying
150 command to make a copy of a repository, it's best to use a
151 built-in command that Mercurial provides. This command is
152 called <command role="hg-cmd">hg clone</command>, because it
153 creates an identical copy of an existing repository. <!--
154 &interaction.tour.clone; --> If our clone succeeded, we should
155 now have a local directory called <filename
156 class="directory">hello</filename>. This directory will
157 contain some files. <!-- &interaction.tour.ls; --> These files
158 have the same contents and history in our repository as they
159 do in the repository we cloned.</para>
161 <para>Every Mercurial repository is complete, self-contained,
162 and independent. It contains its own private copy of a
163 project's files and history. A cloned repository remembers
164 the location of the repository it was cloned from, but it does
165 not communicate with that repository, or any other, unless you
166 tell it to.</para>
168 <para>What this means for now is that we're free to experiment
169 with our repository, safe in the knowledge that it's a private
170 <quote>sandbox</quote> that won't affect anyone else.</para>
172 </sect2>
173 <sect2>
174 <title>What's in a repository?</title>
176 <para>When we take a more detailed look inside a repository, we
177 can see that it contains a directory named <filename
178 class="directory">.hg</filename>. This is where Mercurial
179 keeps all of its metadata for the repository. <!--
180 &interaction.tour.ls-a; --></para>
182 <para>The contents of the <filename
183 class="directory">.hg</filename> directory and its
184 subdirectories are private to Mercurial. Every other file and
185 directory in the repository is yours to do with as you
186 please.</para>
188 <para>To introduce a little terminology, the <filename
189 class="directory">.hg</filename> directory is the
190 <quote>real</quote> repository, and all of the files and
191 directories that coexist with it are said to live in the
192 <emphasis>working directory</emphasis>. An easy way to
193 remember the distinction is that the
194 <emphasis>repository</emphasis> contains the
195 <emphasis>history</emphasis> of your project, while the
196 <emphasis>working directory</emphasis> contains a
197 <emphasis>snapshot</emphasis> of your project at a particular
198 point in history.</para>
200 </sect2>
201 </sect1>
202 <sect1>
203 <title>A tour through history</title>
205 <para>One of the first things we might want to do with a new,
206 unfamiliar repository is understand its history. The <command
207 role="hg-cmd">hg log</command> command gives us a view of
208 history. <!-- &interaction.tour.log; --> By default, this
209 command prints a brief paragraph of output for each change to
210 the project that was recorded. In Mercurial terminology, we
211 call each of these recorded events a
212 <emphasis>changeset</emphasis>, because it can contain a record
213 of changes to several files.</para>
215 <para>The fields in a record of output from <command
216 role="hg-cmd">hg log</command> are as follows.</para>
217 <itemizedlist>
218 <listitem><para><literal>changeset</literal>: This field has the
219 format of a number, followed by a colon, followed by a
220 hexadecimal string. These are
221 <emphasis>identifiers</emphasis> for the changeset. There
222 are two identifiers because the number is shorter and easier
223 to type than the hex string.</para></listitem>
224 <listitem><para><literal>user</literal>: The identity of the
225 person who created the changeset. This is a free-form
226 field, but it most often contains a person's name and email
227 address.</para></listitem>
228 <listitem><para><literal>date</literal>: The date and time on
229 which the changeset was created, and the timezone in which
230 it was created. (The date and time are local to that
231 timezone; they display what time and date it was for the
232 person who created the changeset.)</para></listitem>
233 <listitem><para><literal>summary</literal>: The first line of
234 the text message that the creator of the changeset entered
235 to describe the changeset.</para></listitem></itemizedlist>
236 <para>The default output printed by <command role="hg-cmd">hg
237 log</command> is purely a summary; it is missing a lot of
238 detail.</para>
240 <para>Figure <xref id="fig:tour-basic:history"/> provides a
241 graphical representation of the history of the <filename
242 class="directory">hello</filename> repository, to make it a
243 little easier to see which direction history is
244 <quote>flowing</quote> in. We'll be returning to this figure
245 several times in this chapter and the chapter that
246 follows.</para>
248 <figure>
250 <para> <mediaobject><imageobject><imagedata
251 fileref="tour-history"/></imageobject><textobject><phrase>XXX
252 add text</phrase></textobject></mediaobject>
253 <caption>Graphical history of the <filename
254 class="directory">hello</filename> repository</caption>
255 \label{fig:tour-basic:history}</para>
256 </figure>
258 <sect2>
259 <title>Changesets, revisions, and talking to other
260 people</title>
262 <para>As English is a notoriously sloppy language, and computer
263 science has a hallowed history of terminological confusion
264 (why use one term when four will do?), revision control has a
265 variety of words and phrases that mean the same thing. If you
266 are talking about Mercurial history with other people, you
267 will find that the word <quote>changeset</quote> is often
268 compressed to <quote>change</quote> or (when written)
269 <quote>cset</quote>, and sometimes a changeset is referred to
270 as a <quote>revision</quote> or a <quote>rev</quote>.</para>
272 <para>While it doesn't matter what <emphasis>word</emphasis> you
273 use to refer to the concept of <quote>a changeset</quote>, the
274 <emphasis>identifier</emphasis> that you use to refer to
275 <quote>a <emphasis>specific</emphasis> changeset</quote> is of
276 great importance. Recall that the <literal>changeset</literal>
277 field in the output from <command role="hg-cmd">hg
278 log</command> identifies a changeset using both a number and
279 a hexadecimal string.</para>
280 <itemizedlist>
281 <listitem><para>The revision number is <emphasis>only valid in
282 that repository</emphasis>,</para></listitem>
283 <listitem><para>while the hex string is the
284 <emphasis>permanent, unchanging identifier</emphasis> that
285 will always identify that exact changeset in
286 <emphasis>every</emphasis> copy of the
287 repository.</para></listitem></itemizedlist>
288 <para>This distinction is important. If you send someone an
289 email talking about <quote>revision 33</quote>, there's a high
290 likelihood that their revision 33 will <emphasis>not be the
291 same</emphasis> as yours. The reason for this is that a
292 revision number depends on the order in which changes arrived
293 in a repository, and there is no guarantee that the same
294 changes will happen in the same order in different
295 repositories. Three changes $a,b,c$ can easily appear in one
296 repository as $0,1,2$, while in another as $1,0,2$.</para>
298 <para>Mercurial uses revision numbers purely as a convenient
299 shorthand. If you need to discuss a changeset with someone,
300 or make a record of a changeset for some other reason (for
301 example, in a bug report), use the hexadecimal
302 identifier.</para>
304 </sect2>
305 <sect2>
306 <title>Viewing specific revisions</title>
308 <para>To narrow the output of <command role="hg-cmd">hg
309 log</command> down to a single revision, use the <option
310 role="hg-opt-log">-r</option> (or <option
311 role="hg-opt-log">--rev</option>) option. You can use
312 either a revision number or a long-form changeset identifier,
313 and you can provide as many revisions as you want. <!--
314 &interaction.tour.log-r; --></para>
316 <para>If you want to see the history of several revisions
317 without having to list each one, you can use <emphasis>range
318 notation</emphasis>; this lets you express the idea <quote>I
319 want all revisions between $a$ and $b$, inclusive</quote>.
320 <!-- &interaction.tour.log.range; --> Mercurial also honours
321 the order in which you specify revisions, so <command
322 role="hg-cmd">hg log -r 2:4</command> prints $2,3,4$ while
323 <command role="hg-cmd">hg log -r 4:2</command> prints
324 $4,3,2$.</para>
326 </sect2>
327 <sect2>
328 <title>More detailed information</title>
330 <para>While the summary information printed by <command
331 role="hg-cmd">hg log</command> is useful if you already know
332 what you're looking for, you may need to see a complete
333 description of the change, or a list of the files changed, if
334 you're trying to decide whether a changeset is the one you're
335 looking for. The <command role="hg-cmd">hg log</command>
336 command's <option role="hg-opt-global">-v</option> (or <option
337 role="hg-opt-global">--verbose</option>) option gives you
338 this extra detail. <!-- &interaction.tour.log-v; --></para>
340 <para>If you want to see both the description and content of a
341 change, add the <option role="hg-opt-log">-p</option> (or
342 <option role="hg-opt-log">--patch</option>) option. This
343 displays the content of a change as a <emphasis>unified
344 diff</emphasis> (if you've never seen a unified diff before,
345 see section <xref id="sec:mq:patch"/> for an
346 overview). <!-- &interaction.tour.log-vp; --></para>
348 </sect2>
349 </sect1>
350 <sect1>
351 <title>All about command options</title>
353 <para>Let's take a brief break from exploring Mercurial commands
354 to discuss a pattern in the way that they work; you may find
355 this useful to keep in mind as we continue our tour.</para>
357 <para>Mercurial has a consistent and straightforward approach to
358 dealing with the options that you can pass to commands. It
359 follows the conventions for options that are common to modern
360 Linux and Unix systems.</para>
361 <itemizedlist>
362 <listitem><para>Every option has a long name. For example, as
363 we've already seen, the <command role="hg-cmd">hg
364 log</command> command accepts a <option
365 role="hg-opt-log">--rev</option> option.</para></listitem>
366 <listitem><para>Most options have short names, too. Instead of
367 <option role="hg-opt-log">--rev</option>, we can use <option
368 role="hg-opt-log">-r</option>. (The reason that some
369 options don't have short names is that the options in
370 question are rarely used.)</para></listitem>
371 <listitem><para>Long options start with two dashes (e.g. <option
372 role="hg-opt-log">--rev</option>), while short options
373 start with one (e.g. <option
374 role="hg-opt-log">-r</option>).</para></listitem>
375 <listitem><para>Option naming and usage is consistent across
376 commands. For example, every command that lets you specify
377 a changeset ID or revision number accepts both <option
378 role="hg-opt-log">-r</option> and <option
379 role="hg-opt-log">--rev</option>
380 arguments.</para></listitem></itemizedlist>
381 <para>In the examples throughout this book, I use short options
382 instead of long. This just reflects my own preference, so don't
383 read anything significant into it.</para>
385 <para>Most commands that print output of some kind will print more
386 output when passed a <option role="hg-opt-global">-v</option>
387 (or <option role="hg-opt-global">--verbose</option>) option, and
388 less when passed <option role="hg-opt-global">-q</option> (or
389 <option role="hg-opt-global">--quiet</option>).</para>
391 </sect1>
392 <sect1>
393 <title>Making and reviewing changes</title>
395 <para>Now that we have a grasp of viewing history in Mercurial,
396 let's take a look at making some changes and examining
397 them.</para>
399 <para>The first thing we'll do is isolate our experiment in a
400 repository of its own. We use the <command role="hg-cmd">hg
401 clone</command> command, but we don't need to clone a copy of
402 the remote repository. Since we already have a copy of it
403 locally, we can just clone that instead. This is much faster
404 than cloning over the network, and cloning a local repository
405 uses less disk space in most cases, too. <!--
406 &interaction.tour.reclone; --> As an aside, it's often good
407 practice to keep a <quote>pristine</quote> copy of a remote
408 repository around, which you can then make temporary clones of
409 to create sandboxes for each task you want to work on. This
410 lets you work on multiple tasks in parallel, each isolated from
411 the others until it's complete and you're ready to integrate it
412 back. Because local clones are so cheap, there's almost no
413 overhead to cloning and destroying repositories whenever you
414 want.</para>
416 <para>In our <filename class="directory">my-hello</filename>
417 repository, we have a file <filename>hello.c</filename> that
418 contains the classic <quote>hello, world</quote> program. Let's
419 use the ancient and venerable <command>sed</command> command to
420 edit this file so that it prints a second line of output. (I'm
421 only using <command>sed</command> to do this because it's easy
422 to write a scripted example this way. Since you're not under
423 the same constraint, you probably won't want to use
424 <command>sed</command>; simply use your preferred text editor to
425 do the same thing.) <!-- &interaction.tour.sed; --></para>
427 <para>Mercurial's <command role="hg-cmd">hg status</command>
428 command will tell us what Mercurial knows about the files in the
429 repository. <!-- &interaction.tour.status; --> The <command
430 role="hg-cmd">hg status</command> command prints no output for
431 some files, but a line starting with
432 <quote><literal>M</literal></quote> for
433 <filename>hello.c</filename>. Unless you tell it to, <command
434 role="hg-cmd">hg status</command> will not print any output
435 for files that have not been modified.</para>
437 <para>The <quote><literal>M</literal></quote> indicates that
438 Mercurial has noticed that we modified
439 <filename>hello.c</filename>. We didn't need to
440 <emphasis>inform</emphasis> Mercurial that we were going to
441 modify the file before we started, or that we had modified the
442 file after we were done; it was able to figure this out
443 itself.</para>
445 <para>It's a little bit helpful to know that we've modified
446 <filename>hello.c</filename>, but we might prefer to know
447 exactly <emphasis>what</emphasis> changes we've made to it. To
448 do this, we use the <command role="hg-cmd">hg diff</command>
449 command. <!-- &interaction.tour.diff; --></para>
451 </sect1>
452 <sect1>
453 <title>Recording changes in a new changeset</title>
455 <para>We can modify files, build and test our changes, and use
456 <command role="hg-cmd">hg status</command> and <command
457 role="hg-cmd">hg diff</command> to review our changes, until
458 we're satisfied with what we've done and arrive at a natural
459 stopping point where we want to record our work in a new
460 changeset.</para>
462 <para>The <command role="hg-cmd">hg commit</command> command lets
463 us create a new changeset; we'll usually refer to this as
464 <quote>making a commit</quote> or
465 <quote>committing</quote>.</para>
467 <sect2>
468 <title>Setting up a username</title>
470 <para>When you try to run <command role="hg-cmd">hg
471 commit</command> for the first time, it is not guaranteed to
472 succeed. Mercurial records your name and address with each
473 change that you commit, so that you and others will later be
474 able to tell who made each change. Mercurial tries to
475 automatically figure out a sensible username to commit the
476 change with. It will attempt each of the following methods,
477 in order:</para>
478 <orderedlist>
479 <listitem><para>If you specify a <option
480 role="hg-opt-commit">-u</option> option to the <command
481 role="hg-cmd">hg commit</command> command on the command
482 line, followed by a username, this is always given the
483 highest precedence.</para></listitem>
484 <listitem><para>If you have set the <envar>HGUSER</envar>
485 environment variable, this is checked
486 next.</para></listitem>
487 <listitem><para>If you create a file in your home directory
488 called <filename role="special">.hgrc</filename>, with a
489 <envar role="rc-item-ui">username</envar> entry, that will
490 be used next. To see what the contents of this file
491 should look like, refer to section <xref
492 id="sec:tour-basic:username"/>
493 below.</para></listitem>
494 <listitem><para>If you have set the <envar>EMAIL</envar>
495 environment variable, this will be used
496 next.</para></listitem>
497 <listitem><para>Mercurial will query your system to find out
498 your local user name and host name, and construct a
499 username from these components. Since this often results
500 in a username that is not very useful, it will print a
501 warning if it has to do
502 this.</para></listitem></orderedlist>
503 <listitem><para>If all of these mechanisms fail, Mercurial will
504 fail, printing an error message. In this case, it will not
505 let you commit until you set up a
506 username.</para></listitem>
507 <listitem><para>You should think of the <envar>HGUSER</envar>
508 environment variable and the <option
509 role="hg-opt-commit">-u</option> option to the <command
510 role="hg-cmd">hg commit</command> command as ways to
511 <emphasis>override</emphasis> Mercurial's default selection
512 of username. For normal use, the simplest and most robust
513 way to set a username for yourself is by creating a
514 <filename role="special">.hgrc</filename> file; see below
515 for details.</para></listitem>
516 <sect3>
517 <title>Creating a Mercurial configuration file</title>
518 <listitem><para>\label{sec:tour-basic:username}</para></listitem>
519 <listitem><para>To set a user name, use your favourite editor
520 to create a file called <filename
521 role="special">.hgrc</filename> in your home directory.
522 Mercurial will use this file to look up your personalised
523 configuration settings. The initial contents of your
524 <filename role="special">.hgrc</filename> should look like
525 this.</para></listitem><programlisting>
526 <listitem><para> # This is a Mercurial configuration file.
527 [ui] username = Firstname Lastname
528 <email.address@domain.net></para></listitem></programlisting>
529 <listitem><para>The <quote><literal>[ui]</literal></quote>
530 line begins a <emphasis>section</emphasis> of the config
531 file, so you can read the <quote><literal>username =
532 ...</literal></quote> line as meaning <quote>set the
533 value of the <literal>username</literal> item in the
534 <literal>ui</literal> section</quote>. A section
535 continues until a new section begins, or the end of the
536 file. Mercurial ignores empty lines and treats any text
537 from <quote><literal>#</literal></quote> to the end of a
538 line as a comment.</para></listitem>
539 </sect3>
540 <sect3>
541 <title>Choosing a user name</title>
543 <listitem><para>You can use any text you like as the value of
544 the <literal>username</literal> config item, since this
545 information is for reading by other people, but for
546 interpreting by Mercurial. The convention that most
547 people follow is to use their name and email address, as
548 in the example above.</para></listitem>
549 <note>
550 <listitem><para> Mercurial's built-in web server obfuscates
551 email addresses, to make it more difficult for the email
552 harvesting tools that spammers use. This reduces the
553 likelihood that you'll start receiving more junk email
554 if you publish a Mercurial repository on the
555 web.</para></listitem></note>
557 </sect3>
558 </sect2>
559 <sect2>
560 <title>Writing a commit message</title>
562 <listitem><para>When we commit a change, Mercurial drops us into
563 a text editor, to enter a message that will describe the
564 modifications we've made in this changeset. This is called
565 the <emphasis>commit message</emphasis>. It will be a
566 record for readers of what we did and why, and it will be
567 printed by <command role="hg-cmd">hg log</command> after
568 we've finished committing. <!-- &interaction.tour.commit;
569 --></para></listitem>
570 <listitem><para>The editor that the <command role="hg-cmd">hg
571 commit</command> command drops us into will contain an
572 empty line, followed by a number of lines starting with
573 <quote><literal>HG:</literal></quote>.</para></listitem><programlisting>
574 <listitem><para> <emphasis>empty line</emphasis> HG: changed
575 hello.c</para></listitem></programlisting>
576 <listitem><para>Mercurial ignores the lines that start with
577 <quote><literal>HG:</literal></quote>; it uses them only to
578 tell us which files it's recording changes to. Modifying or
579 deleting these lines has no effect.</para></listitem>
580 </sect2>
581 <sect2>
582 <title>Writing a good commit message</title>
584 <listitem><para>Since <command role="hg-cmd">hg log</command>
585 only prints the first line of a commit message by default,
586 it's best to write a commit message whose first line stands
587 alone. Here's a real example of a commit message that
588 <emphasis>doesn't</emphasis> follow this guideline, and
589 hence has a summary that is not
590 readable.</para></listitem><programlisting>
591 <listitem><para> changeset: 73:584af0e231be user: Censored
592 Person <censored.person@example.org> date: Tue Sep
593 26 21:37:07 2006 -0700 summary: include
594 buildmeister/commondefs. Add an exports and
595 install</para></listitem></programlisting>
597 <listitem><para>As far as the remainder of the contents of the
598 commit message are concerned, there are no hard-and-fast
599 rules. Mercurial itself doesn't interpret or care about the
600 contents of the commit message, though your project may have
601 policies that dictate a certain kind of
602 formatting.</para></listitem>
603 <listitem><para>My personal preference is for short, but
604 informative, commit messages that tell me something that I
605 can't figure out with a quick glance at the output of
606 <command role="hg-cmd">hg log
607 --patch</command>.</para></listitem>
608 </sect2>
609 <sect2>
610 <title>Aborting a commit</title>
612 <listitem><para>If you decide that you don't want to commit
613 while in the middle of editing a commit message, simply exit
614 from your editor without saving the file that it's editing.
615 This will cause nothing to happen to either the repository
616 or the working directory.</para></listitem>
617 <listitem><para>If we run the <command role="hg-cmd">hg
618 commit</command> command without any arguments, it records
619 all of the changes we've made, as reported by <command
620 role="hg-cmd">hg status</command> and <command
621 role="hg-cmd">hg diff</command>.</para></listitem>
622 </sect2>
623 <sect2>
624 <title>Admiring our new handiwork</title>
626 <listitem><para>Once we've finished the commit, we can use the
627 <command role="hg-cmd">hg tip</command> command to display
628 the changeset we just created. This command produces output
629 that is identical to <command role="hg-cmd">hg
630 log</command>, but it only displays the newest revision in
631 the repository. <!-- &interaction.tour.tip; --> We refer to
632 the newest revision in the repository as the tip revision,
633 or simply the tip.</para></listitem>
634 </sect2>
635 </sect1>
636 <sect1>
637 <title>Sharing changes</title>
639 <listitem><para>We mentioned earlier that repositories in
640 Mercurial are self-contained. This means that the changeset
641 we just created exists only in our <filename
642 class="directory">my-hello</filename> repository. Let's
643 look at a few ways that we can propagate this change into
644 other repositories.</para></listitem>
645 <sect2>
646 <title>Pulling changes from another repository</title>
647 <listitem><para>\label{sec:tour:pull}</para></listitem>
648 <listitem><para>To get started, let's clone our original
649 <filename class="directory">hello</filename> repository,
650 which does not contain the change we just committed. We'll
651 call our temporary repository <filename
652 class="directory">hello-pull</filename>. <!--
653 &interaction.tour.clone-pull; --></para></listitem>
654 <listitem><para>We'll use the <command role="hg-cmd">hg
655 pull</command> command to bring changes from <filename
656 class="directory">my-hello</filename> into <filename
657 class="directory">hello-pull</filename>. However, blindly
658 pulling unknown changes into a repository is a somewhat
659 scary prospect. Mercurial provides the <command
660 role="hg-cmd">hg incoming</command> command to tell us
661 what changes the <command role="hg-cmd">hg pull</command>
662 command <emphasis>would</emphasis> pull into the repository,
663 without actually pulling the changes in. <!--
664 &interaction.tour.incoming; --> (Of course, someone could
665 cause more changesets to appear in the repository that we
666 ran <command role="hg-cmd">hg incoming</command> in, before
667 we get a chance to <command role="hg-cmd">hg pull</command>
668 the changes, so that we could end up pulling changes that we
669 didn't expect.)</para></listitem>
670 <listitem><para>Bringing changes into a repository is a simple
671 matter of running the <command role="hg-cmd">hg
672 pull</command> command, and telling it which repository to
673 pull from. <!-- &interaction.tour.pull; --> As you can see
674 from the before-and-after output of <command
675 role="hg-cmd">hg tip</command>, we have successfully
676 pulled changes into our repository. There remains one step
677 before we can see these changes in the working
678 directory.</para></listitem>
679 </sect2>
680 <sect2>
681 <title>Updating the working directory</title>
683 <listitem><para>We have so far glossed over the relationship
684 between a repository and its working directory. The
685 <command role="hg-cmd">hg pull</command> command that we ran
686 in section <xref id="sec:tour:pull"/> brought changes into
687 the
688 repository, but if we check, there's no sign of those
689 changes in the working directory. This is because <command
690 role="hg-cmd">hg pull</command> does not (by default)
691 touch the working directory. Instead, we use the <command
692 role="hg-cmd">hg update</command> command to do this. <!--
693 &interaction.tour.update; --></para></listitem>
694 <listitem><para>It might seem a bit strange that <command
695 role="hg-cmd">hg pull</command> doesn't update the working
696 directory automatically. There's actually a good reason for
697 this: you can use <command role="hg-cmd">hg update</command>
698 to update the working directory to the state it was in at
699 <emphasis>any revision</emphasis> in the history of the
700 repository. If you had the working directory updated to an
701 old revision---to hunt down the origin of a bug, say---and
702 ran a <command role="hg-cmd">hg pull</command> which
703 automatically updated the working directory to a new
704 revision, you might not be terribly happy.</para></listitem>
705 <listitem><para>However, since pull-then-update is such a common
706 thing to do, Mercurial lets you combine the two by passing
707 the <option role="hg-opt-pull">-u</option> option to
708 <command role="hg-cmd">hg
709 pull</command>.</para></listitem><programlisting>
710 <listitem><para> hg pull
711 -u</para></listitem></programlisting>
712 <listitem><para>If you look back at the output of <command
713 role="hg-cmd">hg pull</command> in section <xref
714 id="sec:tour:pull"/> when we ran it without <option
715 role="hg-opt-pull">-u</option>, you can see that it
716 printed a helpful reminder that we'd have to take an
717 explicit step to update the working
718 directory:</para></listitem><programlisting>
719 <listitem><para> (run 'hg update' to get a working
720 copy)</para></listitem></programlisting>
722 <listitem><para>To find out what revision the working directory
723 is at, use the <command role="hg-cmd">hg parents</command>
724 command. <!-- &interaction.tour.parents; --> If you look
725 back at figure <xref id="fig:tour-basic:history"/>, you'll
726 see arrows connecting each changeset. The node that the
727 arrow leads <emphasis>from</emphasis> in each case is a
728 parent, and the node that the arrow leads
729 <emphasis>to</emphasis> is its child. The working directory
730 has a parent in just the same way; this is the changeset
731 that the working directory currently
732 contains.</para></listitem>
733 <listitem><para>To update the working directory to a particular
734 revision, give a revision number or changeset ID to the
735 <command role="hg-cmd">hg update</command> command. <!--
736 &interaction.tour.older; --> If you omit an explicit
737 revision, <command role="hg-cmd">hg update</command> will
738 update to the tip revision, as shown by the second call to
739 <command role="hg-cmd">hg update</command> in the example
740 above.</para></listitem>
741 </sect2>
742 <sect2>
743 <title>Pushing changes to another repository</title>
745 <listitem><para>Mercurial lets us push changes to another
746 repository, from the repository we're currently visiting.
747 As with the example of <command role="hg-cmd">hg
748 pull</command> above, we'll create a temporary repository
749 to push our changes into. <!-- &interaction.tour.clone-push;
750 --> The <command role="hg-cmd">hg outgoing</command> command
751 tells us what changes would be pushed into another
752 repository. <!-- &interaction.tour.outgoing; --> And the
753 <command role="hg-cmd">hg push</command> command does the
754 actual push. <!-- &interaction.tour.push; --> As with
755 <command role="hg-cmd">hg pull</command>, the <command
756 role="hg-cmd">hg push</command> command does not update
757 the working directory in the repository that it's pushing
758 changes into. (Unlike <command role="hg-cmd">hg
759 pull</command>, <command role="hg-cmd">hg push</command>
760 does not provide a <literal>-u</literal> option that updates
761 the other repository's working directory.)</para></listitem>
762 <listitem><para>What happens if we try to pull or push changes
763 and the receiving repository already has those changes?
764 Nothing too exciting. <!-- &interaction.tour.push.nothing;
765 --></para></listitem>
766 </sect2>
767 <sect2>
768 <title>Sharing changes over a network</title>
770 <listitem><para>The commands we have covered in the previous few
771 sections are not limited to working with local repositories.
772 Each works in exactly the same fashion over a network
773 connection; simply pass in a URL instead of a local path.
774 <!-- &interaction.tour.outgoing.net; --> In this example, we
775 can see what changes we could push to the remote repository,
776 but the repository is understandably not set up to let
777 anonymous users push to it. <!-- &interaction.tour.push.net;
778 --></para></listitem>
779 </sect2>
780 </sect1>
781 </chapter>
783 <!--
784 local variables:
785 sgml-parent-document: ("00book.xml" "book" "chapter")
786 end:
787 -->