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