1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/fr/appA-svn.xml	Sun Aug 16 17:24:16 2009 +0200
     1.3 @@ -0,0 +1,540 @@
     1.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5 +
     1.6 +<appendix id="svn">
     1.7 +  <?dbhtml filename="migrating-to-mercurial.html"?>
     1.8 +<title>Migrating to Mercurial</title>
     1.9 +
    1.10 +  <para id="x_6e1">A common way to test the waters with a new revision control
    1.11 +    tool is to experiment with switching an existing project, rather
    1.12 +    than starting a new project from scratch.</para>
    1.13 +
    1.14 +  <para id="x_6e2">In this appendix, we discuss how to import a project's history
    1.15 +    into Mercurial, and what to look out for if you are used to a
    1.16 +    different revision control system.</para>
    1.17 +
    1.18 +  <sect1>
    1.19 +    <title>Importing history from another system</title>
    1.20 +
    1.21 +    <para id="x_6e3">Mercurial ships with an extension named
    1.22 +      <literal>convert</literal>, which can import project history
    1.23 +      from most popular revision control systems.  At the time this
    1.24 +      book was written, it could import history from the following
    1.25 +      systems:</para>
    1.26 +    <itemizedlist>
    1.27 +      <listitem>
    1.28 +	<para id="x_6e4">Subversion</para>
    1.29 +      </listitem>
    1.30 +      <listitem>
    1.31 +	<para id="x_6e5">CVS</para>
    1.32 +      </listitem>
    1.33 +      <listitem>
    1.34 +	<para id="x_6e6">git</para>
    1.35 +      </listitem>
    1.36 +      <listitem>
    1.37 +	<para id="x_6e7">Darcs</para>
    1.38 +      </listitem>
    1.39 +      <listitem>
    1.40 +	<para id="x_6e8">Bazaar</para>
    1.41 +      </listitem>
    1.42 +      <listitem>
    1.43 +	<para id="x_6e9">Monotone</para>
    1.44 +      </listitem>
    1.45 +      <listitem>
    1.46 +	<para id="x_6ea">GNU Arch</para>
    1.47 +      </listitem>
    1.48 +      <listitem>
    1.49 +	<para id="x_6eb">Mercurial</para>
    1.50 +      </listitem>
    1.51 +    </itemizedlist>
    1.52 +
    1.53 +    <para id="x_6ec">(To see why Mercurial itself is supported as a source, see
    1.54 +      <xref linkend="svn.filemap"/>.)</para>
    1.55 +
    1.56 +    <para id="x_6ed">You can enable the extension in the usual way, by editing
    1.57 +      your <filename>~/.hgrc</filename> file.</para>
    1.58 +
    1.59 +    <programlisting>[extensions]
    1.60 +convert =</programlisting>
    1.61 +
    1.62 +    <para id="x_6ee">This will make a <command>hg convert</command> command
    1.63 +      available.  The command is easy to use.  For instance, this
    1.64 +      command will import the Subversion history for the Nose unit
    1.65 +      testing framework into Mercurial.</para>
    1.66 +
    1.67 +    <screen><prompt>$</prompt> <userinput>hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen>
    1.68 +
    1.69 +    <para id="x_6ef">The <literal>convert</literal> extension operates
    1.70 +      incrementally.  In other words, after you have run <command>hg
    1.71 +	convert</command> once, running it again will import any new
    1.72 +      revisions committed after the first run began.  Incremental
    1.73 +      conversion will only work if you run <command>hg
    1.74 +	convert</command> in the same Mercurial repository that you
    1.75 +      originally used, because the <literal>convert</literal>
    1.76 +      extension saves some private metadata in a
    1.77 +      non-revision-controlled file named
    1.78 +      <filename>.hg/shamap</filename> inside the target
    1.79 +      repository.</para>
    1.80 +
    1.81 +    <para id="x_707">When you want to start making changes using Mercurial, it's
    1.82 +      best to clone the tree in which you are doing your conversions,
    1.83 +      and leave the original tree for future incremental conversions.
    1.84 +      This is the safest way to let you pull and merge future commits
    1.85 +      from the source revision control system into your newly active
    1.86 +      Mercurial project.</para>
    1.87 +
    1.88 +    <sect2>
    1.89 +      <title>Converting multiple branches</title>
    1.90 +
    1.91 +      <para id="x_708">The <command>hg convert</command> command given above
    1.92 +	converts only the history of the <literal>trunk</literal>
    1.93 +	branch of the Subversion repository.  If we instead use the
    1.94 +	URL <literal>http://python-nose.googlecode.com/svn</literal>,
    1.95 +	Mercurial will automatically detect the
    1.96 +	<literal>trunk</literal>, <literal>tags</literal> and
    1.97 +	<literal>branches</literal> layout that Subversion projects
    1.98 +	usually use, and it will import each as a separate Mercurial
    1.99 +	branch.</para>
   1.100 +
   1.101 +      <para id="x_709">By default, each Subversion branch imported into Mercurial
   1.102 +	is given a branch name.  After the conversion completes, you
   1.103 +	can get a list of the active branch names in the Mercurial
   1.104 +	repository using <command>hg branches -a</command>. If you
   1.105 +	would prefer to import the Subversion branches without names,
   1.106 +	pass the <option>--config
   1.107 +	  convert.hg.usebranchnames=false</option> option to
   1.108 +	<command>hg convert</command>.</para>
   1.109 +
   1.110 +      <para id="x_70a">Once you have converted your tree, if you want to follow
   1.111 +	the usual Mercurial practice of working in a tree that
   1.112 +	contains a single branch, you can clone that single branch
   1.113 +	using <command>hg clone -r mybranchname</command>.</para>
   1.114 +    </sect2>
   1.115 +
   1.116 +    <sect2>
   1.117 +      <title>Mapping user names</title>
   1.118 +
   1.119 +      <para id="x_6f0">Some revision control tools save only short usernames with
   1.120 +	commits, and these can be difficult to interpret.  The norm
   1.121 +	with Mercurial is to save a committer's name and email
   1.122 +	address, which is much more useful for talking to them after
   1.123 +	the fact.</para>
   1.124 +
   1.125 +      <para id="x_6f1">If you are converting a tree from a revision control
   1.126 +	system that uses short names, you can map those names to
   1.127 +	longer equivalents by passing a <option>--authors</option>
   1.128 +	option to <command>hg convert</command>.  This option accepts
   1.129 +	a file name that should contain entries of the following
   1.130 +	form.</para>
   1.131 +
   1.132 +      <programlisting>arist = Aristotle &lt;aristotle@phil.example.gr&gt;
   1.133 +soc = Socrates &lt;socrates@phil.example.gr&gt;</programlisting>
   1.134 +
   1.135 +      <para id="x_6f2">Whenever <literal>convert</literal> encounters a commit
   1.136 +	with the username <literal>arist</literal> in the source
   1.137 +	repository, it will use the name <literal>Aristotle
   1.138 +	  &lt;aristotle@phil.example.gr&gt;</literal> in the converted
   1.139 +	Mercurial revision.  If no match is found for a name, it is
   1.140 +	used verbatim.</para>
   1.141 +    </sect2>
   1.142 +
   1.143 +    <sect2 id="svn.filemap">
   1.144 +      <title>Tidying up the tree</title>
   1.145 +
   1.146 +      <para id="x_6f3">Not all projects have pristine history.  There may be a
   1.147 +	directory that should never have been checked in, a file that
   1.148 +	is too big, or a whole hierarchy that needs to be
   1.149 +	refactored.</para>
   1.150 +
   1.151 +      <para id="x_6f4">The <literal>convert</literal> extension supports the idea
   1.152 +	of a <quote>file map</quote> that can reorganize the files and
   1.153 +	directories in a project as it imports the project's history.
   1.154 +	This is useful not only when importing history from other
   1.155 +	revision control systems, but also to prune or refactor a
   1.156 +	Mercurial tree.</para>
   1.157 +
   1.158 +      <para id="x_6f5">To specify a file map, use the <option>--filemap</option>
   1.159 +	option and supply a file name.  A file map contains lines of the
   1.160 +	following forms.</para>
   1.161 +
   1.162 +      <programlisting># This is a comment.
   1.163 +# Empty lines are ignored.	
   1.164 +
   1.165 +include path/to/file
   1.166 +
   1.167 +exclude path/to/file
   1.168 +
   1.169 +rename from/some/path to/some/other/place
   1.170 +</programlisting>
   1.171 +
   1.172 +      <para id="x_6f6">The <literal>include</literal> directive causes a file, or
   1.173 +	all files under a directory, to be included in the destination
   1.174 +	repository.  This also excludes all other files and dirs not
   1.175 +	explicitely included.  The <literal>exclude</literal>
   1.176 +	directive causes files or directories to be omitted, and
   1.177 +	others not explicitly mentioned to be included.</para>
   1.178 +
   1.179 +      <para id="x_6f7">To move a file or directory from one location to another,
   1.180 +	use the <literal>rename</literal> directive.  If you need to
   1.181 +	move a file or directory from a subdirectory into the root of
   1.182 +	the repository, use <literal>.</literal> as the second
   1.183 +	argument to the <literal>rename</literal> directive.</para>
   1.184 +    </sect2>
   1.185 +
   1.186 +    <sect2>
   1.187 +      <title>Improving Subversion conversion performance</title>
   1.188 +
   1.189 +      <para id="x_70b">You will often need several attempts before you hit the
   1.190 +	perfect combination of user map, file map, and other
   1.191 +	conversion parameters.  Converting a Subversion repository
   1.192 +	over an access protocol like <literal>ssh</literal> or
   1.193 +	<literal>http</literal> can proceed thousands of times more
   1.194 +	slowly than Mercurial is capable of actually operating, due to
   1.195 +	network delays.  This can make tuning that perfect conversion
   1.196 +	recipe very painful.</para>
   1.197 +
   1.198 +      <para id="x_70c">The <ulink
   1.199 +	  url="http://svn.collab.net/repos/svn/trunk/notes/svnsync.txt"><command>svnsync</command></ulink> 
   1.200 +	command can greatly speed up the conversion of a Subversion
   1.201 +	repository.  It is a read-only mirroring program for
   1.202 +	Subversion repositories.  The idea is that you create a local
   1.203 +	mirror of your Subversion tree, then convert the mirror into a
   1.204 +	Mercurial repository.</para>
   1.205 +
   1.206 +      <para id="x_70d">Suppose we want to convert the Subversion repository for
   1.207 +	the popular Memcached project into a Mercurial tree.  First,
   1.208 +	we create a local Subversion repository.</para>
   1.209 +
   1.210 +      <screen><prompt>$</prompt> <userinput>svnadmin create memcached-mirror</userinput></screen>
   1.211 +
   1.212 +      <para id="x_70e">Next, we set up a Subversion hook that
   1.213 +	<command>svnsync</command> needs.</para>
   1.214 +
   1.215 +      <screen><prompt>$</prompt> <userinput>echo '#!/bin/sh' > memcached-mirror/hooks/pre-revprop-change</userinput>
   1.216 +<prompt>$</prompt> <userinput>chmod +x memcached-mirror/hooks/pre-revprop-change</userinput></screen>
   1.217 +
   1.218 +      <para id="x_70f">We then initialize <command>svnsync</command> in this
   1.219 +	repository.</para>
   1.220 +
   1.221 +      <screen><prompt>$</prompt> <userinput>svnsync --init file://`pwd`/memcached-mirror \
   1.222 +  http://code.sixapart.com/svn/memcached</userinput></screen>
   1.223 +
   1.224 +      <para id="x_710">Our next step is to begin the <command>svnsync</command>
   1.225 +	mirroring process.</para>
   1.226 +
   1.227 +      <screen><prompt>$</prompt> <userinput>svnsync sync file://`pwd`/memcached-mirror</userinput></screen>
   1.228 +
   1.229 +      <para id="x_711">Finally, we import the history of our local Subversion
   1.230 +	mirror into Mercurial.</para>
   1.231 +
   1.232 +      <screen><prompt>$</prompt> <userinput>hg convert memcached-mirror</userinput></screen>
   1.233 +      
   1.234 +      <para id="x_712">We can use this process incrementally if the Subversion
   1.235 +	repository is still in use.  We run <command>svnsync</command>
   1.236 +	to pull new changes into our mirror, then <command>hg
   1.237 +	  convert</command> to import them into our Mercurial
   1.238 +	tree.</para>
   1.239 +
   1.240 +      <para id="x_713">There are two advantages to doing a two-stage import with
   1.241 +	<command>svnsync</command>.  The first is that it uses more
   1.242 +	efficient Subversion network syncing code than <command>hg
   1.243 +	  convert</command>, so it transfers less data over the
   1.244 +	network.  The second is that the import from a local
   1.245 +	Subversion tree is so fast that you can tweak your conversion
   1.246 +	setup repeatedly without having to sit through a painfully
   1.247 +	slow network-based conversion process each time.</para>
   1.248 +    </sect2>
   1.249 +  </sect1>
   1.250 +
   1.251 +  <sect1>
   1.252 +    <title>Migrating from Subversion</title>
   1.253 +
   1.254 +    <para id="x_6f8">Subversion is currently the most popular open source
   1.255 +      revision control system. Although there are many differences
   1.256 +      between Mercurial and Subversion, making the transition from
   1.257 +      Subversion to Mercurial is not particularly difficult.  The two
   1.258 +      have similar command sets and generally uniform
   1.259 +      interfaces.</para>
   1.260 +
   1.261 +    <sect2>
   1.262 +      <title>Philosophical differences</title>
   1.263 +
   1.264 +      <para id="x_6f9">The fundamental difference between Subversion and
   1.265 +	Mercurial is of course that Subversion is centralized, while
   1.266 +	Mercurial is distributed.  Since Mercurial stores all of a
   1.267 +	project's history on your local drive, it only needs to
   1.268 +	perform a network access when you want to explicitly
   1.269 +	communicate with another repository. In contrast, Subversion
   1.270 +	stores very little information locally, and the client must
   1.271 +	thus contact its server for many common operations.</para>
   1.272 +
   1.273 +      <para id="x_6fa">Subversion more or less gets away without a well-defined
   1.274 +	notion of a branch: which portion of a server's namespace
   1.275 +	qualifies as a branch is a matter of convention, with the
   1.276 +	software providing no enforcement.  Mercurial treats a
   1.277 +	repository as the unit of branch management.</para>
   1.278 +
   1.279 +      <sect3>
   1.280 +	<title>Scope of commands</title>
   1.281 +
   1.282 +	<para id="x_6fb">Since Subversion doesn't know what parts of its
   1.283 +	  namespace are really branches, it treats most commands as
   1.284 +	  requests to operate at and below whatever directory you are
   1.285 +	  currently visiting.  For instance, if you run <command>svn
   1.286 +	    log</command>, you'll get the history of whatever part of
   1.287 +	  the tree you're looking at, not the tree as a whole.</para>
   1.288 +
   1.289 +	<para id="x_6fc">Mercurial's commands behave differently, by defaulting
   1.290 +	  to operating over an entire repository.  Run <command>hg
   1.291 +	    log</command> and it will tell you the history of the
   1.292 +	  entire tree, no matter what part of the working directory
   1.293 +	  you're visiting at the time.  If you want the history of
   1.294 +	  just a particular file or directory, simply supply it by
   1.295 +	  name, e.g. <command>hg log src</command>.</para>
   1.296 +
   1.297 +	<para id="x_6fd">From my own experience, this difference in default
   1.298 +	  behaviors is probably the most likely to trip you up if you
   1.299 +	  have to switch back and forth frequently between the two
   1.300 +	  tools.</para>
   1.301 +      </sect3>
   1.302 +
   1.303 +      <sect3>
   1.304 +	<title>Multi-user operation and safety</title>
   1.305 +
   1.306 +	<para id="x_6fe">With Subversion, it is normal (though slightly frowned
   1.307 +	  upon) for multiple people to collaborate in a single branch.
   1.308 +	  If Alice and Bob are working together, and Alice commits
   1.309 +	  some changes to their shared branch, Bob must update his
   1.310 +	  client's view of the branch before he can commit.  Since at
   1.311 +	  this time he has no permanent record of the changes he has
   1.312 +	  made, he can corrupt or lose his modifications during and
   1.313 +	  after his update.</para>
   1.314 +
   1.315 +	<para id="x_6ff">Mercurial encourages a commit-then-merge model instead.
   1.316 +	  Bob commits his changes locally before pulling changes from,
   1.317 +	  or pushing them to, the server that he shares with Alice.
   1.318 +	  If Alice pushed her changes before Bob tries to push his, he
   1.319 +	  will not be able to push his changes until he pulls hers,
   1.320 +	  merges with them, and commits the result of the merge.  If
   1.321 +	  he makes a mistake during the merge, he still has the option
   1.322 +	  of reverting to the commit that recorded his changes.</para>
   1.323 +
   1.324 +	<para id="x_700">It is worth emphasizing that these are the common ways
   1.325 +	  of working with these tools. Subversion supports a safer
   1.326 +	  work-in-your-own-branch model, but it is cumbersome enough
   1.327 +	  in practice to not be widely used.  Mercurial can support
   1.328 +	  the less safe mode of allowing changes to be pulled in and
   1.329 +	  merged on top of uncommitted edits, but this is considered
   1.330 +	  highly unusual.</para>
   1.331 +      </sect3>
   1.332 +
   1.333 +      <sect3>
   1.334 +	<title>Published vs local changes</title>
   1.335 +
   1.336 +	<para id="x_701">A Subversion <command>svn commit</command> command
   1.337 +	  immediately publishes changes to a server, where they can be
   1.338 +	  seen by everyone who has read access.</para>
   1.339 +
   1.340 +	<para id="x_702">With Mercurial, commits are always local, and must be
   1.341 +	  published via a <command>hg push</command> command
   1.342 +	  afterwards.</para>
   1.343 +
   1.344 +	<para id="x_703">Each approach has its advantages and disadvantages.  The
   1.345 +	  Subversion model means that changes are published, and hence
   1.346 +	  reviewable and usable, immediately.  On the other hand, this
   1.347 +	  means that a user must have commit access to a repository in
   1.348 +	  order to use the software in a normal way, and commit access
   1.349 +	  is not lightly given out by most open source
   1.350 +	  projects.</para>
   1.351 +
   1.352 +	<para id="x_704">The Mercurial approach allows anyone who can clone a
   1.353 +	  repository to commit changes without the need for someone
   1.354 +	  else's permission, and they can then publish their changes
   1.355 +	  and continue to participate however they see fit.  The
   1.356 +	  distinction between committing and pushing does open up the
   1.357 +	  possibility of someone committing changes to their laptop
   1.358 +	  and walking away for a few days having forgotten to push
   1.359 +	  them, which in rare cases might leave collaborators
   1.360 +	  temporarily stuck.</para>
   1.361 +      </sect3>
   1.362 +    </sect2>
   1.363 +
   1.364 +    <sect2>
   1.365 +      <title>Quick reference</title>
   1.366 +
   1.367 +      <table>
   1.368 +	<title>Subversion commands and Mercurial equivalents</title>
   1.369 +	<tgroup cols="3">
   1.370 +	  <thead>
   1.371 +	    <row>
   1.372 +	      <entry>Subversion</entry>
   1.373 +	      <entry>Mercurial</entry>
   1.374 +	      <entry>Notes</entry>
   1.375 +	    </row>
   1.376 +	  </thead>
   1.377 +	  <tbody>
   1.378 +	    <row>
   1.379 +	      <entry><command>svn add</command></entry>
   1.380 +	      <entry><command>hg add</command></entry>
   1.381 +	      <entry></entry>
   1.382 +	    </row>
   1.383 +	    <row>
   1.384 +	      <entry><command>svn blame</command></entry>
   1.385 +	      <entry><command>hg annotate</command></entry>
   1.386 +	      <entry></entry>
   1.387 +	    </row>
   1.388 +	    <row>
   1.389 +	      <entry><command>svn cat</command></entry>
   1.390 +	      <entry><command>hg cat</command></entry>
   1.391 +	      <entry></entry>
   1.392 +	    </row>
   1.393 +	    <row>
   1.394 +	      <entry><command>svn checkout</command></entry>
   1.395 +	      <entry><command>hg clone</command></entry>
   1.396 +	      <entry></entry>
   1.397 +	    </row>
   1.398 +	    <row>
   1.399 +	      <entry><command>svn cleanup</command></entry>
   1.400 +	      <entry>n/a</entry>
   1.401 +	      <entry>No cleanup needed</entry>
   1.402 +	    </row>
   1.403 +	    <row>
   1.404 +	      <entry><command>svn commit</command></entry>
   1.405 +	      <entry><command>hg commit</command>; <command>hg
   1.406 +		  push</command></entry>
   1.407 +	      <entry><command>hg push</command> publishes after
   1.408 +		commit</entry>
   1.409 +	    </row>
   1.410 +	    <row>
   1.411 +	      <entry><command>svn copy</command></entry>
   1.412 +	      <entry><command>hg clone</command></entry>
   1.413 +	      <entry>To create a new branch</entry>
   1.414 +	    </row>
   1.415 +	    <row>
   1.416 +	      <entry><command>svn copy</command></entry>
   1.417 +	      <entry><command>hg copy</command></entry>
   1.418 +	      <entry>To copy files or directories</entry>
   1.419 +	    </row>
   1.420 +	    <row>
   1.421 +	      <entry><command>svn delete</command> (<command>svn
   1.422 +		  remove</command>)</entry>
   1.423 +	      <entry><command>hg remove</command></entry>
   1.424 +	      <entry></entry>
   1.425 +	    </row>
   1.426 +	    <row>
   1.427 +	      <entry><command>svn diff</command></entry>
   1.428 +	      <entry><command>hg diff</command></entry>
   1.429 +	      <entry></entry>
   1.430 +	    </row>
   1.431 +	    <row>
   1.432 +	      <entry><command>svn export</command></entry>
   1.433 +	      <entry><command>hg archive</command></entry>
   1.434 +	      <entry></entry>
   1.435 +	    </row>
   1.436 +	    <row>
   1.437 +	      <entry><command>svn help</command></entry>
   1.438 +	      <entry><command>hg help</command></entry>
   1.439 +	      <entry></entry>
   1.440 +	    </row>
   1.441 +	    <row>
   1.442 +	      <entry><command>svn import</command></entry>
   1.443 +	      <entry><command>hg addremove</command>; <command>hg
   1.444 +		  commit</command></entry>
   1.445 +	      <entry></entry>
   1.446 +	    </row>
   1.447 +	    <row>
   1.448 +	      <entry><command>svn info</command></entry>
   1.449 +	      <entry><command>hg parents</command></entry>
   1.450 +	      <entry>Shows what revision is checked out</entry>
   1.451 +	    </row>
   1.452 +	    <row>
   1.453 +	      <entry><command>svn info</command></entry>
   1.454 +	      <entry><command>hg showconfig
   1.455 +		  paths.parent</command></entry>
   1.456 +	      <entry>Shows what URL is checked out</entry>
   1.457 +	    </row>
   1.458 +	    <row>
   1.459 +	      <entry><command>svn list</command></entry>
   1.460 +	      <entry><command>hg manifest</command></entry>
   1.461 +	      <entry></entry>
   1.462 +	    </row>
   1.463 +	    <row>
   1.464 +	      <entry><command>svn log</command></entry>
   1.465 +	      <entry><command>hg log</command></entry>
   1.466 +	      <entry></entry>
   1.467 +	    </row>
   1.468 +	    <row>
   1.469 +	      <entry><command>svn merge</command></entry>
   1.470 +	      <entry><command>hg merge</command></entry>
   1.471 +	      <entry></entry>
   1.472 +	    </row>
   1.473 +	    <row>
   1.474 +	      <entry><command>svn mkdir</command></entry>
   1.475 +	      <entry>n/a</entry>
   1.476 +	      <entry>Mercurial does not track directories</entry>
   1.477 +	    </row>
   1.478 +	    <row>
   1.479 +	      <entry><command>svn move</command> (<command>svn
   1.480 +		  rename</command>)</entry>
   1.481 +	      <entry><command>hg rename</command></entry>
   1.482 +	      <entry></entry>
   1.483 +	    </row>
   1.484 +	    <row>
   1.485 +	      <entry><command>svn resolved</command></entry>
   1.486 +	      <entry><command>hg resolve -m</command></entry>
   1.487 +	      <entry></entry>
   1.488 +	    </row>
   1.489 +	    <row>
   1.490 +	      <entry><command>svn revert</command></entry>
   1.491 +	      <entry><command>hg revert</command></entry>
   1.492 +	      <entry></entry>
   1.493 +	    </row>
   1.494 +	    <row>
   1.495 +	      <entry><command>svn status</command></entry>
   1.496 +	      <entry><command>hg status</command></entry>
   1.497 +	      <entry></entry>
   1.498 +	    </row>
   1.499 +	    <row>
   1.500 +	      <entry><command>svn update</command></entry>
   1.501 +	      <entry><command>hg pull -u</command></entry>
   1.502 +	      <entry></entry>
   1.503 +	    </row>
   1.504 +	  </tbody>
   1.505 +	</tgroup>
   1.506 +      </table>
   1.507 +    </sect2>
   1.508 +  </sect1>
   1.509 +
   1.510 +  <sect1>
   1.511 +    <title>Useful tips for newcomers</title>
   1.512 +
   1.513 +    <para id="x_705">Under some revision control systems, printing a diff for a
   1.514 +      single committed revision can be painful. For instance, with
   1.515 +      Subversion, to see what changed in revision 104654, you must
   1.516 +      type <command>svn diff -r104653:104654</command>. Mercurial
   1.517 +      eliminates the need to type the revision ID twice in this common
   1.518 +      case. For a plain diff, <command>hg export 104654</command>. For
   1.519 +      a log message followed by a diff, <command>hg log -r104654
   1.520 +	-p</command>.</para>
   1.521 +
   1.522 +    <para id="x_706">When you run <command>hg status</command> without any
   1.523 +      arguments, it prints the status of the entire tree, with paths
   1.524 +      relative to the root of the repository.  This makes it tricky to
   1.525 +      copy a file name from the output of <command>hg status</command>
   1.526 +      into the command line.  If you supply a file or directory name
   1.527 +      to <command>hg status</command>, it will print paths relative to
   1.528 +      your current location instead.  So to get tree-wide status from
   1.529 +      <command>hg status</command>, with paths that are relative to
   1.530 +      your current directory and not the root of the repository, feed
   1.531 +      the output of <command>hg root</command> into <command>hg
   1.532 +	status</command>.  You can easily do this as follows on a
   1.533 +      Unix-like system:</para>
   1.534 +
   1.535 +    <screen><prompt>$</prompt> <userinput>hg status `hg root`</userinput></screen>
   1.536 +  </sect1>
   1.537 +</appendix>
   1.538 +
   1.539 +<!--
   1.540 +local variables: 
   1.541 +sgml-parent-document: ("00book.xml" "book" "appendix")
   1.542 +end:
   1.543 +-->