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