Mercurial > hgbook
comparison en/ch01-tour-basic.xml @ 766:3b33dd6aba87
Merge with http://hg.serpentine.com/mercurial/book
author | Dongsheng Song <songdongsheng@live.cn> |
---|---|
date | Thu, 02 Apr 2009 09:24:36 +0800 |
parents | 1c13ed2130a7 c44d5854620b |
children | 3b640272a966 |
comparison
equal
deleted
inserted
replaced
765:d8c85d831fb4 | 766:3b33dd6aba87 |
---|---|
8 <title>Installing Mercurial on your system</title> | 8 <title>Installing Mercurial on your system</title> |
9 | 9 |
10 <para id="x_1">Prebuilt binary packages of Mercurial are available for | 10 <para id="x_1">Prebuilt binary packages of Mercurial are available for |
11 every popular operating system. These make it easy to start | 11 every popular operating system. These make it easy to start |
12 using Mercurial on your computer immediately.</para> | 12 using Mercurial on your computer immediately.</para> |
13 | |
14 <sect2> | |
15 <title>Windows</title> | |
16 | |
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> | |
23 | |
24 </sect2> | |
25 | |
26 <sect2> | |
27 <title>Mac OS X</title> | |
28 | |
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> | |
13 | 33 |
14 <sect2> | 34 <sect2> |
15 <title>Linux</title> | 35 <title>Linux</title> |
16 | 36 |
17 <para id="x_2">Because each Linux distribution has its own packaging | 37 <para id="x_2">Because each Linux distribution has its own packaging |
27 package managers that will let you install Mercurial with a | 47 package managers that will let you install Mercurial with a |
28 single click; the package name to look for is | 48 single click; the package name to look for is |
29 <literal>mercurial</literal>.</para> | 49 <literal>mercurial</literal>.</para> |
30 | 50 |
31 <itemizedlist> | 51 <itemizedlist> |
32 <listitem><para id="x_4">Debian:</para> | 52 <listitem><para id="x_4">Ubuntu and Debian:</para> |
33 <programlisting>apt-get install mercurial</programlisting></listitem> | 53 <programlisting>apt-get install mercurial</programlisting></listitem> |
34 <listitem><para id="x_5">Fedora Core:</para> | 54 <listitem><para id="x_5">Fedora and OpenSUSE:</para> |
35 <programlisting>yum install mercurial</programlisting></listitem> | 55 <programlisting>yum install mercurial</programlisting></listitem> |
36 <listitem><para id="x_6">Gentoo:</para> | 56 <listitem><para id="x_6">Gentoo:</para> |
37 <programlisting>emerge mercurial</programlisting></listitem> | 57 <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> | 58 </itemizedlist> |
45 | 59 |
46 </sect2> | 60 </sect2> |
47 <sect2> | 61 <sect2> |
48 <title>Solaris</title> | 62 <title>Solaris</title> |
49 | 63 |
50 <para id="x_9">SunFreeWare, at <ulink | 64 <para id="x_9">SunFreeWare, at <ulink |
51 url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, | 65 url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, |
52 is a good source for a large number of pre-built Solaris | 66 provides prebuilt packages of Mercurial.</para> |
53 packages for 32 and 64 bit Intel and Sparc architectures, | 67 |
54 including current versions of Mercurial.</para> | 68 </sect2> |
55 | 69 |
56 </sect2> | |
57 <sect2> | |
58 <title>Mac OS X</title> | |
59 | |
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> | |
68 | |
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> | |
74 | |
75 </sect2> | |
76 <sect2> | |
77 <title>Windows</title> | |
78 | |
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> | |
84 | |
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> | |
92 | |
93 </sect2> | |
94 </sect1> | 70 </sect1> |
71 | |
95 <sect1> | 72 <sect1> |
96 <title>Getting started</title> | 73 <title>Getting started</title> |
97 | 74 |
98 <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg | 75 <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 | 76 version</command> command to find out whether Mercurial is |
148 <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little | 125 <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little |
149 bit special. While you could use a normal file copying | 126 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 | 127 command to make a copy of a repository, it's best to use a |
151 built-in command that Mercurial provides. This command is | 128 built-in command that Mercurial provides. This command is |
152 called <command role="hg-cmd">hg clone</command>, because it | 129 called <command role="hg-cmd">hg clone</command>, because it |
153 creates an identical copy of an existing repository.</para> | 130 makes an identical copy of an existing repository.</para> |
154 | 131 |
155 &interaction.tour.clone; | 132 &interaction.tour.clone; |
133 | |
134 <para>One advantage of using <command role="hg-cmd">hg | |
135 clone</command> is that, as we can see above, it lets us clone | |
136 repositories over the network. Another is that it remembers | |
137 where we cloned from, which we'll find useful soon when we | |
138 want to fetch new changes from another repository.</para> | |
156 | 139 |
157 <para id="x_14">If our clone succeeded, we should now have a local | 140 <para id="x_14">If our clone succeeded, we should now have a local |
158 directory called <filename class="directory">hello</filename>. | 141 directory called <filename class="directory">hello</filename>. |
159 This directory will contain some files.</para> | 142 This directory will contain some files.</para> |
160 | 143 |
161 &interaction.tour.ls; | 144 &interaction.tour.ls; |
162 | 145 |
163 <para id="x_15">These files have the same contents and history in our | 146 <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> | 147 repository as they do in the repository we cloned.</para> |
165 | 148 |
166 <para id="x_16">Every Mercurial repository is complete, self-contained, | 149 <para id="x_16">Every Mercurial repository is complete, |
167 and independent. It contains its own private copy of a | 150 self-contained, and independent. It contains its own private |
168 project's files and history. A cloned repository remembers | 151 copy of a project's files and history. As we just mentioned, |
169 the location of the repository it was cloned from, but it does | 152 a cloned repository remembers the location of the repository |
170 not communicate with that repository, or any other, unless you | 153 it was cloned from, but Mercurial will not communicate with |
171 tell it to.</para> | 154 that repository, or any other, unless you tell it to.</para> |
172 | 155 |
173 <para id="x_17">What this means for now is that we're free to experiment | 156 <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 | 157 with our repository, safe in the knowledge that it's a private |
175 <quote>sandbox</quote> that won't affect anyone else.</para> | 158 <quote>sandbox</quote> that won't affect anyone else.</para> |
176 | 159 |
209 <title>A tour through history</title> | 192 <title>A tour through history</title> |
210 | 193 |
211 <para id="x_1b">One of the first things we might want to do with a new, | 194 <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 | 195 unfamiliar repository is understand its history. The <command |
213 role="hg-cmd">hg log</command> command gives us a view of | 196 role="hg-cmd">hg log</command> command gives us a view of |
214 history.</para> | 197 the history of changes in the repository.</para> |
215 | 198 |
216 &interaction.tour.log; | 199 &interaction.tour.log; |
217 | 200 |
218 <para id="x_1c">By default, this command prints a brief paragraph of output | 201 <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 | 202 for each change to the project that was recorded. In Mercurial |
221 <emphasis>changeset</emphasis>, because it can contain a record | 204 <emphasis>changeset</emphasis>, because it can contain a record |
222 of changes to several files.</para> | 205 of changes to several files.</para> |
223 | 206 |
224 <para id="x_1d">The fields in a record of output from <command | 207 <para id="x_1d">The fields in a record of output from <command |
225 role="hg-cmd">hg log</command> are as follows.</para> | 208 role="hg-cmd">hg log</command> are as follows.</para> |
209 | |
226 <itemizedlist> | 210 <itemizedlist> |
227 <listitem><para id="x_1e"><literal>changeset</literal>: This field has the | 211 <listitem><para id="x_1e"><literal>changeset</literal>: This |
228 format of a number, followed by a colon, followed by a | 212 field has the format of a number, followed by a colon, |
229 hexadecimal string. These are | 213 followed by a hexadecimal (or <emphasis>hex</emphasis>) |
230 <emphasis>identifiers</emphasis> for the changeset. There | 214 string. These are <emphasis>identifiers</emphasis> for the |
231 are two identifiers because the number is shorter and easier | 215 changeset. The hex string is a unique identifier: the same |
232 to type than the hex string.</para></listitem> | 216 hex string will always refer to the same changeset. The |
217 number is shorter and easier to type than the hex string, | |
218 but it isn't unique: the same number in two different clones | |
219 of a repository may identify different changesets. Why | |
220 provide the number at all, then? For local | |
221 convenience.</para> | |
222 </listitem> | |
233 <listitem><para id="x_1f"><literal>user</literal>: The identity of the | 223 <listitem><para id="x_1f"><literal>user</literal>: The identity of the |
234 person who created the changeset. This is a free-form | 224 person who created the changeset. This is a free-form |
235 field, but it most often contains a person's name and email | 225 field, but it most often contains a person's name and email |
236 address.</para></listitem> | 226 address.</para></listitem> |
237 <listitem><para id="x_20"><literal>date</literal>: The date and time on | 227 <listitem><para id="x_20"><literal>date</literal>: The date and time on |
239 it was created. (The date and time are local to that | 229 it was created. (The date and time are local to that |
240 timezone; they display what time and date it was for the | 230 timezone; they display what time and date it was for the |
241 person who created the changeset.)</para></listitem> | 231 person who created the changeset.)</para></listitem> |
242 <listitem><para id="x_21"><literal>summary</literal>: The first line of | 232 <listitem><para id="x_21"><literal>summary</literal>: The first line of |
243 the text message that the creator of the changeset entered | 233 the text message that the creator of the changeset entered |
244 to describe the changeset.</para></listitem></itemizedlist> | 234 to describe the changeset.</para></listitem> |
245 <para id="x_22">The default output printed by <command role="hg-cmd">hg | 235 <listitem> |
246 log</command> is purely a summary; it is missing a lot of | 236 <para>Some changesets, such as the first in the list above, |
247 detail.</para> | 237 have a <literal>tag</literal> field. A tag is another way |
238 to identify a changeset, by giving it an easy-to-remember | |
239 name. (The tag named <literal>tip</literal> is special: it | |
240 always refers to the newest change in a repository.)</para> | |
241 </listitem> | |
242 </itemizedlist> | |
243 | |
244 <para id="x_22">The default output printed by <command | |
245 role="hg-cmd">hg log</command> is purely a summary; it is | |
246 missing a lot of detail.</para> | |
248 | 247 |
249 <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides | 248 <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides |
250 a graphical representation of the history of the <filename | 249 a graphical representation of the history of the <filename |
251 class="directory">hello</filename> repository, to make it a | 250 class="directory">hello</filename> repository, to make it a |
252 little easier to see which direction history is | 251 little easier to see which direction history is |
284 great importance. Recall that the <literal>changeset</literal> | 283 great importance. Recall that the <literal>changeset</literal> |
285 field in the output from <command role="hg-cmd">hg | 284 field in the output from <command role="hg-cmd">hg |
286 log</command> identifies a changeset using both a number and | 285 log</command> identifies a changeset using both a number and |
287 a hexadecimal string.</para> | 286 a hexadecimal string.</para> |
288 <itemizedlist> | 287 <itemizedlist> |
289 <listitem><para id="x_27">The revision number is <emphasis>only valid in | 288 <listitem><para id="x_27">The revision number is a handy |
290 that repository</emphasis>,</para></listitem> | 289 notation that is <emphasis>only valid in that |
291 <listitem><para id="x_28">while the hex string is the | 290 repository</emphasis>.</para></listitem> |
291 <listitem><para id="x_28">The hexadecimal string is the | |
292 <emphasis>permanent, unchanging identifier</emphasis> that | 292 <emphasis>permanent, unchanging identifier</emphasis> that |
293 will always identify that exact changeset in | 293 will always identify that exact changeset in |
294 <emphasis>every</emphasis> copy of the | 294 <emphasis>every</emphasis> copy of the |
295 repository.</para></listitem></itemizedlist> | 295 repository.</para></listitem></itemizedlist> |
296 <para id="x_29">This distinction is important. If you send someone an | 296 |
297 email talking about <quote>revision 33</quote>, there's a high | 297 <para id="x_29">This distinction is important. If you send |
298 likelihood that their revision 33 will <emphasis>not be the | 298 someone an email talking about <quote>revision 33</quote>, |
299 same</emphasis> as yours. The reason for this is that a | 299 there's a high likelihood that their revision 33 will |
300 revision number depends on the order in which changes arrived | 300 <emphasis>not be the same</emphasis> as yours. The reason for |
301 in a repository, and there is no guarantee that the same | 301 this is that a revision number depends on the order in which |
302 changes will happen in the same order in different | 302 changes arrived in a repository, and there is no guarantee |
303 repositories. Three changes $a,b,c$ can easily appear in one | 303 that the same changes will happen in the same order in |
304 repository as $0,1,2$, while in another as $1,0,2$.</para> | 304 different repositories. Three changes <literal>a,b,c</literal> |
305 can easily appear in one repository as | |
306 <literal>0,1,2</literal>, while in another as | |
307 <literal>0,2,1</literal>.</para> | |
305 | 308 |
306 <para id="x_2a">Mercurial uses revision numbers purely as a convenient | 309 <para id="x_2a">Mercurial uses revision numbers purely as a convenient |
307 shorthand. If you need to discuss a changeset with someone, | 310 shorthand. If you need to discuss a changeset with someone, |
308 or make a record of a changeset for some other reason (for | 311 or make a record of a changeset for some other reason (for |
309 example, in a bug report), use the hexadecimal | 312 example, in a bug report), use the hexadecimal |
315 | 318 |
316 <para id="x_2b">To narrow the output of <command role="hg-cmd">hg | 319 <para id="x_2b">To narrow the output of <command role="hg-cmd">hg |
317 log</command> down to a single revision, use the <option | 320 log</command> down to a single revision, use the <option |
318 role="hg-opt-log">-r</option> (or <option | 321 role="hg-opt-log">-r</option> (or <option |
319 role="hg-opt-log">--rev</option>) option. You can use | 322 role="hg-opt-log">--rev</option>) option. You can use |
320 either a revision number or a long-form changeset identifier, | 323 either a revision number or a hexadecimal identifier, |
321 and you can provide as many revisions as you want.</para> | 324 and you can provide as many revisions as you want.</para> |
322 | 325 |
323 &interaction.tour.log-r; | 326 &interaction.tour.log-r; |
324 | 327 |
325 <para id="x_2c">If you want to see the history of several revisions | 328 <para id="x_2c">If you want to see the history of several revisions |
359 (if you've never seen a unified diff before, see <xref | 362 (if you've never seen a unified diff before, see <xref |
360 linkend="sec:mq:patch"/> for an overview).</para> | 363 linkend="sec:mq:patch"/> for an overview).</para> |
361 | 364 |
362 &interaction.tour.log-vp; | 365 &interaction.tour.log-vp; |
363 | 366 |
367 <para>The <option role="hg-opt-log">-p</option> option is | |
368 tremendously useful, so it's well worth remembering.</para> | |
369 | |
364 </sect2> | 370 </sect2> |
365 </sect1> | 371 </sect1> |
372 | |
366 <sect1> | 373 <sect1> |
367 <title>All about command options</title> | 374 <title>All about command options</title> |
368 | 375 |
369 <para id="x_30">Let's take a brief break from exploring Mercurial commands | 376 <para id="x_30">Let's take a brief break from exploring Mercurial commands |
370 to discuss a pattern in the way that they work; you may find | 377 to discuss a pattern in the way that they work; you may find |
372 | 379 |
373 <para id="x_31">Mercurial has a consistent and straightforward approach to | 380 <para id="x_31">Mercurial has a consistent and straightforward approach to |
374 dealing with the options that you can pass to commands. It | 381 dealing with the options that you can pass to commands. It |
375 follows the conventions for options that are common to modern | 382 follows the conventions for options that are common to modern |
376 Linux and Unix systems.</para> | 383 Linux and Unix systems.</para> |
384 | |
377 <itemizedlist> | 385 <itemizedlist> |
378 <listitem><para id="x_32">Every option has a long name. For example, as | 386 <listitem> |
387 <para id="x_32">Every option has a long name. For example, as | |
379 we've already seen, the <command role="hg-cmd">hg | 388 we've already seen, the <command role="hg-cmd">hg |
380 log</command> command accepts a <option | 389 log</command> command accepts a <option |
381 role="hg-opt-log">--rev</option> option.</para></listitem> | 390 role="hg-opt-log">--rev</option> option.</para> |
382 <listitem><para id="x_33">Most options have short names, too. Instead of | 391 </listitem> |
383 <option role="hg-opt-log">--rev</option>, we can use <option | 392 <listitem> |
384 role="hg-opt-log">-r</option>. (The reason that some | 393 <para id="x_33">Most options have short names, too. Instead |
385 options don't have short names is that the options in | 394 of <option role="hg-opt-log">--rev</option>, we can use |
386 question are rarely used.)</para></listitem> | 395 <option role="hg-opt-log">-r</option>. (The reason that |
387 <listitem><para id="x_34">Long options start with two dashes (e.g. <option | 396 some options don't have short names is that the options in |
388 role="hg-opt-log">--rev</option>), while short options | 397 question are rarely used.)</para> |
389 start with one (e.g. <option | 398 </listitem> |
390 role="hg-opt-log">-r</option>).</para></listitem> | 399 <listitem> |
391 <listitem><para id="x_35">Option naming and usage is consistent across | 400 <para id="x_34">Long options start with two dashes (e.g. |
401 <option role="hg-opt-log">--rev</option>), while short | |
402 options start with one (e.g. <option | |
403 role="hg-opt-log">-r</option>).</para> | |
404 </listitem> | |
405 <listitem> | |
406 <para id="x_35">Option naming and usage is consistent across | |
392 commands. For example, every command that lets you specify | 407 commands. For example, every command that lets you specify |
393 a changeset ID or revision number accepts both <option | 408 a changeset ID or revision number accepts both <option |
394 role="hg-opt-log">-r</option> and <option | 409 role="hg-opt-log">-r</option> and <option |
395 role="hg-opt-log">--rev</option> | 410 role="hg-opt-log">--rev</option> arguments.</para> |
396 arguments.</para></listitem></itemizedlist> | 411 </listitem> |
412 <listitem> | |
413 <para>If you are using short options, you can save typing by | |
414 running them together. For example, the command <command | |
415 role="hg-cmd">hg log -v -p -r 2</command> can be written | |
416 as <command role="hg-cmd">hg log -vpr2</command>.</para> | |
417 </listitem> | |
418 </itemizedlist> | |
419 | |
397 <para id="x_36">In the examples throughout this book, I use short options | 420 <para id="x_36">In the examples throughout this book, I use short options |
398 instead of long. This just reflects my own preference, so don't | 421 instead of long. This just reflects my own preference, so don't |
399 read anything significant into it.</para> | 422 read anything significant into it.</para> |
400 | 423 |
401 <para id="x_37">Most commands that print output of some kind will print more | 424 <para id="x_37">Most commands that print output of some kind will print more |
402 output when passed a <option role="hg-opt-global">-v</option> | 425 output when passed a <option role="hg-opt-global">-v</option> |
403 (or <option role="hg-opt-global">--verbose</option>) option, and | 426 (or <option role="hg-opt-global">--verbose</option>) option, and |
404 less when passed <option role="hg-opt-global">-q</option> (or | 427 less when passed <option role="hg-opt-global">-q</option> (or |
405 <option role="hg-opt-global">--quiet</option>).</para> | 428 <option role="hg-opt-global">--quiet</option>).</para> |
429 | |
430 <note> | |
431 <title>Option naming consistency</title> | |
432 | |
433 <para>Almost always, Mercurial commands use consistent option | |
434 names to refer to the same concepts. For instance, if a | |
435 command deals with changesets, you'll always identify them | |
436 with <option role="hg-opt-log">--rev</option> or <option | |
437 role="hg-opt-log">-r</option>. This consistent use of | |
438 option names makes it easier to remember what options a | |
439 particular command takes.</para> | |
440 </note> | |
406 | 441 |
407 </sect1> | 442 </sect1> |
408 <sect1> | 443 <sect1> |
409 <title>Making and reviewing changes</title> | 444 <title>Making and reviewing changes</title> |
410 | 445 |
416 repository of its own. We use the <command role="hg-cmd">hg | 451 repository of its own. We use the <command role="hg-cmd">hg |
417 clone</command> command, but we don't need to clone a copy of | 452 clone</command> command, but we don't need to clone a copy of |
418 the remote repository. Since we already have a copy of it | 453 the remote repository. Since we already have a copy of it |
419 locally, we can just clone that instead. This is much faster | 454 locally, we can just clone that instead. This is much faster |
420 than cloning over the network, and cloning a local repository | 455 than cloning over the network, and cloning a local repository |
421 uses less disk space in most cases, too.</para> | 456 uses less disk space in most cases, too<footnote> |
457 <para>The saving of space arises when source and destination | |
458 repositories are on the same filesystem, in which case | |
459 Mercurial will use hardlinks to do copy-on-write sharing of | |
460 its internal metadata. If that explanation meant nothing to | |
461 you, don't worry: everything happens transparently and | |
462 automatically, and you don't need to understand it.</para> | |
463 </footnote>.</para> | |
422 | 464 |
423 &interaction.tour.reclone; | 465 &interaction.tour.reclone; |
424 | 466 |
425 <para id="x_3a">As an aside, it's often good practice to keep a | 467 <para id="x_3a">As an aside, it's often good practice to keep a |
426 <quote>pristine</quote> copy of a remote repository around, | 468 <quote>pristine</quote> copy of a remote repository around, |
431 local clones are so cheap, there's almost no overhead to cloning | 473 local clones are so cheap, there's almost no overhead to cloning |
432 and destroying repositories whenever you want.</para> | 474 and destroying repositories whenever you want.</para> |
433 | 475 |
434 <para id="x_3b">In our <filename class="directory">my-hello</filename> | 476 <para id="x_3b">In our <filename class="directory">my-hello</filename> |
435 repository, we have a file <filename>hello.c</filename> that | 477 repository, we have a file <filename>hello.c</filename> that |
436 contains the classic <quote>hello, world</quote> program. Let's | 478 contains the classic <quote>hello, world</quote> program.</para> |
437 use the ancient and venerable <command>sed</command> command to | 479 |
438 edit this file so that it prints a second line of output. (I'm | 480 &interaction.tour.cat1; |
439 only using <command>sed</command> to do this because it's easy | 481 |
440 to write a scripted example this way. Since you're not under | 482 <para>Let's edit this file so that it prints a second line of |
441 the same constraint, you probably won't want to use | 483 output.</para> |
442 <command>sed</command>; simply use your preferred text editor to | 484 |
443 do the same thing.)</para> | 485 &interaction.tour.cat2; |
444 | |
445 &interaction.tour.sed; | |
446 | 486 |
447 <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command> | 487 <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command> |
448 command will tell us what Mercurial knows about the files in the | 488 command will tell us what Mercurial knows about the files in the |
449 repository.</para> | 489 repository.</para> |
450 | 490 |
463 <emphasis>inform</emphasis> Mercurial that we were going to | 503 <emphasis>inform</emphasis> Mercurial that we were going to |
464 modify the file before we started, or that we had modified the | 504 modify the file before we started, or that we had modified the |
465 file after we were done; it was able to figure this out | 505 file after we were done; it was able to figure this out |
466 itself.</para> | 506 itself.</para> |
467 | 507 |
468 <para id="x_3f">It's a little bit helpful to know that we've modified | 508 <para id="x_3f">It's somewhat helpful to know that we've modified |
469 <filename>hello.c</filename>, but we might prefer to know | 509 <filename>hello.c</filename>, but we might prefer to know |
470 exactly <emphasis>what</emphasis> changes we've made to it. To | 510 exactly <emphasis>what</emphasis> changes we've made to it. To |
471 do this, we use the <command role="hg-cmd">hg diff</command> | 511 do this, we use the <command role="hg-cmd">hg diff</command> |
472 command.</para> | 512 command.</para> |
473 | 513 |
474 &interaction.tour.diff; | 514 &interaction.tour.diff; |
475 | 515 |
516 <tip> | |
517 <title>Understanding patches</title> | |
518 | |
519 <para>Remember to take a look at <xref | |
520 linkend="sec:mq:patch"/> if you don't know how to read | |
521 output above.</para> | |
522 </tip> | |
476 </sect1> | 523 </sect1> |
477 <sect1> | 524 <sect1> |
478 <title>Recording changes in a new changeset</title> | 525 <title>Recording changes in a new changeset</title> |
479 | 526 |
480 <para id="x_40">We can modify files, build and test our changes, and use | 527 <para id="x_40">We can modify files, build and test our changes, and use |
547 role="special">.hgrc</filename> in your home directory. | 594 role="special">.hgrc</filename> in your home directory. |
548 Mercurial will use this file to look up your personalised | 595 Mercurial will use this file to look up your personalised |
549 configuration settings. The initial contents of your | 596 configuration settings. The initial contents of your |
550 <filename role="special">.hgrc</filename> should look like | 597 <filename role="special">.hgrc</filename> should look like |
551 this.</para> | 598 this.</para> |
599 | |
600 <remark>Figure out what the appropriate directory is on | |
601 Windows.</remark> | |
602 | |
552 <programlisting># This is a Mercurial configuration file. | 603 <programlisting># This is a Mercurial configuration file. |
553 [ui] | 604 [ui] |
554 username = Firstname Lastname | 605 username = Firstname Lastname <email.address@domain.net></programlisting> |
555 <email.address@domain.net></programlisting> | |
556 | 606 |
557 <para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a | 607 <para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a |
558 <emphasis>section</emphasis> of the config file, so you can | 608 <emphasis>section</emphasis> of the config file, so you can |
559 read the <quote><literal>username = ...</literal></quote> | 609 read the <quote><literal>username = ...</literal></quote> |
560 line as meaning <quote>set the value of the | 610 line as meaning <quote>set the value of the |
569 <sect3> | 619 <sect3> |
570 <title>Choosing a user name</title> | 620 <title>Choosing a user name</title> |
571 | 621 |
572 <para id="x_4c">You can use any text you like as the value of | 622 <para id="x_4c">You can use any text you like as the value of |
573 the <literal>username</literal> config item, since this | 623 the <literal>username</literal> config item, since this |
574 information is for reading by other people, but for | 624 information is for reading by other people, but will not be |
575 interpreting by Mercurial. The convention that most | 625 interpreted by Mercurial. The convention that most |
576 people follow is to use their name and email address, as | 626 people follow is to use their name and email address, as |
577 in the example above.</para> | 627 in the example above.</para> |
578 <note> | 628 <note> |
579 <para id="x_4d">Mercurial's built-in web server obfuscates | 629 <para id="x_4d">Mercurial's built-in web server obfuscates |
580 email addresses, to make it more difficult for the email | 630 email addresses, to make it more difficult for the email |
598 | 648 |
599 &interaction.tour.commit; | 649 &interaction.tour.commit; |
600 | 650 |
601 <para id="x_4f">The editor that the <command role="hg-cmd">hg | 651 <para id="x_4f">The editor that the <command role="hg-cmd">hg |
602 commit</command> command drops us into will contain an | 652 commit</command> command drops us into will contain an |
603 empty line, followed by a number of lines starting with | 653 empty line or two, followed by a number of lines starting with |
604 <quote><literal>HG:</literal></quote>.</para> | 654 <quote><literal>HG:</literal></quote>.</para> |
605 | 655 |
606 <programlisting>XXX fix this XXX</programlisting> | 656 <programlisting> |
657 This is where I type my commit comment. | |
658 | |
659 HG: Enter commit message. Lines beginning with 'HG:' are removed. | |
660 HG: -- | |
661 HG: user: Bryan O'Sullivan <bos@serpentine.com> | |
662 HG: branch 'default' | |
663 HG: changed hello.c</programlisting> | |
607 | 664 |
608 <para id="x_50">Mercurial ignores the lines that start with | 665 <para id="x_50">Mercurial ignores the lines that start with |
609 <quote><literal>HG:</literal></quote>; it uses them only to | 666 <quote><literal>HG:</literal></quote>; it uses them only to |
610 tell us which files it's recording changes to. Modifying or | 667 tell us which files it's recording changes to. Modifying or |
611 deleting these lines has no effect.</para> | 668 deleting these lines has no effect.</para> |
663 log</command>, but it only displays the newest revision in | 720 log</command>, but it only displays the newest revision in |
664 the repository.</para> | 721 the repository.</para> |
665 | 722 |
666 &interaction.tour.tip; | 723 &interaction.tour.tip; |
667 | 724 |
668 <para id="x_57">We refer to | 725 <para id="x_57">We refer to the newest revision in the |
669 the newest revision in the repository as the tip revision, | 726 repository as the <emphasis>tip revision</emphasis>, or simply |
670 or simply the tip.</para> | 727 the <emphasis>tip</emphasis>.</para> |
728 | |
729 <para>By the way, the <command role="hg-cmd">hg tip</command> | |
730 command accepts many of the same options as <command | |
731 role="hg-cmd">hg log</command>, so <option | |
732 role="hg-opt-global">-v</option> above indicates <quote>be | |
733 verbose</quote>, <option role="hg-opt-tip">-p</option> | |
734 specifies <quote>print a patch</quote>. The use of <option | |
735 role="hg-opt-tip">-p</option> to print patches is another | |
736 example of the consistent naming we mentioned earlier.</para> | |
671 </sect2> | 737 </sect2> |
672 </sect1> | 738 </sect1> |
673 | 739 |
674 <sect1> | 740 <sect1> |
675 <title>Sharing changes</title> | 741 <title>Sharing changes</title> |
702 command <emphasis>would</emphasis> pull into the repository, | 768 command <emphasis>would</emphasis> pull into the repository, |
703 without actually pulling the changes in.</para> | 769 without actually pulling the changes in.</para> |
704 | 770 |
705 &interaction.tour.incoming; | 771 &interaction.tour.incoming; |
706 | 772 |
707 <para id="x_5b">(Of course, someone could | 773 <para id="x_5b">Suppose you're pulling changes from a repository |
708 cause more changesets to appear in the repository that we | 774 on the network somewhere. While you are looking at the <command |
709 ran <command role="hg-cmd">hg incoming</command> in, before | 775 role="hg-cmd">hg incoming</command> output, and before you |
710 we get a chance to <command role="hg-cmd">hg pull</command> | 776 pull those changes, someone might have committed something in |
711 the changes, so that we could end up pulling changes that we | 777 the remote repository. This means that it's possible to pull |
712 didn't expect.)</para> | 778 more changes than you saw when using <command |
779 role="hg-cmd">hg incoming</command>.</para> | |
713 | 780 |
714 <para id="x_5c">Bringing changes into a repository is a simple | 781 <para id="x_5c">Bringing changes into a repository is a simple |
715 matter of running the <command role="hg-cmd">hg | 782 matter of running the <command role="hg-cmd">hg |
716 pull</command> command, and telling it which repository to | 783 pull</command> command, and telling it which repository to |
717 pull from.</para> | 784 pull from.</para> |
744 pull</command> doesn't update the working directory | 811 pull</command> doesn't update the working directory |
745 automatically. There's actually a good reason for this: you | 812 automatically. There's actually a good reason for this: you |
746 can use <command role="hg-cmd">hg update</command> to update | 813 can use <command role="hg-cmd">hg update</command> to update |
747 the working directory to the state it was in at <emphasis>any | 814 the working directory to the state it was in at <emphasis>any |
748 revision</emphasis> in the history of the repository. If | 815 revision</emphasis> in the history of the repository. If |
749 you had the working directory updated to an old revision---to | 816 you had the working directory updated to an old revision&emdash;to |
750 hunt down the origin of a bug, say---and ran a <command | 817 hunt down the origin of a bug, say&emdash;and ran a <command |
751 role="hg-cmd">hg pull</command> which automatically updated | 818 role="hg-cmd">hg pull</command> which automatically updated |
752 the working directory to a new revision, you might not be | 819 the working directory to a new revision, you might not be |
753 terribly happy.</para> | 820 terribly happy.</para> |
754 <para id="x_60">However, since pull-then-update is such a common thing to | 821 <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 | 822 do, Mercurial lets you combine the two by passing the <option |
815 <command role="hg-cmd">hg push</command> command does the | 882 <command role="hg-cmd">hg push</command> command does the |
816 actual push.</para> | 883 actual push.</para> |
817 | 884 |
818 &interaction.tour.push; | 885 &interaction.tour.push; |
819 | 886 |
820 <para id="x_69">As with | 887 <para id="x_69">As with <command role="hg-cmd">hg |
821 <command role="hg-cmd">hg pull</command>, the <command | 888 pull</command>, the <command role="hg-cmd">hg push</command> |
822 role="hg-cmd">hg push</command> command does not update | 889 command does not update the working directory in the |
823 the working directory in the repository that it's pushing | 890 repository that it's pushing changes into. Unlike <command |
824 changes into. (Unlike <command role="hg-cmd">hg | 891 role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg |
825 pull</command>, <command role="hg-cmd">hg push</command> | 892 push</command> does not provide a <literal>-u</literal> |
826 does not provide a <literal>-u</literal> option that updates | 893 option that updates the other repository's working directory. |
827 the other repository's working directory.)</para> | 894 This asymmetry is deliberate: the repository we're pushing to |
895 might be on a remote server and shared between several people. | |
896 If we were to update its working directory while someone was | |
897 working in it, their work would be disrupted.</para> | |
828 | 898 |
829 <para id="x_6a">What happens if we try to pull or push changes | 899 <para id="x_6a">What happens if we try to pull or push changes |
830 and the receiving repository already has those changes? | 900 and the receiving repository already has those changes? |
831 Nothing too exciting.</para> | 901 Nothing too exciting.</para> |
832 | 902 |