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