hgbook
view en/ch01-tour-basic.xml @ 667:3b33dd6aba87
Merge with http://hg.serpentine.com/mercurial/book
| author | Dongsheng Song <songdongsheng@live.cn> |
|---|---|
| date | Thu Apr 02 09:24:36 2009 +0800 (2009-04-02) |
| parents | 1c13ed2130a7 c44d5854620b |
| children | 3b640272a966 |
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 id="x_1">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>Windows</title>
17 <para id="x_c">The best version of Mercurial for Windows is
18 TortoiseHg, which can be found at <ulink
19 url="http://bitbucket.org/tortoisehg/stable/wiki/Home">http://bitbucket.org/tortoisehg/stable/wiki/Home</ulink>.
20 This package has no external dependencies; it <quote>just
21 works</quote>. It provides both command line and graphical
22 user interfaces.</para>
24 </sect2>
26 <sect2>
27 <title>Mac OS X</title>
29 <para id="x_a">Lee Cantey publishes an installer of Mercurial
30 for Mac OS X at <ulink
31 url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para>
32 </sect2>
34 <sect2>
35 <title>Linux</title>
37 <para id="x_2">Because each Linux distribution has its own packaging
38 tools, policies, and rate of development, it's difficult to
39 give a comprehensive set of instructions on how to install
40 Mercurial binaries. The version of Mercurial that you will
41 end up with can vary depending on how active the person is who
42 maintains the package for your distribution.</para>
44 <para id="x_3">To keep things simple, I will focus on installing
45 Mercurial from the command line under the most popular Linux
46 distributions. Most of these distributions provide graphical
47 package managers that will let you install Mercurial with a
48 single click; the package name to look for is
49 <literal>mercurial</literal>.</para>
51 <itemizedlist>
52 <listitem><para id="x_4">Ubuntu and Debian:</para>
53 <programlisting>apt-get install mercurial</programlisting></listitem>
54 <listitem><para id="x_5">Fedora and OpenSUSE:</para>
55 <programlisting>yum install mercurial</programlisting></listitem>
56 <listitem><para id="x_6">Gentoo:</para>
57 <programlisting>emerge mercurial</programlisting></listitem>
58 </itemizedlist>
60 </sect2>
61 <sect2>
62 <title>Solaris</title>
64 <para id="x_9">SunFreeWare, at <ulink
65 url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>,
66 provides prebuilt packages of Mercurial.</para>
68 </sect2>
70 </sect1>
72 <sect1>
73 <title>Getting started</title>
75 <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg
76 version</command> command to find out whether Mercurial is
77 actually installed properly. The actual version information
78 that it prints isn't so important; it's whether it prints
79 anything at all that we care about.</para>
81 &interaction.tour.version;
83 <sect2>
84 <title>Built-in help</title>
86 <para id="x_f">Mercurial provides a built-in help system. This is
87 invaluable for those times when you find yourself stuck
88 trying to remember how to run a command. If you are
89 completely stuck, simply run <command role="hg-cmd">hg
90 help</command>; it will print a brief list of commands,
91 along with a description of what each does. If you ask for
92 help on a specific command (as below), it prints more
93 detailed information.</para>
95 &interaction.tour.help;
97 <para id="x_10">For a more impressive level of detail (which you won't
98 usually need) run <command role="hg-cmd">hg help <option
99 role="hg-opt-global">-v</option></command>. The <option
100 role="hg-opt-global">-v</option> option is short for
101 <option role="hg-opt-global">--verbose</option>, and tells
102 Mercurial to print more information than it usually
103 would.</para>
105 </sect2>
106 </sect1>
107 <sect1>
108 <title>Working with a repository</title>
110 <para id="x_11">In Mercurial, everything happens inside a
111 <emphasis>repository</emphasis>. The repository for a project
112 contains all of the files that <quote>belong to</quote> that
113 project, along with a historical record of the project's
114 files.</para>
116 <para id="x_12">There's nothing particularly magical about a repository; it
117 is simply a directory tree in your filesystem that Mercurial
118 treats as special. You can rename or delete a repository any
119 time you like, using either the command line or your file
120 browser.</para>
122 <sect2>
123 <title>Making a local copy of a repository</title>
125 <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little
126 bit special. While you could use a normal file copying
127 command to make a copy of a repository, it's best to use a
128 built-in command that Mercurial provides. This command is
129 called <command role="hg-cmd">hg clone</command>, because it
130 makes an identical copy of an existing repository.</para>
132 &interaction.tour.clone;
134 <para>One advantage of using <command role="hg-cmd">hg
135 clone</command> is that, as we can see above, it lets us clone
136 repositories over the network. Another is that it remembers
137 where we cloned from, which we'll find useful soon when we
138 want to fetch new changes from another repository.</para>
140 <para id="x_14">If our clone succeeded, we should now have a local
141 directory called <filename class="directory">hello</filename>.
142 This directory will contain some files.</para>
144 &interaction.tour.ls;
146 <para id="x_15">These files have the same contents and history in our
147 repository as they do in the repository we cloned.</para>
149 <para id="x_16">Every Mercurial repository is complete,
150 self-contained, and independent. It contains its own private
151 copy of a project's files and history. As we just mentioned,
152 a cloned repository remembers the location of the repository
153 it was cloned from, but Mercurial will not communicate with
154 that repository, or any other, unless you tell it to.</para>
156 <para id="x_17">What this means for now is that we're free to experiment
157 with our repository, safe in the knowledge that it's a private
158 <quote>sandbox</quote> that won't affect anyone else.</para>
160 </sect2>
161 <sect2>
162 <title>What's in a repository?</title>
164 <para id="x_18">When we take a more detailed look inside a repository, we
165 can see that it contains a directory named <filename
166 class="directory">.hg</filename>. This is where Mercurial
167 keeps all of its metadata for the repository.</para>
169 &interaction.tour.ls-a;
171 <para id="x_19">The contents of the <filename
172 class="directory">.hg</filename> directory and its
173 subdirectories are private to Mercurial. Every other file and
174 directory in the repository is yours to do with as you
175 please.</para>
177 <para id="x_1a">To introduce a little terminology, the <filename
178 class="directory">.hg</filename> directory is the
179 <quote>real</quote> repository, and all of the files and
180 directories that coexist with it are said to live in the
181 <emphasis>working directory</emphasis>. An easy way to
182 remember the distinction is that the
183 <emphasis>repository</emphasis> contains the
184 <emphasis>history</emphasis> of your project, while the
185 <emphasis>working directory</emphasis> contains a
186 <emphasis>snapshot</emphasis> of your project at a particular
187 point in history.</para>
189 </sect2>
190 </sect1>
191 <sect1>
192 <title>A tour through history</title>
194 <para id="x_1b">One of the first things we might want to do with a new,
195 unfamiliar repository is understand its history. The <command
196 role="hg-cmd">hg log</command> command gives us a view of
197 the history of changes in the repository.</para>
199 &interaction.tour.log;
201 <para id="x_1c">By default, this command prints a brief paragraph of output
202 for each change to the project that was recorded. In Mercurial
203 terminology, we call each of these recorded events a
204 <emphasis>changeset</emphasis>, because it can contain a record
205 of changes to several files.</para>
207 <para id="x_1d">The fields in a record of output from <command
208 role="hg-cmd">hg log</command> are as follows.</para>
210 <itemizedlist>
211 <listitem><para id="x_1e"><literal>changeset</literal>: This
212 field has the format of a number, followed by a colon,
213 followed by a hexadecimal (or <emphasis>hex</emphasis>)
214 string. These are <emphasis>identifiers</emphasis> for the
215 changeset. The hex string is a unique identifier: the same
216 hex string will always refer to the same changeset. The
217 number is shorter and easier to type than the hex string,
218 but it isn't unique: the same number in two different clones
219 of a repository may identify different changesets. Why
220 provide the number at all, then? For local
221 convenience.</para>
222 </listitem>
223 <listitem><para id="x_1f"><literal>user</literal>: The identity of the
224 person who created the changeset. This is a free-form
225 field, but it most often contains a person's name and email
226 address.</para></listitem>
227 <listitem><para id="x_20"><literal>date</literal>: The date and time on
228 which the changeset was created, and the timezone in which
229 it was created. (The date and time are local to that
230 timezone; they display what time and date it was for the
231 person who created the changeset.)</para></listitem>
232 <listitem><para id="x_21"><literal>summary</literal>: The first line of
233 the text message that the creator of the changeset entered
234 to describe the changeset.</para></listitem>
235 <listitem>
236 <para>Some changesets, such as the first in the list above,
237 have a <literal>tag</literal> field. A tag is another way
238 to identify a changeset, by giving it an easy-to-remember
239 name. (The tag named <literal>tip</literal> is special: it
240 always refers to the newest change in a repository.)</para>
241 </listitem>
242 </itemizedlist>
244 <para id="x_22">The default output printed by <command
245 role="hg-cmd">hg log</command> is purely a summary; it is
246 missing a lot of detail.</para>
248 <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides
249 a graphical representation of the history of the <filename
250 class="directory">hello</filename> repository, to make it a
251 little easier to see which direction history is
252 <quote>flowing</quote> in. We'll be returning to this figure
253 several times in this chapter and the chapter that
254 follows.</para>
256 <figure id="fig:tour-basic:history">
257 <title>Graphical history of the <filename
258 class="directory">hello</filename> repository</title>
259 <mediaobject>
260 <imageobject><imagedata fileref="figs/tour-history.png"/></imageobject>
261 <textobject><phrase>XXX add text</phrase></textobject>
262 </mediaobject>
263 </figure>
265 <sect2>
266 <title>Changesets, revisions, and talking to other
267 people</title>
269 <para id="x_25">As English is a notoriously sloppy language, and computer
270 science has a hallowed history of terminological confusion
271 (why use one term when four will do?), revision control has a
272 variety of words and phrases that mean the same thing. If you
273 are talking about Mercurial history with other people, you
274 will find that the word <quote>changeset</quote> is often
275 compressed to <quote>change</quote> or (when written)
276 <quote>cset</quote>, and sometimes a changeset is referred to
277 as a <quote>revision</quote> or a <quote>rev</quote>.</para>
279 <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you
280 use to refer to the concept of <quote>a changeset</quote>, the
281 <emphasis>identifier</emphasis> that you use to refer to
282 <quote>a <emphasis>specific</emphasis> changeset</quote> is of
283 great importance. Recall that the <literal>changeset</literal>
284 field in the output from <command role="hg-cmd">hg
285 log</command> identifies a changeset using both a number and
286 a hexadecimal string.</para>
287 <itemizedlist>
288 <listitem><para id="x_27">The revision number is a handy
289 notation that is <emphasis>only valid in that
290 repository</emphasis>.</para></listitem>
291 <listitem><para id="x_28">The hexadecimal string is the
292 <emphasis>permanent, unchanging identifier</emphasis> that
293 will always identify that exact changeset in
294 <emphasis>every</emphasis> copy of the
295 repository.</para></listitem></itemizedlist>
297 <para id="x_29">This distinction is important. If you send
298 someone an email talking about <quote>revision 33</quote>,
299 there's a high likelihood that their revision 33 will
300 <emphasis>not be the same</emphasis> as yours. The reason for
301 this is that a revision number depends on the order in which
302 changes arrived in a repository, and there is no guarantee
303 that the same changes will happen in the same order in
304 different repositories. Three changes <literal>a,b,c</literal>
305 can easily appear in one repository as
306 <literal>0,1,2</literal>, while in another as
307 <literal>0,2,1</literal>.</para>
309 <para id="x_2a">Mercurial uses revision numbers purely as a convenient
310 shorthand. If you need to discuss a changeset with someone,
311 or make a record of a changeset for some other reason (for
312 example, in a bug report), use the hexadecimal
313 identifier.</para>
315 </sect2>
316 <sect2>
317 <title>Viewing specific revisions</title>
319 <para id="x_2b">To narrow the output of <command role="hg-cmd">hg
320 log</command> down to a single revision, use the <option
321 role="hg-opt-log">-r</option> (or <option
322 role="hg-opt-log">--rev</option>) option. You can use
323 either a revision number or a hexadecimal identifier,
324 and you can provide as many revisions as you want.</para>
326 &interaction.tour.log-r;
328 <para id="x_2c">If you want to see the history of several revisions
329 without having to list each one, you can use <emphasis>range
330 notation</emphasis>; this lets you express the idea <quote>I
331 want all revisions between <literal>abc</literal> and
332 <literal>def</literal>, inclusive</quote>.</para>
334 &interaction.tour.log.range;
336 <para id="x_2d">Mercurial also honours the order in which you specify
337 revisions, so <command role="hg-cmd">hg log -r 2:4</command>
338 prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
339 4:2</command> prints 4, 3, and 2.</para>
341 </sect2>
342 <sect2>
343 <title>More detailed information</title>
345 <para id="x_2e">While the summary information printed by <command
346 role="hg-cmd">hg log</command> is useful if you already know
347 what you're looking for, you may need to see a complete
348 description of the change, or a list of the files changed, if
349 you're trying to decide whether a changeset is the one you're
350 looking for. The <command role="hg-cmd">hg log</command>
351 command's <option role="hg-opt-global">-v</option> (or <option
352 role="hg-opt-global">--verbose</option>) option gives you
353 this extra detail.</para>
355 &interaction.tour.log-v;
357 <para id="x_2f">If you want to see both the description and
358 content of a change, add the <option
359 role="hg-opt-log">-p</option> (or <option
360 role="hg-opt-log">--patch</option>) option. This displays
361 the content of a change as a <emphasis>unified diff</emphasis>
362 (if you've never seen a unified diff before, see <xref
363 linkend="sec:mq:patch"/> for an overview).</para>
365 &interaction.tour.log-vp;
367 <para>The <option role="hg-opt-log">-p</option> option is
368 tremendously useful, so it's well worth remembering.</para>
370 </sect2>
371 </sect1>
373 <sect1>
374 <title>All about command options</title>
376 <para id="x_30">Let's take a brief break from exploring Mercurial commands
377 to discuss a pattern in the way that they work; you may find
378 this useful to keep in mind as we continue our tour.</para>
380 <para id="x_31">Mercurial has a consistent and straightforward approach to
381 dealing with the options that you can pass to commands. It
382 follows the conventions for options that are common to modern
383 Linux and Unix systems.</para>
385 <itemizedlist>
386 <listitem>
387 <para id="x_32">Every option has a long name. For example, as
388 we've already seen, the <command role="hg-cmd">hg
389 log</command> command accepts a <option
390 role="hg-opt-log">--rev</option> option.</para>
391 </listitem>
392 <listitem>
393 <para id="x_33">Most options have short names, too. Instead
394 of <option role="hg-opt-log">--rev</option>, we can use
395 <option role="hg-opt-log">-r</option>. (The reason that
396 some options don't have short names is that the options in
397 question are rarely used.)</para>
398 </listitem>
399 <listitem>
400 <para id="x_34">Long options start with two dashes (e.g.
401 <option role="hg-opt-log">--rev</option>), while short
402 options start with one (e.g. <option
403 role="hg-opt-log">-r</option>).</para>
404 </listitem>
405 <listitem>
406 <para id="x_35">Option naming and usage is consistent across
407 commands. For example, every command that lets you specify
408 a changeset ID or revision number accepts both <option
409 role="hg-opt-log">-r</option> and <option
410 role="hg-opt-log">--rev</option> arguments.</para>
411 </listitem>
412 <listitem>
413 <para>If you are using short options, you can save typing by
414 running them together. For example, the command <command
415 role="hg-cmd">hg log -v -p -r 2</command> can be written
416 as <command role="hg-cmd">hg log -vpr2</command>.</para>
417 </listitem>
418 </itemizedlist>
420 <para id="x_36">In the examples throughout this book, I use short options
421 instead of long. This just reflects my own preference, so don't
422 read anything significant into it.</para>
424 <para id="x_37">Most commands that print output of some kind will print more
425 output when passed a <option role="hg-opt-global">-v</option>
426 (or <option role="hg-opt-global">--verbose</option>) option, and
427 less when passed <option role="hg-opt-global">-q</option> (or
428 <option role="hg-opt-global">--quiet</option>).</para>
430 <note>
431 <title>Option naming consistency</title>
433 <para>Almost always, Mercurial commands use consistent option
434 names to refer to the same concepts. For instance, if a
435 command deals with changesets, you'll always identify them
436 with <option role="hg-opt-log">--rev</option> or <option
437 role="hg-opt-log">-r</option>. This consistent use of
438 option names makes it easier to remember what options a
439 particular command takes.</para>
440 </note>
442 </sect1>
443 <sect1>
444 <title>Making and reviewing changes</title>
446 <para id="x_38">Now that we have a grasp of viewing history in Mercurial,
447 let's take a look at making some changes and examining
448 them.</para>
450 <para id="x_39">The first thing we'll do is isolate our experiment in a
451 repository of its own. We use the <command role="hg-cmd">hg
452 clone</command> command, but we don't need to clone a copy of
453 the remote repository. Since we already have a copy of it
454 locally, we can just clone that instead. This is much faster
455 than cloning over the network, and cloning a local repository
456 uses less disk space in most cases, too<footnote>
457 <para>The saving of space arises when source and destination
458 repositories are on the same filesystem, in which case
459 Mercurial will use hardlinks to do copy-on-write sharing of
460 its internal metadata. If that explanation meant nothing to
461 you, don't worry: everything happens transparently and
462 automatically, and you don't need to understand it.</para>
463 </footnote>.</para>
465 &interaction.tour.reclone;
467 <para id="x_3a">As an aside, it's often good practice to keep a
468 <quote>pristine</quote> copy of a remote repository around,
469 which you can then make temporary clones of to create sandboxes
470 for each task you want to work on. This lets you work on
471 multiple tasks in parallel, each isolated from the others until
472 it's complete and you're ready to integrate it back. Because
473 local clones are so cheap, there's almost no overhead to cloning
474 and destroying repositories whenever you want.</para>
476 <para id="x_3b">In our <filename class="directory">my-hello</filename>
477 repository, we have a file <filename>hello.c</filename> that
478 contains the classic <quote>hello, world</quote> program.</para>
480 &interaction.tour.cat1;
482 <para>Let's edit this file so that it prints a second line of
483 output.</para>
485 &interaction.tour.cat2;
487 <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command>
488 command will tell us what Mercurial knows about the files in the
489 repository.</para>
491 &interaction.tour.status;
493 <para id="x_3d">The <command role="hg-cmd">hg status</command> command
494 prints no output for some files, but a line starting with
495 <quote><literal>M</literal></quote> for
496 <filename>hello.c</filename>. Unless you tell it to, <command
497 role="hg-cmd">hg status</command> will not print any output
498 for files that have not been modified.</para>
500 <para id="x_3e">The <quote><literal>M</literal></quote> indicates that
501 Mercurial has noticed that we modified
502 <filename>hello.c</filename>. We didn't need to
503 <emphasis>inform</emphasis> Mercurial that we were going to
504 modify the file before we started, or that we had modified the
505 file after we were done; it was able to figure this out
506 itself.</para>
508 <para id="x_3f">It's somewhat helpful to know that we've modified
509 <filename>hello.c</filename>, but we might prefer to know
510 exactly <emphasis>what</emphasis> changes we've made to it. To
511 do this, we use the <command role="hg-cmd">hg diff</command>
512 command.</para>
514 &interaction.tour.diff;
516 <tip>
517 <title>Understanding patches</title>
519 <para>Remember to take a look at <xref
520 linkend="sec:mq:patch"/> if you don't know how to read
521 output above.</para>
522 </tip>
523 </sect1>
524 <sect1>
525 <title>Recording changes in a new changeset</title>
527 <para id="x_40">We can modify files, build and test our changes, and use
528 <command role="hg-cmd">hg status</command> and <command
529 role="hg-cmd">hg diff</command> to review our changes, until
530 we're satisfied with what we've done and arrive at a natural
531 stopping point where we want to record our work in a new
532 changeset.</para>
534 <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets
535 us create a new changeset; we'll usually refer to this as
536 <quote>making a commit</quote> or
537 <quote>committing</quote>.</para>
539 <sect2>
540 <title>Setting up a username</title>
542 <para id="x_42">When you try to run <command role="hg-cmd">hg
543 commit</command> for the first time, it is not guaranteed to
544 succeed. Mercurial records your name and address with each
545 change that you commit, so that you and others will later be
546 able to tell who made each change. Mercurial tries to
547 automatically figure out a sensible username to commit the
548 change with. It will attempt each of the following methods,
549 in order:</para>
550 <orderedlist>
551 <listitem><para id="x_43">If you specify a <option
552 role="hg-opt-commit">-u</option> option to the <command
553 role="hg-cmd">hg commit</command> command on the command
554 line, followed by a username, this is always given the
555 highest precedence.</para></listitem>
556 <listitem><para id="x_44">If you have set the <envar>HGUSER</envar>
557 environment variable, this is checked
558 next.</para></listitem>
559 <listitem><para id="x_45">If you create a file in your home
560 directory called <filename
561 role="special">.hgrc</filename>, with a <envar
562 role="rc-item-ui">username</envar> entry, that will be
563 used next. To see what the contents of this file should
564 look like, refer to <xref
565 linkend="sec:tour-basic:username"/>
566 below.</para></listitem>
567 <listitem><para id="x_46">If you have set the <envar>EMAIL</envar>
568 environment variable, this will be used
569 next.</para></listitem>
570 <listitem><para id="x_47">Mercurial will query your system to find out
571 your local user name and host name, and construct a
572 username from these components. Since this often results
573 in a username that is not very useful, it will print a
574 warning if it has to do
575 this.</para></listitem>
576 </orderedlist>
577 <para id="x_48">If all of these mechanisms fail, Mercurial will
578 fail, printing an error message. In this case, it will not
579 let you commit until you set up a
580 username.</para>
581 <para id="x_49">You should think of the <envar>HGUSER</envar> environment
582 variable and the <option role="hg-opt-commit">-u</option>
583 option to the <command role="hg-cmd">hg commit</command>
584 command as ways to <emphasis>override</emphasis> Mercurial's
585 default selection of username. For normal use, the simplest
586 and most robust way to set a username for yourself is by
587 creating a <filename role="special">.hgrc</filename> file; see
588 below for details.</para>
589 <sect3 id="sec:tour-basic:username">
590 <title>Creating a Mercurial configuration file</title>
592 <para id="x_4a">To set a user name, use your favourite editor
593 to create a file called <filename
594 role="special">.hgrc</filename> in your home directory.
595 Mercurial will use this file to look up your personalised
596 configuration settings. The initial contents of your
597 <filename role="special">.hgrc</filename> should look like
598 this.</para>
600 <remark>Figure out what the appropriate directory is on
601 Windows.</remark>
603 <programlisting># This is a Mercurial configuration file.
604 [ui]
605 username = Firstname Lastname <email.address@domain.net></programlisting>
607 <para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a
608 <emphasis>section</emphasis> of the config file, so you can
609 read the <quote><literal>username = ...</literal></quote>
610 line as meaning <quote>set the value of the
611 <literal>username</literal> item in the
612 <literal>ui</literal> section</quote>. A section continues
613 until a new section begins, or the end of the file.
614 Mercurial ignores empty lines and treats any text from
615 <quote><literal>#</literal></quote> to the end of a line as
616 a comment.</para>
617 </sect3>
619 <sect3>
620 <title>Choosing a user name</title>
622 <para id="x_4c">You can use any text you like as the value of
623 the <literal>username</literal> config item, since this
624 information is for reading by other people, but will not be
625 interpreted by Mercurial. The convention that most
626 people follow is to use their name and email address, as
627 in the example above.</para>
628 <note>
629 <para id="x_4d">Mercurial's built-in web server obfuscates
630 email addresses, to make it more difficult for the email
631 harvesting tools that spammers use. This reduces the
632 likelihood that you'll start receiving more junk email
633 if you publish a Mercurial repository on the
634 web.</para></note>
636 </sect3>
637 </sect2>
638 <sect2>
639 <title>Writing a commit message</title>
641 <para id="x_4e">When we commit a change, Mercurial drops us into
642 a text editor, to enter a message that will describe the
643 modifications we've made in this changeset. This is called
644 the <emphasis>commit message</emphasis>. It will be a
645 record for readers of what we did and why, and it will be
646 printed by <command role="hg-cmd">hg log</command> after
647 we've finished committing.</para>
649 &interaction.tour.commit;
651 <para id="x_4f">The editor that the <command role="hg-cmd">hg
652 commit</command> command drops us into will contain an
653 empty line or two, followed by a number of lines starting with
654 <quote><literal>HG:</literal></quote>.</para>
656 <programlisting>
657 This is where I type my commit comment.
659 HG: Enter commit message. Lines beginning with 'HG:' are removed.
660 HG: --
661 HG: user: Bryan O'Sullivan <bos@serpentine.com>
662 HG: branch 'default'
663 HG: changed hello.c</programlisting>
665 <para id="x_50">Mercurial ignores the lines that start with
666 <quote><literal>HG:</literal></quote>; it uses them only to
667 tell us which files it's recording changes to. Modifying or
668 deleting these lines has no effect.</para>
669 </sect2>
670 <sect2>
671 <title>Writing a good commit message</title>
673 <para id="x_51">Since <command role="hg-cmd">hg log</command>
674 only prints the first line of a commit message by default,
675 it's best to write a commit message whose first line stands
676 alone. Here's a real example of a commit message that
677 <emphasis>doesn't</emphasis> follow this guideline, and
678 hence has a summary that is not
679 readable.</para>
681 <programlisting>
682 changeset: 73:584af0e231be
683 user: Censored Person <censored.person@example.org>
684 date: Tue Sep 26 21:37:07 2006 -0700
685 summary: include buildmeister/commondefs. Add exports.</programlisting>
687 <para id="x_52">As far as the remainder of the contents of the
688 commit message are concerned, there are no hard-and-fast
689 rules. Mercurial itself doesn't interpret or care about the
690 contents of the commit message, though your project may have
691 policies that dictate a certain kind of
692 formatting.</para>
693 <para id="x_53">My personal preference is for short, but
694 informative, commit messages that tell me something that I
695 can't figure out with a quick glance at the output of
696 <command role="hg-cmd">hg log
697 --patch</command>.</para>
698 </sect2>
699 <sect2>
700 <title>Aborting a commit</title>
702 <para id="x_54">If you decide that you don't want to commit
703 while in the middle of editing a commit message, simply exit
704 from your editor without saving the file that it's editing.
705 This will cause nothing to happen to either the repository
706 or the working directory.</para>
707 <para id="x_55">If we run the <command role="hg-cmd">hg
708 commit</command> command without any arguments, it records
709 all of the changes we've made, as reported by <command
710 role="hg-cmd">hg status</command> and <command
711 role="hg-cmd">hg diff</command>.</para>
712 </sect2>
713 <sect2>
714 <title>Admiring our new handiwork</title>
716 <para id="x_56">Once we've finished the commit, we can use the
717 <command role="hg-cmd">hg tip</command> command to display
718 the changeset we just created. This command produces output
719 that is identical to <command role="hg-cmd">hg
720 log</command>, but it only displays the newest revision in
721 the repository.</para>
723 &interaction.tour.tip;
725 <para id="x_57">We refer to the newest revision in the
726 repository as the <emphasis>tip revision</emphasis>, or simply
727 the <emphasis>tip</emphasis>.</para>
729 <para>By the way, the <command role="hg-cmd">hg tip</command>
730 command accepts many of the same options as <command
731 role="hg-cmd">hg log</command>, so <option
732 role="hg-opt-global">-v</option> above indicates <quote>be
733 verbose</quote>, <option role="hg-opt-tip">-p</option>
734 specifies <quote>print a patch</quote>. The use of <option
735 role="hg-opt-tip">-p</option> to print patches is another
736 example of the consistent naming we mentioned earlier.</para>
737 </sect2>
738 </sect1>
740 <sect1>
741 <title>Sharing changes</title>
743 <para id="x_58">We mentioned earlier that repositories in
744 Mercurial are self-contained. This means that the changeset
745 we just created exists only in our <filename
746 class="directory">my-hello</filename> repository. Let's
747 look at a few ways that we can propagate this change into
748 other repositories.</para>
750 <sect2 id="sec:tour:pull">
751 <title>Pulling changes from another repository</title>
752 <para id="x_59">To get started, let's clone our original
753 <filename class="directory">hello</filename> repository,
754 which does not contain the change we just committed. We'll
755 call our temporary repository <filename
756 class="directory">hello-pull</filename>.</para>
758 &interaction.tour.clone-pull;
760 <para id="x_5a">We'll use the <command role="hg-cmd">hg
761 pull</command> command to bring changes from <filename
762 class="directory">my-hello</filename> into <filename
763 class="directory">hello-pull</filename>. However, blindly
764 pulling unknown changes into a repository is a somewhat
765 scary prospect. Mercurial provides the <command
766 role="hg-cmd">hg incoming</command> command to tell us
767 what changes the <command role="hg-cmd">hg pull</command>
768 command <emphasis>would</emphasis> pull into the repository,
769 without actually pulling the changes in.</para>
771 &interaction.tour.incoming;
773 <para id="x_5b">Suppose you're pulling changes from a repository
774 on the network somewhere. While you are looking at the <command
775 role="hg-cmd">hg incoming</command> output, and before you
776 pull those changes, someone might have committed something in
777 the remote repository. This means that it's possible to pull
778 more changes than you saw when using <command
779 role="hg-cmd">hg incoming</command>.</para>
781 <para id="x_5c">Bringing changes into a repository is a simple
782 matter of running the <command role="hg-cmd">hg
783 pull</command> command, and telling it which repository to
784 pull from.</para>
786 &interaction.tour.pull;
788 <para id="x_5d">As you can see
789 from the before-and-after output of <command
790 role="hg-cmd">hg tip</command>, we have successfully
791 pulled changes into our repository. There remains one step
792 before we can see these changes in the working
793 directory.</para>
794 </sect2>
795 <sect2>
796 <title>Updating the working directory</title>
798 <para id="x_5e">We have so far glossed over the relationship
799 between a repository and its working directory. The <command
800 role="hg-cmd">hg pull</command> command that we ran in
801 <xref linkend="sec:tour:pull"/> brought changes into the
802 repository, but if we check, there's no sign of those changes
803 in the working directory. This is because <command
804 role="hg-cmd">hg pull</command> does not (by default) touch
805 the working directory. Instead, we use the <command
806 role="hg-cmd">hg update</command> command to do this.</para>
808 &interaction.tour.update;
810 <para id="x_5f">It might seem a bit strange that <command role="hg-cmd">hg
811 pull</command> doesn't update the working directory
812 automatically. There's actually a good reason for this: you
813 can use <command role="hg-cmd">hg update</command> to update
814 the working directory to the state it was in at <emphasis>any
815 revision</emphasis> in the history of the repository. If
816 you had the working directory updated to an old revision&emdash;to
817 hunt down the origin of a bug, say&emdash;and ran a <command
818 role="hg-cmd">hg pull</command> which automatically updated
819 the working directory to a new revision, you might not be
820 terribly happy.</para>
821 <para id="x_60">However, since pull-then-update is such a common thing to
822 do, Mercurial lets you combine the two by passing the <option
823 role="hg-opt-pull">-u</option> option to <command
824 role="hg-cmd">hg pull</command>.</para>
826 <para id="x_61">If you look back at the output of <command
827 role="hg-cmd">hg pull</command> in <xref
828 linkend="sec:tour:pull"/> when we ran it without <option
829 role="hg-opt-pull">-u</option>, you can see that it printed
830 a helpful reminder that we'd have to take an explicit step to
831 update the working directory:</para>
833 <!-- &interaction.xxx.fixme; -->
835 <para id="x_62">To find out what revision the working directory is at, use
836 the <command role="hg-cmd">hg parents</command>
837 command.</para>
839 &interaction.tour.parents;
841 <para id="x_63">If you look back at <xref
842 linkend="fig:tour-basic:history"/>,
843 you'll see arrows connecting each changeset. The node that
844 the arrow leads <emphasis>from</emphasis> in each case is a
845 parent, and the node that the arrow leads
846 <emphasis>to</emphasis> is its child. The working directory
847 has a parent in just the same way; this is the changeset that
848 the working directory currently contains.</para>
850 <para id="x_64">To update the working directory to a particular revision,
852 give a revision number or changeset ID to the <command
853 role="hg-cmd">hg update</command> command.</para>
855 &interaction.tour.older;
857 <para id="x_65">If you omit an explicit revision, <command
858 role="hg-cmd">hg update</command> will update to the tip
859 revision, as shown by the second call to <command
860 role="hg-cmd">hg update</command> in the example
861 above.</para>
862 </sect2>
864 <sect2>
865 <title>Pushing changes to another repository</title>
867 <para id="x_66">Mercurial lets us push changes to another
868 repository, from the repository we're currently visiting.
869 As with the example of <command role="hg-cmd">hg
870 pull</command> above, we'll create a temporary repository
871 to push our changes into.</para>
873 &interaction.tour.clone-push;
875 <para id="x_67">The <command role="hg-cmd">hg outgoing</command> command
876 tells us what changes would be pushed into another
877 repository.</para>
879 &interaction.tour.outgoing;
881 <para id="x_68">And the
882 <command role="hg-cmd">hg push</command> command does the
883 actual push.</para>
885 &interaction.tour.push;
887 <para id="x_69">As with <command role="hg-cmd">hg
888 pull</command>, the <command role="hg-cmd">hg push</command>
889 command does not update the working directory in the
890 repository that it's pushing changes into. Unlike <command
891 role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg
892 push</command> does not provide a <literal>-u</literal>
893 option that updates the other repository's working directory.
894 This asymmetry is deliberate: the repository we're pushing to
895 might be on a remote server and shared between several people.
896 If we were to update its working directory while someone was
897 working in it, their work would be disrupted.</para>
899 <para id="x_6a">What happens if we try to pull or push changes
900 and the receiving repository already has those changes?
901 Nothing too exciting.</para>
903 &interaction.tour.push.nothing;
904 </sect2>
905 <sect2>
906 <title>Sharing changes over a network</title>
908 <para id="x_6b">The commands we have covered in the previous few
909 sections are not limited to working with local repositories.
910 Each works in exactly the same fashion over a network
911 connection; simply pass in a URL instead of a local
912 path.</para>
914 &interaction.tour.outgoing.net;
916 <para id="x_6c">In this example, we
917 can see what changes we could push to the remote repository,
918 but the repository is understandably not set up to let
919 anonymous users push to it.</para>
921 &interaction.tour.push.net;
922 </sect2>
923 </sect1>
924 </chapter>
926 <!--
927 local variables:
928 sgml-parent-document: ("00book.xml" "book" "chapter")
929 end:
930 -->