1.1 --- a/en/appA-svn.xml	Sun Apr 26 23:24:56 2009 -0700
     1.2 +++ b/en/appA-svn.xml	Tue Apr 28 22:49:50 2009 -0700
     1.3 @@ -75,6 +75,41 @@
     1.4        <filename>.hg/shamap</filename> inside the target
     1.5        repository.</para>
     1.6  
     1.7 +    <para>When you want to start making changes using Mercurial, it's
     1.8 +      best to clone the tree in which you are doing your conversions,
     1.9 +      and leave the original tree for future incremental conversions.
    1.10 +      This is the safest way to let you pull and merge future commits
    1.11 +      from the source revision control system into your newly active
    1.12 +      Mercurial project.</para>
    1.13 +
    1.14 +    <sect2>
    1.15 +      <title>Converting multiple branches</title>
    1.16 +
    1.17 +      <para>The <command>hg convert</command> command given above
    1.18 +	converts only the history of the <literal>trunk</literal>
    1.19 +	branch of the Subversion repository.  If we instead use the
    1.20 +	URL <literal>http://python-nose.googlecode.com/svn</literal>,
    1.21 +	Mercurial will automatically detect the
    1.22 +	<literal>trunk</literal>, <literal>tags</literal> and
    1.23 +	<literal>branches</literal> layout that Subversion projects
    1.24 +	usually use, and it will import each as a separate Mercurial
    1.25 +	branch.</para>
    1.26 +
    1.27 +      <para>By default, each Subversion branch imported into Mercurial
    1.28 +	is given a branch name.  After the conversion completes, you
    1.29 +	can get a list of the active branch names in the Mercurial
    1.30 +	repository using <command>hg branches -a</command>. If you
    1.31 +	would prefer to import the Subversion branches without names,
    1.32 +	pass the <option>--config
    1.33 +	  convert.hg.usebranchnames=false</option> option to
    1.34 +	<command>hg convert</command>.</para>
    1.35 +
    1.36 +      <para>Once you have converted your tree, if you want to follow
    1.37 +	the usual Mercurial practice of working in a tree that
    1.38 +	contains a single branch, you can clone that single branch
    1.39 +	using <command>hg clone -r mybranchname</command>.</para>
    1.40 +    </sect2>
    1.41 +
    1.42      <sect2>
    1.43        <title>Mapping user names</title>
    1.44  
    1.45 @@ -144,6 +179,70 @@
    1.46  	the repository, use <literal>.</literal> as the second
    1.47  	argument to the <literal>rename</literal> directive.</para>
    1.48      </sect2>
    1.49 +
    1.50 +    <sect2>
    1.51 +      <title>Improving Subversion conversion performance</title>
    1.52 +
    1.53 +      <para>You will often need several attempts before you hit the
    1.54 +	perfect combination of user map, file map, and other
    1.55 +	conversion parameters.  Converting a Subversion repository
    1.56 +	over an access protocol like <literal>ssh</literal> or
    1.57 +	<literal>http</literal> can proceed thousands of times more
    1.58 +	slowly than Mercurial is capable of actually operating, due to
    1.59 +	network delays.  This can make tuning that perfect conversion
    1.60 +	recipe very painful.</para>
    1.61 +
    1.62 +      <para>The <ulink
    1.63 +	  url="http://svn.collab.net/repos/svn/trunk/notes/svnsync.txt"><command>svnsync</command></ulink> 
    1.64 +	command can greatly speed up the conversion of a Subversion
    1.65 +	repository.  It is a read-only mirroring program for
    1.66 +	Subversion repositories.  The idea is that you create a local
    1.67 +	mirror of your Subversion tree, then convert the mirror into a
    1.68 +	Mercurial repository.</para>
    1.69 +
    1.70 +      <para>Suppose we want to convert the Subversion repository for
    1.71 +	the popular Memcached project into a Mercurial tree.  First,
    1.72 +	we create a local Subversion repository.</para>
    1.73 +
    1.74 +      <screen><prompt>$</prompt> <userinput>svnadmin create memcached-mirror</userinput></screen>
    1.75 +
    1.76 +      <para>Next, we set up a Subversion hook that
    1.77 +	<command>svnsync</command> needs.</para>
    1.78 +
    1.79 +      <screen><prompt>$</prompt> <userinput>echo '#!/bin/sh' > memcached-mirror/hooks/pre-revprop-change</userinput>
    1.80 +<prompt>$</prompt> <userinput>chmod +x memcached-mirror/hooks/pre-revprop-change</userinput></screen>
    1.81 +
    1.82 +      <para>We then initialize <command>svnsync</command> in this
    1.83 +	repository.</para>
    1.84 +
    1.85 +      <screen><prompt>$</prompt> <userinput>svnsync --init file://`pwd`/memcached-mirror \
    1.86 +  http://code.sixapart.com/svn/memcached</userinput></screen>
    1.87 +
    1.88 +      <para>Our next step is to begin the <command>svnsync</command>
    1.89 +	mirroring process.</para>
    1.90 +
    1.91 +      <screen><prompt>$</prompt> <userinput>svnsync sync file://`pwd`/memcached-mirror</userinput></screen>
    1.92 +
    1.93 +      <para>Finally, we import the history of our local Subversion
    1.94 +	mirror into Mercurial.</para>
    1.95 +
    1.96 +      <screen><prompt>$</prompt> <userinput>hg convert memcached-mirror</userinput></screen>
    1.97 +      
    1.98 +      <para>We can use this process incrementally if the Subversion
    1.99 +	repository is still in use.  We run <command>svnsync</command>
   1.100 +	to pull new changes into our mirror, then <command>hg
   1.101 +	  convert</command> to import them into our Mercurial
   1.102 +	tree.</para>
   1.103 +
   1.104 +      <para>There are two advantages to doing a two-stage import with
   1.105 +	<command>svnsync</command>.  The first is that it uses more
   1.106 +	efficient Subversion network syncing code than <command>hg
   1.107 +	  convert</command>, so it transfers less data over the
   1.108 +	network.  The second is that the import from a local
   1.109 +	Subversion tree is so fast that you can tweak your conversion
   1.110 +	setup repeatedly without having to sit through a painfully
   1.111 +	slow network-based conversion process each time.</para>
   1.112 +    </sect2>
   1.113    </sect1>
   1.114  
   1.115    <sect1>