diff en/appA-svn.xml @ 814:e9154b3daa94

Repurpose appendix A.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/en/appA-svn.xml	Sun Apr 26 23:16:56 2009 -0700
@@ -0,0 +1,441 @@
+<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
+
+<appendix id="svn">
+  <?dbhtml filename="mercurial-for-subversion-users.html"?>
+<title>Migrating to Mercurial</title>
+
+  <para>A common way to test the waters with a new revision control
+    tool is to experiment with switching an existing project, rather
+    than starting a new project from scratch.</para>
+
+  <para>In this appendix, we discuss how to import a project's history
+    into Mercurial, and what to look out for if you are used to a
+    different revision control system.</para>
+
+  <sect1>
+    <title>Importing history from another system</title>
+
+    <para>Mercurial ships with an extension named
+      <literal>convert</literal>, which can import project history
+      from most popular revision control systems.  At the time this
+      book was written, it could import history from the following
+      systems:</para>
+    <itemizedlist>
+      <listitem>
+	<para>Subversion</para>
+      </listitem>
+      <listitem>
+	<para>CVS</para>
+      </listitem>
+      <listitem>
+	<para>git</para>
+      </listitem>
+      <listitem>
+	<para>Darcs</para>
+      </listitem>
+      <listitem>
+	<para>Bazaar</para>
+      </listitem>
+      <listitem>
+	<para>Monotone</para>
+      </listitem>
+      <listitem>
+	<para>GNU Arch</para>
+      </listitem>
+      <listitem>
+	<para>Mercurial</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>(To see why Mercurial itself is supported as a source, see
+      <xref linkend="svn.filemap"/>.)</para>
+
+    <para>You can enable the extension in the usual way, by editing
+      your <filename>~/.hgrc</filename> file.</para>
+
+    <programlisting>[extensions]
+convert =</programlisting>
+
+    <para>This will make a <command>hg convert</command> command
+      available.  The command is easy to use.  For instance, this
+      command will import the Subversion history for the Nose unit
+      testing framework into Mercurial.</para>
+
+    <screen><prompt>$</prompt> <userinput>hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen>
+
+    <para>The <literal>convert</literal> extension operates
+      incrementally.  In other words, after you have run <command>hg
+	convert</command> once, running it again will import any new
+      revisions committed after the first run began.  Incremental
+      conversion will only work if you run <command>hg
+	convert</command> in the same Mercurial repository that you
+      originally used, because the <literal>convert</literal>
+      extension saves some private metadata in a
+      non-revision-controlled file named
+      <filename>.hg/shamap</filename> inside the target
+      repository.</para>
+
+    <sect2>
+      <title>Mapping user names</title>
+
+      <para>Some revision control tools save only short usernames with
+	commits, and these can be difficult to interpret.  The norm
+	with Mercurial is to save a committer's name and email
+	address, which is much more useful for talking to them after
+	the fact.</para>
+
+      <para>If you are converting a tree from a revision control
+	system that uses short names, you can map those names to
+	longer equivalents by passing a <option>--authors</option>
+	option to <command>hg convert</command>.  This option accepts
+	a file name that should contain entries of the following
+	form.</para>
+
+      <programlisting>arist = Aristotle &lt;[e-mail]&gt;
+soc = Socrates &lt;[e-mail]&gt;</programlisting>
+
+      <para>Whenever <literal>convert</literal> encounters a commit
+	with the username <literal>arist</literal> in the source
+	repository, it will use the name <literal>Aristotle
+	  &lt;[e-mail]&gt;</literal> in the converted
+	Mercurial revision.  If no match is found for a name, it is
+	used verbatim.</para>
+    </sect2>
+
+    <sect2 id="svn.filemap">
+      <title>Tidying up the tree</title>
+
+      <para>Not all projects have pristine history.  There may be a
+	directory that should never have been checked in, a file that
+	is too big, or a whole hierarchy that needs to be
+	refactored.</para>
+
+      <para>The <literal>convert</literal> extension supports the idea
+	of a <quote>file map</quote> that can reorganize the files and
+	directories in a project as it imports the project's history.
+	This is useful not only when importing history from other
+	revision control systems, but also to prune or refactor a
+	Mercurial tree.</para>
+
+      <para>To specify a file map, use the <option>--filemap</option>
+	option and supply a file name.  A file map contains lines of the
+	following forms.</para>
+
+      <programlisting># This is a comment.
+# Empty lines are ignored.	
+
+include path/to/file
+
+exclude path/to/file
+
+rename from/some/path to/some/other/place
+</programlisting>
+
+      <para>The <literal>include</literal> directive causes a file, or
+	all files under a directory, to be included in the destination
+	repository.  This also excludes all other files and dirs not
+	explicitely included.  The <literal>exclude</literal>
+	directive causes files or directories to be omitted, and
+	others not explicitly mentioned to be included.</para>
+
+      <para>To move a file or directory from one location to another,
+	use the <literal>rename</literal> directive.  If you need to
+	move a file or directory from a subdirectory into the root of
+	the repository, use <literal>.</literal> as the second
+	argument to the <literal>rename</literal> directive.</para>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Migrating from Subversion</title>
+
+    <para>Subversion is currently the most popular open source
+      revision control system. Although there are many differences
+      between Mercurial and Subversion, making the transition from
+      Subversion to Mercurial is not particularly difficult.  The two
+      have similar command sets and generally uniform
+      interfaces.</para>
+
+    <sect2>
+      <title>Philosophical differences</title>
+
+      <para>The fundamental difference between Subversion and
+	Mercurial is of course that Subversion is centralized, while
+	Mercurial is distributed.  Since Mercurial stores all of a
+	project's history on your local drive, it only needs to
+	perform a network access when you want to explicitly
+	communicate with another repository. In contrast, Subversion
+	stores very little information locally, and the client must
+	thus contact its server for many common operations.</para>
+
+      <para>Subversion more or less gets away without a well-defined
+	notion of a branch: which portion of a server's namespace
+	qualifies as a branch is a matter of convention, with the
+	software providing no enforcement.  Mercurial treats a
+	repository as the unit of branch management.</para>
+
+      <sect3>
+	<title>Scope of commands</title>
+
+	<para>Since Subversion doesn't know what parts of its
+	  namespace are really branches, it treats most commands as
+	  requests to operate at and below whatever directory you are
+	  currently visiting.  For instance, if you run <command>svn
+	    log</command>, you'll get the history of whatever part of
+	  the tree you're looking at, not the tree as a whole.</para>
+
+	<para>Mercurial's commands behave differently, by defaulting
+	  to operating over an entire repository.  Run <command>hg
+	    log</command> and it will tell you the history of the
+	  entire tree, no matter what part of the working directory
+	  you're visiting at the time.  If you want the history of
+	  just a particular file or directory, simply supply it by
+	  name, e.g. <command>hg log src</command>.</para>
+
+	<para>From my own experience, this difference in default
+	  behaviors is probably the most likely to trip you up if you
+	  have to switch back and forth frequently between the two
+	  tools.</para>
+      </sect3>
+
+      <sect3>
+	<title>Multi-user operation and safety</title>
+
+	<para>With Subversion, it is normal (though slightly frowned
+	  upon) for multiple people to collaborate in a single branch.
+	  If Alice and Bob are working together, and Alice commits
+	  some changes to their shared branch, Bob must update his
+	  client's view of the branch before he can commit.  Since at
+	  this time he has no permanent record of the changes he has
+	  made, he can corrupt or lose his modifications during and
+	  after his update.</para>
+
+	<para>Mercurial encourages a commit-then-merge model instead.
+	  Bob commits his changes locally before pulling changes from,
+	  or pushing them to, the server that he shares with Alice.
+	  If Alice pushed her changes before Bob tries to push his, he
+	  will not be able to push his changes until he pulls hers,
+	  merges with them, and commits the result of the merge.  If
+	  he makes a mistake during the merge, he still has the option
+	  of reverting to the commit that recorded his changes.</para>
+
+	<para>It is worth emphasizing that these are the common ways
+	  of working with these tools. Subversion supports a safer
+	  work-in-your-own-branch model, but it is cumbersome enough
+	  in practice to not be widely used.  Mercurial can support
+	  the less safe mode of allowing changes to be pulled in and
+	  merged on top of uncommitted edits, but this is considered
+	  highly unusual.</para>
+      </sect3>
+
+      <sect3>
+	<title>Published vs local changes</title>
+
+	<para>A Subversion <command>svn commit</command> command
+	  immediately publishes changes to a server, where they can be
+	  seen by everyone who has read access.</para>
+
+	<para>With Mercurial, commits are always local, and must be
+	  published via a <command>hg push</command> command
+	  afterwards.</para>
+
+	<para>Each approach has its advantages and disadvantages.  The
+	  Subversion model means that changes are published, and hence
+	  reviewable and usable, immediately.  On the other hand, this
+	  means that a user must have commit access to a repository in
+	  order to use the software in a normal way, and commit access
+	  is not lightly given out by most open source
+	  projects.</para>
+
+	<para>The Mercurial approach allows anyone who can clone a
+	  repository to commit changes without the need for someone
+	  else's permission, and they can then publish their changes
+	  and continue to participate however they see fit.  The
+	  distinction between committing and pushing does open up the
+	  possibility of someone committing changes to their laptop
+	  and walking away for a few days having forgotten to push
+	  them, which in rare cases might leave collaborators
+	  temporarily stuck.</para>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Quick reference</title>
+
+      <table>
+	<title>Subversion commands and Mercurial equivalents</title>
+	<tgroup cols="3">
+	  <thead>
+	    <row>
+	      <entry>Subversion</entry>
+	      <entry>Mercurial</entry>
+	      <entry>Notes</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry><command>svn add</command></entry>
+	      <entry><command>hg add</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn blame</command></entry>
+	      <entry><command>hg annotate</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn cat</command></entry>
+	      <entry><command>hg cat</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn checkout</command></entry>
+	      <entry><command>hg clone</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn cleanup</command></entry>
+	      <entry>n/a</entry>
+	      <entry>No cleanup needed</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn commit</command></entry>
+	      <entry><command>hg commit</command>; <command>hg
+		  push</command></entry>
+	      <entry><command>hg push</command> publishes after
+		commit</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn copy</command></entry>
+	      <entry><command>hg clone</command></entry>
+	      <entry>To create a new branch</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn copy</command></entry>
+	      <entry><command>hg copy</command></entry>
+	      <entry>To copy files or directories</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn delete</command> (<command>svn
+		  remove</command>)</entry>
+	      <entry><command>hg remove</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn diff</command></entry>
+	      <entry><command>hg diff</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn export</command></entry>
+	      <entry><command>hg archive</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn help</command></entry>
+	      <entry><command>hg help</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn import</command></entry>
+	      <entry><command>hg addremove</command>; <command>hg
+		  commit</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn info</command></entry>
+	      <entry><command>hg parents</command></entry>
+	      <entry>Shows what revision is checked out</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn info</command></entry>
+	      <entry><command>hg showconfig
+		  paths.parent</command></entry>
+	      <entry>Shows what URL is checked out</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn list</command></entry>
+	      <entry><command>hg manifest</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn log</command></entry>
+	      <entry><command>hg log</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn merge</command></entry>
+	      <entry><command>hg merge</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn mkdir</command></entry>
+	      <entry>n/a</entry>
+	      <entry>Mercurial does not track directories</entry>
+	    </row>
+	    <row>
+	      <entry><command>svn move</command> (<command>svn
+		  rename</command>)</entry>
+	      <entry><command>hg rename</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn resolved</command></entry>
+	      <entry><command>hg resolve -m</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn revert</command></entry>
+	      <entry><command>hg revert</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn status</command></entry>
+	      <entry><command>hg status</command></entry>
+	      <entry></entry>
+	    </row>
+	    <row>
+	      <entry><command>svn update</command></entry>
+	      <entry><command>hg pull -u</command></entry>
+	      <entry></entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+    </sect2>
+  </sect1>
+
+  <sect1>
+    <title>Useful tips for newcomers</title>
+
+    <para>Under some revision control systems, printing a diff for a
+      single committed revision can be painful. For instance, with
+      Subversion, to see what changed in revision 104654, you must
+      type <command>svn diff -r104653:104654</command>. Mercurial
+      eliminates the need to type the revision ID twice in this common
+      case. For a plain diff, <command>hg export 104654</command>. For
+      a log message followed by a diff, <command>hg log -r104654
+	-p</command>.</para>
+
+    <para>When you run <command>hg status</command> without any
+      arguments, it prints the status of the entire tree, with paths
+      relative to the root of the repository.  This makes it tricky to
+      copy a file name from the output of <command>hg status</command>
+      into the command line.  If you supply a file or directory name
+      to <command>hg status</command>, it will print paths relative to
+      your current location instead.  So to get tree-wide status from
+      <command>hg status</command>, with paths that are relative to
+      your current directory and not the root of the repository, feed
+      the output of <command>hg root</command> into <command>hg
+	status</command>.  You can easily do this as follows on a
+      Unix-like system:</para>
+
+    <screen><prompt>$</prompt> <userinput>hg status `hg root`</userinput></screen>
+  </sect1>
+</appendix>
+
+<!--
+local variables: 
+sgml-parent-document: ("00book.xml" "book" "appendix")
+end:
+-->