hgbook

annotate en/ch02-tour-basic.xml @ 1033:47f3810fd4fd

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