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