Mercurial > hgbook
comparison en/ch01-tour-basic.xml @ 749:7e7c47481e4f
Oops, this is the real merge for my hg's oddity
author | Dongsheng Song <dongsheng.song@gmail.com> |
---|---|
date | Fri, 20 Mar 2009 16:43:35 +0800 |
parents | en/ch02-tour-basic.xml@d0160b0b1a9e |
children | 1c13ed2130a7 |
comparison
equal
deleted
inserted
replaced
748:d13c7c706a58 | 749:7e7c47481e4f |
---|---|
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> | |
2 | |
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> | |
6 | |
7 <sect1 id="sec.tour.install"> | |
8 <title>Installing Mercurial on your system</title> | |
9 | |
10 <para>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> | |
13 | |
14 <sect2> | |
15 <title>Linux</title> | |
16 | |
17 <para>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> | |
23 | |
24 <para>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> | |
30 | |
31 <itemizedlist> | |
32 <listitem><para>Debian:</para> | |
33 <programlisting>apt-get install mercurial</programlisting></listitem> | |
34 <listitem><para>Fedora Core:</para> | |
35 <programlisting>yum install mercurial</programlisting></listitem> | |
36 <listitem><para>Gentoo:</para> | |
37 <programlisting>emerge mercurial</programlisting></listitem> | |
38 <listitem><para>OpenSUSE:</para> | |
39 <programlisting>yum install mercurial</programlisting></listitem> | |
40 <listitem><para>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> | |
45 | |
46 </sect2> | |
47 <sect2> | |
48 <title>Solaris</title> | |
49 | |
50 <para>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> | |
55 | |
56 </sect2> | |
57 <sect2> | |
58 <title>Mac OS X</title> | |
59 | |
60 <para>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> | |
68 | |
69 <para>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> | |
74 | |
75 </sect2> | |
76 <sect2> | |
77 <title>Windows</title> | |
78 | |
79 <para>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> | |
84 | |
85 <note> | |
86 <para> 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> | |
92 | |
93 </sect2> | |
94 </sect1> | |
95 <sect1> | |
96 <title>Getting started</title> | |
97 | |
98 <para>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> | |
103 | |
104 &interaction.tour.version; | |
105 | |
106 <sect2> | |
107 <title>Built-in help</title> | |
108 | |
109 <para>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> | |
117 | |
118 &interaction.tour.help; | |
119 | |
120 <para>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> | |
127 | |
128 </sect2> | |
129 </sect1> | |
130 <sect1> | |
131 <title>Working with a repository</title> | |
132 | |
133 <para>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> | |
138 | |
139 <para>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> | |
144 | |
145 <sect2> | |
146 <title>Making a local copy of a repository</title> | |
147 | |
148 <para><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> | |
154 | |
155 &interaction.tour.clone; | |
156 | |
157 <para>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> | |
160 | |
161 &interaction.tour.ls; | |
162 | |
163 <para>These files have the same contents and history in our | |
164 repository as they do in the repository we cloned.</para> | |
165 | |
166 <para>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> | |
172 | |
173 <para>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> | |
176 | |
177 </sect2> | |
178 <sect2> | |
179 <title>What's in a repository?</title> | |
180 | |
181 <para>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> | |
185 | |
186 &interaction.tour.ls-a; | |
187 | |
188 <para>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> | |
193 | |
194 <para>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> | |
205 | |
206 </sect2> | |
207 </sect1> | |
208 <sect1> | |
209 <title>A tour through history</title> | |
210 | |
211 <para>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> | |
215 | |
216 &interaction.tour.log; | |
217 | |
218 <para>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> | |
223 | |
224 <para>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><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><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><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><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>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> | |
248 | |
249 <para>Figure <xref endterm="fig.tour-basic.history.caption" | |
250 linkend="fig.tour-basic.history"/> provides a | |
251 graphical representation of the history of the <filename | |
252 class="directory">hello</filename> repository, to make it a | |
253 little easier to see which direction history is | |
254 <quote>flowing</quote> in. We'll be returning to this figure | |
255 several times in this chapter and the chapter that | |
256 follows.</para> | |
257 | |
258 <informalfigure id="fig.tour-basic.history"> | |
259 <mediaobject> | |
260 <imageobject><imagedata fileref="images/tour-history.png"/></imageobject> | |
261 <textobject><phrase>XXX add text</phrase></textobject> | |
262 <caption><para id="fig.tour-basic.history.caption">Graphical history of | |
263 the <filename class="directory">hello</filename> repository</para> | |
264 </caption> | |
265 </mediaobject> | |
266 </informalfigure> | |
267 | |
268 <sect2> | |
269 <title>Changesets, revisions, and talking to other | |
270 people</title> | |
271 | |
272 <para>As English is a notoriously sloppy language, and computer | |
273 science has a hallowed history of terminological confusion | |
274 (why use one term when four will do?), revision control has a | |
275 variety of words and phrases that mean the same thing. If you | |
276 are talking about Mercurial history with other people, you | |
277 will find that the word <quote>changeset</quote> is often | |
278 compressed to <quote>change</quote> or (when written) | |
279 <quote>cset</quote>, and sometimes a changeset is referred to | |
280 as a <quote>revision</quote> or a <quote>rev</quote>.</para> | |
281 | |
282 <para>While it doesn't matter what <emphasis>word</emphasis> you | |
283 use to refer to the concept of <quote>a changeset</quote>, the | |
284 <emphasis>identifier</emphasis> that you use to refer to | |
285 <quote>a <emphasis>specific</emphasis> changeset</quote> is of | |
286 great importance. Recall that the <literal>changeset</literal> | |
287 field in the output from <command role="hg-cmd">hg | |
288 log</command> identifies a changeset using both a number and | |
289 a hexadecimal string.</para> | |
290 <itemizedlist> | |
291 <listitem><para>The revision number is <emphasis>only valid in | |
292 that repository</emphasis>,</para></listitem> | |
293 <listitem><para>while the hex string is the | |
294 <emphasis>permanent, unchanging identifier</emphasis> that | |
295 will always identify that exact changeset in | |
296 <emphasis>every</emphasis> copy of the | |
297 repository.</para></listitem></itemizedlist> | |
298 <para>This distinction is important. If you send someone an | |
299 email talking about <quote>revision 33</quote>, there's a high | |
300 likelihood that their revision 33 will <emphasis>not be the | |
301 same</emphasis> as yours. The reason for this is that a | |
302 revision number depends on the order in which changes arrived | |
303 in a repository, and there is no guarantee that the same | |
304 changes will happen in the same order in different | |
305 repositories. Three changes $a,b,c$ can easily appear in one | |
306 repository as $0,1,2$, while in another as $1,0,2$.</para> | |
307 | |
308 <para>Mercurial uses revision numbers purely as a convenient | |
309 shorthand. If you need to discuss a changeset with someone, | |
310 or make a record of a changeset for some other reason (for | |
311 example, in a bug report), use the hexadecimal | |
312 identifier.</para> | |
313 | |
314 </sect2> | |
315 <sect2> | |
316 <title>Viewing specific revisions</title> | |
317 | |
318 <para>To narrow the output of <command role="hg-cmd">hg | |
319 log</command> down to a single revision, use the <option | |
320 role="hg-opt-log">-r</option> (or <option | |
321 role="hg-opt-log">--rev</option>) option. You can use | |
322 either a revision number or a long-form changeset identifier, | |
323 and you can provide as many revisions as you want.</para> | |
324 | |
325 &interaction.tour.log-r; | |
326 | |
327 <para>If you want to see the history of several revisions | |
328 without having to list each one, you can use <emphasis>range | |
329 notation</emphasis>; this lets you express the idea <quote>I | |
330 want all revisions between <literal>abc</literal> and | |
331 <literal>def</literal>, inclusive</quote>.</para> | |
332 | |
333 &interaction.tour.log.range; | |
334 | |
335 <para>Mercurial also honours the order in which you specify | |
336 revisions, so <command role="hg-cmd">hg log -r 2:4</command> | |
337 prints 2, 3, and 4. while <command role="hg-cmd">hg log -r | |
338 4:2</command> prints 4, 3, and 2.</para> | |
339 | |
340 </sect2> | |
341 <sect2> | |
342 <title>More detailed information</title> | |
343 | |
344 <para>While the summary information printed by <command | |
345 role="hg-cmd">hg log</command> is useful if you already know | |
346 what you're looking for, you may need to see a complete | |
347 description of the change, or a list of the files changed, if | |
348 you're trying to decide whether a changeset is the one you're | |
349 looking for. The <command role="hg-cmd">hg log</command> | |
350 command's <option role="hg-opt-global">-v</option> (or <option | |
351 role="hg-opt-global">--verbose</option>) option gives you | |
352 this extra detail.</para> | |
353 | |
354 &interaction.tour.log-v; | |
355 | |
356 <para>If you want to see both the description and content of a | |
357 change, add the <option role="hg-opt-log">-p</option> (or | |
358 <option role="hg-opt-log">--patch</option>) option. This | |
359 displays the content of a change as a <emphasis>unified | |
360 diff</emphasis> (if you've never seen a unified diff before, | |
361 see section <xref linkend="sec.mq.patch"/> for an | |
362 overview).</para> | |
363 | |
364 &interaction.tour.log-vp; | |
365 | |
366 </sect2> | |
367 </sect1> | |
368 <sect1> | |
369 <title>All about command options</title> | |
370 | |
371 <para>Let's take a brief break from exploring Mercurial commands | |
372 to discuss a pattern in the way that they work; you may find | |
373 this useful to keep in mind as we continue our tour.</para> | |
374 | |
375 <para>Mercurial has a consistent and straightforward approach to | |
376 dealing with the options that you can pass to commands. It | |
377 follows the conventions for options that are common to modern | |
378 Linux and Unix systems.</para> | |
379 <itemizedlist> | |
380 <listitem><para>Every option has a long name. For example, as | |
381 we've already seen, the <command role="hg-cmd">hg | |
382 log</command> command accepts a <option | |
383 role="hg-opt-log">--rev</option> option.</para></listitem> | |
384 <listitem><para>Most options have short names, too. Instead of | |
385 <option role="hg-opt-log">--rev</option>, we can use <option | |
386 role="hg-opt-log">-r</option>. (The reason that some | |
387 options don't have short names is that the options in | |
388 question are rarely used.)</para></listitem> | |
389 <listitem><para>Long options start with two dashes (e.g. <option | |
390 role="hg-opt-log">--rev</option>), while short options | |
391 start with one (e.g. <option | |
392 role="hg-opt-log">-r</option>).</para></listitem> | |
393 <listitem><para>Option naming and usage is consistent across | |
394 commands. For example, every command that lets you specify | |
395 a changeset ID or revision number accepts both <option | |
396 role="hg-opt-log">-r</option> and <option | |
397 role="hg-opt-log">--rev</option> | |
398 arguments.</para></listitem></itemizedlist> | |
399 <para>In the examples throughout this book, I use short options | |
400 instead of long. This just reflects my own preference, so don't | |
401 read anything significant into it.</para> | |
402 | |
403 <para>Most commands that print output of some kind will print more | |
404 output when passed a <option role="hg-opt-global">-v</option> | |
405 (or <option role="hg-opt-global">--verbose</option>) option, and | |
406 less when passed <option role="hg-opt-global">-q</option> (or | |
407 <option role="hg-opt-global">--quiet</option>).</para> | |
408 | |
409 </sect1> | |
410 <sect1> | |
411 <title>Making and reviewing changes</title> | |
412 | |
413 <para>Now that we have a grasp of viewing history in Mercurial, | |
414 let's take a look at making some changes and examining | |
415 them.</para> | |
416 | |
417 <para>The first thing we'll do is isolate our experiment in a | |
418 repository of its own. We use the <command role="hg-cmd">hg | |
419 clone</command> command, but we don't need to clone a copy of | |
420 the remote repository. Since we already have a copy of it | |
421 locally, we can just clone that instead. This is much faster | |
422 than cloning over the network, and cloning a local repository | |
423 uses less disk space in most cases, too.</para> | |
424 | |
425 &interaction.tour.reclone; | |
426 | |
427 <para>As an aside, it's often good practice to keep a | |
428 <quote>pristine</quote> copy of a remote repository around, | |
429 which you can then make temporary clones of to create sandboxes | |
430 for each task you want to work on. This lets you work on | |
431 multiple tasks in parallel, each isolated from the others until | |
432 it's complete and you're ready to integrate it back. Because | |
433 local clones are so cheap, there's almost no overhead to cloning | |
434 and destroying repositories whenever you want.</para> | |
435 | |
436 <para>In our <filename class="directory">my-hello</filename> | |
437 repository, we have a file <filename>hello.c</filename> that | |
438 contains the classic <quote>hello, world</quote> program. Let's | |
439 use the ancient and venerable <command>sed</command> command to | |
440 edit this file so that it prints a second line of output. (I'm | |
441 only using <command>sed</command> to do this because it's easy | |
442 to write a scripted example this way. Since you're not under | |
443 the same constraint, you probably won't want to use | |
444 <command>sed</command>; simply use your preferred text editor to | |
445 do the same thing.)</para> | |
446 | |
447 &interaction.tour.sed; | |
448 | |
449 <para>Mercurial's <command role="hg-cmd">hg status</command> | |
450 command will tell us what Mercurial knows about the files in the | |
451 repository.</para> | |
452 | |
453 &interaction.tour.status; | |
454 | |
455 <para>The <command role="hg-cmd">hg status</command> command | |
456 prints no output for some files, but a line starting with | |
457 <quote><literal>M</literal></quote> for | |
458 <filename>hello.c</filename>. Unless you tell it to, <command | |
459 role="hg-cmd">hg status</command> will not print any output | |
460 for files that have not been modified.</para> | |
461 | |
462 <para>The <quote><literal>M</literal></quote> indicates that | |
463 Mercurial has noticed that we modified | |
464 <filename>hello.c</filename>. We didn't need to | |
465 <emphasis>inform</emphasis> Mercurial that we were going to | |
466 modify the file before we started, or that we had modified the | |
467 file after we were done; it was able to figure this out | |
468 itself.</para> | |
469 | |
470 <para>It's a little bit helpful to know that we've modified | |
471 <filename>hello.c</filename>, but we might prefer to know | |
472 exactly <emphasis>what</emphasis> changes we've made to it. To | |
473 do this, we use the <command role="hg-cmd">hg diff</command> | |
474 command.</para> | |
475 | |
476 &interaction.tour.diff; | |
477 | |
478 </sect1> | |
479 <sect1> | |
480 <title>Recording changes in a new changeset</title> | |
481 | |
482 <para>We can modify files, build and test our changes, and use | |
483 <command role="hg-cmd">hg status</command> and <command | |
484 role="hg-cmd">hg diff</command> to review our changes, until | |
485 we're satisfied with what we've done and arrive at a natural | |
486 stopping point where we want to record our work in a new | |
487 changeset.</para> | |
488 | |
489 <para>The <command role="hg-cmd">hg commit</command> command lets | |
490 us create a new changeset; we'll usually refer to this as | |
491 <quote>making a commit</quote> or | |
492 <quote>committing</quote>.</para> | |
493 | |
494 <sect2> | |
495 <title>Setting up a username</title> | |
496 | |
497 <para>When you try to run <command role="hg-cmd">hg | |
498 commit</command> for the first time, it is not guaranteed to | |
499 succeed. Mercurial records your name and address with each | |
500 change that you commit, so that you and others will later be | |
501 able to tell who made each change. Mercurial tries to | |
502 automatically figure out a sensible username to commit the | |
503 change with. It will attempt each of the following methods, | |
504 in order:</para> | |
505 <orderedlist> | |
506 <listitem><para>If you specify a <option | |
507 role="hg-opt-commit">-u</option> option to the <command | |
508 role="hg-cmd">hg commit</command> command on the command | |
509 line, followed by a username, this is always given the | |
510 highest precedence.</para></listitem> | |
511 <listitem><para>If you have set the <envar>HGUSER</envar> | |
512 environment variable, this is checked | |
513 next.</para></listitem> | |
514 <listitem><para>If you create a file in your home directory | |
515 called <filename role="special">.hgrc</filename>, with a | |
516 <envar role="rc-item-ui">username</envar> entry, that will | |
517 be used next. To see what the contents of this file | |
518 should look like, refer to section <xref | |
519 linkend="sec.tour-basic.username"/> | |
520 below.</para></listitem> | |
521 <listitem><para>If you have set the <envar>EMAIL</envar> | |
522 environment variable, this will be used | |
523 next.</para></listitem> | |
524 <listitem><para>Mercurial will query your system to find out | |
525 your local user name and host name, and construct a | |
526 username from these components. Since this often results | |
527 in a username that is not very useful, it will print a | |
528 warning if it has to do | |
529 this.</para></listitem> | |
530 </orderedlist> | |
531 <para>If all of these mechanisms fail, Mercurial will | |
532 fail, printing an error message. In this case, it will not | |
533 let you commit until you set up a | |
534 username.</para> | |
535 <para>You should think of the <envar>HGUSER</envar> environment | |
536 variable and the <option role="hg-opt-commit">-u</option> | |
537 option to the <command role="hg-cmd">hg commit</command> | |
538 command as ways to <emphasis>override</emphasis> Mercurial's | |
539 default selection of username. For normal use, the simplest | |
540 and most robust way to set a username for yourself is by | |
541 creating a <filename role="special">.hgrc</filename> file; see | |
542 below for details.</para> | |
543 <sect3 id="sec.tour-basic.username"> | |
544 <title>Creating a Mercurial configuration file</title> | |
545 | |
546 <para>To set a user name, use your favourite editor | |
547 to create a file called <filename | |
548 role="special">.hgrc</filename> in your home directory. | |
549 Mercurial will use this file to look up your personalised | |
550 configuration settings. The initial contents of your | |
551 <filename role="special">.hgrc</filename> should look like | |
552 this.</para> | |
553 <programlisting># This is a Mercurial configuration file. | |
554 [ui] | |
555 username = Firstname Lastname | |
556 <email.address@domain.net></programlisting> | |
557 | |
558 <para>The <quote><literal>[ui]</literal></quote> line begins a | |
559 <emphasis>section</emphasis> of the config file, so you can | |
560 read the <quote><literal>username = ...</literal></quote> | |
561 line as meaning <quote>set the value of the | |
562 <literal>username</literal> item in the | |
563 <literal>ui</literal> section</quote>. A section continues | |
564 until a new section begins, or the end of the file. | |
565 Mercurial ignores empty lines and treats any text from | |
566 <quote><literal>#</literal></quote> to the end of a line as | |
567 a comment.</para> | |
568 </sect3> | |
569 | |
570 <sect3> | |
571 <title>Choosing a user name</title> | |
572 | |
573 <para>You can use any text you like as the value of | |
574 the <literal>username</literal> config item, since this | |
575 information is for reading by other people, but for | |
576 interpreting by Mercurial. The convention that most | |
577 people follow is to use their name and email address, as | |
578 in the example above.</para> | |
579 <note> | |
580 <para>Mercurial's built-in web server obfuscates | |
581 email addresses, to make it more difficult for the email | |
582 harvesting tools that spammers use. This reduces the | |
583 likelihood that you'll start receiving more junk email | |
584 if you publish a Mercurial repository on the | |
585 web.</para></note> | |
586 | |
587 </sect3> | |
588 </sect2> | |
589 <sect2> | |
590 <title>Writing a commit message</title> | |
591 | |
592 <para>When we commit a change, Mercurial drops us into | |
593 a text editor, to enter a message that will describe the | |
594 modifications we've made in this changeset. This is called | |
595 the <emphasis>commit message</emphasis>. It will be a | |
596 record for readers of what we did and why, and it will be | |
597 printed by <command role="hg-cmd">hg log</command> after | |
598 we've finished committing.</para> | |
599 | |
600 &interaction.tour.commit; | |
601 | |
602 <para>The editor that the <command role="hg-cmd">hg | |
603 commit</command> command drops us into will contain an | |
604 empty line, followed by a number of lines starting with | |
605 <quote><literal>HG:</literal></quote>.</para> | |
606 | |
607 <programlisting>XXX fix this XXX</programlisting> | |
608 | |
609 <para>Mercurial ignores the lines that start with | |
610 <quote><literal>HG:</literal></quote>; it uses them only to | |
611 tell us which files it's recording changes to. Modifying or | |
612 deleting these lines has no effect.</para> | |
613 </sect2> | |
614 <sect2> | |
615 <title>Writing a good commit message</title> | |
616 | |
617 <para>Since <command role="hg-cmd">hg log</command> | |
618 only prints the first line of a commit message by default, | |
619 it's best to write a commit message whose first line stands | |
620 alone. Here's a real example of a commit message that | |
621 <emphasis>doesn't</emphasis> follow this guideline, and | |
622 hence has a summary that is not | |
623 readable.</para> | |
624 | |
625 <programlisting> | |
626 changeset: 73:584af0e231be | |
627 user: Censored Person <censored.person@example.org> | |
628 date: Tue Sep 26 21:37:07 2006 -0700 | |
629 summary: include buildmeister/commondefs. Add exports.</programlisting> | |
630 | |
631 <para>As far as the remainder of the contents of the | |
632 commit message are concerned, there are no hard-and-fast | |
633 rules. Mercurial itself doesn't interpret or care about the | |
634 contents of the commit message, though your project may have | |
635 policies that dictate a certain kind of | |
636 formatting.</para> | |
637 <para>My personal preference is for short, but | |
638 informative, commit messages that tell me something that I | |
639 can't figure out with a quick glance at the output of | |
640 <command role="hg-cmd">hg log | |
641 --patch</command>.</para> | |
642 </sect2> | |
643 <sect2> | |
644 <title>Aborting a commit</title> | |
645 | |
646 <para>If you decide that you don't want to commit | |
647 while in the middle of editing a commit message, simply exit | |
648 from your editor without saving the file that it's editing. | |
649 This will cause nothing to happen to either the repository | |
650 or the working directory.</para> | |
651 <para>If we run the <command role="hg-cmd">hg | |
652 commit</command> command without any arguments, it records | |
653 all of the changes we've made, as reported by <command | |
654 role="hg-cmd">hg status</command> and <command | |
655 role="hg-cmd">hg diff</command>.</para> | |
656 </sect2> | |
657 <sect2> | |
658 <title>Admiring our new handiwork</title> | |
659 | |
660 <para>Once we've finished the commit, we can use the | |
661 <command role="hg-cmd">hg tip</command> command to display | |
662 the changeset we just created. This command produces output | |
663 that is identical to <command role="hg-cmd">hg | |
664 log</command>, but it only displays the newest revision in | |
665 the repository.</para> | |
666 | |
667 &interaction.tour.tip; | |
668 | |
669 <para>We refer to | |
670 the newest revision in the repository as the tip revision, | |
671 or simply the tip.</para> | |
672 </sect2> | |
673 </sect1> | |
674 | |
675 <sect1> | |
676 <title>Sharing changes</title> | |
677 | |
678 <para>We mentioned earlier that repositories in | |
679 Mercurial are self-contained. This means that the changeset | |
680 we just created exists only in our <filename | |
681 class="directory">my-hello</filename> repository. Let's | |
682 look at a few ways that we can propagate this change into | |
683 other repositories.</para> | |
684 | |
685 <sect2 id="sec.tour.pull"> | |
686 <title>Pulling changes from another repository</title> | |
687 <para>To get started, let's clone our original | |
688 <filename class="directory">hello</filename> repository, | |
689 which does not contain the change we just committed. We'll | |
690 call our temporary repository <filename | |
691 class="directory">hello-pull</filename>.</para> | |
692 | |
693 &interaction.tour.clone-pull; | |
694 | |
695 <para>We'll use the <command role="hg-cmd">hg | |
696 pull</command> command to bring changes from <filename | |
697 class="directory">my-hello</filename> into <filename | |
698 class="directory">hello-pull</filename>. However, blindly | |
699 pulling unknown changes into a repository is a somewhat | |
700 scary prospect. Mercurial provides the <command | |
701 role="hg-cmd">hg incoming</command> command to tell us | |
702 what changes the <command role="hg-cmd">hg pull</command> | |
703 command <emphasis>would</emphasis> pull into the repository, | |
704 without actually pulling the changes in.</para> | |
705 | |
706 &interaction.tour.incoming; | |
707 | |
708 <para>(Of course, someone could | |
709 cause more changesets to appear in the repository that we | |
710 ran <command role="hg-cmd">hg incoming</command> in, before | |
711 we get a chance to <command role="hg-cmd">hg pull</command> | |
712 the changes, so that we could end up pulling changes that we | |
713 didn't expect.)</para> | |
714 | |
715 <para>Bringing changes into a repository is a simple | |
716 matter of running the <command role="hg-cmd">hg | |
717 pull</command> command, and telling it which repository to | |
718 pull from.</para> | |
719 | |
720 &interaction.tour.pull; | |
721 | |
722 <para>As you can see | |
723 from the before-and-after output of <command | |
724 role="hg-cmd">hg tip</command>, we have successfully | |
725 pulled changes into our repository. There remains one step | |
726 before we can see these changes in the working | |
727 directory.</para> | |
728 </sect2> | |
729 <sect2> | |
730 <title>Updating the working directory</title> | |
731 | |
732 <para>We have so far glossed over the relationship between a | |
733 repository and its working directory. The <command | |
734 role="hg-cmd">hg pull</command> command that we ran in | |
735 section <xref linkend="sec.tour.pull"/> brought changes | |
736 into the repository, but if we check, there's no sign of those | |
737 changes in the working directory. This is because <command | |
738 role="hg-cmd">hg pull</command> does not (by default) touch | |
739 the working directory. Instead, we use the <command | |
740 role="hg-cmd">hg update</command> command to do this.</para> | |
741 | |
742 &interaction.tour.update; | |
743 | |
744 <para>It might seem a bit strange that <command role="hg-cmd">hg | |
745 pull</command> doesn't update the working directory | |
746 automatically. There's actually a good reason for this: you | |
747 can use <command role="hg-cmd">hg update</command> to update | |
748 the working directory to the state it was in at <emphasis>any | |
749 revision</emphasis> in the history of the repository. If | |
750 you had the working directory updated to an old revision---to | |
751 hunt down the origin of a bug, say---and ran a <command | |
752 role="hg-cmd">hg pull</command> which automatically updated | |
753 the working directory to a new revision, you might not be | |
754 terribly happy.</para> | |
755 <para>However, since pull-then-update is such a common thing to | |
756 do, Mercurial lets you combine the two by passing the <option | |
757 role="hg-opt-pull">-u</option> option to <command | |
758 role="hg-cmd">hg pull</command>.</para> | |
759 | |
760 <para>If you look back at the output of <command | |
761 role="hg-cmd">hg pull</command> in section <xref | |
762 linkend="sec.tour.pull"/> when we ran it without <option | |
763 role="hg-opt-pull">-u</option>, you can see that it printed | |
764 a helpful reminder that we'd have to take an explicit step to | |
765 update the working directory:</para> | |
766 | |
767 <!-- &interaction.xxx.fixme; --> | |
768 | |
769 <para>To find out what revision the working directory is at, use | |
770 the <command role="hg-cmd">hg parents</command> | |
771 command.</para> | |
772 | |
773 &interaction.tour.parents; | |
774 | |
775 <para>If you look back at figure <xref | |
776 endterm="fig.tour-basic.history.caption" | |
777 linkend="fig.tour-basic.history"/>, | |
778 you'll see arrows connecting each changeset. The node that | |
779 the arrow leads <emphasis>from</emphasis> in each case is a | |
780 parent, and the node that the arrow leads | |
781 <emphasis>to</emphasis> is its child. The working directory | |
782 has a parent in just the same way; this is the changeset that | |
783 the working directory currently contains.</para> | |
784 | |
785 <para>To update the working directory to a particular revision, | |
786 | |
787 give a revision number or changeset ID to the <command | |
788 role="hg-cmd">hg update</command> command.</para> | |
789 | |
790 &interaction.tour.older; | |
791 | |
792 <para>If you omit an explicit revision, <command | |
793 role="hg-cmd">hg update</command> will update to the tip | |
794 revision, as shown by the second call to <command | |
795 role="hg-cmd">hg update</command> in the example | |
796 above.</para> | |
797 </sect2> | |
798 | |
799 <sect2> | |
800 <title>Pushing changes to another repository</title> | |
801 | |
802 <para>Mercurial lets us push changes to another | |
803 repository, from the repository we're currently visiting. | |
804 As with the example of <command role="hg-cmd">hg | |
805 pull</command> above, we'll create a temporary repository | |
806 to push our changes into.</para> | |
807 | |
808 &interaction.tour.clone-push; | |
809 | |
810 <para>The <command role="hg-cmd">hg outgoing</command> command | |
811 tells us what changes would be pushed into another | |
812 repository.</para> | |
813 | |
814 &interaction.tour.outgoing; | |
815 | |
816 <para>And the | |
817 <command role="hg-cmd">hg push</command> command does the | |
818 actual push.</para> | |
819 | |
820 &interaction.tour.push; | |
821 | |
822 <para>As with | |
823 <command role="hg-cmd">hg pull</command>, the <command | |
824 role="hg-cmd">hg push</command> command does not update | |
825 the working directory in the repository that it's pushing | |
826 changes into. (Unlike <command role="hg-cmd">hg | |
827 pull</command>, <command role="hg-cmd">hg push</command> | |
828 does not provide a <literal>-u</literal> option that updates | |
829 the other repository's working directory.)</para> | |
830 | |
831 <para>What happens if we try to pull or push changes | |
832 and the receiving repository already has those changes? | |
833 Nothing too exciting.</para> | |
834 | |
835 &interaction.tour.push.nothing; | |
836 </sect2> | |
837 <sect2> | |
838 <title>Sharing changes over a network</title> | |
839 | |
840 <para>The commands we have covered in the previous few | |
841 sections are not limited to working with local repositories. | |
842 Each works in exactly the same fashion over a network | |
843 connection; simply pass in a URL instead of a local | |
844 path.</para> | |
845 | |
846 &interaction.tour.outgoing.net; | |
847 | |
848 <para>In this example, we | |
849 can see what changes we could push to the remote repository, | |
850 but the repository is understandably not set up to let | |
851 anonymous users push to it.</para> | |
852 | |
853 &interaction.tour.push.net; | |
854 </sect2> | |
855 </sect1> | |
856 </chapter> | |
857 | |
858 <!-- | |
859 local variables: | |
860 sgml-parent-document: ("00book.xml" "book" "chapter") | |
861 end: | |
862 --> |