hgbook
view en/ch01-tour-basic.xml @ 584:c838b3975bc6
Add IDs to paragraphs.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Thu Mar 19 21:18:52 2009 -0700 (2009-03-19) |
| parents | 28b5a5befb08 |
| children | b788b405e141 |
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 <informalfigure id="fig:tour-basic:history">
258 <mediaobject>
259 <imageobject><imagedata fileref="tour-history"/></imageobject>
260 <textobject><phrase>XXX add text</phrase></textobject>
261 <caption><para id="x_24">Graphical history of the <filename
262 class="directory">hello</filename>
263 repository</para></caption>
264 </mediaobject>
265 </informalfigure>
267 <sect2>
268 <title>Changesets, revisions, and talking to other
269 people</title>
271 <para id="x_25">As English is a notoriously sloppy language, and computer
272 science has a hallowed history of terminological confusion
273 (why use one term when four will do?), revision control has a
274 variety of words and phrases that mean the same thing. If you
275 are talking about Mercurial history with other people, you
276 will find that the word <quote>changeset</quote> is often
277 compressed to <quote>change</quote> or (when written)
278 <quote>cset</quote>, and sometimes a changeset is referred to
279 as a <quote>revision</quote> or a <quote>rev</quote>.</para>
281 <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you
282 use to refer to the concept of <quote>a changeset</quote>, the
283 <emphasis>identifier</emphasis> that you use to refer to
284 <quote>a <emphasis>specific</emphasis> changeset</quote> is of
285 great importance. Recall that the <literal>changeset</literal>
286 field in the output from <command role="hg-cmd">hg
287 log</command> identifies a changeset using both a number and
288 a hexadecimal string.</para>
289 <itemizedlist>
290 <listitem><para id="x_27">The revision number is <emphasis>only valid in
291 that repository</emphasis>,</para></listitem>
292 <listitem><para id="x_28">while the hex string is the
293 <emphasis>permanent, unchanging identifier</emphasis> that
294 will always identify that exact changeset in
295 <emphasis>every</emphasis> copy of the
296 repository.</para></listitem></itemizedlist>
297 <para id="x_29">This distinction is important. If you send someone an
298 email talking about <quote>revision 33</quote>, there's a high
299 likelihood that their revision 33 will <emphasis>not be the
300 same</emphasis> as yours. The reason for this is that a
301 revision number depends on the order in which changes arrived
302 in a repository, and there is no guarantee that the same
303 changes will happen in the same order in different
304 repositories. Three changes $a,b,c$ can easily appear in one
305 repository as $0,1,2$, while in another as $1,0,2$.</para>
307 <para id="x_2a">Mercurial uses revision numbers purely as a convenient
308 shorthand. If you need to discuss a changeset with someone,
309 or make a record of a changeset for some other reason (for
310 example, in a bug report), use the hexadecimal
311 identifier.</para>
313 </sect2>
314 <sect2>
315 <title>Viewing specific revisions</title>
317 <para id="x_2b">To narrow the output of <command role="hg-cmd">hg
318 log</command> down to a single revision, use the <option
319 role="hg-opt-log">-r</option> (or <option
320 role="hg-opt-log">--rev</option>) option. You can use
321 either a revision number or a long-form changeset identifier,
322 and you can provide as many revisions as you want.</para>
324 &interaction.tour.log-r;
326 <para id="x_2c">If you want to see the history of several revisions
327 without having to list each one, you can use <emphasis>range
328 notation</emphasis>; this lets you express the idea <quote>I
329 want all revisions between <literal>abc</literal> and
330 <literal>def</literal>, inclusive</quote>.</para>
332 &interaction.tour.log.range;
334 <para id="x_2d">Mercurial also honours the order in which you specify
335 revisions, so <command role="hg-cmd">hg log -r 2:4</command>
336 prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
337 4:2</command> prints 4, 3, and 2.</para>
339 </sect2>
340 <sect2>
341 <title>More detailed information</title>
343 <para id="x_2e">While the summary information printed by <command
344 role="hg-cmd">hg log</command> is useful if you already know
345 what you're looking for, you may need to see a complete
346 description of the change, or a list of the files changed, if
347 you're trying to decide whether a changeset is the one you're
348 looking for. The <command role="hg-cmd">hg log</command>
349 command's <option role="hg-opt-global">-v</option> (or <option
350 role="hg-opt-global">--verbose</option>) option gives you
351 this extra detail.</para>
353 &interaction.tour.log-v;
355 <para id="x_2f">If you want to see both the description and content of a
356 change, add the <option role="hg-opt-log">-p</option> (or
357 <option role="hg-opt-log">--patch</option>) option. This
358 displays the content of a change as a <emphasis>unified
359 diff</emphasis> (if you've never seen a unified diff before,
360 see section <xref linkend="sec:mq:patch"/> for an
361 overview).</para>
363 &interaction.tour.log-vp;
365 </sect2>
366 </sect1>
367 <sect1>
368 <title>All about command options</title>
370 <para id="x_30">Let's take a brief break from exploring Mercurial commands
371 to discuss a pattern in the way that they work; you may find
372 this useful to keep in mind as we continue our tour.</para>
374 <para id="x_31">Mercurial has a consistent and straightforward approach to
375 dealing with the options that you can pass to commands. It
376 follows the conventions for options that are common to modern
377 Linux and Unix systems.</para>
378 <itemizedlist>
379 <listitem><para id="x_32">Every option has a long name. For example, as
380 we've already seen, the <command role="hg-cmd">hg
381 log</command> command accepts a <option
382 role="hg-opt-log">--rev</option> option.</para></listitem>
383 <listitem><para id="x_33">Most options have short names, too. Instead of
384 <option role="hg-opt-log">--rev</option>, we can use <option
385 role="hg-opt-log">-r</option>. (The reason that some
386 options don't have short names is that the options in
387 question are rarely used.)</para></listitem>
388 <listitem><para id="x_34">Long options start with two dashes (e.g. <option
389 role="hg-opt-log">--rev</option>), while short options
390 start with one (e.g. <option
391 role="hg-opt-log">-r</option>).</para></listitem>
392 <listitem><para id="x_35">Option naming and usage is consistent across
393 commands. For example, every command that lets you specify
394 a changeset ID or revision number accepts both <option
395 role="hg-opt-log">-r</option> and <option
396 role="hg-opt-log">--rev</option>
397 arguments.</para></listitem></itemizedlist>
398 <para id="x_36">In the examples throughout this book, I use short options
399 instead of long. This just reflects my own preference, so don't
400 read anything significant into it.</para>
402 <para id="x_37">Most commands that print output of some kind will print more
403 output when passed a <option role="hg-opt-global">-v</option>
404 (or <option role="hg-opt-global">--verbose</option>) option, and
405 less when passed <option role="hg-opt-global">-q</option> (or
406 <option role="hg-opt-global">--quiet</option>).</para>
408 </sect1>
409 <sect1>
410 <title>Making and reviewing changes</title>
412 <para id="x_38">Now that we have a grasp of viewing history in Mercurial,
413 let's take a look at making some changes and examining
414 them.</para>
416 <para id="x_39">The first thing we'll do is isolate our experiment in a
417 repository of its own. We use the <command role="hg-cmd">hg
418 clone</command> command, but we don't need to clone a copy of
419 the remote repository. Since we already have a copy of it
420 locally, we can just clone that instead. This is much faster
421 than cloning over the network, and cloning a local repository
422 uses less disk space in most cases, too.</para>
424 &interaction.tour.reclone;
426 <para id="x_3a">As an aside, it's often good practice to keep a
427 <quote>pristine</quote> copy of a remote repository around,
428 which you can then make temporary clones of to create sandboxes
429 for each task you want to work on. This lets you work on
430 multiple tasks in parallel, each isolated from the others until
431 it's complete and you're ready to integrate it back. Because
432 local clones are so cheap, there's almost no overhead to cloning
433 and destroying repositories whenever you want.</para>
435 <para id="x_3b">In our <filename class="directory">my-hello</filename>
436 repository, we have a file <filename>hello.c</filename> that
437 contains the classic <quote>hello, world</quote> program. Let's
438 use the ancient and venerable <command>sed</command> command to
439 edit this file so that it prints a second line of output. (I'm
440 only using <command>sed</command> to do this because it's easy
441 to write a scripted example this way. Since you're not under
442 the same constraint, you probably won't want to use
443 <command>sed</command>; simply use your preferred text editor to
444 do the same thing.)</para>
446 &interaction.tour.sed;
448 <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command>
449 command will tell us what Mercurial knows about the files in the
450 repository.</para>
452 &interaction.tour.status;
454 <para id="x_3d">The <command role="hg-cmd">hg status</command> command
455 prints no output for some files, but a line starting with
456 <quote><literal>M</literal></quote> for
457 <filename>hello.c</filename>. Unless you tell it to, <command
458 role="hg-cmd">hg status</command> will not print any output
459 for files that have not been modified.</para>
461 <para id="x_3e">The <quote><literal>M</literal></quote> indicates that
462 Mercurial has noticed that we modified
463 <filename>hello.c</filename>. We didn't need to
464 <emphasis>inform</emphasis> Mercurial that we were going to
465 modify the file before we started, or that we had modified the
466 file after we were done; it was able to figure this out
467 itself.</para>
469 <para id="x_3f">It's a little bit helpful to know that we've modified
470 <filename>hello.c</filename>, but we might prefer to know
471 exactly <emphasis>what</emphasis> changes we've made to it. To
472 do this, we use the <command role="hg-cmd">hg diff</command>
473 command.</para>
475 &interaction.tour.diff;
477 </sect1>
478 <sect1>
479 <title>Recording changes in a new changeset</title>
481 <para id="x_40">We can modify files, build and test our changes, and use
482 <command role="hg-cmd">hg status</command> and <command
483 role="hg-cmd">hg diff</command> to review our changes, until
484 we're satisfied with what we've done and arrive at a natural
485 stopping point where we want to record our work in a new
486 changeset.</para>
488 <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets
489 us create a new changeset; we'll usually refer to this as
490 <quote>making a commit</quote> or
491 <quote>committing</quote>.</para>
493 <sect2>
494 <title>Setting up a username</title>
496 <para id="x_42">When you try to run <command role="hg-cmd">hg
497 commit</command> for the first time, it is not guaranteed to
498 succeed. Mercurial records your name and address with each
499 change that you commit, so that you and others will later be
500 able to tell who made each change. Mercurial tries to
501 automatically figure out a sensible username to commit the
502 change with. It will attempt each of the following methods,
503 in order:</para>
504 <orderedlist>
505 <listitem><para id="x_43">If you specify a <option
506 role="hg-opt-commit">-u</option> option to the <command
507 role="hg-cmd">hg commit</command> command on the command
508 line, followed by a username, this is always given the
509 highest precedence.</para></listitem>
510 <listitem><para id="x_44">If you have set the <envar>HGUSER</envar>
511 environment variable, this is checked
512 next.</para></listitem>
513 <listitem><para id="x_45">If you create a file in your home directory
514 called <filename role="special">.hgrc</filename>, with a
515 <envar role="rc-item-ui">username</envar> entry, that will
516 be used next. To see what the contents of this file
517 should look like, refer to section <xref
518 linkend="sec:tour-basic:username"/>
519 below.</para></listitem>
520 <listitem><para id="x_46">If you have set the <envar>EMAIL</envar>
521 environment variable, this will be used
522 next.</para></listitem>
523 <listitem><para id="x_47">Mercurial will query your system to find out
524 your local user name and host name, and construct a
525 username from these components. Since this often results
526 in a username that is not very useful, it will print a
527 warning if it has to do
528 this.</para></listitem>
529 </orderedlist>
530 <para id="x_48">If all of these mechanisms fail, Mercurial will
531 fail, printing an error message. In this case, it will not
532 let you commit until you set up a
533 username.</para>
534 <para id="x_49">You should think of the <envar>HGUSER</envar> environment
535 variable and the <option role="hg-opt-commit">-u</option>
536 option to the <command role="hg-cmd">hg commit</command>
537 command as ways to <emphasis>override</emphasis> Mercurial's
538 default selection of username. For normal use, the simplest
539 and most robust way to set a username for yourself is by
540 creating a <filename role="special">.hgrc</filename> file; see
541 below for details.</para>
542 <sect3 id="sec:tour-basic:username">
543 <title>Creating a Mercurial configuration file</title>
545 <para id="x_4a">To set a user name, use your favourite editor
546 to create a file called <filename
547 role="special">.hgrc</filename> in your home directory.
548 Mercurial will use this file to look up your personalised
549 configuration settings. The initial contents of your
550 <filename role="special">.hgrc</filename> should look like
551 this.</para>
552 <programlisting># This is a Mercurial configuration file.
553 [ui]
554 username = Firstname Lastname
555 <email.address@domain.net></programlisting>
557 <para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a
558 <emphasis>section</emphasis> of the config file, so you can
559 read the <quote><literal>username = ...</literal></quote>
560 line as meaning <quote>set the value of the
561 <literal>username</literal> item in the
562 <literal>ui</literal> section</quote>. A section continues
563 until a new section begins, or the end of the file.
564 Mercurial ignores empty lines and treats any text from
565 <quote><literal>#</literal></quote> to the end of a line as
566 a comment.</para>
567 </sect3>
569 <sect3>
570 <title>Choosing a user name</title>
572 <para id="x_4c">You can use any text you like as the value of
573 the <literal>username</literal> config item, since this
574 information is for reading by other people, but for
575 interpreting by Mercurial. The convention that most
576 people follow is to use their name and email address, as
577 in the example above.</para>
578 <note>
579 <para id="x_4d">Mercurial's built-in web server obfuscates
580 email addresses, to make it more difficult for the email
581 harvesting tools that spammers use. This reduces the
582 likelihood that you'll start receiving more junk email
583 if you publish a Mercurial repository on the
584 web.</para></note>
586 </sect3>
587 </sect2>
588 <sect2>
589 <title>Writing a commit message</title>
591 <para id="x_4e">When we commit a change, Mercurial drops us into
592 a text editor, to enter a message that will describe the
593 modifications we've made in this changeset. This is called
594 the <emphasis>commit message</emphasis>. It will be a
595 record for readers of what we did and why, and it will be
596 printed by <command role="hg-cmd">hg log</command> after
597 we've finished committing.</para>
599 &interaction.tour.commit;
601 <para id="x_4f">The editor that the <command role="hg-cmd">hg
602 commit</command> command drops us into will contain an
603 empty line, followed by a number of lines starting with
604 <quote><literal>HG:</literal></quote>.</para>
606 <programlisting>XXX fix this XXX</programlisting>
608 <para id="x_50">Mercurial ignores the lines that start with
609 <quote><literal>HG:</literal></quote>; it uses them only to
610 tell us which files it's recording changes to. Modifying or
611 deleting these lines has no effect.</para>
612 </sect2>
613 <sect2>
614 <title>Writing a good commit message</title>
616 <para id="x_51">Since <command role="hg-cmd">hg log</command>
617 only prints the first line of a commit message by default,
618 it's best to write a commit message whose first line stands
619 alone. Here's a real example of a commit message that
620 <emphasis>doesn't</emphasis> follow this guideline, and
621 hence has a summary that is not
622 readable.</para>
624 <programlisting>
625 changeset: 73:584af0e231be
626 user: Censored Person <censored.person@example.org>
627 date: Tue Sep 26 21:37:07 2006 -0700
628 summary: include buildmeister/commondefs. Add exports.</programlisting>
630 <para id="x_52">As far as the remainder of the contents of the
631 commit message are concerned, there are no hard-and-fast
632 rules. Mercurial itself doesn't interpret or care about the
633 contents of the commit message, though your project may have
634 policies that dictate a certain kind of
635 formatting.</para>
636 <para id="x_53">My personal preference is for short, but
637 informative, commit messages that tell me something that I
638 can't figure out with a quick glance at the output of
639 <command role="hg-cmd">hg log
640 --patch</command>.</para>
641 </sect2>
642 <sect2>
643 <title>Aborting a commit</title>
645 <para id="x_54">If you decide that you don't want to commit
646 while in the middle of editing a commit message, simply exit
647 from your editor without saving the file that it's editing.
648 This will cause nothing to happen to either the repository
649 or the working directory.</para>
650 <para id="x_55">If we run the <command role="hg-cmd">hg
651 commit</command> command without any arguments, it records
652 all of the changes we've made, as reported by <command
653 role="hg-cmd">hg status</command> and <command
654 role="hg-cmd">hg diff</command>.</para>
655 </sect2>
656 <sect2>
657 <title>Admiring our new handiwork</title>
659 <para id="x_56">Once we've finished the commit, we can use the
660 <command role="hg-cmd">hg tip</command> command to display
661 the changeset we just created. This command produces output
662 that is identical to <command role="hg-cmd">hg
663 log</command>, but it only displays the newest revision in
664 the repository.</para>
666 &interaction.tour.tip;
668 <para id="x_57">We refer to
669 the newest revision in the repository as the tip revision,
670 or simply the tip.</para>
671 </sect2>
672 </sect1>
674 <sect1>
675 <title>Sharing changes</title>
677 <para id="x_58">We mentioned earlier that repositories in
678 Mercurial are self-contained. This means that the changeset
679 we just created exists only in our <filename
680 class="directory">my-hello</filename> repository. Let's
681 look at a few ways that we can propagate this change into
682 other repositories.</para>
684 <sect2 id="sec:tour:pull">
685 <title>Pulling changes from another repository</title>
686 <para id="x_59">To get started, let's clone our original
687 <filename class="directory">hello</filename> repository,
688 which does not contain the change we just committed. We'll
689 call our temporary repository <filename
690 class="directory">hello-pull</filename>.</para>
692 &interaction.tour.clone-pull;
694 <para id="x_5a">We'll use the <command role="hg-cmd">hg
695 pull</command> command to bring changes from <filename
696 class="directory">my-hello</filename> into <filename
697 class="directory">hello-pull</filename>. However, blindly
698 pulling unknown changes into a repository is a somewhat
699 scary prospect. Mercurial provides the <command
700 role="hg-cmd">hg incoming</command> command to tell us
701 what changes the <command role="hg-cmd">hg pull</command>
702 command <emphasis>would</emphasis> pull into the repository,
703 without actually pulling the changes in.</para>
705 &interaction.tour.incoming;
707 <para id="x_5b">(Of course, someone could
708 cause more changesets to appear in the repository that we
709 ran <command role="hg-cmd">hg incoming</command> in, before
710 we get a chance to <command role="hg-cmd">hg pull</command>
711 the changes, so that we could end up pulling changes that we
712 didn't expect.)</para>
714 <para id="x_5c">Bringing changes into a repository is a simple
715 matter of running the <command role="hg-cmd">hg
716 pull</command> command, and telling it which repository to
717 pull from.</para>
719 &interaction.tour.pull;
721 <para id="x_5d">As you can see
722 from the before-and-after output of <command
723 role="hg-cmd">hg tip</command>, we have successfully
724 pulled changes into our repository. There remains one step
725 before we can see these changes in the working
726 directory.</para>
727 </sect2>
728 <sect2>
729 <title>Updating the working directory</title>
731 <para id="x_5e">We have so far glossed over the relationship between a
732 repository and its working directory. The <command
733 role="hg-cmd">hg pull</command> command that we ran in
734 section <xref linkend="sec:tour:pull"/> brought changes
735 into the repository, but if we check, there's no sign of those
736 changes in the working directory. This is because <command
737 role="hg-cmd">hg pull</command> does not (by default) touch
738 the working directory. Instead, we use the <command
739 role="hg-cmd">hg update</command> command to do this.</para>
741 &interaction.tour.update;
743 <para id="x_5f">It might seem a bit strange that <command role="hg-cmd">hg
744 pull</command> doesn't update the working directory
745 automatically. There's actually a good reason for this: you
746 can use <command role="hg-cmd">hg update</command> to update
747 the working directory to the state it was in at <emphasis>any
748 revision</emphasis> in the history of the repository. If
749 you had the working directory updated to an old revision---to
750 hunt down the origin of a bug, say---and ran a <command
751 role="hg-cmd">hg pull</command> which automatically updated
752 the working directory to a new revision, you might not be
753 terribly happy.</para>
754 <para id="x_60">However, since pull-then-update is such a common thing to
755 do, Mercurial lets you combine the two by passing the <option
756 role="hg-opt-pull">-u</option> option to <command
757 role="hg-cmd">hg pull</command>.</para>
759 <para id="x_61">If you look back at the output of <command
760 role="hg-cmd">hg pull</command> in section <xref
761 linkend="sec:tour:pull"/> when we ran it without <option
762 role="hg-opt-pull">-u</option>, you can see that it printed
763 a helpful reminder that we'd have to take an explicit step to
764 update the working directory:</para>
766 <!-- &interaction.xxx.fixme; -->
768 <para id="x_62">To find out what revision the working directory is at, use
769 the <command role="hg-cmd">hg parents</command>
770 command.</para>
772 &interaction.tour.parents;
774 <para id="x_63">If you look back at figure <xref
775 linkend="fig:tour-basic:history"/>,
776 you'll see arrows connecting each changeset. The node that
777 the arrow leads <emphasis>from</emphasis> in each case is a
778 parent, and the node that the arrow leads
779 <emphasis>to</emphasis> is its child. The working directory
780 has a parent in just the same way; this is the changeset that
781 the working directory currently contains.</para>
783 <para id="x_64">To update the working directory to a particular revision,
785 give a revision number or changeset ID to the <command
786 role="hg-cmd">hg update</command> command.</para>
788 &interaction.tour.older;
790 <para id="x_65">If you omit an explicit revision, <command
791 role="hg-cmd">hg update</command> will update to the tip
792 revision, as shown by the second call to <command
793 role="hg-cmd">hg update</command> in the example
794 above.</para>
795 </sect2>
797 <sect2>
798 <title>Pushing changes to another repository</title>
800 <para id="x_66">Mercurial lets us push changes to another
801 repository, from the repository we're currently visiting.
802 As with the example of <command role="hg-cmd">hg
803 pull</command> above, we'll create a temporary repository
804 to push our changes into.</para>
806 &interaction.tour.clone-push;
808 <para id="x_67">The <command role="hg-cmd">hg outgoing</command> command
809 tells us what changes would be pushed into another
810 repository.</para>
812 &interaction.tour.outgoing;
814 <para id="x_68">And the
815 <command role="hg-cmd">hg push</command> command does the
816 actual push.</para>
818 &interaction.tour.push;
820 <para id="x_69">As with
821 <command role="hg-cmd">hg pull</command>, the <command
822 role="hg-cmd">hg push</command> command does not update
823 the working directory in the repository that it's pushing
824 changes into. (Unlike <command role="hg-cmd">hg
825 pull</command>, <command role="hg-cmd">hg push</command>
826 does not provide a <literal>-u</literal> option that updates
827 the other repository's working directory.)</para>
829 <para id="x_6a">What happens if we try to pull or push changes
830 and the receiving repository already has those changes?
831 Nothing too exciting.</para>
833 &interaction.tour.push.nothing;
834 </sect2>
835 <sect2>
836 <title>Sharing changes over a network</title>
838 <para id="x_6b">The commands we have covered in the previous few
839 sections are not limited to working with local repositories.
840 Each works in exactly the same fashion over a network
841 connection; simply pass in a URL instead of a local
842 path.</para>
844 &interaction.tour.outgoing.net;
846 <para id="x_6c">In this example, we
847 can see what changes we could push to the remote repository,
848 but the repository is understandably not set up to let
849 anonymous users push to it.</para>
851 &interaction.tour.push.net;
852 </sect2>
853 </sect1>
854 </chapter>
856 <!--
857 local variables:
858 sgml-parent-document: ("00book.xml" "book" "chapter")
859 end:
860 -->