hgbook

annotate en/appA-svn.xml @ 890:2887b61fa4fe

find changesets by author, revision, files, or words in the commit message
Change fields to fieldsets in the Comment admin model. The 'date'
field isn't working properly for an unknown reason, so it has been
removed from the interface temporarily.
author dukebody <dukebody@gmail.com>
date Sun Oct 11 21:12:46 2009 +0200 (2009-10-11)
parents 3edacbff2b43
children
rev   line source
bos@559 1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
bos@559 2
bos@686 3 <appendix id="svn">
bos@687 4 <?dbhtml filename="migrating-to-mercurial.html"?>
bos@686 5 <title>Migrating to Mercurial</title>
bos@686 6
bos@691 7 <para id="x_6e1">A common way to test the waters with a new revision control
bos@686 8 tool is to experiment with switching an existing project, rather
bos@686 9 than starting a new project from scratch.</para>
bos@686 10
bos@691 11 <para id="x_6e2">In this appendix, we discuss how to import a project's history
bos@686 12 into Mercurial, and what to look out for if you are used to a
bos@686 13 different revision control system.</para>
bos@686 14
bos@686 15 <sect1>
bos@686 16 <title>Importing history from another system</title>
bos@686 17
bos@691 18 <para id="x_6e3">Mercurial ships with an extension named
bos@686 19 <literal>convert</literal>, which can import project history
bos@686 20 from most popular revision control systems. At the time this
bos@686 21 book was written, it could import history from the following
bos@686 22 systems:</para>
bos@686 23 <itemizedlist>
bos@686 24 <listitem>
bos@691 25 <para id="x_6e4">Subversion</para>
bos@691 26 </listitem>
bos@691 27 <listitem>
bos@691 28 <para id="x_6e5">CVS</para>
bos@691 29 </listitem>
bos@691 30 <listitem>
bos@691 31 <para id="x_6e6">git</para>
bos@691 32 </listitem>
bos@691 33 <listitem>
bos@691 34 <para id="x_6e7">Darcs</para>
bos@691 35 </listitem>
bos@691 36 <listitem>
bos@691 37 <para id="x_6e8">Bazaar</para>
bos@691 38 </listitem>
bos@691 39 <listitem>
bos@691 40 <para id="x_6e9">Monotone</para>
bos@691 41 </listitem>
bos@691 42 <listitem>
bos@691 43 <para id="x_6ea">GNU Arch</para>
bos@691 44 </listitem>
bos@691 45 <listitem>
bos@691 46 <para id="x_6eb">Mercurial</para>
bos@686 47 </listitem>
bos@686 48 </itemizedlist>
bos@686 49
bos@691 50 <para id="x_6ec">(To see why Mercurial itself is supported as a source, see
bos@686 51 <xref linkend="svn.filemap"/>.)</para>
bos@686 52
bos@691 53 <para id="x_6ed">You can enable the extension in the usual way, by editing
bos@686 54 your <filename>~/.hgrc</filename> file.</para>
bos@686 55
bos@686 56 <programlisting>[extensions]
bos@686 57 convert =</programlisting>
bos@686 58
bos@691 59 <para id="x_6ee">This will make a <command>hg convert</command> command
bos@686 60 available. The command is easy to use. For instance, this
bos@686 61 command will import the Subversion history for the Nose unit
bos@686 62 testing framework into Mercurial.</para>
bos@686 63
bos@686 64 <screen><prompt>$</prompt> <userinput>hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen>
bos@686 65
bos@691 66 <para id="x_6ef">The <literal>convert</literal> extension operates
bos@686 67 incrementally. In other words, after you have run <command>hg
bos@686 68 convert</command> once, running it again will import any new
bos@686 69 revisions committed after the first run began. Incremental
bos@686 70 conversion will only work if you run <command>hg
bos@686 71 convert</command> in the same Mercurial repository that you
bos@686 72 originally used, because the <literal>convert</literal>
bos@686 73 extension saves some private metadata in a
bos@686 74 non-revision-controlled file named
bos@686 75 <filename>.hg/shamap</filename> inside the target
bos@686 76 repository.</para>
bos@686 77
bos@695 78 <para id="x_707">When you want to start making changes using Mercurial, it's
bos@693 79 best to clone the tree in which you are doing your conversions,
bos@693 80 and leave the original tree for future incremental conversions.
bos@693 81 This is the safest way to let you pull and merge future commits
bos@693 82 from the source revision control system into your newly active
bos@693 83 Mercurial project.</para>
bos@693 84
bos@693 85 <sect2>
bos@693 86 <title>Converting multiple branches</title>
bos@693 87
bos@695 88 <para id="x_708">The <command>hg convert</command> command given above
bos@693 89 converts only the history of the <literal>trunk</literal>
bos@693 90 branch of the Subversion repository. If we instead use the
bos@693 91 URL <literal>http://python-nose.googlecode.com/svn</literal>,
bos@693 92 Mercurial will automatically detect the
bos@693 93 <literal>trunk</literal>, <literal>tags</literal> and
bos@693 94 <literal>branches</literal> layout that Subversion projects
bos@693 95 usually use, and it will import each as a separate Mercurial
bos@693 96 branch.</para>
bos@693 97
bos@695 98 <para id="x_709">By default, each Subversion branch imported into Mercurial
bos@693 99 is given a branch name. After the conversion completes, you
bos@693 100 can get a list of the active branch names in the Mercurial
bos@693 101 repository using <command>hg branches -a</command>. If you
bos@693 102 would prefer to import the Subversion branches without names,
bos@693 103 pass the <option>--config
bos@693 104 convert.hg.usebranchnames=false</option> option to
bos@693 105 <command>hg convert</command>.</para>
bos@693 106
bos@695 107 <para id="x_70a">Once you have converted your tree, if you want to follow
bos@693 108 the usual Mercurial practice of working in a tree that
bos@693 109 contains a single branch, you can clone that single branch
bos@693 110 using <command>hg clone -r mybranchname</command>.</para>
bos@693 111 </sect2>
bos@693 112
bos@686 113 <sect2>
bos@686 114 <title>Mapping user names</title>
bos@686 115
bos@691 116 <para id="x_6f0">Some revision control tools save only short usernames with
bos@686 117 commits, and these can be difficult to interpret. The norm
bos@686 118 with Mercurial is to save a committer's name and email
bos@686 119 address, which is much more useful for talking to them after
bos@686 120 the fact.</para>
bos@686 121
bos@691 122 <para id="x_6f1">If you are converting a tree from a revision control
bos@686 123 system that uses short names, you can map those names to
bos@686 124 longer equivalents by passing a <option>--authors</option>
bos@686 125 option to <command>hg convert</command>. This option accepts
bos@686 126 a file name that should contain entries of the following
bos@686 127 form.</para>
bos@686 128
bos@686 129 <programlisting>arist = Aristotle &lt;aristotle@phil.example.gr&gt;
bos@686 130 soc = Socrates &lt;socrates@phil.example.gr&gt;</programlisting>
bos@686 131
bos@691 132 <para id="x_6f2">Whenever <literal>convert</literal> encounters a commit
bos@686 133 with the username <literal>arist</literal> in the source
bos@686 134 repository, it will use the name <literal>Aristotle
bos@686 135 &lt;aristotle@phil.example.gr&gt;</literal> in the converted
bos@686 136 Mercurial revision. If no match is found for a name, it is
bos@686 137 used verbatim.</para>
bos@686 138 </sect2>
bos@686 139
bos@686 140 <sect2 id="svn.filemap">
bos@686 141 <title>Tidying up the tree</title>
bos@686 142
bos@691 143 <para id="x_6f3">Not all projects have pristine history. There may be a
bos@686 144 directory that should never have been checked in, a file that
bos@686 145 is too big, or a whole hierarchy that needs to be
bos@686 146 refactored.</para>
bos@686 147
bos@691 148 <para id="x_6f4">The <literal>convert</literal> extension supports the idea
bos@686 149 of a <quote>file map</quote> that can reorganize the files and
bos@686 150 directories in a project as it imports the project's history.
bos@686 151 This is useful not only when importing history from other
bos@686 152 revision control systems, but also to prune or refactor a
bos@686 153 Mercurial tree.</para>
bos@686 154
bos@691 155 <para id="x_6f5">To specify a file map, use the <option>--filemap</option>
bos@686 156 option and supply a file name. A file map contains lines of the
bos@686 157 following forms.</para>
bos@686 158
bos@686 159 <programlisting># This is a comment.
bos@686 160 # Empty lines are ignored.
bos@686 161
bos@686 162 include path/to/file
bos@686 163
bos@686 164 exclude path/to/file
bos@686 165
bos@686 166 rename from/some/path to/some/other/place
bos@686 167 </programlisting>
bos@686 168
bos@691 169 <para id="x_6f6">The <literal>include</literal> directive causes a file, or
bos@686 170 all files under a directory, to be included in the destination
bos@686 171 repository. This also excludes all other files and dirs not
bos@686 172 explicitely included. The <literal>exclude</literal>
bos@686 173 directive causes files or directories to be omitted, and
bos@686 174 others not explicitly mentioned to be included.</para>
bos@686 175
bos@691 176 <para id="x_6f7">To move a file or directory from one location to another,
bos@686 177 use the <literal>rename</literal> directive. If you need to
bos@686 178 move a file or directory from a subdirectory into the root of
bos@686 179 the repository, use <literal>.</literal> as the second
bos@686 180 argument to the <literal>rename</literal> directive.</para>
bos@686 181 </sect2>
bos@693 182
bos@693 183 <sect2>
bos@693 184 <title>Improving Subversion conversion performance</title>
bos@693 185
bos@695 186 <para id="x_70b">You will often need several attempts before you hit the
bos@693 187 perfect combination of user map, file map, and other
bos@693 188 conversion parameters. Converting a Subversion repository
bos@693 189 over an access protocol like <literal>ssh</literal> or
bos@693 190 <literal>http</literal> can proceed thousands of times more
bos@693 191 slowly than Mercurial is capable of actually operating, due to
bos@693 192 network delays. This can make tuning that perfect conversion
bos@693 193 recipe very painful.</para>
bos@693 194
bos@695 195 <para id="x_70c">The <ulink
bos@693 196 url="http://svn.collab.net/repos/svn/trunk/notes/svnsync.txt"><command>svnsync</command></ulink>
bos@693 197 command can greatly speed up the conversion of a Subversion
bos@693 198 repository. It is a read-only mirroring program for
bos@693 199 Subversion repositories. The idea is that you create a local
bos@693 200 mirror of your Subversion tree, then convert the mirror into a
bos@693 201 Mercurial repository.</para>
bos@693 202
bos@695 203 <para id="x_70d">Suppose we want to convert the Subversion repository for
bos@693 204 the popular Memcached project into a Mercurial tree. First,
bos@693 205 we create a local Subversion repository.</para>
bos@693 206
bos@693 207 <screen><prompt>$</prompt> <userinput>svnadmin create memcached-mirror</userinput></screen>
bos@693 208
bos@695 209 <para id="x_70e">Next, we set up a Subversion hook that
bos@693 210 <command>svnsync</command> needs.</para>
bos@693 211
bos@693 212 <screen><prompt>$</prompt> <userinput>echo '#!/bin/sh' > memcached-mirror/hooks/pre-revprop-change</userinput>
bos@693 213 <prompt>$</prompt> <userinput>chmod +x memcached-mirror/hooks/pre-revprop-change</userinput></screen>
bos@693 214
bos@695 215 <para id="x_70f">We then initialize <command>svnsync</command> in this
bos@693 216 repository.</para>
bos@693 217
bos@693 218 <screen><prompt>$</prompt> <userinput>svnsync --init file://`pwd`/memcached-mirror \
bos@693 219 http://code.sixapart.com/svn/memcached</userinput></screen>
bos@693 220
bos@695 221 <para id="x_710">Our next step is to begin the <command>svnsync</command>
bos@693 222 mirroring process.</para>
bos@693 223
bos@693 224 <screen><prompt>$</prompt> <userinput>svnsync sync file://`pwd`/memcached-mirror</userinput></screen>
bos@693 225
bos@695 226 <para id="x_711">Finally, we import the history of our local Subversion
bos@693 227 mirror into Mercurial.</para>
bos@693 228
bos@693 229 <screen><prompt>$</prompt> <userinput>hg convert memcached-mirror</userinput></screen>
bos@693 230
bos@695 231 <para id="x_712">We can use this process incrementally if the Subversion
bos@693 232 repository is still in use. We run <command>svnsync</command>
bos@693 233 to pull new changes into our mirror, then <command>hg
bos@693 234 convert</command> to import them into our Mercurial
bos@693 235 tree.</para>
bos@693 236
bos@695 237 <para id="x_713">There are two advantages to doing a two-stage import with
bos@693 238 <command>svnsync</command>. The first is that it uses more
bos@693 239 efficient Subversion network syncing code than <command>hg
bos@693 240 convert</command>, so it transfers less data over the
bos@693 241 network. The second is that the import from a local
bos@693 242 Subversion tree is so fast that you can tweak your conversion
bos@693 243 setup repeatedly without having to sit through a painfully
bos@693 244 slow network-based conversion process each time.</para>
bos@693 245 </sect2>
bos@686 246 </sect1>
bos@686 247
bos@686 248 <sect1>
bos@686 249 <title>Migrating from Subversion</title>
bos@686 250
bos@691 251 <para id="x_6f8">Subversion is currently the most popular open source
bos@686 252 revision control system. Although there are many differences
bos@686 253 between Mercurial and Subversion, making the transition from
bos@686 254 Subversion to Mercurial is not particularly difficult. The two
bos@686 255 have similar command sets and generally uniform
bos@686 256 interfaces.</para>
bos@686 257
bos@686 258 <sect2>
bos@686 259 <title>Philosophical differences</title>
bos@686 260
bos@691 261 <para id="x_6f9">The fundamental difference between Subversion and
bos@686 262 Mercurial is of course that Subversion is centralized, while
bos@686 263 Mercurial is distributed. Since Mercurial stores all of a
bos@686 264 project's history on your local drive, it only needs to
bos@686 265 perform a network access when you want to explicitly
bos@686 266 communicate with another repository. In contrast, Subversion
bos@686 267 stores very little information locally, and the client must
bos@686 268 thus contact its server for many common operations.</para>
bos@686 269
bos@691 270 <para id="x_6fa">Subversion more or less gets away without a well-defined
bos@686 271 notion of a branch: which portion of a server's namespace
bos@686 272 qualifies as a branch is a matter of convention, with the
bos@686 273 software providing no enforcement. Mercurial treats a
bos@686 274 repository as the unit of branch management.</para>
bos@686 275
bos@686 276 <sect3>
bos@686 277 <title>Scope of commands</title>
bos@686 278
bos@691 279 <para id="x_6fb">Since Subversion doesn't know what parts of its
bos@686 280 namespace are really branches, it treats most commands as
bos@686 281 requests to operate at and below whatever directory you are
bos@686 282 currently visiting. For instance, if you run <command>svn
bos@686 283 log</command>, you'll get the history of whatever part of
bos@686 284 the tree you're looking at, not the tree as a whole.</para>
bos@686 285
bos@691 286 <para id="x_6fc">Mercurial's commands behave differently, by defaulting
bos@686 287 to operating over an entire repository. Run <command>hg
bos@686 288 log</command> and it will tell you the history of the
bos@686 289 entire tree, no matter what part of the working directory
bos@686 290 you're visiting at the time. If you want the history of
bos@686 291 just a particular file or directory, simply supply it by
bos@686 292 name, e.g. <command>hg log src</command>.</para>
bos@686 293
bos@691 294 <para id="x_6fd">From my own experience, this difference in default
bos@686 295 behaviors is probably the most likely to trip you up if you
bos@686 296 have to switch back and forth frequently between the two
bos@686 297 tools.</para>
bos@686 298 </sect3>
bos@686 299
bos@686 300 <sect3>
bos@686 301 <title>Multi-user operation and safety</title>
bos@686 302
bos@691 303 <para id="x_6fe">With Subversion, it is normal (though slightly frowned
bos@686 304 upon) for multiple people to collaborate in a single branch.
bos@686 305 If Alice and Bob are working together, and Alice commits
bos@686 306 some changes to their shared branch, Bob must update his
bos@686 307 client's view of the branch before he can commit. Since at
bos@686 308 this time he has no permanent record of the changes he has
bos@686 309 made, he can corrupt or lose his modifications during and
bos@686 310 after his update.</para>
bos@686 311
bos@691 312 <para id="x_6ff">Mercurial encourages a commit-then-merge model instead.
bos@686 313 Bob commits his changes locally before pulling changes from,
bos@686 314 or pushing them to, the server that he shares with Alice.
bos@686 315 If Alice pushed her changes before Bob tries to push his, he
bos@686 316 will not be able to push his changes until he pulls hers,
bos@686 317 merges with them, and commits the result of the merge. If
bos@686 318 he makes a mistake during the merge, he still has the option
bos@686 319 of reverting to the commit that recorded his changes.</para>
bos@686 320
bos@691 321 <para id="x_700">It is worth emphasizing that these are the common ways
bos@686 322 of working with these tools. Subversion supports a safer
bos@686 323 work-in-your-own-branch model, but it is cumbersome enough
bos@686 324 in practice to not be widely used. Mercurial can support
bos@686 325 the less safe mode of allowing changes to be pulled in and
bos@686 326 merged on top of uncommitted edits, but this is considered
bos@686 327 highly unusual.</para>
bos@686 328 </sect3>
bos@686 329
bos@686 330 <sect3>
bos@686 331 <title>Published vs local changes</title>
bos@686 332
bos@691 333 <para id="x_701">A Subversion <command>svn commit</command> command
bos@686 334 immediately publishes changes to a server, where they can be
bos@686 335 seen by everyone who has read access.</para>
bos@686 336
bos@691 337 <para id="x_702">With Mercurial, commits are always local, and must be
bos@686 338 published via a <command>hg push</command> command
bos@686 339 afterwards.</para>
bos@686 340
bos@691 341 <para id="x_703">Each approach has its advantages and disadvantages. The
bos@686 342 Subversion model means that changes are published, and hence
bos@686 343 reviewable and usable, immediately. On the other hand, this
bos@686 344 means that a user must have commit access to a repository in
bos@686 345 order to use the software in a normal way, and commit access
bos@686 346 is not lightly given out by most open source
bos@686 347 projects.</para>
bos@686 348
bos@691 349 <para id="x_704">The Mercurial approach allows anyone who can clone a
bos@686 350 repository to commit changes without the need for someone
bos@686 351 else's permission, and they can then publish their changes
bos@686 352 and continue to participate however they see fit. The
bos@686 353 distinction between committing and pushing does open up the
bos@686 354 possibility of someone committing changes to their laptop
bos@686 355 and walking away for a few days having forgotten to push
bos@686 356 them, which in rare cases might leave collaborators
bos@686 357 temporarily stuck.</para>
bos@686 358 </sect3>
bos@686 359 </sect2>
bos@686 360
bos@686 361 <sect2>
bos@686 362 <title>Quick reference</title>
bos@686 363
bos@686 364 <table>
bos@686 365 <title>Subversion commands and Mercurial equivalents</title>
bos@686 366 <tgroup cols="3">
bos@686 367 <thead>
bos@686 368 <row>
bos@686 369 <entry>Subversion</entry>
bos@686 370 <entry>Mercurial</entry>
bos@686 371 <entry>Notes</entry>
bos@686 372 </row>
bos@686 373 </thead>
bos@686 374 <tbody>
bos@686 375 <row>
bos@686 376 <entry><command>svn add</command></entry>
bos@686 377 <entry><command>hg add</command></entry>
bos@686 378 <entry></entry>
bos@686 379 </row>
bos@686 380 <row>
bos@686 381 <entry><command>svn blame</command></entry>
bos@686 382 <entry><command>hg annotate</command></entry>
bos@686 383 <entry></entry>
bos@686 384 </row>
bos@686 385 <row>
bos@686 386 <entry><command>svn cat</command></entry>
bos@686 387 <entry><command>hg cat</command></entry>
bos@686 388 <entry></entry>
bos@686 389 </row>
bos@686 390 <row>
bos@686 391 <entry><command>svn checkout</command></entry>
bos@686 392 <entry><command>hg clone</command></entry>
bos@686 393 <entry></entry>
bos@686 394 </row>
bos@686 395 <row>
bos@686 396 <entry><command>svn cleanup</command></entry>
bos@686 397 <entry>n/a</entry>
bos@686 398 <entry>No cleanup needed</entry>
bos@686 399 </row>
bos@686 400 <row>
bos@686 401 <entry><command>svn commit</command></entry>
bos@686 402 <entry><command>hg commit</command>; <command>hg
bos@686 403 push</command></entry>
bos@686 404 <entry><command>hg push</command> publishes after
bos@686 405 commit</entry>
bos@686 406 </row>
bos@686 407 <row>
bos@686 408 <entry><command>svn copy</command></entry>
bos@686 409 <entry><command>hg clone</command></entry>
bos@686 410 <entry>To create a new branch</entry>
bos@686 411 </row>
bos@686 412 <row>
bos@686 413 <entry><command>svn copy</command></entry>
bos@686 414 <entry><command>hg copy</command></entry>
bos@686 415 <entry>To copy files or directories</entry>
bos@686 416 </row>
bos@686 417 <row>
bos@686 418 <entry><command>svn delete</command> (<command>svn
bos@686 419 remove</command>)</entry>
bos@686 420 <entry><command>hg remove</command></entry>
bos@686 421 <entry></entry>
bos@686 422 </row>
bos@686 423 <row>
bos@686 424 <entry><command>svn diff</command></entry>
bos@686 425 <entry><command>hg diff</command></entry>
bos@686 426 <entry></entry>
bos@686 427 </row>
bos@686 428 <row>
bos@686 429 <entry><command>svn export</command></entry>
bos@686 430 <entry><command>hg archive</command></entry>
bos@686 431 <entry></entry>
bos@686 432 </row>
bos@686 433 <row>
bos@686 434 <entry><command>svn help</command></entry>
bos@686 435 <entry><command>hg help</command></entry>
bos@686 436 <entry></entry>
bos@686 437 </row>
bos@686 438 <row>
bos@686 439 <entry><command>svn import</command></entry>
bos@686 440 <entry><command>hg addremove</command>; <command>hg
bos@686 441 commit</command></entry>
bos@686 442 <entry></entry>
bos@686 443 </row>
bos@686 444 <row>
bos@686 445 <entry><command>svn info</command></entry>
bos@686 446 <entry><command>hg parents</command></entry>
bos@686 447 <entry>Shows what revision is checked out</entry>
bos@686 448 </row>
bos@686 449 <row>
bos@686 450 <entry><command>svn info</command></entry>
bos@686 451 <entry><command>hg showconfig
bos@686 452 paths.parent</command></entry>
bos@686 453 <entry>Shows what URL is checked out</entry>
bos@686 454 </row>
bos@686 455 <row>
bos@686 456 <entry><command>svn list</command></entry>
bos@686 457 <entry><command>hg manifest</command></entry>
bos@686 458 <entry></entry>
bos@686 459 </row>
bos@686 460 <row>
bos@686 461 <entry><command>svn log</command></entry>
bos@686 462 <entry><command>hg log</command></entry>
bos@686 463 <entry></entry>
bos@686 464 </row>
bos@686 465 <row>
bos@686 466 <entry><command>svn merge</command></entry>
bos@686 467 <entry><command>hg merge</command></entry>
bos@686 468 <entry></entry>
bos@686 469 </row>
bos@686 470 <row>
bos@686 471 <entry><command>svn mkdir</command></entry>
bos@686 472 <entry>n/a</entry>
bos@686 473 <entry>Mercurial does not track directories</entry>
bos@686 474 </row>
bos@686 475 <row>
bos@686 476 <entry><command>svn move</command> (<command>svn
bos@686 477 rename</command>)</entry>
bos@686 478 <entry><command>hg rename</command></entry>
bos@686 479 <entry></entry>
bos@686 480 </row>
bos@686 481 <row>
bos@686 482 <entry><command>svn resolved</command></entry>
bos@686 483 <entry><command>hg resolve -m</command></entry>
bos@686 484 <entry></entry>
bos@686 485 </row>
bos@686 486 <row>
bos@686 487 <entry><command>svn revert</command></entry>
bos@686 488 <entry><command>hg revert</command></entry>
bos@686 489 <entry></entry>
bos@686 490 </row>
bos@686 491 <row>
bos@686 492 <entry><command>svn status</command></entry>
bos@686 493 <entry><command>hg status</command></entry>
bos@686 494 <entry></entry>
bos@686 495 </row>
bos@686 496 <row>
bos@686 497 <entry><command>svn update</command></entry>
bos@686 498 <entry><command>hg pull -u</command></entry>
bos@686 499 <entry></entry>
bos@686 500 </row>
bos@686 501 </tbody>
bos@686 502 </tgroup>
bos@686 503 </table>
bos@686 504 </sect2>
bos@686 505 </sect1>
bos@686 506
bos@686 507 <sect1>
bos@686 508 <title>Useful tips for newcomers</title>
bos@686 509
bos@691 510 <para id="x_705">Under some revision control systems, printing a diff for a
bos@686 511 single committed revision can be painful. For instance, with
bos@686 512 Subversion, to see what changed in revision 104654, you must
bos@686 513 type <command>svn diff -r104653:104654</command>. Mercurial
bos@686 514 eliminates the need to type the revision ID twice in this common
bos@686 515 case. For a plain diff, <command>hg export 104654</command>. For
bos@686 516 a log message followed by a diff, <command>hg log -r104654
bos@686 517 -p</command>.</para>
bos@686 518
bos@691 519 <para id="x_706">When you run <command>hg status</command> without any
bos@686 520 arguments, it prints the status of the entire tree, with paths
bos@686 521 relative to the root of the repository. This makes it tricky to
bos@686 522 copy a file name from the output of <command>hg status</command>
bos@686 523 into the command line. If you supply a file or directory name
bos@686 524 to <command>hg status</command>, it will print paths relative to
bos@686 525 your current location instead. So to get tree-wide status from
bos@686 526 <command>hg status</command>, with paths that are relative to
bos@686 527 your current directory and not the root of the repository, feed
bos@686 528 the output of <command>hg root</command> into <command>hg
bos@686 529 status</command>. You can easily do this as follows on a
bos@686 530 Unix-like system:</para>
bos@686 531
bos@686 532 <screen><prompt>$</prompt> <userinput>hg status `hg root`</userinput></screen>
bos@686 533 </sect1>
bos@559 534 </appendix>
bos@559 535
bos@559 536 <!--
bos@559 537 local variables:
bos@559 538 sgml-parent-document: ("00book.xml" "book" "appendix")
bos@559 539 end:
bos@559 540 -->