hgbook
view en/ch02-tour-basic.xml @ 738:0edc45e721d5
First literal translation of Ch.4.
| author | Giulio@puck |
|---|---|
| date | Wed Jul 01 17:25:39 2009 +0200 (2009-07-01) |
| parents | d2aacc06e562 |
| children | 1dd00abb3fa9 |
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:</para>
55 <programlisting>yum install mercurial</programlisting></listitem>
56 <listitem><para id="x_715">OpenSUSE:</para>
57 <programlisting>zypper install mercurial</programlisting></listitem>
58 <listitem><para id="x_6">Gentoo:</para>
59 <programlisting>emerge mercurial</programlisting></listitem>
60 </itemizedlist>
62 </sect2>
63 <sect2>
64 <title>Solaris</title>
66 <para id="x_9">SunFreeWare, at <ulink
67 url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>,
68 provides prebuilt packages of Mercurial.</para>
70 </sect2>
72 </sect1>
74 <sect1>
75 <title>Getting started</title>
77 <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg
78 version</command> command to find out whether Mercurial is
79 installed properly. The actual version information that it
80 prints isn't so important; we simply care whether the command
81 runs and prints anything at all.</para>
83 &interaction.tour.version;
85 <sect2>
86 <title>Built-in help</title>
88 <para id="x_f">Mercurial provides a built-in help system. This is
89 invaluable for those times when you find yourself stuck
90 trying to remember how to run a command. If you are
91 completely stuck, simply run <command role="hg-cmd">hg
92 help</command>; it will print a brief list of commands,
93 along with a description of what each does. If you ask for
94 help on a specific command (as below), it prints more
95 detailed information.</para>
97 &interaction.tour.help;
99 <para id="x_10">For a more impressive level of detail (which you won't
100 usually need) run <command role="hg-cmd">hg help <option
101 role="hg-opt-global">-v</option></command>. The <option
102 role="hg-opt-global">-v</option> option is short for
103 <option role="hg-opt-global">--verbose</option>, and tells
104 Mercurial to print more information than it usually
105 would.</para>
107 </sect2>
108 </sect1>
109 <sect1>
110 <title>Working with a repository</title>
112 <para id="x_11">In Mercurial, everything happens inside a
113 <emphasis>repository</emphasis>. The repository for a project
114 contains all of the files that <quote>belong to</quote> that
115 project, along with a historical record of the project's
116 files.</para>
118 <para id="x_12">There's nothing particularly magical about a repository; it
119 is simply a directory tree in your filesystem that Mercurial
120 treats as special. You can rename or delete a repository any
121 time you like, using either the command line or your file
122 browser.</para>
124 <sect2>
125 <title>Making a local copy of a repository</title>
127 <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little
128 bit special. While you could use a normal file copying
129 command to make a copy of a repository, it's best to use a
130 built-in command that Mercurial provides. This command is
131 called <command role="hg-cmd">hg clone</command>, because it
132 makes an identical copy of an existing repository.</para>
134 &interaction.tour.clone;
136 <para id="x_67c">One advantage of using <command role="hg-cmd">hg
137 clone</command> is that, as we can see above, it lets us clone
138 repositories over the network. Another is that it remembers
139 where we cloned from, which we'll find useful soon when we
140 want to fetch new changes from another repository.</para>
142 <para id="x_14">If our clone succeeded, we should now have a local
143 directory called <filename class="directory">hello</filename>.
144 This directory will contain some files.</para>
146 &interaction.tour.ls;
148 <para id="x_15">These files have the same contents and history in our
149 repository as they do in the repository we cloned.</para>
151 <para id="x_16">Every Mercurial repository is complete,
152 self-contained, and independent. It contains its own private
153 copy of a project's files and history. As we just mentioned,
154 a cloned repository remembers the location of the repository
155 it was cloned from, but Mercurial will not communicate with
156 that repository, or any other, unless you tell it to.</para>
158 <para id="x_17">What this means for now is that we're free to experiment
159 with our repository, safe in the knowledge that it's a private
160 <quote>sandbox</quote> that won't affect anyone else.</para>
162 </sect2>
163 <sect2>
164 <title>What's in a repository?</title>
166 <para id="x_18">When we take a more detailed look inside a repository, we
167 can see that it contains a directory named <filename
168 class="directory">.hg</filename>. This is where Mercurial
169 keeps all of its metadata for the repository.</para>
171 &interaction.tour.ls-a;
173 <para id="x_19">The contents of the <filename
174 class="directory">.hg</filename> directory and its
175 subdirectories are private to Mercurial. Every other file and
176 directory in the repository is yours to do with as you
177 please.</para>
179 <para id="x_1a">To introduce a little terminology, the <filename
180 class="directory">.hg</filename> directory is the
181 <quote>real</quote> repository, and all of the files and
182 directories that coexist with it are said to live in the
183 <emphasis>working directory</emphasis>. An easy way to
184 remember the distinction is that the
185 <emphasis>repository</emphasis> contains the
186 <emphasis>history</emphasis> of your project, while the
187 <emphasis>working directory</emphasis> contains a
188 <emphasis>snapshot</emphasis> of your project at a particular
189 point in history.</para>
191 </sect2>
192 </sect1>
193 <sect1>
194 <title>A tour through history</title>
196 <para id="x_1b">One of the first things we might want to do with a new,
197 unfamiliar repository is understand its history. The <command
198 role="hg-cmd">hg log</command> command gives us a view of
199 the history of changes in the repository.</para>
201 &interaction.tour.log;
203 <para id="x_1c">By default, this command prints a brief paragraph of output
204 for each change to the project that was recorded. In Mercurial
205 terminology, we call each of these recorded events a
206 <emphasis>changeset</emphasis>, because it can contain a record
207 of changes to several files.</para>
209 <para id="x_1d">The fields in a record of output from <command
210 role="hg-cmd">hg log</command> are as follows.</para>
212 <itemizedlist>
213 <listitem><para id="x_1e"><literal>changeset</literal>: This
214 field has the format of a number, followed by a colon,
215 followed by a hexadecimal (or <emphasis>hex</emphasis>)
216 string. These are <emphasis>identifiers</emphasis> for the
217 changeset. The hex string is a unique identifier: the same
218 hex string will always refer to the same changeset in every
219 copy of this repository. The
220 number is shorter and easier to type than the hex string,
221 but it isn't unique: the same number in two different clones
222 of a repository may identify different changesets.</para>
223 </listitem>
224 <listitem><para id="x_1f"><literal>user</literal>: The identity of the
225 person who created the changeset. This is a free-form
226 field, but it most often contains a person's name and email
227 address.</para></listitem>
228 <listitem><para id="x_20"><literal>date</literal>: The date and time on
229 which the changeset was created, and the timezone in which
230 it was created. (The date and time are local to that
231 timezone; they display what time and date it was for the
232 person who created the changeset.)</para></listitem>
233 <listitem><para id="x_21"><literal>summary</literal>: The first line of
234 the text message that the creator of the changeset entered
235 to describe the changeset.</para></listitem>
236 <listitem>
237 <para id="x_67d">Some changesets, such as the first in the list above,
238 have a <literal>tag</literal> field. A tag is another way
239 to identify a changeset, by giving it an easy-to-remember
240 name. (The tag named <literal>tip</literal> is special: it
241 always refers to the newest change in a repository.)</para>
242 </listitem>
243 </itemizedlist>
245 <para id="x_22">The default output printed by <command
246 role="hg-cmd">hg log</command> is purely a summary; it is
247 missing a lot of detail.</para>
249 <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides
250 a 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="figs/tour-history.png"/></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 a handy
290 notation that is <emphasis>only valid in that
291 repository</emphasis>.</para></listitem>
292 <listitem><para id="x_28">The hexadecimal 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>
298 <para id="x_29">This distinction is important. If you send
299 someone an email talking about <quote>revision 33</quote>,
300 there's a high likelihood that their revision 33 will
301 <emphasis>not be the same</emphasis> as yours. The reason for
302 this is that a revision number depends on the order in which
303 changes arrived in a repository, and there is no guarantee
304 that the same changes will happen in the same order in
305 different repositories. Three changes <literal>a,b,c</literal>
306 can easily appear in one repository as
307 <literal>0,1,2</literal>, while in another as
308 <literal>0,2,1</literal>.</para>
310 <para id="x_2a">Mercurial uses revision numbers purely as a convenient
311 shorthand. If you need to discuss a changeset with someone,
312 or make a record of a changeset for some other reason (for
313 example, in a bug report), use the hexadecimal
314 identifier.</para>
316 </sect2>
317 <sect2>
318 <title>Viewing specific revisions</title>
320 <para id="x_2b">To narrow the output of <command role="hg-cmd">hg
321 log</command> down to a single revision, use the <option
322 role="hg-opt-log">-r</option> (or <option
323 role="hg-opt-log">--rev</option>) option. You can use
324 either a revision number or a hexadecimal identifier,
325 and you can provide as many revisions as you want.</para>
327 &interaction.tour.log-r;
329 <para id="x_2c">If you want to see the history of several revisions
330 without having to list each one, you can use <emphasis>range
331 notation</emphasis>; this lets you express the idea <quote>I
332 want all revisions between <literal>abc</literal> and
333 <literal>def</literal>, inclusive</quote>.</para>
335 &interaction.tour.log.range;
337 <para id="x_2d">Mercurial also honours the order in which you specify
338 revisions, so <command role="hg-cmd">hg log -r 2:4</command>
339 prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
340 4:2</command> prints 4, 3, and 2.</para>
342 </sect2>
343 <sect2>
344 <title>More detailed information</title>
346 <para id="x_2e">While the summary information printed by <command
347 role="hg-cmd">hg log</command> is useful if you already know
348 what you're looking for, you may need to see a complete
349 description of the change, or a list of the files changed, if
350 you're trying to decide whether a changeset is the one you're
351 looking for. The <command role="hg-cmd">hg log</command>
352 command's <option role="hg-opt-global">-v</option> (or <option
353 role="hg-opt-global">--verbose</option>) option gives you
354 this extra detail.</para>
356 &interaction.tour.log-v;
358 <para id="x_2f">If you want to see both the description and
359 content of a change, add the <option
360 role="hg-opt-log">-p</option> (or <option
361 role="hg-opt-log">--patch</option>) option. This displays
362 the content of a change as a <emphasis>unified diff</emphasis>
363 (if you've never seen a unified diff before, see <xref
364 linkend="sec:mq:patch"/> for an overview).</para>
366 &interaction.tour.log-vp;
368 <para id="x_67e">The <option role="hg-opt-log">-p</option> option is
369 tremendously useful, so it's well worth remembering.</para>
371 </sect2>
372 </sect1>
374 <sect1>
375 <title>All about command options</title>
377 <para id="x_30">Let's take a brief break from exploring Mercurial commands
378 to discuss a pattern in the way that they work; you may find
379 this useful to keep in mind as we continue our tour.</para>
381 <para id="x_31">Mercurial has a consistent and straightforward approach to
382 dealing with the options that you can pass to commands. It
383 follows the conventions for options that are common to modern
384 Linux and Unix systems.</para>
386 <itemizedlist>
387 <listitem>
388 <para id="x_32">Every option has a long name. For example, as
389 we've already seen, the <command role="hg-cmd">hg
390 log</command> command accepts a <option
391 role="hg-opt-log">--rev</option> option.</para>
392 </listitem>
393 <listitem>
394 <para id="x_33">Most options have short names, too. Instead
395 of <option role="hg-opt-log">--rev</option>, we can use
396 <option role="hg-opt-log">-r</option>. (The reason that
397 some options don't have short names is that the options in
398 question are rarely used.)</para>
399 </listitem>
400 <listitem>
401 <para id="x_34">Long options start with two dashes (e.g.
402 <option role="hg-opt-log">--rev</option>), while short
403 options start with one (e.g. <option
404 role="hg-opt-log">-r</option>).</para>
405 </listitem>
406 <listitem>
407 <para id="x_35">Option naming and usage is consistent across
408 commands. For example, every command that lets you specify
409 a changeset ID or revision number accepts both <option
410 role="hg-opt-log">-r</option> and <option
411 role="hg-opt-log">--rev</option> arguments.</para>
412 </listitem>
413 <listitem>
414 <para id="x_67f">If you are using short options, you can save typing by
415 running them together. For example, the command <command
416 role="hg-cmd">hg log -v -p -r 2</command> can be written
417 as <command role="hg-cmd">hg log -vpr2</command>.</para>
418 </listitem>
419 </itemizedlist>
421 <para id="x_36">In the examples throughout this book, I usually
422 use short options instead of long. This simply reflects my own
423 preference, so don't read anything significant into it.</para>
425 <para id="x_37">Most commands that print output of some kind will print more
426 output when passed a <option role="hg-opt-global">-v</option>
427 (or <option role="hg-opt-global">--verbose</option>) option, and
428 less when passed <option role="hg-opt-global">-q</option> (or
429 <option role="hg-opt-global">--quiet</option>).</para>
431 <note>
432 <title>Option naming consistency</title>
434 <para id="x_680">Almost always, Mercurial commands use consistent option
435 names to refer to the same concepts. For instance, if a
436 command deals with changesets, you'll always identify them
437 with <option role="hg-opt-log">--rev</option> or <option
438 role="hg-opt-log">-r</option>. This consistent use of
439 option names makes it easier to remember what options a
440 particular command takes.</para>
441 </note>
443 </sect1>
444 <sect1>
445 <title>Making and reviewing changes</title>
447 <para id="x_38">Now that we have a grasp of viewing history in Mercurial,
448 let's take a look at making some changes and examining
449 them.</para>
451 <para id="x_39">The first thing we'll do is isolate our experiment in a
452 repository of its own. We use the <command role="hg-cmd">hg
453 clone</command> command, but we don't need to clone a copy of
454 the remote repository. Since we already have a copy of it
455 locally, we can just clone that instead. This is much faster
456 than cloning over the network, and cloning a local repository
457 uses less disk space in most cases, too<footnote>
458 <para id="x_681">The saving of space arises when source and destination
459 repositories are on the same filesystem, in which case
460 Mercurial will use hardlinks to do copy-on-write sharing of
461 its internal metadata. If that explanation meant nothing to
462 you, don't worry: everything happens transparently and
463 automatically, and you don't need to understand it.</para>
464 </footnote>.</para>
466 &interaction.tour.reclone;
468 <para id="x_3a">As an aside, it's often good practice to keep a
469 <quote>pristine</quote> copy of a remote repository around,
470 which you can then make temporary clones of to create sandboxes
471 for each task you want to work on. This lets you work on
472 multiple tasks in parallel, each isolated from the others until
473 it's complete and you're ready to integrate it back. Because
474 local clones are so cheap, there's almost no overhead to cloning
475 and destroying repositories whenever you want.</para>
477 <para id="x_3b">In our <filename class="directory">my-hello</filename>
478 repository, we have a file <filename>hello.c</filename> that
479 contains the classic <quote>hello, world</quote> program.</para>
481 &interaction.tour.cat1;
483 <para id="x_682">Let's edit this file so that it prints a second line of
484 output.</para>
486 &interaction.tour.cat2;
488 <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command>
489 command will tell us what Mercurial knows about the files in the
490 repository.</para>
492 &interaction.tour.status;
494 <para id="x_3d">The <command role="hg-cmd">hg status</command> command
495 prints no output for some files, but a line starting with
496 <quote><literal>M</literal></quote> for
497 <filename>hello.c</filename>. Unless you tell it to, <command
498 role="hg-cmd">hg status</command> will not print any output
499 for files that have not been modified.</para>
501 <para id="x_3e">The <quote><literal>M</literal></quote> indicates that
502 Mercurial has noticed that we modified
503 <filename>hello.c</filename>. We didn't need to
504 <emphasis>inform</emphasis> Mercurial that we were going to
505 modify the file before we started, or that we had modified the
506 file after we were done; it was able to figure this out
507 itself.</para>
509 <para id="x_3f">It's somewhat helpful to know that we've modified
510 <filename>hello.c</filename>, but we might prefer to know
511 exactly <emphasis>what</emphasis> changes we've made to it. To
512 do this, we use the <command role="hg-cmd">hg diff</command>
513 command.</para>
515 &interaction.tour.diff;
517 <tip>
518 <title>Understanding patches</title>
520 <para id="x_683">Remember to take a look at <xref
521 linkend="sec:mq:patch"/> if you don't know how to read
522 output above.</para>
523 </tip>
524 </sect1>
525 <sect1>
526 <title>Recording changes in a new changeset</title>
528 <para id="x_40">We can modify files, build and test our changes, and use
529 <command role="hg-cmd">hg status</command> and <command
530 role="hg-cmd">hg diff</command> to review our changes, until
531 we're satisfied with what we've done and arrive at a natural
532 stopping point where we want to record our work in a new
533 changeset.</para>
535 <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets
536 us create a new changeset; we'll usually refer to this as
537 <quote>making a commit</quote> or
538 <quote>committing</quote>.</para>
540 <sect2>
541 <title>Setting up a username</title>
543 <para id="x_42">When you try to run <command role="hg-cmd">hg
544 commit</command> for the first time, it is not guaranteed to
545 succeed. Mercurial records your name and address with each
546 change that you commit, so that you and others will later be
547 able to tell who made each change. Mercurial tries to
548 automatically figure out a sensible username to commit the
549 change with. It will attempt each of the following methods,
550 in order:</para>
551 <orderedlist>
552 <listitem><para id="x_43">If you specify a <option
553 role="hg-opt-commit">-u</option> option to the <command
554 role="hg-cmd">hg commit</command> command on the command
555 line, followed by a username, this is always given the
556 highest precedence.</para></listitem>
557 <listitem><para id="x_44">If you have set the <envar>HGUSER</envar>
558 environment variable, this is checked
559 next.</para></listitem>
560 <listitem><para id="x_45">If you create a file in your home
561 directory called <filename
562 role="special">.hgrc</filename>, with a <envar
563 role="rc-item-ui">username</envar> entry, that will be
564 used next. To see what the contents of this file should
565 look like, refer to <xref
566 linkend="sec:tour-basic:username"/>
567 below.</para></listitem>
568 <listitem><para id="x_46">If you have set the <envar>EMAIL</envar>
569 environment variable, this will be used
570 next.</para></listitem>
571 <listitem><para id="x_47">Mercurial will query your system to find out
572 your local user name and host name, and construct a
573 username from these components. Since this often results
574 in a username that is not very useful, it will print a
575 warning if it has to do
576 this.</para></listitem>
577 </orderedlist>
578 <para id="x_48">If all of these mechanisms fail, Mercurial will
579 fail, printing an error message. In this case, it will not
580 let you commit until you set up a
581 username.</para>
582 <para id="x_49">You should think of the <envar>HGUSER</envar> environment
583 variable and the <option role="hg-opt-commit">-u</option>
584 option to the <command role="hg-cmd">hg commit</command>
585 command as ways to <emphasis>override</emphasis> Mercurial's
586 default selection of username. For normal use, the simplest
587 and most robust way to set a username for yourself is by
588 creating a <filename role="special">.hgrc</filename> file; see
589 below for details.</para>
590 <sect3 id="sec:tour-basic:username">
591 <title>Creating a Mercurial configuration file</title>
593 <para id="x_4a">To set a user name, use your favorite editor
594 to create a file called <filename
595 role="special">.hgrc</filename> in your home directory.
596 Mercurial will use this file to look up your personalised
597 configuration settings. The initial contents of your
598 <filename role="special">.hgrc</filename> should look like
599 this.</para>
601 <tip>
602 <title><quote>Home directory</quote> on Windows</title>
604 <para id="x_716">When we refer to your home directory, on an English
605 language installation of Windows this will usually be a
606 folder named after your user name in
607 <filename>C:\Documents and Settings</filename>. You can
608 find out the exact name of your home directory by opening
609 a command prompt window and running the following
610 command.</para>
612 <screen><prompt>C:\></prompt> <userinput>echo %UserProfile%</userinput></screen>
613 </tip>
615 <programlisting># This is a Mercurial configuration file.
616 [ui]
617 username = Firstname Lastname <email.address@example.net></programlisting>
619 <para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a
620 <emphasis>section</emphasis> of the config file, so you can
621 read the <quote><literal>username = ...</literal></quote>
622 line as meaning <quote>set the value of the
623 <literal>username</literal> item in the
624 <literal>ui</literal> section</quote>. A section continues
625 until a new section begins, or the end of the file.
626 Mercurial ignores empty lines and treats any text from
627 <quote><literal>#</literal></quote> to the end of a line as
628 a comment.</para>
629 </sect3>
631 <sect3>
632 <title>Choosing a user name</title>
634 <para id="x_4c">You can use any text you like as the value of
635 the <literal>username</literal> config item, since this
636 information is for reading by other people, but will not be
637 interpreted by Mercurial. The convention that most people
638 follow is to use their name and email address, as in the
639 example above.</para>
640 <note>
641 <para id="x_4d">Mercurial's built-in web server obfuscates
642 email addresses, to make it more difficult for the email
643 harvesting tools that spammers use. This reduces the
644 likelihood that you'll start receiving more junk email if
645 you publish a Mercurial repository on the
646 web.</para></note>
647 </sect3>
648 </sect2>
649 <sect2>
650 <title>Writing a commit message</title>
652 <para id="x_4e">When we commit a change, Mercurial drops us into
653 a text editor, to enter a message that will describe the
654 modifications we've made in this changeset. This is called
655 the <emphasis>commit message</emphasis>. It will be a record
656 for readers of what we did and why, and it will be printed by
657 <command role="hg-cmd">hg log</command> after we've finished
658 committing.</para>
660 &interaction.tour.commit;
662 <para id="x_4f">The editor that the <command role="hg-cmd">hg
663 commit</command> command drops us into will contain an empty
664 line or two, followed by a number of lines starting with
665 <quote><literal>HG:</literal></quote>.</para>
667 <programlisting>
668 This is where I type my commit comment.
670 HG: Enter commit message. Lines beginning with 'HG:' are removed.
671 HG: --
672 HG: user: Bryan O'Sullivan <bos@serpentine.com>
673 HG: branch 'default'
674 HG: changed hello.c</programlisting>
676 <para id="x_50">Mercurial ignores the lines that start with
677 <quote><literal>HG:</literal></quote>; it uses them only to
678 tell us which files it's recording changes to. Modifying or
679 deleting these lines has no effect.</para>
680 </sect2>
681 <sect2>
682 <title>Writing a good commit message</title>
684 <para id="x_51">Since <command role="hg-cmd">hg log</command>
685 only prints the first line of a commit message by default,
686 it's best to write a commit message whose first line stands
687 alone. Here's a real example of a commit message that
688 <emphasis>doesn't</emphasis> follow this guideline, and hence
689 has a summary that is not readable.</para>
691 <programlisting>
692 changeset: 73:584af0e231be
693 user: Censored Person <censored.person@example.org>
694 date: Tue Sep 26 21:37:07 2006 -0700
695 summary: include buildmeister/commondefs. Add exports.</programlisting>
697 <para id="x_52">As far as the remainder of the contents of the
698 commit message are concerned, there are no hard-and-fast
699 rules. Mercurial itself doesn't interpret or care about the
700 contents of the commit message, though your project may have
701 policies that dictate a certain kind of formatting.</para>
702 <para id="x_53">My personal preference is for short, but
703 informative, commit messages that tell me something that I
704 can't figure out with a quick glance at the output of <command
705 role="hg-cmd">hg log --patch</command>.</para>
706 <para id="x_55">If we run the <command role="hg-cmd">hg
707 commit</command> command without any arguments, it records
708 all of the changes we've made, as reported by <command
709 role="hg-cmd">hg status</command> and <command
710 role="hg-cmd">hg diff</command>.</para>
712 <note>
713 <title>A surprise for Subversion users</title>
715 <para id="x_717">Like other Mercurial commands, if we don't supply
716 explicit names to commit to the <command role="hg-cmd">hg
717 commit</command>, it will operate across a repository's
718 entire working directory. Be wary of this if you're coming
719 from the Subversion or CVS world, since you might expect it
720 to operate only on the current directory that you happen to
721 be visiting and its subdirectories.</para>
722 </note>
723 </sect2>
725 <sect2>
726 <title>Aborting a commit</title>
728 <para id="x_54">If you decide that you don't want to commit
729 while in the middle of editing a commit message, simply exit
730 from your editor without saving the file that it's editing.
731 This will cause nothing to happen to either the repository or
732 the working directory.</para>
733 </sect2>
735 <sect2>
736 <title>Admiring our new handiwork</title>
738 <para id="x_56">Once we've finished the commit, we can use the
739 <command role="hg-cmd">hg tip</command> command to display the
740 changeset we just created. This command produces output that
741 is identical to <command role="hg-cmd">hg log</command>, but
742 it only displays the newest revision in the repository.</para>
744 &interaction.tour.tip;
746 <para id="x_57">We refer to the newest revision in the
747 repository as the <emphasis>tip revision</emphasis>, or simply
748 the <emphasis>tip</emphasis>.</para>
750 <para id="x_684">By the way, the <command role="hg-cmd">hg tip</command>
751 command accepts many of the same options as <command
752 role="hg-cmd">hg log</command>, so <option
753 role="hg-opt-global">-v</option> above indicates <quote>be
754 verbose</quote>, <option role="hg-opt-tip">-p</option>
755 specifies <quote>print a patch</quote>. The use of <option
756 role="hg-opt-tip">-p</option> to print patches is another
757 example of the consistent naming we mentioned earlier.</para>
758 </sect2>
759 </sect1>
761 <sect1>
762 <title>Sharing changes</title>
764 <para id="x_58">We mentioned earlier that repositories in
765 Mercurial are self-contained. This means that the changeset we
766 just created exists only in our <filename
767 class="directory">my-hello</filename> repository. Let's look
768 at a few ways that we can propagate this change into other
769 repositories.</para>
771 <sect2 id="sec:tour:pull">
772 <title>Pulling changes from another repository</title>
774 <para id="x_59">To get started, let's clone our original
775 <filename class="directory">hello</filename> repository, which
776 does not contain the change we just committed. We'll call our
777 temporary repository <filename
778 class="directory">hello-pull</filename>.</para>
780 &interaction.tour.clone-pull;
782 <para id="x_5a">We'll use the <command role="hg-cmd">hg
783 pull</command> command to bring changes from <filename
784 class="directory">my-hello</filename> into <filename
785 class="directory">hello-pull</filename>. However, blindly
786 pulling unknown changes into a repository is a somewhat scary
787 prospect. Mercurial provides the <command role="hg-cmd">hg
788 incoming</command> command to tell us what changes the
789 <command role="hg-cmd">hg pull</command> command
790 <emphasis>would</emphasis> pull into the repository, without
791 actually pulling the changes in.</para>
793 &interaction.tour.incoming;
795 <para id="x_5c">Bringing changes into a repository is a simple
796 matter of running the <command role="hg-cmd">hg pull</command>
797 command, and optionally telling it which repository to pull from.</para>
799 &interaction.tour.pull;
801 <para id="x_5d">As you can see from the before-and-after output
802 of <command role="hg-cmd">hg tip</command>, we have
803 successfully pulled changes into our repository. However,
804 Mercurial separates pulling changes in from updating the
805 working directory. There remains one step before we will see
806 the changes that we just pulled appear in the working
807 directory.</para>
809 <tip>
810 <title>Pulling specific changes</title>
812 <para id="x_5b">It is possible that due to the delay between
813 running <command role="hg-cmd">hg incoming</command> and
814 <command role="hg-cmd">hg pull</command>, you may not see
815 all changesets that will be brought from the other
816 repository. Suppose you're pulling changes from a repository
817 on the network somewhere. While you are looking at the
818 <command role="hg-cmd">hg incoming</command> output, and
819 before you pull those changes, someone might have committed
820 something in the remote repository. This means that it's
821 possible to pull more changes than you saw when using
822 <command role="hg-cmd">hg incoming</command>.</para>
824 <para id="x_718">If you only want to pull precisely the changes that were
825 listed by <command role="hg-cmd">hg incoming</command>, or
826 you have some other reason to pull a subset of changes,
827 simply identify the change that you want to pull by its
828 changeset ID, e.g. <command>hg pull
829 -r7e95bb</command>.</para>
830 </tip>
831 </sect2>
833 <sect2>
834 <title>Updating the working directory</title>
836 <para id="x_5e">We have so far glossed over the relationship
837 between a repository and its working directory. The <command
838 role="hg-cmd">hg pull</command> command that we ran in
839 <xref linkend="sec:tour:pull"/> brought changes into the
840 repository, but if we check, there's no sign of those changes
841 in the working directory. This is because <command
842 role="hg-cmd">hg pull</command> does not (by default) touch
843 the working directory. Instead, we use the <command
844 role="hg-cmd">hg update</command> command to do this.</para>
846 &interaction.tour.update;
848 <para id="x_5f">It might seem a bit strange that <command
849 role="hg-cmd">hg pull</command> doesn't update the working
850 directory automatically. There's actually a good reason for
851 this: you can use <command role="hg-cmd">hg update</command>
852 to update the working directory to the state it was in at
853 <emphasis>any revision</emphasis> in the history of the
854 repository. If you had the working directory updated to an
855 old revision&emdash;to hunt down the origin of a bug,
856 say&emdash;and ran a <command role="hg-cmd">hg pull</command>
857 which automatically updated the working directory to a new
858 revision, you might not be terribly happy.</para>
860 <para id="x_60">Since pull-then-update is such a common sequence
861 of operations, Mercurial lets you combine the two by passing
862 the <option role="hg-opt-pull">-u</option> option to <command
863 role="hg-cmd">hg pull</command>.</para>
865 <para id="x_61">If you look back at the output of <command
866 role="hg-cmd">hg pull</command> in <xref
867 linkend="sec:tour:pull"/> when we ran it without <option
868 role="hg-opt-pull">-u</option>, you can see that it printed
869 a helpful reminder that we'd have to take an explicit step to
870 update the working directory.</para>
872 <para id="x_62">To find out what revision the working directory
873 is at, use the <command role="hg-cmd">hg parents</command>
874 command.</para>
876 &interaction.tour.parents;
878 <para id="x_63">If you look back at <xref
879 linkend="fig:tour-basic:history"/>, you'll see arrows
880 connecting each changeset. The node that the arrow leads
881 <emphasis>from</emphasis> in each case is a parent, and the
882 node that the arrow leads <emphasis>to</emphasis> is its
883 child. The working directory has a parent in just the same
884 way; this is the changeset that the working directory
885 currently contains.</para>
887 <para id="x_64">To update the working directory to a particular
888 revision, give a revision number or changeset ID to the
889 <command role="hg-cmd">hg update</command> command.</para>
891 &interaction.tour.older;
893 <para id="x_65">If you omit an explicit revision, <command
894 role="hg-cmd">hg update</command> will update to the tip
895 revision, as shown by the second call to <command
896 role="hg-cmd">hg update</command> in the example
897 above.</para>
898 </sect2>
900 <sect2>
901 <title>Pushing changes to another repository</title>
903 <para id="x_66">Mercurial lets us push changes to another
904 repository, from the repository we're currently visiting. As
905 with the example of <command role="hg-cmd">hg pull</command>
906 above, we'll create a temporary repository to push our changes
907 into.</para>
909 &interaction.tour.clone-push;
911 <para id="x_67">The <command role="hg-cmd">hg outgoing</command>
912 command tells us what changes would be pushed into another
913 repository.</para>
915 &interaction.tour.outgoing;
917 <para id="x_68">And the <command role="hg-cmd">hg push</command>
918 command does the actual push.</para>
920 &interaction.tour.push;
922 <para id="x_69">As with <command role="hg-cmd">hg
923 pull</command>, the <command role="hg-cmd">hg push</command>
924 command does not update the working directory in the
925 repository that it's pushing changes into. Unlike <command
926 role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg
927 push</command> does not provide a <literal>-u</literal>
928 option that updates the other repository's working directory.
929 This asymmetry is deliberate: the repository we're pushing to
930 might be on a remote server and shared between several people.
931 If we were to update its working directory while someone was
932 working in it, their work would be disrupted.</para>
934 <para id="x_6a">What happens if we try to pull or push changes
935 and the receiving repository already has those changes?
936 Nothing too exciting.</para>
938 &interaction.tour.push.nothing;
939 </sect2>
941 <sect2>
942 <title>Default locations</title>
944 <para id="x_719">When we clone a repository, Mercurial records the location
945 of the repository we cloned in the
946 <filename>.hg/hgrc</filename> file of the new repository. If
947 we don't supply a location to <command>hg pull</command> from
948 or <command>hg push</command> to, those commands will use this
949 location as a default. The <command>hg incoming</command>
950 and <command>hg outgoing</command> commands do so too.</para>
952 <para id="x_71a">If you open a repository's <filename>.hg/hgrc</filename>
953 file in a text editor, you will see contents like the
954 following.</para>
956 <programlisting>[paths]
957 default = http://www.selenic.com/repo/hg</programlisting>
959 <para id="x_71b">It is possible&emdash;and often useful&emdash;to have the
960 default location for <command>hg push</command> and
961 <command>hg outgoing</command> be different from those for
962 <command>hg pull</command> and <command>hg incoming</command>.
963 We can do this by adding a <literal>default-push</literal>
964 entry to the <literal>[paths]</literal> section of the
965 <filename>.hg/hgrc</filename> file, as follows.</para>
967 <programlisting>[paths]
968 default = http://www.selenic.com/repo/hg
969 default-push = http://hg.example.com/hg</programlisting>
970 </sect2>
972 <sect2>
973 <title>Sharing changes over a network</title>
975 <para id="x_6b">The commands we have covered in the previous few
976 sections are not limited to working with local repositories.
977 Each works in exactly the same fashion over a network
978 connection; simply pass in a URL instead of a local
979 path.</para>
981 &interaction.tour.outgoing.net;
983 <para id="x_6c">In this example, we can see what changes we
984 could push to the remote repository, but the repository is
985 understandably not set up to let anonymous users push to
986 it.</para>
988 &interaction.tour.push.net;
989 </sect2>
990 </sect1>
992 <sect1>
993 <title>Starting a new project</title>
995 <para id="x_71c">It is just as easy to begin a new project as to work on one
996 that already exists. The <command>hg init</command> command
997 creates a new, empty Mercurial repository.</para>
999 &interaction.ch01-new.init;
1001 <para id="x_71d">This simply creates a repository named
1002 <filename>myproject</filename> in the current directory.</para>
1004 &interaction.ch01-new.ls;
1006 <para id="x_71e">We can tell that <filename>myproject</filename> is a
1007 Mercurial repository, because it contains a
1008 <filename>.hg</filename> directory.</para>
1010 &interaction.ch01-new.ls2;
1012 <para id="x_71f">If we want to add some pre-existing files to the repository,
1013 we copy them into place, and tell Mercurial to start tracking
1014 them using the <command>hg add</command> command.</para>
1016 &interaction.ch01-new.add;
1018 <para id="x_720">Once we are satisfied that our project looks right, we
1019 commit our changes.</para>
1021 &interaction.ch01-new.commit;
1023 <para id="x_721">It takes just a few moments to start using Mercurial on a
1024 new project, which is part of its appeal. Revision control is
1025 now so easy to work with, we can use it on the smallest of
1026 projects that we might not have considered with a more
1027 complicated tool.</para>
1028 </sect1>
1029 </chapter>
1031 <!--
1032 local variables:
1033 sgml-parent-document: ("00book.xml" "book" "chapter")
1034 end:
1035 -->