hgbook
annotate en/ch02-tour-basic.xml @ 1114:527b86d55d4a
inotify: update installation information
inotify is shipped in Mercurial since 1.0, which greatly simplifies the installation process
inotify is shipped in Mercurial since 1.0, which greatly simplifies the installation process
author | Nicolas Dumazet <nicdumz.commits@gmail.com> |
---|---|
date | Sun Dec 13 16:35:56 2009 +0900 (2009-12-13) |
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 <email.address@example.net></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 <bos@serpentine.com> |
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 <censored.person@example.org> |
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 --> |