1.1 --- a/.hgignore	Mon Feb 09 23:25:40 2009 -0800
     1.2 +++ b/.hgignore	Wed Feb 18 00:22:09 2009 -0800
     1.3 @@ -35,3 +35,4 @@
     1.4  .*.swp
     1.5  .\#*
     1.6  .run
     1.7 +xsl/system-xsl

     2.1 --- a/en/00book.xml	Mon Feb 09 23:25:40 2009 -0800
     2.2 +++ b/en/00book.xml	Wed Feb 18 00:22:09 2009 -0800
     2.3 @@ -9,7 +9,22 @@
     2.4  
     2.5  <!ENTITY ch01     SYSTEM "ch01-intro.xml">
     2.6  <!ENTITY ch02     SYSTEM "ch02-tour-basic.xml">
     2.7 +<!ENTITY ch03     SYSTEM "ch03-tour-merge.xml">
     2.8 +<!ENTITY ch04     SYSTEM "ch04-concepts.xml">
     2.9 +<!ENTITY ch05     SYSTEM "ch05-daily.xml">
    2.10 +<!ENTITY ch06     SYSTEM "ch06-collab.xml">
    2.11 +<!ENTITY ch07     SYSTEM "ch07-filenames.xml">
    2.12 +<!ENTITY ch08     SYSTEM "ch08-branch.xml">
    2.13 +<!ENTITY ch09     SYSTEM "ch09-undo.xml">
    2.14 +<!ENTITY ch10     SYSTEM "ch10-hook.xml">
    2.15 +<!ENTITY ch11     SYSTEM "ch11-template.xml">
    2.16  <!ENTITY ch12     SYSTEM "ch12-mq.xml">
    2.17 +<!ENTITY ch13     SYSTEM "ch13-mq-collab.xml">
    2.18 +<!ENTITY ch14     SYSTEM "ch14-hgext.xml">
    2.19 +<!ENTITY appA     SYSTEM "appA-cmdref.xml">
    2.20 +<!ENTITY appB     SYSTEM "appB-mq-ref.xml">
    2.21 +<!ENTITY appC     SYSTEM "appC-srcinstall.xml">
    2.22 +<!ENTITY appD     SYSTEM "appD-license.xml">
    2.23  
    2.24  <!-- Include our standard shortcuts. -->
    2.25  
    2.26 @@ -41,5 +56,20 @@
    2.27  
    2.28    &ch01;
    2.29    &ch02;
    2.30 +  &ch03;
    2.31 +  &ch04;
    2.32 +  &ch05;
    2.33 +  &ch06;
    2.34 +  &ch07;
    2.35 +  &ch08;
    2.36 +  &ch09;
    2.37 +  &ch10;
    2.38 +  &ch11;
    2.39    &ch12;
    2.40 +  &ch13;
    2.41 +  &ch14;
    2.42 +  <!-- &appA; -->
    2.43 +  &appB;
    2.44 +  &appC;
    2.45 +  &appD;
    2.46  </book>

     3.1 --- a/en/Makefile	Mon Feb 09 23:25:40 2009 -0800
     3.2 +++ b/en/Makefile	Wed Feb 18 00:22:09 2009 -0800
     3.3 @@ -33,9 +33,8 @@
     3.4  
     3.5  xml-src-files := \
     3.6  	00book.xml \
     3.7 -	ch01-intro.xml \
     3.8 -	ch02-tour-basic.xml \
     3.9 -	ch12-mq.xml
    3.10 +	app*.xml \
    3.11 +	ch*.xml
    3.12  
    3.13  image-dot := $(filter %.dot,$(image-sources))
    3.14  image-svg := $(filter %.svg,$(image-sources))

     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/en/appA-cmdref.xml	Wed Feb 18 00:22:09 2009 -0800
     4.3 @@ -0,0 +1,223 @@
     4.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     4.5 +
     4.6 +<appendix id="cmdref">
     4.7 +<title>Command reference</title>
     4.8 +
     4.9 +<para>\cmdref{add}{add files at the next commit}
    4.10 +\optref{add}{I}{include}
    4.11 +\optref{add}{X}{exclude}
    4.12 +\optref{add}{n}{dry-run}</para>
    4.13 +
    4.14 +<para>\cmdref{diff}{print changes in history or working directory}</para>
    4.15 +
    4.16 +<para>Show differences between revisions for the specified files or
    4.17 +directories, using the unified diff format.  For a description of the
    4.18 +unified diff format, see section <xref linkend="sec:mq:patch"/>.</para>
    4.19 +
    4.20 +<para>By default, this command does not print diffs for files that Mercurial
    4.21 +considers to contain binary data.  To control this behaviour, see the
    4.22 +<option role="hg-opt-diff">-a</option> and <option role="hg-opt-diff">--git</option> options.</para>
    4.23 +
    4.24 +<sect2>
    4.25 +<title>Options</title>
    4.26 +
    4.27 +<para>\loptref{diff}{nodates}</para>
    4.28 +
    4.29 +<para>Omit date and time information when printing diff headers.</para>
    4.30 +
    4.31 +<para>\optref{diff}{B}{ignore-blank-lines}</para>
    4.32 +
    4.33 +<para>Do not print changes that only insert or delete blank lines.  A line
    4.34 +that contains only whitespace is not considered blank.
    4.35 +</para>
    4.36 +
    4.37 +<para>\optref{diff}{I}{include}
    4.38 +</para>
    4.39 +
    4.40 +<para>Include files and directories whose names match the given patterns.
    4.41 +</para>
    4.42 +
    4.43 +<para>\optref{diff}{X}{exclude}
    4.44 +</para>
    4.45 +
    4.46 +<para>Exclude files and directories whose names match the given patterns.
    4.47 +</para>
    4.48 +
    4.49 +<para>\optref{diff}{a}{text}
    4.50 +</para>
    4.51 +
    4.52 +<para>If this option is not specified, <command role="hg-cmd">hg diff</command> will refuse to print
    4.53 +diffs for files that it detects as binary. Specifying <option role="hg-opt-diff">-a</option>
    4.54 +forces <command role="hg-cmd">hg diff</command> to treat all files as text, and generate diffs for
    4.55 +all of them.
    4.56 +</para>
    4.57 +
    4.58 +<para>This option is useful for files that are <quote>mostly text</quote> but have a
    4.59 +few embedded NUL characters.  If you use it on files that contain a
    4.60 +lot of binary data, its output will be incomprehensible.
    4.61 +</para>
    4.62 +
    4.63 +<para>\optref{diff}{b}{ignore-space-change}
    4.64 +</para>
    4.65 +
    4.66 +<para>Do not print a line if the only change to that line is in the amount
    4.67 +of white space it contains.
    4.68 +</para>
    4.69 +
    4.70 +<para>\optref{diff}{g}{git}
    4.71 +</para>
    4.72 +
    4.73 +<para>Print <command>git</command>-compatible diffs.  XXX reference a format
    4.74 +description.
    4.75 +</para>
    4.76 +
    4.77 +<para>\optref{diff}{p}{show-function}
    4.78 +</para>
    4.79 +
    4.80 +<para>Display the name of the enclosing function in a hunk header, using a
    4.81 +simple heuristic.  This functionality is enabled by default, so the
    4.82 +<option role="hg-opt-diff">-p</option> option has no effect unless you change the value of
    4.83 +the <envar role="rc-item-diff">showfunc</envar> config item, as in the following example.</para>
    4.84 +
    4.85 +<!-- &interaction.cmdref.diff-p; -->
    4.86 +
    4.87 +<para>\optref{diff}{r}{rev}
    4.88 +</para>
    4.89 +
    4.90 +<para>Specify one or more revisions to compare.  The <command role="hg-cmd">hg diff</command> command
    4.91 +accepts up to two <option role="hg-opt-diff">-r</option> options to specify the revisions to
    4.92 +compare.
    4.93 +</para>
    4.94 +
    4.95 +<orderedlist>
    4.96 +<listitem><para>Display the differences between the parent revision of the
    4.97 +  working directory and the working directory.
    4.98 +</para>
    4.99 +</listitem>
   4.100 +<listitem><para>Display the differences between the specified changeset and the
   4.101 +  working directory.
   4.102 +</para>
   4.103 +</listitem>
   4.104 +<listitem><para>Display the differences between the two specified changesets.
   4.105 +</para>
   4.106 +</listitem></orderedlist>
   4.107 +
   4.108 +<para>You can specify two revisions using either two <option role="hg-opt-diff">-r</option>
   4.109 +options or revision range notation.  For example, the two revision
   4.110 +specifications below are equivalent.
   4.111 +</para>
   4.112 +<programlisting>hg diff -r 10 -r 20
   4.113 +hg diff -r10:20</programlisting>
   4.114 +
   4.115 +<para>When you provide two revisions, Mercurial treats the order of those
   4.116 +revisions as significant.  Thus, <command role="hg-cmd">hg diff -r10:20</command> will
   4.117 +produce a diff that will transform files from their contents as of
   4.118 +revision 10 to their contents as of revision 20, while
   4.119 +<command role="hg-cmd">hg diff -r20:10</command> means the opposite: the diff that will
   4.120 +transform files from their revision 20 contents to their revision 10
   4.121 +contents.  You cannot reverse the ordering in this way if you are
   4.122 +diffing against the working directory.
   4.123 +</para>
   4.124 +
   4.125 +<para>\optref{diff}{w}{ignore-all-space}
   4.126 +</para>
   4.127 +
   4.128 +<para>\cmdref{version}{print version and copyright information}
   4.129 +</para>
   4.130 +
   4.131 +<para>This command displays the version of Mercurial you are running, and
   4.132 +its copyright license.  There are four kinds of version string that
   4.133 +you may see.
   4.134 +</para>
   4.135 +<itemizedlist>
   4.136 +<listitem><para>The string <quote><literal>unknown</literal></quote>. This version of Mercurial was
   4.137 +  not built in a Mercurial repository, and cannot determine its own
   4.138 +  version.
   4.139 +</para>
   4.140 +</listitem>
   4.141 +<listitem><para>A short numeric string, such as <quote><literal>1.1</literal></quote>. This is a
   4.142 +  build of a revision of Mercurial that was identified by a specific
   4.143 +  tag in the repository where it was built.  (This doesn't necessarily
   4.144 +  mean that you're running an official release; someone else could
   4.145 +  have added that tag to any revision in the repository where they
   4.146 +  built Mercurial.)
   4.147 +</para>
   4.148 +</listitem>
   4.149 +<listitem><para>A hexadecimal string, such as <quote><literal>875489e31abe</literal></quote>.  This
   4.150 +  is a build of the given revision of Mercurial.
   4.151 +</para>
   4.152 +</listitem>
   4.153 +<listitem><para>A hexadecimal string followed by a date, such as
   4.154 +  <quote><literal>875489e31abe+20070205</literal></quote>.  This is a build of the given
   4.155 +  revision of Mercurial, where the build repository contained some
   4.156 +  local changes that had not been committed.
   4.157 +</para>
   4.158 +</listitem></itemizedlist>
   4.159 +
   4.160 +</sect2>
   4.161 +<sect2>
   4.162 +<title>Tips and tricks</title>
   4.163 +
   4.164 +<sect3 id="cmdref:diff-vs-status">
   4.165 +<title>Why do the results of <command role="hg-cmd">hg diff</command> and <command role="hg-cmd">hg status</command> differ?</title>
   4.166 +
   4.167 +<para>When you run the <command role="hg-cmd">hg status</command> command, you'll see a list of files
   4.168 +that Mercurial will record changes for the next time you perform a
   4.169 +commit.  If you run the <command role="hg-cmd">hg diff</command> command, you may notice that it
   4.170 +prints diffs for only a <emphasis>subset</emphasis> of the files that <command role="hg-cmd">hg status</command>
   4.171 +listed.  There are two possible reasons for this.
   4.172 +</para>
   4.173 +
   4.174 +<para>The first is that <command role="hg-cmd">hg status</command> prints some kinds of modifications
   4.175 +that <command role="hg-cmd">hg diff</command> doesn't normally display.  The <command role="hg-cmd">hg diff</command> command
   4.176 +normally outputs unified diffs, which don't have the ability to
   4.177 +represent some changes that Mercurial can track.  Most notably,
   4.178 +traditional diffs can't represent a change in whether or not a file is
   4.179 +executable, but Mercurial records this information.
   4.180 +</para>
   4.181 +
   4.182 +<para>If you use the <option role="hg-opt-diff">--git</option> option to <command role="hg-cmd">hg diff</command>, it will
   4.183 +display <command>git</command>-compatible diffs that <emphasis>can</emphasis> display this
   4.184 +extra information.
   4.185 +</para>
   4.186 +
   4.187 +<para>The second possible reason that <command role="hg-cmd">hg diff</command> might be printing diffs
   4.188 +for a subset of the files displayed by <command role="hg-cmd">hg status</command> is that if you
   4.189 +invoke it without any arguments, <command role="hg-cmd">hg diff</command> prints diffs against the
   4.190 +first parent of the working directory.  If you have run <command role="hg-cmd">hg merge</command>
   4.191 +to merge two changesets, but you haven't yet committed the results of
   4.192 +the merge, your working directory has two parents (use <command role="hg-cmd">hg parents</command>
   4.193 +to see them).  While <command role="hg-cmd">hg status</command> prints modifications relative to
   4.194 +<emphasis>both</emphasis> parents after an uncommitted merge, <command role="hg-cmd">hg diff</command> still
   4.195 +operates relative only to the first parent.  You can get it to print
   4.196 +diffs relative to the second parent by specifying that parent with the
   4.197 +<option role="hg-opt-diff">-r</option> option.  There is no way to print diffs relative to
   4.198 +both parents.
   4.199 +</para>
   4.200 +
   4.201 +</sect3>
   4.202 +<sect3>
   4.203 +<title>Generating safe binary diffs</title>
   4.204 +
   4.205 +<para>If you use the <option role="hg-opt-diff">-a</option> option to force Mercurial to print
   4.206 +diffs of files that are either <quote>mostly text</quote> or contain lots of
   4.207 +binary data, those diffs cannot subsequently be applied by either
   4.208 +Mercurial's <command role="hg-cmd">hg import</command> command or the system's <command>patch</command>
   4.209 +command.
   4.210 +</para>
   4.211 +
   4.212 +<para>If you want to generate a diff of a binary file that is safe to use as
   4.213 +input for <command role="hg-cmd">hg import</command>, use the <command role="hg-cmd">hg diff</command>{--git} option when you
   4.214 +generate the patch.  The system <command>patch</command> command cannot handle
   4.215 +binary patches at all.
   4.216 +</para>
   4.217 +
   4.218 +</sect3>
   4.219 +</sect2>
   4.220 +</appendix>
   4.221 +
   4.222 +<!--
   4.223 +local variables: 
   4.224 +sgml-parent-document: ("00book.xml" "book" "appendix")
   4.225 +end:
   4.226 +-->

     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/en/appB-mq-ref.xml	Wed Feb 18 00:22:09 2009 -0800
     5.3 @@ -0,0 +1,568 @@
     5.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     5.5 +
     5.6 +<appendix id="chap:mqref">
     5.7 +  <title>Mercurial Queues reference</title>
     5.8 +
     5.9 +  <sect1 id="sec:mqref:cmdref">
    5.10 +    <title>MQ command reference</title>
    5.11 +
    5.12 +    <para>For an overview of the commands provided by MQ, use the
    5.13 +      command <command role="hg-cmd">hg help mq</command>.</para>
    5.14 +
    5.15 +    <sect2>
    5.16 +      <title><command role="hg-ext-mq">qapplied</command>&emdash;print
    5.17 +	applied patches</title>
    5.18 +
    5.19 +      <para>The <command role="hg-ext-mq">qapplied</command> command
    5.20 +	prints the current stack of applied patches.  Patches are
    5.21 +	printed in oldest-to-newest order, so the last patch in the
    5.22 +	list is the <quote>top</quote> patch.</para>
    5.23 +
    5.24 +    </sect2>
    5.25 +    <sect2>
    5.26 +      <title><command role="hg-ext-mq">qcommit</command>&emdash;commit
    5.27 +	changes in the queue repository</title>
    5.28 +
    5.29 +      <para>The <command role="hg-ext-mq">qcommit</command> command
    5.30 +	commits any outstanding changes in the <filename
    5.31 +	  role="special" class="directory">.hg/patches</filename>
    5.32 +	repository.  This command only works if the <filename
    5.33 +	  role="special" class="directory">.hg/patches</filename>
    5.34 +	directory is a repository, i.e. you created the directory
    5.35 +	using <command role="hg-cmd">hg qinit <option
    5.36 +	    role="hg-ext-mq-cmd-qinit-opt">-c</option></command> or
    5.37 +	ran <command role="hg-cmd">hg init</command> in the directory
    5.38 +	after running <command
    5.39 +	  role="hg-ext-mq">qinit</command>.</para>
    5.40 +
    5.41 +      <para>This command is shorthand for <command role="hg-cmd">hg
    5.42 +	  commit --cwd .hg/patches</command>.</para>
    5.43 +
    5.44 +      <para>\subsection{<command
    5.45 +	  role="hg-ext-mq">qdelete</command>&emdash;delete a patch
    5.46 +	from the <filename role="special">series</filename>
    5.47 +	file}</para>
    5.48 +
    5.49 +      <para>The <command role="hg-ext-mq">qdelete</command> command
    5.50 +	removes the entry for a patch from the <filename
    5.51 +	  role="special">series</filename> file in the <filename
    5.52 +	  role="special" class="directory">.hg/patches</filename>
    5.53 +	directory.  It does not pop the patch if the patch is already
    5.54 +	applied.  By default, it does not delete the patch file; use
    5.55 +	the <option role="hg-ext-mq-cmd-qdel-opt">-f</option> option
    5.56 +	to do that.</para>
    5.57 +
    5.58 +      <para>Options:</para>
    5.59 +      <itemizedlist>
    5.60 +	<listitem><para><option
    5.61 +	      role="hg-ext-mq-cmd-qdel-opt">-f</option>: Delete the
    5.62 +	    patch file.</para>
    5.63 +	</listitem></itemizedlist>
    5.64 +
    5.65 +    </sect2>
    5.66 +    <sect2>
    5.67 +      <title><command role="hg-ext-mq">qdiff</command>&emdash;print a
    5.68 +	diff of the topmost applied patch</title>
    5.69 +
    5.70 +      <para>The <command role="hg-ext-mq">qdiff</command> command
    5.71 +	prints a diff of the topmost applied patch. It is equivalent
    5.72 +	to <command role="hg-cmd">hg diff -r-2:-1</command>.</para>
    5.73 +
    5.74 +    </sect2>
    5.75 +    <sect2>
    5.76 +      <title><command role="hg-ext-mq">qfold</command>&emdash;merge
    5.77 +	(<quote>fold</quote>) several patches into one</title>
    5.78 +
    5.79 +      <para>The <command role="hg-ext-mq">qfold</command> command
    5.80 +	merges multiple patches into the topmost applied patch, so
    5.81 +	that the topmost applied patch makes the union of all of the
    5.82 +	changes in the patches in question.</para>
    5.83 +
    5.84 +      <para>The patches to fold must not be applied; <command
    5.85 +	  role="hg-ext-mq">qfold</command> will exit with an error if
    5.86 +	any is.  The order in which patches are folded is significant;
    5.87 +	<command role="hg-cmd">hg qfold a b</command> means
    5.88 +	<quote>apply the current topmost patch, followed by
    5.89 +	  <literal>a</literal>, followed by
    5.90 +	  <literal>b</literal></quote>.</para>
    5.91 +
    5.92 +      <para>The comments from the folded patches are appended to the
    5.93 +	comments of the destination patch, with each block of comments
    5.94 +	separated by three asterisk
    5.95 +	(<quote><literal>*</literal></quote>) characters.  Use the
    5.96 +	<option role="hg-ext-mq-cmd-qfold-opt">-e</option> option to
    5.97 +	edit the commit message for the combined patch/changeset after
    5.98 +	the folding has completed.</para>
    5.99 +
   5.100 +      <para>Options:</para>
   5.101 +      <itemizedlist>
   5.102 +	<listitem><para><option
   5.103 +	      role="hg-ext-mq-cmd-qfold-opt">-e</option>: Edit the
   5.104 +	    commit message and patch description for the newly folded
   5.105 +	    patch.</para>
   5.106 +	</listitem>
   5.107 +	<listitem><para><option
   5.108 +	      role="hg-ext-mq-cmd-qfold-opt">-l</option>: Use the
   5.109 +	    contents of the given file as the new commit message and
   5.110 +	    patch description for the folded patch.</para>
   5.111 +	</listitem>
   5.112 +	<listitem><para><option
   5.113 +	      role="hg-ext-mq-cmd-qfold-opt">-m</option>: Use the
   5.114 +	    given text as the new commit message and patch description
   5.115 +	    for the folded patch.</para>
   5.116 +	</listitem></itemizedlist>
   5.117 +
   5.118 +    </sect2>
   5.119 +    <sect2>
   5.120 +      <title><command
   5.121 +	  role="hg-ext-mq">qheader</command>&emdash;display the
   5.122 +	header/description of a patch</title>
   5.123 +
   5.124 +      <para>The <command role="hg-ext-mq">qheader</command> command
   5.125 +	prints the header, or description, of a patch.  By default, it
   5.126 +	prints the header of the topmost applied patch. Given an
   5.127 +	argument, it prints the header of the named patch.</para>
   5.128 +
   5.129 +    </sect2>
   5.130 +    <sect2>
   5.131 +      <title><command role="hg-ext-mq">qimport</command>&emdash;import
   5.132 +	a third-party patch into the queue</title>
   5.133 +
   5.134 +      <para>The <command role="hg-ext-mq">qimport</command> command
   5.135 +	adds an entry for an external patch to the <filename
   5.136 +	  role="special">series</filename> file, and copies the patch
   5.137 +	into the <filename role="special"
   5.138 +	  class="directory">.hg/patches</filename> directory.  It adds
   5.139 +	the entry immediately after the topmost applied patch, but
   5.140 +	does not push the patch.</para>
   5.141 +
   5.142 +      <para>If the <filename role="special"
   5.143 +	  class="directory">.hg/patches</filename> directory is a
   5.144 +	repository, <command role="hg-ext-mq">qimport</command>
   5.145 +	automatically does an <command role="hg-cmd">hg add</command>
   5.146 +	of the imported patch.</para>
   5.147 +
   5.148 +    </sect2>
   5.149 +    <sect2>
   5.150 +      <title><command role="hg-ext-mq">qinit</command>&emdash;prepare
   5.151 +	a repository to work with MQ</title>
   5.152 +
   5.153 +      <para>The <command role="hg-ext-mq">qinit</command> command
   5.154 +	prepares a repository to work with MQ.  It creates a directory
   5.155 +	called <filename role="special"
   5.156 +	  class="directory">.hg/patches</filename>.</para>
   5.157 +
   5.158 +      <para>Options:</para>
   5.159 +      <itemizedlist>
   5.160 +	<listitem><para><option
   5.161 +	      role="hg-ext-mq-cmd-qinit-opt">-c</option>: Create
   5.162 +	    <filename role="special"
   5.163 +	      class="directory">.hg/patches</filename> as a repository
   5.164 +	    in its own right.  Also creates a <filename
   5.165 +	      role="special">.hgignore</filename> file that will
   5.166 +	    ignore the <filename role="special">status</filename>
   5.167 +	    file.</para>
   5.168 +	</listitem></itemizedlist>
   5.169 +
   5.170 +      <para>When the <filename role="special"
   5.171 +	  class="directory">.hg/patches</filename> directory is a
   5.172 +	repository, the <command role="hg-ext-mq">qimport</command>
   5.173 +	and <command role="hg-ext-mq">qnew</command> commands
   5.174 +	automatically <command role="hg-cmd">hg add</command> new
   5.175 +	patches.</para>
   5.176 +
   5.177 +    </sect2>
   5.178 +    <sect2>
   5.179 +      <title><command role="hg-ext-mq">qnew</command>&emdash;create a
   5.180 +	new patch</title>
   5.181 +
   5.182 +      <para>The <command role="hg-ext-mq">qnew</command> command
   5.183 +	creates a new patch.  It takes one mandatory argument, the
   5.184 +	name to use for the patch file.  The newly created patch is
   5.185 +	created empty by default.  It is added to the <filename
   5.186 +	  role="special">series</filename> file after the current
   5.187 +	topmost applied patch, and is immediately pushed on top of
   5.188 +	that patch.</para>
   5.189 +
   5.190 +      <para>If <command role="hg-ext-mq">qnew</command> finds modified
   5.191 +	files in the working directory, it will refuse to create a new
   5.192 +	patch unless the <option
   5.193 +	  role="hg-ext-mq-cmd-qnew-opt">-f</option> option is used
   5.194 +	(see below).  This behaviour allows you to <command
   5.195 +	  role="hg-ext-mq">qrefresh</command> your topmost applied
   5.196 +	patch before you apply a new patch on top of it.</para>
   5.197 +
   5.198 +      <para>Options:</para>
   5.199 +      <itemizedlist>
   5.200 +	<listitem><para><option
   5.201 +	      role="hg-ext-mq-cmd-qnew-opt">-f</option>: Create a new
   5.202 +	    patch if the contents of the working directory are
   5.203 +	    modified.  Any outstanding modifications are added to the
   5.204 +	    newly created patch, so after this command completes, the
   5.205 +	    working directory will no longer be modified.</para>
   5.206 +	</listitem>
   5.207 +	<listitem><para><option
   5.208 +	      role="hg-ext-mq-cmd-qnew-opt">-m</option>: Use the given
   5.209 +	    text as the commit message. This text will be stored at
   5.210 +	    the beginning of the patch file, before the patch
   5.211 +	    data.</para>
   5.212 +	</listitem></itemizedlist>
   5.213 +
   5.214 +    </sect2>
   5.215 +    <sect2>
   5.216 +      <title><command role="hg-ext-mq">qnext</command>&emdash;print
   5.217 +	the name of the next patch</title>
   5.218 +
   5.219 +      <para>The <command role="hg-ext-mq">qnext</command> command
   5.220 +	prints the name name of the next patch in the <filename
   5.221 +	  role="special">series</filename> file after the topmost
   5.222 +	applied patch.  This patch will become the topmost applied
   5.223 +	patch if you run <command
   5.224 +	  role="hg-ext-mq">qpush</command>.</para>
   5.225 +
   5.226 +    </sect2>
   5.227 +    <sect2>
   5.228 +      <title><command role="hg-ext-mq">qpop</command>&emdash;pop
   5.229 +	patches off the stack</title>
   5.230 +
   5.231 +      <para>The <command role="hg-ext-mq">qpop</command> command
   5.232 +	removes applied patches from the top of the stack of applied
   5.233 +	patches.  By default, it removes only one patch.</para>
   5.234 +
   5.235 +      <para>This command removes the changesets that represent the
   5.236 +	popped patches from the repository, and updates the working
   5.237 +	directory to undo the effects of the patches.</para>
   5.238 +
   5.239 +      <para>This command takes an optional argument, which it uses as
   5.240 +	the name or index of the patch to pop to.  If given a name, it
   5.241 +	will pop patches until the named patch is the topmost applied
   5.242 +	patch.  If given a number, <command
   5.243 +	  role="hg-ext-mq">qpop</command> treats the number as an
   5.244 +	index into the entries in the series file, counting from zero
   5.245 +	(empty lines and lines containing only comments do not count).
   5.246 +	It pops patches until the patch identified by the given index
   5.247 +	is the topmost applied patch.</para>
   5.248 +
   5.249 +      <para>The <command role="hg-ext-mq">qpop</command> command does
   5.250 +	not read or write patches or the <filename
   5.251 +	  role="special">series</filename> file.  It is thus safe to
   5.252 +	<command role="hg-ext-mq">qpop</command> a patch that you have
   5.253 +	removed from the <filename role="special">series</filename>
   5.254 +	file, or a patch that you have renamed or deleted entirely.
   5.255 +	In the latter two cases, use the name of the patch as it was
   5.256 +	when you applied it.</para>
   5.257 +
   5.258 +      <para>By default, the <command role="hg-ext-mq">qpop</command>
   5.259 +	command will not pop any patches if the working directory has
   5.260 +	been modified.  You can override this behaviour using the
   5.261 +	<option role="hg-ext-mq-cmd-qpop-opt">-f</option> option,
   5.262 +	which reverts all modifications in the working
   5.263 +	directory.</para>
   5.264 +
   5.265 +      <para>Options:</para>
   5.266 +      <itemizedlist>
   5.267 +	<listitem><para><option
   5.268 +	      role="hg-ext-mq-cmd-qpop-opt">-a</option>: Pop all
   5.269 +	    applied patches.  This returns the repository to its state
   5.270 +	    before you applied any patches.</para>
   5.271 +	</listitem>
   5.272 +	<listitem><para><option
   5.273 +	      role="hg-ext-mq-cmd-qpop-opt">-f</option>: Forcibly
   5.274 +	    revert any modifications to the working directory when
   5.275 +	    popping.</para>
   5.276 +	</listitem>
   5.277 +	<listitem><para><option
   5.278 +	      role="hg-ext-mq-cmd-qpop-opt">-n</option>: Pop a patch
   5.279 +	    from the named queue.</para>
   5.280 +	</listitem></itemizedlist>
   5.281 +
   5.282 +      <para>The <command role="hg-ext-mq">qpop</command> command
   5.283 +	removes one line from the end of the <filename
   5.284 +	  role="special">status</filename> file for each patch that it
   5.285 +	pops.</para>
   5.286 +
   5.287 +    </sect2>
   5.288 +    <sect2>
   5.289 +      <title><command role="hg-ext-mq">qprev</command>&emdash;print
   5.290 +	the name of the previous patch</title>
   5.291 +
   5.292 +      <para>The <command role="hg-ext-mq">qprev</command> command
   5.293 +	prints the name of the patch in the <filename
   5.294 +	  role="special">series</filename> file that comes before the
   5.295 +	topmost applied patch. This will become the topmost applied
   5.296 +	patch if you run <command
   5.297 +	  role="hg-ext-mq">qpop</command>.</para>
   5.298 +
   5.299 +    </sect2>
   5.300 +    <sect2 id="sec:mqref:cmd:qpush">
   5.301 +      <title><command role="hg-ext-mq">qpush</command>&emdash;push
   5.302 +	patches onto the stack</title>
   5.303 +
   5.304 +      <para>The <command role="hg-ext-mq">qpush</command> command adds
   5.305 +	patches onto the applied stack.  By default, it adds only one
   5.306 +	patch.</para>
   5.307 +
   5.308 +      <para>This command creates a new changeset to represent each
   5.309 +	applied patch, and updates the working directory to apply the
   5.310 +	effects of the patches.</para>
   5.311 +
   5.312 +      <para>The default data used when creating a changeset are as
   5.313 +	follows:</para>
   5.314 +      <itemizedlist>
   5.315 +	<listitem><para>The commit date and time zone are the current
   5.316 +	    date and time zone.  Because these data are used to
   5.317 +	    compute the identity of a changeset, this means that if
   5.318 +	    you <command role="hg-ext-mq">qpop</command> a patch and
   5.319 +	    <command role="hg-ext-mq">qpush</command> it again, the
   5.320 +	    changeset that you push will have a different identity
   5.321 +	    than the changeset you popped.</para>
   5.322 +	</listitem>
   5.323 +	<listitem><para>The author is the same as the default used by
   5.324 +	    the <command role="hg-cmd">hg commit</command>
   5.325 +	    command.</para>
   5.326 +	</listitem>
   5.327 +	<listitem><para>The commit message is any text from the patch
   5.328 +	    file that comes before the first diff header.  If there is
   5.329 +	    no such text, a default commit message is used that
   5.330 +	    identifies the name of the patch.</para>
   5.331 +	</listitem></itemizedlist>
   5.332 +      <para>If a patch contains a Mercurial patch header (XXX add
   5.333 +	link), the information in the patch header overrides these
   5.334 +	defaults.</para>
   5.335 +
   5.336 +      <para>Options:</para>
   5.337 +      <itemizedlist>
   5.338 +	<listitem><para><option
   5.339 +	      role="hg-ext-mq-cmd-qpush-opt">-a</option>: Push all
   5.340 +	    unapplied patches from the <filename
   5.341 +	      role="special">series</filename> file until there are
   5.342 +	    none left to push.</para>
   5.343 +	</listitem>
   5.344 +	<listitem><para><option
   5.345 +	      role="hg-ext-mq-cmd-qpush-opt">-l</option>: Add the name
   5.346 +	    of the patch to the end of the commit message.</para>
   5.347 +	</listitem>
   5.348 +	<listitem><para><option
   5.349 +	      role="hg-ext-mq-cmd-qpush-opt">-m</option>: If a patch
   5.350 +	    fails to apply cleanly, use the entry for the patch in
   5.351 +	    another saved queue to compute the parameters for a
   5.352 +	    three-way merge, and perform a three-way merge using the
   5.353 +	    normal Mercurial merge machinery.  Use the resolution of
   5.354 +	    the merge as the new patch content.</para>
   5.355 +	</listitem>
   5.356 +	<listitem><para><option
   5.357 +	      role="hg-ext-mq-cmd-qpush-opt">-n</option>: Use the
   5.358 +	    named queue if merging while pushing.</para>
   5.359 +	</listitem></itemizedlist>
   5.360 +
   5.361 +      <para>The <command role="hg-ext-mq">qpush</command> command
   5.362 +	reads, but does not modify, the <filename
   5.363 +	  role="special">series</filename> file.  It appends one line
   5.364 +	to the <command role="hg-cmd">hg status</command> file for
   5.365 +	each patch that it pushes.</para>
   5.366 +
   5.367 +    </sect2>
   5.368 +    <sect2>
   5.369 +      <title><command
   5.370 +	  role="hg-ext-mq">qrefresh</command>&emdash;update the
   5.371 +	topmost applied patch</title>
   5.372 +
   5.373 +      <para>The <command role="hg-ext-mq">qrefresh</command> command
   5.374 +	updates the topmost applied patch.  It modifies the patch,
   5.375 +	removes the old changeset that represented the patch, and
   5.376 +	creates a new changeset to represent the modified
   5.377 +	patch.</para>
   5.378 +
   5.379 +      <para>The <command role="hg-ext-mq">qrefresh</command> command
   5.380 +	looks for the following modifications:</para>
   5.381 +      <itemizedlist>
   5.382 +	<listitem><para>Changes to the commit message, i.e. the text
   5.383 +	    before the first diff header in the patch file, are
   5.384 +	    reflected in the new changeset that represents the
   5.385 +	    patch.</para>
   5.386 +	</listitem>
   5.387 +	<listitem><para>Modifications to tracked files in the working
   5.388 +	    directory are added to the patch.</para>
   5.389 +	</listitem>
   5.390 +	<listitem><para>Changes to the files tracked using <command
   5.391 +	      role="hg-cmd">hg add</command>, <command
   5.392 +	      role="hg-cmd">hg copy</command>, <command
   5.393 +	      role="hg-cmd">hg remove</command>, or <command
   5.394 +	      role="hg-cmd">hg rename</command>.  Added files and copy
   5.395 +	    and rename destinations are added to the patch, while
   5.396 +	    removed files and rename sources are removed.</para>
   5.397 +	</listitem></itemizedlist>
   5.398 +
   5.399 +      <para>Even if <command role="hg-ext-mq">qrefresh</command>
   5.400 +	detects no changes, it still recreates the changeset that
   5.401 +	represents the patch.  This causes the identity of the
   5.402 +	changeset to differ from the previous changeset that
   5.403 +	identified the patch.</para>
   5.404 +
   5.405 +      <para>Options:</para>
   5.406 +      <itemizedlist>
   5.407 +	<listitem><para><option
   5.408 +	      role="hg-ext-mq-cmd-qrefresh-opt">-e</option>: Modify
   5.409 +	    the commit and patch description, using the preferred text
   5.410 +	    editor.</para>
   5.411 +	</listitem>
   5.412 +	<listitem><para><option
   5.413 +	      role="hg-ext-mq-cmd-qrefresh-opt">-m</option>: Modify
   5.414 +	    the commit message and patch description, using the given
   5.415 +	    text.</para>
   5.416 +	</listitem>
   5.417 +	<listitem><para><option
   5.418 +	      role="hg-ext-mq-cmd-qrefresh-opt">-l</option>: Modify
   5.419 +	    the commit message and patch description, using text from
   5.420 +	    the given file.</para>
   5.421 +	</listitem></itemizedlist>
   5.422 +
   5.423 +    </sect2>
   5.424 +    <sect2>
   5.425 +      <title><command role="hg-ext-mq">qrename</command>&emdash;rename
   5.426 +	a patch</title>
   5.427 +
   5.428 +      <para>The <command role="hg-ext-mq">qrename</command> command
   5.429 +	renames a patch, and changes the entry for the patch in the
   5.430 +	<filename role="special">series</filename> file.</para>
   5.431 +
   5.432 +      <para>With a single argument, <command
   5.433 +	  role="hg-ext-mq">qrename</command> renames the topmost
   5.434 +	applied patch.  With two arguments, it renames its first
   5.435 +	argument to its second.</para>
   5.436 +
   5.437 +    </sect2>
   5.438 +    <sect2>
   5.439 +      <title><command
   5.440 +	  role="hg-ext-mq">qrestore</command>&emdash;restore saved
   5.441 +	queue state</title>
   5.442 +
   5.443 +      <para>XXX No idea what this does.</para>
   5.444 +
   5.445 +    </sect2>
   5.446 +    <sect2>
   5.447 +      <title><command role="hg-ext-mq">qsave</command>&emdash;save
   5.448 +	current queue state</title>
   5.449 +
   5.450 +      <para>XXX Likewise.</para>
   5.451 +
   5.452 +    </sect2>
   5.453 +    <sect2>
   5.454 +      <title><command role="hg-ext-mq">qseries</command>&emdash;print
   5.455 +	the entire patch series</title>
   5.456 +
   5.457 +      <para>The <command role="hg-ext-mq">qseries</command> command
   5.458 +	prints the entire patch series from the <filename
   5.459 +	  role="special">series</filename> file.  It prints only patch
   5.460 +	names, not empty lines or comments.  It prints in order from
   5.461 +	first to be applied to last.</para>
   5.462 +
   5.463 +    </sect2>
   5.464 +    <sect2>
   5.465 +      <title><command role="hg-ext-mq">qtop</command>&emdash;print the
   5.466 +	name of the current patch</title>
   5.467 +
   5.468 +      <para>The <command role="hg-ext-mq">qtop</command> prints the
   5.469 +	name of the topmost currently applied patch.</para>
   5.470 +
   5.471 +    </sect2>
   5.472 +    <sect2>
   5.473 +      <title><command
   5.474 +	  role="hg-ext-mq">qunapplied</command>&emdash;print patches
   5.475 +	not yet applied</title>
   5.476 +
   5.477 +      <para>The <command role="hg-ext-mq">qunapplied</command> command
   5.478 +	prints the names of patches from the <filename
   5.479 +	  role="special">series</filename> file that are not yet
   5.480 +	applied.  It prints them in order from the next patch that
   5.481 +	will be pushed to the last.</para>
   5.482 +
   5.483 +    </sect2>
   5.484 +    <sect2>
   5.485 +      <title><command role="hg-cmd">hg strip</command>&emdash;remove a
   5.486 +	revision and descendants</title>
   5.487 +
   5.488 +      <para>The <command role="hg-cmd">hg strip</command> command
   5.489 +	removes a revision, and all of its descendants, from the
   5.490 +	repository.  It undoes the effects of the removed revisions
   5.491 +	from the repository, and updates the working directory to the
   5.492 +	first parent of the removed revision.</para>
   5.493 +
   5.494 +      <para>The <command role="hg-cmd">hg strip</command> command
   5.495 +	saves a backup of the removed changesets in a bundle, so that
   5.496 +	they can be reapplied if removed in error.</para>
   5.497 +
   5.498 +      <para>Options:</para>
   5.499 +      <itemizedlist>
   5.500 +	<listitem><para><option role="hg-opt-strip">-b</option>: Save
   5.501 +	    unrelated changesets that are intermixed with the stripped
   5.502 +	    changesets in the backup bundle.</para>
   5.503 +	</listitem>
   5.504 +	<listitem><para><option role="hg-opt-strip">-f</option>: If a
   5.505 +	    branch has multiple heads, remove all heads. XXX This
   5.506 +	    should be renamed, and use <literal>-f</literal> to strip
   5.507 +	    revs when there are pending changes.</para>
   5.508 +	</listitem>
   5.509 +	<listitem><para><option role="hg-opt-strip">-n</option>: Do
   5.510 +	    not save a backup bundle.</para>
   5.511 +	</listitem></itemizedlist>
   5.512 +
   5.513 +    </sect2>
   5.514 +  </sect1>
   5.515 +  <sect1>
   5.516 +    <title>MQ file reference</title>
   5.517 +
   5.518 +    <sect2>
   5.519 +      <title>The <filename role="special">series</filename>
   5.520 +	file</title>
   5.521 +
   5.522 +      <para>The <filename role="special">series</filename> file
   5.523 +	contains a list of the names of all patches that MQ can apply.
   5.524 +	It is represented as a list of names, with one name saved per
   5.525 +	line.  Leading and trailing white space in each line are
   5.526 +	ignored.</para>
   5.527 +
   5.528 +      <para>Lines may contain comments.  A comment begins with the
   5.529 +	<quote><literal>#</literal></quote> character, and extends to
   5.530 +	the end of the line.  Empty lines, and lines that contain only
   5.531 +	comments, are ignored.</para>
   5.532 +
   5.533 +      <para>You will often need to edit the <filename
   5.534 +	  role="special">series</filename> file by hand, hence the
   5.535 +	support for comments and empty lines noted above.  For
   5.536 +	example, you can comment out a patch temporarily, and <command
   5.537 +	  role="hg-ext-mq">qpush</command> will skip over that patch
   5.538 +	when applying patches.  You can also change the order in which
   5.539 +	patches are applied by reordering their entries in the
   5.540 +	<filename role="special">series</filename> file.</para>
   5.541 +
   5.542 +      <para>Placing the <filename role="special">series</filename>
   5.543 +	file under revision control is also supported; it is a good
   5.544 +	idea to place all of the patches that it refers to under
   5.545 +	revision control, as well.  If you create a patch directory
   5.546 +	using the <option role="hg-ext-mq-cmd-qinit-opt">-c</option>
   5.547 +	option to <command role="hg-ext-mq">qinit</command>, this will
   5.548 +	be done for you automatically.</para>
   5.549 +
   5.550 +    </sect2>
   5.551 +    <sect2>
   5.552 +      <title>The <filename role="special">status</filename>
   5.553 +	file</title>
   5.554 +
   5.555 +      <para>The <filename role="special">status</filename> file
   5.556 +	contains the names and changeset hashes of all patches that MQ
   5.557 +	currently has applied.  Unlike the <filename
   5.558 +	  role="special">series</filename> file, this file is not
   5.559 +	intended for editing.  You should not place this file under
   5.560 +	revision control, or modify it in any way.  It is used by MQ
   5.561 +	strictly for internal book-keeping.</para>
   5.562 +
   5.563 +    </sect2>
   5.564 +  </sect1>
   5.565 +</appendix>
   5.566 +
   5.567 +<!--
   5.568 +local variables: 
   5.569 +sgml-parent-document: ("00book.xml" "book" "appendix")
   5.570 +end:
   5.571 +-->

     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/en/appC-srcinstall.xml	Wed Feb 18 00:22:09 2009 -0800
     6.3 @@ -0,0 +1,65 @@
     6.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     6.5 +
     6.6 +<appendix id="chap:srcinstall">
     6.7 +  <title>Installing Mercurial from source</title>
     6.8 +
     6.9 +  <sect1 id="sec:srcinstall:unixlike">
    6.10 +    <title>On a Unix-like system</title>
    6.11 +
    6.12 +    <para>If you are using a Unix-like system that has a sufficiently
    6.13 +      recent version of Python (2.3 or newer) available, it is easy to
    6.14 +      install Mercurial from source.</para>
    6.15 +    <orderedlist>
    6.16 +      <listitem><para>Download a recent source tarball from <ulink
    6.17 +	    url="http://www.selenic.com/mercurial/download">http://www.selenic.com/mercurial/download</ulink>.</para>
    6.18 +      </listitem>
    6.19 +      <listitem><para>Unpack the tarball:</para>
    6.20 +	<programlisting>gzip -dc mercurial-MYVERSION.tar.gz | tar xf -</programlisting>
    6.21 +      </listitem>
    6.22 +      <listitem><para>Go into the source directory and run the
    6.23 +	  installer script.  This will build Mercurial and install it
    6.24 +	  in your home directory.</para>
    6.25 +	<programlisting>cd mercurial-MYVERSION
    6.26 +python setup.py install --force --home=$HOME</programlisting>
    6.27 +      </listitem>
    6.28 +    </orderedlist>
    6.29 +    <para>Once the install finishes, Mercurial will be in the
    6.30 +      <literal>bin</literal> subdirectory of your home directory.
    6.31 +      Don't forget to make sure that this directory is present in your
    6.32 +      shell's search path.</para>
    6.33 +
    6.34 +    <para>You will probably need to set the <envar>PYTHONPATH</envar>
    6.35 +      environment variable so that the Mercurial executable can find
    6.36 +      the rest of the Mercurial packages.  For example, on my laptop,
    6.37 +      I have set it to <literal>/home/bos/lib/python</literal>.  The
    6.38 +      exact path that you will need to use depends on how Python was
    6.39 +      built for your system, but should be easy to figure out.  If
    6.40 +      you're uncertain, look through the output of the installer
    6.41 +      script above, and see where the contents of the
    6.42 +      <literal>mercurial</literal> directory were installed to.</para>
    6.43 +
    6.44 +  </sect1>
    6.45 +  <sect1>
    6.46 +    <title>On Windows</title>
    6.47 +
    6.48 +    <para>Building and installing Mercurial on Windows requires a
    6.49 +      variety of tools, a fair amount of technical knowledge, and
    6.50 +      considerable patience.  I very much <emphasis>do not
    6.51 +	recommend</emphasis> this route if you are a <quote>casual
    6.52 +	user</quote>.  Unless you intend to hack on Mercurial, I
    6.53 +      strongly suggest that you use a binary package instead.</para>
    6.54 +
    6.55 +    <para>If you are intent on building Mercurial from source on
    6.56 +      Windows, follow the <quote>hard way</quote> directions on the
    6.57 +      Mercurial wiki at <ulink
    6.58 +	url="http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall">http://www.selenic.com/mercurial/wiki/index.cgi/WindowsInstall</ulink>, 
    6.59 +      and expect the process to involve a lot of fiddly work.</para>
    6.60 +
    6.61 +  </sect1>
    6.62 +</appendix>
    6.63 +
    6.64 +<!--
    6.65 +local variables: 
    6.66 +sgml-parent-document: ("00book.xml" "book" "appendix")
    6.67 +end:
    6.68 +-->

     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/en/appD-license.xml	Wed Feb 18 00:22:09 2009 -0800
     7.3 @@ -0,0 +1,178 @@
     7.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     7.5 +
     7.6 +<appendix id="cha:opl">
     7.7 +  <title>Open Publication License</title>
     7.8 +
     7.9 +  <para>Version 1.0, 8 June 1999</para>
    7.10 +
    7.11 +  <sect1>
    7.12 +    <title>Requirements on both unmodified and modified
    7.13 +      versions</title>
    7.14 +
    7.15 +    <para>The Open Publication works may be reproduced and distributed
    7.16 +      in whole or in part, in any medium physical or electronic,
    7.17 +      provided that the terms of this license are adhered to, and that
    7.18 +      this license or an incorporation of it by reference (with any
    7.19 +      options elected by the author(s) and/or publisher) is displayed
    7.20 +      in the reproduction.</para>
    7.21 +
    7.22 +    <para>Proper form for an incorporation by reference is as
    7.23 +      follows:</para>
    7.24 +
    7.25 +    <blockquote>
    7.26 +      <para>  Copyright (c) <emphasis>year</emphasis> by
    7.27 +	<emphasis>author's name or designee</emphasis>. This material
    7.28 +	may be distributed only subject to the terms and conditions
    7.29 +	set forth in the Open Publication License,
    7.30 +	v<emphasis>x.y</emphasis> or later (the latest version is
    7.31 +	presently available at <ulink
    7.32 +	  url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para>
    7.33 +    </blockquote>
    7.34 +
    7.35 +    <para>The reference must be immediately followed with any options
    7.36 +      elected by the author(s) and/or publisher of the document (see
    7.37 +      section <xref linkend="sec:opl:options"/>).</para>
    7.38 +
    7.39 +    <para>Commercial redistribution of Open Publication-licensed
    7.40 +      material is permitted.</para>
    7.41 +
    7.42 +    <para>Any publication in standard (paper) book form shall require
    7.43 +      the citation of the original publisher and author. The publisher
    7.44 +      and author's names shall appear on all outer surfaces of the
    7.45 +      book. On all outer surfaces of the book the original publisher's
    7.46 +      name shall be as large as the title of the work and cited as
    7.47 +      possessive with respect to the title.</para>
    7.48 +
    7.49 +  </sect1>
    7.50 +  <sect1>
    7.51 +    <title>Copyright</title>
    7.52 +
    7.53 +    <para>The copyright to each Open Publication is owned by its
    7.54 +      author(s) or designee.</para>
    7.55 +
    7.56 +  </sect1>
    7.57 +  <sect1>
    7.58 +    <title>Scope of license</title>
    7.59 +
    7.60 +    <para>The following license terms apply to all Open Publication
    7.61 +      works, unless otherwise explicitly stated in the
    7.62 +      document.</para>
    7.63 +
    7.64 +    <para>Mere aggregation of Open Publication works or a portion of
    7.65 +      an Open Publication work with other works or programs on the
    7.66 +      same media shall not cause this license to apply to those other
    7.67 +      works. The aggregate work shall contain a notice specifying the
    7.68 +      inclusion of the Open Publication material and appropriate
    7.69 +      copyright notice.</para>
    7.70 +
    7.71 +    <para><emphasis role="bold">Severability</emphasis>. If any part
    7.72 +      of this license is found to be unenforceable in any
    7.73 +      jurisdiction, the remaining portions of the license remain in
    7.74 +      force.</para>
    7.75 +
    7.76 +    <para><emphasis role="bold">No warranty</emphasis>. Open
    7.77 +      Publication works are licensed and provided <quote>as is</quote>
    7.78 +      without warranty of any kind, express or implied, including, but
    7.79 +      not limited to, the implied warranties of merchantability and
    7.80 +      fitness for a particular purpose or a warranty of
    7.81 +      non-infringement.</para>
    7.82 +
    7.83 +  </sect1>
    7.84 +  <sect1>
    7.85 +    <title>Requirements on modified works</title>
    7.86 +
    7.87 +    <para>All modified versions of documents covered by this license,
    7.88 +      including translations, anthologies, compilations and partial
    7.89 +      documents, must meet the following requirements:</para>
    7.90 +
    7.91 +    <orderedlist>
    7.92 +      <listitem><para>The modified version must be labeled as
    7.93 +	  such.</para>
    7.94 +      </listitem>
    7.95 +      <listitem><para>The person making the modifications must be
    7.96 +	  identified and the modifications dated.</para>
    7.97 +      </listitem>
    7.98 +      <listitem><para>Acknowledgement of the original author and
    7.99 +	  publisher if applicable must be retained according to normal
   7.100 +	  academic citation practices.</para>
   7.101 +      </listitem>
   7.102 +      <listitem><para>The location of the original unmodified document
   7.103 +	  must be identified.</para>
   7.104 +      </listitem>
   7.105 +      <listitem><para>The original author's (or authors') name(s) may
   7.106 +	  not be used to assert or imply endorsement of the resulting
   7.107 +	  document without the original author's (or authors')
   7.108 +	  permission.</para>
   7.109 +      </listitem></orderedlist>
   7.110 +
   7.111 +  </sect1>
   7.112 +  <sect1>
   7.113 +    <title>Good-practice recommendations</title>
   7.114 +
   7.115 +    <para>In addition to the requirements of this license, it is
   7.116 +      requested from and strongly recommended of redistributors
   7.117 +      that:</para>
   7.118 +
   7.119 +    <orderedlist>
   7.120 +      <listitem><para>If you are distributing Open Publication works
   7.121 +	  on hardcopy or CD-ROM, you provide email notification to the
   7.122 +	  authors of your intent to redistribute at least thirty days
   7.123 +	  before your manuscript or media freeze, to give the authors
   7.124 +	  time to provide updated documents. This notification should
   7.125 +	  describe modifications, if any, made to the document.</para>
   7.126 +      </listitem>
   7.127 +      <listitem><para>All substantive modifications (including
   7.128 +	  deletions) be either clearly marked up in the document or
   7.129 +	  else described in an attachment to the document.</para>
   7.130 +      </listitem>
   7.131 +      <listitem><para>Finally, while it is not mandatory under this
   7.132 +	  license, it is considered good form to offer a free copy of
   7.133 +	  any hardcopy and CD-ROM expression of an Open
   7.134 +	  Publication-licensed work to its author(s).</para>
   7.135 +      </listitem></orderedlist>
   7.136 +
   7.137 +  </sect1>
   7.138 +  <sect1 id="sec:opl:options">
   7.139 +    <title>License options</title>
   7.140 +
   7.141 +    <para>The author(s) and/or publisher of an Open
   7.142 +      Publication-licensed document may elect certain options by
   7.143 +      appending language to the reference to or copy of the license.
   7.144 +      These options are considered part of the license instance and
   7.145 +      must be included with the license (or its incorporation by
   7.146 +      reference) in derived works.</para>
   7.147 +
   7.148 +    <orderedlist>
   7.149 +      <listitem><para>To prohibit distribution of substantively
   7.150 +	  modified versions without the explicit permission of the
   7.151 +	  author(s). <quote>Substantive modification</quote> is
   7.152 +	  defined as a change to the semantic content of the document,
   7.153 +	  and excludes mere changes in format or typographical
   7.154 +	  corrections.</para>
   7.155 +      </listitem>
   7.156 +      <listitem><para>  To accomplish this, add the phrase
   7.157 +	  <quote>Distribution of substantively modified versions of
   7.158 +	    this document is prohibited without the explicit
   7.159 +	    permission of the copyright holder.</quote> to the license
   7.160 +	  reference or copy.</para>
   7.161 +      </listitem>
   7.162 +      <listitem><para>To prohibit any publication of this work or
   7.163 +	  derivative works in whole or in part in standard (paper)
   7.164 +	  book form for commercial purposes is prohibited unless prior
   7.165 +	  permission is obtained from the copyright holder.</para>
   7.166 +      </listitem>
   7.167 +      <listitem><para>To accomplish this, add the phrase
   7.168 +	  <quote>Distribution of the work or derivative of the work in
   7.169 +	    any standard (paper) book form is prohibited unless prior
   7.170 +	    permission is obtained from the copyright holder.</quote>
   7.171 +	  to the license reference or copy.</para>
   7.172 +      </listitem></orderedlist>
   7.173 +
   7.174 +  </sect1>
   7.175 +</appendix>
   7.176 +
   7.177 +<!--
   7.178 +local variables: 
   7.179 +sgml-parent-document: ("00book.xml" "book" "appendix")
   7.180 +end:
   7.181 +-->

     8.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     8.2 +++ b/en/ch00-preface.xml	Wed Feb 18 00:22:09 2009 -0800
     8.3 @@ -0,0 +1,80 @@
     8.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     8.5 +
     8.6 +<preface id="chap:preface">
     8.7 +  <title>Preface</title>
     8.8 +
     8.9 +  <para>Distributed revision control is a relatively new territory,
    8.10 +    and has thus far grown due to people's willingness to strike out
    8.11 +    into ill-charted territory.</para>
    8.12 +
    8.13 +  <para>I am writing a book about distributed revision control because
    8.14 +    I believe that it is an important subject that deserves a field
    8.15 +    guide. I chose to write about Mercurial because it is the easiest
    8.16 +    tool to learn the terrain with, and yet it scales to the demands
    8.17 +    of real, challenging environments where many other revision
    8.18 +    control tools fail.</para>
    8.19 +
    8.20 +  <sect1>
    8.21 +    <title>This book is a work in progress</title>
    8.22 +
    8.23 +    <para>I am releasing this book while I am still writing it, in the
    8.24 +      hope that it will prove useful to others.  I also hope that
    8.25 +      readers will contribute as they see fit.</para>
    8.26 +
    8.27 +  </sect1>
    8.28 +  <sect1>
    8.29 +    <title>About the examples in this book</title>
    8.30 +
    8.31 +    <para>This book takes an unusual approach to code samples.  Every
    8.32 +      example is <quote>live</quote>---each one is actually the result
    8.33 +      of a shell script that executes the Mercurial commands you see.
    8.34 +      Every time an image of the book is built from its sources, all
    8.35 +      the example scripts are automatically run, and their current
    8.36 +      results compared against their expected results.</para>
    8.37 +
    8.38 +    <para>The advantage of this approach is that the examples are
    8.39 +      always accurate; they describe <emphasis>exactly</emphasis> the
    8.40 +      behaviour of the version of Mercurial that's mentioned at the
    8.41 +      front of the book.  If I update the version of Mercurial that
    8.42 +      I'm documenting, and the output of some command changes, the
    8.43 +      build fails.</para>
    8.44 +
    8.45 +    <para>There is a small disadvantage to this approach, which is
    8.46 +      that the dates and times you'll see in examples tend to be
    8.47 +      <quote>squashed</quote> together in a way that they wouldn't be
    8.48 +      if the same commands were being typed by a human.  Where a human
    8.49 +      can issue no more than one command every few seconds, with any
    8.50 +      resulting timestamps correspondingly spread out, my automated
    8.51 +      example scripts run many commands in one second.</para>
    8.52 +
    8.53 +    <para>As an instance of this, several consecutive commits in an
    8.54 +      example can show up as having occurred during the same second.
    8.55 +      You can see this occur in the <literal
    8.56 +	role="hg-ext">bisect</literal> example in section <xref
    8.57 +	id="sec:undo:bisect"/>, for instance.</para>
    8.58 +
    8.59 +    <para>So when you're reading examples, don't place too much weight
    8.60 +      on the dates or times you see in the output of commands.  But
    8.61 +      <emphasis>do</emphasis> be confident that the behaviour you're
    8.62 +      seeing is consistent and reproducible.</para>
    8.63 +
    8.64 +  </sect1>
    8.65 +  <sect1>
    8.66 +    <title>Colophon---this book is Free</title>
    8.67 +
    8.68 +    <para>This book is licensed under the Open Publication License,
    8.69 +      and is produced entirely using Free Software tools.  It is
    8.70 +      typeset with \LaTeX{}; illustrations are drawn and rendered with
    8.71 +      <ulink url="http://www.inkscape.org/">Inkscape</ulink>.</para>
    8.72 +
    8.73 +    <para>The complete source code for this book is published as a
    8.74 +      Mercurial repository, at <ulink
    8.75 +	url="http://hg.serpentine.com/mercurial/book">http://hg.serpentine.com/mercurial/book</ulink>.</para>
    8.76 +
    8.77 +  </sect1>
    8.78 +</preface>
    8.79 +<!--
    8.80 +local variables: 
    8.81 +sgml-parent-document: ("00book.xml" "book" "preface")
    8.82 +end:
    8.83 +-->

     9.1 --- a/en/ch02-tour-basic.xml	Mon Feb 09 23:25:40 2009 -0800
     9.2 +++ b/en/ch02-tour-basic.xml	Wed Feb 18 00:22:09 2009 -0800
     9.3 @@ -1,12 +1,10 @@
     9.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     9.5  
     9.6 -<chapter>
     9.7 +<chapter id="chap:tour-basic">
     9.8    <title>A tour of Mercurial: the basics</title>
     9.9 -  <para>\label{chap:tour-basic}</para>
    9.10 -
    9.11 -  <sect1>
    9.12 +
    9.13 +  <sect1 id="sec:tour:install">
    9.14      <title>Installing Mercurial on your system</title>
    9.15 -    <para>\label{sec:tour:install}</para>
    9.16  
    9.17      <para>Prebuilt binary packages of Mercurial are available for
    9.18        every popular operating system.  These make it easy to start
    9.19 @@ -65,10 +63,10 @@
    9.20        <para>Lee Cantey publishes an installer of Mercurial for Mac OS
    9.21  	X at <ulink
    9.22  	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. 
    9.23 -	This package works on both Intel- and Power-based Macs.
    9.24 -	Before you can use it, you must install a compatible version
    9.25 -	of Universal MacPython <citation>web:macpython</citation>.
    9.26 -	This is easy to do; simply follow the instructions on Lee's
    9.27 +	This package works on both Intel- and Power-based Macs. Before
    9.28 +	you can use it, you must install a compatible version of
    9.29 +	Universal MacPython <citation>web:macpython</citation>. This
    9.30 +	is easy to do; simply follow the instructions on Lee's
    9.31  	site.</para>
    9.32  
    9.33        <para>It's also possible to install Mercurial using Fink or
    9.34 @@ -104,26 +102,31 @@
    9.35  	version</command> command to find out whether Mercurial is
    9.36        actually installed properly.  The actual version information
    9.37        that it prints isn't so important; it's whether it prints
    9.38 -      anything at all that we care about. <!--
    9.39 -      &interaction.tour.version; --></para>
    9.40 +      anything at all that we care about.</para>
    9.41 +
    9.42 +      <!-- &interaction.tour.version; -->
    9.43  
    9.44      <sect2>
    9.45        <title>Built-in help</title>
    9.46  
    9.47        <para>Mercurial provides a built-in help system.  This is
    9.48 -	invaluable for those times when you find yourself stuck trying
    9.49 -	to remember how to run a command.  If you are completely
    9.50 -	stuck, simply run <command role="hg-cmd">hg help</command>; it
    9.51 -	will print a brief list of commands, along with a description
    9.52 -	of what each does.  If you ask for help on a specific command
    9.53 -	(as below), it prints more detailed information. <!--
    9.54 -	&interaction.tour.help; --> For a more impressive level of
    9.55 -	detail (which you won't usually need) run <command
    9.56 -	  role="hg-cmd">hg help <option
    9.57 -	    role="hg-opt-global">-v</option></command>.  The <option
    9.58 -	  role="hg-opt-global">-v</option> option is short for <option
    9.59 -	  role="hg-opt-global">--verbose</option>, and tells Mercurial
    9.60 -	to print more information than it usually would.</para>
    9.61 +	  invaluable for those times when you find yourself stuck
    9.62 +	  trying to remember how to run a command.  If you are
    9.63 +	  completely stuck, simply run <command role="hg-cmd">hg
    9.64 +	    help</command>; it will print a brief list of commands,
    9.65 +	  along with a description of what each does.  If you ask for
    9.66 +	  help on a specific command (as below), it prints more
    9.67 +	  detailed information.</para>
    9.68 +
    9.69 +	<!-- &interaction.tour.help; -->
    9.70 +
    9.71 +	<para>For a more impressive level of detail (which you won't
    9.72 +	  usually need) run <command role="hg-cmd">hg help <option
    9.73 +	      role="hg-opt-global">-v</option></command>.  The <option
    9.74 +	    role="hg-opt-global">-v</option> option is short for
    9.75 +	  <option role="hg-opt-global">--verbose</option>, and tells
    9.76 +	  Mercurial to print more information than it usually
    9.77 +	  would.</para>
    9.78  
    9.79      </sect2>
    9.80    </sect1>
    9.81 @@ -150,13 +153,18 @@
    9.82  	command to make a copy of a repository, it's best to use a
    9.83  	built-in command that Mercurial provides.  This command is
    9.84  	called <command role="hg-cmd">hg clone</command>, because it
    9.85 -	creates an identical copy of an existing repository. <!--
    9.86 -	&interaction.tour.clone; --> If our clone succeeded, we should
    9.87 -	now have a local directory called <filename
    9.88 -	  class="directory">hello</filename>.  This directory will
    9.89 -	contain some files. <!-- &interaction.tour.ls; --> These files
    9.90 -	have the same contents and history in our repository as they
    9.91 -	do in the repository we cloned.</para>
    9.92 +	creates an identical copy of an existing repository.</para>
    9.93 +
    9.94 +      <!-- &interaction.tour.clone; -->
    9.95 +
    9.96 +      <para>If our clone succeeded, we should now have a local
    9.97 +	directory called <filename class="directory">hello</filename>.
    9.98 +	This directory will contain some files.</para>
    9.99 +
   9.100 +      <!-- &interaction.tour.ls; -->
   9.101 +
   9.102 +      <para>These files have the same contents and history in our
   9.103 +	repository as they do in the repository we cloned.</para>
   9.104  
   9.105        <para>Every Mercurial repository is complete, self-contained,
   9.106  	and independent.  It contains its own private copy of a
   9.107 @@ -176,8 +184,9 @@
   9.108        <para>When we take a more detailed look inside a repository, we
   9.109  	can see that it contains a directory named <filename
   9.110  	  class="directory">.hg</filename>.  This is where Mercurial
   9.111 -	keeps all of its metadata for the repository. <!--
   9.112 -	&interaction.tour.ls-a; --></para>
   9.113 +	keeps all of its metadata for the repository.</para>
   9.114 +
   9.115 +      <!-- &interaction.tour.ls-a; -->
   9.116  
   9.117        <para>The contents of the <filename
   9.118  	  class="directory">.hg</filename> directory and its
   9.119 @@ -205,10 +214,13 @@
   9.120      <para>One of the first things we might want to do with a new,
   9.121        unfamiliar repository is understand its history.  The <command
   9.122  	role="hg-cmd">hg log</command> command gives us a view of
   9.123 -      history. <!-- &interaction.tour.log; --> By default, this
   9.124 -      command prints a brief paragraph of output for each change to
   9.125 -      the project that was recorded.  In Mercurial terminology, we
   9.126 -      call each of these recorded events a
   9.127 +      history.</para>
   9.128 +
   9.129 +    <!-- &interaction.tour.log; -->
   9.130 +
   9.131 +    <para>By default, this command prints a brief paragraph of output
   9.132 +      for each change to the project that was recorded.  In Mercurial
   9.133 +      terminology, we call each of these recorded events a
   9.134        <emphasis>changeset</emphasis>, because it can contain a record
   9.135        of changes to several files.</para>
   9.136  
   9.137 @@ -310,18 +322,22 @@
   9.138  	  role="hg-opt-log">-r</option> (or <option
   9.139  	  role="hg-opt-log">--rev</option>) option.  You can use
   9.140  	either a revision number or a long-form changeset identifier,
   9.141 -	and you can provide as many revisions as you want.  <!--
   9.142 -	&interaction.tour.log-r; --></para>
   9.143 +	and you can provide as many revisions as you want.</para>
   9.144 +
   9.145 +      <!-- &interaction.tour.log-r; -->
   9.146  
   9.147        <para>If you want to see the history of several revisions
   9.148  	without having to list each one, you can use <emphasis>range
   9.149  	  notation</emphasis>; this lets you express the idea <quote>I
   9.150 -	  want all revisions between $a$ and $b$, inclusive</quote>.
   9.151 -	<!-- &interaction.tour.log.range; --> Mercurial also honours
   9.152 -	the order in which you specify revisions, so <command
   9.153 -	  role="hg-cmd">hg log -r 2:4</command> prints $2,3,4$ while
   9.154 -	<command role="hg-cmd">hg log -r 4:2</command> prints
   9.155 -	$4,3,2$.</para>
   9.156 +	  want all revisions between <literal>abc</literal> and
   9.157 +	  <literal>def</literal>, inclusive</quote>.</para>
   9.158 +      
   9.159 +	<!-- &interaction.tour.log.range; -->
   9.160 +
   9.161 +      <para>Mercurial also honours the order in which you specify
   9.162 +	revisions, so <command role="hg-cmd">hg log -r 2:4</command>
   9.163 +	prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
   9.164 +	  4:2</command> prints 4, 3, and 2.</para>
   9.165  
   9.166      </sect2>
   9.167      <sect2>
   9.168 @@ -335,7 +351,9 @@
   9.169  	looking for. The <command role="hg-cmd">hg log</command>
   9.170  	command's <option role="hg-opt-global">-v</option> (or <option
   9.171  	  role="hg-opt-global">--verbose</option>) option gives you
   9.172 -	this extra detail. <!-- &interaction.tour.log-v; --></para>
   9.173 +	this extra detail.</para>
   9.174 +
   9.175 +      <!-- &interaction.tour.log-v; -->
   9.176  
   9.177        <para>If you want to see both the description and content of a
   9.178  	change, add the <option role="hg-opt-log">-p</option> (or
   9.179 @@ -343,7 +361,9 @@
   9.180  	displays the content of a change as a <emphasis>unified
   9.181  	  diff</emphasis> (if you've never seen a unified diff before,
   9.182  	see section <xref linkend="sec:mq:patch"/> for an
   9.183 -	overview). <!-- &interaction.tour.log-vp; --></para>
   9.184 +	overview).</para>
   9.185 +
   9.186 +      <!-- &interaction.tour.log-vp; -->
   9.187  
   9.188      </sect2>
   9.189    </sect1>
   9.190 @@ -402,16 +422,18 @@
   9.191        the remote repository.  Since we already have a copy of it
   9.192        locally, we can just clone that instead.  This is much faster
   9.193        than cloning over the network, and cloning a local repository
   9.194 -      uses less disk space in most cases, too. <!--
   9.195 -      &interaction.tour.reclone; --> As an aside, it's often good
   9.196 -      practice to keep a <quote>pristine</quote> copy of a remote
   9.197 -      repository around, which you can then make temporary clones of
   9.198 -      to create sandboxes for each task you want to work on.  This
   9.199 -      lets you work on multiple tasks in parallel, each isolated from
   9.200 -      the others until it's complete and you're ready to integrate it
   9.201 -      back.  Because local clones are so cheap, there's almost no
   9.202 -      overhead to cloning and destroying repositories whenever you
   9.203 -      want.</para>
   9.204 +      uses less disk space in most cases, too.</para>
   9.205 +
   9.206 +    <!-- &interaction.tour.reclone; -->
   9.207 +
   9.208 +    <para>As an aside, it's often good practice to keep a
   9.209 +      <quote>pristine</quote> copy of a remote repository around,
   9.210 +      which you can then make temporary clones of to create sandboxes
   9.211 +      for each task you want to work on.  This lets you work on
   9.212 +      multiple tasks in parallel, each isolated from the others until
   9.213 +      it's complete and you're ready to integrate it back.  Because
   9.214 +      local clones are so cheap, there's almost no overhead to cloning
   9.215 +      and destroying repositories whenever you want.</para>
   9.216  
   9.217      <para>In our <filename class="directory">my-hello</filename>
   9.218        repository, we have a file <filename>hello.c</filename> that
   9.219 @@ -422,13 +444,18 @@
   9.220        to write a scripted example this way.  Since you're not under
   9.221        the same constraint, you probably won't want to use
   9.222        <command>sed</command>; simply use your preferred text editor to
   9.223 -      do the same thing.) <!-- &interaction.tour.sed; --></para>
   9.224 +      do the same thing.)</para>
   9.225 +
   9.226 +    <!-- &interaction.tour.sed; -->
   9.227  
   9.228      <para>Mercurial's <command role="hg-cmd">hg status</command>
   9.229        command will tell us what Mercurial knows about the files in the
   9.230 -      repository. <!-- &interaction.tour.status; --> The <command
   9.231 -	role="hg-cmd">hg status</command> command prints no output for
   9.232 -      some files, but a line starting with
   9.233 +      repository.</para>
   9.234 +
   9.235 +    <!-- &interaction.tour.status; -->
   9.236 +
   9.237 +    <para>The <command role="hg-cmd">hg status</command> command
   9.238 +      prints no output for some files, but a line starting with
   9.239        <quote><literal>M</literal></quote> for
   9.240        <filename>hello.c</filename>.  Unless you tell it to, <command
   9.241  	role="hg-cmd">hg status</command> will not print any output
   9.242 @@ -446,7 +473,9 @@
   9.243        <filename>hello.c</filename>, but we might prefer to know
   9.244        exactly <emphasis>what</emphasis> changes we've made to it.  To
   9.245        do this, we use the <command role="hg-cmd">hg diff</command>
   9.246 -      command. <!-- &interaction.tour.diff; --></para>
   9.247 +      command.</para>
   9.248 +
   9.249 +    <!-- &interaction.tour.diff; -->
   9.250  
   9.251    </sect1>
   9.252    <sect1>
   9.253 @@ -701,67 +730,70 @@
   9.254      <sect2>
   9.255        <title>Updating the working directory</title>
   9.256  
   9.257 -      <para>We have so far glossed over the relationship
   9.258 -	  between a repository and its working directory.  The
   9.259 -	  <command role="hg-cmd">hg pull</command> command that we ran
   9.260 -	  in section <xref linkend="sec:tour:pull"/> brought changes into
   9.261 -	  the
   9.262 -	  repository, but if we check, there's no sign of those
   9.263 -	  changes in the working directory.  This is because <command
   9.264 -	    role="hg-cmd">hg pull</command> does not (by default)
   9.265 -	  touch the working directory.  Instead, we use the <command
   9.266 -	    role="hg-cmd">hg update</command> command to do this. <!--
   9.267 -	  &interaction.tour.update; --></para>
   9.268 -      <para>It might seem a bit strange that <command
   9.269 -	    role="hg-cmd">hg pull</command> doesn't update the working
   9.270 -	  directory automatically.  There's actually a good reason for
   9.271 -	  this: you can use <command role="hg-cmd">hg update</command>
   9.272 -	  to update the working directory to the state it was in at
   9.273 -	  <emphasis>any revision</emphasis> in the history of the
   9.274 -	  repository.  If you had the working directory updated to an
   9.275 -	  old revision---to hunt down the origin of a bug, say---and
   9.276 -	  ran a <command role="hg-cmd">hg pull</command> which
   9.277 -	  automatically updated the working directory to a new
   9.278 -	  revision, you might not be terribly happy.</para>
   9.279 -      <para>However, since pull-then-update is such a common
   9.280 -	  thing to do, Mercurial lets you combine the two by passing
   9.281 -	  the <option role="hg-opt-pull">-u</option> option to
   9.282 -	  <command role="hg-cmd">hg
   9.283 -	    pull</command>.</para>
   9.284 +      <para>We have so far glossed over the relationship between a
   9.285 +	repository and its working directory.  The <command
   9.286 +	  role="hg-cmd">hg pull</command> command that we ran in
   9.287 +	section <xref linkend="sec:tour:pull"/> brought changes
   9.288 +	into the repository, but if we check, there's no sign of those
   9.289 +	changes in the working directory.  This is because <command
   9.290 +	  role="hg-cmd">hg pull</command> does not (by default) touch
   9.291 +	the working directory.  Instead, we use the <command
   9.292 +	  role="hg-cmd">hg update</command> command to do this.</para>
   9.293 +
   9.294 +      <!-- &interaction.tour.update; -->
   9.295 +
   9.296 +      <para>It might seem a bit strange that <command role="hg-cmd">hg
   9.297 +	  pull</command> doesn't update the working directory
   9.298 +	automatically.  There's actually a good reason for this: you
   9.299 +	can use <command role="hg-cmd">hg update</command> to update
   9.300 +	the working directory to the state it was in at <emphasis>any
   9.301 +	  revision</emphasis> in the history of the repository.  If
   9.302 +	you had the working directory updated to an old revision---to
   9.303 +	hunt down the origin of a bug, say---and ran a <command
   9.304 +	  role="hg-cmd">hg pull</command> which automatically updated
   9.305 +	the working directory to a new revision, you might not be
   9.306 +	terribly happy.</para>
   9.307 +      <para>However, since pull-then-update is such a common thing to
   9.308 +	do, Mercurial lets you combine the two by passing the <option
   9.309 +	  role="hg-opt-pull">-u</option> option to <command
   9.310 +	  role="hg-cmd">hg pull</command>.</para>
   9.311  
   9.312        <para>If you look back at the output of <command
   9.313 -	    role="hg-cmd">hg pull</command> in section <xref
   9.314 +	  role="hg-cmd">hg pull</command> in section <xref
   9.315  	    linkend="sec:tour:pull"/> when we ran it without <option
   9.316 -	    role="hg-opt-pull">-u</option>, you can see that it
   9.317 -	  printed a helpful reminder that we'd have to take an
   9.318 -	  explicit step to update the working
   9.319 -	  directory:</para>
   9.320 +	  role="hg-opt-pull">-u</option>, you can see that it printed
   9.321 +	a helpful reminder that we'd have to take an explicit step to
   9.322 +	update the working directory:</para>
   9.323  
   9.324        <!-- &interaction.xxx.fixme; -->
   9.325  
   9.326 -      <para>To find out what revision the working directory
   9.327 -	  is at, use the <command role="hg-cmd">hg parents</command>
   9.328 -	  command.</para>
   9.329 +      <para>To find out what revision the working directory is at, use
   9.330 +	the <command role="hg-cmd">hg parents</command>
   9.331 +	command.</para>
   9.332  
   9.333        <!-- &interaction.tour.parents; -->
   9.334  
   9.335 -      <para>If you look
   9.336 -	  back at figure <xref linkend="fig:tour-basic:history"/>, you'll
   9.337 -	  see arrows connecting each changeset.  The node that the
   9.338 -	  arrow leads <emphasis>from</emphasis> in each case is a
   9.339 -	  parent, and the node that the arrow leads
   9.340 -	  <emphasis>to</emphasis> is its child.  The working directory
   9.341 -	  has a parent in just the same way; this is the changeset
   9.342 -	  that the working directory currently
   9.343 -	  contains.</para>
   9.344 -      <para>To update the working directory to a particular
   9.345 -	  revision, give a revision number or changeset ID to the
   9.346 -	  <command role="hg-cmd">hg update</command> command. <!--
   9.347 -	  &interaction.tour.older; --> If you omit an explicit
   9.348 -	  revision, <command role="hg-cmd">hg update</command> will
   9.349 -	  update to the tip revision, as shown by the second call to
   9.350 -	  <command role="hg-cmd">hg update</command> in the example
   9.351 -	  above.</para>
   9.352 +      <para>If you look back at figure <xref
   9.353 +	  linkend="fig:tour-basic:history"/>,
   9.354 +	you'll see arrows connecting each changeset.  The node that
   9.355 +	the arrow leads <emphasis>from</emphasis> in each case is a
   9.356 +	parent, and the node that the arrow leads
   9.357 +	<emphasis>to</emphasis> is its child.  The working directory
   9.358 +	has a parent in just the same way; this is the changeset that
   9.359 +	the working directory currently contains.</para>
   9.360 +
   9.361 +      <para>To update the working directory to a particular revision,
   9.362 +
   9.363 +	give a revision number or changeset ID to the <command
   9.364 +	  role="hg-cmd">hg update</command> command.</para>
   9.365 +
   9.366 +      <!-- &interaction.tour.older; -->
   9.367 +
   9.368 +      <para>If you omit an explicit revision, <command
   9.369 +	  role="hg-cmd">hg update</command> will update to the tip
   9.370 +	revision, as shown by the second call to <command
   9.371 +	  role="hg-cmd">hg update</command> in the example
   9.372 +	above.</para>
   9.373      </sect2>
   9.374  
   9.375      <sect2>

    10.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    10.2 +++ b/en/ch03-tour-merge.xml	Wed Feb 18 00:22:09 2009 -0800
    10.3 @@ -0,0 +1,394 @@
    10.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    10.5 +
    10.6 +<chapter id="chap:tour-merge">
    10.7 +  <title>A tour of Mercurial: merging work</title>
    10.8 +
    10.9 +  <para>We've now covered cloning a repository, making changes in a
   10.10 +    repository, and pulling or pushing changes from one repository
   10.11 +    into another.  Our next step is <emphasis>merging</emphasis>
   10.12 +    changes from separate repositories.</para>
   10.13 +
   10.14 +  <sect1>
   10.15 +    <title>Merging streams of work</title>
   10.16 +
   10.17 +    <para>Merging is a fundamental part of working with a distributed
   10.18 +      revision control tool.</para>
   10.19 +    <itemizedlist>
   10.20 +      <listitem><para>Alice and Bob each have a personal copy of a
   10.21 +	  repository for a project they're collaborating on.  Alice
   10.22 +	  fixes a bug in her repository; Bob adds a new feature in
   10.23 +	  his.  They want the shared repository to contain both the
   10.24 +	  bug fix and the new feature.</para>
   10.25 +      </listitem>
   10.26 +      <listitem><para>I frequently work on several different tasks for
   10.27 +	  a single project at once, each safely isolated in its own
   10.28 +	  repository. Working this way means that I often need to
   10.29 +	  merge one piece of my own work with another.</para>
   10.30 +      </listitem></itemizedlist>
   10.31 +
   10.32 +    <para>Because merging is such a common thing to need to do,
   10.33 +      Mercurial makes it easy.  Let's walk through the process.  We'll
   10.34 +      begin by cloning yet another repository (see how often they
   10.35 +      spring up?) and making a change in it.</para>
   10.36 +
   10.37 +    <!-- &interaction.tour.merge.clone; -->
   10.38 +
   10.39 +    <para>We should now have two copies of
   10.40 +      <filename>hello.c</filename> with different contents.  The
   10.41 +      histories of the two repositories have also diverged, as
   10.42 +      illustrated in figure <xref
   10.43 +	linkend="fig:tour-merge:sep-repos"/>.</para>
   10.44 +
   10.45 +    <!-- &interaction.tour.merge.cat; -->
   10.46 +
   10.47 +    <informalfigure id="fig:tour-merge:sep-repos">
   10.48 +      <mediaobject>
   10.49 +	<imageobject><imagedata fileref="tour-merge-sep-repos"/></imageobject>
   10.50 +	<textobject><phrase>XXX add text</phrase></textobject>
   10.51 +	<caption><para>Divergent recent histories of the <filename
   10.52 +	      class="directory">my-hello</filename> and <filename
   10.53 +	      class="directory">my-new-hello</filename>
   10.54 +	    repositories</para></caption>
   10.55 +      </mediaobject>
   10.56 +    </informalfigure>
   10.57 +
   10.58 +    <para>We already know that pulling changes from our <filename
   10.59 +	class="directory">my-hello</filename> repository will have no
   10.60 +      effect on the working directory.</para>
   10.61 +
   10.62 +    <!-- &interaction.tour.merge.pull; -->
   10.63 +
   10.64 +    <para>However, the <command role="hg-cmd">hg pull</command>
   10.65 +      command says something about <quote>heads</quote>.</para>
   10.66 +
   10.67 +    <sect2>
   10.68 +      <title>Head changesets</title>
   10.69 +
   10.70 +      <para>A head is a change that has no descendants, or children,
   10.71 +	as they're also known.  The tip revision is thus a head,
   10.72 +	because the newest revision in a repository doesn't have any
   10.73 +	children, but a repository can contain more than one
   10.74 +	head.</para>
   10.75 +
   10.76 +      <informalfigure id="fig:tour-merge:pull">
   10.77 +	<mediaobject><imageobject><imagedata
   10.78 +				    fileref="tour-merge-pull"/></imageobject><textobject><phrase>XXX 
   10.79 +	      add text</phrase></textobject>
   10.80 +	  <caption><para>Repository contents after pulling from
   10.81 +	      <filename class="directory">my-hello</filename> into
   10.82 +	      <filename
   10.83 +		class="directory">my-new-hello</filename></para></caption>
   10.84 +	</mediaobject>
   10.85 +      </informalfigure>
   10.86 +
   10.87 +      <para>In figure <xref linkend="fig:tour-merge:pull"/>, you can
   10.88 +	see the effect of the pull from <filename
   10.89 +	  class="directory">my-hello</filename> into <filename
   10.90 +	  class="directory">my-new-hello</filename>.  The history that
   10.91 +	was already present in <filename
   10.92 +	  class="directory">my-new-hello</filename> is untouched, but
   10.93 +	a new revision has been added.  By referring to figure <xref
   10.94 +	  linkend="fig:tour-merge:sep-repos"/>, we can see that the
   10.95 +	<emphasis>changeset ID</emphasis> remains the same in the new
   10.96 +	repository, but the <emphasis>revision number</emphasis> has
   10.97 +	changed.  (This, incidentally, is a fine example of why it's
   10.98 +	not safe to use revision numbers when discussing changesets.)
   10.99 +	We can view the heads in a repository using the <command
  10.100 +	  role="hg-cmd">hg heads</command> command.</para>
  10.101 +
  10.102 +      <!-- &interaction.tour.merge.heads; -->
  10.103 +
  10.104 +    </sect2>
  10.105 +    <sect2>
  10.106 +      <title>Performing the merge</title>
  10.107 +
  10.108 +      <para>What happens if we try to use the normal <command
  10.109 +	  role="hg-cmd">hg update</command> command to update to the
  10.110 +	new tip?</para>
  10.111 +
  10.112 +      <!-- &interaction.tour.merge.update; -->
  10.113 +
  10.114 +      <para>Mercurial is telling us that the <command role="hg-cmd">hg
  10.115 +	  update</command> command won't do a merge; it won't update
  10.116 +	the working directory when it thinks we might be wanting to do
  10.117 +	a merge, unless we force it to do so.  Instead, we use the
  10.118 +	<command role="hg-cmd">hg merge</command> command to merge the
  10.119 +	two heads.</para>
  10.120 +
  10.121 +      <!-- &interaction.tour.merge.merge; -->
  10.122 +
  10.123 +      <informalfigure id="fig:tour-merge:merge">
  10.124 +
  10.125 +	<mediaobject><imageobject><imagedata
  10.126 +				    fileref="tour-merge-merge"/></imageobject><textobject><phrase>XXX 
  10.127 +	      add text</phrase></textobject>
  10.128 +	  <caption><para>Working directory and repository during
  10.129 +	      merge, and following commit</para></caption>
  10.130 +	</mediaobject>
  10.131 +      </informalfigure>
  10.132 +
  10.133 +      <para>This updates the working directory so that it contains
  10.134 +	changes from <emphasis>both</emphasis> heads, which is
  10.135 +	reflected in both the output of <command role="hg-cmd">hg
  10.136 +	  parents</command> and the contents of
  10.137 +	<filename>hello.c</filename>.</para>
  10.138 +
  10.139 +      <!-- &interaction.tour.merge.parents; -->
  10.140 +
  10.141 +    </sect2>
  10.142 +    <sect2>
  10.143 +      <title>Committing the results of the merge</title>
  10.144 +
  10.145 +      <para>Whenever we've done a merge, <command role="hg-cmd">hg
  10.146 +	  parents</command> will display two parents until we <command
  10.147 +	  role="hg-cmd">hg commit</command> the results of the
  10.148 +	  merge.</para>
  10.149 +
  10.150 +	<!-- &interaction.tour.merge.commit; -->
  10.151 +
  10.152 +      <para>We now have a new tip revision; notice that it has
  10.153 +	<emphasis>both</emphasis> of our former heads as its parents.
  10.154 +	These are the same revisions that were previously displayed by
  10.155 +	<command role="hg-cmd">hg parents</command>.</para>
  10.156 +
  10.157 +      <!-- &interaction.tour.merge.tip; -->
  10.158 +
  10.159 +      <para>In figure <xref
  10.160 +	  linkend="fig:tour-merge:merge"/>, you can see a
  10.161 +	representation of what happens to the working directory during
  10.162 +	the merge, and how this affects the repository when the commit
  10.163 +	happens.  During the merge, the working directory has two
  10.164 +	parent changesets, and these become the parents of the new
  10.165 +	changeset.</para>
  10.166 +
  10.167 +    </sect2>
  10.168 +  </sect1>
  10.169 +  <sect1>
  10.170 +    <title>Merging conflicting changes</title>
  10.171 +
  10.172 +    <para>Most merges are simple affairs, but sometimes you'll find
  10.173 +      yourself merging changes where each modifies the same portions
  10.174 +      of the same files.  Unless both modifications are identical,
  10.175 +      this results in a <emphasis>conflict</emphasis>, where you have
  10.176 +      to decide how to reconcile the different changes into something
  10.177 +      coherent.</para>
  10.178 +
  10.179 +    <informalfigure>
  10.180 +
  10.181 +      <mediaobject id="fig:tour-merge:conflict">
  10.182 +	<imageobject><imagedata fileref="tour-merge-conflict"/></imageobject>
  10.183 +	<textobject><phrase>XXX add text</phrase></textobject>
  10.184 +	<caption><para>Conflicting changes to a
  10.185 +	    document</para></caption>      </mediaobject>
  10.186 +    </informalfigure>
  10.187 +
  10.188 +    <para>Figure <xref linkend="fig:tour-merge:conflict"/> illustrates
  10.189 +      an instance of two conflicting changes to a document.  We
  10.190 +      started with a single version of the file; then we made some
  10.191 +      changes; while someone else made different changes to the same
  10.192 +      text.  Our task in resolving the conflicting changes is to
  10.193 +      decide what the file should look like.</para>
  10.194 +
  10.195 +    <para>Mercurial doesn't have a built-in facility for handling
  10.196 +      conflicts. Instead, it runs an external program called
  10.197 +      <command>hgmerge</command>.  This is a shell script that is
  10.198 +      bundled with Mercurial; you can change it to behave however you
  10.199 +      please.  What it does by default is try to find one of several
  10.200 +      different merging tools that are likely to be installed on your
  10.201 +      system.  It first tries a few fully automatic merging tools; if
  10.202 +      these don't succeed (because the resolution process requires
  10.203 +      human guidance) or aren't present, the script tries a few
  10.204 +      different graphical merging tools.</para>
  10.205 +
  10.206 +    <para>It's also possible to get Mercurial to run another program
  10.207 +      or script instead of <command>hgmerge</command>, by setting the
  10.208 +      <envar>HGMERGE</envar> environment variable to the name of your
  10.209 +      preferred program.</para>
  10.210 +
  10.211 +    <sect2>
  10.212 +      <title>Using a graphical merge tool</title>
  10.213 +
  10.214 +      <para>My preferred graphical merge tool is
  10.215 +	<command>kdiff3</command>, which I'll use to describe the
  10.216 +	features that are common to graphical file merging tools.  You
  10.217 +	can see a screenshot of <command>kdiff3</command> in action in
  10.218 +	figure <xref linkend="fig:tour-merge:kdiff3"/>.  The kind of
  10.219 +	merge it is performing is called a <emphasis>three-way
  10.220 +	  merge</emphasis>, because there are three different versions
  10.221 +	of the file of interest to us.  The tool thus splits the upper
  10.222 +	portion of the window into three panes:</para>
  10.223 +      <itemizedlist>
  10.224 +	<listitem><para>At the left is the <emphasis>base</emphasis>
  10.225 +	    version of the file, i.e. the most recent version from
  10.226 +	    which the two versions we're trying to merge are
  10.227 +	    descended.</para>
  10.228 +	</listitem>
  10.229 +	<listitem><para>In the middle is <quote>our</quote> version of
  10.230 +	    the file, with the contents that we modified.</para>
  10.231 +	</listitem>
  10.232 +	<listitem><para>On the right is <quote>their</quote> version
  10.233 +	    of the file, the one that from the changeset that we're
  10.234 +	    trying to merge with.</para>
  10.235 +	</listitem></itemizedlist>
  10.236 +      <para>In the pane below these is the current
  10.237 +	<emphasis>result</emphasis> of the merge. Our task is to
  10.238 +	replace all of the red text, which indicates unresolved
  10.239 +	conflicts, with some sensible merger of the
  10.240 +	<quote>ours</quote> and <quote>theirs</quote> versions of the
  10.241 +	file.</para>
  10.242 +
  10.243 +      <para>All four of these panes are <emphasis>locked
  10.244 +	  together</emphasis>; if we scroll vertically or horizontally
  10.245 +	in any of them, the others are updated to display the
  10.246 +	corresponding sections of their respective files.</para>
  10.247 +
  10.248 +      <informalfigure id="fig:tour-merge:kdiff3">
  10.249 +	<mediaobject><imageobject><imagedata
  10.250 +				    fileref="kdiff3"/></imageobject><textobject><phrase>XXX 
  10.251 +	      add text</phrase></textobject>
  10.252 +	  <caption><para>Using <command>kdiff3</command> to merge
  10.253 +	      versions of a file</para></caption>
  10.254 +	</mediaobject>
  10.255 +      </informalfigure>
  10.256 +
  10.257 +      <para>For each conflicting portion of the file, we can choose to
  10.258 +	resolve the conflict using some combination of text from the
  10.259 +	base version, ours, or theirs.  We can also manually edit the
  10.260 +	merged file at any time, in case we need to make further
  10.261 +	modifications.</para>
  10.262 +
  10.263 +      <para>There are <emphasis>many</emphasis> file merging tools
  10.264 +	available, too many to cover here.  They vary in which
  10.265 +	platforms they are available for, and in their particular
  10.266 +	strengths and weaknesses.  Most are tuned for merging files
  10.267 +	containing plain text, while a few are aimed at specialised
  10.268 +	file formats (generally XML).</para>
  10.269 +
  10.270 +    </sect2>
  10.271 +    <sect2>
  10.272 +      <title>A worked example</title>
  10.273 +
  10.274 +      <para>In this example, we will reproduce the file modification
  10.275 +	history of figure <xref linkend="fig:tour-merge:conflict"/>
  10.276 +	above.  Let's begin by creating a repository with a base
  10.277 +	version of our document.</para>
  10.278 +
  10.279 +      <!-- &interaction.tour-merge-conflict.wife; -->
  10.280 +
  10.281 +      <para>We'll clone the repository and make a change to the
  10.282 +	file.</para>
  10.283 +
  10.284 +      <!-- &interaction.tour-merge-conflict.cousin; -->
  10.285 +
  10.286 +      <para>And another clone, to simulate someone else making a
  10.287 +	change to the file. (This hints at the idea that it's not all
  10.288 +	that unusual to merge with yourself when you isolate tasks in
  10.289 +	separate repositories, and indeed to find and resolve
  10.290 +	conflicts while doing so.)</para>
  10.291 +
  10.292 +      <!-- &interaction.tour-merge-conflict.son; -->
  10.293 +
  10.294 +      <para>Having created two
  10.295 +	different versions of the file, we'll set up an environment
  10.296 +	suitable for running our merge.</para>
  10.297 +
  10.298 +      <!-- &interaction.tour-merge-conflict.pull; -->
  10.299 +
  10.300 +      <para>In this example, I won't use Mercurial's normal
  10.301 +	<command>hgmerge</command> program to do the merge, because it
  10.302 +	would drop my nice automated example-running tool into a
  10.303 +	graphical user interface.  Instead, I'll set
  10.304 +	<envar>HGMERGE</envar> to tell Mercurial to use the
  10.305 +	non-interactive <command>merge</command> command.  This is
  10.306 +	bundled with many Unix-like systems. If you're following this
  10.307 +	example on your computer, don't bother setting
  10.308 +	<envar>HGMERGE</envar>.</para>
  10.309 +
  10.310 +      <para><emphasis role="bold">XXX FIX THIS
  10.311 +	  EXAMPLE.</emphasis></para>
  10.312 +
  10.313 +      <!-- &interaction.tour-merge-conflict.merge; -->
  10.314 +
  10.315 +      <para>Because <command>merge</command> can't resolve the
  10.316 +	conflicting changes, it leaves <emphasis>merge
  10.317 +	  markers</emphasis> inside the file that has conflicts,
  10.318 +	indicating which lines have conflicts, and whether they came
  10.319 +	from our version of the file or theirs.</para>
  10.320 +
  10.321 +      <para>Mercurial can tell from the way <command>merge</command>
  10.322 +	exits that it wasn't able to merge successfully, so it tells
  10.323 +	us what commands we'll need to run if we want to redo the
  10.324 +	merging operation.  This could be useful if, for example, we
  10.325 +	were running a graphical merge tool and quit because we were
  10.326 +	confused or realised we had made a mistake.</para>
  10.327 +
  10.328 +      <para>If automatic or manual merges fail, there's nothing to
  10.329 +	prevent us from <quote>fixing up</quote> the affected files
  10.330 +	ourselves, and committing the results of our merge:</para>
  10.331 +
  10.332 +      <!-- &interaction.tour-merge-conflict.commit; -->
  10.333 +
  10.334 +    </sect2>
  10.335 +  </sect1>
  10.336 +  <sect1 id="sec:tour-merge:fetch">
  10.337 +    <title>Simplifying the pull-merge-commit sequence</title>
  10.338 +
  10.339 +    <para>The process of merging changes as outlined above is
  10.340 +      straightforward, but requires running three commands in
  10.341 +      sequence.</para>
  10.342 +    <programlisting>
  10.343 +      hg pull hg merge hg commit -m 'Merged remote changes'
  10.344 +    </programlisting>
  10.345 +    <para>In the case of the final commit, you also need to enter a
  10.346 +      commit message, which is almost always going to be a piece of
  10.347 +      uninteresting <quote>boilerplate</quote> text.</para>
  10.348 +
  10.349 +    <para>It would be nice to reduce the number of steps needed, if
  10.350 +      this were possible.  Indeed, Mercurial is distributed with an
  10.351 +      extension called <literal role="hg-ext">fetch</literal> that
  10.352 +      does just this.</para>
  10.353 +
  10.354 +    <para>Mercurial provides a flexible extension mechanism that lets
  10.355 +      people extend its functionality, while keeping the core of
  10.356 +      Mercurial small and easy to deal with.  Some extensions add new
  10.357 +      commands that you can use from the command line, while others
  10.358 +      work <quote>behind the scenes,</quote> for example adding
  10.359 +      capabilities to the server.</para>
  10.360 +
  10.361 +    <para>The <literal role="hg-ext">fetch</literal> extension adds a
  10.362 +      new command called, not surprisingly, <command role="hg-cmd">hg
  10.363 +	fetch</command>.  This extension acts as a combination of
  10.364 +      <command role="hg-cmd">hg pull</command>, <command
  10.365 +	role="hg-cmd">hg update</command> and <command
  10.366 +	role="hg-cmd">hg merge</command>.  It begins by pulling
  10.367 +      changes from another repository into the current repository.  If
  10.368 +      it finds that the changes added a new head to the repository, it
  10.369 +      begins a merge, then commits the result of the merge with an
  10.370 +      automatically-generated commit message.  If no new heads were
  10.371 +      added, it updates the working directory to the new tip
  10.372 +      changeset.</para>
  10.373 +
  10.374 +    <para>Enabling the <literal role="hg-ext">fetch</literal>
  10.375 +      extension is easy.  Edit your <filename
  10.376 +	role="special">.hgrc</filename>, and either go to the <literal
  10.377 +	role="rc-extensions">extensions</literal> section or create an
  10.378 +      <literal role="rc-extensions">extensions</literal> section. Then
  10.379 +      add a line that simply reads <quote><literal>fetch
  10.380 +	</literal></quote>.</para>
  10.381 +    <programlisting>
  10.382 +      [extensions] fetch =
  10.383 +    </programlisting>
  10.384 +    <para>(Normally, on the right-hand side of the
  10.385 +      <quote><literal>=</literal></quote> would appear the location of
  10.386 +      the extension, but since the <literal
  10.387 +	role="hg-ext">fetch</literal> extension is in the standard
  10.388 +      distribution, Mercurial knows where to search for it.)</para>
  10.389 +
  10.390 +  </sect1>
  10.391 +</chapter>
  10.392 +
  10.393 +<!--
  10.394 +local variables: 
  10.395 +sgml-parent-document: ("00book.xml" "book" "chapter")
  10.396 +end:
  10.397 +-->

    11.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    11.2 +++ b/en/ch04-concepts.xml	Wed Feb 18 00:22:09 2009 -0800
    11.3 @@ -0,0 +1,725 @@
    11.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    11.5 +
    11.6 +<chapter id="chap:concepts">
    11.7 +  <title>Behind the scenes</title>
    11.8 +
    11.9 +  <para>Unlike many revision control systems, the concepts upon which
   11.10 +    Mercurial is built are simple enough that it's easy to understand
   11.11 +    how the software really works.  Knowing this certainly isn't
   11.12 +    necessary, but I find it useful to have a <quote>mental
   11.13 +      model</quote> of what's going on.</para>
   11.14 +
   11.15 +  <para>This understanding gives me confidence that Mercurial has been
   11.16 +    carefully designed to be both <emphasis>safe</emphasis> and
   11.17 +    <emphasis>efficient</emphasis>.  And just as importantly, if it's
   11.18 +    easy for me to retain a good idea of what the software is doing
   11.19 +    when I perform a revision control task, I'm less likely to be
   11.20 +    surprised by its behaviour.</para>
   11.21 +
   11.22 +  <para>In this chapter, we'll initially cover the core concepts
   11.23 +    behind Mercurial's design, then continue to discuss some of the
   11.24 +    interesting details of its implementation.</para>
   11.25 +
   11.26 +  <sect1>
   11.27 +    <title>Mercurial's historical record</title>
   11.28 +
   11.29 +    <sect2>
   11.30 +      <title>Tracking the history of a single file</title>
   11.31 +
   11.32 +      <para>When Mercurial tracks modifications to a file, it stores
   11.33 +	the history of that file in a metadata object called a
   11.34 +	<emphasis>filelog</emphasis>.  Each entry in the filelog
   11.35 +	contains enough information to reconstruct one revision of the
   11.36 +	file that is being tracked.  Filelogs are stored as files in
   11.37 +	the <filename role="special"
   11.38 +	  class="directory">.hg/store/data</filename> directory.  A
   11.39 +	filelog contains two kinds of information: revision data, and
   11.40 +	an index to help Mercurial to find a revision
   11.41 +	efficiently.</para>
   11.42 +
   11.43 +      <para>A file that is large, or has a lot of history, has its
   11.44 +	filelog stored in separate data
   11.45 +	(<quote><literal>.d</literal></quote> suffix) and index
   11.46 +	(<quote><literal>.i</literal></quote> suffix) files.  For
   11.47 +	small files without much history, the revision data and index
   11.48 +	are combined in a single <quote><literal>.i</literal></quote>
   11.49 +	file.  The correspondence between a file in the working
   11.50 +	directory and the filelog that tracks its history in the
   11.51 +	repository is illustrated in figure <xref
   11.52 +	  linkend="fig:concepts:filelog"/>.</para>
   11.53 +
   11.54 +      <informalfigure id="fig:concepts:filelog">
   11.55 +	<mediaobject><imageobject><imagedata
   11.56 +				    fileref="filelog"/></imageobject><textobject><phrase>XXX 
   11.57 +	      add text</phrase></textobject>
   11.58 +	  <caption><para>Relationships between files in working
   11.59 +	      directory and filelogs in
   11.60 +	      repository</para></caption></mediaobject>
   11.61 +      </informalfigure>
   11.62 +
   11.63 +    </sect2>
   11.64 +    <sect2>
   11.65 +      <title>Managing tracked files</title>
   11.66 +
   11.67 +      <para>Mercurial uses a structure called a
   11.68 +	<emphasis>manifest</emphasis> to collect together information
   11.69 +	about the files that it tracks.  Each entry in the manifest
   11.70 +	contains information about the files present in a single
   11.71 +	changeset.  An entry records which files are present in the
   11.72 +	changeset, the revision of each file, and a few other pieces
   11.73 +	of file metadata.</para>
   11.74 +
   11.75 +    </sect2>
   11.76 +    <sect2>
   11.77 +      <title>Recording changeset information</title>
   11.78 +
   11.79 +      <para>The <emphasis>changelog</emphasis> contains information
   11.80 +	about each changeset.  Each revision records who committed a
   11.81 +	change, the changeset comment, other pieces of
   11.82 +	changeset-related information, and the revision of the
   11.83 +	manifest to use.</para>
   11.84 +
   11.85 +    </sect2>
   11.86 +    <sect2>
   11.87 +      <title>Relationships between revisions</title>
   11.88 +
   11.89 +      <para>Within a changelog, a manifest, or a filelog, each
   11.90 +	revision stores a pointer to its immediate parent (or to its
   11.91 +	two parents, if it's a merge revision).  As I mentioned above,
   11.92 +	there are also relationships between revisions
   11.93 +	<emphasis>across</emphasis> these structures, and they are
   11.94 +	hierarchical in nature.</para>
   11.95 +
   11.96 +      <para>For every changeset in a repository, there is exactly one
   11.97 +	revision stored in the changelog.  Each revision of the
   11.98 +	changelog contains a pointer to a single revision of the
   11.99 +	manifest.  A revision of the manifest stores a pointer to a
  11.100 +	single revision of each filelog tracked when that changeset
  11.101 +	was created.  These relationships are illustrated in figure
  11.102 +	<xref linkend="fig:concepts:metadata"/>.</para>
  11.103 +
  11.104 +      <informalfigure id="fig:concepts:metadata">
  11.105 +	<mediaobject><imageobject><imagedata
  11.106 +				    fileref="metadata"/></imageobject><textobject><phrase>XXX 
  11.107 +	      add text</phrase></textobject><caption><para>Metadata
  11.108 +	      relationships</para></caption>
  11.109 +	</mediaobject>
  11.110 +      </informalfigure>
  11.111 +
  11.112 +      <para>As the illustration shows, there is
  11.113 +	<emphasis>not</emphasis> a <quote>one to one</quote>
  11.114 +	relationship between revisions in the changelog, manifest, or
  11.115 +	filelog. If the manifest hasn't changed between two
  11.116 +	changesets, the changelog entries for those changesets will
  11.117 +	point to the same revision of the manifest.  If a file that
  11.118 +	Mercurial tracks hasn't changed between two changesets, the
  11.119 +	entry for that file in the two revisions of the manifest will
  11.120 +	point to the same revision of its filelog.</para>
  11.121 +
  11.122 +    </sect2>
  11.123 +  </sect1>
  11.124 +  <sect1>
  11.125 +    <title>Safe, efficient storage</title>
  11.126 +
  11.127 +    <para>The underpinnings of changelogs, manifests, and filelogs are
  11.128 +      provided by a single structure called the
  11.129 +      <emphasis>revlog</emphasis>.</para>
  11.130 +
  11.131 +    <sect2>
  11.132 +      <title>Efficient storage</title>
  11.133 +
  11.134 +      <para>The revlog provides efficient storage of revisions using a
  11.135 +	<emphasis>delta</emphasis> mechanism.  Instead of storing a
  11.136 +	complete copy of a file for each revision, it stores the
  11.137 +	changes needed to transform an older revision into the new
  11.138 +	revision.  For many kinds of file data, these deltas are
  11.139 +	typically a fraction of a percent of the size of a full copy
  11.140 +	of a file.</para>
  11.141 +
  11.142 +      <para>Some obsolete revision control systems can only work with
  11.143 +	deltas of text files.  They must either store binary files as
  11.144 +	complete snapshots or encoded into a text representation, both
  11.145 +	of which are wasteful approaches.  Mercurial can efficiently
  11.146 +	handle deltas of files with arbitrary binary contents; it
  11.147 +	doesn't need to treat text as special.</para>
  11.148 +
  11.149 +    </sect2>
  11.150 +    <sect2 id="sec:concepts:txn">
  11.151 +      <title>Safe operation</title>
  11.152 +
  11.153 +      <para>Mercurial only ever <emphasis>appends</emphasis> data to
  11.154 +	the end of a revlog file. It never modifies a section of a
  11.155 +	file after it has written it.  This is both more robust and
  11.156 +	efficient than schemes that need to modify or rewrite
  11.157 +	data.</para>
  11.158 +
  11.159 +      <para>In addition, Mercurial treats every write as part of a
  11.160 +	<emphasis>transaction</emphasis> that can span a number of
  11.161 +	files.  A transaction is <emphasis>atomic</emphasis>: either
  11.162 +	the entire transaction succeeds and its effects are all
  11.163 +	visible to readers in one go, or the whole thing is undone.
  11.164 +	This guarantee of atomicity means that if you're running two
  11.165 +	copies of Mercurial, where one is reading data and one is
  11.166 +	writing it, the reader will never see a partially written
  11.167 +	result that might confuse it.</para>
  11.168 +
  11.169 +      <para>The fact that Mercurial only appends to files makes it
  11.170 +	easier to provide this transactional guarantee.  The easier it
  11.171 +	is to do stuff like this, the more confident you should be
  11.172 +	that it's done correctly.</para>
  11.173 +
  11.174 +    </sect2>
  11.175 +    <sect2>
  11.176 +      <title>Fast retrieval</title>
  11.177 +
  11.178 +      <para>Mercurial cleverly avoids a pitfall common to all earlier
  11.179 +	revision control systems: the problem of <emphasis>inefficient
  11.180 +	  retrieval</emphasis>. Most revision control systems store
  11.181 +	the contents of a revision as an incremental series of
  11.182 +	modifications against a <quote>snapshot</quote>.  To
  11.183 +	reconstruct a specific revision, you must first read the
  11.184 +	snapshot, and then every one of the revisions between the
  11.185 +	snapshot and your target revision.  The more history that a
  11.186 +	file accumulates, the more revisions you must read, hence the
  11.187 +	longer it takes to reconstruct a particular revision.</para>
  11.188 +
  11.189 +      <informalfigure id="fig:concepts:snapshot">
  11.190 +	<mediaobject><imageobject><imagedata
  11.191 +				    fileref="snapshot"/></imageobject><textobject><phrase>XXX 
  11.192 +	      add text</phrase></textobject><caption><para>Snapshot of
  11.193 +	      a revlog, with incremental
  11.194 +	      deltas</para></caption></mediaobject>
  11.195 +      </informalfigure>
  11.196 +
  11.197 +      <para>The innovation that Mercurial applies to this problem is
  11.198 +	simple but effective.  Once the cumulative amount of delta
  11.199 +	information stored since the last snapshot exceeds a fixed
  11.200 +	threshold, it stores a new snapshot (compressed, of course),
  11.201 +	instead of another delta.  This makes it possible to
  11.202 +	reconstruct <emphasis>any</emphasis> revision of a file
  11.203 +	quickly.  This approach works so well that it has since been
  11.204 +	copied by several other revision control systems.</para>
  11.205 +
  11.206 +      <para>Figure <xref linkend="fig:concepts:snapshot"/> illustrates
  11.207 +	the idea.  In an entry in a revlog's index file, Mercurial
  11.208 +	stores the range of entries from the data file that it must
  11.209 +	read to reconstruct a particular revision.</para>
  11.210 +
  11.211 +      <sect3>
  11.212 +	<title>Aside: the influence of video compression</title>
  11.213 +
  11.214 +	<para>If you're familiar with video compression or have ever
  11.215 +	  watched a TV feed through a digital cable or satellite
  11.216 +	  service, you may know that most video compression schemes
  11.217 +	  store each frame of video as a delta against its predecessor
  11.218 +	  frame.  In addition, these schemes use <quote>lossy</quote>
  11.219 +	  compression techniques to increase the compression ratio, so
  11.220 +	  visual errors accumulate over the course of a number of
  11.221 +	  inter-frame deltas.</para>
  11.222 +
  11.223 +	<para>Because it's possible for a video stream to <quote>drop
  11.224 +	    out</quote> occasionally due to signal glitches, and to
  11.225 +	  limit the accumulation of artefacts introduced by the lossy
  11.226 +	  compression process, video encoders periodically insert a
  11.227 +	  complete frame (called a <quote>key frame</quote>) into the
  11.228 +	  video stream; the next delta is generated against that
  11.229 +	  frame.  This means that if the video signal gets
  11.230 +	  interrupted, it will resume once the next key frame is
  11.231 +	  received.  Also, the accumulation of encoding errors
  11.232 +	  restarts anew with each key frame.</para>
  11.233 +
  11.234 +      </sect3>
  11.235 +    </sect2>
  11.236 +    <sect2>
  11.237 +      <title>Identification and strong integrity</title>
  11.238 +
  11.239 +      <para>Along with delta or snapshot information, a revlog entry
  11.240 +	contains a cryptographic hash of the data that it represents.
  11.241 +	This makes it difficult to forge the contents of a revision,
  11.242 +	and easy to detect accidental corruption.</para>
  11.243 +
  11.244 +      <para>Hashes provide more than a mere check against corruption;
  11.245 +	they are used as the identifiers for revisions.  The changeset
  11.246 +	identification hashes that you see as an end user are from
  11.247 +	revisions of the changelog.  Although filelogs and the
  11.248 +	manifest also use hashes, Mercurial only uses these behind the
  11.249 +	scenes.</para>
  11.250 +
  11.251 +      <para>Mercurial verifies that hashes are correct when it
  11.252 +	retrieves file revisions and when it pulls changes from
  11.253 +	another repository.  If it encounters an integrity problem, it
  11.254 +	will complain and stop whatever it's doing.</para>
  11.255 +
  11.256 +      <para>In addition to the effect it has on retrieval efficiency,
  11.257 +	Mercurial's use of periodic snapshots makes it more robust
  11.258 +	against partial data corruption.  If a revlog becomes partly
  11.259 +	corrupted due to a hardware error or system bug, it's often
  11.260 +	possible to reconstruct some or most revisions from the
  11.261 +	uncorrupted sections of the revlog, both before and after the
  11.262 +	corrupted section.  This would not be possible with a
  11.263 +	delta-only storage model.</para>
  11.264 +
  11.265 +    </sect2>
  11.266 +  </sect1>
  11.267 +  <sect1>
  11.268 +    <title>Revision history, branching, and merging</title>
  11.269 +
  11.270 +    <para>Every entry in a Mercurial revlog knows the identity of its
  11.271 +      immediate ancestor revision, usually referred to as its
  11.272 +      <emphasis>parent</emphasis>.  In fact, a revision contains room
  11.273 +      for not one parent, but two.  Mercurial uses a special hash,
  11.274 +      called the <quote>null ID</quote>, to represent the idea
  11.275 +      <quote>there is no parent here</quote>.  This hash is simply a
  11.276 +      string of zeroes.</para>
  11.277 +
  11.278 +    <para>In figure <xref linkend="fig:concepts:revlog"/>, you can see
  11.279 +      an example of the conceptual structure of a revlog.  Filelogs,
  11.280 +      manifests, and changelogs all have this same structure; they
  11.281 +      differ only in the kind of data stored in each delta or
  11.282 +      snapshot.</para>
  11.283 +
  11.284 +    <para>The first revision in a revlog (at the bottom of the image)
  11.285 +      has the null ID in both of its parent slots.  For a
  11.286 +      <quote>normal</quote> revision, its first parent slot contains
  11.287 +      the ID of its parent revision, and its second contains the null
  11.288 +      ID, indicating that the revision has only one real parent.  Any
  11.289 +      two revisions that have the same parent ID are branches.  A
  11.290 +      revision that represents a merge between branches has two normal
  11.291 +      revision IDs in its parent slots.</para>
  11.292 +
  11.293 +    <informalfigure id="fig:concepts:revlog">
  11.294 +      <mediaobject><imageobject><imagedata
  11.295 +				  fileref="revlog"/></imageobject><textobject><phrase>XXX 
  11.296 +	    add text</phrase></textobject></mediaobject>
  11.297 +    </informalfigure>
  11.298 +
  11.299 +  </sect1>
  11.300 +  <sect1>
  11.301 +    <title>The working directory</title>
  11.302 +
  11.303 +    <para>In the working directory, Mercurial stores a snapshot of the
  11.304 +      files from the repository as of a particular changeset.</para>
  11.305 +
  11.306 +    <para>The working directory <quote>knows</quote> which changeset
  11.307 +      it contains.  When you update the working directory to contain a
  11.308 +      particular changeset, Mercurial looks up the appropriate
  11.309 +      revision of the manifest to find out which files it was tracking
  11.310 +      at the time that changeset was committed, and which revision of
  11.311 +      each file was then current.  It then recreates a copy of each of
  11.312 +      those files, with the same contents it had when the changeset
  11.313 +      was committed.</para>
  11.314 +
  11.315 +    <para>The <emphasis>dirstate</emphasis> contains Mercurial's
  11.316 +      knowledge of the working directory.  This details which
  11.317 +      changeset the working directory is updated to, and all of the
  11.318 +      files that Mercurial is tracking in the working
  11.319 +      directory.</para>
  11.320 +
  11.321 +    <para>Just as a revision of a revlog has room for two parents, so
  11.322 +      that it can represent either a normal revision (with one parent)
  11.323 +      or a merge of two earlier revisions, the dirstate has slots for
  11.324 +      two parents.  When you use the <command role="hg-cmd">hg
  11.325 +	update</command> command, the changeset that you update to is
  11.326 +      stored in the <quote>first parent</quote> slot, and the null ID
  11.327 +      in the second. When you <command role="hg-cmd">hg
  11.328 +	merge</command> with another changeset, the first parent
  11.329 +      remains unchanged, and the second parent is filled in with the
  11.330 +      changeset you're merging with.  The <command role="hg-cmd">hg
  11.331 +	parents</command> command tells you what the parents of the
  11.332 +      dirstate are.</para>
  11.333 +
  11.334 +    <sect2>
  11.335 +      <title>What happens when you commit</title>
  11.336 +
  11.337 +      <para>The dirstate stores parent information for more than just
  11.338 +	book-keeping purposes.  Mercurial uses the parents of the
  11.339 +	dirstate as <emphasis>the parents of a new
  11.340 +	  changeset</emphasis> when you perform a commit.</para>
  11.341 +
  11.342 +      <informalfigure id="fig:concepts:wdir">
  11.343 +	<mediaobject><imageobject><imagedata
  11.344 +				    fileref="wdir"/></imageobject><textobject><phrase>XXX 
  11.345 +	      add text</phrase></textobject><caption><para>The working
  11.346 +	      directory can have two
  11.347 +	      parents</para></caption></mediaobject>
  11.348 +      </informalfigure>
  11.349 +
  11.350 +      <para>Figure <xref linkend="fig:concepts:wdir"/> shows the
  11.351 +	normal state of the working directory, where it has a single
  11.352 +	changeset as parent.  That changeset is the
  11.353 +	<emphasis>tip</emphasis>, the newest changeset in the
  11.354 +	repository that has no children.</para>
  11.355 +
  11.356 +      <informalfigure id="fig:concepts:wdir-after-commit">
  11.357 +	<mediaobject><imageobject><imagedata
  11.358 +				    fileref="wdir-after-commit"/></imageobject><textobject><phrase>XXX 
  11.359 +	      add text</phrase></textobject><caption><para>The working
  11.360 +	      directory gains new parents after a
  11.361 +	      commit</para></caption></mediaobject>
  11.362 +      </informalfigure>
  11.363 +
  11.364 +      <para>It's useful to think of the working directory as
  11.365 +	<quote>the changeset I'm about to commit</quote>.  Any files
  11.366 +	that you tell Mercurial that you've added, removed, renamed,
  11.367 +	or copied will be reflected in that changeset, as will
  11.368 +	modifications to any files that Mercurial is already tracking;
  11.369 +	the new changeset will have the parents of the working
  11.370 +	directory as its parents.</para>
  11.371 +
  11.372 +      <para>After a commit, Mercurial will update the parents of the
  11.373 +	working directory, so that the first parent is the ID of the
  11.374 +	new changeset, and the second is the null ID.  This is shown
  11.375 +	in figure <xref linkend="fig:concepts:wdir-after-commit"/>.
  11.376 +	Mercurial
  11.377 +	doesn't touch any of the files in the working directory when
  11.378 +	you commit; it just modifies the dirstate to note its new
  11.379 +	parents.</para>
  11.380 +
  11.381 +    </sect2>
  11.382 +    <sect2>
  11.383 +      <title>Creating a new head</title>
  11.384 +
  11.385 +      <para>It's perfectly normal to update the working directory to a
  11.386 +	changeset other than the current tip.  For example, you might
  11.387 +	want to know what your project looked like last Tuesday, or
  11.388 +	you could be looking through changesets to see which one
  11.389 +	introduced a bug.  In cases like this, the natural thing to do
  11.390 +	is update the working directory to the changeset you're
  11.391 +	interested in, and then examine the files in the working
  11.392 +	directory directly to see their contents as they were when you
  11.393 +	committed that changeset.  The effect of this is shown in
  11.394 +	figure <xref linkend="fig:concepts:wdir-pre-branch"/>.</para>
  11.395 +
  11.396 +      <informalfigure id="fig:concepts:wdir-pre-branch">
  11.397 +	<mediaobject><imageobject><imagedata
  11.398 +				    fileref="wdir-pre-branch"/></imageobject><textobject><phrase>XXX 
  11.399 +	      add text</phrase></textobject><caption><para>The working
  11.400 +	      directory, updated to an older
  11.401 +	      changeset</para></caption></mediaobject>
  11.402 +      </informalfigure>
  11.403 +
  11.404 +      <para>Having updated the working directory to an older
  11.405 +	changeset, what happens if you make some changes, and then
  11.406 +	commit?  Mercurial behaves in the same way as I outlined
  11.407 +	above.  The parents of the working directory become the
  11.408 +	parents of the new changeset.  This new changeset has no
  11.409 +	children, so it becomes the new tip.  And the repository now
  11.410 +	contains two changesets that have no children; we call these
  11.411 +	<emphasis>heads</emphasis>.  You can see the structure that
  11.412 +	this creates in figure <xref
  11.413 +	  linkend="fig:concepts:wdir-branch"/>.</para>
  11.414 +
  11.415 +      <informalfigure id="fig:concepts:wdir-branch">
  11.416 +	<mediaobject><imageobject><imagedata
  11.417 +				    fileref="wdir-branch"/></imageobject><textobject><phrase>XXX 
  11.418 +	      add text</phrase></textobject><caption><para>After a
  11.419 +	      commit made while synced to an older
  11.420 +	      changeset</para></caption></mediaobject>
  11.421 +      </informalfigure>
  11.422 +
  11.423 +      <note>
  11.424 +	<para>  If you're new to Mercurial, you should keep in mind a
  11.425 +	  common <quote>error</quote>, which is to use the <command
  11.426 +	    role="hg-cmd">hg pull</command> command without any
  11.427 +	  options.  By default, the <command role="hg-cmd">hg
  11.428 +	    pull</command> command <emphasis>does not</emphasis>
  11.429 +	  update the working directory, so you'll bring new changesets
  11.430 +	  into your repository, but the working directory will stay
  11.431 +	  synced at the same changeset as before the pull.  If you
  11.432 +	  make some changes and commit afterwards, you'll thus create
  11.433 +	  a new head, because your working directory isn't synced to
  11.434 +	  whatever the current tip is.</para>
  11.435 +
  11.436 +	<para>  I put the word <quote>error</quote> in quotes because
  11.437 +	  all that you need to do to rectify this situation is
  11.438 +	  <command role="hg-cmd">hg merge</command>, then <command
  11.439 +	    role="hg-cmd">hg commit</command>.  In other words, this
  11.440 +	  almost never has negative consequences; it just surprises
  11.441 +	  people.  I'll discuss other ways to avoid this behaviour,
  11.442 +	  and why Mercurial behaves in this initially surprising way,
  11.443 +	  later on.</para>
  11.444 +      </note>
  11.445 +
  11.446 +    </sect2>
  11.447 +    <sect2>
  11.448 +      <title>Merging heads</title>
  11.449 +
  11.450 +      <para>When you run the <command role="hg-cmd">hg merge</command>
  11.451 +	command, Mercurial leaves the first parent of the working
  11.452 +	directory unchanged, and sets the second parent to the
  11.453 +	changeset you're merging with, as shown in figure <xref
  11.454 +	  linkend="fig:concepts:wdir-merge"/>.</para>
  11.455 +
  11.456 +      <informalfigure id="fig:concepts:wdir-merge">
  11.457 +	<mediaobject><imageobject><imagedata
  11.458 +				    fileref="wdir-merge"/></imageobject><textobject><phrase>XXX 
  11.459 +	      add text</phrase></textobject><caption><para>Merging two
  11.460 +	      heads</para></caption></mediaobject>
  11.461 +      </informalfigure>
  11.462 +
  11.463 +      <para>Mercurial also has to modify the working directory, to
  11.464 +	merge the files managed in the two changesets.  Simplified a
  11.465 +	little, the merging process goes like this, for every file in
  11.466 +	the manifests of both changesets.</para>
  11.467 +      <itemizedlist>
  11.468 +	<listitem><para>If neither changeset has modified a file, do
  11.469 +	    nothing with that file.</para>
  11.470 +	</listitem>
  11.471 +	<listitem><para>If one changeset has modified a file, and the
  11.472 +	    other hasn't, create the modified copy of the file in the
  11.473 +	    working directory.</para>
  11.474 +	</listitem>
  11.475 +	<listitem><para>If one changeset has removed a file, and the
  11.476 +	    other hasn't (or has also deleted it), delete the file
  11.477 +	    from the working directory.</para>
  11.478 +	</listitem>
  11.479 +	<listitem><para>If one changeset has removed a file, but the
  11.480 +	    other has modified the file, ask the user what to do: keep
  11.481 +	    the modified file, or remove it?</para>
  11.482 +	</listitem>
  11.483 +	<listitem><para>If both changesets have modified a file,
  11.484 +	    invoke an external merge program to choose the new
  11.485 +	    contents for the merged file.  This may require input from
  11.486 +	    the user.</para>
  11.487 +	</listitem>
  11.488 +	<listitem><para>If one changeset has modified a file, and the
  11.489 +	    other has renamed or copied the file, make sure that the
  11.490 +	    changes follow the new name of the file.</para>
  11.491 +	</listitem></itemizedlist>
  11.492 +      <para>There are more details&emdash;merging has plenty of corner
  11.493 +	cases&emdash;but these are the most common choices that are
  11.494 +	involved in a merge.  As you can see, most cases are
  11.495 +	completely automatic, and indeed most merges finish
  11.496 +	automatically, without requiring your input to resolve any
  11.497 +	conflicts.</para>
  11.498 +
  11.499 +      <para>When you're thinking about what happens when you commit
  11.500 +	after a merge, once again the working directory is <quote>the
  11.501 +	  changeset I'm about to commit</quote>.  After the <command
  11.502 +	  role="hg-cmd">hg merge</command> command completes, the
  11.503 +	working directory has two parents; these will become the
  11.504 +	parents of the new changeset.</para>
  11.505 +
  11.506 +      <para>Mercurial lets you perform multiple merges, but you must
  11.507 +	commit the results of each individual merge as you go.  This
  11.508 +	is necessary because Mercurial only tracks two parents for
  11.509 +	both revisions and the working directory.  While it would be
  11.510 +	technically possible to merge multiple changesets at once, the
  11.511 +	prospect of user confusion and making a terrible mess of a
  11.512 +	merge immediately becomes overwhelming.</para>
  11.513 +
  11.514 +    </sect2>
  11.515 +  </sect1>
  11.516 +  <sect1>
  11.517 +    <title>Other interesting design features</title>
  11.518 +
  11.519 +    <para>In the sections above, I've tried to highlight some of the
  11.520 +      most important aspects of Mercurial's design, to illustrate that
  11.521 +      it pays careful attention to reliability and performance.
  11.522 +      However, the attention to detail doesn't stop there.  There are
  11.523 +      a number of other aspects of Mercurial's construction that I
  11.524 +      personally find interesting.  I'll detail a few of them here,
  11.525 +      separate from the <quote>big ticket</quote> items above, so that
  11.526 +      if you're interested, you can gain a better idea of the amount
  11.527 +      of thinking that goes into a well-designed system.</para>
  11.528 +
  11.529 +    <sect2>
  11.530 +      <title>Clever compression</title>
  11.531 +
  11.532 +      <para>When appropriate, Mercurial will store both snapshots and
  11.533 +	deltas in compressed form.  It does this by always
  11.534 +	<emphasis>trying to</emphasis> compress a snapshot or delta,
  11.535 +	but only storing the compressed version if it's smaller than
  11.536 +	the uncompressed version.</para>
  11.537 +
  11.538 +      <para>This means that Mercurial does <quote>the right
  11.539 +	  thing</quote> when storing a file whose native form is
  11.540 +	compressed, such as a <literal>zip</literal> archive or a JPEG
  11.541 +	image.  When these types of files are compressed a second
  11.542 +	time, the resulting file is usually bigger than the
  11.543 +	once-compressed form, and so Mercurial will store the plain
  11.544 +	<literal>zip</literal> or JPEG.</para>
  11.545 +
  11.546 +      <para>Deltas between revisions of a compressed file are usually
  11.547 +	larger than snapshots of the file, and Mercurial again does
  11.548 +	<quote>the right thing</quote> in these cases.  It finds that
  11.549 +	such a delta exceeds the threshold at which it should store a
  11.550 +	complete snapshot of the file, so it stores the snapshot,
  11.551 +	again saving space compared to a naive delta-only
  11.552 +	approach.</para>
  11.553 +
  11.554 +      <sect3>
  11.555 +	<title>Network recompression</title>
  11.556 +
  11.557 +	<para>When storing revisions on disk, Mercurial uses the
  11.558 +	  <quote>deflate</quote> compression algorithm (the same one
  11.559 +	  used by the popular <literal>zip</literal> archive format),
  11.560 +	  which balances good speed with a respectable compression
  11.561 +	  ratio.  However, when transmitting revision data over a
  11.562 +	  network connection, Mercurial uncompresses the compressed
  11.563 +	  revision data.</para>
  11.564 +
  11.565 +	<para>If the connection is over HTTP, Mercurial recompresses
  11.566 +	  the entire stream of data using a compression algorithm that
  11.567 +	  gives a better compression ratio (the Burrows-Wheeler
  11.568 +	  algorithm from the widely used <literal>bzip2</literal>
  11.569 +	  compression package).  This combination of algorithm and
  11.570 +	  compression of the entire stream (instead of a revision at a
  11.571 +	  time) substantially reduces the number of bytes to be
  11.572 +	  transferred, yielding better network performance over almost
  11.573 +	  all kinds of network.</para>
  11.574 +
  11.575 +	<para>(If the connection is over <command>ssh</command>,
  11.576 +	  Mercurial <emphasis>doesn't</emphasis> recompress the
  11.577 +	  stream, because <command>ssh</command> can already do this
  11.578 +	  itself.)</para>
  11.579 +
  11.580 +      </sect3>
  11.581 +    </sect2>
  11.582 +    <sect2>
  11.583 +      <title>Read/write ordering and atomicity</title>
  11.584 +
  11.585 +      <para>Appending to files isn't the whole story when it comes to
  11.586 +	guaranteeing that a reader won't see a partial write.  If you
  11.587 +	recall figure <xref linkend="fig:concepts:metadata"/>,
  11.588 +	revisions in the
  11.589 +	changelog point to revisions in the manifest, and revisions in
  11.590 +	the manifest point to revisions in filelogs.  This hierarchy
  11.591 +	is deliberate.</para>
  11.592 +
  11.593 +      <para>A writer starts a transaction by writing filelog and
  11.594 +	manifest data, and doesn't write any changelog data until
  11.595 +	those are finished.  A reader starts by reading changelog
  11.596 +	data, then manifest data, followed by filelog data.</para>
  11.597 +
  11.598 +      <para>Since the writer has always finished writing filelog and
  11.599 +	manifest data before it writes to the changelog, a reader will
  11.600 +	never read a pointer to a partially written manifest revision
  11.601 +	from the changelog, and it will never read a pointer to a
  11.602 +	partially written filelog revision from the manifest.</para>
  11.603 +
  11.604 +    </sect2>
  11.605 +    <sect2>
  11.606 +      <title>Concurrent access</title>
  11.607 +
  11.608 +      <para>The read/write ordering and atomicity guarantees mean that
  11.609 +	Mercurial never needs to <emphasis>lock</emphasis> a
  11.610 +	repository when it's reading data, even if the repository is
  11.611 +	being written to while the read is occurring. This has a big
  11.612 +	effect on scalability; you can have an arbitrary number of
  11.613 +	Mercurial processes safely reading data from a repository
  11.614 +	safely all at once, no matter whether it's being written to or
  11.615 +	not.</para>
  11.616 +
  11.617 +      <para>The lockless nature of reading means that if you're
  11.618 +	sharing a repository on a multi-user system, you don't need to
  11.619 +	grant other local users permission to
  11.620 +	<emphasis>write</emphasis> to your repository in order for
  11.621 +	them to be able to clone it or pull changes from it; they only
  11.622 +	need <emphasis>read</emphasis> permission.  (This is
  11.623 +	<emphasis>not</emphasis> a common feature among revision
  11.624 +	control systems, so don't take it for granted!  Most require
  11.625 +	readers to be able to lock a repository to access it safely,
  11.626 +	and this requires write permission on at least one directory,
  11.627 +	which of course makes for all kinds of nasty and annoying
  11.628 +	security and administrative problems.)</para>
  11.629 +
  11.630 +      <para>Mercurial uses locks to ensure that only one process can
  11.631 +	write to a repository at a time (the locking mechanism is safe
  11.632 +	even over filesystems that are notoriously hostile to locking,
  11.633 +	such as NFS).  If a repository is locked, a writer will wait
  11.634 +	for a while to retry if the repository becomes unlocked, but
  11.635 +	if the repository remains locked for too long, the process
  11.636 +	attempting to write will time out after a while. This means
  11.637 +	that your daily automated scripts won't get stuck forever and
  11.638 +	pile up if a system crashes unnoticed, for example.  (Yes, the
  11.639 +	timeout is configurable, from zero to infinity.)</para>
  11.640 +
  11.641 +      <sect3>
  11.642 +	<title>Safe dirstate access</title>
  11.643 +
  11.644 +	<para>As with revision data, Mercurial doesn't take a lock to
  11.645 +	  read the dirstate file; it does acquire a lock to write it.
  11.646 +	  To avoid the possibility of reading a partially written copy
  11.647 +	  of the dirstate file, Mercurial writes to a file with a
  11.648 +	  unique name in the same directory as the dirstate file, then
  11.649 +	  renames the temporary file atomically to
  11.650 +	  <filename>dirstate</filename>.  The file named
  11.651 +	  <filename>dirstate</filename> is thus guaranteed to be
  11.652 +	  complete, not partially written.</para>
  11.653 +
  11.654 +      </sect3>
  11.655 +    </sect2>
  11.656 +    <sect2>
  11.657 +      <title>Avoiding seeks</title>
  11.658 +
  11.659 +      <para>Critical to Mercurial's performance is the avoidance of
  11.660 +	seeks of the disk head, since any seek is far more expensive
  11.661 +	than even a comparatively large read operation.</para>
  11.662 +
  11.663 +      <para>This is why, for example, the dirstate is stored in a
  11.664 +	single file.  If there were a dirstate file per directory that
  11.665 +	Mercurial tracked, the disk would seek once per directory.
  11.666 +	Instead, Mercurial reads the entire single dirstate file in
  11.667 +	one step.</para>
  11.668 +
  11.669 +      <para>Mercurial also uses a <quote>copy on write</quote> scheme
  11.670 +	when cloning a repository on local storage.  Instead of
  11.671 +	copying every revlog file from the old repository into the new
  11.672 +	repository, it makes a <quote>hard link</quote>, which is a
  11.673 +	shorthand way to say <quote>these two names point to the same
  11.674 +	  file</quote>.  When Mercurial is about to write to one of a
  11.675 +	revlog's files, it checks to see if the number of names
  11.676 +	pointing at the file is greater than one.  If it is, more than
  11.677 +	one repository is using the file, so Mercurial makes a new
  11.678 +	copy of the file that is private to this repository.</para>
  11.679 +
  11.680 +      <para>A few revision control developers have pointed out that
  11.681 +	this idea of making a complete private copy of a file is not
  11.682 +	very efficient in its use of storage.  While this is true,
  11.683 +	storage is cheap, and this method gives the highest
  11.684 +	performance while deferring most book-keeping to the operating
  11.685 +	system.  An alternative scheme would most likely reduce
  11.686 +	performance and increase the complexity of the software, each
  11.687 +	of which is much more important to the <quote>feel</quote> of
  11.688 +	day-to-day use.</para>
  11.689 +
  11.690 +    </sect2>
  11.691 +    <sect2>
  11.692 +      <title>Other contents of the dirstate</title>
  11.693 +
  11.694 +      <para>Because Mercurial doesn't force you to tell it when you're
  11.695 +	modifying a file, it uses the dirstate to store some extra
  11.696 +	information so it can determine efficiently whether you have
  11.697 +	modified a file.  For each file in the working directory, it
  11.698 +	stores the time that it last modified the file itself, and the
  11.699 +	size of the file at that time.</para>
  11.700 +
  11.701 +      <para>When you explicitly <command role="hg-cmd">hg
  11.702 +	  add</command>, <command role="hg-cmd">hg remove</command>,
  11.703 +	<command role="hg-cmd">hg rename</command> or <command
  11.704 +	  role="hg-cmd">hg copy</command> files, Mercurial updates the
  11.705 +	dirstate so that it knows what to do with those files when you
  11.706 +	commit.</para>
  11.707 +
  11.708 +      <para>When Mercurial is checking the states of files in the
  11.709 +	working directory, it first checks a file's modification time.
  11.710 +	If that has not changed, the file must not have been modified.
  11.711 +	If the file's size has changed, the file must have been
  11.712 +	modified.  If the modification time has changed, but the size
  11.713 +	has not, only then does Mercurial need to read the actual
  11.714 +	contents of the file to see if they've changed. Storing these
  11.715 +	few extra pieces of information dramatically reduces the
  11.716 +	amount of data that Mercurial needs to read, which yields
  11.717 +	large performance improvements compared to other revision
  11.718 +	control systems.</para>
  11.719 +
  11.720 +    </sect2>
  11.721 +  </sect1>
  11.722 +</chapter>
  11.723 +
  11.724 +<!--
  11.725 +local variables: 
  11.726 +sgml-parent-document: ("00book.xml" "book" "chapter")
  11.727 +end:
  11.728 +-->

    12.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    12.2 +++ b/en/ch05-daily.xml	Wed Feb 18 00:22:09 2009 -0800
    12.3 @@ -0,0 +1,490 @@
    12.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    12.5 +
    12.6 +<chapter id="chap:daily">
    12.7 +  <title>Mercurial in daily use</title>
    12.8 +
    12.9 +  <sect1>
   12.10 +    <title>Telling Mercurial which files to track</title>
   12.11 +
   12.12 +    <para>Mercurial does not work with files in your repository unless
   12.13 +      you tell it to manage them.  The <command role="hg-cmd">hg
   12.14 +	status</command> command will tell you which files Mercurial
   12.15 +      doesn't know about; it uses a
   12.16 +      <quote><literal>?</literal></quote> to display such
   12.17 +      files.</para>
   12.18 +
   12.19 +    <para>To tell Mercurial to track a file, use the <command
   12.20 +	role="hg-cmd">hg add</command> command.  Once you have added a
   12.21 +      file, the entry in the output of <command role="hg-cmd">hg
   12.22 +	status</command> for that file changes from
   12.23 +      <quote><literal>?</literal></quote> to
   12.24 +      <quote><literal>A</literal></quote>. <!--
   12.25 +      &interaction.daily.files.add; --></para>
   12.26 +
   12.27 +    <para>After you run a <command role="hg-cmd">hg commit</command>,
   12.28 +      the files that you added before the commit will no longer be
   12.29 +      listed in the output of <command role="hg-cmd">hg
   12.30 +	status</command>.  The reason for this is that <command
   12.31 +	role="hg-cmd">hg status</command> only tells you about
   12.32 +      <quote>interesting</quote> files&emdash;those that you have
   12.33 +      modified or told Mercurial to do something with&emdash;by
   12.34 +      default.  If you have a repository that contains thousands of
   12.35 +      files, you will rarely want to know about files that Mercurial
   12.36 +      is tracking, but that have not changed.  (You can still get this
   12.37 +      information; we'll return to this later.)</para>
   12.38 +
   12.39 +    <para>Once you add a file, Mercurial doesn't do anything with it
   12.40 +      immediately.  Instead, it will take a snapshot of the file's
   12.41 +      state the next time you perform a commit.  It will then continue
   12.42 +      to track the changes you make to the file every time you commit,
   12.43 +      until you remove the file.</para>
   12.44 +
   12.45 +    <sect2>
   12.46 +      <title>Explicit versus implicit file naming</title>
   12.47 +
   12.48 +      <para>A useful behaviour that Mercurial has is that if you pass
   12.49 +	the name of a directory to a command, every Mercurial command
   12.50 +	will treat this as <quote>I want to operate on every file in
   12.51 +	  this directory and its subdirectories</quote>. <!--
   12.52 +	&interaction.daily.files.add-dir; --> Notice in this example
   12.53 +	that Mercurial printed the names of the files it added,
   12.54 +	whereas it didn't do so when we added the file named
   12.55 +	<filename>a</filename> in the earlier example.</para>
   12.56 +
   12.57 +      <para>What's going on is that in the former case, we explicitly
   12.58 +	named the file to add on the command line, so the assumption
   12.59 +	that Mercurial makes in such cases is that you know what you
   12.60 +	were doing, and it doesn't print any output.</para>
   12.61 +
   12.62 +      <para>However, when we <emphasis>imply</emphasis> the names of
   12.63 +	files by giving the name of a directory, Mercurial takes the
   12.64 +	extra step of printing the name of each file that it does
   12.65 +	something with.  This makes it more clear what is happening,
   12.66 +	and reduces the likelihood of a silent and nasty surprise.
   12.67 +	This behaviour is common to most Mercurial commands.</para>
   12.68 +
   12.69 +    </sect2>
   12.70 +    <sect2>
   12.71 +      <title>Aside: Mercurial tracks files, not directories</title>
   12.72 +
   12.73 +      <para>Mercurial does not track directory information.  Instead,
   12.74 +	it tracks the path to a file.  Before creating a file, it
   12.75 +	first creates any missing directory components of the path.
   12.76 +	After it deletes a file, it then deletes any empty directories
   12.77 +	that were in the deleted file's path.  This sounds like a
   12.78 +	trivial distinction, but it has one minor practical
   12.79 +	consequence: it is not possible to represent a completely
   12.80 +	empty directory in Mercurial.</para>
   12.81 +
   12.82 +      <para>Empty directories are rarely useful, and there are
   12.83 +	unintrusive workarounds that you can use to achieve an
   12.84 +	appropriate effect.  The developers of Mercurial thus felt
   12.85 +	that the complexity that would be required to manage empty
   12.86 +	directories was not worth the limited benefit this feature
   12.87 +	would bring.</para>
   12.88 +
   12.89 +      <para>If you need an empty directory in your repository, there
   12.90 +	are a few ways to achieve this. One is to create a directory,
   12.91 +	then <command role="hg-cmd">hg add</command> a
   12.92 +	<quote>hidden</quote> file to that directory.  On Unix-like
   12.93 +	systems, any file name that begins with a period
   12.94 +	(<quote><literal>.</literal></quote>) is treated as hidden by
   12.95 +	most commands and GUI tools.  This approach is illustrated
   12.96 +	below.</para>
   12.97 +
   12.98 +<!-- &interaction.daily.files.hidden; -->
   12.99 +
  12.100 +      <para>Another way to tackle a need for an empty directory is to
  12.101 +	simply create one in your automated build scripts before they
  12.102 +	will need it.</para>
  12.103 +
  12.104 +    </sect2>
  12.105 +  </sect1>
  12.106 +  <sect1>
  12.107 +    <title>How to stop tracking a file</title>
  12.108 +
  12.109 +    <para>Once you decide that a file no longer belongs in your
  12.110 +      repository, use the <command role="hg-cmd">hg remove</command>
  12.111 +      command; this deletes the file, and tells Mercurial to stop
  12.112 +      tracking it.  A removed file is represented in the output of
  12.113 +      <command role="hg-cmd">hg status</command> with a
  12.114 +      <quote><literal>R</literal></quote>. <!--
  12.115 +      &interaction.daily.files.remove; --></para>
  12.116 +
  12.117 +    <para>After you <command role="hg-cmd">hg remove</command> a file,
  12.118 +      Mercurial will no longer track changes to that file, even if you
  12.119 +      recreate a file with the same name in your working directory.
  12.120 +      If you do recreate a file with the same name and want Mercurial
  12.121 +      to track the new file, simply <command role="hg-cmd">hg
  12.122 +	add</command> it. Mercurial will know that the newly added
  12.123 +      file is not related to the old file of the same name.</para>
  12.124 +
  12.125 +    <sect2>
  12.126 +      <title>Removing a file does not affect its history</title>
  12.127 +
  12.128 +      <para>It is important to understand that removing a file has
  12.129 +	only two effects.</para>
  12.130 +      <itemizedlist>
  12.131 +	<listitem><para>It removes the current version of the file
  12.132 +	    from the working directory.</para>
  12.133 +	</listitem>
  12.134 +	<listitem><para>It stops Mercurial from tracking changes to
  12.135 +	    the file, from the time of the next commit.</para>
  12.136 +	</listitem></itemizedlist>
  12.137 +      <para>Removing a file <emphasis>does not</emphasis> in any way
  12.138 +	alter the <emphasis>history</emphasis> of the file.</para>
  12.139 +
  12.140 +      <para>If you update the working directory to a changeset in
  12.141 +	which a file that you have removed was still tracked, it will
  12.142 +	reappear in the working directory, with the contents it had
  12.143 +	when you committed that changeset.  If you then update the
  12.144 +	working directory to a later changeset, in which the file had
  12.145 +	been removed, Mercurial will once again remove the file from
  12.146 +	the working directory.</para>
  12.147 +
  12.148 +    </sect2>
  12.149 +    <sect2>
  12.150 +      <title>Missing files</title>
  12.151 +
  12.152 +      <para>Mercurial considers a file that you have deleted, but not
  12.153 +	used <command role="hg-cmd">hg remove</command> to delete, to
  12.154 +	be <emphasis>missing</emphasis>.  A missing file is
  12.155 +	represented with <quote><literal>!</literal></quote> in the
  12.156 +	output of <command role="hg-cmd">hg status</command>.
  12.157 +	Mercurial commands will not generally do anything with missing
  12.158 +	files. <!-- &interaction.daily.files.missing; --></para>
  12.159 +
  12.160 +      <para>If your repository contains a file that <command
  12.161 +	  role="hg-cmd">hg status</command> reports as missing, and
  12.162 +	you want the file to stay gone, you can run <command
  12.163 +	  role="hg-cmd">hg remove <option
  12.164 +	    role="hg-opt-remove">--after</option></command> at any
  12.165 +	time later on, to tell Mercurial that you really did mean to
  12.166 +	remove the file. <!-- &interaction.daily.files.remove-after;
  12.167 +	--></para>
  12.168 +
  12.169 +      <para>On the other hand, if you deleted the missing file by
  12.170 +	accident, give <command role="hg-cmd">hg revert</command> the
  12.171 +	name of the file to recover.  It will reappear, in unmodified
  12.172 +	form.</para>
  12.173 +
  12.174 +<!-- &interaction.daily.files.recover-missing; -->
  12.175 +
  12.176 +    </sect2>
  12.177 +    <sect2>
  12.178 +      <title>Aside: why tell Mercurial explicitly to remove a
  12.179 +	file?</title>
  12.180 +
  12.181 +      <para>You might wonder why Mercurial requires you to explicitly
  12.182 +	tell it that you are deleting a file.  Early during the
  12.183 +	development of Mercurial, it let you delete a file however you
  12.184 +	pleased; Mercurial would notice the absence of the file
  12.185 +	automatically when you next ran a <command role="hg-cmd">hg
  12.186 +	  commit</command>, and stop tracking the file.  In practice,
  12.187 +	this made it too easy to accidentally remove a file without
  12.188 +	noticing.</para>
  12.189 +
  12.190 +    </sect2>
  12.191 +    <sect2>
  12.192 +      <title>Useful shorthand&emdash;adding and removing files in one
  12.193 +	step</title>
  12.194 +
  12.195 +      <para>Mercurial offers a combination command, <command
  12.196 +	  role="hg-cmd">hg addremove</command>, that adds untracked
  12.197 +	files and marks missing files as removed. <!--
  12.198 +	&interaction.daily.files.addremove; --> The <command
  12.199 +	  role="hg-cmd">hg commit</command> command also provides a
  12.200 +	<option role="hg-opt-commit">-A</option> option that performs
  12.201 +	this same add-and-remove, immediately followed by a commit.
  12.202 +	<!-- &interaction.daily.files.commit-addremove; --></para>
  12.203 +
  12.204 +    </sect2>
  12.205 +  </sect1>
  12.206 +  <sect1>
  12.207 +    <title>Copying files</title>
  12.208 +
  12.209 +    <para>Mercurial provides a <command role="hg-cmd">hg
  12.210 +	copy</command> command that lets you make a new copy of a
  12.211 +      file.  When you copy a file using this command, Mercurial makes
  12.212 +      a record of the fact that the new file is a copy of the original
  12.213 +      file.  It treats these copied files specially when you merge
  12.214 +      your work with someone else's.</para>
  12.215 +
  12.216 +    <sect2>
  12.217 +      <title>The results of copying during a merge</title>
  12.218 +
  12.219 +      <para>What happens during a merge is that changes
  12.220 +	<quote>follow</quote> a copy.  To best illustrate what this
  12.221 +	means, let's create an example.  We'll start with the usual
  12.222 +	tiny repository that contains a single file. <!--
  12.223 +	&interaction.daily.copy.init; --> We need to do some work in
  12.224 +	parallel, so that we'll have something to merge.  So let's
  12.225 +	clone our repository. <!-- &interaction.daily.copy.clone; -->
  12.226 +	Back in our initial repository, let's use the <command
  12.227 +	  role="hg-cmd">hg copy</command> command to make a copy of
  12.228 +	the first file we created. <!-- &interaction.daily.copy.copy;
  12.229 +	--></para>
  12.230 +
  12.231 +      <para>If we look at the output of the <command role="hg-cmd">hg
  12.232 +	  status</command> command afterwards, the copied file looks
  12.233 +	just like a normal added file. <!--
  12.234 +	&interaction.daily.copy.status; --> But if we pass the <option
  12.235 +	  role="hg-opt-status">-C</option> option to <command
  12.236 +	  role="hg-cmd">hg status</command>, it prints another line of
  12.237 +	output: this is the file that our newly-added file was copied
  12.238 +	<emphasis>from</emphasis>. <!--
  12.239 +	&interaction.daily.copy.status-copy; --></para>
  12.240 +
  12.241 +      <para>Now, back in the repository we cloned, let's make a change
  12.242 +	in parallel.  We'll add a line of content to the original file
  12.243 +	that we created. <!-- &interaction.daily.copy.other; --> Now
  12.244 +	we have a modified <filename>file</filename> in this
  12.245 +	repository.  When we pull the changes from the first
  12.246 +	repository, and merge the two heads, Mercurial will propagate
  12.247 +	the changes that we made locally to <filename>file</filename>
  12.248 +	into its copy, <filename>new-file</filename>. <!--
  12.249 +	&interaction.daily.copy.merge; --></para>
  12.250 +
  12.251 +    </sect2>
  12.252 +    <sect2 id="sec:daily:why-copy">
  12.253 +      <title>Why should changes follow copies?</title>
  12.254 +
  12.255 +      <para>This behaviour, of changes to a file propagating out to
  12.256 +	copies of the file, might seem esoteric, but in most cases
  12.257 +	it's highly desirable.</para>
  12.258 +
  12.259 +      <para>First of all, remember that this propagation
  12.260 +	<emphasis>only</emphasis> happens when you merge.  So if you
  12.261 +	<command role="hg-cmd">hg copy</command> a file, and
  12.262 +	subsequently modify the original file during the normal course
  12.263 +	of your work, nothing will happen.</para>
  12.264 +
  12.265 +      <para>The second thing to know is that modifications will only
  12.266 +	propagate across a copy as long as the repository that you're
  12.267 +	pulling changes from <emphasis>doesn't know</emphasis> about
  12.268 +	the copy.</para>
  12.269 +
  12.270 +      <para>The reason that Mercurial does this is as follows.  Let's
  12.271 +	say I make an important bug fix in a source file, and commit
  12.272 +	my changes. Meanwhile, you've decided to <command
  12.273 +	  role="hg-cmd">hg copy</command> the file in your repository,
  12.274 +	without knowing about the bug or having seen the fix, and you
  12.275 +	have started hacking on your copy of the file.</para>
  12.276 +
  12.277 +      <para>If you pulled and merged my changes, and Mercurial
  12.278 +	<emphasis>didn't</emphasis> propagate changes across copies,
  12.279 +	your source file would now contain the bug, and unless you
  12.280 +	remembered to propagate the bug fix by hand, the bug would
  12.281 +	<emphasis>remain</emphasis> in your copy of the file.</para>
  12.282 +
  12.283 +      <para>By automatically propagating the change that fixed the bug
  12.284 +	from the original file to the copy, Mercurial prevents this
  12.285 +	class of problem. To my knowledge, Mercurial is the
  12.286 +	<emphasis>only</emphasis> revision control system that
  12.287 +	propagates changes across copies like this.</para>
  12.288 +
  12.289 +      <para>Once your change history has a record that the copy and
  12.290 +	subsequent merge occurred, there's usually no further need to
  12.291 +	propagate changes from the original file to the copied file,
  12.292 +	and that's why Mercurial only propagates changes across copies
  12.293 +	until this point, and no further.</para>
  12.294 +
  12.295 +    </sect2>
  12.296 +    <sect2>
  12.297 +      <title>How to make changes <emphasis>not</emphasis> follow a
  12.298 +	copy</title>
  12.299 +
  12.300 +      <para>If, for some reason, you decide that this business of
  12.301 +	automatically propagating changes across copies is not for
  12.302 +	you, simply use your system's normal file copy command (on
  12.303 +	Unix-like systems, that's <command>cp</command>) to make a
  12.304 +	copy of a file, then <command role="hg-cmd">hg add</command>
  12.305 +	the new copy by hand.  Before you do so, though, please do
  12.306 +	reread section <xref linkend="sec:daily:why-copy"/>, and make
  12.307 +	an informed
  12.308 +	decision that this behaviour is not appropriate to your
  12.309 +	specific case.</para>
  12.310 +
  12.311 +    </sect2>
  12.312 +    <sect2>
  12.313 +      <title>Behaviour of the <command role="hg-cmd">hg copy</command>
  12.314 +	command</title>
  12.315 +
  12.316 +      <para>When you use the <command role="hg-cmd">hg copy</command>
  12.317 +	command, Mercurial makes a copy of each source file as it
  12.318 +	currently stands in the working directory.  This means that if
  12.319 +	you make some modifications to a file, then <command
  12.320 +	  role="hg-cmd">hg copy</command> it without first having
  12.321 +	committed those changes, the new copy will also contain the
  12.322 +	modifications you have made up until that point.  (I find this
  12.323 +	behaviour a little counterintuitive, which is why I mention it
  12.324 +	here.)</para>
  12.325 +
  12.326 +      <para>The <command role="hg-cmd">hg copy</command> command acts
  12.327 +	similarly to the Unix <command>cp</command> command (you can
  12.328 +	use the <command role="hg-cmd">hg cp</command> alias if you
  12.329 +	prefer).  The last argument is the
  12.330 +	<emphasis>destination</emphasis>, and all prior arguments are
  12.331 +	<emphasis>sources</emphasis>.  If you pass it a single file as
  12.332 +	the source, and the destination does not exist, it creates a
  12.333 +	new file with that name. <!-- &interaction.daily.copy.simple;
  12.334 +	--> If the destination is a directory, Mercurial copies its
  12.335 +	sources into that directory. <!--
  12.336 +	&interaction.daily.copy.dir-dest; --> Copying a directory is
  12.337 +	recursive, and preserves the directory structure of the
  12.338 +	source. <!-- &interaction.daily.copy.dir-src; --> If the
  12.339 +	source and destination are both directories, the source tree
  12.340 +	is recreated in the destination directory. <!--
  12.341 +	&interaction.daily.copy.dir-src-dest; --></para>
  12.342 +
  12.343 +      <para>As with the <command role="hg-cmd">hg rename</command>
  12.344 +	command, if you copy a file manually and then want Mercurial
  12.345 +	to know that you've copied the file, simply use the <option
  12.346 +	  role="hg-opt-copy">--after</option> option to <command
  12.347 +	  role="hg-cmd">hg copy</command>. <!--
  12.348 +	&interaction.daily.copy.after; --></para>
  12.349 +
  12.350 +    </sect2>
  12.351 +  </sect1>
  12.352 +  <sect1>
  12.353 +    <title>Renaming files</title>
  12.354 +
  12.355 +    <para>It's rather more common to need to rename a file than to
  12.356 +      make a copy of it.  The reason I discussed the <command
  12.357 +	role="hg-cmd">hg copy</command> command before talking about
  12.358 +      renaming files is that Mercurial treats a rename in essentially
  12.359 +      the same way as a copy.  Therefore, knowing what Mercurial does
  12.360 +      when you copy a file tells you what to expect when you rename a
  12.361 +      file.</para>
  12.362 +
  12.363 +    <para>When you use the <command role="hg-cmd">hg rename</command>
  12.364 +      command, Mercurial makes a copy of each source file, then
  12.365 +      deletes it and marks the file as removed. <!--
  12.366 +      &interaction.daily.rename.rename; --> The <command
  12.367 +	role="hg-cmd">hg status</command> command shows the newly
  12.368 +      copied file as added, and the copied-from file as removed. <!--
  12.369 +      &interaction.daily.rename.status; --> As with the results of a
  12.370 +      <command role="hg-cmd">hg copy</command>, we must use the
  12.371 +      <option role="hg-opt-status">-C</option> option to <command
  12.372 +	role="hg-cmd">hg status</command> to see that the added file
  12.373 +      is really being tracked by Mercurial as a copy of the original,
  12.374 +      now removed, file. <!-- &interaction.daily.rename.status-copy;
  12.375 +      --></para>
  12.376 +
  12.377 +    <para>As with <command role="hg-cmd">hg remove</command> and
  12.378 +      <command role="hg-cmd">hg copy</command>, you can tell Mercurial
  12.379 +      about a rename after the fact using the <option
  12.380 +	role="hg-opt-rename">--after</option> option.  In most other
  12.381 +      respects, the behaviour of the <command role="hg-cmd">hg
  12.382 +	rename</command> command, and the options it accepts, are
  12.383 +      similar to the <command role="hg-cmd">hg copy</command>
  12.384 +      command.</para>
  12.385 +
  12.386 +    <sect2>
  12.387 +      <title>Renaming files and merging changes</title>
  12.388 +
  12.389 +      <para>Since Mercurial's rename is implemented as
  12.390 +	copy-and-remove, the same propagation of changes happens when
  12.391 +	you merge after a rename as after a copy.</para>
  12.392 +
  12.393 +      <para>If I modify a file, and you rename it to a new name, and
  12.394 +	then we merge our respective changes, my modifications to the
  12.395 +	file under its original name will be propagated into the file
  12.396 +	under its new name. (This is something you might expect to
  12.397 +	<quote>simply work,</quote> but not all revision control
  12.398 +	systems actually do this.)</para>
  12.399 +
  12.400 +      <para>Whereas having changes follow a copy is a feature where
  12.401 +	you can perhaps nod and say <quote>yes, that might be
  12.402 +	  useful,</quote> it should be clear that having them follow a
  12.403 +	rename is definitely important.  Without this facility, it
  12.404 +	would simply be too easy for changes to become orphaned when
  12.405 +	files are renamed.</para>
  12.406 +
  12.407 +    </sect2>
  12.408 +    <sect2>
  12.409 +      <title>Divergent renames and merging</title>
  12.410 +
  12.411 +      <para>The case of diverging names occurs when two developers
  12.412 +	start with a file&emdash;let's call it
  12.413 +	<filename>foo</filename>&emdash;in their respective
  12.414 +	repositories.</para>
  12.415 +
  12.416 +      <para><!-- &interaction.rename.divergent.clone; --> Anne renames
  12.417 +	the file to <filename>bar</filename>. <!--
  12.418 +	&interaction.rename.divergent.rename.anne; --> Meanwhile, Bob
  12.419 +	renames it to <filename>quux</filename>. <!--
  12.420 +	&interaction.rename.divergent.rename.bob; --></para>
  12.421 +
  12.422 +      <para>I like to think of this as a conflict because each
  12.423 +	developer has expressed different intentions about what the
  12.424 +	file ought to be named.</para>
  12.425 +
  12.426 +      <para>What do you think should happen when they merge their
  12.427 +	work? Mercurial's actual behaviour is that it always preserves
  12.428 +	<emphasis>both</emphasis> names when it merges changesets that
  12.429 +	contain divergent renames. <!--
  12.430 +	&interaction.rename.divergent.merge; --></para>
  12.431 +
  12.432 +      <para>Notice that Mercurial does warn about the divergent
  12.433 +	renames, but it leaves it up to you to do something about the
  12.434 +	divergence after the merge.</para>
  12.435 +
  12.436 +    </sect2>
  12.437 +    <sect2>
  12.438 +      <title>Convergent renames and merging</title>
  12.439 +
  12.440 +      <para>Another kind of rename conflict occurs when two people
  12.441 +	choose to rename different <emphasis>source</emphasis> files
  12.442 +	to the same <emphasis>destination</emphasis>. In this case,
  12.443 +	Mercurial runs its normal merge machinery, and lets you guide
  12.444 +	it to a suitable resolution.</para>
  12.445 +
  12.446 +    </sect2>
  12.447 +    <sect2>
  12.448 +      <title>Other name-related corner cases</title>
  12.449 +
  12.450 +      <para>Mercurial has a longstanding bug in which it fails to
  12.451 +	handle a merge where one side has a file with a given name,
  12.452 +	while another has a directory with the same name.  This is
  12.453 +	documented as <ulink role="hg-bug"
  12.454 +	  url="http://www.selenic.com/mercurial/bts/issue29">issue
  12.455 +	  29</ulink>. <!-- &interaction.issue29.go; --></para>
  12.456 +
  12.457 +    </sect2>
  12.458 +  </sect1>
  12.459 +  <sect1>
  12.460 +    <title>Recovering from mistakes</title>
  12.461 +
  12.462 +    <para>Mercurial has some useful commands that will help you to
  12.463 +      recover from some common mistakes.</para>
  12.464 +
  12.465 +    <para>The <command role="hg-cmd">hg revert</command> command lets
  12.466 +      you undo changes that you have made to your working directory.
  12.467 +      For example, if you <command role="hg-cmd">hg add</command> a
  12.468 +      file by accident, just run <command role="hg-cmd">hg
  12.469 +	revert</command> with the name of the file you added, and
  12.470 +      while the file won't be touched in any way, it won't be tracked
  12.471 +      for adding by Mercurial any longer, either.  You can also use
  12.472 +      <command role="hg-cmd">hg revert</command> to get rid of
  12.473 +      erroneous changes to a file.</para>
  12.474 +
  12.475 +    <para>It's useful to remember that the <command role="hg-cmd">hg
  12.476 +	revert</command> command is useful for changes that you have
  12.477 +      not yet committed.  Once you've committed a change, if you
  12.478 +      decide it was a mistake, you can still do something about it,
  12.479 +      though your options may be more limited.</para>
  12.480 +
  12.481 +    <para>For more information about the <command role="hg-cmd">hg
  12.482 +	revert</command> command, and details about how to deal with
  12.483 +      changes you have already committed, see chapter <xref
  12.484 +	linkend="chap:undo"/>.</para>
  12.485 +
  12.486 +  </sect1>
  12.487 +</chapter>
  12.488 +
  12.489 +<!--
  12.490 +local variables: 
  12.491 +sgml-parent-document: ("00book.xml" "book" "chapter")
  12.492 +end:
  12.493 +-->

    13.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    13.2 +++ b/en/ch06-collab.xml	Wed Feb 18 00:22:09 2009 -0800
    13.3 @@ -0,0 +1,1415 @@
    13.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
    13.5 +
    13.6 +<chapter id="cha:collab">
    13.7 +  <title>Collaborating with other people</title>
    13.8 +
    13.9 +  <para>As a completely decentralised tool, Mercurial doesn't impose
   13.10 +    any policy on how people ought to work with each other.  However,
   13.11 +    if you're new to distributed revision control, it helps to have
   13.12 +    some tools and examples in mind when you're thinking about
   13.13 +    possible workflow models.</para>
   13.14 +
   13.15 +  <sect1>
   13.16 +    <title>Mercurial's web interface</title>
   13.17 +
   13.18 +    <para>Mercurial has a powerful web interface that provides several
   13.19 +      useful capabilities.</para>
   13.20 +
   13.21 +    <para>For interactive use, the web interface lets you browse a
   13.22 +      single repository or a collection of repositories.  You can view
   13.23 +      the history of a repository, examine each change (comments and
   13.24 +      diffs), and view the contents of each directory and file.</para>
   13.25 +
   13.26 +    <para>Also for human consumption, the web interface provides an
   13.27 +      RSS feed of the changes in a repository.  This lets you
   13.28 +      <quote>subscribe</quote> to a repository using your favourite
   13.29 +      feed reader, and be automatically notified of activity in that
   13.30 +      repository as soon as it happens.  I find this capability much
   13.31 +      more convenient than the model of subscribing to a mailing list
   13.32 +      to which notifications are sent, as it requires no additional
   13.33 +      configuration on the part of whoever is serving the
   13.34 +      repository.</para>
   13.35 +
   13.36 +    <para>The web interface also lets remote users clone a repository,
   13.37 +      pull changes from it, and (when the server is configured to
   13.38 +      permit it) push changes back to it.  Mercurial's HTTP tunneling
   13.39 +      protocol aggressively compresses data, so that it works
   13.40 +      efficiently even over low-bandwidth network connections.</para>
   13.41 +
   13.42 +    <para>The easiest way to get started with the web interface is to
   13.43 +      use your web browser to visit an existing repository, such as
   13.44 +      the master Mercurial repository at <ulink
   13.45 +	url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para>
   13.46 +
   13.47 +    <para>If you're interested in providing a web interface to your
   13.48 +      own repositories, Mercurial provides two ways to do this.  The
   13.49 +      first is using the <command role="hg-cmd">hg serve</command>
   13.50 +      command, which is best suited to short-term
   13.51 +      <quote>lightweight</quote> serving.  See section <xref
   13.52 +	linkend="sec:collab:serve"/> below for details of how to use
   13.53 +      this command.  If you have a long-lived repository that you'd
   13.54 +      like to make permanently available, Mercurial has built-in
   13.55 +      support for the CGI (Common Gateway Interface) standard, which
   13.56 +      all common web servers support.  See section <xref
   13.57 +	linkend="sec:collab:cgi"/> for details of CGI
   13.58 +      configuration.</para>
   13.59 +
   13.60 +  </sect1>
   13.61 +  <sect1>
   13.62 +    <title>Collaboration models</title>
   13.63 +
   13.64 +    <para>With a suitably flexible tool, making decisions about
   13.65 +      workflow is much more of a social engineering challenge than a
   13.66 +      technical one. Mercurial imposes few limitations on how you can
   13.67 +      structure the flow of work in a project, so it's up to you and
   13.68 +      your group to set up and live with a model that matches your own
   13.69 +      particular needs.</para>
   13.70 +
   13.71 +    <sect2>
   13.72 +      <title>Factors to keep in mind</title>
   13.73 +
   13.74 +      <para>The most important aspect of any model that you must keep
   13.75 +	in mind is how well it matches the needs and capabilities of
   13.76 +	the people who will be using it.  This might seem
   13.77 +	self-evident; even so, you still can't afford to forget it for
   13.78 +	a moment.</para>
   13.79 +
   13.80 +      <para>I once put together a workflow model that seemed to make
   13.81 +	perfect sense to me, but that caused a considerable amount of
   13.82 +	consternation and strife within my development team.  In spite
   13.83 +	of my attempts to explain why we needed a complex set of
   13.84 +	branches, and how changes ought to flow between them, a few
   13.85 +	team members revolted.  Even though they were smart people,
   13.86 +	they didn't want to pay attention to the constraints we were
   13.87 +	operating under, or face the consequences of those constraints
   13.88 +	in the details of the model that I was advocating.</para>
   13.89 +
   13.90 +      <para>Don't sweep foreseeable social or technical problems under
   13.91 +	the rug. Whatever scheme you put into effect, you should plan
   13.92 +	for mistakes and problem scenarios.  Consider adding automated
   13.93 +	machinery to prevent, or quickly recover from, trouble that
   13.94 +	you can anticipate.  As an example, if you intend to have a
   13.95 +	branch with not-for-release changes in it, you'd do well to
   13.96 +	think early about the possibility that someone might
   13.97 +	accidentally merge those changes into a release branch.  You
   13.98 +	could avoid this particular problem by writing a hook that
   13.99 +	prevents changes from being merged from an inappropriate
  13.100 +	branch.</para>
  13.101 +
  13.102 +    </sect2>
  13.103 +    <sect2>
  13.104 +      <title>Informal anarchy</title>
  13.105 +
  13.106 +      <para>I wouldn't suggest an <quote>anything goes</quote>
  13.107 +	approach as something sustainable, but it's a model that's
  13.108 +	easy to grasp, and it works perfectly well in a few unusual
  13.109 +	situations.</para>
  13.110 +
  13.111 +      <para>As one example, many projects have a loose-knit group of
  13.112 +	collaborators who rarely physically meet each other.  Some
  13.113 +	groups like to overcome the isolation of working at a distance
  13.114 +	by organising occasional <quote>sprints</quote>.  In a sprint,
  13.115 +	a number of people get together in a single location (a
  13.116 +	company's conference room, a hotel meeting room, that kind of
  13.117 +	place) and spend several days more or less locked in there,
  13.118 +	hacking intensely on a handful of projects.</para>
  13.119 +
  13.120 +      <para>A sprint is the perfect place to use the <command
  13.121 +	  role="hg-cmd">hg serve</command> command, since <command
  13.122 +	  role="hg-cmd">hg serve</command> does not requires any fancy
  13.123 +	server infrastructure.  You can get started with <command
  13.124 +	  role="hg-cmd">hg serve</command> in moments, by reading
  13.125 +	section <xref linkend="sec:collab:serve"/> below.  Then simply
  13.126 +	tell
  13.127 +	the person next to you that you're running a server, send the
  13.128 +	URL to them in an instant message, and you immediately have a
  13.129 +	quick-turnaround way to work together.  They can type your URL
  13.130 +	into their web browser and quickly review your changes; or
  13.131 +	they can pull a bugfix from you and verify it; or they can
  13.132 +	clone a branch containing a new feature and try it out.</para>
  13.133 +
  13.134 +      <para>The charm, and the problem, with doing things in an ad hoc
  13.135 +	fashion like this is that only people who know about your
  13.136 +	changes, and where they are, can see them.  Such an informal
  13.137 +	approach simply doesn't scale beyond a handful people, because
  13.138 +	each individual needs to know about $n$ different repositories
  13.139 +	to pull from.</para>
  13.140 +
  13.141 +    </sect2>
  13.142 +    <sect2>
  13.143 +      <title>A single central repository</title>
  13.144 +
  13.145 +      <para>For smaller projects migrating from a centralised revision
  13.146 +	control tool, perhaps the easiest way to get started is to
  13.147 +	have changes flow through a single shared central repository.
  13.148 +	This is also the most common <quote>building block</quote> for
  13.149 +	more ambitious workflow schemes.</para>
  13.150 +
  13.151 +      <para>Contributors start by cloning a copy of this repository.
  13.152 +	They can pull changes from it whenever they need to, and some
  13.153 +	(perhaps all) developers have permission to push a change back
  13.154 +	when they're ready for other people to see it.</para>
  13.155 +
  13.156 +      <para>Under this model, it can still often make sense for people
  13.157 +	to pull changes directly from each other, without going
  13.158 +	through the central repository.  Consider a case in which I
  13.159 +	have a tentative bug fix, but I am worried that if I were to
  13.160 +	publish it to the central repository, it might subsequently
  13.161 +	break everyone else's trees as they pull it.  To reduce the
  13.162 +	potential for damage, I can ask you to clone my repository
  13.163 +	into a temporary repository of your own and test it.  This
  13.164 +	lets us put off publishing the potentially unsafe change until
  13.165 +	it has had a little testing.</para>
  13.166 +
  13.167 +      <para>In this kind of scenario, people usually use the
  13.168 +	<command>ssh</command> protocol to securely push changes to
  13.169 +	the central repository, as documented in section <xref
  13.170 +	  linkend="sec:collab:ssh"/>.  It's also
  13.171 +	usual to publish a read-only copy of the repository over HTTP
  13.172 +	using CGI, as in section <xref linkend="sec:collab:cgi"/>.
  13.173 +	Publishing over HTTP
  13.174 +	satisfies the needs of people who don't have push access, and
  13.175 +	those who want to use web browsers to browse the repository's
  13.176 +	history.</para>
  13.177 +
  13.178 +    </sect2>
  13.179 +    <sect2>
  13.180 +      <title>Working with multiple branches</title>
  13.181 +
  13.182 +      <para>Projects of any significant size naturally tend to make
  13.183 +	progress on several fronts simultaneously.  In the case of
  13.184 +	software, it's common for a project to go through periodic
  13.185 +	official releases.  A release might then go into
  13.186 +	<quote>maintenance mode</quote> for a while after its first
  13.187 +	publication; maintenance releases tend to contain only bug
  13.188 +	fixes, not new features.  In parallel with these maintenance
  13.189 +	releases, one or more future releases may be under
  13.190 +	development.  People normally use the word
  13.191 +	<quote>branch</quote> to refer to one of these many slightly
  13.192 +	different directions in which development is
  13.193 +	proceeding.</para>
  13.194 +
  13.195 +      <para>Mercurial is particularly well suited to managing a number
  13.196 +	of simultaneous, but not identical, branches.  Each
  13.197 +	<quote>development direction</quote> can live in its own
  13.198 +	central repository, and you can merge changes from one to
  13.199 +	another as the need arises.  Because repositories are
  13.200 +	independent of each other, unstable changes in a development
  13.201 +	branch will never affect a stable branch unless someone
  13.202 +	explicitly merges those changes in.</para>
  13.203 +
  13.204 +      <para>Here's an example of how this can work in practice.  Let's
  13.205 +	say you have one <quote>main branch</quote> on a central
  13.206 +	server. <!-- &interaction.branching.init; --> People clone it,
  13.207 +	make changes locally, test them, and push them back.</para>
  13.208 +
  13.209 +      <para>Once the main branch reaches a release milestone, you can
  13.210 +	use the <command role="hg-cmd">hg tag</command> command to
  13.211 +	give a permanent name to the milestone revision. <!--
  13.212 +	&interaction.branching.tag; --> Let's say some ongoing
  13.213 +	development occurs on the main branch. <!--
  13.214 +	&interaction.branching.main; --> Using the tag that was
  13.215 +	recorded at the milestone, people who clone that repository at
  13.216 +	any time in the future can use <command role="hg-cmd">hg
  13.217 +	  update</command> to get a copy of the working directory
  13.218 +	exactly as it was when that tagged revision was committed.
  13.219 +	<!-- &interaction.branching.update; --></para>
  13.220 +
  13.221 +      <para>In addition, immediately after the main branch is tagged,
  13.222 +	someone can then clone the main branch on the server to a new
  13.223 +	<quote>stable</quote> branch, also on the server. <!--
  13.224 +	&interaction.branching.clone; --></para>
  13.225 +
  13.226 +      <para>Someone who needs to make a change to the stable branch
  13.227 +	can then clone <emphasis>that</emphasis> repository, make
  13.228 +	their changes, commit, and push their changes back there. <!--
  13.229 +	&interaction.branching.stable; --> Because Mercurial
  13.230 +	repositories are independent, and Mercurial doesn't move
  13.231 +	changes around automatically, the stable and main branches are
  13.232 +	<emphasis>isolated</emphasis> from each other.  The changes
  13.233 +	that you made on the main branch don't <quote>leak</quote> to
  13.234 +	the stable branch, and vice versa.</para>
  13.235 +
  13.236 +      <para>You'll often want all of your bugfixes on the stable
  13.237 +	branch to show up on the main branch, too.  Rather than
  13.238 +	rewrite a bugfix on the main branch, you can simply pull and
  13.239 +	merge changes from the stable to the main branch, and
  13.240 +	Mercurial will bring those bugfixes in for you. <!--
  13.241 +	&interaction.branching.merge; --> The main branch will still
  13.242 +	contain changes that are not on the stable branch, but it will
  13.243 +	also contain all of the bugfixes from the stable branch.  The
  13.244 +	stable branch remains unaffected by these changes.</para>
  13.245 +
  13.246 +    </sect2>
  13.247 +    <sect2>
  13.248 +      <title>Feature branches</title>
  13.249 +
  13.250 +      <para>For larger projects, an effective way to manage change is
  13.251 +	to break up a team into smaller groups.  Each group has a
  13.252 +	shared branch of its own, cloned from a single
  13.253 +	<quote>master</quote> branch used by the entire project.
  13.254 +	People working on an individual branch are typically quite
  13.255 +	isolated from developments on other branches.</para>
  13.256 +
  13.257 +      <informalfigure id="fig:collab:feature-branches">
  13.258 +	<mediaobject><imageobject><imagedata
  13.259 +				    fileref="feature-branches"/></imageobject><textobject><phrase>XXX 
  13.260 +	      add text</phrase></textobject><caption><para>Feature
  13.261 +	      branches</para></caption></mediaobject>
  13.262 +      </informalfigure>
  13.263 +
  13.264 +      <para>When a particular feature is deemed to be in suitable
  13.265 +	shape, someone on that feature team pulls and merges from the
  13.266 +	master branch into the feature branch, then pushes back up to
  13.267 +	the master branch.</para>
  13.268 +
  13.269 +    </sect2>
  13.270 +    <sect2>
  13.271 +      <title>The release train</title>
  13.272 +
  13.273 +      <para>Some projects are organised on a <quote>train</quote>
  13.274 +	basis: a release is scheduled to happen every few months, and
  13.275 +	whatever features are ready when the <quote>train</quote> is
  13.276 +	ready to leave are allowed in.</para>
  13.277 +
  13.278 +      <para>This model resembles working with feature branches.  The
  13.279 +	difference is that when a feature branch misses a train,
  13.280 +	someone on the feature team pulls and merges the changes that
  13.281 +	went out on that train release into the feature branch, and
  13.282 +	the team continues its work on top of that release so that
  13.283 +	their feature can make the next release.</para>
  13.284 +
  13.285 +    </sect2>
  13.286 +    <sect2>
  13.287 +      <title>The Linux kernel model</title>
  13.288 +
  13.289 +      <para>The development of the Linux kernel has a shallow
  13.290 +	hierarchical structure, surrounded by a cloud of apparent
  13.291 +	chaos.  Because most Linux developers use
  13.292 +	<command>git</command>, a distributed revision control tool
  13.293 +	with capabilities similar to Mercurial, it's useful to
  13.294 +	describe the way work flows in that environment; if you like
  13.295 +	the ideas, the approach translates well across tools.</para>
  13.296 +
  13.297 +      <para>At the center of the community sits Linus Torvalds, the
  13.298 +	creator of Linux.  He publishes a single source repository
  13.299 +	that is considered the <quote>authoritative</quote> current
  13.300 +	tree by the entire developer community. Anyone can clone
  13.301 +	Linus's tree, but he is very choosy about whose trees he pulls
  13.302 +	from.</para>
  13.303 +
  13.304 +      <para>Linus has a number of <quote>trusted lieutenants</quote>.
  13.305 +	As a general rule, he pulls whatever changes they publish, in
  13.306 +	most cases without even reviewing those changes.  Some of
  13.307 +	those lieutenants are generally agreed to be
  13.308 +	<quote>maintainers</quote>, responsible for specific
  13.309 +	subsystems within the kernel.  If a random kernel hacker wants
  13.310 +	to make a change to a subsystem that they want to end up in
  13.311 +	Linus's tree, they must find out who the subsystem's
  13.312 +	maintainer is, and ask that maintainer to take their change.
  13.313 +	If the maintainer reviews their changes and agrees to take
  13.314 +	them, they'll pass them along to Linus in due course.</para>
  13.315 +
  13.316 +      <para>Individual lieutenants have their own approaches to
  13.317 +	reviewing, accepting, and publishing changes; and for deciding
  13.318 +	when to feed them to Linus.  In addition, there are several
  13.319 +	well known branches that people use for different purposes.
  13.320 +	For example, a few people maintain <quote>stable</quote>
  13.321 +	repositories of older versions of the kernel, to which they
  13.322 +	apply critical fixes as needed.  Some maintainers publish
  13.323 +	multiple trees: one for experimental changes; one for changes
  13.324 +	that they are about to feed upstream; and so on.  Others just
  13.325 +	publish a single tree.</para>
  13.326 +
  13.327 +      <para>This model has two notable features.  The first is that
  13.328 +	it's <quote>pull only</quote>.  You have to ask, convince, or
  13.329 +	beg another developer to take a change from you, because there
  13.330 +	are almost no trees to which more than one person can push,
  13.331 +	and there's no way to push changes into a tree that someone
  13.332 +	else controls.</para>
  13.333 +
  13.334 +      <para>The second is that it's based on reputation and acclaim.
  13.335 +	If you're an unknown, Linus will probably ignore changes from
  13.336 +	you without even responding.  But a subsystem maintainer will
  13.337 +	probably review them, and will likely take them if they pass
  13.338 +	their criteria for suitability. The more <quote>good</quote>
  13.339 +	changes you contribute to a maintainer, the more likely they
  13.340 +	are to trust your judgment and accept your changes.  If you're
  13.341 +	well-known and maintain a long-lived branch for something
  13.342 +	Linus hasn't yet accepted, people with similar interests may
  13.343 +	pull your changes regularly to keep up with your work.</para>
  13.344 +
  13.345 +      <para>Reputation and acclaim don't necessarily cross subsystem
  13.346 +	or <quote>people</quote> boundaries.  If you're a respected
  13.347 +	but specialised storage hacker, and you try to fix a
  13.348 +	networking bug, that change will receive a level of scrutiny
  13.349 +	from a network maintainer comparable to a change from a
  13.350 +	complete stranger.</para>
  13.351 +
  13.352 +      <para>To people who come from more orderly project backgrounds,
  13.353 +	the comparatively chaotic Linux kernel development process
  13.354 +	often seems completely insane.  It's subject to the whims of
  13.355 +	individuals; people make sweeping changes whenever they deem
  13.356 +	it appropriate; and the pace of development is astounding.
  13.357 +	And yet Linux is a highly successful, well-regarded piece of
  13.358 +	software.</para>
  13.359 +
  13.360 +    </sect2>
  13.361 +    <sect2>
  13.362 +      <title>Pull-only versus shared-push collaboration</title>
  13.363 +
  13.364 +      <para>A perpetual source of heat in the open source community is
  13.365 +	whether a development model in which people only ever pull
  13.366 +	changes from others is <quote>better than</quote> one in which
  13.367 +	multiple people can push changes to a shared
  13.368 +	repository.</para>
  13.369 +
  13.370 +      <para>Typically, the backers of the shared-push model use tools
  13.371 +	that actively enforce this approach.  If you're using a
  13.372 +	centralised revision control tool such as Subversion, there's
  13.373 +	no way to make a choice over which model you'll use: the tool
  13.374 +	gives you shared-push, and if you want to do anything else,
  13.375 +	you'll have to roll your own approach on top (such as applying
  13.376 +	a patch by hand).</para>
  13.377 +
  13.378 +      <para>A good distributed revision control tool, such as
  13.379 +	Mercurial, will support both models.  You and your
  13.380 +	collaborators can then structure how you work together based
  13.381 +	on your own needs and preferences, not on what contortions
  13.382 +	your tools force you into.</para>
  13.383 +
  13.384 +    </sect2>
  13.385 +    <sect2>
  13.386 +      <title>Where collaboration meets branch management</title>
  13.387 +
  13.388 +      <para>Once you and your team set up some shared repositories and
  13.389 +	start propagating changes back and forth between local and
  13.390 +	shared repos, you begin to face a related, but slightly
  13.391 +	different challenge: that of managing the multiple directions
  13.392 +	in which your team may be moving at once.  Even though this
  13.393 +	subject is intimately related to how your team collaborates,
  13.394 +	it's dense enough to merit treatment of its own, in chapter
  13.395 +	<xref linkend="chap:branch"/>.</para>
  13.396 +
  13.397 +    </sect2>
  13.398 +  </sect1>
  13.399 +  <sect1>
  13.400 +    <title>The technical side of sharing</title>
  13.401 +
  13.402 +    <para>The remainder of this chapter is devoted to the question of
  13.403 +      serving data to your collaborators.</para>
  13.404 +
  13.405 +  </sect1>
  13.406 +  <sect1 id="sec:collab:serve">
  13.407 +    <title>Informal sharing with <command role="hg-cmd">hg
  13.408 +	serve</command></title>
  13.409 +
  13.410 +    <para>Mercurial's <command role="hg-cmd">hg serve</command>
  13.411 +      command is wonderfully suited to small, tight-knit, and
  13.412 +      fast-paced group environments.  It also provides a great way to
  13.413 +      get a feel for using Mercurial commands over a network.</para>
  13.414 +
  13.415 +    <para>Run <command role="hg-cmd">hg serve</command> inside a
  13.416 +      repository, and in under a second it will bring up a specialised
  13.417 +      HTTP server; this will accept connections from any client, and
  13.418 +      serve up data for that repository until you terminate it.
  13.419 +      Anyone who knows the URL of the server you just started, and can
  13.420 +      talk to your computer over the network, can then use a web
  13.421 +      browser or Mercurial to read data from that repository.  A URL
  13.422 +      for a <command role="hg-cmd">hg serve</command> instance running
  13.423 +      on a laptop is likely to look something like
  13.424 +      <literal>http://my-laptop.local:8000/</literal>.</para>
  13.425 +
  13.426 +    <para>The <command role="hg-cmd">hg serve</command> command is
  13.427 +      <emphasis>not</emphasis> a general-purpose web server. It can do
  13.428 +      only two things:</para>
  13.429 +    <itemizedlist>
  13.430 +      <listitem><para>Allow people to browse the history of the
  13.431 +	  repository it's serving, from their normal web
  13.432 +	  browsers.</para>
  13.433 +      </listitem>
  13.434 +      <listitem><para>Speak Mercurial's wire protocol, so that people
  13.435 +	  can <command role="hg-cmd">hg clone</command> or <command
  13.436 +	    role="hg-cmd">hg pull</command> changes from that
  13.437 +	  repository.</para>
  13.438 +      </listitem></itemizedlist>
  13.439 +    <para>In particular, <command role="hg-cmd">hg serve</command>
  13.440 +      won't allow remote users to <emphasis>modify</emphasis> your
  13.441 +      repository.  It's intended for read-only use.</para>
  13.442 +
  13.443 +    <para>If you're getting started with Mercurial, there's nothing to
  13.444 +      prevent you from using <command role="hg-cmd">hg serve</command>
  13.445 +      to serve up a repository on your own computer, then use commands
  13.446 +      like <command role="hg-cmd">hg clone</command>, <command
  13.447 +	role="hg-cmd">hg incoming</command>, and so on to talk to that
  13.448 +      server as if the repository was hosted remotely. This can help
  13.449 +      you to quickly get acquainted with using commands on
  13.450 +      network-hosted repositories.</para>
  13.451 +
  13.452 +    <sect2>
  13.453 +      <title>A few things to keep in mind</title>
  13.454 +
  13.455 +      <para>Because it provides unauthenticated read access to all
  13.456 +	clients, you should only use <command role="hg-cmd">hg
  13.457 +	  serve</command> in an environment where you either don't
  13.458 +	care, or have complete control over, who can access your
  13.459 +	network and pull data from your repository.</para>
  13.460 +
  13.461 +      <para>The <command role="hg-cmd">hg serve</command> command
  13.462 +	knows nothing about any firewall software you might have
  13.463 +	installed on your system or network.  It cannot detect or
  13.464 +	control your firewall software.  If other people are unable to
  13.465 +	talk to a running <command role="hg-cmd">hg serve</command>
  13.466 +	instance, the second thing you should do
  13.467 +	(<emphasis>after</emphasis> you make sure that they're using
  13.468 +	the correct URL) is check your firewall configuration.</para>
  13.469 +
  13.470 +      <para>By default, <command role="hg-cmd">hg serve</command>
  13.471 +	listens for incoming connections on port 8000.  If another
  13.472 +	process is already listening on the port you want to use, you
  13.473 +	can specify a different port to listen on using the <option
  13.474 +	  role="hg-opt-serve">-p</option> option.</para>
  13.475 +
  13.476 +      <para>Normally, when <command role="hg-cmd">hg serve</command>
  13.477 +	starts, it prints no output, which can be a bit unnerving.  If
  13.478 +	you'd like to confirm that it is indeed running correctly, and
  13.479 +	find out what URL you should send to your collaborators, start
  13.480 +	it with the <option role="hg-opt-global">-v</option>
  13.481 +	option.</para>
  13.482 +
  13.483 +    </sect2>
  13.484 +  </sect1>
  13.485 +  <sect1 id="sec:collab:ssh">
  13.486 +    <title>Using the Secure Shell (ssh) protocol</title>
  13.487 +
  13.488 +    <para>You can pull and push changes securely over a network
  13.489 +      connection using the Secure Shell (<literal>ssh</literal>)
  13.490 +      protocol.  To use this successfully, you may have to do a little
  13.491 +      bit of configuration on the client or server sides.</para>
  13.492 +
  13.493 +    <para>If you're not familiar with ssh, it's a network protocol
  13.494 +      that lets you securely communicate with another computer.  To
  13.495 +      use it with Mercurial, you'll be setting up one or more user
  13.496 +      accounts on a server so that remote users can log in and execute
  13.497 +      commands.</para>
  13.498 +
  13.499 +    <para>(If you <emphasis>are</emphasis> familiar with ssh, you'll
  13.500 +      probably find some of the material that follows to be elementary
  13.501 +      in nature.)</para>
  13.502 +
  13.503 +    <sect2>
  13.504 +      <title>How to read and write ssh URLs</title>
  13.505 +
  13.506 +      <para>An ssh URL tends to look like this:</para>
  13.507 +      <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting>
  13.508 +      <orderedlist>
  13.509 +	<listitem><para>The <quote><literal>ssh://</literal></quote>
  13.510 +	    part tells Mercurial to use the ssh protocol.</para>
  13.511 +	</listitem>
  13.512 +	<listitem><para>The <quote><literal>bos@</literal></quote>
  13.513 +	    component indicates what username to log into the server
  13.514 +	    as.  You can leave this out if the remote username is the
  13.515 +	    same as your local username.</para>
  13.516 +	</listitem>
  13.517 +	<listitem><para>The
  13.518 +	    <quote><literal>hg.serpentine.com</literal></quote> gives
  13.519 +	    the hostname of the server to log into.</para>
  13.520 +	</listitem>
  13.521 +	<listitem><para>The <quote>:22</quote> identifies the port
  13.522 +	    number to connect to the server on.  The default port is
  13.523 +	    22, so you only need to specify this part if you're
  13.524 +	    <emphasis>not</emphasis> using port 22.</para>
  13.525 +	</listitem>
  13.526 +	<listitem><para>The remainder of the URL is the local path to
  13.527 +	    the repository on the server.</para>
  13.528 +	</listitem></orderedlist>
  13.529 +
  13.530 +      <para>There's plenty of scope for confusion with the path
  13.531 +	component of ssh URLs, as there is no standard way for tools
  13.532 +	to interpret it.  Some programs behave differently than others
  13.533 +	when dealing with these paths. This isn't an ideal situation,
  13.534 +	but it's unlikely to change.  Please read the following
  13.535 +	paragraphs carefully.</para>
  13.536 +
  13.537 +      <para>Mercurial treats the path to a repository on the server as
  13.538 +	relative to the remote user's home directory.  For example, if
  13.539 +	user <literal>foo</literal> on the server has a home directory
  13.540 +	of <filename class="directory">/home/foo</filename>, then an
  13.541 +	ssh URL that contains a path component of <filename
  13.542 +	  class="directory">bar</filename> <emphasis>really</emphasis>
  13.543 +	refers to the directory <filename
  13.544 +	  class="directory">/home/foo/bar</filename>.</para>
  13.545 +
  13.546 +      <para>If you want to specify a path relative to another user's
  13.547 +	home directory, you can use a path that starts with a tilde
  13.548 +	character followed by the user's name (let's call them
  13.549 +	<literal>otheruser</literal>), like this.</para>
  13.550 +      <programlisting>ssh://server/~otheruser/hg/repo</programlisting>
  13.551 +
  13.552 +      <para>And if you really want to specify an
  13.553 +	<emphasis>absolute</emphasis> path on the server, begin the
  13.554 +	path component with two slashes, as in this example.</para>
  13.555 +      <programlisting>ssh://server//absolute/path</programlisting>
  13.556 +
  13.557 +    </sect2>
  13.558 +    <sect2>
  13.559 +      <title>Finding an ssh client for your system</title>
  13.560 +
  13.561 +      <para>Almost every Unix-like system comes with OpenSSH
  13.562 +	preinstalled.  If you're using such a system, run
  13.563 +	<literal>which ssh</literal> to find out if the
  13.564 +	<command>ssh</command> command is installed (it's usually in
  13.565 +	<filename class="directory">/usr/bin</filename>).  In the
  13.566 +	unlikely event that it isn't present, take a look at your
  13.567 +	system documentation to figure out how to install it.</para>
  13.568 +
  13.569 +      <para>On Windows, you'll first need to download a suitable ssh
  13.570 +	client.  There are two alternatives.</para>
  13.571 +      <itemizedlist>
  13.572 +	<listitem><para>Simon Tatham's excellent PuTTY package
  13.573 +	    <citation>web:putty</citation> provides a complete suite
  13.574 +	    of ssh client commands.</para>
  13.575 +	</listitem>
  13.576 +	<listitem><para>If you have a high tolerance for pain, you can
  13.577 +	    use the Cygwin port of OpenSSH.</para>
  13.578 +	</listitem></itemizedlist>
  13.579 +      <para>In either case, you'll need to edit your \hgini\ file to
  13.580 +	tell Mercurial where to find the actual client command.  For
  13.581 +	example, if you're using PuTTY, you'll need to use the
  13.582 +	<command>plink</command> command as a command-line ssh
  13.583 +	client.</para>
  13.584 +      <programlisting>[ui] ssh = C:/path/to/plink.exe -ssh -i
  13.585 +	"C:/path/to/my/private/key"</programlisting>
  13.586 +
  13.587 +      <note>
  13.588 +	<para>  The path to <command>plink</command> shouldn't contain
  13.589 +	  any whitespace characters, or Mercurial may not be able to
  13.590 +	  run it correctly (so putting it in <filename
  13.591 +	    class="directory">C:\\Program Files</filename> is probably
  13.592 +	  not a good idea).</para>
  13.593 +      </note>
  13.594 +
  13.595 +    </sect2>
  13.596 +    <sect2>
  13.597 +      <title>Generating a key pair</title>
  13.598 +
  13.599 +      <para>To avoid the need to repetitively type a password every
  13.600 +	time you need to use your ssh client, I recommend generating a
  13.601 +	key pair.  On a Unix-like system, the
  13.602 +	<command>ssh-keygen</command> command will do the trick. On
  13.603 +	Windows, if you're using PuTTY, the
  13.604 +	<command>puttygen</command> command is what you'll
  13.605 +	need.</para>
  13.606 +
  13.607 +      <para>When you generate a key pair, it's usually
  13.608 +	<emphasis>highly</emphasis> advisable to protect it with a
  13.609 +	passphrase.  (The only time that you might not want to do this
  13.610 +	is when you're using the ssh protocol for automated tasks on a
  13.611 +	secure network.)</para>
  13.612 +
  13.613 +      <para>Simply generating a key pair isn't enough, however.
  13.614 +	You'll need to add the public key to the set of authorised
  13.615 +	keys for whatever user you're logging in remotely as.  For
  13.616 +	servers using OpenSSH (the vast majority), this will mean
  13.617 +	adding the public key to a list in a file called <filename
  13.618 +	  role="special">authorized_keys</filename> in their <filename
  13.619 +	  role="special" class="directory">.ssh</filename>
  13.620 +	directory.</para>
  13.621 +
  13.622 +      <para>On a Unix-like system, your public key will have a
  13.623 +	<filename>.pub</filename> extension.  If you're using
  13.624 +	<command>puttygen</command> on Windows, you can save the
  13.625 +	public key to a file of your choosing, or paste it from the
  13.626 +	window it's displayed in straight into the <filename
  13.627 +	  role="special">authorized_keys</filename> file.</para>
  13.628 +
  13.629 +    </sect2>
  13.630 +    <sect2>
  13.631 +      <title>Using an authentication agent</title>
  13.632 +
  13.633 +      <para>An authentication agent is a daemon that stores
  13.634 +	passphrases in memory (so it will forget passphrases if you
  13.635 +	log out and log back in again). An ssh client will notice if
  13.636 +	it's running, and query it for a passphrase.  If there's no
  13.637 +	authentication agent running, or the agent doesn't store the
  13.638 +	necessary passphrase, you'll have to type your passphrase
  13.639 +	every time Mercurial tries to communicate with a server on
  13.640 +	your behalf (e.g. whenever you pull or push changes).</para>
  13.641 +
  13.642 +      <para>The downside of storing passphrases in an agent is that
  13.643 +	it's possible for a well-prepared attacker to recover the
  13.644 +	plain text of your passphrases, in some cases even if your
  13.645 +	system has been power-cycled. You should make your own
  13.646 +	judgment as to whether this is an acceptable risk.  It
  13.647 +	certainly saves a lot of repeated typing.</para>
  13.648 +
  13.649 +      <para>On Unix-like systems, the agent is called
  13.650 +	<command>ssh-agent</command>, and it's often run automatically
  13.651 +	for you when you log in.  You'll need to use the
  13.652 +	<command>ssh-add</command> command to add passphrases to the
  13.653 +	agent's store.  On Windows, if you're using PuTTY, the
  13.654 +	<command>pageant</command> command acts as the agent.  It adds
  13.655 +	an icon to your system tray that will let you manage stored
  13.656 +	passphrases.</para>
  13.657 +
  13.658 +    </sect2>
  13.659 +    <sect2>
  13.660 +      <title>Configuring the server side properly</title>
  13.661 +
  13.662 +      <para>Because ssh can be fiddly to set up if you're new to it,
  13.663 +	there's a variety of things that can go wrong.  Add Mercurial
  13.664 +	on top, and there's plenty more scope for head-scratching.
  13.665 +	Most of these potential problems occur on the server side, not
  13.666 +	the client side.  The good news is that once you've gotten a
  13.667 +	configuration working, it will usually continue to work
  13.668 +	indefinitely.</para>
  13.669 +
  13.670 +      <para>Before you try using Mercurial to talk to an ssh server,
  13.671 +	it's best to make sure that you can use the normal
  13.672 +	<command>ssh</command> or <command>putty</command> command to
  13.673 +	talk to the server first.  If you run into problems with using
  13.674 +	these commands directly, Mercurial surely won't work.  Worse,
  13.675 +	it will obscure the underlying problem.  Any time you want to
  13.676 +	debug ssh-related Mercurial problems, you should drop back to
  13.677 +	making sure that plain ssh client commands work first,
  13.678 +	<emphasis>before</emphasis> you worry about whether there's a
  13.679 +	problem with Mercurial.</para>
  13.680 +
  13.681 +      <para>The first thing to be sure of on the server side is that
  13.682 +	you can actually log in from another machine at all.  If you
  13.683 +	can't use <command>ssh</command> or <command>putty</command>
  13.684 +	to log in, the error message you get may give you a few hints
  13.685 +	as to what's wrong.  The most common problems are as
  13.686 +	follows.</para>
  13.687 +      <itemizedlist>
  13.688 +	<listitem><para>If you get a <quote>connection refused</quote>
  13.689 +	    error, either there isn't an SSH daemon running on the
  13.690 +	    server at all, or it's inaccessible due to firewall
  13.691 +	    configuration.</para>
  13.692 +	</listitem>
  13.693 +	<listitem><para>If you get a <quote>no route to host</quote>
  13.694 +	    error, you either have an incorrect address for the server
  13.695 +	    or a seriously locked down firewall that won't admit its
  13.696 +	    existence at all.</para>
  13.697 +	</listitem>
  13.698 +	<listitem><para>If you get a <quote>permission denied</quote>
  13.699 +	    error, you may have mistyped the username on the server,
  13.700 +	    or you could have mistyped your key's passphrase or the
  13.701 +	    remote user's password.</para>
  13.702 +	</listitem></itemizedlist>
  13.703 +      <para>In summary, if you're having trouble talking to the
  13.704 +	server's ssh daemon, first make sure that one is running at
  13.705 +	all.  On many systems it will be installed, but disabled, by
  13.706 +	default.  Once you're done with this step, you should then
  13.707 +	check that the server's firewall is configured to allow
  13.708 +	incoming connections on the port the ssh daemon is listening
  13.709 +	on (usually 22).  Don't worry about more exotic possibilities
  13.710 +	for misconfiguration until you've checked these two
  13.711 +	first.</para>
  13.712 +
  13.713 +      <para>If you're using an authentication agent on the client side
  13.714 +	to store passphrases for your keys, you ought to be able to
  13.715 +	log into the server without being prompted for a passphrase or
  13.716 +	a password.  If you're prompted for a passphrase, there are a
  13.717 +	few possible culprits.</para>
  13.718 +      <itemizedlist>
  13.719 +	<listitem><para>You might have forgotten to use
  13.720 +	    <command>ssh-add</command> or <command>pageant</command>
  13.721 +	    to store the passphrase.</para>
  13.722 +	</listitem>
  13.723 +	<listitem><para>You might have stored the passphrase for the
  13.724 +	    wrong key.</para>
  13.725 +	</listitem></itemizedlist>
  13.726 +      <para>If you're being prompted for the remote user's password,
  13.727 +	there are another few possible problems to check.</para>
  13.728 +      <itemizedlist>
  13.729 +	<listitem><para>Either the user's home directory or their
  13.730 +	    <filename role="special" class="directory">.ssh</filename>
  13.731 +	    directory might have excessively liberal permissions.  As
  13.732 +	    a result, the ssh daemon will not trust or read their
  13.733 +	    <filename role="special">authorized_keys</filename> file.
  13.734 +	    For example, a group-writable home or <filename
  13.735 +	      role="special" class="directory">.ssh</filename>
  13.736 +	    directory will often cause this symptom.</para>
  13.737 +	</listitem>
  13.738 +	<listitem><para>The user's <filename
  13.739 +	      role="special">authorized_keys</filename> file may have
  13.740 +	    a problem. If anyone other than the user owns or can write
  13.741 +	    to that file, the ssh daemon will not trust or read
  13.742 +	    it.</para>
  13.743 +	</listitem></itemizedlist>
  13.744 +
  13.745 +      <para>In the ideal world, you should be able to run the
  13.746 +	following command successfully, and it should print exactly
  13.747 +	one line of output, the current date and time.</para>
  13.748 +      <programlisting>ssh myserver date</programlisting>
  13.749 +
  13.750 +      <para>If, on your server, you have login scripts that print
  13.751 +	banners or other junk even when running non-interactive
  13.752 +	commands like this, you should fix them before you continue,
  13.753 +	so that they only print output if they're run interactively.
  13.754 +	Otherwise these banners will at least clutter up Mercurial's
  13.755 +	output.  Worse, they could potentially cause problems with
  13.756 +	running Mercurial commands remotely.  Mercurial makes tries to
  13.757 +	detect and ignore banners in non-interactive
  13.758 +	<command>ssh</command> sessions, but it is not foolproof.  (If
  13.759 +	you're editing your login scripts on your server, the usual
  13.760 +	way to see if a login script is running in an interactive
  13.761 +	shell is to check the return code from the command
  13.762 +	<literal>tty -s</literal>.)</para>
  13.763 +
  13.764 +      <para>Once you've verified that plain old ssh is working with
  13.765 +	your server, the next step is to ensure that Mercurial runs on
  13.766 +	the server.  The following command should run
  13.767 +	successfully:</para>
  13.768 +      <programlisting>ssh myserver hg version</programlisting>
  13.769 +      <para>If you see an error message instead of normal <command
  13.770 +	  role="hg-cmd">hg version</command> output, this is usually
  13.771 +	because you haven't installed Mercurial to <filename
  13.772 +	  class="directory">/usr/bin</filename>.  Don't worry if this
  13.773 +	is the case; you don't need to do that.  But you should check
  13.774 +	for a few possible problems.</para>
  13.775 +      <itemizedlist>
  13.776 +	<listitem><para>Is Mercurial really installed on the server at
  13.777 +	    all?  I know this sounds trivial, but it's worth
  13.778 +	    checking!</para>
  13.779 +	</listitem>
  13.780 +	<listitem><para>Maybe your shell's search path (usually set
  13.781 +	    via the <envar>PATH</envar> environment variable) is
  13.782 +	    simply misconfigured.</para>
  13.783 +	</listitem>
  13.784 +	<listitem><para>Perhaps your <envar>PATH</envar> environment
  13.785 +	    variable is only being set to point to the location of the
  13.786 +	    <command>hg</command> executable if the login session is
  13.787 +	    interactive.  This can happen if you're setting the path
  13.788 +	    in the wrong shell login script.  See your shell's
  13.789 +	    documentation for details.</para>
  13.790 +	</listitem>
  13.791 +	<listitem><para>The <envar>PYTHONPATH</envar> environment
  13.792 +	    variable may need to contain the path to the Mercurial
  13.793 +	    Python modules.  It might not be set at all; it could be
  13.794 +	    incorrect; or it may be set only if the login is
  13.795 +	    interactive.</para>
  13.796 +	</listitem></itemizedlist>
  13.797 +
  13.798 +      <para>If you can run <command role="hg-cmd">hg version</command>
  13.799 +	over an ssh connection, well done! You've got the server and
  13.800 +	client sorted out.  You should now be able to use Mercurial to
  13.801 +	access repositories hosted by that username on that server.
  13.802 +	If you run into problems with Mercurial and ssh at this point,
  13.803 +	try using the <option role="hg-opt-global">--debug</option>
  13.804 +	option to get a clearer picture of what's going on.</para>
  13.805 +
  13.806 +    </sect2>
  13.807 +    <sect2>
  13.808 +      <title>Using compression with ssh</title>
  13.809 +
  13.810 +      <para>Mercurial does not compress data when it uses the ssh
  13.811 +	protocol, because the ssh protocol can transparently compress
  13.812 +	data.  However, the default behaviour of ssh clients is
  13.813 +	<emphasis>not</emphasis> to request compression.</para>
  13.814 +
  13.815 +      <para>Over any network other than a fast LAN (even a wireless
  13.816 +	network), using compression is likely to significantly speed
  13.817 +	up Mercurial's network operations.  For example, over a WAN,
  13.818 +	someone measured compression as reducing the amount of time
  13.819 +	required to clone a particularly large repository from 51
  13.820 +	minutes to 17 minutes.</para>
  13.821 +
  13.822 +      <para>Both <command>ssh</command> and <command>plink</command>
  13.823 +	accept a <option role="cmd-opt-ssh">-C</option> option which
  13.824 +	turns on compression.  You can easily edit your <filename
  13.825 +	  role="special"> /.hgrc</filename>\ to enable compression for
  13.826 +	all of Mercurial's uses of the ssh protocol.</para>
  13.827 +      <programlisting>[ui] ssh = ssh -C</programlisting>
  13.828 +
  13.829 +      <para>If you use <command>ssh</command>, you can configure it to
  13.830 +	always use compression when talking to your server.  To do
  13.831 +	this, edit your <filename
  13.832 +	  role="special">.ssh/config</filename> file (which may not
  13.833 +	yet exist), as follows.</para>
  13.834 +      <programlisting>Host hg Compression yes HostName
  13.835 +	hg.example.com</programlisting>
  13.836 +      <para>This defines an alias, <literal>hg</literal>.  When you
  13.837 +	use it on the <command>ssh</command> command line or in a
  13.838 +	Mercurial <literal>ssh</literal>-protocol URL, it will cause
  13.839 +	<command>ssh</command> to connect to
  13.840 +	<literal>hg.example.com</literal> and use compression.  This
  13.841 +	gives you both a shorter name to type and compression, each of
  13.842 +	which is a good thing in its own right.</para>
  13.843 +
  13.844 +    </sect2>
  13.845 +  </sect1>
  13.846 +  <sect1 id="sec:collab:cgi">
  13.847 +    <title>Serving over HTTP using CGI</title>
  13.848 +
  13.849 +    <para>Depending on how ambitious you are, configuring Mercurial's
  13.850 +      CGI interface can take anything from a few moments to several
  13.851 +      hours.</para>
  13.852 +
  13.853 +    <para>We'll begin with the simplest of examples, and work our way
  13.854 +      towards a more complex configuration.  Even for the most basic
  13.855 +      case, you're almost certainly going to need to read and modify
  13.856 +      your web server's configuration.</para>
  13.857 +
  13.858 +    <note>
  13.859 +      <para>  Configuring a web server is a complex, fiddly, and
  13.860 +	highly system-dependent activity.  I can't possibly give you
  13.861 +	instructions that will cover anything like all of the cases
  13.862 +	you will encounter. Please use your discretion and judgment in
  13.863 +	following the sections below.  Be prepared to make plenty of
  13.864 +	mistakes, and to spend a lot of time reading your server's
  13.865 +	error logs.</para>
  13.866 +    </note>
  13.867 +
  13.868 +    <sect2>
  13.869 +      <title>Web server configuration checklist</title>
  13.870 +
  13.871 +      <para>Before you continue, do take a few moments to check a few
  13.872 +	aspects of your system's setup.</para>
  13.873 +
  13.874 +      <orderedlist>
  13.875 +	<listitem><para>Do you have a web server installed at all?
  13.876 +	    Mac OS X ships with Apache, but many other systems may not
  13.877 +	    have a web server installed.</para>
  13.878 +	</listitem>
  13.879 +	<listitem><para>If you have a web server installed, is it
  13.880 +	    actually running?  On most systems, even if one is
  13.881 +	    present, it will be disabled by default.</para>
  13.882 +	</listitem>
  13.883 +	<listitem><para>Is your server configured to allow you to run
  13.884 +	    CGI programs in the directory where you plan to do so?
  13.885 +	    Most servers default to explicitly disabling the ability
  13.886 +	    to run CGI programs.</para>
  13.887 +	</listitem></orderedlist>
  13.888 +
  13.889 +      <para>If you don't have a web server installed, and don't have
  13.890 +	substantial experience configuring Apache, you should consider
  13.891 +	using the <literal>lighttpd</literal> web server instead of
  13.892 +	Apache.  Apache has a well-deserved reputation for baroque and
  13.893 +	confusing configuration. While <literal>lighttpd</literal> is
  13.894 +	less capable in some ways than Apache, most of these
  13.895 +	capabilities are not relevant to serving Mercurial
  13.896 +	repositories.  And <literal>lighttpd</literal> is undeniably
  13.897 +	<emphasis>much</emphasis> easier to get started with than
  13.898 +	Apache.</para>
  13.899 +
  13.900 +    </sect2>
  13.901 +    <sect2>
  13.902 +      <title>Basic CGI configuration</title>
  13.903 +
  13.904 +      <para>On Unix-like systems, it's common for users to have a
  13.905 +	subdirectory named something like <filename
  13.906 +	  class="directory">public_html</filename> in their home
  13.907 +	directory, from which they can serve up web pages.  A file
  13.908 +	named <filename>foo</filename> in this directory will be
  13.909 +	accessible at a URL of the form
  13.910 +	<literal>http://www.example.com/\
  13.911 +	  {</literal>username/foo}.</para>
  13.912 +
  13.913 +      <para>To get started, find the <filename
  13.914 +	  role="special">hgweb.cgi</filename> script that should be
  13.915 +	present in your Mercurial installation.  If you can't quickly
  13.916 +	find a local copy on your system, simply download one from the
  13.917 +	master Mercurial repository at <ulink
  13.918 +	  url="http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi</ulink>.</para>
  13.919 +
  13.920 +      <para>You'll need to copy this script into your <filename
  13.921 +	  class="directory">public_html</filename> directory, and
  13.922 +	ensure that it's executable.</para>
  13.923 +      <programlisting>cp .../hgweb.cgi ~/public_html chmod 755
  13.924 +	~/public_html/hgweb.cgi</programlisting>
  13.925 +      <para>The <literal>755</literal> argument to
  13.926 +	<command>chmod</command> is a little more general than just
  13.927 +	making the script executable: it ensures that the script is
  13.928 +	executable by anyone, and that <quote>group</quote> and
  13.929 +	<quote>other</quote> write permissions are
  13.930 +	<emphasis>not</emphasis> set.  If you were to leave those
  13.931 +	write permissions enabled, Apache's <literal>suexec</literal>
  13.932 +	subsystem would likely refuse to execute the script.  In fact,
  13.933 +	<literal>suexec</literal> also insists that the
  13.934 +	<emphasis>directory</emphasis> in which the script resides
  13.935 +	must not be writable by others.</para>
  13.936 +      <programlisting>chmod 755 ~/public_html</programlisting>
  13.937 +
  13.938 +      <sect3 id="sec:collab:wtf">
  13.939 +	<title>What could <emphasis>possibly</emphasis> go
  13.940 +	  wrong?</title>
  13.941 +
  13.942 +	<para>Once you've copied the CGI script into place, go into a
  13.943 +	  web browser, and try to open the URL <ulink
  13.944 +	    url="http://myhostname/
  13.945 +	    myuser/hgweb.cgi">http://myhostname/
  13.946 +	    myuser/hgweb.cgi</ulink>, <emphasis>but</emphasis> brace
  13.947 +	  yourself for instant failure.  There's a high probability
  13.948 +	  that trying to visit this URL will fail, and there are many
  13.949 +	  possible reasons for this.  In fact, you're likely to
  13.950 +	  stumble over almost every one of the possible errors below,
  13.951 +	  so please read carefully.  The following are all of the
  13.952 +	  problems I ran into on a system running Fedora 7, with a
  13.953 +	  fresh installation of Apache, and a user account that I
  13.954 +	  created specially to perform this exercise.</para>
  13.955 +
  13.956 +	<para>Your web server may have per-user directories disabled.
  13.957 +	  If you're using Apache, search your config file for a
  13.958 +	  <literal>UserDir</literal> directive.  If there's none
  13.959 +	  present, per-user directories will be disabled.  If one
  13.960 +	  exists, but its value is <literal>disabled</literal>, then
  13.961 +	  per-user directories will be disabled.  Otherwise, the
  13.962 +	  string after <literal>UserDir</literal> gives the name of
  13.963 +	  the subdirectory that Apache will look in under your home
  13.964 +	  directory, for example <filename
  13.965 +	    class="directory">public_html</filename>.</para>
  13.966 +
  13.967 +	<para>Your file access permissions may be too restrictive.
  13.968 +	  The web server must be able to traverse your home directory
  13.969 +	  and directories under your <filename
  13.970 +	    class="directory">public_html</filename> directory, and
  13.971 +	  read files under the latter too.  Here's a quick recipe to
  13.972 +	  help you to make your permissions more appropriate.</para>
  13.973 +	<programlisting>chmod 755 ~ find ~/public_html -type d -print0
  13.974 +	  | xargs -0r chmod 755 find ~/public_html -type f -print0 |
  13.975 +	  xargs -0r chmod 644</programlisting>
  13.976 +
  13.977 +	<para>The other possibility with permissions is that you might
  13.978 +	  get a completely empty window when you try to load the
  13.979 +	  script.  In this case, it's likely that your access
  13.980 +	  permissions are \emph{too permissive}.  Apache's
  13.981 +	  <literal>suexec</literal> subsystem won't execute a script
  13.982 +	  that's group- or world-writable, for example.</para>
  13.983 +
  13.984 +	<para>Your web server may be configured to disallow execution
  13.985 +	  of CGI programs in your per-user web directory.  Here's
  13.986 +	  Apache's default per-user configuration from my Fedora
  13.987 +	  system.</para>
  13.988 +	<programlisting>&lt;Directory /home/*/public_html&gt;
  13.989 +	  AllowOverride FileInfo AuthConfig Limit Options MultiViews
  13.990 +	  Indexes SymLinksIfOwnerMatch IncludesNoExec &lt;Limit GET
  13.991 +	  POST OPTIONS&gt; Order allow,deny Allow from all
  13.992 +	  &lt;/Limit&gt; &lt;LimitExcept GET POST OPTIONS&gt; Order
  13.993 +	  deny,allow Deny from all &lt;/LimitExcept&gt;
  13.994 +	  &lt;/Directory&gt;</programlisting>
  13.995 +	<para>If you find a similar-looking
  13.996 +	  <literal>Directory</literal> group in your Apache
  13.997 +	  configuration, the directive to look at inside it is
  13.998 +	  <literal>Options</literal>. Add <literal>ExecCGI</literal>
  13.999 +	  to the end of this list if it's missing, and restart the web
 13.1000 +	  server.</para>
 13.1001 +
 13.1002 +	<para>If you find that Apache serves you the text of the CGI
 13.1003 +	  script instead of executing it, you may need to either
 13.1004 +	  uncomment (if already present) or add a directive like
 13.1005 +	  this.</para>
 13.1006 +	<programlisting>AddHandler cgi-script .cgi</programlisting>
 13.1007 +
 13.1008 +	<para>The next possibility is that you might be served with a
 13.1009 +	  colourful Python backtrace claiming that it can't import a
 13.1010 +	  <literal>mercurial</literal>-related module.  This is
 13.1011 +	  actually progress!  The server is now capable of executing
 13.1012 +	  your CGI script.  This error is only likely to occur if
 13.1013 +	  you're running a private installation of Mercurial, instead
 13.1014 +	  of a system-wide version.  Remember that the web server runs
 13.1015 +	  the CGI program without any of the environment variables
 13.1016 +	  that you take for granted in an interactive session.  If
 13.1017 +	  this error happens to you, edit your copy of <filename
 13.1018 +	    role="special">hgweb.cgi</filename> and follow the
 13.1019 +	  directions inside it to correctly set your
 13.1020 +	  <envar>PYTHONPATH</envar> environment variable.</para>
 13.1021 +
 13.1022 +	<para>Finally, you are <emphasis>certain</emphasis> to by
 13.1023 +	  served with another colourful Python backtrace: this one
 13.1024 +	  will complain that it can't find <filename
 13.1025 +	    class="directory">/path/to/repository</filename>.  Edit
 13.1026 +	  your <filename role="special">hgweb.cgi</filename> script
 13.1027 +	  and replace the <filename
 13.1028 +	    class="directory">/path/to/repository</filename> string
 13.1029 +	  with the complete path to the repository you want to serve
 13.1030 +	  up.</para>
 13.1031 +
 13.1032 +	<para>At this point, when you try to reload the page, you
 13.1033 +	  should be presented with a nice HTML view of your
 13.1034 +	  repository's history.  Whew!</para>
 13.1035 +
 13.1036 +      </sect3>
 13.1037 +      <sect3>
 13.1038 +	<title>Configuring lighttpd</title>
 13.1039 +
 13.1040 +	<para>To be exhaustive in my experiments, I tried configuring
 13.1041 +	  the increasingly popular <literal>lighttpd</literal> web
 13.1042 +	  server to serve the same repository as I described with
 13.1043 +	  Apache above.  I had already overcome all of the problems I
 13.1044 +	  outlined with Apache, many of which are not server-specific.
 13.1045 +	  As a result, I was fairly sure that my file and directory
 13.1046 +	  permissions were good, and that my <filename
 13.1047 +	    role="special">hgweb.cgi</filename> script was properly
 13.1048 +	  edited.</para>
 13.1049 +
 13.1050 +	<para>Once I had Apache running, getting
 13.1051 +	  <literal>lighttpd</literal> to serve the repository was a
 13.1052 +	  snap (in other words, even if you're trying to use
 13.1053 +	  <literal>lighttpd</literal>, you should read the Apache
 13.1054 +	  section).  I first had to edit the
 13.1055 +	  <literal>mod_access</literal> section of its config file to
 13.1056 +	  enable <literal>mod_cgi</literal> and
 13.1057 +	  <literal>mod_userdir</literal>, both of which were disabled
 13.1058 +	  by default on my system.  I then added a few lines to the
 13.1059 +	  end of the config file, to configure these modules.</para>
 13.1060 +	<programlisting>userdir.path = "public_html" cgi.assign = (
 13.1061 +	  ".cgi" =&gt; "" )</programlisting>
 13.1062 +	<para>With this done, <literal>lighttpd</literal> ran
 13.1063 +	  immediately for me.  If I had configured
 13.1064 +	  <literal>lighttpd</literal> before Apache, I'd almost
 13.1065 +	  certainly have run into many of the same system-level
 13.1066 +	  configuration problems as I did with Apache.  However, I
 13.1067 +	  found <literal>lighttpd</literal> to be noticeably easier to
 13.1068 +	  configure than Apache, even though I've used Apache for over
 13.1069 +	  a decade, and this was my first exposure to
 13.1070 +	  <literal>lighttpd</literal>.</para>
 13.1071 +
 13.1072 +      </sect3>
 13.1073 +    </sect2>
 13.1074 +    <sect2>
 13.1075 +      <title>Sharing multiple repositories with one CGI script</title>
 13.1076 +
 13.1077 +      <para>The <filename role="special">hgweb.cgi</filename> script
 13.1078 +	only lets you publish a single repository, which is an
 13.1079 +	annoying restriction.  If you want to publish more than one
 13.1080 +	without wracking yourself with multiple copies of the same
 13.1081 +	script, each with different names, a better choice is to use
 13.1082 +	the <filename role="special">hgwebdir.cgi</filename>
 13.1083 +	script.</para>
 13.1084 +
 13.1085 +      <para>The procedure to configure <filename
 13.1086 +	  role="special">hgwebdir.cgi</filename> is only a little more
 13.1087 +	involved than for <filename
 13.1088 +	  role="special">hgweb.cgi</filename>.  First, you must obtain
 13.1089 +	a copy of the script.  If you don't have one handy, you can
 13.1090 +	download a copy from the master Mercurial repository at <ulink
 13.1091 +	  url="http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi</ulink>.</para>
 13.1092 +
 13.1093 +      <para>You'll need to copy this script into your <filename
 13.1094 +	  class="directory">public_html</filename> directory, and
 13.1095 +	ensure that it's executable.</para>
 13.1096 +      <programlisting>cp .../hgwebdir.cgi ~/public_html chmod 755
 13.1097 +	~/public_html ~/public_html/hgwebdir.cgi</programlisting>
 13.1098 +      <para>With basic configuration out of the way, try to visit
 13.1099 +	<ulink url="http://myhostname/
 13.1100 +	  myuser/hgwebdir.cgi">http://myhostname/
 13.1101 +	  myuser/hgwebdir.cgi</ulink> in your browser.  It should
 13.1102 +	display an empty list of repositories.  If you get a blank
 13.1103 +	window or error message, try walking through the list of
 13.1104 +	potential problems in section <xref
 13.1105 +	  linkend="sec:collab:wtf"/>.</para>
 13.1106 +
 13.1107 +      <para>The <filename role="special">hgwebdir.cgi</filename>
 13.1108 +	script relies on an external configuration file.  By default,
 13.1109 +	it searches for a file named <filename
 13.1110 +	  role="special">hgweb.config</filename> in the same directory
 13.1111 +	as itself.  You'll need to create this file, and make it
 13.1112 +	world-readable.  The format of the file is similar to a
 13.1113 +	Windows <quote>ini</quote> file, as understood by Python's
 13.1114 +	<literal>ConfigParser</literal>
 13.1115 +	<citation>web:configparser</citation> module.</para>
 13.1116 +
 13.1117 +      <para>The easiest way to configure <filename
 13.1118 +	  role="special">hgwebdir.cgi</filename> is with a section
 13.1119 +	named <literal>collections</literal>.  This will automatically
 13.1120 +	publish <emphasis>every</emphasis> repository under the
 13.1121 +	directories you name.  The section should look like
 13.1122 +	this:</para>
 13.1123 +      <programlisting>[collections] /my/root =
 13.1124 +	/my/root</programlisting>
 13.1125 +      <para>Mercurial interprets this by looking at the directory name
 13.1126 +	on the <emphasis>right</emphasis> hand side of the
 13.1127 +	<quote><literal>=</literal></quote> sign; finding repositories
 13.1128 +	in that directory hierarchy; and using the text on the
 13.1129 +	<emphasis>left</emphasis> to strip off matching text from the
 13.1130 +	names it will actually list in the web interface.  The
 13.1131 +	remaining component of a path after this stripping has
 13.1132 +	occurred is called a <quote>virtual path</quote>.</para>
 13.1133 +
 13.1134 +      <para>Given the example above, if we have a repository whose
 13.1135 +	local path is <filename
 13.1136 +	  class="directory">/my/root/this/repo</filename>, the CGI
 13.1137 +	script will strip the leading <filename
 13.1138 +	  class="directory">/my/root</filename> from the name, and
 13.1139 +	publish the repository with a virtual path of <filename
 13.1140 +	  class="directory">this/repo</filename>.  If the base URL for
 13.1141 +	our CGI script is <ulink url="http://myhostname/
 13.1142 +	  myuser/hgwebdir.cgi">http://myhostname/
 13.1143 +	  myuser/hgwebdir.cgi</ulink>, the complete URL for that
 13.1144 +	repository will be <ulink url="http://myhostname/
 13.1145 +	  myuser/hgwebdir.cgi/this/repo">http://myhostname/
 13.1146 +	  myuser/hgwebdir.cgi/this/repo</ulink>.</para>
 13.1147 +
 13.1148 +      <para>If we replace <filename
 13.1149 +	  class="directory">/my/root</filename> on the left hand side
 13.1150 +	of this example with <filename
 13.1151 +	  class="directory">/my</filename>, then <filename
 13.1152 +	  role="special">hgwebdir.cgi</filename> will only strip off
 13.1153 +	<filename class="directory">/my</filename> from the repository
 13.1154 +	name, and will give us a virtual path of <filename
 13.1155 +	  class="directory">root/this/repo</filename> instead of
 13.1156 +	<filename class="directory">this/repo</filename>.</para>
 13.1157 +
 13.1158 +      <para>The <filename role="special">hgwebdir.cgi</filename>
 13.1159 +	script will recursively search each directory listed in the
 13.1160 +	<literal>collections</literal> section of its configuration
 13.1161 +	file, but it will <literal>not</literal> recurse into the
 13.1162 +	repositories it finds.</para>
 13.1163 +
 13.1164 +      <para>The <literal>collections</literal> mechanism makes it easy
 13.1165 +	to publish many repositories in a <quote>fire and
 13.1166 +	  forget</quote> manner.  You only need to set up the CGI
 13.1167 +	script and configuration file one time.  Afterwards, you can
 13.1168 +	publish or unpublish a repository at any time by simply moving
 13.1169 +	it into, or out of, the directory hierarchy in which you've
 13.1170 +	configured <filename role="special">hgwebdir.cgi</filename> to
 13.1171 +	look.</para>
 13.1172 +
 13.1173 +      <sect3>
 13.1174 +	<title>Explicitly specifying which repositories to
 13.1175 +	  publish</title>
 13.1176 +
 13.1177 +	<para>In addition to the <literal>collections</literal>
 13.1178 +	  mechanism, the <filename
 13.1179 +	    role="special">hgwebdir.cgi</filename> script allows you
 13.1180 +	  to publish a specific list of repositories.  To do so,
 13.1181 +	  create a <literal>paths</literal> section, with contents of
 13.1182 +	  the following form.</para>
 13.1183 +	<programlisting>[paths] repo1 = /my/path/to/some/repo repo2 =
 13.1184 +	  /some/path/to/another</programlisting>
 13.1185 +	<para>In this case, the virtual path (the component that will
 13.1186 +	  appear in a URL) is on the left hand side of each
 13.1187 +	  definition, while the path to the repository is on the
 13.1188 +	  right.  Notice that there does not need to be any
 13.1189 +	  relationship between the virtual path you choose and the
 13.1190 +	  location of a repository in your filesystem.</para>
 13.1191 +
 13.1192 +	<para>If you wish, you can use both the
 13.1193 +	  <literal>collections</literal> and <literal>paths</literal>
 13.1194 +	  mechanisms simultaneously in a single configuration
 13.1195 +	  file.</para>
 13.1196 +
 13.1197 +	<note>
 13.1198 +	  <para>  If multiple repositories have the same virtual path,
 13.1199 +	    <filename role="special">hgwebdir.cgi</filename> will not
 13.1200 +	    report an error.  Instead, it will behave
 13.1201 +	    unpredictably.</para>
 13.1202 +	</note>
 13.1203 +
 13.1204 +      </sect3>
 13.1205 +    </sect2>
 13.1206 +    <sect2>
 13.1207 +      <title>Downloading source archives</title>
 13.1208 +
 13.1209 +      <para>Mercurial's web interface lets users download an archive
 13.1210 +	of any revision.  This archive will contain a snapshot of the
 13.1211 +	working directory as of that revision, but it will not contain
 13.1212 +	a copy of the repository data.</para>
 13.1213 +
 13.1214 +      <para>By default, this feature is not enabled.  To enable it,
 13.1215 +	you'll need to add an <envar
 13.1216 +	  role="rc-item-web">allow_archive</envar> item to the
 13.1217 +	<literal role="rc-web">web</literal> section of your <filename
 13.1218 +	  role="special"> /.hgrc</filename>.</para>
 13.1219 +
 13.1220 +    </sect2>
 13.1221 +    <sect2>
 13.1222 +      <title>Web configuration options</title>
 13.1223 +
 13.1224 +      <para>Mercurial's web interfaces (the <command role="hg-cmd">hg
 13.1225 +	  serve</command> command, and the <filename
 13.1226 +	  role="special">hgweb.cgi</filename> and <filename
 13.1227 +	  role="special">hgwebdir.cgi</filename> scripts) have a
 13.1228 +	number of configuration options that you can set.  These
 13.1229 +	belong in a section named <literal
 13.1230 +	  role="rc-web">web</literal>.</para>
 13.1231 +      <itemizedlist>
 13.1232 +	<listitem><para><envar
 13.1233 +	      role="rc-item-web">allow_archive</envar>: Determines
 13.1234 +	    which (if any) archive download mechanisms Mercurial
 13.1235 +	    supports.  If you enable this feature, users of the web
 13.1236 +	    interface will be able to download an archive of whatever
 13.1237 +	    revision of a repository they are viewing. To enable the
 13.1238 +	    archive feature, this item must take the form of a
 13.1239 +	    sequence of words drawn from the list below.</para>
 13.1240 +	  <itemizedlist>
 13.1241 +	    <listitem><para><literal>bz2</literal>: A
 13.1242 +		<command>tar</command> archive, compressed using
 13.1243 +		<literal>bzip2</literal> compression.  This has the
 13.1244 +		best compression ratio, but uses the most CPU time on
 13.1245 +		the server.</para>
 13.1246 +	    </listitem>
 13.1247 +	    <listitem><para><literal>gz</literal>: A
 13.1248 +		<command>tar</command> archive, compressed using
 13.1249 +		<literal>gzip</literal> compression.</para>
 13.1250 +	    </listitem>
 13.1251 +	    <listitem><para><literal>zip</literal>: A
 13.1252 +		<command>zip</command> archive, compressed using LZW
 13.1253 +		compression.  This format has the worst compression
 13.1254 +		ratio, but is widely used in the Windows world.</para>
 13.1255 +	    </listitem>
 13.1256 +	  </itemizedlist>
 13.1257 +	  <para>  If you provide an empty list, or don't have an
 13.1258 +	    <envar role="rc-item-web">allow_archive</envar> entry at
 13.1259 +	    all, this feature will be disabled.  Here is an example of
 13.1260 +	    how to enable all three supported formats.</para>
 13.1261 +	  <programlisting>[web] allow_archive = bz2 gz
 13.1262 +	    zip</programlisting>
 13.1263 +	</listitem>
 13.1264 +	<listitem><para><envar role="rc-item-web">allowpull</envar>:
 13.1265 +	    Boolean.  Determines whether the web interface allows
 13.1266 +	    remote users to <command role="hg-cmd">hg pull</command>
 13.1267 +	    and <command role="hg-cmd">hg clone</command> this
 13.1268 +	    repository over HTTP.  If set to <literal>no</literal> or
 13.1269 +	    <literal>false</literal>, only the
 13.1270 +	    <quote>human-oriented</quote> portion of the web interface
 13.1271 +	    is available.</para>
 13.1272 +	</listitem>
 13.1273 +	<listitem><para><envar role="rc-item-web">contact</envar>:
 13.1274 +	    String.  A free-form (but preferably brief) string
 13.1275 +	    identifying the person or group in charge of the
 13.1276 +	    repository.  This often contains the name and email
 13.1277 +	    address of a person or mailing list.  It often makes sense
 13.1278 +	    to place this entry in a repository's own <filename
 13.1279 +	      role="special">.hg/hgrc</filename> file, but it can make
 13.1280 +	    sense to use in a global <filename role="special">
 13.1281 +	      /.hgrc</filename>\ if every repository has a single
 13.1282 +	    maintainer.</para>
 13.1283 +	</listitem>
 13.1284 +	<listitem><para><envar role="rc-item-web">maxchanges</envar>:
 13.1285 +	    Integer.  The default maximum number of changesets to
 13.1286 +	    display in a single page of output.</para>
 13.1287 +	</listitem>
 13.1288 +	<listitem><para><envar role="rc-item-web">maxfiles</envar>:
 13.1289 +	    Integer.  The default maximum number of modified files to
 13.1290 +	    display in a single page of output.</para>
 13.1291 +	</listitem>
 13.1292 +	<listitem><para><envar role="rc-item-web">stripes</envar>:
 13.1293 +	    Integer.  If the web interface displays alternating
 13.1294 +	    <quote>stripes</quote> to make it easier to visually align
 13.1295 +	    rows when you are looking at a table, this number controls
 13.1296 +	    the number of rows in each stripe.</para>
 13.1297 +	</listitem>
 13.1298 +	<listitem><para><envar role="rc-item-web">style</envar>:
 13.1299 +	    Controls the template Mercurial uses to display the web
 13.1300 +	    interface.  Mercurial ships with two web templates, named
 13.1301 +	    <literal>default</literal> and <literal>gitweb</literal>
 13.1302 +	    (the latter is much more visually attractive).  You can
 13.1303 +	    also specify a custom template of your own; see chapter
 13.1304 +	    <xref linkend="chap:template"/> for details.
 13.1305 +	    Here, you can see how to enable the
 13.1306 +	    <literal>gitweb</literal> style.</para>
 13.1307 +	  <programlisting>[web] style = gitweb</programlisting>
 13.1308 +	</listitem>
 13.1309 +	<listitem><para><envar role="rc-item-web">templates</envar>:
 13.1310 +	    Path.  The directory in which to search for template
 13.1311 +	    files.  By default, Mercurial searches in the directory in
 13.1312 +	    which it was installed.</para>
 13.1313 +	</listitem></itemizedlist>
 13.1314 +      <para>If you are using <filename
 13.1315 +	  role="special">hgwebdir.cgi</filename>, you can place a few
 13.1316 +	configuration items in a <literal role="rc-web">web</literal>
 13.1317 +	section of the <filename
 13.1318 +	  role="special">hgweb.config</filename> file instead of a
 13.1319 +	<filename role="special"> /.hgrc</filename>\ file, for
 13.1320 +	convenience.  These items are <envar
 13.1321 +	  role="rc-item-web">motd</envar> and <envar
 13.1322 +	  role="rc-item-web">style</envar>.</para>
 13.1323 +
 13.1324 +      <sect3>
 13.1325 +	<title>Options specific to an individual repository</title>
 13.1326 +
 13.1327 +	<para>A few <literal role="rc-web">web</literal> configuration
 13.1328 +	  items ought to be placed in a repository's local <filename
 13.1329 +	    role="special">.hg/hgrc</filename>, rather than a user's
 13.1330 +	  or global <filename role="special">
 13.1331 +	    /.hgrc</filename>.</para>
 13.1332 +	<itemizedlist>
 13.1333 +	  <listitem><para><envar
 13.1334 +		role="rc-item-web">description</envar>: String.  A
 13.1335 +	      free-form (but preferably brief) string that describes
 13.1336 +	      the contents or purpose of the repository.</para>
 13.1337 +	  </listitem>
 13.1338 +	  <listitem><para><envar role="rc-item-web">name</envar>:
 13.1339 +	      String.  The name to use for the repository in the web
 13.1340 +	      interface.  This overrides the default name, which is
 13.1341 +	      the last component of the repository's path.</para>
 13.1342 +	  </listitem></itemizedlist>
 13.1343 +
 13.1344 +      </sect3>
 13.1345 +      <sect3>
 13.1346 +	<title>Options specific to the <command role="hg-cmd">hg
 13.1347 +	    serve</command> command</title>
 13.1348 +
 13.1349 +	<para>Some of the items in the <literal
 13.1350 +	    role="rc-web">web</literal> section of a <filename
 13.1351 +	    role="special"> /.hgrc</filename>\ file are only for use
 13.1352 +	  with the <command role="hg-cmd">hg serve</command>
 13.1353 +	  command.</para>
 13.1354 +	<itemizedlist>
 13.1355 +	  <listitem><para><envar role="rc-item-web">accesslog</envar>:
 13.1356 +	      Path.  The name of a file into which to write an access
 13.1357 +	      log.  By default, the <command role="hg-cmd">hg
 13.1358 +		serve</command> command writes this information to
 13.1359 +	      standard output, not to a file.  Log entries are written
 13.1360 +	      in the standard <quote>combined</quote> file format used
 13.1361 +	      by almost all web servers.</para>
 13.1362 +	  </listitem>
 13.1363 +	  <listitem><para><envar role="rc-item-web">address</envar>:
 13.1364 +	      String.  The local address on which the server should
 13.1365 +	      listen for incoming connections.  By default, the server
 13.1366 +	      listens on all addresses.</para>
 13.1367 +	  </listitem>
 13.1368 +	  <listitem><para><envar role="rc-item-web">errorlog</envar>:
 13.1369 +	      Path.  The name of a file into which to write an error
 13.1370 +	      log.  By default, the <command role="hg-cmd">hg
 13.1371 +		serve</command> command writes this information to
 13.1372 +	      standard error, not to a file.</para>
 13.1373 +	  </listitem>
 13.1374 +	  <listitem><para><envar role="rc-item-web">ipv6</envar>:
 13.1375 +	      Boolean.  Whether to use the IPv6 protocol. By default,
 13.1376 +	      IPv6 is not used.</para>
 13.1377 +	  </listitem>
 13.1378 +	  <listitem><para><envar role="rc-item-web">port</envar>:
 13.1379 +	      Integer.  The TCP port number on which the server should
 13.1380 +	      listen.  The default port number used is 8000.</para>
 13.1381 +	  </listitem></itemizedlist>
 13.1382 +
 13.1383 +      </sect3>
 13.1384 +      <sect3>
 13.1385 +	<title>Choosing the right <filename role="special">
 13.1386 +	    /.hgrc</filename>\ file to add <literal
 13.1387 +	    role="rc-web">web</literal> items to</title>
 13.1388 +
 13.1389 +	<para>It is important to remember that a web server like
 13.1390 +	  Apache or <literal>lighttpd</literal> will run under a user
 13.1391 +	  ID that is different to yours. CGI scripts run by your
 13.1392 +	  server, such as <filename
 13.1393 +	    role="special">hgweb.cgi</filename>, will usually also run
 13.1394 +	  under that user ID.</para>
 13.1395 +
 13.1396 +	<para>If you add <literal role="rc-web">web</literal> items to
 13.1397 +	  your own personal <filename role="special">
 13.1398 +	    /.hgrc</filename>\ file, CGI scripts won't read that
 13.1399 +	  <filename role="special"> /.hgrc</filename>\ file.  Those
 13.1400 +	  settings will thus only affect the behaviour of the <command
 13.1401 +	    role="hg-cmd">hg serve</command> command when you run it.
 13.1402 +	  To cause CGI scripts to see your settings, either create a
 13.1403 +	  <filename role="special"> /.hgrc</filename>\ file in the
 13.1404 +	  home directory of the user ID that runs your web server, or
 13.1405 +	  add those settings to a system-wide <filename
 13.1406 +	    role="special"> /.hgrc</filename>\ file.</para>
 13.1407 +
 13.1408 +
 13.1409 +      </sect3>
 13.1410 +    </sect2>
 13.1411 +  </sect1>
 13.1412 +</chapter>
 13.1413 +
 13.1414 +<!--
 13.1415 +local variables: 
 13.1416 +sgml-parent-document: ("00book.xml" "book" "chapter")
 13.1417 +end:
 13.1418 +-->