1.1 --- a/en/00book.xml	Fri Apr 24 00:31:21 2009 -0700
     1.2 +++ b/en/00book.xml	Sun Apr 26 23:16:56 2009 -0700
     1.3 @@ -21,7 +21,7 @@
     1.4  <!ENTITY ch11     SYSTEM "ch11-mq.xml">
     1.5  <!ENTITY ch12     SYSTEM "ch12-mq-collab.xml">
     1.6  <!ENTITY ch13     SYSTEM "ch13-hgext.xml">
     1.7 -<!ENTITY appA     SYSTEM "appA-cmdref.xml">
     1.8 +<!ENTITY appA     SYSTEM "appA-svn.xml">
     1.9  <!ENTITY appB     SYSTEM "appB-mq-ref.xml">
    1.10  <!ENTITY appC     SYSTEM "appC-srcinstall.xml">
    1.11  <!ENTITY appD     SYSTEM "appD-license.xml">
    1.12 @@ -96,6 +96,8 @@
    1.13    &ch12;
    1.14    <!-- BEGIN ch13 -->
    1.15    &ch13;
    1.16 +  <!-- BEGIN appA -->
    1.17 +  &appA;
    1.18    <!-- BEGIN appB -->
    1.19    &appB;
    1.20    <!-- BEGIN appC -->

     2.1 --- a/en/appA-cmdref.xml	Fri Apr 24 00:31:21 2009 -0700
     2.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.3 @@ -1,224 +0,0 @@
     2.4 -<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     2.5 -
     2.6 -<appendix id="cmdref">
     2.7 -  <?dbhtml filename="command-reference.html"?>
     2.8 -<title>Command reference</title>
     2.9 -
    2.10 -<para id="x_653">\cmdref{add}{add files at the next commit}
    2.11 -\optref{add}{I}{include}
    2.12 -\optref{add}{X}{exclude}
    2.13 -\optref{add}{n}{dry-run}</para>
    2.14 -
    2.15 -<para id="x_654">\cmdref{diff}{print changes in history or working directory}</para>
    2.16 -
    2.17 -<para id="x_655">Show differences between revisions for the specified files or
    2.18 -directories, using the unified diff format.  For a description of the
    2.19 -unified diff format, see <xref linkend="sec:mq:patch"/>.</para>
    2.20 -
    2.21 -<para id="x_656">By default, this command does not print diffs for files that Mercurial
    2.22 -considers to contain binary data.  To control this behavior, see the
    2.23 -<option role="hg-opt-diff">-a</option> and <option role="hg-opt-diff">--git</option> options.</para>
    2.24 -
    2.25 -<sect2>
    2.26 -<title>Options</title>
    2.27 -x
    2.28 -<para id="x_657">\loptref{diff}{nodates}</para>
    2.29 -
    2.30 -<para id="x_658">Omit date and time information when printing diff headers.</para>
    2.31 -
    2.32 -<para id="x_659">\optref{diff}{B}{ignore-blank-lines}</para>
    2.33 -
    2.34 -<para id="x_65a">Do not print changes that only insert or delete blank lines.  A line
    2.35 -that contains only whitespace is not considered blank.
    2.36 -</para>
    2.37 -
    2.38 -<para id="x_65b">\optref{diff}{I}{include}
    2.39 -</para>
    2.40 -
    2.41 -<para id="x_65c">Include files and directories whose names match the given patterns.
    2.42 -</para>
    2.43 -
    2.44 -<para id="x_65d">\optref{diff}{X}{exclude}
    2.45 -</para>
    2.46 -
    2.47 -<para id="x_65e">Exclude files and directories whose names match the given patterns.
    2.48 -</para>
    2.49 -
    2.50 -<para id="x_65f">\optref{diff}{a}{text}
    2.51 -</para>
    2.52 -
    2.53 -<para id="x_660">If this option is not specified, <command role="hg-cmd">hg diff</command> will refuse to print
    2.54 -diffs for files that it detects as binary. Specifying <option role="hg-opt-diff">-a</option>
    2.55 -forces <command role="hg-cmd">hg diff</command> to treat all files as text, and generate diffs for
    2.56 -all of them.
    2.57 -</para>
    2.58 -
    2.59 -<para id="x_661">This option is useful for files that are <quote>mostly text</quote> but have a
    2.60 -few embedded NUL characters.  If you use it on files that contain a
    2.61 -lot of binary data, its output will be incomprehensible.
    2.62 -</para>
    2.63 -
    2.64 -<para id="x_662">\optref{diff}{b}{ignore-space-change}
    2.65 -</para>
    2.66 -
    2.67 -<para id="x_663">Do not print a line if the only change to that line is in the amount
    2.68 -of white space it contains.
    2.69 -</para>
    2.70 -
    2.71 -<para id="x_664">\optref{diff}{g}{git}
    2.72 -</para>
    2.73 -
    2.74 -<para id="x_665">Print <command>git</command>-compatible diffs.  XXX reference a format
    2.75 -description.
    2.76 -</para>
    2.77 -
    2.78 -<para id="x_666">\optref{diff}{p}{show-function}
    2.79 -</para>
    2.80 -
    2.81 -<para id="x_667">Display the name of the enclosing function in a hunk header, using a
    2.82 -simple heuristic.  This functionality is enabled by default, so the
    2.83 -<option role="hg-opt-diff">-p</option> option has no effect unless you change the value of
    2.84 -the <envar role="rc-item-diff">showfunc</envar> config item, as in the following example.</para>
    2.85 -
    2.86 -<!-- &interaction.cmdref.diff-p; -->
    2.87 -
    2.88 -<para id="x_668">\optref{diff}{r}{rev}
    2.89 -</para>
    2.90 -
    2.91 -<para id="x_669">Specify one or more revisions to compare.  The <command role="hg-cmd">hg diff</command> command
    2.92 -accepts up to two <option role="hg-opt-diff">-r</option> options to specify the revisions to
    2.93 -compare.
    2.94 -</para>
    2.95 -
    2.96 -<orderedlist>
    2.97 -<listitem><para id="x_66a">Display the differences between the parent revision of the
    2.98 -  working directory and the working directory.
    2.99 -</para>
   2.100 -</listitem>
   2.101 -<listitem><para id="x_66b">Display the differences between the specified changeset and the
   2.102 -  working directory.
   2.103 -</para>
   2.104 -</listitem>
   2.105 -<listitem><para id="x_66c">Display the differences between the two specified changesets.
   2.106 -</para>
   2.107 -</listitem></orderedlist>
   2.108 -
   2.109 -<para id="x_66d">You can specify two revisions using either two <option role="hg-opt-diff">-r</option>
   2.110 -options or revision range notation.  For example, the two revision
   2.111 -specifications below are equivalent.
   2.112 -</para>
   2.113 -<programlisting>hg diff -r 10 -r 20
   2.114 -hg diff -r10:20</programlisting>
   2.115 -
   2.116 -<para id="x_66e">When you provide two revisions, Mercurial treats the order of those
   2.117 -revisions as significant.  Thus, <command role="hg-cmd">hg diff -r10:20</command> will
   2.118 -produce a diff that will transform files from their contents as of
   2.119 -revision 10 to their contents as of revision 20, while
   2.120 -<command role="hg-cmd">hg diff -r20:10</command> means the opposite: the diff that will
   2.121 -transform files from their revision 20 contents to their revision 10
   2.122 -contents.  You cannot reverse the ordering in this way if you are
   2.123 -diffing against the working directory.
   2.124 -</para>
   2.125 -
   2.126 -<para id="x_66f">\optref{diff}{w}{ignore-all-space}
   2.127 -</para>
   2.128 -
   2.129 -<para id="x_670">\cmdref{version}{print version and copyright information}
   2.130 -</para>
   2.131 -
   2.132 -<para id="x_671">This command displays the version of Mercurial you are running, and
   2.133 -its copyright license.  There are four kinds of version string that
   2.134 -you may see.
   2.135 -</para>
   2.136 -<itemizedlist>
   2.137 -<listitem><para id="x_672">The string <quote><literal>unknown</literal></quote>. This version of Mercurial was
   2.138 -  not built in a Mercurial repository, and cannot determine its own
   2.139 -  version.
   2.140 -</para>
   2.141 -</listitem>
   2.142 -<listitem><para id="x_673">A short numeric string, such as <quote><literal>1.1</literal></quote>. This is a
   2.143 -  build of a revision of Mercurial that was identified by a specific
   2.144 -  tag in the repository where it was built.  (This doesn't necessarily
   2.145 -  mean that you're running an official release; someone else could
   2.146 -  have added that tag to any revision in the repository where they
   2.147 -  built Mercurial.)
   2.148 -</para>
   2.149 -</listitem>
   2.150 -<listitem><para id="x_674">A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>.  This
   2.151 -  is a build of the given revision of Mercurial.
   2.152 -</para>
   2.153 -</listitem>
   2.154 -<listitem><para id="x_675">A hexadecimal string followed by a date, such as
   2.155 -  <quote><literal>875489e31abe+20070205</literal></quote>.  This is a build of the given
   2.156 -  revision of Mercurial, where the build repository contained some
   2.157 -  local changes that had not been committed.
   2.158 -</para>
   2.159 -</listitem></itemizedlist>
   2.160 -
   2.161 -</sect2>
   2.162 -<sect2>
   2.163 -<title>Tips and tricks</title>
   2.164 -
   2.165 -<sect3 id="cmdref:diff-vs-status">
   2.166 -<title>Why do the results of <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg status</command> differ?</title>
   2.167 -
   2.168 -<para id="x_676">When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files
   2.169 -that Mercurial will record changes for the next time you perform a
   2.170 -commit.  If you run the <command role="hg-cmd">hg diff</command> command, you may notice that it
   2.171 -prints diffs for only a <emphasis>subset</emphasis> of the files that <command role="hg-cmd">hg status</command>
   2.172 -listed.  There are two possible reasons for this.
   2.173 -</para>
   2.174 -
   2.175 -<para id="x_677">The first is that <command role="hg-cmd">hg status</command> prints some kinds of modifications
   2.176 -that <command role="hg-cmd">hg diff</command> doesn't normally display.  The <command role="hg-cmd">hg diff</command> command
   2.177 -normally outputs unified diffs, which don't have the ability to
   2.178 -represent some changes that Mercurial can track.  Most notably,
   2.179 -traditional diffs can't represent a change in whether or not a file is
   2.180 -executable, but Mercurial records this information.
   2.181 -</para>
   2.182 -
   2.183 -<para id="x_678">If you use the <option role="hg-opt-diff">--git</option> option to <command role="hg-cmd">hg diff</command>, it will
   2.184 -display <command>git</command>-compatible diffs that <emphasis>can</emphasis> display this
   2.185 -extra information.
   2.186 -</para>
   2.187 -
   2.188 -<para id="x_679">The second possible reason that <command role="hg-cmd">hg diff</command> might be printing diffs
   2.189 -for a subset of the files displayed by <command role="hg-cmd">hg status</command> is that if you
   2.190 -invoke it without any arguments, <command role="hg-cmd">hg diff</command> prints diffs against the
   2.191 -first parent of the working directory.  If you have run <command role="hg-cmd">hg merge</command>
   2.192 -to merge two changesets, but you haven't yet committed the results of
   2.193 -the merge, your working directory has two parents (use <command role="hg-cmd">hg parents</command>
   2.194 -to see them).  While <command role="hg-cmd">hg status</command> prints modifications relative to
   2.195 -<emphasis>both</emphasis> parents after an uncommitted merge, <command role="hg-cmd">hg diff</command> still
   2.196 -operates relative only to the first parent.  You can get it to print
   2.197 -diffs relative to the second parent by specifying that parent with the
   2.198 -<option role="hg-opt-diff">-r</option> option.  There is no way to print diffs relative to
   2.199 -both parents.
   2.200 -</para>
   2.201 -
   2.202 -</sect3>
   2.203 -<sect3>
   2.204 -<title>Generating safe binary diffs</title>
   2.205 -
   2.206 -<para id="x_67a">If you use the <option role="hg-opt-diff">-a</option> option to force Mercurial to print
   2.207 -diffs of files that are either <quote>mostly text</quote> or contain lots of
   2.208 -binary data, those diffs cannot subsequently be applied by either
   2.209 -Mercurial's <command role="hg-cmd">hg import</command> command or the system's <command>patch</command>
   2.210 -command.
   2.211 -</para>
   2.212 -
   2.213 -<para id="x_67b">If you want to generate a diff of a binary file that is safe to use as
   2.214 -input for <command role="hg-cmd">hg import</command>, use the <command role="hg-cmd">hg diff</command>{--git} option when you
   2.215 -generate the patch.  The system <command>patch</command> command cannot handle
   2.216 -binary patches at all.
   2.217 -</para>
   2.218 -
   2.219 -</sect3>
   2.220 -</sect2>
   2.221 -</appendix>
   2.222 -
   2.223 -<!--
   2.224 -local variables: 
   2.225 -sgml-parent-document: ("00book.xml" "book" "appendix")
   2.226 -end:
   2.227 --->

     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/en/appA-svn.xml	Sun Apr 26 23:16:56 2009 -0700
     3.3 @@ -0,0 +1,441 @@
     3.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     3.5 +
     3.6 +<appendix id="svn">
     3.7 +  <?dbhtml filename="mercurial-for-subversion-users.html"?>
     3.8 +<title>Migrating to Mercurial</title>
     3.9 +
    3.10 +  <para>A common way to test the waters with a new revision control
    3.11 +    tool is to experiment with switching an existing project, rather
    3.12 +    than starting a new project from scratch.</para>
    3.13 +
    3.14 +  <para>In this appendix, we discuss how to import a project's history
    3.15 +    into Mercurial, and what to look out for if you are used to a
    3.16 +    different revision control system.</para>
    3.17 +
    3.18 +  <sect1>
    3.19 +    <title>Importing history from another system</title>
    3.20 +
    3.21 +    <para>Mercurial ships with an extension named
    3.22 +      <literal>convert</literal>, which can import project history
    3.23 +      from most popular revision control systems.  At the time this
    3.24 +      book was written, it could import history from the following
    3.25 +      systems:</para>
    3.26 +    <itemizedlist>
    3.27 +      <listitem>
    3.28 +	<para>Subversion</para>
    3.29 +      </listitem>
    3.30 +      <listitem>
    3.31 +	<para>CVS</para>
    3.32 +      </listitem>
    3.33 +      <listitem>
    3.34 +	<para>git</para>
    3.35 +      </listitem>
    3.36 +      <listitem>
    3.37 +	<para>Darcs</para>
    3.38 +      </listitem>
    3.39 +      <listitem>
    3.40 +	<para>Bazaar</para>
    3.41 +      </listitem>
    3.42 +      <listitem>
    3.43 +	<para>Monotone</para>
    3.44 +      </listitem>
    3.45 +      <listitem>
    3.46 +	<para>GNU Arch</para>
    3.47 +      </listitem>
    3.48 +      <listitem>
    3.49 +	<para>Mercurial</para>
    3.50 +      </listitem>
    3.51 +    </itemizedlist>
    3.52 +
    3.53 +    <para>(To see why Mercurial itself is supported as a source, see
    3.54 +      <xref linkend="svn.filemap"/>.)</para>
    3.55 +
    3.56 +    <para>You can enable the extension in the usual way, by editing
    3.57 +      your <filename>~/.hgrc</filename> file.</para>
    3.58 +
    3.59 +    <programlisting>[extensions]
    3.60 +convert =</programlisting>
    3.61 +
    3.62 +    <para>This will make a <command>hg convert</command> command
    3.63 +      available.  The command is easy to use.  For instance, this
    3.64 +      command will import the Subversion history for the Nose unit
    3.65 +      testing framework into Mercurial.</para>
    3.66 +
    3.67 +    <screen><prompt>$</prompt> <userinput>hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen>
    3.68 +
    3.69 +    <para>The <literal>convert</literal> extension operates
    3.70 +      incrementally.  In other words, after you have run <command>hg
    3.71 +	convert</command> once, running it again will import any new
    3.72 +      revisions committed after the first run began.  Incremental
    3.73 +      conversion will only work if you run <command>hg
    3.74 +	convert</command> in the same Mercurial repository that you
    3.75 +      originally used, because the <literal>convert</literal>
    3.76 +      extension saves some private metadata in a
    3.77 +      non-revision-controlled file named
    3.78 +      <filename>.hg/shamap</filename> inside the target
    3.79 +      repository.</para>
    3.80 +
    3.81 +    <sect2>
    3.82 +      <title>Mapping user names</title>
    3.83 +
    3.84 +      <para>Some revision control tools save only short usernames with
    3.85 +	commits, and these can be difficult to interpret.  The norm
    3.86 +	with Mercurial is to save a committer's name and email
    3.87 +	address, which is much more useful for talking to them after
    3.88 +	the fact.</para>
    3.89 +
    3.90 +      <para>If you are converting a tree from a revision control
    3.91 +	system that uses short names, you can map those names to
    3.92 +	longer equivalents by passing a <option>--authors</option>
    3.93 +	option to <command>hg convert</command>.  This option accepts
    3.94 +	a file name that should contain entries of the following
    3.95 +	form.</para>
    3.96 +
    3.97 +      <programlisting>arist = Aristotle &lt;aristotle@phil.example.gr&gt;
    3.98 +soc = Socrates &lt;socrates@phil.example.gr&gt;</programlisting>
    3.99 +
   3.100 +      <para>Whenever <literal>convert</literal> encounters a commit
   3.101 +	with the username <literal>arist</literal> in the source
   3.102 +	repository, it will use the name <literal>Aristotle
   3.103 +	  &lt;aristotle@phil.example.gr&gt;</literal> in the converted
   3.104 +	Mercurial revision.  If no match is found for a name, it is
   3.105 +	used verbatim.</para>
   3.106 +    </sect2>
   3.107 +
   3.108 +    <sect2 id="svn.filemap">
   3.109 +      <title>Tidying up the tree</title>
   3.110 +
   3.111 +      <para>Not all projects have pristine history.  There may be a
   3.112 +	directory that should never have been checked in, a file that
   3.113 +	is too big, or a whole hierarchy that needs to be
   3.114 +	refactored.</para>
   3.115 +
   3.116 +      <para>The <literal>convert</literal> extension supports the idea
   3.117 +	of a <quote>file map</quote> that can reorganize the files and
   3.118 +	directories in a project as it imports the project's history.
   3.119 +	This is useful not only when importing history from other
   3.120 +	revision control systems, but also to prune or refactor a
   3.121 +	Mercurial tree.</para>
   3.122 +
   3.123 +      <para>To specify a file map, use the <option>--filemap</option>
   3.124 +	option and supply a file name.  A file map contains lines of the
   3.125 +	following forms.</para>
   3.126 +
   3.127 +      <programlisting># This is a comment.
   3.128 +# Empty lines are ignored.	
   3.129 +
   3.130 +include path/to/file
   3.131 +
   3.132 +exclude path/to/file
   3.133 +
   3.134 +rename from/some/path to/some/other/place
   3.135 +</programlisting>
   3.136 +
   3.137 +      <para>The <literal>include</literal> directive causes a file, or
   3.138 +	all files under a directory, to be included in the destination
   3.139 +	repository.  This also excludes all other files and dirs not
   3.140 +	explicitely included.  The <literal>exclude</literal>
   3.141 +	directive causes files or directories to be omitted, and
   3.142 +	others not explicitly mentioned to be included.</para>
   3.143 +
   3.144 +      <para>To move a file or directory from one location to another,
   3.145 +	use the <literal>rename</literal> directive.  If you need to
   3.146 +	move a file or directory from a subdirectory into the root of
   3.147 +	the repository, use <literal>.</literal> as the second
   3.148 +	argument to the <literal>rename</literal> directive.</para>
   3.149 +    </sect2>
   3.150 +  </sect1>
   3.151 +
   3.152 +  <sect1>
   3.153 +    <title>Migrating from Subversion</title>
   3.154 +
   3.155 +    <para>Subversion is currently the most popular open source
   3.156 +      revision control system. Although there are many differences
   3.157 +      between Mercurial and Subversion, making the transition from
   3.158 +      Subversion to Mercurial is not particularly difficult.  The two
   3.159 +      have similar command sets and generally uniform
   3.160 +      interfaces.</para>
   3.161 +
   3.162 +    <sect2>
   3.163 +      <title>Philosophical differences</title>
   3.164 +
   3.165 +      <para>The fundamental difference between Subversion and
   3.166 +	Mercurial is of course that Subversion is centralized, while
   3.167 +	Mercurial is distributed.  Since Mercurial stores all of a
   3.168 +	project's history on your local drive, it only needs to
   3.169 +	perform a network access when you want to explicitly
   3.170 +	communicate with another repository. In contrast, Subversion
   3.171 +	stores very little information locally, and the client must
   3.172 +	thus contact its server for many common operations.</para>
   3.173 +
   3.174 +      <para>Subversion more or less gets away without a well-defined
   3.175 +	notion of a branch: which portion of a server's namespace
   3.176 +	qualifies as a branch is a matter of convention, with the
   3.177 +	software providing no enforcement.  Mercurial treats a
   3.178 +	repository as the unit of branch management.</para>
   3.179 +
   3.180 +      <sect3>
   3.181 +	<title>Scope of commands</title>
   3.182 +
   3.183 +	<para>Since Subversion doesn't know what parts of its
   3.184 +	  namespace are really branches, it treats most commands as
   3.185 +	  requests to operate at and below whatever directory you are
   3.186 +	  currently visiting.  For instance, if you run <command>svn
   3.187 +	    log</command>, you'll get the history of whatever part of
   3.188 +	  the tree you're looking at, not the tree as a whole.</para>
   3.189 +
   3.190 +	<para>Mercurial's commands behave differently, by defaulting
   3.191 +	  to operating over an entire repository.  Run <command>hg
   3.192 +	    log</command> and it will tell you the history of the
   3.193 +	  entire tree, no matter what part of the working directory
   3.194 +	  you're visiting at the time.  If you want the history of
   3.195 +	  just a particular file or directory, simply supply it by
   3.196 +	  name, e.g. <command>hg log src</command>.</para>
   3.197 +
   3.198 +	<para>From my own experience, this difference in default
   3.199 +	  behaviors is probably the most likely to trip you up if you
   3.200 +	  have to switch back and forth frequently between the two
   3.201 +	  tools.</para>
   3.202 +      </sect3>
   3.203 +
   3.204 +      <sect3>
   3.205 +	<title>Multi-user operation and safety</title>
   3.206 +
   3.207 +	<para>With Subversion, it is normal (though slightly frowned
   3.208 +	  upon) for multiple people to collaborate in a single branch.
   3.209 +	  If Alice and Bob are working together, and Alice commits
   3.210 +	  some changes to their shared branch, Bob must update his
   3.211 +	  client's view of the branch before he can commit.  Since at
   3.212 +	  this time he has no permanent record of the changes he has
   3.213 +	  made, he can corrupt or lose his modifications during and
   3.214 +	  after his update.</para>
   3.215 +
   3.216 +	<para>Mercurial encourages a commit-then-merge model instead.
   3.217 +	  Bob commits his changes locally before pulling changes from,
   3.218 +	  or pushing them to, the server that he shares with Alice.
   3.219 +	  If Alice pushed her changes before Bob tries to push his, he
   3.220 +	  will not be able to push his changes until he pulls hers,
   3.221 +	  merges with them, and commits the result of the merge.  If
   3.222 +	  he makes a mistake during the merge, he still has the option
   3.223 +	  of reverting to the commit that recorded his changes.</para>
   3.224 +
   3.225 +	<para>It is worth emphasizing that these are the common ways
   3.226 +	  of working with these tools. Subversion supports a safer
   3.227 +	  work-in-your-own-branch model, but it is cumbersome enough
   3.228 +	  in practice to not be widely used.  Mercurial can support
   3.229 +	  the less safe mode of allowing changes to be pulled in and
   3.230 +	  merged on top of uncommitted edits, but this is considered
   3.231 +	  highly unusual.</para>
   3.232 +      </sect3>
   3.233 +
   3.234 +      <sect3>
   3.235 +	<title>Published vs local changes</title>
   3.236 +
   3.237 +	<para>A Subversion <command>svn commit</command> command
   3.238 +	  immediately publishes changes to a server, where they can be
   3.239 +	  seen by everyone who has read access.</para>
   3.240 +
   3.241 +	<para>With Mercurial, commits are always local, and must be
   3.242 +	  published via a <command>hg push</command> command
   3.243 +	  afterwards.</para>
   3.244 +
   3.245 +	<para>Each approach has its advantages and disadvantages.  The
   3.246 +	  Subversion model means that changes are published, and hence
   3.247 +	  reviewable and usable, immediately.  On the other hand, this
   3.248 +	  means that a user must have commit access to a repository in
   3.249 +	  order to use the software in a normal way, and commit access
   3.250 +	  is not lightly given out by most open source
   3.251 +	  projects.</para>
   3.252 +
   3.253 +	<para>The Mercurial approach allows anyone who can clone a
   3.254 +	  repository to commit changes without the need for someone
   3.255 +	  else's permission, and they can then publish their changes
   3.256 +	  and continue to participate however they see fit.  The
   3.257 +	  distinction between committing and pushing does open up the
   3.258 +	  possibility of someone committing changes to their laptop
   3.259 +	  and walking away for a few days having forgotten to push
   3.260 +	  them, which in rare cases might leave collaborators
   3.261 +	  temporarily stuck.</para>
   3.262 +      </sect3>
   3.263 +    </sect2>
   3.264 +
   3.265 +    <sect2>
   3.266 +      <title>Quick reference</title>
   3.267 +
   3.268 +      <table>
   3.269 +	<title>Subversion commands and Mercurial equivalents</title>
   3.270 +	<tgroup cols="3">
   3.271 +	  <thead>
   3.272 +	    <row>
   3.273 +	      <entry>Subversion</entry>
   3.274 +	      <entry>Mercurial</entry>
   3.275 +	      <entry>Notes</entry>
   3.276 +	    </row>
   3.277 +	  </thead>
   3.278 +	  <tbody>
   3.279 +	    <row>
   3.280 +	      <entry><command>svn add</command></entry>
   3.281 +	      <entry><command>hg add</command></entry>
   3.282 +	      <entry></entry>
   3.283 +	    </row>
   3.284 +	    <row>
   3.285 +	      <entry><command>svn blame</command></entry>
   3.286 +	      <entry><command>hg annotate</command></entry>
   3.287 +	      <entry></entry>
   3.288 +	    </row>
   3.289 +	    <row>
   3.290 +	      <entry><command>svn cat</command></entry>
   3.291 +	      <entry><command>hg cat</command></entry>
   3.292 +	      <entry></entry>
   3.293 +	    </row>
   3.294 +	    <row>
   3.295 +	      <entry><command>svn checkout</command></entry>
   3.296 +	      <entry><command>hg clone</command></entry>
   3.297 +	      <entry></entry>
   3.298 +	    </row>
   3.299 +	    <row>
   3.300 +	      <entry><command>svn cleanup</command></entry>
   3.301 +	      <entry>n/a</entry>
   3.302 +	      <entry>No cleanup needed</entry>
   3.303 +	    </row>
   3.304 +	    <row>
   3.305 +	      <entry><command>svn commit</command></entry>
   3.306 +	      <entry><command>hg commit</command>; <command>hg
   3.307 +		  push</command></entry>
   3.308 +	      <entry><command>hg push</command> publishes after
   3.309 +		commit</entry>
   3.310 +	    </row>
   3.311 +	    <row>
   3.312 +	      <entry><command>svn copy</command></entry>
   3.313 +	      <entry><command>hg clone</command></entry>
   3.314 +	      <entry>To create a new branch</entry>
   3.315 +	    </row>
   3.316 +	    <row>
   3.317 +	      <entry><command>svn copy</command></entry>
   3.318 +	      <entry><command>hg copy</command></entry>
   3.319 +	      <entry>To copy files or directories</entry>
   3.320 +	    </row>
   3.321 +	    <row>
   3.322 +	      <entry><command>svn delete</command> (<command>svn
   3.323 +		  remove</command>)</entry>
   3.324 +	      <entry><command>hg remove</command></entry>
   3.325 +	      <entry></entry>
   3.326 +	    </row>
   3.327 +	    <row>
   3.328 +	      <entry><command>svn diff</command></entry>
   3.329 +	      <entry><command>hg diff</command></entry>
   3.330 +	      <entry></entry>
   3.331 +	    </row>
   3.332 +	    <row>
   3.333 +	      <entry><command>svn export</command></entry>
   3.334 +	      <entry><command>hg archive</command></entry>
   3.335 +	      <entry></entry>
   3.336 +	    </row>
   3.337 +	    <row>
   3.338 +	      <entry><command>svn help</command></entry>
   3.339 +	      <entry><command>hg help</command></entry>
   3.340 +	      <entry></entry>
   3.341 +	    </row>
   3.342 +	    <row>
   3.343 +	      <entry><command>svn import</command></entry>
   3.344 +	      <entry><command>hg addremove</command>; <command>hg
   3.345 +		  commit</command></entry>
   3.346 +	      <entry></entry>
   3.347 +	    </row>
   3.348 +	    <row>
   3.349 +	      <entry><command>svn info</command></entry>
   3.350 +	      <entry><command>hg parents</command></entry>
   3.351 +	      <entry>Shows what revision is checked out</entry>
   3.352 +	    </row>
   3.353 +	    <row>
   3.354 +	      <entry><command>svn info</command></entry>
   3.355 +	      <entry><command>hg showconfig
   3.356 +		  paths.parent</command></entry>
   3.357 +	      <entry>Shows what URL is checked out</entry>
   3.358 +	    </row>
   3.359 +	    <row>
   3.360 +	      <entry><command>svn list</command></entry>
   3.361 +	      <entry><command>hg manifest</command></entry>
   3.362 +	      <entry></entry>
   3.363 +	    </row>
   3.364 +	    <row>
   3.365 +	      <entry><command>svn log</command></entry>
   3.366 +	      <entry><command>hg log</command></entry>
   3.367 +	      <entry></entry>
   3.368 +	    </row>
   3.369 +	    <row>
   3.370 +	      <entry><command>svn merge</command></entry>
   3.371 +	      <entry><command>hg merge</command></entry>
   3.372 +	      <entry></entry>
   3.373 +	    </row>
   3.374 +	    <row>
   3.375 +	      <entry><command>svn mkdir</command></entry>
   3.376 +	      <entry>n/a</entry>
   3.377 +	      <entry>Mercurial does not track directories</entry>
   3.378 +	    </row>
   3.379 +	    <row>
   3.380 +	      <entry><command>svn move</command> (<command>svn
   3.381 +		  rename</command>)</entry>
   3.382 +	      <entry><command>hg rename</command></entry>
   3.383 +	      <entry></entry>
   3.384 +	    </row>
   3.385 +	    <row>
   3.386 +	      <entry><command>svn resolved</command></entry>
   3.387 +	      <entry><command>hg resolve -m</command></entry>
   3.388 +	      <entry></entry>
   3.389 +	    </row>
   3.390 +	    <row>
   3.391 +	      <entry><command>svn revert</command></entry>
   3.392 +	      <entry><command>hg revert</command></entry>
   3.393 +	      <entry></entry>
   3.394 +	    </row>
   3.395 +	    <row>
   3.396 +	      <entry><command>svn status</command></entry>
   3.397 +	      <entry><command>hg status</command></entry>
   3.398 +	      <entry></entry>
   3.399 +	    </row>
   3.400 +	    <row>
   3.401 +	      <entry><command>svn update</command></entry>
   3.402 +	      <entry><command>hg pull -u</command></entry>
   3.403 +	      <entry></entry>
   3.404 +	    </row>
   3.405 +	  </tbody>
   3.406 +	</tgroup>
   3.407 +      </table>
   3.408 +    </sect2>
   3.409 +  </sect1>
   3.410 +
   3.411 +  <sect1>
   3.412 +    <title>Useful tips for newcomers</title>
   3.413 +
   3.414 +    <para>Under some revision control systems, printing a diff for a
   3.415 +      single committed revision can be painful. For instance, with
   3.416 +      Subversion, to see what changed in revision 104654, you must
   3.417 +      type <command>svn diff -r104653:104654</command>. Mercurial
   3.418 +      eliminates the need to type the revision ID twice in this common
   3.419 +      case. For a plain diff, <command>hg export 104654</command>. For
   3.420 +      a log message followed by a diff, <command>hg log -r104654
   3.421 +	-p</command>.</para>
   3.422 +
   3.423 +    <para>When you run <command>hg status</command> without any
   3.424 +      arguments, it prints the status of the entire tree, with paths
   3.425 +      relative to the root of the repository.  This makes it tricky to
   3.426 +      copy a file name from the output of <command>hg status</command>
   3.427 +      into the command line.  If you supply a file or directory name
   3.428 +      to <command>hg status</command>, it will print paths relative to
   3.429 +      your current location instead.  So to get tree-wide status from
   3.430 +      <command>hg status</command>, with paths that are relative to
   3.431 +      your current directory and not the root of the repository, feed
   3.432 +      the output of <command>hg root</command> into <command>hg
   3.433 +	status</command>.  You can easily do this as follows on a
   3.434 +      Unix-like system:</para>
   3.435 +
   3.436 +    <screen><prompt>$</prompt> <userinput>hg status `hg root`</userinput></screen>
   3.437 +  </sect1>
   3.438 +</appendix>
   3.439 +
   3.440 +<!--
   3.441 +local variables: 
   3.442 +sgml-parent-document: ("00book.xml" "book" "appendix")
   3.443 +end:
   3.444 +-->