hgbook
view en/ch01-tour-basic.xml @ 591:b788b405e141
Replace uses of <informalfigure> with <figure>
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Thu Mar 26 21:07:39 2009 -0700 (2009-03-26) |
| parents | c838b3975bc6 |
| children | 4ce9d0754af3 |
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>Linux</title>
17 <para id="x_2">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 id="x_3">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 id="x_4">Debian:</para>
33 <programlisting>apt-get install mercurial</programlisting></listitem>
34 <listitem><para id="x_5">Fedora Core:</para>
35 <programlisting>yum install mercurial</programlisting></listitem>
36 <listitem><para id="x_6">Gentoo:</para>
37 <programlisting>emerge mercurial</programlisting></listitem>
38 <listitem><para id="x_7">OpenSUSE:</para>
39 <programlisting>yum install mercurial</programlisting></listitem>
40 <listitem><para id="x_8">Ubuntu: Ubuntu's Mercurial package is based on
41 Debian's. To install it, run the following
42 command.</para>
43 <programlisting>apt-get install mercurial</programlisting></listitem>
44 </itemizedlist>
46 </sect2>
47 <sect2>
48 <title>Solaris</title>
50 <para id="x_9">SunFreeWare, at <ulink
51 url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>,
52 is a good source for a large number of pre-built Solaris
53 packages for 32 and 64 bit Intel and Sparc architectures,
54 including current versions of Mercurial.</para>
56 </sect2>
57 <sect2>
58 <title>Mac OS X</title>
60 <para id="x_a">Lee Cantey publishes an installer of Mercurial for Mac OS
61 X at <ulink
62 url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.
63 This package works on both Intel- and Power-based Macs. Before
64 you can use it, you must install a compatible version of
65 Universal MacPython <citation>web:macpython</citation>. This
66 is easy to do; simply follow the instructions on Lee's
67 site.</para>
69 <para id="x_b">It's also possible to install Mercurial using Fink or
70 MacPorts, two popular free package managers for Mac OS X. If
71 you have Fink, use <command>sudo apt-get install
72 mercurial-py25</command>. If MacPorts, <command>sudo port
73 install mercurial</command>.</para>
75 </sect2>
76 <sect2>
77 <title>Windows</title>
79 <para id="x_c">Lee Cantey publishes an installer of Mercurial for Windows
80 at <ulink
81 url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.
82 This package has no external dependencies; it <quote>just
83 works</quote>.</para>
85 <note>
86 <para id="x_d"> The Windows version of Mercurial does not
87 automatically convert line endings between Windows and Unix
88 styles. If you want to share work with Unix users, you must
89 do a little additional configuration work. XXX Flesh this
90 out.</para>
91 </note>
93 </sect2>
94 </sect1>
95 <sect1>
96 <title>Getting started</title>
98 <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg
99 version</command> command to find out whether Mercurial is
100 actually installed properly. The actual version information
101 that it prints isn't so important; it's whether it prints
102 anything at all that we care about.</para>
104 &interaction.tour.version;
106 <sect2>
107 <title>Built-in help</title>
109 <para id="x_f">Mercurial provides a built-in help system. This is
110 invaluable for those times when you find yourself stuck
111 trying to remember how to run a command. If you are
112 completely stuck, simply run <command role="hg-cmd">hg
113 help</command>; it will print a brief list of commands,
114 along with a description of what each does. If you ask for
115 help on a specific command (as below), it prints more
116 detailed information.</para>
118 &interaction.tour.help;
120 <para id="x_10">For a more impressive level of detail (which you won't
121 usually need) run <command role="hg-cmd">hg help <option
122 role="hg-opt-global">-v</option></command>. The <option
123 role="hg-opt-global">-v</option> option is short for
124 <option role="hg-opt-global">--verbose</option>, and tells
125 Mercurial to print more information than it usually
126 would.</para>
128 </sect2>
129 </sect1>
130 <sect1>
131 <title>Working with a repository</title>
133 <para id="x_11">In Mercurial, everything happens inside a
134 <emphasis>repository</emphasis>. The repository for a project
135 contains all of the files that <quote>belong to</quote> that
136 project, along with a historical record of the project's
137 files.</para>
139 <para id="x_12">There's nothing particularly magical about a repository; it
140 is simply a directory tree in your filesystem that Mercurial
141 treats as special. You can rename or delete a repository any
142 time you like, using either the command line or your file
143 browser.</para>
145 <sect2>
146 <title>Making a local copy of a repository</title>
148 <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little
149 bit special. While you could use a normal file copying
150 command to make a copy of a repository, it's best to use a
151 built-in command that Mercurial provides. This command is
152 called <command role="hg-cmd">hg clone</command>, because it
153 creates an identical copy of an existing repository.</para>
155 &interaction.tour.clone;
157 <para id="x_14">If our clone succeeded, we should now have a local
158 directory called <filename class="directory">hello</filename>.
159 This directory will contain some files.</para>
161 &interaction.tour.ls;
163 <para id="x_15">These files have the same contents and history in our
164 repository as they do in the repository we cloned.</para>
166 <para id="x_16">Every Mercurial repository is complete, self-contained,
167 and independent. It contains its own private copy of a
168 project's files and history. A cloned repository remembers
169 the location of the repository it was cloned from, but it does
170 not communicate with that repository, or any other, unless you
171 tell it to.</para>
173 <para id="x_17">What this means for now is that we're free to experiment
174 with our repository, safe in the knowledge that it's a private
175 <quote>sandbox</quote> that won't affect anyone else.</para>
177 </sect2>
178 <sect2>
179 <title>What's in a repository?</title>
181 <para id="x_18">When we take a more detailed look inside a repository, we
182 can see that it contains a directory named <filename
183 class="directory">.hg</filename>. This is where Mercurial
184 keeps all of its metadata for the repository.</para>
186 &interaction.tour.ls-a;
188 <para id="x_19">The contents of the <filename
189 class="directory">.hg</filename> directory and its
190 subdirectories are private to Mercurial. Every other file and
191 directory in the repository is yours to do with as you
192 please.</para>
194 <para id="x_1a">To introduce a little terminology, the <filename
195 class="directory">.hg</filename> directory is the
196 <quote>real</quote> repository, and all of the files and
197 directories that coexist with it are said to live in the
198 <emphasis>working directory</emphasis>. An easy way to
199 remember the distinction is that the
200 <emphasis>repository</emphasis> contains the
201 <emphasis>history</emphasis> of your project, while the
202 <emphasis>working directory</emphasis> contains a
203 <emphasis>snapshot</emphasis> of your project at a particular
204 point in history.</para>
206 </sect2>
207 </sect1>
208 <sect1>
209 <title>A tour through history</title>
211 <para id="x_1b">One of the first things we might want to do with a new,
212 unfamiliar repository is understand its history. The <command
213 role="hg-cmd">hg log</command> command gives us a view of
214 history.</para>
216 &interaction.tour.log;
218 <para id="x_1c">By default, this command prints a brief paragraph of output
219 for each change to the project that was recorded. In Mercurial
220 terminology, we call each of these recorded events a
221 <emphasis>changeset</emphasis>, because it can contain a record
222 of changes to several files.</para>
224 <para id="x_1d">The fields in a record of output from <command
225 role="hg-cmd">hg log</command> are as follows.</para>
226 <itemizedlist>
227 <listitem><para id="x_1e"><literal>changeset</literal>: This field has the
228 format of a number, followed by a colon, followed by a
229 hexadecimal string. These are
230 <emphasis>identifiers</emphasis> for the changeset. There
231 are two identifiers because the number is shorter and easier
232 to type than the hex string.</para></listitem>
233 <listitem><para id="x_1f"><literal>user</literal>: The identity of the
234 person who created the changeset. This is a free-form
235 field, but it most often contains a person's name and email
236 address.</para></listitem>
237 <listitem><para id="x_20"><literal>date</literal>: The date and time on
238 which the changeset was created, and the timezone in which
239 it was created. (The date and time are local to that
240 timezone; they display what time and date it was for the
241 person who created the changeset.)</para></listitem>
242 <listitem><para id="x_21"><literal>summary</literal>: The first line of
243 the text message that the creator of the changeset entered
244 to describe the changeset.</para></listitem></itemizedlist>
245 <para id="x_22">The default output printed by <command role="hg-cmd">hg
246 log</command> is purely a summary; it is missing a lot of
247 detail.</para>
249 <para id="x_23">Figure <xref linkend="fig:tour-basic:history"/> provides a
250 graphical representation of the history of the <filename
251 class="directory">hello</filename> repository, to make it a
252 little easier to see which direction history is
253 <quote>flowing</quote> in. We'll be returning to this figure
254 several times in this chapter and the chapter that
255 follows.</para>
257 <figure id="fig:tour-basic:history">
258 <title>Graphical history of the <filename
259 class="directory">hello</filename> repository</title>
260 <mediaobject>
261 <imageobject><imagedata fileref="tour-history"/></imageobject>
262 <textobject><phrase>XXX add text</phrase></textobject>
263 </mediaobject>
264 </figure>
266 <sect2>
267 <title>Changesets, revisions, and talking to other
268 people</title>
270 <para id="x_25">As English is a notoriously sloppy language, and computer
271 science has a hallowed history of terminological confusion
272 (why use one term when four will do?), revision control has a
273 variety of words and phrases that mean the same thing. If you
274 are talking about Mercurial history with other people, you
275 will find that the word <quote>changeset</quote> is often
276 compressed to <quote>change</quote> or (when written)
277 <quote>cset</quote>, and sometimes a changeset is referred to
278 as a <quote>revision</quote> or a <quote>rev</quote>.</para>
280 <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you
281 use to refer to the concept of <quote>a changeset</quote>, the
282 <emphasis>identifier</emphasis> that you use to refer to
283 <quote>a <emphasis>specific</emphasis> changeset</quote> is of
284 great importance. Recall that the <literal>changeset</literal>
285 field in the output from <command role="hg-cmd">hg
286 log</command> identifies a changeset using both a number and
287 a hexadecimal string.</para>
288 <itemizedlist>
289 <listitem><para id="x_27">The revision number is <emphasis>only valid in
290 that repository</emphasis>,</para></listitem>
291 <listitem><para id="x_28">while the hex 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>
296 <para id="x_29">This distinction is important. If you send someone an
297 email talking about <quote>revision 33</quote>, there's a high
298 likelihood that their revision 33 will <emphasis>not be the
299 same</emphasis> as yours. The reason for this is that a
300 revision number depends on the order in which changes arrived
301 in a repository, and there is no guarantee that the same
302 changes will happen in the same order in different
303 repositories. Three changes $a,b,c$ can easily appear in one
304 repository as $0,1,2$, while in another as $1,0,2$.</para>
306 <para id="x_2a">Mercurial uses revision numbers purely as a convenient
307 shorthand. If you need to discuss a changeset with someone,
308 or make a record of a changeset for some other reason (for
309 example, in a bug report), use the hexadecimal
310 identifier.</para>
312 </sect2>
313 <sect2>
314 <title>Viewing specific revisions</title>
316 <para id="x_2b">To narrow the output of <command role="hg-cmd">hg
317 log</command> down to a single revision, use the <option
318 role="hg-opt-log">-r</option> (or <option
319 role="hg-opt-log">--rev</option>) option. You can use
320 either a revision number or a long-form changeset identifier,
321 and you can provide as many revisions as you want.</para>
323 &interaction.tour.log-r;
325 <para id="x_2c">If you want to see the history of several revisions
326 without having to list each one, you can use <emphasis>range
327 notation</emphasis>; this lets you express the idea <quote>I
328 want all revisions between <literal>abc</literal> and
329 <literal>def</literal>, inclusive</quote>.</para>
331 &interaction.tour.log.range;
333 <para id="x_2d">Mercurial also honours the order in which you specify
334 revisions, so <command role="hg-cmd">hg log -r 2:4</command>
335 prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
336 4:2</command> prints 4, 3, and 2.</para>
338 </sect2>
339 <sect2>
340 <title>More detailed information</title>
342 <para id="x_2e">While the summary information printed by <command
343 role="hg-cmd">hg log</command> is useful if you already know
344 what you're looking for, you may need to see a complete
345 description of the change, or a list of the files changed, if
346 you're trying to decide whether a changeset is the one you're
347 looking for. The <command role="hg-cmd">hg log</command>
348 command's <option role="hg-opt-global">-v</option> (or <option
349 role="hg-opt-global">--verbose</option>) option gives you
350 this extra detail.</para>
352 &interaction.tour.log-v;
354 <para id="x_2f">If you want to see both the description and content of a
355 change, add the <option role="hg-opt-log">-p</option> (or
356 <option role="hg-opt-log">--patch</option>) option. This
357 displays the content of a change as a <emphasis>unified
358 diff</emphasis> (if you've never seen a unified diff before,
359 see section <xref linkend="sec:mq:patch"/> for an
360 overview).</para>
362 &interaction.tour.log-vp;
364 </sect2>
365 </sect1>
366 <sect1>
367 <title>All about command options</title>
369 <para id="x_30">Let's take a brief break from exploring Mercurial commands
370 to discuss a pattern in the way that they work; you may find
371 this useful to keep in mind as we continue our tour.</para>
373 <para id="x_31">Mercurial has a consistent and straightforward approach to
374 dealing with the options that you can pass to commands. It
375 follows the conventions for options that are common to modern
376 Linux and Unix systems.</para>
377 <itemizedlist>
378 <listitem><para id="x_32">Every option has a long name. For example, as
379 we've already seen, the <command role="hg-cmd">hg
380 log</command> command accepts a <option
381 role="hg-opt-log">--rev</option> option.</para></listitem>
382 <listitem><para id="x_33">Most options have short names, too. Instead of
383 <option role="hg-opt-log">--rev</option>, we can use <option
384 role="hg-opt-log">-r</option>. (The reason that some
385 options don't have short names is that the options in
386 question are rarely used.)</para></listitem>
387 <listitem><para id="x_34">Long options start with two dashes (e.g. <option
388 role="hg-opt-log">--rev</option>), while short options
389 start with one (e.g. <option
390 role="hg-opt-log">-r</option>).</para></listitem>
391 <listitem><para id="x_35">Option naming and usage is consistent across
392 commands. For example, every command that lets you specify
393 a changeset ID or revision number accepts both <option
394 role="hg-opt-log">-r</option> and <option
395 role="hg-opt-log">--rev</option>
396 arguments.</para></listitem></itemizedlist>
397 <para id="x_36">In the examples throughout this book, I use short options
398 instead of long. This just reflects my own preference, so don't
399 read anything significant into it.</para>
401 <para id="x_37">Most commands that print output of some kind will print more
402 output when passed a <option role="hg-opt-global">-v</option>
403 (or <option role="hg-opt-global">--verbose</option>) option, and
404 less when passed <option role="hg-opt-global">-q</option> (or
405 <option role="hg-opt-global">--quiet</option>).</para>
407 </sect1>
408 <sect1>
409 <title>Making and reviewing changes</title>
411 <para id="x_38">Now that we have a grasp of viewing history in Mercurial,
412 let's take a look at making some changes and examining
413 them.</para>
415 <para id="x_39">The first thing we'll do is isolate our experiment in a
416 repository of its own. We use the <command role="hg-cmd">hg
417 clone</command> command, but we don't need to clone a copy of
418 the remote repository. Since we already have a copy of it
419 locally, we can just clone that instead. This is much faster
420 than cloning over the network, and cloning a local repository
421 uses less disk space in most cases, too.</para>
423 &interaction.tour.reclone;
425 <para id="x_3a">As an aside, it's often good practice to keep a
426 <quote>pristine</quote> copy of a remote repository around,
427 which you can then make temporary clones of to create sandboxes
428 for each task you want to work on. This lets you work on
429 multiple tasks in parallel, each isolated from the others until
430 it's complete and you're ready to integrate it back. Because
431 local clones are so cheap, there's almost no overhead to cloning
432 and destroying repositories whenever you want.</para>
434 <para id="x_3b">In our <filename class="directory">my-hello</filename>
435 repository, we have a file <filename>hello.c</filename> that
436 contains the classic <quote>hello, world</quote> program. Let's
437 use the ancient and venerable <command>sed</command> command to
438 edit this file so that it prints a second line of output. (I'm
439 only using <command>sed</command> to do this because it's easy
440 to write a scripted example this way. Since you're not under
441 the same constraint, you probably won't want to use
442 <command>sed</command>; simply use your preferred text editor to
443 do the same thing.)</para>
445 &interaction.tour.sed;
447 <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command>
448 command will tell us what Mercurial knows about the files in the
449 repository.</para>
451 &interaction.tour.status;
453 <para id="x_3d">The <command role="hg-cmd">hg status</command> command
454 prints no output for some files, but a line starting with
455 <quote><literal>M</literal></quote> for
456 <filename>hello.c</filename>. Unless you tell it to, <command
457 role="hg-cmd">hg status</command> will not print any output
458 for files that have not been modified.</para>
460 <para id="x_3e">The <quote><literal>M</literal></quote> indicates that
461 Mercurial has noticed that we modified
462 <filename>hello.c</filename>. We didn't need to
463 <emphasis>inform</emphasis> Mercurial that we were going to
464 modify the file before we started, or that we had modified the
465 file after we were done; it was able to figure this out
466 itself.</para>
468 <para id="x_3f">It's a little bit helpful to know that we've modified
469 <filename>hello.c</filename>, but we might prefer to know
470 exactly <emphasis>what</emphasis> changes we've made to it. To
471 do this, we use the <command role="hg-cmd">hg diff</command>
472 command.</para>
474 &interaction.tour.diff;
476 </sect1>
477 <sect1>
478 <title>Recording changes in a new changeset</title>
480 <para id="x_40">We can modify files, build and test our changes, and use
481 <command role="hg-cmd">hg status</command> and <command
482 role="hg-cmd">hg diff</command> to review our changes, until
483 we're satisfied with what we've done and arrive at a natural
484 stopping point where we want to record our work in a new
485 changeset.</para>
487 <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets
488 us create a new changeset; we'll usually refer to this as
489 <quote>making a commit</quote> or
490 <quote>committing</quote>.</para>
492 <sect2>
493 <title>Setting up a username</title>
495 <para id="x_42">When you try to run <command role="hg-cmd">hg
496 commit</command> for the first time, it is not guaranteed to
497 succeed. Mercurial records your name and address with each
498 change that you commit, so that you and others will later be
499 able to tell who made each change. Mercurial tries to
500 automatically figure out a sensible username to commit the
501 change with. It will attempt each of the following methods,
502 in order:</para>
503 <orderedlist>
504 <listitem><para id="x_43">If you specify a <option
505 role="hg-opt-commit">-u</option> option to the <command
506 role="hg-cmd">hg commit</command> command on the command
507 line, followed by a username, this is always given the
508 highest precedence.</para></listitem>
509 <listitem><para id="x_44">If you have set the <envar>HGUSER</envar>
510 environment variable, this is checked
511 next.</para></listitem>
512 <listitem><para id="x_45">If you create a file in your home directory
513 called <filename role="special">.hgrc</filename>, with a
514 <envar role="rc-item-ui">username</envar> entry, that will
515 be used next. To see what the contents of this file
516 should look like, refer to section <xref
517 linkend="sec:tour-basic:username"/>
518 below.</para></listitem>
519 <listitem><para id="x_46">If you have set the <envar>EMAIL</envar>
520 environment variable, this will be used
521 next.</para></listitem>
522 <listitem><para id="x_47">Mercurial will query your system to find out
523 your local user name and host name, and construct a
524 username from these components. Since this often results
525 in a username that is not very useful, it will print a
526 warning if it has to do
527 this.</para></listitem>
528 </orderedlist>
529 <para id="x_48">If all of these mechanisms fail, Mercurial will
530 fail, printing an error message. In this case, it will not
531 let you commit until you set up a
532 username.</para>
533 <para id="x_49">You should think of the <envar>HGUSER</envar> environment
534 variable and the <option role="hg-opt-commit">-u</option>
535 option to the <command role="hg-cmd">hg commit</command>
536 command as ways to <emphasis>override</emphasis> Mercurial's
537 default selection of username. For normal use, the simplest
538 and most robust way to set a username for yourself is by
539 creating a <filename role="special">.hgrc</filename> file; see
540 below for details.</para>
541 <sect3 id="sec:tour-basic:username">
542 <title>Creating a Mercurial configuration file</title>
544 <para id="x_4a">To set a user name, use your favourite editor
545 to create a file called <filename
546 role="special">.hgrc</filename> in your home directory.
547 Mercurial will use this file to look up your personalised
548 configuration settings. The initial contents of your
549 <filename role="special">.hgrc</filename> should look like
550 this.</para>
551 <programlisting># This is a Mercurial configuration file.
552 [ui]
553 username = Firstname Lastname
554 <email.address@domain.net></programlisting>
556 <para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a
557 <emphasis>section</emphasis> of the config file, so you can
558 read the <quote><literal>username = ...</literal></quote>
559 line as meaning <quote>set the value of the
560 <literal>username</literal> item in the
561 <literal>ui</literal> section</quote>. A section continues
562 until a new section begins, or the end of the file.
563 Mercurial ignores empty lines and treats any text from
564 <quote><literal>#</literal></quote> to the end of a line as
565 a comment.</para>
566 </sect3>
568 <sect3>
569 <title>Choosing a user name</title>
571 <para id="x_4c">You can use any text you like as the value of
572 the <literal>username</literal> config item, since this
573 information is for reading by other people, but for
574 interpreting by Mercurial. The convention that most
575 people follow is to use their name and email address, as
576 in the example above.</para>
577 <note>
578 <para id="x_4d">Mercurial's built-in web server obfuscates
579 email addresses, to make it more difficult for the email
580 harvesting tools that spammers use. This reduces the
581 likelihood that you'll start receiving more junk email
582 if you publish a Mercurial repository on the
583 web.</para></note>
585 </sect3>
586 </sect2>
587 <sect2>
588 <title>Writing a commit message</title>
590 <para id="x_4e">When we commit a change, Mercurial drops us into
591 a text editor, to enter a message that will describe the
592 modifications we've made in this changeset. This is called
593 the <emphasis>commit message</emphasis>. It will be a
594 record for readers of what we did and why, and it will be
595 printed by <command role="hg-cmd">hg log</command> after
596 we've finished committing.</para>
598 &interaction.tour.commit;
600 <para id="x_4f">The editor that the <command role="hg-cmd">hg
601 commit</command> command drops us into will contain an
602 empty line, followed by a number of lines starting with
603 <quote><literal>HG:</literal></quote>.</para>
605 <programlisting>XXX fix this XXX</programlisting>
607 <para id="x_50">Mercurial ignores the lines that start with
608 <quote><literal>HG:</literal></quote>; it uses them only to
609 tell us which files it's recording changes to. Modifying or
610 deleting these lines has no effect.</para>
611 </sect2>
612 <sect2>
613 <title>Writing a good commit message</title>
615 <para id="x_51">Since <command role="hg-cmd">hg log</command>
616 only prints the first line of a commit message by default,
617 it's best to write a commit message whose first line stands
618 alone. Here's a real example of a commit message that
619 <emphasis>doesn't</emphasis> follow this guideline, and
620 hence has a summary that is not
621 readable.</para>
623 <programlisting>
624 changeset: 73:584af0e231be
625 user: Censored Person <censored.person@example.org>
626 date: Tue Sep 26 21:37:07 2006 -0700
627 summary: include buildmeister/commondefs. Add exports.</programlisting>
629 <para id="x_52">As far as the remainder of the contents of the
630 commit message are concerned, there are no hard-and-fast
631 rules. Mercurial itself doesn't interpret or care about the
632 contents of the commit message, though your project may have
633 policies that dictate a certain kind of
634 formatting.</para>
635 <para id="x_53">My personal preference is for short, but
636 informative, commit messages that tell me something that I
637 can't figure out with a quick glance at the output of
638 <command role="hg-cmd">hg log
639 --patch</command>.</para>
640 </sect2>
641 <sect2>
642 <title>Aborting a commit</title>
644 <para id="x_54">If you decide that you don't want to commit
645 while in the middle of editing a commit message, simply exit
646 from your editor without saving the file that it's editing.
647 This will cause nothing to happen to either the repository
648 or the working directory.</para>
649 <para id="x_55">If we run the <command role="hg-cmd">hg
650 commit</command> command without any arguments, it records
651 all of the changes we've made, as reported by <command
652 role="hg-cmd">hg status</command> and <command
653 role="hg-cmd">hg diff</command>.</para>
654 </sect2>
655 <sect2>
656 <title>Admiring our new handiwork</title>
658 <para id="x_56">Once we've finished the commit, we can use the
659 <command role="hg-cmd">hg tip</command> command to display
660 the changeset we just created. This command produces output
661 that is identical to <command role="hg-cmd">hg
662 log</command>, but it only displays the newest revision in
663 the repository.</para>
665 &interaction.tour.tip;
667 <para id="x_57">We refer to
668 the newest revision in the repository as the tip revision,
669 or simply the tip.</para>
670 </sect2>
671 </sect1>
673 <sect1>
674 <title>Sharing changes</title>
676 <para id="x_58">We mentioned earlier that repositories in
677 Mercurial are self-contained. This means that the changeset
678 we just created exists only in our <filename
679 class="directory">my-hello</filename> repository. Let's
680 look at a few ways that we can propagate this change into
681 other repositories.</para>
683 <sect2 id="sec:tour:pull">
684 <title>Pulling changes from another repository</title>
685 <para id="x_59">To get started, let's clone our original
686 <filename class="directory">hello</filename> repository,
687 which does not contain the change we just committed. We'll
688 call our temporary repository <filename
689 class="directory">hello-pull</filename>.</para>
691 &interaction.tour.clone-pull;
693 <para id="x_5a">We'll use the <command role="hg-cmd">hg
694 pull</command> command to bring changes from <filename
695 class="directory">my-hello</filename> into <filename
696 class="directory">hello-pull</filename>. However, blindly
697 pulling unknown changes into a repository is a somewhat
698 scary prospect. Mercurial provides the <command
699 role="hg-cmd">hg incoming</command> command to tell us
700 what changes the <command role="hg-cmd">hg pull</command>
701 command <emphasis>would</emphasis> pull into the repository,
702 without actually pulling the changes in.</para>
704 &interaction.tour.incoming;
706 <para id="x_5b">(Of course, someone could
707 cause more changesets to appear in the repository that we
708 ran <command role="hg-cmd">hg incoming</command> in, before
709 we get a chance to <command role="hg-cmd">hg pull</command>
710 the changes, so that we could end up pulling changes that we
711 didn't expect.)</para>
713 <para id="x_5c">Bringing changes into a repository is a simple
714 matter of running the <command role="hg-cmd">hg
715 pull</command> command, and telling it which repository to
716 pull from.</para>
718 &interaction.tour.pull;
720 <para id="x_5d">As you can see
721 from the before-and-after output of <command
722 role="hg-cmd">hg tip</command>, we have successfully
723 pulled changes into our repository. There remains one step
724 before we can see these changes in the working
725 directory.</para>
726 </sect2>
727 <sect2>
728 <title>Updating the working directory</title>
730 <para id="x_5e">We have so far glossed over the relationship between a
731 repository and its working directory. The <command
732 role="hg-cmd">hg pull</command> command that we ran in
733 section <xref linkend="sec:tour:pull"/> brought changes
734 into the repository, but if we check, there's no sign of those
735 changes in the working directory. This is because <command
736 role="hg-cmd">hg pull</command> does not (by default) touch
737 the working directory. Instead, we use the <command
738 role="hg-cmd">hg update</command> command to do this.</para>
740 &interaction.tour.update;
742 <para id="x_5f">It might seem a bit strange that <command role="hg-cmd">hg
743 pull</command> doesn't update the working directory
744 automatically. There's actually a good reason for this: you
745 can use <command role="hg-cmd">hg update</command> to update
746 the working directory to the state it was in at <emphasis>any
747 revision</emphasis> in the history of the repository. If
748 you had the working directory updated to an old revision---to
749 hunt down the origin of a bug, say---and ran a <command
750 role="hg-cmd">hg pull</command> which automatically updated
751 the working directory to a new revision, you might not be
752 terribly happy.</para>
753 <para id="x_60">However, since pull-then-update is such a common thing to
754 do, Mercurial lets you combine the two by passing the <option
755 role="hg-opt-pull">-u</option> option to <command
756 role="hg-cmd">hg pull</command>.</para>
758 <para id="x_61">If you look back at the output of <command
759 role="hg-cmd">hg pull</command> in section <xref
760 linkend="sec:tour:pull"/> when we ran it without <option
761 role="hg-opt-pull">-u</option>, you can see that it printed
762 a helpful reminder that we'd have to take an explicit step to
763 update the working directory:</para>
765 <!-- &interaction.xxx.fixme; -->
767 <para id="x_62">To find out what revision the working directory is at, use
768 the <command role="hg-cmd">hg parents</command>
769 command.</para>
771 &interaction.tour.parents;
773 <para id="x_63">If you look back at figure <xref
774 linkend="fig:tour-basic:history"/>,
775 you'll see arrows connecting each changeset. The node that
776 the arrow leads <emphasis>from</emphasis> in each case is a
777 parent, and the node that the arrow leads
778 <emphasis>to</emphasis> is its child. The working directory
779 has a parent in just the same way; this is the changeset that
780 the working directory currently contains.</para>
782 <para id="x_64">To update the working directory to a particular revision,
784 give a revision number or changeset ID to the <command
785 role="hg-cmd">hg update</command> command.</para>
787 &interaction.tour.older;
789 <para id="x_65">If you omit an explicit revision, <command
790 role="hg-cmd">hg update</command> will update to the tip
791 revision, as shown by the second call to <command
792 role="hg-cmd">hg update</command> in the example
793 above.</para>
794 </sect2>
796 <sect2>
797 <title>Pushing changes to another repository</title>
799 <para id="x_66">Mercurial lets us push changes to another
800 repository, from the repository we're currently visiting.
801 As with the example of <command role="hg-cmd">hg
802 pull</command> above, we'll create a temporary repository
803 to push our changes into.</para>
805 &interaction.tour.clone-push;
807 <para id="x_67">The <command role="hg-cmd">hg outgoing</command> command
808 tells us what changes would be pushed into another
809 repository.</para>
811 &interaction.tour.outgoing;
813 <para id="x_68">And the
814 <command role="hg-cmd">hg push</command> command does the
815 actual push.</para>
817 &interaction.tour.push;
819 <para id="x_69">As with
820 <command role="hg-cmd">hg pull</command>, the <command
821 role="hg-cmd">hg push</command> command does not update
822 the working directory in the repository that it's pushing
823 changes into. (Unlike <command role="hg-cmd">hg
824 pull</command>, <command role="hg-cmd">hg push</command>
825 does not provide a <literal>-u</literal> option that updates
826 the other repository's working directory.)</para>
828 <para id="x_6a">What happens if we try to pull or push changes
829 and the receiving repository already has those changes?
830 Nothing too exciting.</para>
832 &interaction.tour.push.nothing;
833 </sect2>
834 <sect2>
835 <title>Sharing changes over a network</title>
837 <para id="x_6b">The commands we have covered in the previous few
838 sections are not limited to working with local repositories.
839 Each works in exactly the same fashion over a network
840 connection; simply pass in a URL instead of a local
841 path.</para>
843 &interaction.tour.outgoing.net;
845 <para id="x_6c">In this example, we
846 can see what changes we could push to the remote repository,
847 but the repository is understandably not set up to let
848 anonymous users push to it.</para>
850 &interaction.tour.push.net;
851 </sect2>
852 </sect1>
853 </chapter>
855 <!--
856 local variables:
857 sgml-parent-document: ("00book.xml" "book" "chapter")
858 end:
859 -->