1.1 --- a/fr/appD-license.xml	Wed Sep 09 15:25:09 2009 +0200
     1.2 +++ b/fr/appD-license.xml	Wed Sep 09 16:07:36 2009 +0200
     1.3 @@ -1,185 +1,179 @@
     1.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5  
     1.6 -<chapter>
     1.7 -<title>Open Publication License</title>
     1.8 -<para>\label{cha:opl}</para>
     1.9 +<appendix id="cha:opl">
    1.10 +  <?dbhtml filename="open-publication-license.html"?>
    1.11 +  <title>Open Publication License</title>
    1.12  
    1.13 -<para>Version 1.0, 8 June 1999</para>
    1.14 +  <para id="x_638">Version 1.0, 8 June 1999</para>
    1.15  
    1.16 -<sect1>
    1.17 -<title>Requirements on both unmodified and modified versions</title>
    1.18 +  <sect1>
    1.19 +    <title>Requirements on both unmodified and modified
    1.20 +      versions</title>
    1.21  
    1.22 -<para>The Open Publication works may be reproduced and distributed in whole
    1.23 -or in part, in any medium physical or electronic, provided that the
    1.24 -terms of this license are adhered to, and that this license or an
    1.25 -incorporation of it by reference (with any options elected by the
    1.26 -author(s) and/or publisher) is displayed in the reproduction.</para>
    1.27 +    <para id="x_639">The Open Publication works may be reproduced and distributed
    1.28 +      in whole or in part, in any medium physical or electronic,
    1.29 +      provided that the terms of this license are adhered to, and that
    1.30 +      this license or an incorporation of it by reference (with any
    1.31 +      options elected by the author(s) and/or publisher) is displayed
    1.32 +      in the reproduction.</para>
    1.33  
    1.34 -<para>Proper form for an incorporation by reference is as follows:</para>
    1.35 +    <para id="x_63a">Proper form for an incorporation by reference is as
    1.36 +      follows:</para>
    1.37  
    1.38 -<blockquote>
    1.39 -<para>  Copyright (c) <emphasis>year</emphasis> by <emphasis>author's name or designee</emphasis>. This
    1.40 -  material may be distributed only subject to the terms and conditions
    1.41 -  set forth in the Open Publication License, v<emphasis>x.y</emphasis> or later (the
    1.42 -  latest version is presently available at
    1.43 -  <ulink url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para>
    1.44 -</blockquote>
    1.45 +    <blockquote>
    1.46 +      <para id="x_63b">  Copyright (c) <emphasis>year</emphasis> by
    1.47 +	<emphasis>author's name or designee</emphasis>. This material
    1.48 +	may be distributed only subject to the terms and conditions
    1.49 +	set forth in the Open Publication License,
    1.50 +	v<emphasis>x.y</emphasis> or later (the latest version is
    1.51 +	presently available at <ulink
    1.52 +	  url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para>
    1.53 +    </blockquote>
    1.54  
    1.55 -<para>The reference must be immediately followed with any options elected by
    1.56 -the author(s) and/or publisher of the document (see
    1.57 -section <xref linkend="sec:opl:options"/>).</para>
    1.58 +    <para id="x_63c">The reference must be immediately followed with any options
    1.59 +      elected by the author(s) and/or publisher of the document (see
    1.60 +      <xref linkend="sec:opl:options"/>).</para>
    1.61  
    1.62 -<para>Commercial redistribution of Open Publication-licensed material is
    1.63 -permitted.</para>
    1.64 +    <para id="x_63d">Commercial redistribution of Open Publication-licensed
    1.65 +      material is permitted.</para>
    1.66  
    1.67 -<para>Any publication in standard (paper) book form shall require the
    1.68 -citation of the original publisher and author. The publisher and
    1.69 -author's names shall appear on all outer surfaces of the book. On all
    1.70 -outer surfaces of the book the original publisher's name shall be as
    1.71 -large as the title of the work and cited as possessive with respect to
    1.72 -the title.</para>
    1.73 +    <para id="x_63e">Any publication in standard (paper) book form shall require
    1.74 +      the citation of the original publisher and author. The publisher
    1.75 +      and author's names shall appear on all outer surfaces of the
    1.76 +      book. On all outer surfaces of the book the original publisher's
    1.77 +      name shall be as large as the title of the work and cited as
    1.78 +      possessive with respect to the title.</para>
    1.79  
    1.80 -</sect1>
    1.81 -<sect1>
    1.82 -<title>Copyright</title>
    1.83 +  </sect1>
    1.84 +  <sect1>
    1.85 +    <title>Copyright</title>
    1.86  
    1.87 -<para>The copyright to each Open Publication is owned by its author(s) or
    1.88 -designee.
    1.89 -</para>
    1.90 +    <para id="x_63f">The copyright to each Open Publication is owned by its
    1.91 +      author(s) or designee.</para>
    1.92  
    1.93 -</sect1>
    1.94 -<sect1>
    1.95 -<title>Scope of license</title>
    1.96 +  </sect1>
    1.97 +  <sect1>
    1.98 +    <title>Scope of license</title>
    1.99  
   1.100 -<para>The following license terms apply to all Open Publication works,
   1.101 -unless otherwise explicitly stated in the document.
   1.102 -</para>
   1.103 +    <para id="x_640">The following license terms apply to all Open Publication
   1.104 +      works, unless otherwise explicitly stated in the
   1.105 +      document.</para>
   1.106  
   1.107 -<para>Mere aggregation of Open Publication works or a portion of an Open
   1.108 -Publication work with other works or programs on the same media shall
   1.109 -not cause this license to apply to those other works. The aggregate
   1.110 -work shall contain a notice specifying the inclusion of the Open
   1.111 -Publication material and appropriate copyright notice.
   1.112 -</para>
   1.113 +    <para id="x_641">Mere aggregation of Open Publication works or a portion of
   1.114 +      an Open Publication work with other works or programs on the
   1.115 +      same media shall not cause this license to apply to those other
   1.116 +      works. The aggregate work shall contain a notice specifying the
   1.117 +      inclusion of the Open Publication material and appropriate
   1.118 +      copyright notice.</para>
   1.119  
   1.120 -<para><emphasis role="bold">Severability</emphasis>. If any part of this license is found to be
   1.121 -unenforceable in any jurisdiction, the remaining portions of the
   1.122 -license remain in force.
   1.123 -</para>
   1.124 +    <para id="x_642"><emphasis role="bold">Severability</emphasis>. If any part
   1.125 +      of this license is found to be unenforceable in any
   1.126 +      jurisdiction, the remaining portions of the license remain in
   1.127 +      force.</para>
   1.128  
   1.129 -<para><emphasis role="bold">No warranty</emphasis>. Open Publication works are licensed and provided
   1.130 -<quote>as is</quote> without warranty of any kind, express or implied, including,
   1.131 -but not limited to, the implied warranties of merchantability and
   1.132 -fitness for a particular purpose or a warranty of non-infringement.
   1.133 -</para>
   1.134 +    <para id="x_643"><emphasis role="bold">No warranty</emphasis>. Open
   1.135 +      Publication works are licensed and provided <quote>as is</quote>
   1.136 +      without warranty of any kind, express or implied, including, but
   1.137 +      not limited to, the implied warranties of merchantability and
   1.138 +      fitness for a particular purpose or a warranty of
   1.139 +      non-infringement.</para>
   1.140  
   1.141 -</sect1>
   1.142 -<sect1>
   1.143 -<title>Requirements on modified works</title>
   1.144 +  </sect1>
   1.145 +  <sect1>
   1.146 +    <title>Requirements on modified works</title>
   1.147  
   1.148 -<para>All modified versions of documents covered by this license, including
   1.149 -translations, anthologies, compilations and partial documents, must
   1.150 -meet the following requirements:
   1.151 -</para>
   1.152 +    <para id="x_644">All modified versions of documents covered by this license,
   1.153 +      including translations, anthologies, compilations and partial
   1.154 +      documents, must meet the following requirements:</para>
   1.155  
   1.156 -<orderedlist>
   1.157 -<listitem><para>The modified version must be labeled as such.
   1.158 -</para>
   1.159 -</listitem>
   1.160 -<listitem><para>The person making the modifications must be identified and the
   1.161 -  modifications dated.
   1.162 -</para>
   1.163 -</listitem>
   1.164 -<listitem><para>Acknowledgement of the original author and publisher if
   1.165 -  applicable must be retained according to normal academic citation
   1.166 -  practices.
   1.167 -</para>
   1.168 -</listitem>
   1.169 -<listitem><para>The location of the original unmodified document must be
   1.170 -  identified.
   1.171 -</para>
   1.172 -</listitem>
   1.173 -<listitem><para>The original author's (or authors') name(s) may not be used to
   1.174 -  assert or imply endorsement of the resulting document without the
   1.175 -  original author's (or authors') permission.
   1.176 -</para>
   1.177 -</listitem></orderedlist>
   1.178 +    <orderedlist>
   1.179 +      <listitem><para id="x_645">The modified version must be labeled as
   1.180 +	  such.</para>
   1.181 +      </listitem>
   1.182 +      <listitem><para id="x_646">The person making the modifications must be
   1.183 +	  identified and the modifications dated.</para>
   1.184 +      </listitem>
   1.185 +      <listitem><para id="x_647">Acknowledgement of the original author and
   1.186 +	  publisher if applicable must be retained according to normal
   1.187 +	  academic citation practices.</para>
   1.188 +      </listitem>
   1.189 +      <listitem><para id="x_648">The location of the original unmodified document
   1.190 +	  must be identified.</para>
   1.191 +      </listitem>
   1.192 +      <listitem><para id="x_649">The original author's (or authors') name(s) may
   1.193 +	  not be used to assert or imply endorsement of the resulting
   1.194 +	  document without the original author's (or authors')
   1.195 +	  permission.</para>
   1.196 +      </listitem></orderedlist>
   1.197  
   1.198 -</sect1>
   1.199 -<sect1>
   1.200 -<title>Good-practice recommendations</title>
   1.201 +  </sect1>
   1.202 +  <sect1>
   1.203 +    <title>Good-practice recommendations</title>
   1.204  
   1.205 -<para>In addition to the requirements of this license, it is requested from
   1.206 -and strongly recommended of redistributors that:
   1.207 -</para>
   1.208 +    <para id="x_64a">In addition to the requirements of this license, it is
   1.209 +      requested from and strongly recommended of redistributors
   1.210 +      that:</para>
   1.211  
   1.212 -<orderedlist>
   1.213 -<listitem><para>If you are distributing Open Publication works on hardcopy or
   1.214 -  CD-ROM, you provide email notification to the authors of your intent
   1.215 -  to redistribute at least thirty days before your manuscript or media
   1.216 -  freeze, to give the authors time to provide updated documents. This
   1.217 -  notification should describe modifications, if any, made to the
   1.218 -  document.
   1.219 -</para>
   1.220 -</listitem>
   1.221 -<listitem><para>All substantive modifications (including deletions) be either
   1.222 -  clearly marked up in the document or else described in an attachment
   1.223 -  to the document.
   1.224 -</para>
   1.225 -</listitem>
   1.226 -<listitem><para>Finally, while it is not mandatory under this license, it is
   1.227 -  considered good form to offer a free copy of any hardcopy and CD-ROM
   1.228 -  expression of an Open Publication-licensed work to its author(s).
   1.229 -</para>
   1.230 -</listitem></orderedlist>
   1.231 +    <orderedlist>
   1.232 +      <listitem><para id="x_64b">If you are distributing Open Publication works
   1.233 +	  on hardcopy or CD-ROM, you provide email notification to the
   1.234 +	  authors of your intent to redistribute at least thirty days
   1.235 +	  before your manuscript or media freeze, to give the authors
   1.236 +	  time to provide updated documents. This notification should
   1.237 +	  describe modifications, if any, made to the document.</para>
   1.238 +      </listitem>
   1.239 +      <listitem><para id="x_64c">All substantive modifications (including
   1.240 +	  deletions) be either clearly marked up in the document or
   1.241 +	  else described in an attachment to the document.</para>
   1.242 +      </listitem>
   1.243 +      <listitem><para id="x_64d">Finally, while it is not mandatory under this
   1.244 +	  license, it is considered good form to offer a free copy of
   1.245 +	  any hardcopy and CD-ROM expression of an Open
   1.246 +	  Publication-licensed work to its author(s).</para>
   1.247 +      </listitem></orderedlist>
   1.248  
   1.249 -</sect1>
   1.250 -<sect1>
   1.251 -<title>License options</title>
   1.252 -<para>\label{sec:opl:options}
   1.253 -</para>
   1.254 +  </sect1>
   1.255 +  <sect1 id="sec:opl:options">
   1.256 +    <title>License options</title>
   1.257  
   1.258 -<para>The author(s) and/or publisher of an Open Publication-licensed
   1.259 -document may elect certain options by appending language to the
   1.260 -reference to or copy of the license. These options are considered part
   1.261 -of the license instance and must be included with the license (or its
   1.262 -incorporation by reference) in derived works.
   1.263 -</para>
   1.264 +    <para id="x_64e">The author(s) and/or publisher of an Open
   1.265 +      Publication-licensed document may elect certain options by
   1.266 +      appending language to the reference to or copy of the license.
   1.267 +      These options are considered part of the license instance and
   1.268 +      must be included with the license (or its incorporation by
   1.269 +      reference) in derived works.</para>
   1.270  
   1.271 -<orderedlist>
   1.272 -<listitem><para>To prohibit distribution of substantively modified versions
   1.273 -  without the explicit permission of the author(s). <quote>Substantive
   1.274 -  modification</quote> is defined as a change to the semantic content of the
   1.275 -  document, and excludes mere changes in format or typographical
   1.276 -  corrections.
   1.277 -</para>
   1.278 -</listitem>
   1.279 -<listitem><para>  To accomplish this, add the phrase <quote>Distribution of substantively
   1.280 -  modified versions of this document is prohibited without the
   1.281 -  explicit permission of the copyright holder.</quote> to the license
   1.282 -  reference or copy.
   1.283 -</para>
   1.284 -</listitem>
   1.285 -</para>
   1.286 -</listitem>
   1.287 -<listitem><para>To prohibit any publication of this work or derivative works in
   1.288 -  whole or in part in standard (paper) book form for commercial
   1.289 -  purposes is prohibited unless prior permission is obtained from the
   1.290 -  copyright holder.
   1.291 -</para>
   1.292 -</listitem>
   1.293 -<listitem><para>  To accomplish this, add the phrase <quote>Distribution of the work or
   1.294 -  derivative of the work in any standard (paper) book form is
   1.295 -  prohibited unless prior permission is obtained from the copyright
   1.296 -  holder.</quote> to the license reference or copy.
   1.297 -</para>
   1.298 -</listitem></orderedlist>
   1.299 +    <orderedlist>
   1.300 +      <listitem><para id="x_64f">To prohibit distribution of substantively
   1.301 +	  modified versions without the explicit permission of the
   1.302 +	  author(s). <quote>Substantive modification</quote> is
   1.303 +	  defined as a change to the semantic content of the document,
   1.304 +	  and excludes mere changes in format or typographical
   1.305 +	  corrections.</para>
   1.306 +      </listitem>
   1.307 +      <listitem><para id="x_650">  To accomplish this, add the phrase
   1.308 +	  <quote>Distribution of substantively modified versions of
   1.309 +	    this document is prohibited without the explicit
   1.310 +	    permission of the copyright holder.</quote> to the license
   1.311 +	  reference or copy.</para>
   1.312 +      </listitem>
   1.313 +      <listitem><para id="x_651">To prohibit any publication of this work or
   1.314 +	  derivative works in whole or in part in standard (paper)
   1.315 +	  book form for commercial purposes is prohibited unless prior
   1.316 +	  permission is obtained from the copyright holder.</para>
   1.317 +      </listitem>
   1.318 +      <listitem><para id="x_652">To accomplish this, add the phrase
   1.319 +	  <quote>Distribution of the work or derivative of the work in
   1.320 +	    any standard (paper) book form is prohibited unless prior
   1.321 +	    permission is obtained from the copyright holder.</quote>
   1.322 +	  to the license reference or copy.</para>
   1.323 +      </listitem></orderedlist>
   1.324  
   1.325 -</sect1>
   1.326 -</chapter>
   1.327 +  </sect1>
   1.328 +</appendix>
   1.329  
   1.330  <!--
   1.331  local variables: 
   1.332 -sgml-parent-document: ("00book.xml" "book" "chapter")
   1.333 +sgml-parent-document: ("00book.xml" "book" "appendix")
   1.334  end:
   1.335 --->
   1.336 \ No newline at end of file
   1.337 +-->

     2.1 --- a/fr/ch05-daily.xml	Wed Sep 09 15:25:09 2009 +0200
     2.2 +++ b/fr/ch05-daily.xml	Wed Sep 09 16:07:36 2009 +0200
     2.3 @@ -1,474 +1,840 @@
     2.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     2.5  
     2.6 -<chapter>
     2.7 -<title>Mercurial in daily use</title>
     2.8 -<para>\label{chap:daily}</para>
     2.9 -
    2.10 -<sect1>
    2.11 -<title>Telling Mercurial which files to track</title>
    2.12 -
    2.13 -<para>Mercurial does not work with files in your repository unless you tell
    2.14 -it to manage them.  The <command role="hg-cmd">hg status</command> command will tell you which
    2.15 -files Mercurial doesn't know about; it uses a <quote><literal>?</literal></quote> to
    2.16 -display such files.</para>
    2.17 -
    2.18 -<para>To tell Mercurial to track a file, use the <command role="hg-cmd">hg add</command> command.  Once
    2.19 -you have added a file, the entry in the output of <command role="hg-cmd">hg status</command> for
    2.20 -that file changes from <quote><literal>?</literal></quote> to <quote><literal>A</literal></quote>.
    2.21 -<!-- &interaction.daily.files.add; --></para>
    2.22 -
    2.23 -<para>After you run a <command role="hg-cmd">hg commit</command>, the files that you added before the
    2.24 -commit will no longer be listed in the output of <command role="hg-cmd">hg status</command>.  The
    2.25 -reason for this is that <command role="hg-cmd">hg status</command> only tells you about
    2.26 -<quote>interesting</quote> files&emdash;those that you have modified or told Mercurial
    2.27 -to do something with&emdash;by default.  If you have a repository that
    2.28 -contains thousands of files, you will rarely want to know about files
    2.29 -that Mercurial is tracking, but that have not changed.  (You can still
    2.30 -get this information; we'll return to this later.)</para>
    2.31 -
    2.32 -<para>Once you add a file, Mercurial doesn't do anything with it
    2.33 -immediately.  Instead, it will take a snapshot of the file's state the
    2.34 -next time you perform a commit.  It will then continue to track the
    2.35 -changes you make to the file every time you commit, until you remove
    2.36 -the file.</para>
    2.37 -
    2.38 -<sect2>
    2.39 -<title>Explicit versus implicit file naming</title>
    2.40 -
    2.41 -<para>A useful behaviour that Mercurial has is that if you pass the name of
    2.42 -a directory to a command, every Mercurial command will treat this as
    2.43 -<quote>I want to operate on every file in this directory and its
    2.44 -subdirectories</quote>.
    2.45 -<!-- &interaction.daily.files.add-dir; -->
    2.46 -Notice in this example that Mercurial printed the names of the files
    2.47 -it added, whereas it didn't do so when we added the file named
    2.48 -<filename>a</filename> in the earlier example.</para>
    2.49 -
    2.50 -<para>What's going on is that in the former case, we explicitly named the
    2.51 -file to add on the command line, so the assumption that Mercurial
    2.52 -makes in such cases is that you know what you were doing, and it
    2.53 -doesn't print any output.</para>
    2.54 -
    2.55 -<para>However, when we <emphasis>imply</emphasis> the names of files by giving the name of
    2.56 -a directory, Mercurial takes the extra step of printing the name of
    2.57 -each file that it does something with.  This makes it more clear what
    2.58 -is happening, and reduces the likelihood of a silent and nasty
    2.59 -surprise.  This behaviour is common to most Mercurial commands.</para>
    2.60 -
    2.61 -</sect2>
    2.62 -<sect2>
    2.63 -<title>Aside: Mercurial tracks files, not directories</title>
    2.64 -
    2.65 -<para>Mercurial does not track directory information.  Instead, it tracks
    2.66 -the path to a file.  Before creating a file, it first creates any
    2.67 -missing directory components of the path.  After it deletes a file, it
    2.68 -then deletes any empty directories that were in the deleted file's
    2.69 -path.  This sounds like a trivial distinction, but it has one minor
    2.70 -practical consequence: it is not possible to represent a completely
    2.71 -empty directory in Mercurial.
    2.72 -</para>
    2.73 -
    2.74 -<para>Empty directories are rarely useful, and there are unintrusive
    2.75 -workarounds that you can use to achieve an appropriate effect.  The
    2.76 -developers of Mercurial thus felt that the complexity that would be
    2.77 -required to manage empty directories was not worth the limited benefit
    2.78 -this feature would bring.
    2.79 -</para>
    2.80 -
    2.81 -<para>If you need an empty directory in your repository, there are a few
    2.82 -ways to achieve this. One is to create a directory, then <command role="hg-cmd">hg add</command> a
    2.83 -<quote>hidden</quote> file to that directory.  On Unix-like systems, any file
    2.84 -name that begins with a period (<quote><literal>.</literal></quote>) is treated as hidden
    2.85 -by most commands and GUI tools.  This approach is illustrated in
    2.86 -figure <xref linkend="ex:daily:hidden"/>.
    2.87 -</para>
    2.88 -
    2.89 -<informalfigure>
    2.90 -<para>  <!-- &interaction.daily.files.hidden; -->
    2.91 -  <caption><para>Simulating an empty directory using a hidden file</para></caption>
    2.92 -  \label{ex:daily:hidden}
    2.93 -</para>
    2.94 -</informalfigure>
    2.95 -
    2.96 -<para>Another way to tackle a need for an empty directory is to simply
    2.97 -create one in your automated build scripts before they will need it.
    2.98 -</para>
    2.99 -
   2.100 -</sect2>
   2.101 -</sect1>
   2.102 -<sect1>
   2.103 -<title>How to stop tracking a file</title>
   2.104 -
   2.105 -<para>Once you decide that a file no longer belongs in your repository, use
   2.106 -the <command role="hg-cmd">hg remove</command> command; this deletes the file, and tells Mercurial
   2.107 -to stop tracking it.  A removed file is represented in the output of
   2.108 -<command role="hg-cmd">hg status</command> with a <quote><literal>R</literal></quote>.
   2.109 -<!-- &interaction.daily.files.remove; -->
   2.110 -</para>
   2.111 -
   2.112 -<para>After you <command role="hg-cmd">hg remove</command> a file, Mercurial will no longer track
   2.113 -changes to that file, even if you recreate a file with the same name
   2.114 -in your working directory.  If you do recreate a file with the same
   2.115 -name and want Mercurial to track the new file, simply <command role="hg-cmd">hg add</command> it.
   2.116 -Mercurial will know that the newly added file is not related to the
   2.117 -old file of the same name.
   2.118 -</para>
   2.119 -
   2.120 -<sect2>
   2.121 -<title>Removing a file does not affect its history</title>
   2.122 -
   2.123 -<para>It is important to understand that removing a file has only two
   2.124 -effects.
   2.125 -</para>
   2.126 -<itemizedlist>
   2.127 -<listitem><para>It removes the current version of the file from the working
   2.128 -  directory.
   2.129 -</para>
   2.130 -</listitem>
   2.131 -<listitem><para>It stops Mercurial from tracking changes to the file, from the
   2.132 -  time of the next commit.
   2.133 -</para>
   2.134 -</listitem></itemizedlist>
   2.135 -<para>Removing a file <emphasis>does not</emphasis> in any way alter the <emphasis>history</emphasis> of
   2.136 -the file.
   2.137 -</para>
   2.138 -
   2.139 -<para>If you update the working directory to a changeset in which a file
   2.140 -that you have removed was still tracked, it will reappear in the
   2.141 -working directory, with the contents it had when you committed that
   2.142 -changeset.  If you then update the working directory to a later
   2.143 -changeset, in which the file had been removed, Mercurial will once
   2.144 -again remove the file from the working directory.
   2.145 -</para>
   2.146 -
   2.147 -</sect2>
   2.148 -<sect2>
   2.149 -<title>Missing files</title>
   2.150 -
   2.151 -<para>Mercurial considers a file that you have deleted, but not used
   2.152 -<command role="hg-cmd">hg remove</command> to delete, to be <emphasis>missing</emphasis>.  A missing file is
   2.153 -represented with <quote><literal>!</literal></quote> in the output of <command role="hg-cmd">hg status</command>.
   2.154 -Mercurial commands will not generally do anything with missing files.
   2.155 -<!-- &interaction.daily.files.missing; -->
   2.156 -</para>
   2.157 -
   2.158 -<para>If your repository contains a file that <command role="hg-cmd">hg status</command> reports as
   2.159 -missing, and you want the file to stay gone, you can run
   2.160 -<command role="hg-cmd">hg remove <option role="hg-opt-remove">--after</option></command> at any time later on, to
   2.161 -tell Mercurial that you really did mean to remove the file.
   2.162 -<!-- &interaction.daily.files.remove-after; -->
   2.163 -</para>
   2.164 -
   2.165 -<para>On the other hand, if you deleted the missing file by accident, use
   2.166 -<command role="hg-cmd">hg revert <emphasis>filename</emphasis></command> to recover the file.  It will
   2.167 -reappear, in unmodified form.
   2.168 -<!-- &interaction.daily.files.recover-missing; -->
   2.169 -</para>
   2.170 -
   2.171 -<para>\subsection{Aside: why tell Mercurial explicitly to
   2.172 -  remove a file?}
   2.173 -</para>
   2.174 -
   2.175 -<para>You might wonder why Mercurial requires you to explicitly tell it that
   2.176 -you are deleting a file.  Early during the development of Mercurial,
   2.177 -it let you delete a file however you pleased; Mercurial would notice
   2.178 -the absence of the file automatically when you next ran a
   2.179 -<command role="hg-cmd">hg commit</command>, and stop tracking the file.  In practice, this made it
   2.180 -too easy to accidentally remove a file without noticing.
   2.181 -</para>
   2.182 -
   2.183 -<para>\subsection{Useful shorthand&emdash;adding and removing files
   2.184 -  in one step}
   2.185 -</para>
   2.186 -
   2.187 -<para>Mercurial offers a combination command, <command role="hg-cmd">hg addremove</command>, that adds
   2.188 -untracked files and marks missing files as removed.
   2.189 -<!-- &interaction.daily.files.addremove; -->
   2.190 -The <command role="hg-cmd">hg commit</command> command also provides a <option role="hg-opt-commit">-A</option> option
   2.191 -that performs this same add-and-remove, immediately followed by a
   2.192 -commit.
   2.193 -<!-- &interaction.daily.files.commit-addremove; -->
   2.194 -</para>
   2.195 -
   2.196 -</sect2>
   2.197 -</sect1>
   2.198 -<sect1>
   2.199 -<title>Copying files</title>
   2.200 -
   2.201 -<para>Mercurial provides a <command role="hg-cmd">hg copy</command> command that lets you make a new
   2.202 -copy of a file.  When you copy a file using this command, Mercurial
   2.203 -makes a record of the fact that the new file is a copy of the original
   2.204 -file.  It treats these copied files specially when you merge your work
   2.205 -with someone else's.
   2.206 -</para>
   2.207 -
   2.208 -<sect2>
   2.209 -<title>The results of copying during a merge</title>
   2.210 -
   2.211 -<para>What happens during a merge is that changes <quote>follow</quote> a copy.  To
   2.212 -best illustrate what this means, let's create an example.  We'll start
   2.213 -with the usual tiny repository that contains a single file.
   2.214 -<!-- &interaction.daily.copy.init; -->
   2.215 -We need to do some work in parallel, so that we'll have something to
   2.216 -merge.  So let's clone our repository.
   2.217 -<!-- &interaction.daily.copy.clone; -->
   2.218 -Back in our initial repository, let's use the <command role="hg-cmd">hg copy</command> command to
   2.219 -make a copy of the first file we created.
   2.220 -<!-- &interaction.daily.copy.copy; -->
   2.221 -</para>
   2.222 -
   2.223 -<para>If we look at the output of the <command role="hg-cmd">hg status</command> command afterwards, the
   2.224 -copied file looks just like a normal added file.
   2.225 -<!-- &interaction.daily.copy.status; -->
   2.226 -But if we pass the <option role="hg-opt-status">-C</option> option to <command role="hg-cmd">hg status</command>, it
   2.227 -prints another line of output: this is the file that our newly-added
   2.228 -file was copied <emphasis>from</emphasis>.
   2.229 -<!-- &interaction.daily.copy.status-copy; -->
   2.230 -</para>
   2.231 -
   2.232 -<para>Now, back in the repository we cloned, let's make a change in
   2.233 -parallel.  We'll add a line of content to the original file that we
   2.234 -created.
   2.235 -<!-- &interaction.daily.copy.other; -->
   2.236 -Now we have a modified <filename>file</filename> in this repository.  When we
   2.237 -pull the changes from the first repository, and merge the two heads,
   2.238 -Mercurial will propagate the changes that we made locally to
   2.239 -<filename>file</filename> into its copy, <filename>new-file</filename>.
   2.240 -<!-- &interaction.daily.copy.merge; -->
   2.241 -</para>
   2.242 -
   2.243 -</sect2>
   2.244 -<sect2>
   2.245 -<title>Why should changes follow copies?</title>
   2.246 -<para>\label{sec:daily:why-copy}
   2.247 -</para>
   2.248 -
   2.249 -<para>This behaviour, of changes to a file propagating out to copies of the
   2.250 -file, might seem esoteric, but in most cases it's highly desirable.
   2.251 -</para>
   2.252 -
   2.253 -<para>First of all, remember that this propagation <emphasis>only</emphasis> happens when
   2.254 -you merge.  So if you <command role="hg-cmd">hg copy</command> a file, and subsequently modify the
   2.255 -original file during the normal course of your work, nothing will
   2.256 -happen.
   2.257 -</para>
   2.258 -
   2.259 -<para>The second thing to know is that modifications will only propagate
   2.260 -across a copy as long as the repository that you're pulling changes
   2.261 -from <emphasis>doesn't know</emphasis> about the copy.
   2.262 -</para>
   2.263 -
   2.264 -<para>The reason that Mercurial does this is as follows.  Let's say I make
   2.265 -an important bug fix in a source file, and commit my changes.
   2.266 -Meanwhile, you've decided to <command role="hg-cmd">hg copy</command> the file in your repository,
   2.267 -without knowing about the bug or having seen the fix, and you have
   2.268 -started hacking on your copy of the file.
   2.269 -</para>
   2.270 -
   2.271 -<para>If you pulled and merged my changes, and Mercurial <emphasis>didn't</emphasis>
   2.272 -propagate changes across copies, your source file would now contain
   2.273 -the bug, and unless you remembered to propagate the bug fix by hand,
   2.274 -the bug would <emphasis>remain</emphasis> in your copy of the file.
   2.275 -</para>
   2.276 -
   2.277 -<para>By automatically propagating the change that fixed the bug from the
   2.278 -original file to the copy, Mercurial prevents this class of problem.
   2.279 -To my knowledge, Mercurial is the <emphasis>only</emphasis> revision control system
   2.280 -that propagates changes across copies like this.
   2.281 -</para>
   2.282 -
   2.283 -<para>Once your change history has a record that the copy and subsequent
   2.284 -merge occurred, there's usually no further need to propagate changes
   2.285 -from the original file to the copied file, and that's why Mercurial
   2.286 -only propagates changes across copies until this point, and no
   2.287 -further.
   2.288 -</para>
   2.289 -
   2.290 -</sect2>
   2.291 -<sect2>
   2.292 -<title>How to make changes <emphasis>not</emphasis> follow a copy</title>
   2.293 -
   2.294 -<para>If, for some reason, you decide that this business of automatically
   2.295 -propagating changes across copies is not for you, simply use your
   2.296 -system's normal file copy command (on Unix-like systems, that's
   2.297 -<command>cp</command>) to make a copy of a file, then <command role="hg-cmd">hg add</command> the new copy
   2.298 -by hand.  Before you do so, though, please do reread
   2.299 -section <xref linkend="sec:daily:why-copy"/>, and make an informed decision that
   2.300 -this behaviour is not appropriate to your specific case.
   2.301 -</para>
   2.302 -
   2.303 -</sect2>
   2.304 -<sect2>
   2.305 -<title>Behaviour of the <command role="hg-cmd">hg copy</command> command</title>
   2.306 -
   2.307 -<para>When you use the <command role="hg-cmd">hg copy</command> command, Mercurial makes a copy of each
   2.308 -source file as it currently stands in the working directory.  This
   2.309 -means that if you make some modifications to a file, then <command role="hg-cmd">hg copy</command>
   2.310 -it without first having committed those changes, the new copy will
   2.311 -also contain the modifications you have made up until that point.  (I
   2.312 -find this behaviour a little counterintuitive, which is why I mention
   2.313 -it here.)
   2.314 -</para>
   2.315 -
   2.316 -<para>The <command role="hg-cmd">hg copy</command> command acts similarly to the Unix <command>cp</command>
   2.317 -command (you can use the <command role="hg-cmd">hg cp</command> alias if you prefer).  The last
   2.318 -argument is the <emphasis>destination</emphasis>, and all prior arguments are
   2.319 -<emphasis>sources</emphasis>.  If you pass it a single file as the source, and the
   2.320 -destination does not exist, it creates a new file with that name.
   2.321 -<!-- &interaction.daily.copy.simple; -->
   2.322 -If the destination is a directory, Mercurial copies its sources into
   2.323 -that directory.
   2.324 -<!-- &interaction.daily.copy.dir-dest; -->
   2.325 -Copying a directory is recursive, and preserves the directory
   2.326 -structure of the source.
   2.327 -<!-- &interaction.daily.copy.dir-src; -->
   2.328 -If the source and destination are both directories, the source tree is
   2.329 -recreated in the destination directory.
   2.330 -<!-- &interaction.daily.copy.dir-src-dest; -->
   2.331 -</para>
   2.332 -
   2.333 -<para>As with the <command role="hg-cmd">hg rename</command> command, if you copy a file manually and
   2.334 -then want Mercurial to know that you've copied the file, simply use
   2.335 -the <option role="hg-opt-copy">--after</option> option to <command role="hg-cmd">hg copy</command>.
   2.336 -<!-- &interaction.daily.copy.after; -->
   2.337 -</para>
   2.338 -
   2.339 -</sect2>
   2.340 -</sect1>
   2.341 -<sect1>
   2.342 -<title>Renaming files</title>
   2.343 -
   2.344 -<para>It's rather more common to need to rename a file than to make a copy
   2.345 -of it.  The reason I discussed the <command role="hg-cmd">hg copy</command> command before talking
   2.346 -about renaming files is that Mercurial treats a rename in essentially
   2.347 -the same way as a copy.  Therefore, knowing what Mercurial does when
   2.348 -you copy a file tells you what to expect when you rename a file.
   2.349 -</para>
   2.350 -
   2.351 -<para>When you use the <command role="hg-cmd">hg rename</command> command, Mercurial makes a copy of
   2.352 -each source file, then deletes it and marks the file as removed.
   2.353 -<!-- &interaction.daily.rename.rename; -->
   2.354 -The <command role="hg-cmd">hg status</command> command shows the newly copied file as added, and
   2.355 -the copied-from file as removed.
   2.356 -<!-- &interaction.daily.rename.status; -->
   2.357 -As with the results of a <command role="hg-cmd">hg copy</command>, we must use the
   2.358 -<option role="hg-opt-status">-C</option> option to <command role="hg-cmd">hg status</command> to see that the added file
   2.359 -is really being tracked by Mercurial as a copy of the original, now
   2.360 -removed, file.
   2.361 -<!-- &interaction.daily.rename.status-copy; -->
   2.362 -</para>
   2.363 -
   2.364 -<para>As with <command role="hg-cmd">hg remove</command> and <command role="hg-cmd">hg copy</command>, you can tell Mercurial about
   2.365 -a rename after the fact using the <option role="hg-opt-rename">--after</option> option.  In
   2.366 -most other respects, the behaviour of the <command role="hg-cmd">hg rename</command> command, and
   2.367 -the options it accepts, are similar to the <command role="hg-cmd">hg copy</command> command.
   2.368 -</para>
   2.369 -
   2.370 -<sect2>
   2.371 -<title>Renaming files and merging changes</title>
   2.372 -
   2.373 -<para>Since Mercurial's rename is implemented as copy-and-remove, the same
   2.374 -propagation of changes happens when you merge after a rename as after
   2.375 -a copy.
   2.376 -</para>
   2.377 -
   2.378 -<para>If I modify a file, and you rename it to a new name, and then we merge
   2.379 -our respective changes, my modifications to the file under its
   2.380 -original name will be propagated into the file under its new name.
   2.381 -(This is something you might expect to <quote>simply work,</quote> but not all
   2.382 -revision control systems actually do this.)
   2.383 -</para>
   2.384 -
   2.385 -<para>Whereas having changes follow a copy is a feature where you can
   2.386 -perhaps nod and say <quote>yes, that might be useful,</quote> it should be clear
   2.387 -that having them follow a rename is definitely important.  Without
   2.388 -this facility, it would simply be too easy for changes to become
   2.389 -orphaned when files are renamed.
   2.390 -</para>
   2.391 -
   2.392 -</sect2>
   2.393 -<sect2>
   2.394 -<title>Divergent renames and merging</title>
   2.395 -
   2.396 -<para>The case of diverging names occurs when two developers start with a
   2.397 -file&emdash;let's call it <filename>foo</filename>&emdash;in their respective
   2.398 -repositories.
   2.399 -</para>
   2.400 -
   2.401 -<para><!-- &interaction.rename.divergent.clone; -->
   2.402 -Anne renames the file to <filename>bar</filename>.
   2.403 -<!-- &interaction.rename.divergent.rename.anne; -->
   2.404 -Meanwhile, Bob renames it to <filename>quux</filename>.
   2.405 -<!-- &interaction.rename.divergent.rename.bob; -->
   2.406 -</para>
   2.407 -
   2.408 -<para>I like to think of this as a conflict because each developer has
   2.409 -expressed different intentions about what the file ought to be named.
   2.410 -</para>
   2.411 -
   2.412 -<para>What do you think should happen when they merge their work?
   2.413 -Mercurial's actual behaviour is that it always preserves <emphasis>both</emphasis>
   2.414 -names when it merges changesets that contain divergent renames.
   2.415 -<!-- &interaction.rename.divergent.merge; -->
   2.416 -</para>
   2.417 -
   2.418 -<para>Notice that Mercurial does warn about the divergent renames, but it
   2.419 -leaves it up to you to do something about the divergence after the merge.
   2.420 -</para>
   2.421 -
   2.422 -</sect2>
   2.423 -<sect2>
   2.424 -<title>Convergent renames and merging</title>
   2.425 -
   2.426 -<para>Another kind of rename conflict occurs when two people choose to
   2.427 -rename different <emphasis>source</emphasis> files to the same <emphasis>destination</emphasis>.
   2.428 -In this case, Mercurial runs its normal merge machinery, and lets you
   2.429 -guide it to a suitable resolution.
   2.430 -</para>
   2.431 -
   2.432 -</sect2>
   2.433 -<sect2>
   2.434 -<title>Other name-related corner cases</title>
   2.435 -
   2.436 -<para>Mercurial has a longstanding bug in which it fails to handle a merge
   2.437 -where one side has a file with a given name, while another has a
   2.438 -directory with the same name.  This is documented as <ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue29">issue 29</ulink>.
   2.439 -<!-- &interaction.issue29.go; -->
   2.440 -</para>
   2.441 -
   2.442 -</sect2>
   2.443 -</sect1>
   2.444 -<sect1>
   2.445 -<title>Recovering from mistakes</title>
   2.446 -
   2.447 -<para>Mercurial has some useful commands that will help you to recover from
   2.448 -some common mistakes.
   2.449 -</para>
   2.450 -
   2.451 -<para>The <command role="hg-cmd">hg revert</command> command lets you undo changes that you have made to
   2.452 -your working directory.  For example, if you <command role="hg-cmd">hg add</command> a file by
   2.453 -accident, just run <command role="hg-cmd">hg revert</command> with the name of the file you added,
   2.454 -and while the file won't be touched in any way, it won't be tracked
   2.455 -for adding by Mercurial any longer, either.  You can also use
   2.456 -<command role="hg-cmd">hg revert</command> to get rid of erroneous changes to a file.
   2.457 -</para>
   2.458 -
   2.459 -<para>It's useful to remember that the <command role="hg-cmd">hg revert</command> command is useful for
   2.460 -changes that you have not yet committed.  Once you've committed a
   2.461 -change, if you decide it was a mistake, you can still do something
   2.462 -about it, though your options may be more limited.
   2.463 -</para>
   2.464 -
   2.465 -<para>For more information about the <command role="hg-cmd">hg revert</command> command, and details
   2.466 -about how to deal with changes you have already committed, see
   2.467 -chapter <xref linkend="chap:undo"/>.
   2.468 -</para>
   2.469 -
   2.470 -</sect1>
   2.471 +<chapter id="chap:daily">
   2.472 +  <?dbhtml filename="mercurial-in-daily-use.html"?>
   2.473 +  <title>Mercurial in daily use</title>
   2.474 +
   2.475 +  <sect1>
   2.476 +    <title>Telling Mercurial which files to track</title>
   2.477 +
   2.478 +    <para id="x_1a3">Mercurial does not work with files in your repository unless
   2.479 +      you tell it to manage them.  The <command role="hg-cmd">hg
   2.480 +	status</command> command will tell you which files Mercurial
   2.481 +      doesn't know about; it uses a
   2.482 +      <quote><literal>?</literal></quote> to display such
   2.483 +      files.</para>
   2.484 +
   2.485 +    <para id="x_1a4">To tell Mercurial to track a file, use the <command
   2.486 +	role="hg-cmd">hg add</command> command.  Once you have added a
   2.487 +      file, the entry in the output of <command role="hg-cmd">hg
   2.488 +	status</command> for that file changes from
   2.489 +      <quote><literal>?</literal></quote> to
   2.490 +      <quote><literal>A</literal></quote>.</para>
   2.491 +
   2.492 +      &interaction.daily.files.add;
   2.493 +
   2.494 +    <para id="x_1a5">After you run a <command role="hg-cmd">hg commit</command>,
   2.495 +      the files that you added before the commit will no longer be
   2.496 +      listed in the output of <command role="hg-cmd">hg
   2.497 +	status</command>.  The reason for this is that by default, <command
   2.498 +	role="hg-cmd">hg status</command> only tells you about
   2.499 +      <quote>interesting</quote> files&emdash;those that you have (for
   2.500 +      example) modified, removed, or renamed.  If you have a repository
   2.501 +      that contains thousands of files, you will rarely want to know
   2.502 +      about files that Mercurial is tracking, but that have not
   2.503 +      changed.  (You can still get this information; we'll return to
   2.504 +      this later.)</para>
   2.505 +
   2.506 +    <para id="x_1a6">Once you add a file, Mercurial doesn't do anything with it
   2.507 +      immediately.  Instead, it will take a snapshot of the file's
   2.508 +      state the next time you perform a commit.  It will then continue
   2.509 +      to track the changes you make to the file every time you commit,
   2.510 +      until you remove the file.</para>
   2.511 +
   2.512 +    <sect2>
   2.513 +      <title>Explicit versus implicit file naming</title>
   2.514 +
   2.515 +      <para id="x_1a7">A useful behavior that Mercurial has is that if you pass
   2.516 +	the name of a directory to a command, every Mercurial command
   2.517 +	will treat this as <quote>I want to operate on every file in
   2.518 +	  this directory and its subdirectories</quote>.</para>
   2.519 +
   2.520 +      &interaction.daily.files.add-dir;
   2.521 +
   2.522 +      <para id="x_1a8">Notice in this example that Mercurial printed
   2.523 +	the names of the files it added, whereas it didn't do so when
   2.524 +	we added the file named <filename>myfile.txt</filename> in the
   2.525 +	earlier example.</para>
   2.526 +
   2.527 +      <para id="x_1a9">What's going on is that in the former case, we explicitly
   2.528 +	named the file to add on the command line.  The assumption
   2.529 +	that Mercurial makes in such cases is that we know what we
   2.530 +	are doing, and it doesn't print any output.</para>
   2.531 +
   2.532 +      <para id="x_1aa">However, when we <emphasis>imply</emphasis> the names of
   2.533 +	files by giving the name of a directory, Mercurial takes the
   2.534 +	extra step of printing the name of each file that it does
   2.535 +	something with.  This makes it more clear what is happening,
   2.536 +	and reduces the likelihood of a silent and nasty surprise.
   2.537 +	This behavior is common to most Mercurial commands.</para>
   2.538 +    </sect2>
   2.539 +
   2.540 +    <sect2>
   2.541 +      <title>Mercurial tracks files, not directories</title>
   2.542 +
   2.543 +      <para id="x_1ab">Mercurial does not track directory information.  Instead,
   2.544 +	it tracks the path to a file.  Before creating a file, it
   2.545 +	first creates any missing directory components of the path.
   2.546 +	After it deletes a file, it then deletes any empty directories
   2.547 +	that were in the deleted file's path.  This sounds like a
   2.548 +	trivial distinction, but it has one minor practical
   2.549 +	consequence: it is not possible to represent a completely
   2.550 +	empty directory in Mercurial.</para>
   2.551 +
   2.552 +      <para id="x_1ac">Empty directories are rarely useful, and there are
   2.553 +	unintrusive workarounds that you can use to achieve an
   2.554 +	appropriate effect.  The developers of Mercurial thus felt
   2.555 +	that the complexity that would be required to manage empty
   2.556 +	directories was not worth the limited benefit this feature
   2.557 +	would bring.</para>
   2.558 +
   2.559 +      <para id="x_1ad">If you need an empty directory in your repository, there
   2.560 +	are a few ways to achieve this. One is to create a directory,
   2.561 +	then <command role="hg-cmd">hg add</command> a
   2.562 +	<quote>hidden</quote> file to that directory.  On Unix-like
   2.563 +	systems, any file name that begins with a period
   2.564 +	(<quote><literal>.</literal></quote>) is treated as hidden by
   2.565 +	most commands and GUI tools.  This approach is illustrated
   2.566 +	below.</para>
   2.567 +
   2.568 +&interaction.daily.files.hidden;
   2.569 +
   2.570 +      <para id="x_1ae">Another way to tackle a need for an empty directory is to
   2.571 +	simply create one in your automated build scripts before they
   2.572 +	will need it.</para>
   2.573 +    </sect2>
   2.574 +  </sect1>
   2.575 +
   2.576 +  <sect1>
   2.577 +    <title>How to stop tracking a file</title>
   2.578 +
   2.579 +    <para id="x_1af">Once you decide that a file no longer belongs in
   2.580 +      your repository, use the <command role="hg-cmd">hg
   2.581 +	remove</command> command. This deletes the file, and tells
   2.582 +      Mercurial to stop tracking it (which will occur at the next
   2.583 +      commit).  A removed file is represented in the output of
   2.584 +      <command role="hg-cmd">hg status</command> with a
   2.585 +      <quote><literal>R</literal></quote>.</para>
   2.586 +
   2.587 +    &interaction.daily.files.remove;
   2.588 +
   2.589 +    <para id="x_1b0">After you <command role="hg-cmd">hg remove</command> a file,
   2.590 +      Mercurial will no longer track changes to that file, even if you
   2.591 +      recreate a file with the same name in your working directory.
   2.592 +      If you do recreate a file with the same name and want Mercurial
   2.593 +      to track the new file, simply <command role="hg-cmd">hg
   2.594 +	add</command> it. Mercurial will know that the newly added
   2.595 +      file is not related to the old file of the same name.</para>
   2.596 +
   2.597 +    <sect2>
   2.598 +      <title>Removing a file does not affect its history</title>
   2.599 +
   2.600 +      <para id="x_1b1">It is important to understand that removing a file has
   2.601 +	only two effects.</para>
   2.602 +      <itemizedlist>
   2.603 +	<listitem><para id="x_1b2">It removes the current version of the file
   2.604 +	    from the working directory.</para>
   2.605 +	</listitem>
   2.606 +	<listitem><para id="x_1b3">It stops Mercurial from tracking changes to
   2.607 +	    the file, from the time of the next commit.</para>
   2.608 +	</listitem></itemizedlist>
   2.609 +      <para id="x_1b4">Removing a file <emphasis>does not</emphasis> in any way
   2.610 +	alter the <emphasis>history</emphasis> of the file.</para>
   2.611 +
   2.612 +      <para id="x_1b5">If you update the working directory to a
   2.613 +	changeset that was committed when it was still tracking a file
   2.614 +	that you later removed, the file will reappear in the working
   2.615 +	directory, with the contents it had when you committed that
   2.616 +	changeset.  If you then update the working directory to a
   2.617 +	later changeset, in which the file had been removed, Mercurial
   2.618 +	will once again remove the file from the working
   2.619 +	directory.</para>
   2.620 +    </sect2>
   2.621 +
   2.622 +    <sect2>
   2.623 +      <title>Missing files</title>
   2.624 +
   2.625 +      <para id="x_1b6">Mercurial considers a file that you have deleted, but not
   2.626 +	used <command role="hg-cmd">hg remove</command> to delete, to
   2.627 +	be <emphasis>missing</emphasis>.  A missing file is
   2.628 +	represented with <quote><literal>!</literal></quote> in the
   2.629 +	output of <command role="hg-cmd">hg status</command>.
   2.630 +	Mercurial commands will not generally do anything with missing
   2.631 +	files.</para>
   2.632 +
   2.633 +      &interaction.daily.files.missing;
   2.634 +
   2.635 +      <para id="x_1b7">If your repository contains a file that <command
   2.636 +	  role="hg-cmd">hg status</command> reports as missing, and
   2.637 +	you want the file to stay gone, you can run <command
   2.638 +	  role="hg-cmd">hg remove <option
   2.639 +	    role="hg-opt-remove">--after</option></command> at any
   2.640 +	time later on, to tell Mercurial that you really did mean to
   2.641 +	remove the file.</para>
   2.642 +
   2.643 +      &interaction.daily.files.remove-after;
   2.644 +
   2.645 +      <para id="x_1b8">On the other hand, if you deleted the missing file by
   2.646 +	accident, give <command role="hg-cmd">hg revert</command> the
   2.647 +	name of the file to recover.  It will reappear, in unmodified
   2.648 +	form.</para>
   2.649 +
   2.650 +      &interaction.daily.files.recover-missing;
   2.651 +    </sect2>
   2.652 +
   2.653 +    <sect2>
   2.654 +      <title>Aside: why tell Mercurial explicitly to remove a
   2.655 +	file?</title>
   2.656 +
   2.657 +      <para id="x_1b9">You might wonder why Mercurial requires you to explicitly
   2.658 +	tell it that you are deleting a file.  Early during the
   2.659 +	development of Mercurial, it let you delete a file however you
   2.660 +	pleased; Mercurial would notice the absence of the file
   2.661 +	automatically when you next ran a <command role="hg-cmd">hg
   2.662 +	  commit</command>, and stop tracking the file.  In practice,
   2.663 +	this made it too easy to accidentally remove a file without
   2.664 +	noticing.</para>
   2.665 +    </sect2>
   2.666 +
   2.667 +    <sect2>
   2.668 +      <title>Useful shorthand&emdash;adding and removing files in one
   2.669 +	step</title>
   2.670 +
   2.671 +      <para id="x_1ba">Mercurial offers a combination command, <command
   2.672 +	  role="hg-cmd">hg addremove</command>, that adds untracked
   2.673 +	files and marks missing files as removed.</para>
   2.674 +
   2.675 +      &interaction.daily.files.addremove;
   2.676 +
   2.677 +      <para id="x_1bb">The <command role="hg-cmd">hg commit</command> command
   2.678 +	also provides a <option role="hg-opt-commit">-A</option>
   2.679 +	option that performs this same add-and-remove, immediately
   2.680 +	followed by a commit.</para>
   2.681 +
   2.682 +      &interaction.daily.files.commit-addremove;
   2.683 +    </sect2>
   2.684 +  </sect1>
   2.685 +
   2.686 +  <sect1 id="chap:daily.copy">
   2.687 +    <title>Copying files</title>
   2.688 +
   2.689 +    <para id="x_1bc">Mercurial provides a <command role="hg-cmd">hg
   2.690 +	copy</command> command that lets you make a new copy of a
   2.691 +      file.  When you copy a file using this command, Mercurial makes
   2.692 +      a record of the fact that the new file is a copy of the original
   2.693 +      file.  It treats these copied files specially when you merge
   2.694 +      your work with someone else's.</para>
   2.695 +
   2.696 +    <sect2>
   2.697 +      <title>The results of copying during a merge</title>
   2.698 +
   2.699 +      <para id="x_1bd">What happens during a merge is that changes
   2.700 +	<quote>follow</quote> a copy.  To best illustrate what this
   2.701 +	means, let's create an example.  We'll start with the usual
   2.702 +	tiny repository that contains a single file.</para>
   2.703 +
   2.704 +      &interaction.daily.copy.init;
   2.705 +
   2.706 +      <para id="x_1be">We need to do some work in
   2.707 +	parallel, so that we'll have something to merge.  So let's
   2.708 +	clone our repository.</para>
   2.709 +
   2.710 +      &interaction.daily.copy.clone;
   2.711 +
   2.712 +      <para id="x_1bf">Back in our initial repository, let's use the <command
   2.713 +	  role="hg-cmd">hg copy</command> command to make a copy of
   2.714 +	the first file we created.</para>
   2.715 +
   2.716 +      &interaction.daily.copy.copy;
   2.717 +
   2.718 +      <para id="x_1c0">If we look at the output of the <command role="hg-cmd">hg
   2.719 +	  status</command> command afterwards, the copied file looks
   2.720 +	just like a normal added file.</para>
   2.721 +
   2.722 +      &interaction.daily.copy.status;
   2.723 +
   2.724 +      <para id="x_1c1">But if we pass the <option
   2.725 +	  role="hg-opt-status">-C</option> option to <command
   2.726 +	  role="hg-cmd">hg status</command>, it prints another line of
   2.727 +	output: this is the file that our newly-added file was copied
   2.728 +	<emphasis>from</emphasis>.</para>
   2.729 +
   2.730 +      &interaction.daily.copy.status-copy;
   2.731 +
   2.732 +      <para id="x_1c2">Now, back in the repository we cloned, let's make a change
   2.733 +	in parallel.  We'll add a line of content to the original file
   2.734 +	that we created.</para>
   2.735 +
   2.736 +      &interaction.daily.copy.other;
   2.737 +
   2.738 +      <para id="x_1c3">Now we have a modified <filename>file</filename> in this
   2.739 +	repository.  When we pull the changes from the first
   2.740 +	repository, and merge the two heads, Mercurial will propagate
   2.741 +	the changes that we made locally to <filename>file</filename>
   2.742 +	into its copy, <filename>new-file</filename>.</para>
   2.743 +
   2.744 +      &interaction.daily.copy.merge;
   2.745 +    </sect2>
   2.746 +
   2.747 +    <sect2 id="sec:daily:why-copy">
   2.748 +      <title>Why should changes follow copies?</title>
   2.749 +
   2.750 +      <para id="x_1c4">This behavior&emdash;of changes to a file
   2.751 +	propagating out to copies of the file&emdash;might seem
   2.752 +	esoteric, but in most cases it's highly desirable.</para>
   2.753 +
   2.754 +      <para id="x_1c5">First of all, remember that this propagation
   2.755 +	<emphasis>only</emphasis> happens when you merge.  So if you
   2.756 +	<command role="hg-cmd">hg copy</command> a file, and
   2.757 +	subsequently modify the original file during the normal course
   2.758 +	of your work, nothing will happen.</para>
   2.759 +
   2.760 +      <para id="x_1c6">The second thing to know is that modifications will only
   2.761 +	propagate across a copy as long as the changeset that you're
   2.762 +	merging changes from <emphasis>hasn't yet seen</emphasis> 
   2.763 +	the copy.</para>
   2.764 +
   2.765 +      <para id="x_1c7">The reason that Mercurial does this is as follows.  Let's
   2.766 +	say I make an important bug fix in a source file, and commit
   2.767 +	my changes. Meanwhile, you've decided to <command
   2.768 +	  role="hg-cmd">hg copy</command> the file in your repository,
   2.769 +	without knowing about the bug or having seen the fix, and you
   2.770 +	have started hacking on your copy of the file.</para>
   2.771 +
   2.772 +      <para id="x_1c8">If you pulled and merged my changes, and Mercurial
   2.773 +	<emphasis>didn't</emphasis> propagate changes across copies,
   2.774 +	your new source file would now contain the bug, and unless you
   2.775 +	knew to propagate the bug fix by hand, the bug would
   2.776 +	<emphasis>remain</emphasis> in your copy of the file.</para>
   2.777 +
   2.778 +      <para id="x_1c9">By automatically propagating the change that fixed the bug
   2.779 +	from the original file to the copy, Mercurial prevents this
   2.780 +	class of problem. To my knowledge, Mercurial is the
   2.781 +	<emphasis>only</emphasis> revision control system that
   2.782 +	propagates changes across copies like this.</para>
   2.783 +
   2.784 +      <para id="x_1ca">Once your change history has a record that the copy and
   2.785 +	subsequent merge occurred, there's usually no further need to
   2.786 +	propagate changes from the original file to the copied file,
   2.787 +	and that's why Mercurial only propagates changes across copies
   2.788 +	at the first merge, and not afterwards.</para>
   2.789 +    </sect2>
   2.790 +
   2.791 +    <sect2>
   2.792 +      <title>How to make changes <emphasis>not</emphasis> follow a
   2.793 +	copy</title>
   2.794 +
   2.795 +      <para id="x_1cb">If, for some reason, you decide that this business of
   2.796 +	automatically propagating changes across copies is not for
   2.797 +	you, simply use your system's normal file copy command (on
   2.798 +	Unix-like systems, that's <command>cp</command>) to make a
   2.799 +	copy of a file, then <command role="hg-cmd">hg add</command>
   2.800 +	the new copy by hand.  Before you do so, though, please do
   2.801 +	reread <xref linkend="sec:daily:why-copy"/>, and make
   2.802 +	an informed
   2.803 +	decision that this behavior is not appropriate to your
   2.804 +	specific case.</para>
   2.805 +
   2.806 +    </sect2>
   2.807 +    <sect2>
   2.808 +      <title>Behavior of the <command role="hg-cmd">hg copy</command>
   2.809 +	command</title>
   2.810 +
   2.811 +      <para id="x_1cc">When you use the <command role="hg-cmd">hg copy</command>
   2.812 +	command, Mercurial makes a copy of each source file as it
   2.813 +	currently stands in the working directory.  This means that if
   2.814 +	you make some modifications to a file, then <command
   2.815 +	  role="hg-cmd">hg copy</command> it without first having
   2.816 +	committed those changes, the new copy will also contain the
   2.817 +	modifications you have made up until that point.  (I find this
   2.818 +	behavior a little counterintuitive, which is why I mention it
   2.819 +	here.)</para>
   2.820 +
   2.821 +      <para id="x_1cd">The <command role="hg-cmd">hg copy</command>
   2.822 +	command acts similarly to the Unix <command>cp</command>
   2.823 +	command (you can use the <command role="hg-cmd">hg
   2.824 +	  cp</command> alias if you prefer).  We must supply two or
   2.825 +	more arguments, of which the last is treated as the
   2.826 +	<emphasis>destination</emphasis>, and all others are
   2.827 +	<emphasis>sources</emphasis>.</para>
   2.828 +
   2.829 +      <para id="x_685">If you pass <command role="hg-cmd">hg copy</command> a
   2.830 +	single file as the source, and the destination does not exist,
   2.831 +	it creates a new file with that name.</para>
   2.832 +
   2.833 +      &interaction.daily.copy.simple;
   2.834 +      
   2.835 +      <para id="x_1ce">If the destination is a directory, Mercurial copies its
   2.836 +	sources into that directory.</para>
   2.837 +
   2.838 +      &interaction.daily.copy.dir-dest;
   2.839 +
   2.840 +      <para id="x_1cf">Copying a directory is
   2.841 +	recursive, and preserves the directory structure of the
   2.842 +	source.</para>
   2.843 +
   2.844 +      &interaction.daily.copy.dir-src;
   2.845 +
   2.846 +      <para id="x_1d0">If the source and destination are both directories, the
   2.847 +	source tree is recreated in the destination directory.</para>
   2.848 +
   2.849 +	&interaction.daily.copy.dir-src-dest;
   2.850 +
   2.851 +      <para id="x_1d1">As with the <command role="hg-cmd">hg remove</command>
   2.852 +	command, if you copy a file manually and then want Mercurial
   2.853 +	to know that you've copied the file, simply use the <option
   2.854 +	  role="hg-opt-copy">--after</option> option to <command
   2.855 +	  role="hg-cmd">hg copy</command>.</para>
   2.856 +
   2.857 +      &interaction.daily.copy.after;
   2.858 +    </sect2>
   2.859 +  </sect1>
   2.860 +
   2.861 +  <sect1>
   2.862 +    <title>Renaming files</title>
   2.863 +
   2.864 +    <para id="x_1d2">It's rather more common to need to rename a file than to
   2.865 +      make a copy of it.  The reason I discussed the <command
   2.866 +	role="hg-cmd">hg copy</command> command before talking about
   2.867 +      renaming files is that Mercurial treats a rename in essentially
   2.868 +      the same way as a copy.  Therefore, knowing what Mercurial does
   2.869 +      when you copy a file tells you what to expect when you rename a
   2.870 +      file.</para>
   2.871 +
   2.872 +    <para id="x_1d3">When you use the <command role="hg-cmd">hg rename</command>
   2.873 +      command, Mercurial makes a copy of each source file, then
   2.874 +      deletes it and marks the file as removed.</para>
   2.875 +
   2.876 +      &interaction.daily.rename.rename;
   2.877 +
   2.878 +    <para id="x_1d4">The <command role="hg-cmd">hg status</command> command shows
   2.879 +      the newly copied file as added, and the copied-from file as
   2.880 +      removed.</para>
   2.881 +
   2.882 +    &interaction.daily.rename.status;
   2.883 +
   2.884 +    <para id="x_1d5">As with the results of a <command role="hg-cmd">hg
   2.885 +	copy</command>, we must use the <option
   2.886 +	role="hg-opt-status">-C</option> option to <command
   2.887 +	role="hg-cmd">hg status</command> to see that the added file
   2.888 +      is really being tracked by Mercurial as a copy of the original,
   2.889 +      now removed, file.</para>
   2.890 +
   2.891 +    &interaction.daily.rename.status-copy;
   2.892 +
   2.893 +    <para id="x_1d6">As with <command role="hg-cmd">hg remove</command> and
   2.894 +      <command role="hg-cmd">hg copy</command>, you can tell Mercurial
   2.895 +      about a rename after the fact using the <option
   2.896 +	role="hg-opt-rename">--after</option> option.  In most other
   2.897 +      respects, the behavior of the <command role="hg-cmd">hg
   2.898 +	rename</command> command, and the options it accepts, are
   2.899 +      similar to the <command role="hg-cmd">hg copy</command>
   2.900 +      command.</para>
   2.901 +
   2.902 +    <para id="x_686">If you're familiar with the Unix command line, you'll be
   2.903 +      glad to know that <command role="hg-cmd">hg rename</command>
   2.904 +      command can be invoked as <command role="hg-cmd">hg
   2.905 +	mv</command>.</para>
   2.906 +
   2.907 +    <sect2>
   2.908 +      <title>Renaming files and merging changes</title>
   2.909 +
   2.910 +      <para id="x_1d7">Since Mercurial's rename is implemented as
   2.911 +	copy-and-remove, the same propagation of changes happens when
   2.912 +	you merge after a rename as after a copy.</para>
   2.913 +
   2.914 +      <para id="x_1d8">If I modify a file, and you rename it to a new name, and
   2.915 +	then we merge our respective changes, my modifications to the
   2.916 +	file under its original name will be propagated into the file
   2.917 +	under its new name. (This is something you might expect to
   2.918 +	<quote>simply work,</quote> but not all revision control
   2.919 +	systems actually do this.)</para>
   2.920 +
   2.921 +      <para id="x_1d9">Whereas having changes follow a copy is a feature where
   2.922 +	you can perhaps nod and say <quote>yes, that might be
   2.923 +	  useful,</quote> it should be clear that having them follow a
   2.924 +	rename is definitely important.  Without this facility, it
   2.925 +	would simply be too easy for changes to become orphaned when
   2.926 +	files are renamed.</para>
   2.927 +    </sect2>
   2.928 +
   2.929 +    <sect2>
   2.930 +      <title>Divergent renames and merging</title>
   2.931 +
   2.932 +      <para id="x_1da">The case of diverging names occurs when two developers
   2.933 +	start with a file&emdash;let's call it
   2.934 +	<filename>foo</filename>&emdash;in their respective
   2.935 +	repositories.</para>
   2.936 +
   2.937 +      &interaction.rename.divergent.clone;
   2.938 +
   2.939 +      <para id="x_1db">Anne renames the file to <filename>bar</filename>.</para>
   2.940 +
   2.941 +      &interaction.rename.divergent.rename.anne;
   2.942 +
   2.943 +      <para id="x_1dc">Meanwhile, Bob renames it to
   2.944 +	<filename>quux</filename>. (Remember that <command
   2.945 +	  role="hg-cmd">hg mv</command> is an alias for <command
   2.946 +	  role="hg-cmd">hg rename</command>.)</para>
   2.947 +
   2.948 +	&interaction.rename.divergent.rename.bob;
   2.949 +
   2.950 +      <para id="x_1dd">I like to think of this as a conflict because each
   2.951 +	developer has expressed different intentions about what the
   2.952 +	file ought to be named.</para>
   2.953 +
   2.954 +      <para id="x_1de">What do you think should happen when they merge their
   2.955 +	work? Mercurial's actual behavior is that it always preserves
   2.956 +	<emphasis>both</emphasis> names when it merges changesets that
   2.957 +	contain divergent renames.</para>
   2.958 +
   2.959 +      &interaction.rename.divergent.merge;
   2.960 +
   2.961 +      <para id="x_1df">Notice that while Mercurial warns about the divergent
   2.962 +	renames, it leaves it up to you to do something about the
   2.963 +	divergence after the merge.</para>
   2.964 +    </sect2>
   2.965 +
   2.966 +    <sect2>
   2.967 +      <title>Convergent renames and merging</title>
   2.968 +
   2.969 +      <para id="x_1e0">Another kind of rename conflict occurs when two people
   2.970 +	choose to rename different <emphasis>source</emphasis> files
   2.971 +	to the same <emphasis>destination</emphasis>. In this case,
   2.972 +	Mercurial runs its normal merge machinery, and lets you guide
   2.973 +	it to a suitable resolution.</para>
   2.974 +    </sect2>
   2.975 +
   2.976 +    <sect2>
   2.977 +      <title>Other name-related corner cases</title>
   2.978 +
   2.979 +      <para id="x_1e1">Mercurial has a longstanding bug in which it fails to
   2.980 +	handle a merge where one side has a file with a given name,
   2.981 +	while another has a directory with the same name.  This is
   2.982 +	documented as <ulink role="hg-bug"
   2.983 +	  url="http://www.selenic.com/mercurial/bts/issue29">issue
   2.984 +	  29</ulink>.</para>
   2.985 +
   2.986 +      &interaction.issue29.go;
   2.987 +
   2.988 +    </sect2>
   2.989 +  </sect1>
   2.990 +
   2.991 +  <sect1>
   2.992 +    <title>Recovering from mistakes</title>
   2.993 +
   2.994 +    <para id="x_1e2">Mercurial has some useful commands that will help you to
   2.995 +      recover from some common mistakes.</para>
   2.996 +
   2.997 +    <para id="x_1e3">The <command role="hg-cmd">hg revert</command> command lets
   2.998 +      you undo changes that you have made to your working directory.
   2.999 +      For example, if you <command role="hg-cmd">hg add</command> a
  2.1000 +      file by accident, just run <command role="hg-cmd">hg
  2.1001 +	revert</command> with the name of the file you added, and
  2.1002 +      while the file won't be touched in any way, it won't be tracked
  2.1003 +      for adding by Mercurial any longer, either.  You can also use
  2.1004 +      <command role="hg-cmd">hg revert</command> to get rid of
  2.1005 +      erroneous changes to a file.</para>
  2.1006 +
  2.1007 +    <para id="x_1e4">It is helpful to remember that the <command
  2.1008 +	role="hg-cmd">hg revert</command> command is useful for
  2.1009 +      changes that you have not yet committed.  Once you've committed
  2.1010 +      a change, if you decide it was a mistake, you can still do
  2.1011 +      something about it, though your options may be more
  2.1012 +      limited.</para>
  2.1013 +
  2.1014 +    <para id="x_1e5">For more information about the <command
  2.1015 +	role="hg-cmd">hg revert</command> command, and details about
  2.1016 +      how to deal with changes you have already committed, see <xref
  2.1017 +	linkend="chap:undo"/>.</para>
  2.1018 +  </sect1>
  2.1019 +
  2.1020 +  <sect1>
  2.1021 +    <title>Dealing with tricky merges</title>
  2.1022 +
  2.1023 +    <para id="x_687">In a complicated or large project, it's not unusual for a
  2.1024 +      merge of two changesets to result in some headaches.  Suppose
  2.1025 +      there's a big source file that's been extensively edited by each
  2.1026 +      side of a merge: this is almost inevitably going to result in
  2.1027 +      conflicts, some of which can take a few tries to sort
  2.1028 +      out.</para>
  2.1029 +
  2.1030 +    <para id="x_688">Let's develop a simple case of this and see how to deal with
  2.1031 +      it.  We'll start off with a repository containing one file, and
  2.1032 +      clone it twice.</para>
  2.1033 +
  2.1034 +    &interaction.ch04-resolve.init;
  2.1035 +
  2.1036 +    <para id="x_689">In one clone, we'll modify the file in one way.</para>
  2.1037 +
  2.1038 +    &interaction.ch04-resolve.left;
  2.1039 +
  2.1040 +    <para id="x_68a">In another, we'll modify the file differently.</para>
  2.1041 +
  2.1042 +    &interaction.ch04-resolve.right;
  2.1043 +
  2.1044 +    <para id="x_68b">Next, we'll pull each set of changes into our original
  2.1045 +      repo.</para>
  2.1046 +
  2.1047 +    &interaction.ch04-resolve.pull;
  2.1048 +
  2.1049 +    <para id="x_68c">We expect our repository to now contain two heads.</para>
  2.1050 +
  2.1051 +    &interaction.ch04-resolve.heads;
  2.1052 +
  2.1053 +    <para id="x_68d">Normally, if we run <command role="hg-cmd">hg
  2.1054 +	merge</command> at this point, it will drop us into a GUI that
  2.1055 +      will let us manually resolve the conflicting edits to
  2.1056 +      <filename>myfile.txt</filename>.  However, to simplify things
  2.1057 +      for presentation here, we'd like the merge to fail immediately
  2.1058 +      instead.  Here's one way we can do so.</para>
  2.1059 +
  2.1060 +    &interaction.ch04-resolve.export;
  2.1061 +
  2.1062 +    <para id="x_68e">We've told Mercurial's merge machinery to run the command
  2.1063 +      <command>false</command> (which, as we desire, fails
  2.1064 +      immediately) if it detects a merge that it can't sort out
  2.1065 +      automatically.</para>
  2.1066 +
  2.1067 +    <para id="x_68f">If we now fire up <command role="hg-cmd">hg
  2.1068 +	merge</command>, it should grind to a halt and report a
  2.1069 +	failure.</para>
  2.1070 +
  2.1071 +    &interaction.ch04-resolve.merge;
  2.1072 +
  2.1073 +    <para id="x_690">Even if we don't notice that the merge failed, Mercurial
  2.1074 +      will prevent us from accidentally committing the result of a
  2.1075 +      failed merge.</para>
  2.1076 +
  2.1077 +    &interaction.ch04-resolve.cifail;
  2.1078 +
  2.1079 +    <para id="x_691">When <command role="hg-cmd">hg commit</command> fails in
  2.1080 +      this case, it suggests that we use the unfamiliar <command
  2.1081 +	role="hg-cmd">hg resolve</command> command.  As usual,
  2.1082 +	<command role="hg-cmd">hg help resolve</command> will print a
  2.1083 +      helpful synopsis.</para>
  2.1084 +
  2.1085 +    <sect2>
  2.1086 +      <title>File resolution states</title>
  2.1087 +
  2.1088 +      <para id="x_692">When a merge occurs, most files will usually remain
  2.1089 +	unmodified.  For each file where Mercurial has to do
  2.1090 +	something, it tracks the state of the file.</para>
  2.1091 +
  2.1092 +      <itemizedlist>
  2.1093 +	<listitem>
  2.1094 +	  <para id="x_693">A <emphasis>resolved</emphasis> file has been
  2.1095 +	    successfully merged, either automatically by Mercurial or
  2.1096 +	    manually with human intervention.</para>
  2.1097 +	</listitem>
  2.1098 +	<listitem>
  2.1099 +	  <para id="x_694">An <emphasis>unresolved</emphasis> file was not merged
  2.1100 +	    successfully, and needs more attention.</para>
  2.1101 +	</listitem>
  2.1102 +      </itemizedlist>
  2.1103 +
  2.1104 +      <para id="x_695">If Mercurial sees <emphasis>any</emphasis> file in the
  2.1105 +	unresolved state after a merge, it considers the merge to have
  2.1106 +	failed.  Fortunately, we do not need to restart the entire
  2.1107 +	merge from scratch.</para>
  2.1108 +
  2.1109 +      <para id="x_696">The <option role="hg-opt-resolve">--list</option> or
  2.1110 +	<option role="hg-opt-resolve">-l</option> option to <command
  2.1111 +	  role="hg-cmd">hg resolve</command> prints out the state of
  2.1112 +	each merged file.</para>
  2.1113 +
  2.1114 +      &interaction.ch04-resolve.list;
  2.1115 +
  2.1116 +      <para id="x_697">In the output from <command role="hg-cmd">hg
  2.1117 +	  resolve</command>, a resolved file is marked with
  2.1118 +	<literal>R</literal>, while an unresolved file is marked with
  2.1119 +	<literal>U</literal>.  If any files are listed with
  2.1120 +	<literal>U</literal>, we know that an attempt to commit the
  2.1121 +	results of the merge will fail.</para>
  2.1122 +    </sect2>
  2.1123 +
  2.1124 +    <sect2>
  2.1125 +      <title>Resolving a file merge</title>
  2.1126 +
  2.1127 +      <para id="x_698">We have several options to move a file from the unresolved
  2.1128 +	into the resolved state.  By far the most common is to rerun
  2.1129 +	<command role="hg-cmd">hg resolve</command>.  If we pass the
  2.1130 +	names of individual files or directories, it will retry the
  2.1131 +	merges of any unresolved files present in those locations. We
  2.1132 +	can also pass the <option role="hg-opt-resolve">--all</option>
  2.1133 +	or <option role="hg-opt-resolve">-a</option> option, which
  2.1134 +	will retry the merges of <emphasis>all</emphasis> unresolved
  2.1135 +	files.</para>
  2.1136 +
  2.1137 +      <para id="x_699">Mercurial also lets us modify the resolution state of a
  2.1138 +	file directly.  We can manually mark a file as resolved using
  2.1139 +	the <option role="hg-opt-resolve">--mark</option> option, or
  2.1140 +	as unresolved using the <option
  2.1141 +	  role="hg-opt-resolve">--unmark</option> option.  This allows
  2.1142 +	us to clean up a particularly messy merge by hand, and to keep
  2.1143 +	track of our progress with each file as we go.</para>
  2.1144 +    </sect2>
  2.1145 +  </sect1>
  2.1146 +
  2.1147 +  <sect1>
  2.1148 +    <title>More useful diffs</title>
  2.1149 +
  2.1150 +    <para id="x_6c7">The default output of the <command role="hg-cmd">hg
  2.1151 +	diff</command> command is backwards compatible with the
  2.1152 +      regular <command>diff</command> command, but this has some
  2.1153 +      drawbacks.</para>
  2.1154 +
  2.1155 +    <para id="x_6c8">Consider the case where we use <command role="hg-cmd">hg
  2.1156 +	rename</command> to rename a file.</para>
  2.1157 +
  2.1158 +    &interaction.ch04-diff.rename.basic;
  2.1159 +
  2.1160 +    <para id="x_6c9">The output of <command role="hg-cmd">hg diff</command> above
  2.1161 +      obscures the fact that we simply renamed a file.  The <command
  2.1162 +	role="hg-cmd">hg diff</command> command accepts an option,
  2.1163 +      <option>--git</option> or <option>-g</option>, to use a newer
  2.1164 +      diff format that displays such information in a more readable
  2.1165 +      form.</para>
  2.1166 +
  2.1167 +    &interaction.ch04-diff.rename.git;
  2.1168 +
  2.1169 +    <para id="x_6ca">This option also helps with a case that can otherwise be
  2.1170 +      confusing: a file that appears to be modified according to
  2.1171 +      <command role="hg-cmd">hg status</command>, but for which
  2.1172 +      <command role="hg-cmd">hg diff</command> prints nothing. This
  2.1173 +      situation can arise if we change the file's execute
  2.1174 +      permissions.</para>
  2.1175 +
  2.1176 +    &interaction.ch04-diff.chmod;
  2.1177 +
  2.1178 +    <para id="x_6cb">The normal <command>diff</command> command pays no attention
  2.1179 +      to file permissions, which is why <command role="hg-cmd">hg
  2.1180 +	diff</command> prints nothing by default.  If we supply it
  2.1181 +      with the <option>-g</option> option, it tells us what really
  2.1182 +      happened.</para>
  2.1183 +
  2.1184 +    &interaction.ch04-diff.chmod.git;
  2.1185 +  </sect1>
  2.1186 +
  2.1187 +  <sect1>
  2.1188 +    <title>Which files to manage, and which to avoid</title>
  2.1189 +
  2.1190 +    <para id="x_6cc">Revision control systems are generally best at managing text
  2.1191 +      files that are written by humans, such as source code, where the
  2.1192 +      files do not change much from one revision to the next.  Some
  2.1193 +      centralized revision control systems can also deal tolerably
  2.1194 +      well with binary files, such as bitmap images.</para>
  2.1195 +
  2.1196 +    <para id="x_6cd">For instance, a game development team will typically manage
  2.1197 +      both its source code and all of its binary assets (e.g. geometry
  2.1198 +      data, textures, map layouts) in a revision control
  2.1199 +      system.</para>
  2.1200 +
  2.1201 +    <para id="x_6ce">Because it is usually impossible to merge two conflicting
  2.1202 +      modifications to a binary file, centralized systems often
  2.1203 +      provide a file locking mechanism that allow a user to say
  2.1204 +      <quote>I am the only person who can edit this
  2.1205 +	file</quote>.</para>
  2.1206 +
  2.1207 +    <para id="x_6cf">Compared to a centralized system, a distributed revision
  2.1208 +      control system changes some of the factors that guide decisions
  2.1209 +      over which files to manage and how.</para>
  2.1210 +
  2.1211 +    <para id="x_6d0">For instance, a distributed revision control system cannot,
  2.1212 +      by its nature, offer a file locking facility.  There is thus no
  2.1213 +      built-in mechanism to prevent two people from making conflicting
  2.1214 +      changes to a binary file.  If you have a team where several
  2.1215 +      people may be editing binary files frequently, it may not be a
  2.1216 +      good idea to use Mercurial&emdash;or any other distributed
  2.1217 +      revision control system&emdash;to manage those files.</para>
  2.1218 +
  2.1219 +    <para id="x_6d1">When storing modifications to a file, Mercurial usually
  2.1220 +      saves only the differences between the previous and current
  2.1221 +      versions of the file.  For most text files, this is extremely
  2.1222 +      efficient. However, some files (particularly binary files) are
  2.1223 +      laid out in such a way that even a small change to a file's
  2.1224 +      logical content results in many or most of the bytes inside the
  2.1225 +      file changing.  For instance, compressed files are particularly
  2.1226 +      susceptible to this. If the differences between each successive
  2.1227 +      version of a file are always large, Mercurial will not be able
  2.1228 +      to store the file's revision history very efficiently.  This can
  2.1229 +      affect both local storage needs and the amount of time it takes
  2.1230 +      to clone a repository.</para>
  2.1231 +
  2.1232 +    <para id="x_6d2">To get an idea of how this could affect you in practice,
  2.1233 +      suppose you want to use Mercurial to manage an OpenOffice
  2.1234 +      document.  OpenOffice stores documents on disk as compressed zip
  2.1235 +      files. Edit even a single letter of your document in OpenOffice,
  2.1236 +      and almost every byte in the entire file will change when you
  2.1237 +      save it. Now suppose that file is 2MB in size.  Because most of
  2.1238 +      the file changes every time you save, Mercurial will have to
  2.1239 +      store all 2MB of the file every time you commit, even though
  2.1240 +      from your perspective, perhaps only a few words are changing
  2.1241 +      each time.  A single frequently-edited file that is not friendly
  2.1242 +      to Mercurial's storage assumptions can easily have an outsized
  2.1243 +      effect on the size of the repository.</para>
  2.1244 +
  2.1245 +    <para id="x_6d3">Even worse, if both you and someone else edit the OpenOffice
  2.1246 +      document you're working on, there is no useful way to merge your
  2.1247 +      work. In fact, there isn't even a good way to tell what the
  2.1248 +      differences are between your respective changes.</para>
  2.1249 +
  2.1250 +    <para id="x_6d4">There are thus a few clear recommendations about specific
  2.1251 +      kinds of files to be very careful with.</para>
  2.1252 +
  2.1253 +    <itemizedlist>
  2.1254 +      <listitem>
  2.1255 +	<para id="x_6d5">Files that are very large and incompressible, e.g. ISO
  2.1256 +	  CD-ROM images, will by virtue of sheer size make clones over
  2.1257 +	  a network very slow.</para>
  2.1258 +      </listitem>
  2.1259 +      <listitem>
  2.1260 +	<para id="x_6d6">Files that change a lot from one revision to the next
  2.1261 +	  may be expensive to store if you edit them frequently, and
  2.1262 +	  conflicts due to concurrent edits may be difficult to
  2.1263 +	  resolve.</para>
  2.1264 +      </listitem>
  2.1265 +    </itemizedlist>
  2.1266 +  </sect1>
  2.1267 +
  2.1268 +  <sect1>
  2.1269 +    <title>Backups and mirroring</title>
  2.1270 +
  2.1271 +    <para id="x_6d7">Since Mercurial maintains a complete copy of history in each
  2.1272 +      clone, everyone who uses Mercurial to collaborate on a project
  2.1273 +      can potentially act as a source of backups in the event of a
  2.1274 +      catastrophe.  If a central repository becomes unavailable, you
  2.1275 +      can construct a replacement simply by cloning a copy of the
  2.1276 +      repository from one contributor, and pulling any changes they
  2.1277 +      may not have seen from others.</para>
  2.1278 +
  2.1279 +    <para id="x_6d8">It is simple to use Mercurial to perform off-site backups
  2.1280 +      and remote mirrors.  Set up a periodic job (e.g. via the
  2.1281 +      <command>cron</command> command) on a remote server to pull
  2.1282 +      changes from your master repositories every hour.  This will
  2.1283 +      only be tricky in the unlikely case that the number of master
  2.1284 +      repositories you maintain changes frequently, in which case
  2.1285 +      you'll need to do a little scripting to refresh the list of
  2.1286 +      repositories to back up.</para>
  2.1287 +
  2.1288 +    <para id="x_6d9">If you perform traditional backups of your master
  2.1289 +      repositories to tape or disk, and you want to back up a
  2.1290 +      repository named <filename>myrepo</filename>, use <command>hg
  2.1291 +	clone -U myrepo myrepo.bak</command> to create a
  2.1292 +      clone of <filename>myrepo</filename> before you start your
  2.1293 +      backups.  The <option>-U</option> option doesn't check out a
  2.1294 +      working directory after the clone completes, since that would be
  2.1295 +      superfluous and make the backup take longer.</para>
  2.1296 +
  2.1297 +    <para id="x_6da">If you then back up <filename>myrepo.bak</filename> instead
  2.1298 +      of <filename>myrepo</filename>, you will be guaranteed to have a
  2.1299 +      consistent snapshot of your repository that won't be pushed to
  2.1300 +      by an insomniac developer in mid-backup.</para>
  2.1301 +  </sect1>
  2.1302  </chapter>
  2.1303  
  2.1304  <!--
  2.1305  local variables: 
  2.1306  sgml-parent-document: ("00book.xml" "book" "chapter")
  2.1307  end:
  2.1308 --->
  2.1309 \ No newline at end of file
  2.1310 +-->

     3.1 --- a/fr/ch06-collab.xml	Wed Sep 09 15:25:09 2009 +0200
     3.2 +++ b/fr/ch06-collab.xml	Wed Sep 09 16:07:36 2009 +0200
     3.3 @@ -1,1405 +1,1565 @@
     3.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     3.5  
     3.6 -<chapter>
     3.7 -<title>Collaborating with other people</title>
     3.8 -<para>\label{cha:collab}</para>
     3.9 -
    3.10 -<para>As a completely decentralised tool, Mercurial doesn't impose any
    3.11 -policy on how people ought to work with each other.  However, if
    3.12 -you're new to distributed revision control, it helps to have some
    3.13 -tools and examples in mind when you're thinking about possible
    3.14 -workflow models.</para>
    3.15 -
    3.16 -<sect1>
    3.17 -<title>Mercurial's web interface</title>
    3.18 -
    3.19 -<para>Mercurial has a powerful web interface that provides several
    3.20 -useful capabilities.</para>
    3.21 -
    3.22 -<para>For interactive use, the web interface lets you browse a single
    3.23 -repository or a collection of repositories.  You can view the history
    3.24 -of a repository, examine each change (comments and diffs), and view
    3.25 -the contents of each directory and file.</para>
    3.26 -
    3.27 -<para>Also for human consumption, the web interface provides an RSS feed of
    3.28 -the changes in a repository.  This lets you <quote>subscribe</quote> to a
    3.29 -repository using your favourite feed reader, and be automatically
    3.30 -notified of activity in that repository as soon as it happens.  I find
    3.31 -this capability much more convenient than the model of subscribing to
    3.32 -a mailing list to which notifications are sent, as it requires no
    3.33 -additional configuration on the part of whoever is serving the
    3.34 -repository.</para>
    3.35 -
    3.36 -<para>The web interface also lets remote users clone a repository, pull
    3.37 -changes from it, and (when the server is configured to permit it) push
    3.38 -changes back to it.  Mercurial's HTTP tunneling protocol aggressively
    3.39 -compresses data, so that it works efficiently even over low-bandwidth
    3.40 -network connections.</para>
    3.41 -
    3.42 -<para>The easiest way to get started with the web interface is to use your
    3.43 -web browser to visit an existing repository, such as the master
    3.44 -Mercurial repository at
    3.45 -<ulink url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para>
    3.46 -
    3.47 -<para>If you're interested in providing a web interface to your own
    3.48 -repositories, Mercurial provides two ways to do this.  The first is
    3.49 -using the <command role="hg-cmd">hg serve</command> command, which is best suited to short-term
    3.50 -<quote>lightweight</quote> serving.  See section <xref linkend="sec:collab:serve"/> below for
    3.51 -details of how to use this command.  If you have a long-lived
    3.52 -repository that you'd like to make permanently available, Mercurial
    3.53 -has built-in support for the CGI (Common Gateway Interface) standard,
    3.54 -which all common web servers support.  See
    3.55 -section <xref linkend="sec:collab:cgi"/> for details of CGI configuration.</para>
    3.56 -
    3.57 -</sect1>
    3.58 -<sect1>
    3.59 -<title>Collaboration models</title>
    3.60 -
    3.61 -<para>With a suitably flexible tool, making decisions about workflow is much
    3.62 -more of a social engineering challenge than a technical one.
    3.63 -Mercurial imposes few limitations on how you can structure the flow of
    3.64 -work in a project, so it's up to you and your group to set up and live
    3.65 -with a model that matches your own particular needs.
    3.66 -</para>
    3.67 -
    3.68 -<sect2>
    3.69 -<title>Factors to keep in mind</title>
    3.70 -
    3.71 -<para>The most important aspect of any model that you must keep in mind is
    3.72 -how well it matches the needs and capabilities of the people who will
    3.73 -be using it.  This might seem self-evident; even so, you still can't
    3.74 -afford to forget it for a moment.
    3.75 -</para>
    3.76 -
    3.77 -<para>I once put together a workflow model that seemed to make perfect sense
    3.78 -to me, but that caused a considerable amount of consternation and
    3.79 -strife within my development team.  In spite of my attempts to explain
    3.80 -why we needed a complex set of branches, and how changes ought to flow
    3.81 -between them, a few team members revolted.  Even though they were
    3.82 -smart people, they didn't want to pay attention to the constraints we
    3.83 -were operating under, or face the consequences of those constraints in
    3.84 -the details of the model that I was advocating.
    3.85 -</para>
    3.86 -
    3.87 -<para>Don't sweep foreseeable social or technical problems under the rug.
    3.88 -Whatever scheme you put into effect, you should plan for mistakes and
    3.89 -problem scenarios.  Consider adding automated machinery to prevent, or
    3.90 -quickly recover from, trouble that you can anticipate.  As an example,
    3.91 -if you intend to have a branch with not-for-release changes in it,
    3.92 -you'd do well to think early about the possibility that someone might
    3.93 -accidentally merge those changes into a release branch.  You could
    3.94 -avoid this particular problem by writing a hook that prevents changes
    3.95 -from being merged from an inappropriate branch.
    3.96 -</para>
    3.97 -
    3.98 -</sect2>
    3.99 -<sect2>
   3.100 -<title>Informal anarchy</title>
   3.101 -
   3.102 -<para>I wouldn't suggest an <quote>anything goes</quote> approach as something
   3.103 -sustainable, but it's a model that's easy to grasp, and it works
   3.104 -perfectly well in a few unusual situations.
   3.105 -</para>
   3.106 -
   3.107 -<para>As one example, many projects have a loose-knit group of collaborators
   3.108 -who rarely physically meet each other.  Some groups like to overcome
   3.109 -the isolation of working at a distance by organising occasional
   3.110 -<quote>sprints</quote>.  In a sprint, a number of people get together in a single
   3.111 -location (a company's conference room, a hotel meeting room, that kind
   3.112 -of place) and spend several days more or less locked in there, hacking
   3.113 -intensely on a handful of projects.
   3.114 -</para>
   3.115 -
   3.116 -<para>A sprint is the perfect place to use the <command role="hg-cmd">hg serve</command> command, since
   3.117 -<command role="hg-cmd">hg serve</command> does not requires any fancy server infrastructure.  You
   3.118 -can get started with <command role="hg-cmd">hg serve</command> in moments, by reading
   3.119 -section <xref linkend="sec:collab:serve"/> below.  Then simply tell the person
   3.120 -next to you that you're running a server, send the URL to them in an
   3.121 -instant message, and you immediately have a quick-turnaround way to
   3.122 -work together.  They can type your URL into their web browser and
   3.123 -quickly review your changes; or they can pull a bugfix from you and
   3.124 -verify it; or they can clone a branch containing a new feature and try
   3.125 -it out.
   3.126 -</para>
   3.127 -
   3.128 -<para>The charm, and the problem, with doing things in an ad hoc fashion
   3.129 -like this is that only people who know about your changes, and where
   3.130 -they are, can see them.  Such an informal approach simply doesn't
   3.131 -scale beyond a handful people, because each individual needs to know
   3.132 -about $n$ different repositories to pull from.
   3.133 -</para>
   3.134 -
   3.135 -</sect2>
   3.136 -<sect2>
   3.137 -<title>A single central repository</title>
   3.138 -
   3.139 -<para>For smaller projects migrating from a centralised revision control
   3.140 -tool, perhaps the easiest way to get started is to have changes flow
   3.141 -through a single shared central repository.  This is also the
   3.142 -most common <quote>building block</quote> for more ambitious workflow schemes.
   3.143 -</para>
   3.144 -
   3.145 -<para>Contributors start by cloning a copy of this repository.  They can
   3.146 -pull changes from it whenever they need to, and some (perhaps all)
   3.147 -developers have permission to push a change back when they're ready
   3.148 -for other people to see it.
   3.149 -</para>
   3.150 -
   3.151 -<para>Under this model, it can still often make sense for people to pull
   3.152 -changes directly from each other, without going through the central
   3.153 -repository.  Consider a case in which I have a tentative bug fix, but
   3.154 -I am worried that if I were to publish it to the central repository,
   3.155 -it might subsequently break everyone else's trees as they pull it.  To
   3.156 -reduce the potential for damage, I can ask you to clone my repository
   3.157 -into a temporary repository of your own and test it.  This lets us put
   3.158 -off publishing the potentially unsafe change until it has had a little
   3.159 -testing.
   3.160 -</para>
   3.161 -
   3.162 -<para>In this kind of scenario, people usually use the <command>ssh</command>
   3.163 -protocol to securely push changes to the central repository, as
   3.164 -documented in section <xref linkend="sec:collab:ssh"/>.  It's also usual to
   3.165 -publish a read-only copy of the repository over HTTP using CGI, as in
   3.166 -section <xref linkend="sec:collab:cgi"/>.  Publishing over HTTP satisfies the
   3.167 -needs of people who don't have push access, and those who want to use
   3.168 -web browsers to browse the repository's history.
   3.169 -</para>
   3.170 -
   3.171 -</sect2>
   3.172 -<sect2>
   3.173 -<title>Working with multiple branches</title>
   3.174 -
   3.175 -<para>Projects of any significant size naturally tend to make progress on
   3.176 -several fronts simultaneously.  In the case of software, it's common
   3.177 -for a project to go through periodic official releases.  A release
   3.178 -might then go into <quote>maintenance mode</quote> for a while after its first
   3.179 -publication; maintenance releases tend to contain only bug fixes, not
   3.180 -new features.  In parallel with these maintenance releases, one or
   3.181 -more future releases may be under development.  People normally use
   3.182 -the word <quote>branch</quote> to refer to one of these many slightly different
   3.183 -directions in which development is proceeding.
   3.184 -</para>
   3.185 -
   3.186 -<para>Mercurial is particularly well suited to managing a number of
   3.187 -simultaneous, but not identical, branches.  Each <quote>development
   3.188 -direction</quote> can live in its own central repository, and you can merge
   3.189 -changes from one to another as the need arises.  Because repositories
   3.190 -are independent of each other, unstable changes in a development
   3.191 -branch will never affect a stable branch unless someone explicitly
   3.192 -merges those changes in.
   3.193 -</para>
   3.194 -
   3.195 -<para>Here's an example of how this can work in practice.  Let's say you
   3.196 -have one <quote>main branch</quote> on a central server.
   3.197 -<!-- &interaction.branching.init; -->
   3.198 -People clone it, make changes locally, test them, and push them back.
   3.199 -</para>
   3.200 -
   3.201 -<para>Once the main branch reaches a release milestone, you can use the
   3.202 -<command role="hg-cmd">hg tag</command> command to give a permanent name to the milestone
   3.203 -revision.
   3.204 -<!-- &interaction.branching.tag; -->
   3.205 -Let's say some ongoing development occurs on the main branch.
   3.206 -<!-- &interaction.branching.main; -->
   3.207 -Using the tag that was recorded at the milestone, people who clone
   3.208 -that repository at any time in the future can use <command role="hg-cmd">hg update</command> to
   3.209 -get a copy of the working directory exactly as it was when that tagged
   3.210 -revision was committed.
   3.211 -<!-- &interaction.branching.update; -->
   3.212 -</para>
   3.213 -
   3.214 -<para>In addition, immediately after the main branch is tagged, someone can
   3.215 -then clone the main branch on the server to a new <quote>stable</quote> branch,
   3.216 -also on the server.
   3.217 -<!-- &interaction.branching.clone; -->
   3.218 -</para>
   3.219 -
   3.220 -<para>Someone who needs to make a change to the stable branch can then clone
   3.221 -<emphasis>that</emphasis> repository, make their changes, commit, and push their
   3.222 -changes back there.
   3.223 -<!-- &interaction.branching.stable; -->
   3.224 -Because Mercurial repositories are independent, and Mercurial doesn't
   3.225 -move changes around automatically, the stable and main branches are
   3.226 -<emphasis>isolated</emphasis> from each other.  The changes that you made on the
   3.227 -main branch don't <quote>leak</quote> to the stable branch, and vice versa.
   3.228 -</para>
   3.229 -
   3.230 -<para>You'll often want all of your bugfixes on the stable branch to show up
   3.231 -on the main branch, too.  Rather than rewrite a bugfix on the main
   3.232 -branch, you can simply pull and merge changes from the stable to the
   3.233 -main branch, and Mercurial will bring those bugfixes in for you.
   3.234 -<!-- &interaction.branching.merge; -->
   3.235 -The main branch will still contain changes that are not on the stable
   3.236 -branch, but it will also contain all of the bugfixes from the stable
   3.237 -branch.  The stable branch remains unaffected by these changes.
   3.238 -</para>
   3.239 -
   3.240 -</sect2>
   3.241 -<sect2>
   3.242 -<title>Feature branches</title>
   3.243 -
   3.244 -<para>For larger projects, an effective way to manage change is to break up
   3.245 -a team into smaller groups.  Each group has a shared branch of its
   3.246 -own, cloned from a single <quote>master</quote> branch used by the entire
   3.247 -project.  People working on an individual branch are typically quite
   3.248 -isolated from developments on other branches.
   3.249 -</para>
   3.250 -
   3.251 -<informalfigure>
   3.252 -
   3.253 -<para>  <mediaobject><imageobject><imagedata fileref="feature-branches"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject>
   3.254 -  <caption><para>Feature branches</para></caption>
   3.255 -  \label{fig:collab:feature-branches}
   3.256 -</para>
   3.257 -</informalfigure>
   3.258 -
   3.259 -<para>When a particular feature is deemed to be in suitable shape, someone
   3.260 -on that feature team pulls and merges from the master branch into the
   3.261 -feature branch, then pushes back up to the master branch.
   3.262 -</para>
   3.263 -
   3.264 -</sect2>
   3.265 -<sect2>
   3.266 -<title>The release train</title>
   3.267 -
   3.268 -<para>Some projects are organised on a <quote>train</quote> basis: a release is
   3.269 -scheduled to happen every few months, and whatever features are ready
   3.270 -when the <quote>train</quote> is ready to leave are allowed in.
   3.271 -</para>
   3.272 -
   3.273 -<para>This model resembles working with feature branches.  The difference is
   3.274 -that when a feature branch misses a train, someone on the feature team
   3.275 -pulls and merges the changes that went out on that train release into
   3.276 -the feature branch, and the team continues its work on top of that
   3.277 -release so that their feature can make the next release.
   3.278 -</para>
   3.279 -
   3.280 -</sect2>
   3.281 -<sect2>
   3.282 -<title>The Linux kernel model</title>
   3.283 -
   3.284 -<para>The development of the Linux kernel has a shallow hierarchical
   3.285 -structure, surrounded by a cloud of apparent chaos.  Because most
   3.286 -Linux developers use <command>git</command>, a distributed revision control
   3.287 -tool with capabilities similar to Mercurial, it's useful to describe
   3.288 -the way work flows in that environment; if you like the ideas, the
   3.289 -approach translates well across tools.
   3.290 -</para>
   3.291 -
   3.292 -<para>At the center of the community sits Linus Torvalds, the creator of
   3.293 -Linux.  He publishes a single source repository that is considered the
   3.294 -<quote>authoritative</quote> current tree by the entire developer community.
   3.295 -Anyone can clone Linus's tree, but he is very choosy about whose trees
   3.296 -he pulls from.
   3.297 -</para>
   3.298 -
   3.299 -<para>Linus has a number of <quote>trusted lieutenants</quote>.  As a general rule, he
   3.300 -pulls whatever changes they publish, in most cases without even
   3.301 -reviewing those changes.  Some of those lieutenants are generally
   3.302 -agreed to be <quote>maintainers</quote>, responsible for specific subsystems
   3.303 -within the kernel.  If a random kernel hacker wants to make a change
   3.304 -to a subsystem that they want to end up in Linus's tree, they must
   3.305 -find out who the subsystem's maintainer is, and ask that maintainer to
   3.306 -take their change.  If the maintainer reviews their changes and agrees
   3.307 -to take them, they'll pass them along to Linus in due course.
   3.308 -</para>
   3.309 -
   3.310 -<para>Individual lieutenants have their own approaches to reviewing,
   3.311 -accepting, and publishing changes; and for deciding when to feed them
   3.312 -to Linus.  In addition, there are several well known branches that
   3.313 -people use for different purposes.  For example, a few people maintain
   3.314 -<quote>stable</quote> repositories of older versions of the kernel, to which they
   3.315 -apply critical fixes as needed.  Some maintainers publish multiple
   3.316 -trees: one for experimental changes; one for changes that they are
   3.317 -about to feed upstream; and so on.  Others just publish a single
   3.318 -tree.
   3.319 -</para>
   3.320 -
   3.321 -<para>This model has two notable features.  The first is that it's <quote>pull
   3.322 -only</quote>.  You have to ask, convince, or beg another developer to take a
   3.323 -change from you, because there are almost no trees to which more than
   3.324 -one person can push, and there's no way to push changes into a tree
   3.325 -that someone else controls.
   3.326 -</para>
   3.327 -
   3.328 -<para>The second is that it's based on reputation and acclaim.  If you're an
   3.329 -unknown, Linus will probably ignore changes from you without even
   3.330 -responding.  But a subsystem maintainer will probably review them, and
   3.331 -will likely take them if they pass their criteria for suitability.
   3.332 -The more <quote>good</quote> changes you contribute to a maintainer, the more
   3.333 -likely they are to trust your judgment and accept your changes.  If
   3.334 -you're well-known and maintain a long-lived branch for something Linus
   3.335 -hasn't yet accepted, people with similar interests may pull your
   3.336 -changes regularly to keep up with your work.
   3.337 -</para>
   3.338 -
   3.339 -<para>Reputation and acclaim don't necessarily cross subsystem or <quote>people</quote>
   3.340 -boundaries.  If you're a respected but specialised storage hacker, and
   3.341 -you try to fix a networking bug, that change will receive a level of
   3.342 -scrutiny from a network maintainer comparable to a change from a
   3.343 -complete stranger.
   3.344 -</para>
   3.345 -
   3.346 -<para>To people who come from more orderly project backgrounds, the
   3.347 -comparatively chaotic Linux kernel development process often seems
   3.348 -completely insane.  It's subject to the whims of individuals; people
   3.349 -make sweeping changes whenever they deem it appropriate; and the pace
   3.350 -of development is astounding.  And yet Linux is a highly successful,
   3.351 -well-regarded piece of software.
   3.352 -</para>
   3.353 -
   3.354 -</sect2>
   3.355 -<sect2>
   3.356 -<title>Pull-only versus shared-push collaboration</title>
   3.357 -
   3.358 -<para>A perpetual source of heat in the open source community is whether a
   3.359 -development model in which people only ever pull changes from others
   3.360 -is <quote>better than</quote> one in which multiple people can push changes to a
   3.361 -shared repository.
   3.362 -</para>
   3.363 -
   3.364 -<para>Typically, the backers of the shared-push model use tools that
   3.365 -actively enforce this approach.  If you're using a centralised
   3.366 -revision control tool such as Subversion, there's no way to make a
   3.367 -choice over which model you'll use: the tool gives you shared-push,
   3.368 -and if you want to do anything else, you'll have to roll your own
   3.369 -approach on top (such as applying a patch by hand).
   3.370 -</para>
   3.371 -
   3.372 -<para>A good distributed revision control tool, such as Mercurial, will
   3.373 -support both models.  You and your collaborators can then structure
   3.374 -how you work together based on your own needs and preferences, not on
   3.375 -what contortions your tools force you into.
   3.376 -</para>
   3.377 -
   3.378 -</sect2>
   3.379 -<sect2>
   3.380 -<title>Where collaboration meets branch management</title>
   3.381 -
   3.382 -<para>Once you and your team set up some shared repositories and start
   3.383 -propagating changes back and forth between local and shared repos, you
   3.384 -begin to face a related, but slightly different challenge: that of
   3.385 -managing the multiple directions in which your team may be moving at
   3.386 -once.  Even though this subject is intimately related to how your team
   3.387 -collaborates, it's dense enough to merit treatment of its own, in
   3.388 -chapter <xref linkend="chap:branch"/>.
   3.389 -</para>
   3.390 -
   3.391 -</sect2>
   3.392 -</sect1>
   3.393 -<sect1>
   3.394 -<title>The technical side of sharing</title>
   3.395 -
   3.396 -<para>The remainder of this chapter is devoted to the question of serving
   3.397 -data to your collaborators.
   3.398 -</para>
   3.399 -
   3.400 -</sect1>
   3.401 -<sect1>
   3.402 -<title>Informal sharing with <command role="hg-cmd">hg serve</command></title>
   3.403 -<para>\label{sec:collab:serve}
   3.404 -</para>
   3.405 -
   3.406 -<para>Mercurial's <command role="hg-cmd">hg serve</command> command is wonderfully suited to small,
   3.407 -tight-knit, and fast-paced group environments.  It also provides a
   3.408 -great way to get a feel for using Mercurial commands over a network.
   3.409 -</para>
   3.410 -
   3.411 -<para>Run <command role="hg-cmd">hg serve</command> inside a repository, and in under a second it will
   3.412 -bring up a specialised HTTP server; this will accept connections from
   3.413 -any client, and serve up data for that repository until you terminate
   3.414 -it.  Anyone who knows the URL of the server you just started, and can
   3.415 -talk to your computer over the network, can then use a web browser or
   3.416 -Mercurial to read data from that repository.  A URL for a
   3.417 -<command role="hg-cmd">hg serve</command> instance running on a laptop is likely to look something
   3.418 -like <literal>http://my-laptop.local:8000/</literal>.
   3.419 -</para>
   3.420 -
   3.421 -<para>The <command role="hg-cmd">hg serve</command> command is <emphasis>not</emphasis> a general-purpose web server.
   3.422 -It can do only two things:
   3.423 -</para>
   3.424 -<itemizedlist>
   3.425 -<listitem><para>Allow people to browse the history of the repository it's
   3.426 -  serving, from their normal web browsers.
   3.427 -</para>
   3.428 -</listitem>
   3.429 -<listitem><para>Speak Mercurial's wire protocol, so that people can
   3.430 -  <command role="hg-cmd">hg clone</command> or <command role="hg-cmd">hg pull</command> changes from that repository.
   3.431 -</para>
   3.432 -</listitem></itemizedlist>
   3.433 -<para>In particular, <command role="hg-cmd">hg serve</command> won't allow remote users to <emphasis>modify</emphasis>
   3.434 -your repository.  It's intended for read-only use.
   3.435 -</para>
   3.436 -
   3.437 -<para>If you're getting started with Mercurial, there's nothing to prevent
   3.438 -you from using <command role="hg-cmd">hg serve</command> to serve up a repository on your own
   3.439 -computer, then use commands like <command role="hg-cmd">hg clone</command>, <command role="hg-cmd">hg incoming</command>, and
   3.440 -so on to talk to that server as if the repository was hosted remotely.
   3.441 -This can help you to quickly get acquainted with using commands on
   3.442 -network-hosted repositories.
   3.443 -</para>
   3.444 -
   3.445 -<sect2>
   3.446 -<title>A few things to keep in mind</title>
   3.447 -
   3.448 -<para>Because it provides unauthenticated read access to all clients, you
   3.449 -should only use <command role="hg-cmd">hg serve</command> in an environment where you either don't
   3.450 -care, or have complete control over, who can access your network and
   3.451 -pull data from your repository.
   3.452 -</para>
   3.453 -
   3.454 -<para>The <command role="hg-cmd">hg serve</command> command knows nothing about any firewall software
   3.455 -you might have installed on your system or network.  It cannot detect
   3.456 -or control your firewall software.  If other people are unable to talk
   3.457 -to a running <command role="hg-cmd">hg serve</command> instance, the second thing you should do
   3.458 -(<emphasis>after</emphasis> you make sure that they're using the correct URL) is
   3.459 -check your firewall configuration.
   3.460 -</para>
   3.461 -
   3.462 -<para>By default, <command role="hg-cmd">hg serve</command> listens for incoming connections on
   3.463 -port 8000.  If another process is already listening on the port you
   3.464 -want to use, you can specify a different port to listen on using the
   3.465 -<option role="hg-opt-serve">-p</option> option.
   3.466 -</para>
   3.467 -
   3.468 -<para>Normally, when <command role="hg-cmd">hg serve</command> starts, it prints no output, which can be
   3.469 -a bit unnerving.  If you'd like to confirm that it is indeed running
   3.470 -correctly, and find out what URL you should send to your
   3.471 -collaborators, start it with the <option role="hg-opt-global">-v</option> option.
   3.472 -</para>
   3.473 -
   3.474 -</sect2>
   3.475 -</sect1>
   3.476 -<sect1>
   3.477 -<title>Using the Secure Shell (ssh) protocol</title>
   3.478 -<para>\label{sec:collab:ssh}
   3.479 -</para>
   3.480 -
   3.481 -<para>You can pull and push changes securely over a network connection using
   3.482 -the Secure Shell (<literal>ssh</literal>) protocol.  To use this successfully,
   3.483 -you may have to do a little bit of configuration on the client or
   3.484 -server sides.
   3.485 -</para>
   3.486 -
   3.487 -<para>If you're not familiar with ssh, it's a network protocol that lets you
   3.488 -securely communicate with another computer.  To use it with Mercurial,
   3.489 -you'll be setting up one or more user accounts on a server so that
   3.490 -remote users can log in and execute commands.
   3.491 -</para>
   3.492 -
   3.493 -<para>(If you <emphasis>are</emphasis> familiar with ssh, you'll probably find some of the
   3.494 -material that follows to be elementary in nature.)
   3.495 -</para>
   3.496 -
   3.497 -<sect2>
   3.498 -<title>How to read and write ssh URLs</title>
   3.499 -
   3.500 -<para>An ssh URL tends to look like this:
   3.501 -</para>
   3.502 -<programlisting>
   3.503 -<para>  ssh://bos@hg.serpentine.com:22/hg/hgbook
   3.504 -</para>
   3.505 +<chapter id="cha:collab">
   3.506 +  <?dbhtml filename="collaborating-with-other-people.html"?>
   3.507 +  <title>Collaborating with other people</title>
   3.508 +
   3.509 +  <para id="x_44a">As a completely decentralised tool, Mercurial doesn't impose
   3.510 +    any policy on how people ought to work with each other.  However,
   3.511 +    if you're new to distributed revision control, it helps to have
   3.512 +    some tools and examples in mind when you're thinking about
   3.513 +    possible workflow models.</para>
   3.514 +
   3.515 +  <sect1>
   3.516 +    <title>Mercurial's web interface</title>
   3.517 +
   3.518 +    <para id="x_44b">Mercurial has a powerful web interface that provides several
   3.519 +      useful capabilities.</para>
   3.520 +
   3.521 +    <para id="x_44c">For interactive use, the web interface lets you browse a
   3.522 +      single repository or a collection of repositories.  You can view
   3.523 +      the history of a repository, examine each change (comments and
   3.524 +      diffs), and view the contents of each directory and file.  You
   3.525 +      can even get a view of history that gives a graphical view of
   3.526 +      the relationships between individual changes and merges.</para>
   3.527 +
   3.528 +    <para id="x_44d">Also for human consumption, the web interface provides
   3.529 +      Atom and RSS feeds of the changes in a repository.  This lets you
   3.530 +      <quote>subscribe</quote> to a repository using your favorite
   3.531 +      feed reader, and be automatically notified of activity in that
   3.532 +      repository as soon as it happens.  I find this capability much
   3.533 +      more convenient than the model of subscribing to a mailing list
   3.534 +      to which notifications are sent, as it requires no additional
   3.535 +      configuration on the part of whoever is serving the
   3.536 +      repository.</para>
   3.537 +
   3.538 +    <para id="x_44e">The web interface also lets remote users clone a repository,
   3.539 +      pull changes from it, and (when the server is configured to
   3.540 +      permit it) push changes back to it.  Mercurial's HTTP tunneling
   3.541 +      protocol aggressively compresses data, so that it works
   3.542 +      efficiently even over low-bandwidth network connections.</para>
   3.543 +
   3.544 +    <para id="x_44f">The easiest way to get started with the web interface is to
   3.545 +      use your web browser to visit an existing repository, such as
   3.546 +      the master Mercurial repository at <ulink
   3.547 +	url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para>
   3.548 +
   3.549 +    <para id="x_450">If you're interested in providing a web interface
   3.550 +      to your own repositories, there are several good ways to do
   3.551 +      this.</para>
   3.552 +
   3.553 +    <para id="x_69d">The easiest and fastest way to get started in an informal
   3.554 +      environment is to use the <command role="hg-cmd">hg
   3.555 +	serve</command> command, which is best suited to short-term
   3.556 +      <quote>lightweight</quote> serving.  See <xref
   3.557 +	linkend="sec:collab:serve"/> below for details of how to use
   3.558 +      this command.</para>
   3.559 +
   3.560 +    <para id="x_69e">For longer-lived repositories that you'd like to
   3.561 +      have permanently available, there are several public hosting
   3.562 +      services available.  Some are free to open source projects,
   3.563 +      while others offer paid commercial hosting.  An up-to-date list
   3.564 +      is available at <ulink
   3.565 +	url="http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting">http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting</ulink>.</para>
   3.566 +
   3.567 +    <para id="x_6a0">If you would prefer to host your own repositories, Mercurial
   3.568 +      has built-in support for several popular hosting technologies,
   3.569 +      most notably CGI (Common Gateway Interface), and WSGI (Web
   3.570 +      Services Gateway Interface).  See <xref
   3.571 +	linkend="sec:collab:cgi"/> for details of CGI and WSGI
   3.572 +      configuration.</para>
   3.573 +  </sect1>
   3.574 +
   3.575 +  <sect1>
   3.576 +    <title>Collaboration models</title>
   3.577 +
   3.578 +    <para id="x_451">With a suitably flexible tool, making decisions about
   3.579 +      workflow is much more of a social engineering challenge than a
   3.580 +      technical one. Mercurial imposes few limitations on how you can
   3.581 +      structure the flow of work in a project, so it's up to you and
   3.582 +      your group to set up and live with a model that matches your own
   3.583 +      particular needs.</para>
   3.584 +
   3.585 +    <sect2>
   3.586 +      <title>Factors to keep in mind</title>
   3.587 +
   3.588 +      <para id="x_452">The most important aspect of any model that you must keep
   3.589 +	in mind is how well it matches the needs and capabilities of
   3.590 +	the people who will be using it.  This might seem
   3.591 +	self-evident; even so, you still can't afford to forget it for
   3.592 +	a moment.</para>
   3.593 +
   3.594 +      <para id="x_453">I once put together a workflow model that seemed to make
   3.595 +	perfect sense to me, but that caused a considerable amount of
   3.596 +	consternation and strife within my development team.  In spite
   3.597 +	of my attempts to explain why we needed a complex set of
   3.598 +	branches, and how changes ought to flow between them, a few
   3.599 +	team members revolted.  Even though they were smart people,
   3.600 +	they didn't want to pay attention to the constraints we were
   3.601 +	operating under, or face the consequences of those constraints
   3.602 +	in the details of the model that I was advocating.</para>
   3.603 +
   3.604 +      <para id="x_454">Don't sweep foreseeable social or technical problems under
   3.605 +	the rug. Whatever scheme you put into effect, you should plan
   3.606 +	for mistakes and problem scenarios.  Consider adding automated
   3.607 +	machinery to prevent, or quickly recover from, trouble that
   3.608 +	you can anticipate.  As an example, if you intend to have a
   3.609 +	branch with not-for-release changes in it, you'd do well to
   3.610 +	think early about the possibility that someone might
   3.611 +	accidentally merge those changes into a release branch.  You
   3.612 +	could avoid this particular problem by writing a hook that
   3.613 +	prevents changes from being merged from an inappropriate
   3.614 +	branch.</para>
   3.615 +    </sect2>
   3.616 +
   3.617 +    <sect2>
   3.618 +      <title>Informal anarchy</title>
   3.619 +
   3.620 +      <para id="x_455">I wouldn't suggest an <quote>anything goes</quote>
   3.621 +	approach as something sustainable, but it's a model that's
   3.622 +	easy to grasp, and it works perfectly well in a few unusual
   3.623 +	situations.</para>
   3.624 +
   3.625 +      <para id="x_456">As one example, many projects have a loose-knit group of
   3.626 +	collaborators who rarely physically meet each other.  Some
   3.627 +	groups like to overcome the isolation of working at a distance
   3.628 +	by organizing occasional <quote>sprints</quote>.  In a sprint,
   3.629 +	a number of people get together in a single location (a
   3.630 +	company's conference room, a hotel meeting room, that kind of
   3.631 +	place) and spend several days more or less locked in there,
   3.632 +	hacking intensely on a handful of projects.</para>
   3.633 +
   3.634 +      <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the
   3.635 +	<command role="hg-cmd">hg serve</command> command, since
   3.636 +	<command role="hg-cmd">hg serve</command> does not require any
   3.637 +	fancy server infrastructure.  You can get started with
   3.638 +	<command role="hg-cmd">hg serve</command> in moments, by
   3.639 +	reading <xref linkend="sec:collab:serve"/> below.  Then simply
   3.640 +	tell the person next to you that you're running a server, send
   3.641 +	the URL to them in an instant message, and you immediately
   3.642 +	have a quick-turnaround way to work together.  They can type
   3.643 +	your URL into their web browser and quickly review your
   3.644 +	changes; or they can pull a bugfix from you and verify it; or
   3.645 +	they can clone a branch containing a new feature and try it
   3.646 +	out.</para>
   3.647 +
   3.648 +      <para id="x_458">The charm, and the problem, with doing things
   3.649 +	in an ad hoc fashion like this is that only people who know
   3.650 +	about your changes, and where they are, can see them.  Such an
   3.651 +	informal approach simply doesn't scale beyond a handful
   3.652 +	people, because each individual needs to know about
   3.653 +	<emphasis>n</emphasis> different repositories to pull
   3.654 +	from.</para>
   3.655 +    </sect2>
   3.656 +
   3.657 +    <sect2>
   3.658 +      <title>A single central repository</title>
   3.659 +
   3.660 +      <para id="x_459">For smaller projects migrating from a centralised revision
   3.661 +	control tool, perhaps the easiest way to get started is to
   3.662 +	have changes flow through a single shared central repository.
   3.663 +	This is also the most common <quote>building block</quote> for
   3.664 +	more ambitious workflow schemes.</para>
   3.665 +
   3.666 +      <para id="x_45a">Contributors start by cloning a copy of this repository.
   3.667 +	They can pull changes from it whenever they need to, and some
   3.668 +	(perhaps all) developers have permission to push a change back
   3.669 +	when they're ready for other people to see it.</para>
   3.670 +
   3.671 +      <para id="x_45b">Under this model, it can still often make sense for people
   3.672 +	to pull changes directly from each other, without going
   3.673 +	through the central repository.  Consider a case in which I
   3.674 +	have a tentative bug fix, but I am worried that if I were to
   3.675 +	publish it to the central repository, it might subsequently
   3.676 +	break everyone else's trees as they pull it.  To reduce the
   3.677 +	potential for damage, I can ask you to clone my repository
   3.678 +	into a temporary repository of your own and test it.  This
   3.679 +	lets us put off publishing the potentially unsafe change until
   3.680 +	it has had a little testing.</para>
   3.681 +
   3.682 +      <para id="x_45c">If a team is hosting its own repository in this
   3.683 +	kind of scenario, people will usually use the
   3.684 +	<command>ssh</command> protocol to securely push changes to
   3.685 +	the central repository, as documented in <xref
   3.686 +	  linkend="sec:collab:ssh"/>.  It's also usual to publish a
   3.687 +	read-only copy of the repository over HTTP, as in
   3.688 +	<xref linkend="sec:collab:cgi"/>. Publishing over HTTP
   3.689 +	satisfies the needs of people who don't have push access, and
   3.690 +	those who want to use web browsers to browse the repository's
   3.691 +	history.</para>
   3.692 +    </sect2>
   3.693 +
   3.694 +    <sect2>
   3.695 +      <title>A hosted central repository</title>
   3.696 +
   3.697 +      <para id="x_6a1">A wonderful thing about public hosting services like
   3.698 +	<ulink url="http://bitbucket.org/">Bitbucket</ulink> is that
   3.699 +	not only do they handle the fiddly server configuration
   3.700 +	details, such as user accounts, authentication, and secure
   3.701 +	wire protocols, they provide additional infrastructure to make
   3.702 +	this model work well.</para>
   3.703 +
   3.704 +      <para id="x_6a2">For instance, a well-engineered hosting service will let
   3.705 +	people clone their own copies of a repository with a single
   3.706 +	click.  This lets people work in separate spaces and share
   3.707 +	their changes when they're ready.</para>
   3.708 +
   3.709 +      <para id="x_6a3">In addition, a good hosting service will let people
   3.710 +	communicate with each other, for instance to say <quote>there
   3.711 +	  are changes ready for you to review in this
   3.712 +	  tree</quote>.</para>
   3.713 +    </sect2>
   3.714 +
   3.715 +    <sect2>
   3.716 +      <title>Working with multiple branches</title>
   3.717 +
   3.718 +      <para id="x_45d">Projects of any significant size naturally tend to make
   3.719 +	progress on several fronts simultaneously.  In the case of
   3.720 +	software, it's common for a project to go through periodic
   3.721 +	official releases.  A release might then go into
   3.722 +	<quote>maintenance mode</quote> for a while after its first
   3.723 +	publication; maintenance releases tend to contain only bug
   3.724 +	fixes, not new features.  In parallel with these maintenance
   3.725 +	releases, one or more future releases may be under
   3.726 +	development.  People normally use the word
   3.727 +	<quote>branch</quote> to refer to one of these many slightly
   3.728 +	different directions in which development is
   3.729 +	proceeding.</para>
   3.730 +
   3.731 +      <para id="x_45e">Mercurial is particularly well suited to managing a number
   3.732 +	of simultaneous, but not identical, branches.  Each
   3.733 +	<quote>development direction</quote> can live in its own
   3.734 +	central repository, and you can merge changes from one to
   3.735 +	another as the need arises.  Because repositories are
   3.736 +	independent of each other, unstable changes in a development
   3.737 +	branch will never affect a stable branch unless someone
   3.738 +	explicitly merges those changes into the stable branch.</para>
   3.739 +
   3.740 +      <para id="x_45f">Here's an example of how this can work in practice.  Let's
   3.741 +	say you have one <quote>main branch</quote> on a central
   3.742 +	server.</para>
   3.743 +
   3.744 +      &interaction.branching.init;
   3.745 +
   3.746 +      <para id="x_460">People clone it, make changes locally, test them, and push
   3.747 +	them back.</para>
   3.748 +
   3.749 +      <para id="x_461">Once the main branch reaches a release milestone, you can
   3.750 +	use the <command role="hg-cmd">hg tag</command> command to
   3.751 +	give a permanent name to the milestone revision.</para>
   3.752 +
   3.753 +	&interaction.branching.tag;
   3.754 +
   3.755 +      <para id="x_462">Let's say some ongoing
   3.756 +	development occurs on the main branch.</para>
   3.757 +
   3.758 +      &interaction.branching.main;
   3.759 +
   3.760 +      <para id="x_463">Using the tag that was recorded at the milestone, people
   3.761 +	who clone that repository at any time in the future can use
   3.762 +	<command role="hg-cmd">hg update</command> to get a copy of
   3.763 +	the working directory exactly as it was when that tagged
   3.764 +	revision was committed.</para>
   3.765 +
   3.766 +      &interaction.branching.update;
   3.767 +
   3.768 +      <para id="x_464">In addition, immediately after the main branch is tagged,
   3.769 +	we can then clone the main branch on the server to a new
   3.770 +	<quote>stable</quote> branch, also on the server.</para>
   3.771 +
   3.772 +      &interaction.branching.clone;
   3.773 +
   3.774 +      <para id="x_465">If we need to make a change to the stable
   3.775 +	branch, we can then clone <emphasis>that</emphasis>
   3.776 +	repository, make our changes, commit, and push our changes
   3.777 +	back there.</para>
   3.778 +
   3.779 +      &interaction.branching.stable;
   3.780 +
   3.781 +      <para id="x_466">Because Mercurial repositories are independent, and
   3.782 +	Mercurial doesn't move changes around automatically, the
   3.783 +	stable and main branches are <emphasis>isolated</emphasis>
   3.784 +	from each other.  The changes that we made on the main branch
   3.785 +	don't <quote>leak</quote> to the stable branch, and vice
   3.786 +	versa.</para>
   3.787 +
   3.788 +      <para id="x_467">We'll often want all of our bugfixes on the stable
   3.789 +	branch to show up on the main branch, too.  Rather than
   3.790 +	rewrite a bugfix on the main branch, we can simply pull and
   3.791 +	merge changes from the stable to the main branch, and
   3.792 +	Mercurial will bring those bugfixes in for us.</para>
   3.793 +
   3.794 +      &interaction.branching.merge;
   3.795 +
   3.796 +      <para id="x_468">The main branch will still contain changes that
   3.797 +	are not on the stable branch, but it will also contain all of
   3.798 +	the bugfixes from the stable branch.  The stable branch
   3.799 +	remains unaffected by these changes, since changes are only
   3.800 +	flowing from the stable to the main branch, and not the other
   3.801 +	way.</para>
   3.802 +    </sect2>
   3.803 +
   3.804 +    <sect2>
   3.805 +      <title>Feature branches</title>
   3.806 +
   3.807 +      <para id="x_469">For larger projects, an effective way to manage change is
   3.808 +	to break up a team into smaller groups.  Each group has a
   3.809 +	shared branch of its own, cloned from a single
   3.810 +	<quote>master</quote> branch used by the entire project.
   3.811 +	People working on an individual branch are typically quite
   3.812 +	isolated from developments on other branches.</para>
   3.813 +
   3.814 +      <figure id="fig:collab:feature-branches">
   3.815 +	<title>Feature branches</title>
   3.816 +	<mediaobject>
   3.817 +	  <imageobject><imagedata width="100%" fileref="figs/feature-branches.png"/></imageobject>
   3.818 +	  <textobject><phrase>XXX add text</phrase></textobject>
   3.819 +	</mediaobject>
   3.820 +      </figure>
   3.821 +
   3.822 +      <para id="x_46b">When a particular feature is deemed to be in suitable
   3.823 +	shape, someone on that feature team pulls and merges from the
   3.824 +	master branch into the feature branch, then pushes back up to
   3.825 +	the master branch.</para>
   3.826 +    </sect2>
   3.827 +
   3.828 +    <sect2>
   3.829 +      <title>The release train</title>
   3.830 +
   3.831 +      <para id="x_46c">Some projects are organized on a <quote>train</quote>
   3.832 +	basis: a release is scheduled to happen every few months, and
   3.833 +	whatever features are ready when the <quote>train</quote> is
   3.834 +	ready to leave are allowed in.</para>
   3.835 +
   3.836 +      <para id="x_46d">This model resembles working with feature branches.  The
   3.837 +	difference is that when a feature branch misses a train,
   3.838 +	someone on the feature team pulls and merges the changes that
   3.839 +	went out on that train release into the feature branch, and
   3.840 +	the team continues its work on top of that release so that
   3.841 +	their feature can make the next release.</para>
   3.842 +    </sect2>
   3.843 +
   3.844 +    <sect2>
   3.845 +      <title>The Linux kernel model</title>
   3.846 +
   3.847 +      <para id="x_46e">The development of the Linux kernel has a shallow
   3.848 +	hierarchical structure, surrounded by a cloud of apparent
   3.849 +	chaos.  Because most Linux developers use
   3.850 +	<command>git</command>, a distributed revision control tool
   3.851 +	with capabilities similar to Mercurial, it's useful to
   3.852 +	describe the way work flows in that environment; if you like
   3.853 +	the ideas, the approach translates well across tools.</para>
   3.854 +
   3.855 +      <para id="x_46f">At the center of the community sits Linus Torvalds, the
   3.856 +	creator of Linux.  He publishes a single source repository
   3.857 +	that is considered the <quote>authoritative</quote> current
   3.858 +	tree by the entire developer community. Anyone can clone
   3.859 +	Linus's tree, but he is very choosy about whose trees he pulls
   3.860 +	from.</para>
   3.861 +
   3.862 +      <para id="x_470">Linus has a number of <quote>trusted lieutenants</quote>.
   3.863 +	As a general rule, he pulls whatever changes they publish, in
   3.864 +	most cases without even reviewing those changes.  Some of
   3.865 +	those lieutenants are generally agreed to be
   3.866 +	<quote>maintainers</quote>, responsible for specific
   3.867 +	subsystems within the kernel.  If a random kernel hacker wants
   3.868 +	to make a change to a subsystem that they want to end up in
   3.869 +	Linus's tree, they must find out who the subsystem's
   3.870 +	maintainer is, and ask that maintainer to take their change.
   3.871 +	If the maintainer reviews their changes and agrees to take
   3.872 +	them, they'll pass them along to Linus in due course.</para>
   3.873 +
   3.874 +      <para id="x_471">Individual lieutenants have their own approaches to
   3.875 +	reviewing, accepting, and publishing changes; and for deciding
   3.876 +	when to feed them to Linus.  In addition, there are several
   3.877 +	well known branches that people use for different purposes.
   3.878 +	For example, a few people maintain <quote>stable</quote>
   3.879 +	repositories of older versions of the kernel, to which they
   3.880 +	apply critical fixes as needed.  Some maintainers publish
   3.881 +	multiple trees: one for experimental changes; one for changes
   3.882 +	that they are about to feed upstream; and so on.  Others just
   3.883 +	publish a single tree.</para>
   3.884 +
   3.885 +      <para id="x_472">This model has two notable features.  The first is that
   3.886 +	it's <quote>pull only</quote>.  You have to ask, convince, or
   3.887 +	beg another developer to take a change from you, because there
   3.888 +	are almost no trees to which more than one person can push,
   3.889 +	and there's no way to push changes into a tree that someone
   3.890 +	else controls.</para>
   3.891 +
   3.892 +      <para id="x_473">The second is that it's based on reputation and acclaim.
   3.893 +	If you're an unknown, Linus will probably ignore changes from
   3.894 +	you without even responding.  But a subsystem maintainer will
   3.895 +	probably review them, and will likely take them if they pass
   3.896 +	their criteria for suitability. The more <quote>good</quote>
   3.897 +	changes you contribute to a maintainer, the more likely they
   3.898 +	are to trust your judgment and accept your changes.  If you're
   3.899 +	well-known and maintain a long-lived branch for something
   3.900 +	Linus hasn't yet accepted, people with similar interests may
   3.901 +	pull your changes regularly to keep up with your work.</para>
   3.902 +
   3.903 +      <para id="x_474">Reputation and acclaim don't necessarily cross subsystem
   3.904 +	or <quote>people</quote> boundaries.  If you're a respected
   3.905 +	but specialised storage hacker, and you try to fix a
   3.906 +	networking bug, that change will receive a level of scrutiny
   3.907 +	from a network maintainer comparable to a change from a
   3.908 +	complete stranger.</para>
   3.909 +
   3.910 +      <para id="x_475">To people who come from more orderly project backgrounds,
   3.911 +	the comparatively chaotic Linux kernel development process
   3.912 +	often seems completely insane.  It's subject to the whims of
   3.913 +	individuals; people make sweeping changes whenever they deem
   3.914 +	it appropriate; and the pace of development is astounding.
   3.915 +	And yet Linux is a highly successful, well-regarded piece of
   3.916 +	software.</para>
   3.917 +    </sect2>
   3.918 +
   3.919 +    <sect2>
   3.920 +      <title>Pull-only versus shared-push collaboration</title>
   3.921 +
   3.922 +      <para id="x_476">A perpetual source of heat in the open source community is
   3.923 +	whether a development model in which people only ever pull
   3.924 +	changes from others is <quote>better than</quote> one in which
   3.925 +	multiple people can push changes to a shared
   3.926 +	repository.</para>
   3.927 +
   3.928 +      <para id="x_477">Typically, the backers of the shared-push model use tools
   3.929 +	that actively enforce this approach.  If you're using a
   3.930 +	centralised revision control tool such as Subversion, there's
   3.931 +	no way to make a choice over which model you'll use: the tool
   3.932 +	gives you shared-push, and if you want to do anything else,
   3.933 +	you'll have to roll your own approach on top (such as applying
   3.934 +	a patch by hand).</para>
   3.935 +
   3.936 +      <para id="x_478">A good distributed revision control tool will
   3.937 +	support both models.  You and your collaborators can then
   3.938 +	structure how you work together based on your own needs and
   3.939 +	preferences, not on what contortions your tools force you
   3.940 +	into.</para>
   3.941 +    </sect2>
   3.942 +    <sect2>
   3.943 +      <title>Where collaboration meets branch management</title>
   3.944 +
   3.945 +      <para id="x_479">Once you and your team set up some shared
   3.946 +	repositories and start propagating changes back and forth
   3.947 +	between local and shared repos, you begin to face a related,
   3.948 +	but slightly different challenge: that of managing the
   3.949 +	multiple directions in which your team may be moving at once.
   3.950 +	Even though this subject is intimately related to how your
   3.951 +	team collaborates, it's dense enough to merit treatment of its
   3.952 +	own, in <xref linkend="chap:branch"/>.</para>
   3.953 +    </sect2>
   3.954 +  </sect1>
   3.955 +
   3.956 +  <sect1>
   3.957 +    <title>The technical side of sharing</title>
   3.958 +
   3.959 +    <para id="x_47a">The remainder of this chapter is devoted to the question of
   3.960 +      sharing changes with your collaborators.</para>
   3.961 +  </sect1>
   3.962 +
   3.963 +  <sect1 id="sec:collab:serve">
   3.964 +    <title>Informal sharing with <command role="hg-cmd">hg
   3.965 +	serve</command></title>
   3.966 +
   3.967 +    <para id="x_47b">Mercurial's <command role="hg-cmd">hg serve</command>
   3.968 +      command is wonderfully suited to small, tight-knit, and
   3.969 +      fast-paced group environments.  It also provides a great way to
   3.970 +      get a feel for using Mercurial commands over a network.</para>
   3.971 +
   3.972 +    <para id="x_47c">Run <command role="hg-cmd">hg serve</command> inside a
   3.973 +      repository, and in under a second it will bring up a specialised
   3.974 +      HTTP server; this will accept connections from any client, and
   3.975 +      serve up data for that repository until you terminate it.
   3.976 +      Anyone who knows the URL of the server you just started, and can
   3.977 +      talk to your computer over the network, can then use a web
   3.978 +      browser or Mercurial to read data from that repository.  A URL
   3.979 +      for a <command role="hg-cmd">hg serve</command> instance running
   3.980 +      on a laptop is likely to look something like
   3.981 +      <literal>http://my-laptop.local:8000/</literal>.</para>
   3.982 +
   3.983 +    <para id="x_47d">The <command role="hg-cmd">hg serve</command> command is
   3.984 +      <emphasis>not</emphasis> a general-purpose web server. It can do
   3.985 +      only two things:</para>
   3.986 +    <itemizedlist>
   3.987 +      <listitem><para id="x_47e">Allow people to browse the history of the
   3.988 +	  repository it's serving, from their normal web
   3.989 +	  browsers.</para>
   3.990 +      </listitem>
   3.991 +      <listitem><para id="x_47f">Speak Mercurial's wire protocol, so that people
   3.992 +	  can <command role="hg-cmd">hg clone</command> or <command
   3.993 +	    role="hg-cmd">hg pull</command> changes from that
   3.994 +	  repository.</para>
   3.995 +      </listitem></itemizedlist>
   3.996 +    <para id="x_480">In particular, <command role="hg-cmd">hg serve</command>
   3.997 +      won't allow remote users to <emphasis>modify</emphasis> your
   3.998 +      repository.  It's intended for read-only use.</para>
   3.999 +
  3.1000 +    <para id="x_481">If you're getting started with Mercurial, there's nothing to
  3.1001 +      prevent you from using <command role="hg-cmd">hg serve</command>
  3.1002 +      to serve up a repository on your own computer, then use commands
  3.1003 +      like <command role="hg-cmd">hg clone</command>, <command
  3.1004 +	role="hg-cmd">hg incoming</command>, and so on to talk to that
  3.1005 +      server as if the repository was hosted remotely. This can help
  3.1006 +      you to quickly get acquainted with using commands on
  3.1007 +      network-hosted repositories.</para>
  3.1008 +
  3.1009 +    <sect2>
  3.1010 +      <title>A few things to keep in mind</title>
  3.1011 +
  3.1012 +      <para id="x_482">Because it provides unauthenticated read access to all
  3.1013 +	clients, you should only use <command role="hg-cmd">hg
  3.1014 +	  serve</command> in an environment where you either don't
  3.1015 +	care, or have complete control over, who can access your
  3.1016 +	network and pull data from your repository.</para>
  3.1017 +
  3.1018 +      <para id="x_483">The <command role="hg-cmd">hg serve</command> command
  3.1019 +	knows nothing about any firewall software you might have
  3.1020 +	installed on your system or network.  It cannot detect or
  3.1021 +	control your firewall software.  If other people are unable to
  3.1022 +	talk to a running <command role="hg-cmd">hg serve</command>
  3.1023 +	instance, the second thing you should do
  3.1024 +	(<emphasis>after</emphasis> you make sure that they're using
  3.1025 +	the correct URL) is check your firewall configuration.</para>
  3.1026 +
  3.1027 +      <para id="x_484">By default, <command role="hg-cmd">hg serve</command>
  3.1028 +	listens for incoming connections on port 8000.  If another
  3.1029 +	process is already listening on the port you want to use, you
  3.1030 +	can specify a different port to listen on using the <option
  3.1031 +	  role="hg-opt-serve">-p</option> option.</para>
  3.1032 +
  3.1033 +      <para id="x_485">Normally, when <command role="hg-cmd">hg serve</command>
  3.1034 +	starts, it prints no output, which can be a bit unnerving.  If
  3.1035 +	you'd like to confirm that it is indeed running correctly, and
  3.1036 +	find out what URL you should send to your collaborators, start
  3.1037 +	it with the <option role="hg-opt-global">-v</option>
  3.1038 +	option.</para>
  3.1039 +    </sect2>
  3.1040 +  </sect1>
  3.1041 +
  3.1042 +  <sect1 id="sec:collab:ssh">
  3.1043 +    <title>Using the Secure Shell (ssh) protocol</title>
  3.1044 +
  3.1045 +    <para id="x_486">You can pull and push changes securely over a network
  3.1046 +      connection using the Secure Shell (<literal>ssh</literal>)
  3.1047 +      protocol.  To use this successfully, you may have to do a little
  3.1048 +      bit of configuration on the client or server sides.</para>
  3.1049 +
  3.1050 +    <para id="x_487">If you're not familiar with ssh, it's the name of
  3.1051 +      both a command and a network protocol that let you securely
  3.1052 +      communicate with another computer.  To use it with Mercurial,
  3.1053 +      you'll be setting up one or more user accounts on a server so
  3.1054 +      that remote users can log in and execute commands.</para>
  3.1055 +
  3.1056 +    <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll
  3.1057 +      probably find some of the material that follows to be elementary
  3.1058 +      in nature.)</para>
  3.1059 +
  3.1060 +    <sect2>
  3.1061 +      <title>How to read and write ssh URLs</title>
  3.1062 +
  3.1063 +      <para id="x_489">An ssh URL tends to look like this:</para>
  3.1064 +      <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting>
  3.1065 +      <orderedlist>
  3.1066 +	<listitem><para id="x_48a">The <quote><literal>ssh://</literal></quote>
  3.1067 +	    part tells Mercurial to use the ssh protocol.</para>
  3.1068 +	</listitem>
  3.1069 +	<listitem><para id="x_48b">The <quote><literal>bos@</literal></quote>
  3.1070 +	    component indicates what username to log into the server
  3.1071 +	    as.  You can leave this out if the remote username is the
  3.1072 +	    same as your local username.</para>
  3.1073 +	</listitem>
  3.1074 +	<listitem><para id="x_48c">The
  3.1075 +	    <quote><literal>hg.serpentine.com</literal></quote> gives
  3.1076 +	    the hostname of the server to log into.</para>
  3.1077 +	</listitem>
  3.1078 +	<listitem><para id="x_48d">The <quote>:22</quote> identifies the port
  3.1079 +	    number to connect to the server on.  The default port is
  3.1080 +	    22, so you only need to specify a colon and port number if
  3.1081 +	    you're <emphasis>not</emphasis> using port 22.</para>
  3.1082 +	</listitem>
  3.1083 +	<listitem><para id="x_48e">The remainder of the URL is the local path to
  3.1084 +	    the repository on the server.</para>
  3.1085 +	</listitem></orderedlist>
  3.1086 +
  3.1087 +      <para id="x_48f">There's plenty of scope for confusion with the path
  3.1088 +	component of ssh URLs, as there is no standard way for tools
  3.1089 +	to interpret it.  Some programs behave differently than others
  3.1090 +	when dealing with these paths. This isn't an ideal situation,
  3.1091 +	but it's unlikely to change.  Please read the following
  3.1092 +	paragraphs carefully.</para>
  3.1093 +
  3.1094 +      <para id="x_490">Mercurial treats the path to a repository on the server as
  3.1095 +	relative to the remote user's home directory.  For example, if
  3.1096 +	user <literal>foo</literal> on the server has a home directory
  3.1097 +	of <filename class="directory">/home/foo</filename>, then an
  3.1098 +	ssh URL that contains a path component of <filename
  3.1099 +	  class="directory">bar</filename> <emphasis>really</emphasis>
  3.1100 +	refers to the directory <filename
  3.1101 +	  class="directory">/home/foo/bar</filename>.</para>
  3.1102 +
  3.1103 +      <para id="x_491">If you want to specify a path relative to another user's
  3.1104 +	home directory, you can use a path that starts with a tilde
  3.1105 +	character followed by the user's name (let's call them
  3.1106 +	<literal>otheruser</literal>), like this.</para>
  3.1107 +      <programlisting>ssh://server/~otheruser/hg/repo</programlisting>
  3.1108 +
  3.1109 +      <para id="x_492">And if you really want to specify an
  3.1110 +	<emphasis>absolute</emphasis> path on the server, begin the
  3.1111 +	path component with two slashes, as in this example.</para>
  3.1112 +      <programlisting>ssh://server//absolute/path</programlisting>
  3.1113 +    </sect2>
  3.1114 +
  3.1115 +    <sect2>
  3.1116 +      <title>Finding an ssh client for your system</title>
  3.1117 +
  3.1118 +      <para id="x_493">Almost every Unix-like system comes with OpenSSH
  3.1119 +	preinstalled.  If you're using such a system, run
  3.1120 +	<literal>which ssh</literal> to find out if the
  3.1121 +	<command>ssh</command> command is installed (it's usually in
  3.1122 +	<filename class="directory">/usr/bin</filename>).  In the
  3.1123 +	unlikely event that it isn't present, take a look at your
  3.1124 +	system documentation to figure out how to install it.</para>
  3.1125 +
  3.1126 +      <para id="x_494">On Windows, the TortoiseHg package is bundled
  3.1127 +	with a version of Simon Tatham's excellent
  3.1128 +	<command>plink</command> command, and you should not need to
  3.1129 +	do any further configuration.</para>
  3.1130 +    </sect2>
  3.1131 +
  3.1132 +    <sect2>
  3.1133 +      <title>Generating a key pair</title>
  3.1134 +
  3.1135 +      <para id="x_499">To avoid the need to repetitively type a
  3.1136 +	password every time you need to use your ssh client, I
  3.1137 +	recommend generating a key pair.</para>
  3.1138 +
  3.1139 +      <tip>
  3.1140 +	<title>Key pairs are not mandatory</title>
  3.1141 +
  3.1142 +	<para id="x_6a4">Mercurial knows nothing about ssh authentication or key
  3.1143 +	  pairs.  You can, if you like, safely ignore this section and
  3.1144 +	  the one that follows until you grow tired of repeatedly
  3.1145 +	  typing ssh passwords.</para>
  3.1146 +      </tip>
  3.1147 +
  3.1148 +      <itemizedlist>
  3.1149 +	<listitem>
  3.1150 +	  <para id="x_6a5">On a Unix-like system, the
  3.1151 +	    <command>ssh-keygen</command> command will do the
  3.1152 +	    trick.</para>
  3.1153 +	  <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need
  3.1154 +	    to download a command named <command>puttygen</command>
  3.1155 +	    from <ulink
  3.1156 +	      url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the 
  3.1157 +	      PuTTY web site</ulink> to generate a key pair.  See
  3.1158 +	    <ulink
  3.1159 +	      url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the 
  3.1160 +	      <command>puttygen</command> documentation</ulink> for
  3.1161 +	    details of how use the command.</para>
  3.1162 +	</listitem>
  3.1163 +      </itemizedlist>
  3.1164 +
  3.1165 +      <para id="x_49a">When you generate a key pair, it's usually
  3.1166 +	<emphasis>highly</emphasis> advisable to protect it with a
  3.1167 +	passphrase.  (The only time that you might not want to do this
  3.1168 +	is when you're using the ssh protocol for automated tasks on a
  3.1169 +	secure network.)</para>
  3.1170 +
  3.1171 +      <para id="x_49b">Simply generating a key pair isn't enough, however.
  3.1172 +	You'll need to add the public key to the set of authorised
  3.1173 +	keys for whatever user you're logging in remotely as.  For
  3.1174 +	servers using OpenSSH (the vast majority), this will mean
  3.1175 +	adding the public key to a list in a file called <filename
  3.1176 +	  role="special">authorized_keys</filename> in their <filename
  3.1177 +	  role="special" class="directory">.ssh</filename>
  3.1178 +	directory.</para>
  3.1179 +
  3.1180 +      <para id="x_49c">On a Unix-like system, your public key will have a
  3.1181 +	<filename>.pub</filename> extension.  If you're using
  3.1182 +	<command>puttygen</command> on Windows, you can save the
  3.1183 +	public key to a file of your choosing, or paste it from the
  3.1184 +	window it's displayed in straight into the <filename
  3.1185 +	  role="special">authorized_keys</filename> file.</para>
  3.1186 +    </sect2>
  3.1187 +    <sect2>
  3.1188 +      <title>Using an authentication agent</title>
  3.1189 +
  3.1190 +      <para id="x_49d">An authentication agent is a daemon that stores
  3.1191 +	passphrases in memory (so it will forget passphrases if you
  3.1192 +	log out and log back in again). An ssh client will notice if
  3.1193 +	it's running, and query it for a passphrase.  If there's no
  3.1194 +	authentication agent running, or the agent doesn't store the
  3.1195 +	necessary passphrase, you'll have to type your passphrase
  3.1196 +	every time Mercurial tries to communicate with a server on
  3.1197 +	your behalf (e.g. whenever you pull or push changes).</para>
  3.1198 +
  3.1199 +      <para id="x_49e">The downside of storing passphrases in an agent is that
  3.1200 +	it's possible for a well-prepared attacker to recover the
  3.1201 +	plain text of your passphrases, in some cases even if your
  3.1202 +	system has been power-cycled. You should make your own
  3.1203 +	judgment as to whether this is an acceptable risk.  It
  3.1204 +	certainly saves a lot of repeated typing.</para>
  3.1205 +
  3.1206 +      <itemizedlist>
  3.1207 +	<listitem>
  3.1208 +	  <para id="x_49f">On Unix-like systems, the agent is called
  3.1209 +	    <command>ssh-agent</command>, and it's often run
  3.1210 +	    automatically for you when you log in.  You'll need to use
  3.1211 +	    the <command>ssh-add</command> command to add passphrases
  3.1212 +	    to the agent's store.</para>
  3.1213 +	</listitem>
  3.1214 +	<listitem>
  3.1215 +	  <para id="x_6a7">On Windows, if you're using TortoiseHg, the
  3.1216 +	    <command>pageant</command> command acts as the agent.  As
  3.1217 +	    with <command>puttygen</command>, you'll need to <ulink
  3.1218 +	      url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download 
  3.1219 +	      <command>pageant</command></ulink> from the PuTTY web
  3.1220 +	    site and read <ulink
  3.1221 +	      url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its 
  3.1222 +	      documentation</ulink>.  The <command>pageant</command>
  3.1223 +	    command adds an icon to your system tray that will let you
  3.1224 +	    manage stored passphrases.</para>
  3.1225 +	</listitem>
  3.1226 +      </itemizedlist>
  3.1227 +    </sect2>
  3.1228 +
  3.1229 +    <sect2>
  3.1230 +      <title>Configuring the server side properly</title>
  3.1231 +
  3.1232 +      <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
  3.1233 +	a variety of things can go wrong.  Add Mercurial
  3.1234 +	on top, and there's plenty more scope for head-scratching.
  3.1235 +	Most of these potential problems occur on the server side, not
  3.1236 +	the client side.  The good news is that once you've gotten a
  3.1237 +	configuration working, it will usually continue to work
  3.1238 +	indefinitely.</para>
  3.1239 +
  3.1240 +      <para id="x_4a1">Before you try using Mercurial to talk to an ssh server,
  3.1241 +	it's best to make sure that you can use the normal
  3.1242 +	<command>ssh</command> or <command>putty</command> command to
  3.1243 +	talk to the server first.  If you run into problems with using
  3.1244 +	these commands directly, Mercurial surely won't work.  Worse,
  3.1245 +	it will obscure the underlying problem.  Any time you want to
  3.1246 +	debug ssh-related Mercurial problems, you should drop back to
  3.1247 +	making sure that plain ssh client commands work first,
  3.1248 +	<emphasis>before</emphasis> you worry about whether there's a
  3.1249 +	problem with Mercurial.</para>
  3.1250 +
  3.1251 +      <para id="x_4a2">The first thing to be sure of on the server side is that
  3.1252 +	you can actually log in from another machine at all.  If you
  3.1253 +	can't use <command>ssh</command> or <command>putty</command>
  3.1254 +	to log in, the error message you get may give you a few hints
  3.1255 +	as to what's wrong.  The most common problems are as
  3.1256 +	follows.</para>
  3.1257 +      <itemizedlist>
  3.1258 +	<listitem><para id="x_4a3">If you get a <quote>connection refused</quote>
  3.1259 +	    error, either there isn't an SSH daemon running on the
  3.1260 +	    server at all, or it's inaccessible due to firewall
  3.1261 +	    configuration.</para>
  3.1262 +	</listitem>
  3.1263 +	<listitem><para id="x_4a4">If you get a <quote>no route to host</quote>
  3.1264 +	    error, you either have an incorrect address for the server
  3.1265 +	    or a seriously locked down firewall that won't admit its
  3.1266 +	    existence at all.</para>
  3.1267 +	</listitem>
  3.1268 +	<listitem><para id="x_4a5">If you get a <quote>permission denied</quote>
  3.1269 +	    error, you may have mistyped the username on the server,
  3.1270 +	    or you could have mistyped your key's passphrase or the
  3.1271 +	    remote user's password.</para>
  3.1272 +	</listitem></itemizedlist>
  3.1273 +      <para id="x_4a6">In summary, if you're having trouble talking to the
  3.1274 +	server's ssh daemon, first make sure that one is running at
  3.1275 +	all.  On many systems it will be installed, but disabled, by
  3.1276 +	default.  Once you're done with this step, you should then
  3.1277 +	check that the server's firewall is configured to allow
  3.1278 +	incoming connections on the port the ssh daemon is listening
  3.1279 +	on (usually 22).  Don't worry about more exotic possibilities
  3.1280 +	for misconfiguration until you've checked these two
  3.1281 +	first.</para>
  3.1282 +
  3.1283 +      <para id="x_4a7">If you're using an authentication agent on the client side
  3.1284 +	to store passphrases for your keys, you ought to be able to
  3.1285 +	log into the server without being prompted for a passphrase or
  3.1286 +	a password.  If you're prompted for a passphrase, there are a
  3.1287 +	few possible culprits.</para>
  3.1288 +      <itemizedlist>
  3.1289 +	<listitem><para id="x_4a8">You might have forgotten to use
  3.1290 +	    <command>ssh-add</command> or <command>pageant</command>
  3.1291 +	    to store the passphrase.</para>
  3.1292 +	</listitem>
  3.1293 +	<listitem><para id="x_4a9">You might have stored the passphrase for the
  3.1294 +	    wrong key.</para>
  3.1295 +	</listitem></itemizedlist>
  3.1296 +      <para id="x_4aa">If you're being prompted for the remote user's password,
  3.1297 +	there are another few possible problems to check.</para>
  3.1298 +      <itemizedlist>
  3.1299 +	<listitem><para id="x_4ab">Either the user's home directory or their
  3.1300 +	    <filename role="special" class="directory">.ssh</filename>
  3.1301 +	    directory might have excessively liberal permissions.  As
  3.1302 +	    a result, the ssh daemon will not trust or read their
  3.1303 +	    <filename role="special">authorized_keys</filename> file.
  3.1304 +	    For example, a group-writable home or <filename
  3.1305 +	      role="special" class="directory">.ssh</filename>
  3.1306 +	    directory will often cause this symptom.</para>
  3.1307 +	</listitem>
  3.1308 +	<listitem><para id="x_4ac">The user's <filename
  3.1309 +	      role="special">authorized_keys</filename> file may have
  3.1310 +	    a problem. If anyone other than the user owns or can write
  3.1311 +	    to that file, the ssh daemon will not trust or read
  3.1312 +	    it.</para>
  3.1313 +	</listitem></itemizedlist>
  3.1314 +
  3.1315 +      <para id="x_4ad">In the ideal world, you should be able to run the
  3.1316 +	following command successfully, and it should print exactly
  3.1317 +	one line of output, the current date and time.</para>
  3.1318 +      <programlisting>ssh myserver date</programlisting>
  3.1319 +
  3.1320 +      <para id="x_4ae">If, on your server, you have login scripts that print
  3.1321 +	banners or other junk even when running non-interactive
  3.1322 +	commands like this, you should fix them before you continue,
  3.1323 +	so that they only print output if they're run interactively.
  3.1324 +	Otherwise these banners will at least clutter up Mercurial's
  3.1325 +	output.  Worse, they could potentially cause problems with
  3.1326 +	running Mercurial commands remotely.  Mercurial tries to
  3.1327 +	detect and ignore banners in non-interactive
  3.1328 +	<command>ssh</command> sessions, but it is not foolproof.  (If
  3.1329 +	you're editing your login scripts on your server, the usual
  3.1330 +	way to see if a login script is running in an interactive
  3.1331 +	shell is to check the return code from the command
  3.1332 +	<literal>tty -s</literal>.)</para>
  3.1333 +
  3.1334 +      <para id="x_4af">Once you've verified that plain old ssh is working with
  3.1335 +	your server, the next step is to ensure that Mercurial runs on
  3.1336 +	the server.  The following command should run
  3.1337 +	successfully:</para>
  3.1338 +
  3.1339 +      <programlisting>ssh myserver hg version</programlisting>
  3.1340 +
  3.1341 +      <para id="x_4b0">If you see an error message instead of normal <command
  3.1342 +	  role="hg-cmd">hg version</command> output, this is usually
  3.1343 +	because you haven't installed Mercurial to <filename
  3.1344 +	  class="directory">/usr/bin</filename>.  Don't worry if this
  3.1345 +	is the case; you don't need to do that.  But you should check
  3.1346 +	for a few possible problems.</para>
  3.1347 +      <itemizedlist>
  3.1348 +	<listitem><para id="x_4b1">Is Mercurial really installed on the server at
  3.1349 +	    all?  I know this sounds trivial, but it's worth
  3.1350 +	    checking!</para>
  3.1351 +	</listitem>
  3.1352 +	<listitem><para id="x_4b2">Maybe your shell's search path (usually set
  3.1353 +	    via the <envar>PATH</envar> environment variable) is
  3.1354 +	    simply misconfigured.</para>
  3.1355 +	</listitem>
  3.1356 +	<listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment
  3.1357 +	    variable is only being set to point to the location of the
  3.1358 +	    <command>hg</command> executable if the login session is
  3.1359 +	    interactive.  This can happen if you're setting the path
  3.1360 +	    in the wrong shell login script.  See your shell's
  3.1361 +	    documentation for details.</para>
  3.1362 +	</listitem>
  3.1363 +	<listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment
  3.1364 +	    variable may need to contain the path to the Mercurial
  3.1365 +	    Python modules.  It might not be set at all; it could be
  3.1366 +	    incorrect; or it may be set only if the login is
  3.1367 +	    interactive.</para>
  3.1368 +	</listitem></itemizedlist>
  3.1369 +
  3.1370 +      <para id="x_4b5">If you can run <command role="hg-cmd">hg version</command>
  3.1371 +	over an ssh connection, well done! You've got the server and
  3.1372 +	client sorted out.  You should now be able to use Mercurial to
  3.1373 +	access repositories hosted by that username on that server.
  3.1374 +	If you run into problems with Mercurial and ssh at this point,
  3.1375 +	try using the <option role="hg-opt-global">--debug</option>
  3.1376 +	option to get a clearer picture of what's going on.</para>
  3.1377 +    </sect2>
  3.1378 +    <sect2>
  3.1379 +      <title>Using compression with ssh</title>
  3.1380 +
  3.1381 +      <para id="x_4b6">Mercurial does not compress data when it uses the ssh
  3.1382 +	protocol, because the ssh protocol can transparently compress
  3.1383 +	data.  However, the default behavior of ssh clients is
  3.1384 +	<emphasis>not</emphasis> to request compression.</para>
  3.1385 +
  3.1386 +      <para id="x_4b7">Over any network other than a fast LAN (even a wireless
  3.1387 +	network), using compression is likely to significantly speed
  3.1388 +	up Mercurial's network operations.  For example, over a WAN,
  3.1389 +	someone measured compression as reducing the amount of time
  3.1390 +	required to clone a particularly large repository from 51
  3.1391 +	minutes to 17 minutes.</para>
  3.1392 +
  3.1393 +      <para id="x_4b8">Both <command>ssh</command> and <command>plink</command>
  3.1394 +	accept a <option role="cmd-opt-ssh">-C</option> option which
  3.1395 +	turns on compression.  You can easily edit your <filename
  3.1396 +	  role="special">~/.hgrc</filename> to enable compression for
  3.1397 +	all of Mercurial's uses of the ssh protocol.  Here is how to
  3.1398 +	do so for regular <command>ssh</command> on Unix-like systems,
  3.1399 +	for example.</para>
  3.1400 +      <programlisting>[ui]
  3.1401 +ssh = ssh -C</programlisting>
  3.1402 +
  3.1403 +      <para id="x_4b9">If you use <command>ssh</command> on a
  3.1404 +	Unix-like system, you can configure it to always use
  3.1405 +	compression when talking to your server.  To do this, edit
  3.1406 +	your <filename role="special">.ssh/config</filename> file
  3.1407 +	(which may not yet exist), as follows.</para>
  3.1408 +
  3.1409 +      <programlisting>Host hg
  3.1410 +  Compression yes
  3.1411 +  HostName hg.example.com</programlisting>
  3.1412 +
  3.1413 +      <para id="x_4ba">This defines a hostname alias,
  3.1414 +	<literal>hg</literal>.  When you use that hostname on the
  3.1415 +	<command>ssh</command> command line or in a Mercurial
  3.1416 +	<literal>ssh</literal>-protocol URL, it will cause
  3.1417 +	<command>ssh</command> to connect to
  3.1418 +	<literal>hg.example.com</literal> and use compression.  This
  3.1419 +	gives you both a shorter name to type and compression, each of
  3.1420 +	which is a good thing in its own right.</para>
  3.1421 +    </sect2>
  3.1422 +  </sect1>
  3.1423 +
  3.1424 +  <sect1 id="sec:collab:cgi">
  3.1425 +    <title>Serving over HTTP using CGI</title>
  3.1426 +
  3.1427 +    <para id="x_6a8">The simplest way to host one or more repositories in a
  3.1428 +      permanent way is to use a web server and Mercurial's CGI
  3.1429 +      support.</para>
  3.1430 +
  3.1431 +    <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
  3.1432 +      CGI interface can take anything from a few moments to several
  3.1433 +      hours.</para>
  3.1434 +
  3.1435 +    <para id="x_4bc">We'll begin with the simplest of examples, and work our way
  3.1436 +      towards a more complex configuration.  Even for the most basic
  3.1437 +      case, you're almost certainly going to need to read and modify
  3.1438 +      your web server's configuration.</para>
  3.1439 +
  3.1440 +    <note>
  3.1441 +      <title>High pain tolerance required</title>
  3.1442 +
  3.1443 +      <para id="x_4bd">Configuring a web server is a complex, fiddly,
  3.1444 +	and highly system-dependent activity.  I can't possibly give
  3.1445 +	you instructions that will cover anything like all of the
  3.1446 +	cases you will encounter. Please use your discretion and
  3.1447 +	judgment in following the sections below.  Be prepared to make
  3.1448 +	plenty of mistakes, and to spend a lot of time reading your
  3.1449 +	server's error logs.</para>
  3.1450 +
  3.1451 +      <para id="x_6a9">If you don't have a strong stomach for tweaking
  3.1452 +	configurations over and over, or a compelling need to host
  3.1453 +	your own services, you might want to try one of the public
  3.1454 +	hosting services that I mentioned earlier.</para>
  3.1455 +    </note>
  3.1456 +
  3.1457 +    <sect2>
  3.1458 +      <title>Web server configuration checklist</title>
  3.1459 +
  3.1460 +      <para id="x_4be">Before you continue, do take a few moments to check a few
  3.1461 +	aspects of your system's setup.</para>
  3.1462 +
  3.1463 +      <orderedlist>
  3.1464 +	<listitem><para id="x_4bf">Do you have a web server installed
  3.1465 +	    at all? Mac OS X and some Linux distributions ship with
  3.1466 +	    Apache, but many other systems may not have a web server
  3.1467 +	    installed.</para>
  3.1468 +	</listitem>
  3.1469 +	<listitem><para id="x_4c0">If you have a web server installed, is it
  3.1470 +	    actually running?  On most systems, even if one is
  3.1471 +	    present, it will be disabled by default.</para>
  3.1472 +	</listitem>
  3.1473 +	<listitem><para id="x_4c1">Is your server configured to allow you to run
  3.1474 +	    CGI programs in the directory where you plan to do so?
  3.1475 +	    Most servers default to explicitly disabling the ability
  3.1476 +	    to run CGI programs.</para>
  3.1477 +	</listitem></orderedlist>
  3.1478 +
  3.1479 +      <para id="x_4c2">If you don't have a web server installed, and don't have
  3.1480 +	substantial experience configuring Apache, you should consider
  3.1481 +	using the <literal>lighttpd</literal> web server instead of
  3.1482 +	Apache.  Apache has a well-deserved reputation for baroque and
  3.1483 +	confusing configuration. While <literal>lighttpd</literal> is
  3.1484 +	less capable in some ways than Apache, most of these
  3.1485 +	capabilities are not relevant to serving Mercurial
  3.1486 +	repositories.  And <literal>lighttpd</literal> is undeniably
  3.1487 +	<emphasis>much</emphasis> easier to get started with than
  3.1488 +	Apache.</para>
  3.1489 +    </sect2>
  3.1490 +
  3.1491 +    <sect2>
  3.1492 +      <title>Basic CGI configuration</title>
  3.1493 +
  3.1494 +      <para id="x_4c3">On Unix-like systems, it's common for users to have a
  3.1495 +	subdirectory named something like <filename
  3.1496 +	  class="directory">public_html</filename> in their home
  3.1497 +	directory, from which they can serve up web pages.  A file
  3.1498 +	named <filename>foo</filename> in this directory will be
  3.1499 +	accessible at a URL of the form
  3.1500 +	<literal>http://www.example.com/username/foo</literal>.</para>
  3.1501 +
  3.1502 +      <para id="x_4c4">To get started, find the <filename
  3.1503 +	  role="special">hgweb.cgi</filename> script that should be
  3.1504 +	present in your Mercurial installation.  If you can't quickly
  3.1505 +	find a local copy on your system, simply download one from the
  3.1506 +	master Mercurial repository at <ulink
  3.1507 +	  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>
  3.1508 +
  3.1509 +      <para id="x_4c5">You'll need to copy this script into your <filename
  3.1510 +	  class="directory">public_html</filename> directory, and
  3.1511 +	ensure that it's executable.</para>
  3.1512 +      <programlisting>cp .../hgweb.cgi ~/public_html
  3.1513 +chmod 755 ~/public_html/hgweb.cgi</programlisting>
  3.1514 +      <para id="x_4c6">The <literal>755</literal> argument to
  3.1515 +	<command>chmod</command> is a little more general than just
  3.1516 +	making the script executable: it ensures that the script is
  3.1517 +	executable by anyone, and that <quote>group</quote> and
  3.1518 +	<quote>other</quote> write permissions are
  3.1519 +	<emphasis>not</emphasis> set.  If you were to leave those
  3.1520 +	write permissions enabled, Apache's <literal>suexec</literal>
  3.1521 +	subsystem would likely refuse to execute the script.  In fact,
  3.1522 +	<literal>suexec</literal> also insists that the
  3.1523 +	<emphasis>directory</emphasis> in which the script resides
  3.1524 +	must not be writable by others.</para>
  3.1525 +      <programlisting>chmod 755 ~/public_html</programlisting>
  3.1526 +
  3.1527 +      <sect3 id="sec:collab:wtf">
  3.1528 +	<title>What could <emphasis>possibly</emphasis> go
  3.1529 +	  wrong?</title>
  3.1530 +
  3.1531 +	<para id="x_4c7">Once you've copied the CGI script into place,
  3.1532 +	  go into a web browser, and try to open the URL
  3.1533 +	  <literal>http://myhostname/~myuser/hgweb.cgi</literal>,
  3.1534 +	  <emphasis>but</emphasis> brace yourself for instant failure.
  3.1535 +	  There's a high probability that trying to visit this URL
  3.1536 +	  will fail, and there are many possible reasons for this.  In
  3.1537 +	  fact, you're likely to stumble over almost every one of the
  3.1538 +	  possible errors below, so please read carefully.  The
  3.1539 +	  following are all of the problems I ran into on a system
  3.1540 +	  running Fedora 7, with a fresh installation of Apache, and a
  3.1541 +	  user account that I created specially to perform this
  3.1542 +	  exercise.</para>
  3.1543 +
  3.1544 +	<para id="x_4c8">Your web server may have per-user directories disabled.
  3.1545 +	  If you're using Apache, search your config file for a
  3.1546 +	  <literal>UserDir</literal> directive.  If there's none
  3.1547 +	  present, per-user directories will be disabled.  If one
  3.1548 +	  exists, but its value is <literal>disabled</literal>, then
  3.1549 +	  per-user directories will be disabled.  Otherwise, the
  3.1550 +	  string after <literal>UserDir</literal> gives the name of
  3.1551 +	  the subdirectory that Apache will look in under your home
  3.1552 +	  directory, for example <filename
  3.1553 +	    class="directory">public_html</filename>.</para>
  3.1554 +
  3.1555 +	<para id="x_4c9">Your file access permissions may be too restrictive.
  3.1556 +	  The web server must be able to traverse your home directory
  3.1557 +	  and directories under your <filename
  3.1558 +	    class="directory">public_html</filename> directory, and
  3.1559 +	  read files under the latter too.  Here's a quick recipe to
  3.1560 +	  help you to make your permissions more appropriate.</para>
  3.1561 +	<programlisting>chmod 755 ~
  3.1562 +find ~/public_html -type d -print0 | xargs -0r chmod 755
  3.1563 +find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting>
  3.1564 +
  3.1565 +	<para id="x_4ca">The other possibility with permissions is that you might
  3.1566 +	  get a completely empty window when you try to load the
  3.1567 +	  script.  In this case, it's likely that your access
  3.1568 +	  permissions are <emphasis>too permissive</emphasis>.  Apache's
  3.1569 +	  <literal>suexec</literal> subsystem won't execute a script
  3.1570 +	  that's group- or world-writable, for example.</para>
  3.1571 +
  3.1572 +	<para id="x_4cb">Your web server may be configured to disallow execution
  3.1573 +	  of CGI programs in your per-user web directory.  Here's
  3.1574 +	  Apache's default per-user configuration from my Fedora
  3.1575 +	  system.</para>
  3.1576 +
  3.1577 +	&ch06-apache-config.lst;
  3.1578 +
  3.1579 +	<para id="x_4cc">If you find a similar-looking
  3.1580 +	  <literal>Directory</literal> group in your Apache
  3.1581 +	  configuration, the directive to look at inside it is
  3.1582 +	  <literal>Options</literal>. Add <literal>ExecCGI</literal>
  3.1583 +	  to the end of this list if it's missing, and restart the web
  3.1584 +	  server.</para>
  3.1585 +
  3.1586 +	<para id="x_4cd">If you find that Apache serves you the text of the CGI
  3.1587 +	  script instead of executing it, you may need to either
  3.1588 +	  uncomment (if already present) or add a directive like
  3.1589 +	  this.</para>
  3.1590 +	<programlisting>AddHandler cgi-script .cgi</programlisting>
  3.1591 +
  3.1592 +	<para id="x_4ce">The next possibility is that you might be served with a
  3.1593 +	  colourful Python backtrace claiming that it can't import a
  3.1594 +	  <literal>mercurial</literal>-related module.  This is
  3.1595 +	  actually progress!  The server is now capable of executing
  3.1596 +	  your CGI script.  This error is only likely to occur if
  3.1597 +	  you're running a private installation of Mercurial, instead
  3.1598 +	  of a system-wide version.  Remember that the web server runs
  3.1599 +	  the CGI program without any of the environment variables
  3.1600 +	  that you take for granted in an interactive session.  If
  3.1601 +	  this error happens to you, edit your copy of <filename
  3.1602 +	    role="special">hgweb.cgi</filename> and follow the
  3.1603 +	  directions inside it to correctly set your
  3.1604 +	  <envar>PYTHONPATH</envar> environment variable.</para>
  3.1605 +
  3.1606 +	<para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be
  3.1607 +	  served with another colourful Python backtrace: this one
  3.1608 +	  will complain that it can't find <filename
  3.1609 +	    class="directory">/path/to/repository</filename>.  Edit
  3.1610 +	  your <filename role="special">hgweb.cgi</filename> script
  3.1611 +	  and replace the <filename
  3.1612 +	    class="directory">/path/to/repository</filename> string
  3.1613 +	  with the complete path to the repository you want to serve
  3.1614 +	  up.</para>
  3.1615 +
  3.1616 +	<para id="x_4d0">At this point, when you try to reload the page, you
  3.1617 +	  should be presented with a nice HTML view of your
  3.1618 +	  repository's history.  Whew!</para>
  3.1619 +      </sect3>
  3.1620 +
  3.1621 +      <sect3>
  3.1622 +	<title>Configuring lighttpd</title>
  3.1623 +
  3.1624 +	<para id="x_4d1">To be exhaustive in my experiments, I tried configuring
  3.1625 +	  the increasingly popular <literal>lighttpd</literal> web
  3.1626 +	  server to serve the same repository as I described with
  3.1627 +	  Apache above.  I had already overcome all of the problems I
  3.1628 +	  outlined with Apache, many of which are not server-specific.
  3.1629 +	  As a result, I was fairly sure that my file and directory
  3.1630 +	  permissions were good, and that my <filename
  3.1631 +	    role="special">hgweb.cgi</filename> script was properly
  3.1632 +	  edited.</para>
  3.1633 +
  3.1634 +	<para id="x_4d2">Once I had Apache running, getting
  3.1635 +	  <literal>lighttpd</literal> to serve the repository was a
  3.1636 +	  snap (in other words, even if you're trying to use
  3.1637 +	  <literal>lighttpd</literal>, you should read the Apache
  3.1638 +	  section).  I first had to edit the
  3.1639 +	  <literal>mod_access</literal> section of its config file to
  3.1640 +	  enable <literal>mod_cgi</literal> and
  3.1641 +	  <literal>mod_userdir</literal>, both of which were disabled
  3.1642 +	  by default on my system.  I then added a few lines to the
  3.1643 +	  end of the config file, to configure these modules.</para>
  3.1644 +	<programlisting>userdir.path = "public_html"
  3.1645 +cgi.assign = (".cgi" =&gt; "" )</programlisting>
  3.1646 +	<para id="x_4d3">With this done, <literal>lighttpd</literal> ran
  3.1647 +	  immediately for me.  If I had configured
  3.1648 +	  <literal>lighttpd</literal> before Apache, I'd almost
  3.1649 +	  certainly have run into many of the same system-level
  3.1650 +	  configuration problems as I did with Apache.  However, I
  3.1651 +	  found <literal>lighttpd</literal> to be noticeably easier to
  3.1652 +	  configure than Apache, even though I've used Apache for over
  3.1653 +	  a decade, and this was my first exposure to
  3.1654 +	  <literal>lighttpd</literal>.</para>
  3.1655 +      </sect3>
  3.1656 +    </sect2>
  3.1657 +
  3.1658 +    <sect2>
  3.1659 +      <title>Sharing multiple repositories with one CGI script</title>
  3.1660 +
  3.1661 +      <para id="x_4d4">The <filename role="special">hgweb.cgi</filename> script
  3.1662 +	only lets you publish a single repository, which is an
  3.1663 +	annoying restriction.  If you want to publish more than one
  3.1664 +	without wracking yourself with multiple copies of the same
  3.1665 +	script, each with different names, a better choice is to use
  3.1666 +	the <filename role="special">hgwebdir.cgi</filename>
  3.1667 +	script.</para>
  3.1668 +
  3.1669 +      <para id="x_4d5">The procedure to configure <filename
  3.1670 +	  role="special">hgwebdir.cgi</filename> is only a little more
  3.1671 +	involved than for <filename
  3.1672 +	  role="special">hgweb.cgi</filename>.  First, you must obtain
  3.1673 +	a copy of the script.  If you don't have one handy, you can
  3.1674 +	download a copy from the master Mercurial repository at <ulink
  3.1675 +	  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>
  3.1676 +
  3.1677 +      <para id="x_4d6">You'll need to copy this script into your <filename
  3.1678 +	  class="directory">public_html</filename> directory, and
  3.1679 +	ensure that it's executable.</para>
  3.1680 +
  3.1681 +      <programlisting>cp .../hgwebdir.cgi ~/public_html
  3.1682 +chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
  3.1683 +
  3.1684 +      <para id="x_4d7">With basic configuration out of the way, try to
  3.1685 +	visit <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>
  3.1686 +	in your	browser.  It should
  3.1687 +	display an empty list of repositories.  If you get a blank
  3.1688 +	window or error message, try walking through the list of
  3.1689 +	potential problems in <xref
  3.1690 +	  linkend="sec:collab:wtf"/>.</para>
  3.1691 +
  3.1692 +      <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename>
  3.1693 +	script relies on an external configuration file.  By default,
  3.1694 +	it searches for a file named <filename
  3.1695 +	  role="special">hgweb.config</filename> in the same directory
  3.1696 +	as itself.  You'll need to create this file, and make it
  3.1697 +	world-readable.  The format of the file is similar to a
  3.1698 +	Windows <quote>ini</quote> file, as understood by Python's
  3.1699 +	<literal>ConfigParser</literal>
  3.1700 +	<citation>web:configparser</citation> module.</para>
  3.1701 +
  3.1702 +      <para id="x_4d9">The easiest way to configure <filename
  3.1703 +	  role="special">hgwebdir.cgi</filename> is with a section
  3.1704 +	named <literal>collections</literal>.  This will automatically
  3.1705 +	publish <emphasis>every</emphasis> repository under the
  3.1706 +	directories you name.  The section should look like
  3.1707 +	this:</para>
  3.1708 +      <programlisting>[collections]
  3.1709 +/my/root = /my/root</programlisting>
  3.1710 +      <para id="x_4da">Mercurial interprets this by looking at the directory name
  3.1711 +	on the <emphasis>right</emphasis> hand side of the
  3.1712 +	<quote><literal>=</literal></quote> sign; finding repositories
  3.1713 +	in that directory hierarchy; and using the text on the
  3.1714 +	<emphasis>left</emphasis> to strip off matching text from the
  3.1715 +	names it will actually list in the web interface.  The
  3.1716 +	remaining component of a path after this stripping has
  3.1717 +	occurred is called a <quote>virtual path</quote>.</para>
  3.1718 +
  3.1719 +      <para id="x_4db">Given the example above, if we have a
  3.1720 +	repository whose local path is <filename
  3.1721 +	  class="directory">/my/root/this/repo</filename>, the CGI
  3.1722 +	script will strip the leading <filename
  3.1723 +	  class="directory">/my/root</filename> from the name, and
  3.1724 +	publish the repository with a virtual path of <filename
  3.1725 +	  class="directory">this/repo</filename>.  If the base URL for
  3.1726 +	our CGI script is
  3.1727 +	<literal>http://myhostname/~myuser/hgwebdir.cgi</literal>, the
  3.1728 +	complete URL for that repository will be
  3.1729 +	<literal>http://myhostname/~myuser/hgwebdir.cgi/this/repo</literal>.</para>
  3.1730 +
  3.1731 +      <para id="x_4dc">If we replace <filename
  3.1732 +	  class="directory">/my/root</filename> on the left hand side
  3.1733 +	of this example with <filename
  3.1734 +	  class="directory">/my</filename>, then <filename
  3.1735 +	  role="special">hgwebdir.cgi</filename> will only strip off
  3.1736 +	<filename class="directory">/my</filename> from the repository
  3.1737 +	name, and will give us a virtual path of <filename
  3.1738 +	  class="directory">root/this/repo</filename> instead of
  3.1739 +	<filename class="directory">this/repo</filename>.</para>
  3.1740 +
  3.1741 +      <para id="x_4dd">The <filename role="special">hgwebdir.cgi</filename>
  3.1742 +	script will recursively search each directory listed in the
  3.1743 +	<literal>collections</literal> section of its configuration
  3.1744 +	file, but it will <literal>not</literal> recurse into the
  3.1745 +	repositories it finds.</para>
  3.1746 +
  3.1747 +      <para id="x_4de">The <literal>collections</literal> mechanism makes it easy
  3.1748 +	to publish many repositories in a <quote>fire and
  3.1749 +	  forget</quote> manner.  You only need to set up the CGI
  3.1750 +	script and configuration file one time.  Afterwards, you can
  3.1751 +	publish or unpublish a repository at any time by simply moving
  3.1752 +	it into, or out of, the directory hierarchy in which you've
  3.1753 +	configured <filename role="special">hgwebdir.cgi</filename> to
  3.1754 +	look.</para>
  3.1755 +
  3.1756 +      <sect3>
  3.1757 +	<title>Explicitly specifying which repositories to
  3.1758 +	  publish</title>
  3.1759 +
  3.1760 +	<para id="x_4df">In addition to the <literal>collections</literal>
  3.1761 +	  mechanism, the <filename
  3.1762 +	    role="special">hgwebdir.cgi</filename> script allows you
  3.1763 +	  to publish a specific list of repositories.  To do so,
  3.1764 +	  create a <literal>paths</literal> section, with contents of
  3.1765 +	  the following form.</para>
  3.1766 +	<programlisting>[paths]
  3.1767 +repo1 = /my/path/to/some/repo
  3.1768 +repo2 = /some/path/to/another</programlisting>
  3.1769 +	<para id="x_4e0">In this case, the virtual path (the component that will
  3.1770 +	  appear in a URL) is on the left hand side of each
  3.1771 +	  definition, while the path to the repository is on the
  3.1772 +	  right.  Notice that there does not need to be any
  3.1773 +	  relationship between the virtual path you choose and the
  3.1774 +	  location of a repository in your filesystem.</para>
  3.1775 +
  3.1776 +	<para id="x_4e1">If you wish, you can use both the
  3.1777 +	  <literal>collections</literal> and <literal>paths</literal>
  3.1778 +	  mechanisms simultaneously in a single configuration
  3.1779 +	  file.</para>
  3.1780 +
  3.1781 +	<note>
  3.1782 +	  <title>Beware duplicate virtual paths</title>
  3.1783 +
  3.1784 +	  <para id="x_4e2">  If several repositories have the same
  3.1785 +	    virtual path, <filename
  3.1786 +	      role="special">hgwebdir.cgi</filename> will not report
  3.1787 +	    an error.  Instead, it will behave unpredictably.</para>
  3.1788 +	</note>
  3.1789 +      </sect3>
  3.1790 +    </sect2>
  3.1791 +
  3.1792 +    <sect2>
  3.1793 +      <title>Downloading source archives</title>
  3.1794 +
  3.1795 +      <para id="x_4e3">Mercurial's web interface lets users download an archive
  3.1796 +	of any revision.  This archive will contain a snapshot of the
  3.1797 +	working directory as of that revision, but it will not contain
  3.1798 +	a copy of the repository data.</para>
  3.1799 +
  3.1800 +      <para id="x_4e4">By default, this feature is not enabled.  To enable it,
  3.1801 +	you'll need to add an <envar
  3.1802 +	  role="rc-item-web">allow_archive</envar> item to the
  3.1803 +	<literal role="rc-web">web</literal> section of your <filename
  3.1804 +	  role="special">~/.hgrc</filename>; see below for details.</para>
  3.1805 +    </sect2>
  3.1806 +    <sect2>
  3.1807 +      <title>Web configuration options</title>
  3.1808 +
  3.1809 +      <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd">hg
  3.1810 +	  serve</command> command, and the <filename
  3.1811 +	  role="special">hgweb.cgi</filename> and <filename
  3.1812 +	  role="special">hgwebdir.cgi</filename> scripts) have a
  3.1813 +	number of configuration options that you can set.  These
  3.1814 +	belong in a section named <literal
  3.1815 +	  role="rc-web">web</literal>.</para>
  3.1816 +      <itemizedlist>
  3.1817 +	<listitem><para id="x_4e6"><envar
  3.1818 +	      role="rc-item-web">allow_archive</envar>: Determines
  3.1819 +	    which (if any) archive download mechanisms Mercurial
  3.1820 +	    supports.  If you enable this feature, users of the web
  3.1821 +	    interface will be able to download an archive of whatever
  3.1822 +	    revision of a repository they are viewing. To enable the
  3.1823 +	    archive feature, this item must take the form of a
  3.1824 +	    sequence of words drawn from the list below.</para>
  3.1825 +	  <itemizedlist>
  3.1826 +	    <listitem><para id="x_4e7"><literal>bz2</literal>: A
  3.1827 +		<command>tar</command> archive, compressed using
  3.1828 +		<literal>bzip2</literal> compression.  This has the
  3.1829 +		best compression ratio, but uses the most CPU time on
  3.1830 +		the server.</para>
  3.1831 +	    </listitem>
  3.1832 +	    <listitem><para id="x_4e8"><literal>gz</literal>: A
  3.1833 +		<command>tar</command> archive, compressed using
  3.1834 +		<literal>gzip</literal> compression.</para>
  3.1835 +	    </listitem>
  3.1836 +	    <listitem><para id="x_4e9"><literal>zip</literal>: A
  3.1837 +		<command>zip</command> archive, compressed using LZW
  3.1838 +		compression.  This format has the worst compression
  3.1839 +		ratio, but is widely used in the Windows world.</para>
  3.1840 +	    </listitem>
  3.1841 +	  </itemizedlist>
  3.1842 +	  <para id="x_4ea">  If you provide an empty list, or don't have an
  3.1843 +	    <envar role="rc-item-web">allow_archive</envar> entry at
  3.1844 +	    all, this feature will be disabled.  Here is an example of
  3.1845 +	    how to enable all three supported formats.</para>
  3.1846 +	  <programlisting>[web]
  3.1847 +allow_archive = bz2 gz zip</programlisting>
  3.1848 +	</listitem>
  3.1849 +	<listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>:
  3.1850 +	    Boolean.  Determines whether the web interface allows
  3.1851 +	    remote users to <command role="hg-cmd">hg pull</command>
  3.1852 +	    and <command role="hg-cmd">hg clone</command> this
  3.1853 +	    repository over HTTP.  If set to <literal>no</literal> or
  3.1854 +	    <literal>false</literal>, only the
  3.1855 +	    <quote>human-oriented</quote> portion of the web interface
  3.1856 +	    is available.</para>
  3.1857 +	</listitem>
  3.1858 +	<listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>:
  3.1859 +	    String.  A free-form (but preferably brief) string
  3.1860 +	    identifying the person or group in charge of the
  3.1861 +	    repository.  This often contains the name and email
  3.1862 +	    address of a person or mailing list.  It often makes sense
  3.1863 +	    to place this entry in a repository's own <filename
  3.1864 +	      role="special">.hg/hgrc</filename> file, but it can make
  3.1865 +	    sense to use in a global <filename
  3.1866 +	      role="special">~/.hgrc</filename> if every repository
  3.1867 +	    has a single maintainer.</para>
  3.1868 +	</listitem>
  3.1869 +	<listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>:
  3.1870 +	    Integer.  The default maximum number of changesets to
  3.1871 +	    display in a single page of output.</para>
  3.1872 +	</listitem>
  3.1873 +	<listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>:
  3.1874 +	    Integer.  The default maximum number of modified files to
  3.1875 +	    display in a single page of output.</para>
  3.1876 +	</listitem>
  3.1877 +	<listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>:
  3.1878 +	    Integer.  If the web interface displays alternating
  3.1879 +	    <quote>stripes</quote> to make it easier to visually align
  3.1880 +	    rows when you are looking at a table, this number controls
  3.1881 +	    the number of rows in each stripe.</para>
  3.1882 +	</listitem>
  3.1883 +	<listitem><para id="x_4f0"><envar
  3.1884 +	      role="rc-item-web">style</envar>: Controls the template
  3.1885 +	    Mercurial uses to display the web interface.  Mercurial
  3.1886 +	    ships with several web templates.</para>
  3.1887 +	  <itemizedlist>
  3.1888 +	    <listitem>
  3.1889 +	      <para id="x_6aa"><literal>coal</literal> is monochromatic.</para>
  3.1890 +	    </listitem>
  3.1891 +	    <listitem>
  3.1892 +	      <para id="x_6ab"><literal>gitweb</literal> emulates the visual
  3.1893 +		style of git's web interface.</para>
  3.1894 +	    </listitem>
  3.1895 +	    <listitem>
  3.1896 +	      <para id="x_6ac"><literal>monoblue</literal> uses solid blues and
  3.1897 +		greys.</para>
  3.1898 +	    </listitem>
  3.1899 +	    <listitem>
  3.1900 +	      <para id="x_6ad"><literal>paper</literal> is the default.</para>
  3.1901 +	    </listitem>
  3.1902 +	    <listitem>
  3.1903 +	      <para id="x_6ae"><literal>spartan</literal> was the default for a
  3.1904 +		long time.</para>
  3.1905 +	    </listitem>
  3.1906 +	  </itemizedlist>
  3.1907 +	  <para id="x_6af">You can
  3.1908 +	    also specify a custom template of your own; see 
  3.1909 +	    <xref linkend="chap:template"/> for details. Here, you can
  3.1910 +	    see how to enable the <literal>gitweb</literal>
  3.1911 +	    style.</para>
  3.1912 +	  <programlisting>[web]
  3.1913 +style = gitweb</programlisting>
  3.1914 +	</listitem>
  3.1915 +	<listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>:
  3.1916 +	    Path.  The directory in which to search for template
  3.1917 +	    files.  By default, Mercurial searches in the directory in
  3.1918 +	    which it was installed.</para>
  3.1919 +	</listitem></itemizedlist>
  3.1920 +      <para id="x_4f2">If you are using <filename
  3.1921 +	  role="special">hgwebdir.cgi</filename>, you can place a few
  3.1922 +	configuration items in a <literal role="rc-web">web</literal>
  3.1923 +	section of the <filename
  3.1924 +	  role="special">hgweb.config</filename> file instead of a
  3.1925 +	<filename role="special">~/.hgrc</filename> file, for
  3.1926 +	convenience.  These items are <envar
  3.1927 +	  role="rc-item-web">motd</envar> and <envar
  3.1928 +	  role="rc-item-web">style</envar>.</para>
  3.1929 +
  3.1930 +      <sect3>
  3.1931 +	<title>Options specific to an individual repository</title>
  3.1932 +
  3.1933 +	<para id="x_4f3">A few <literal role="rc-web">web</literal> configuration
  3.1934 +	  items ought to be placed in a repository's local <filename
  3.1935 +	    role="special">.hg/hgrc</filename>, rather than a user's
  3.1936 +	  or global <filename role="special">~/.hgrc</filename>.</para>
  3.1937 +	<itemizedlist>
  3.1938 +	  <listitem><para id="x_4f4"><envar
  3.1939 +		role="rc-item-web">description</envar>: String.  A
  3.1940 +	      free-form (but preferably brief) string that describes
  3.1941 +	      the contents or purpose of the repository.</para>
  3.1942 +	  </listitem>
  3.1943 +	  <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>:
  3.1944 +	      String.  The name to use for the repository in the web
  3.1945 +	      interface.  This overrides the default name, which is
  3.1946 +	      the last component of the repository's path.</para>
  3.1947 +	  </listitem></itemizedlist>
  3.1948 +      </sect3>
  3.1949 +
  3.1950 +      <sect3>
  3.1951 +	<title>Options specific to the <command role="hg-cmd">hg
  3.1952 +	    serve</command> command</title>
  3.1953 +
  3.1954 +	<para id="x_4f6">Some of the items in the <literal
  3.1955 +	    role="rc-web">web</literal> section of a <filename
  3.1956 +	    role="special">~/.hgrc</filename> file are only for use
  3.1957 +	  with the <command role="hg-cmd">hg serve</command>
  3.1958 +	  command.</para>
  3.1959 +	<itemizedlist>
  3.1960 +	  <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>:
  3.1961 +	      Path.  The name of a file into which to write an access
  3.1962 +	      log.  By default, the <command role="hg-cmd">hg
  3.1963 +		serve</command> command writes this information to
  3.1964 +	      standard output, not to a file.  Log entries are written
  3.1965 +	      in the standard <quote>combined</quote> file format used
  3.1966 +	      by almost all web servers.</para>
  3.1967 +	  </listitem>
  3.1968 +	  <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>:
  3.1969 +	      String.  The local address on which the server should
  3.1970 +	      listen for incoming connections.  By default, the server
  3.1971 +	      listens on all addresses.</para>
  3.1972 +	  </listitem>
  3.1973 +	  <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>:
  3.1974 +	      Path.  The name of a file into which to write an error
  3.1975 +	      log.  By default, the <command role="hg-cmd">hg
  3.1976 +		serve</command> command writes this information to
  3.1977 +	      standard error, not to a file.</para>
  3.1978 +	  </listitem>
  3.1979 +	  <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>:
  3.1980 +	      Boolean.  Whether to use the IPv6 protocol. By default,
  3.1981 +	      IPv6 is not used.</para>
  3.1982 +	  </listitem>
  3.1983 +	  <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>:
  3.1984 +	      Integer.  The TCP port number on which the server should
  3.1985 +	      listen.  The default port number used is 8000.</para>
  3.1986 +	  </listitem></itemizedlist>
  3.1987 +      </sect3>
  3.1988 +
  3.1989 +      <sect3>
  3.1990 +	<title>Choosing the right <filename
  3.1991 +	    role="special">~/.hgrc</filename> file to add <literal
  3.1992 +	    role="rc-web">web</literal> items to</title>
  3.1993 +
  3.1994 +	<para id="x_4fc">It is important to remember that a web server like
  3.1995 +	  Apache or <literal>lighttpd</literal> will run under a user
  3.1996 +	  ID that is different to yours. CGI scripts run by your
  3.1997 +	  server, such as <filename
  3.1998 +	    role="special">hgweb.cgi</filename>, will usually also run
  3.1999 +	  under that user ID.</para>
  3.2000 +
  3.2001 +	<para id="x_4fd">If you add <literal role="rc-web">web</literal> items to
  3.2002 +	  your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that
  3.2003 +	  <filename role="special">~/.hgrc</filename> file.  Those
  3.2004 +	  settings will thus only affect the behavior of the <command
  3.2005 +	    role="hg-cmd">hg serve</command> command when you run it.
  3.2006 +	  To cause CGI scripts to see your settings, either create a
  3.2007 +	  <filename role="special">~/.hgrc</filename> file in the
  3.2008 +	  home directory of the user ID that runs your web server, or
  3.2009 +	  add those settings to a system-wide <filename
  3.2010 +	    role="special">hgrc</filename> file.</para>
  3.2011 +      </sect3>
  3.2012 +    </sect2>
  3.2013 +  </sect1>
  3.2014 +
  3.2015 +  <sect1>
  3.2016 +    <title>System-wide configuration</title>
  3.2017 +
  3.2018 +    <para id="x_6b0">On Unix-like systems shared by multiple users (such as a
  3.2019 +      server to which people publish changes), it often makes sense to
  3.2020 +      set up some global default behaviors, such as what theme to use
  3.2021 +      in web interfaces.</para>
  3.2022 +
  3.2023 +    <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename>
  3.2024 +      exists, Mercurial will read it at startup time and apply any
  3.2025 +      configuration settings it finds in that file.  It will also look
  3.2026 +      for files ending in a <literal>.rc</literal> extension in a
  3.2027 +      directory named <filename>/etc/mercurial/hgrc.d</filename>, and
  3.2028 +      apply any configuration settings it finds in each of those
  3.2029 +      files.</para>
  3.2030 +
  3.2031 +    <sect2>
  3.2032 +      <title>Making Mercurial more trusting</title>
  3.2033 +
  3.2034 +      <para id="x_6b2">One situation in which a global <filename>hgrc</filename>
  3.2035 +	can be useful is if users are pulling changes owned by other
  3.2036 +	users.  By default, Mercurial will not trust most of the
  3.2037 +	configuration items in a <filename>.hg/hgrc</filename> file
  3.2038 +	inside a repository that is owned by a different user. If we
  3.2039 +	clone or pull changes from such a repository, Mercurial will
  3.2040 +	print a warning stating that it does not trust their
  3.2041 +	<filename>.hg/hgrc</filename>.</para>
  3.2042 +
  3.2043 +      <para id="x_6b3">If everyone in a particular Unix group is on the same team
  3.2044 +	and <emphasis>should</emphasis> trust each other's
  3.2045 +	configuration settings, or we want to trust particular users,
  3.2046 +	we can override Mercurial's skeptical defaults by creating a
  3.2047 +	system-wide <filename>hgrc</filename> file such as the
  3.2048 +	following:</para>
  3.2049 +
  3.2050 +    <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
  3.2051 +[trusted]
  3.2052 +# Trust all entries in any hgrc file owned by the "editors" or
  3.2053 +# "www-data" groups.
  3.2054 +groups = editors, www-data
  3.2055 +
  3.2056 +# Trust entries in hgrc files owned by the following users.
  3.2057 +users = apache, bobo
  3.2058  </programlisting>
  3.2059 -<orderedlist>
  3.2060 -<listitem><para>The <quote><literal>ssh://</literal></quote> part tells Mercurial to use the ssh
  3.2061 -  protocol.
  3.2062 -</para>
  3.2063 -</listitem>
  3.2064 -<listitem><para>The <quote><literal>bos@</literal></quote> component indicates what username to log
  3.2065 -  into the server as.  You can leave this out if the remote username
  3.2066 -  is the same as your local username.
  3.2067 -</para>
  3.2068 -</listitem>
  3.2069 -<listitem><para>The <quote><literal>hg.serpentine.com</literal></quote> gives the hostname of the
  3.2070 -  server to log into.
  3.2071 -</para>
  3.2072 -</listitem>
  3.2073 -<listitem><para>The <quote>:22</quote> identifies the port number to connect to the server
  3.2074 -  on.  The default port is 22, so you only need to specify this part
  3.2075 -  if you're <emphasis>not</emphasis> using port 22.
  3.2076 -</para>
  3.2077 -</listitem>
  3.2078 -<listitem><para>The remainder of the URL is the local path to the repository on
  3.2079 -  the server.
  3.2080 -</para>
  3.2081 -</listitem></orderedlist>
  3.2082 -
  3.2083 -<para>There's plenty of scope for confusion with the path component of ssh
  3.2084 -URLs, as there is no standard way for tools to interpret it.  Some
  3.2085 -programs behave differently than others when dealing with these paths.
  3.2086 -This isn't an ideal situation, but it's unlikely to change.  Please
  3.2087 -read the following paragraphs carefully.
  3.2088 -</para>
  3.2089 -
  3.2090 -<para>Mercurial treats the path to a repository on the server as relative to
  3.2091 -the remote user's home directory.  For example, if user <literal>foo</literal>
  3.2092 -on the server has a home directory of <filename class="directory">/home/foo</filename>, then an ssh
  3.2093 -URL that contains a path component of <filename class="directory">bar</filename>
  3.2094 -<emphasis>really</emphasis> refers to the directory <filename class="directory">/home/foo/bar</filename>.
  3.2095 -</para>
  3.2096 -
  3.2097 -<para>If you want to specify a path relative to another user's home
  3.2098 -directory, you can use a path that starts with a tilde character
  3.2099 -followed by the user's name (let's call them <literal>otheruser</literal>), like
  3.2100 -this.
  3.2101 -</para>
  3.2102 -<programlisting>
  3.2103 -<para>  ssh://server/ otheruser/hg/repo
  3.2104 -</para>
  3.2105 -</programlisting>
  3.2106 -
  3.2107 -<para>And if you really want to specify an <emphasis>absolute</emphasis> path on the
  3.2108 -server, begin the path component with two slashes, as in this example.
  3.2109 -</para>
  3.2110 -<programlisting>
  3.2111 -<para>  ssh://server//absolute/path
  3.2112 -</para>
  3.2113 -</programlisting>
  3.2114 -
  3.2115 -</sect2>
  3.2116 -<sect2>
  3.2117 -<title>Finding an ssh client for your system</title>
  3.2118 -
  3.2119 -<para>Almost every Unix-like system comes with OpenSSH preinstalled.  If
  3.2120 -you're using such a system, run <literal>which ssh</literal> to find out if
  3.2121 -the <command>ssh</command> command is installed (it's usually in
  3.2122 -<filename class="directory">/usr/bin</filename>).  In the unlikely event that it isn't present,
  3.2123 -take a look at your system documentation to figure out how to install
  3.2124 -it.
  3.2125 -</para>
  3.2126 -
  3.2127 -<para>On Windows, you'll first need to download a suitable ssh
  3.2128 -client.  There are two alternatives.
  3.2129 -</para>
  3.2130 -<itemizedlist>
  3.2131 -<listitem><para>Simon Tatham's excellent PuTTY package <citation>web:putty</citation> provides
  3.2132 -  a complete suite of ssh client commands.
  3.2133 -</para>
  3.2134 -</listitem>
  3.2135 -<listitem><para>If you have a high tolerance for pain, you can use the Cygwin
  3.2136 -  port of OpenSSH.
  3.2137 -</para>
  3.2138 -</listitem></itemizedlist>
  3.2139 -<para>In either case, you'll need to edit your \hgini\ file to tell
  3.2140 -Mercurial where to find the actual client command.  For example, if
  3.2141 -you're using PuTTY, you'll need to use the <command>plink</command> command as
  3.2142 -a command-line ssh client.
  3.2143 -</para>
  3.2144 -<programlisting>
  3.2145 -<para>  [ui]
  3.2146 -  ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"
  3.2147 -</para>
  3.2148 -</programlisting>
  3.2149 -
  3.2150 -<note>
  3.2151 -<para>  The path to <command>plink</command> shouldn't contain any whitespace
  3.2152 -  characters, or Mercurial may not be able to run it correctly (so
  3.2153 -  putting it in <filename class="directory">C:\\Program Files</filename> is probably not a good
  3.2154 -  idea).
  3.2155 -</para>
  3.2156 -</note>
  3.2157 -
  3.2158 -</sect2>
  3.2159 -<sect2>
  3.2160 -<title>Generating a key pair</title>
  3.2161 -
  3.2162 -<para>To avoid the need to repetitively type a password every time you need
  3.2163 -to use your ssh client, I recommend generating a key pair.  On a
  3.2164 -Unix-like system, the <command>ssh-keygen</command> command will do the trick.
  3.2165 -On Windows, if you're using PuTTY, the <command>puttygen</command> command is
  3.2166 -what you'll need.
  3.2167 -</para>
  3.2168 -
  3.2169 -<para>When you generate a key pair, it's usually <emphasis>highly</emphasis> advisable to
  3.2170 -protect it with a passphrase.  (The only time that you might not want
  3.2171 -to do this is when you're using the ssh protocol for automated tasks
  3.2172 -on a secure network.)
  3.2173 -</para>
  3.2174 -
  3.2175 -<para>Simply generating a key pair isn't enough, however.  You'll need to
  3.2176 -add the public key to the set of authorised keys for whatever user
  3.2177 -you're logging in remotely as.  For servers using OpenSSH (the vast
  3.2178 -majority), this will mean adding the public key to a list in a file
  3.2179 -called <filename role="special">authorized_keys</filename> in their <filename role="special" class="directory">.ssh</filename>
  3.2180 -directory.
  3.2181 -</para>
  3.2182 -
  3.2183 -<para>On a Unix-like system, your public key will have a <filename>.pub</filename>
  3.2184 -extension.  If you're using <command>puttygen</command> on Windows, you can
  3.2185 -save the public key to a file of your choosing, or paste it from the
  3.2186 -window it's displayed in straight into the
  3.2187 -<filename role="special">authorized_keys</filename> file.
  3.2188 -</para>
  3.2189 -
  3.2190 -</sect2>
  3.2191 -<sect2>
  3.2192 -<title>Using an authentication agent</title>
  3.2193 -
  3.2194 -<para>An authentication agent is a daemon that stores passphrases in memory
  3.2195 -(so it will forget passphrases if you log out and log back in again).
  3.2196 -An ssh client will notice if it's running, and query it for a
  3.2197 -passphrase.  If there's no authentication agent running, or the agent
  3.2198 -doesn't store the necessary passphrase, you'll have to type your
  3.2199 -passphrase every time Mercurial tries to communicate with a server on
  3.2200 -your behalf (e.g. whenever you pull or push changes).
  3.2201 -</para>
  3.2202 -
  3.2203 -<para>The downside of storing passphrases in an agent is that it's possible
  3.2204 -for a well-prepared attacker to recover the plain text of your
  3.2205 -passphrases, in some cases even if your system has been power-cycled.
  3.2206 -You should make your own judgment as to whether this is an acceptable
  3.2207 -risk.  It certainly saves a lot of repeated typing.
  3.2208 -</para>
  3.2209 -
  3.2210 -<para>On Unix-like systems, the agent is called <command>ssh-agent</command>, and
  3.2211 -it's often run automatically for you when you log in.  You'll need to
  3.2212 -use the <command>ssh-add</command> command to add passphrases to the agent's
  3.2213 -store.  On Windows, if you're using PuTTY, the <command>pageant</command>
  3.2214 -command acts as the agent.  It adds an icon to your system tray that
  3.2215 -will let you manage stored passphrases.
  3.2216 -</para>
  3.2217 -
  3.2218 -</sect2>
  3.2219 -<sect2>
  3.2220 -<title>Configuring the server side properly</title>
  3.2221 -
  3.2222 -<para>Because ssh can be fiddly to set up if you're new to it, there's a
  3.2223 -variety of things that can go wrong.  Add Mercurial on top, and
  3.2224 -there's plenty more scope for head-scratching.  Most of these
  3.2225 -potential problems occur on the server side, not the client side.  The
  3.2226 -good news is that once you've gotten a configuration working, it will
  3.2227 -usually continue to work indefinitely.
  3.2228 -</para>
  3.2229 -
  3.2230 -<para>Before you try using Mercurial to talk to an ssh server, it's best to
  3.2231 -make sure that you can use the normal <command>ssh</command> or <command>putty</command>
  3.2232 -command to talk to the server first.  If you run into problems with
  3.2233 -using these commands directly, Mercurial surely won't work.  Worse, it
  3.2234 -will obscure the underlying problem.  Any time you want to debug
  3.2235 -ssh-related Mercurial problems, you should drop back to making sure
  3.2236 -that plain ssh client commands work first, <emphasis>before</emphasis> you worry
  3.2237 -about whether there's a problem with Mercurial.
  3.2238 -</para>
  3.2239 -
  3.2240 -<para>The first thing to be sure of on the server side is that you can
  3.2241 -actually log in from another machine at all.  If you can't use
  3.2242 -<command>ssh</command> or <command>putty</command> to log in, the error message you get
  3.2243 -may give you a few hints as to what's wrong.  The most common problems
  3.2244 -are as follows.
  3.2245 -</para>
  3.2246 -<itemizedlist>
  3.2247 -<listitem><para>If you get a <quote>connection refused</quote> error, either there isn't an
  3.2248 -  SSH daemon running on the server at all, or it's inaccessible due to
  3.2249 -  firewall configuration.
  3.2250 -</para>
  3.2251 -</listitem>
  3.2252 -<listitem><para>If you get a <quote>no route to host</quote> error, you either have an
  3.2253 -  incorrect address for the server or a seriously locked down firewall
  3.2254 -  that won't admit its existence at all.
  3.2255 -</para>
  3.2256 -</listitem>
  3.2257 -<listitem><para>If you get a <quote>permission denied</quote> error, you may have mistyped
  3.2258 -  the username on the server, or you could have mistyped your key's
  3.2259 -  passphrase or the remote user's password.
  3.2260 -</para>
  3.2261 -</listitem></itemizedlist>
  3.2262 -<para>In summary, if you're having trouble talking to the server's ssh
  3.2263 -daemon, first make sure that one is running at all.  On many systems
  3.2264 -it will be installed, but disabled, by default.  Once you're done with
  3.2265 -this step, you should then check that the server's firewall is
  3.2266 -configured to allow incoming connections on the port the ssh daemon is
  3.2267 -listening on (usually 22).  Don't worry about more exotic
  3.2268 -possibilities for misconfiguration until you've checked these two
  3.2269 -first.
  3.2270 -</para>
  3.2271 -
  3.2272 -<para>If you're using an authentication agent on the client side to store
  3.2273 -passphrases for your keys, you ought to be able to log into the server
  3.2274 -without being prompted for a passphrase or a password.  If you're
  3.2275 -prompted for a passphrase, there are a few possible culprits.
  3.2276 -</para>
  3.2277 -<itemizedlist>
  3.2278 -<listitem><para>You might have forgotten to use <command>ssh-add</command> or
  3.2279 -  <command>pageant</command> to store the passphrase.
  3.2280 -</para>
  3.2281 -</listitem>
  3.2282 -<listitem><para>You might have stored the passphrase for the wrong key.
  3.2283 -</para>
  3.2284 -</listitem></itemizedlist>
  3.2285 -<para>If you're being prompted for the remote user's password, there are
  3.2286 -another few possible problems to check.
  3.2287 -</para>
  3.2288 -<itemizedlist>
  3.2289 -<listitem><para>Either the user's home directory or their <filename role="special" class="directory">.ssh</filename>
  3.2290 -  directory might have excessively liberal permissions.  As a result,
  3.2291 -  the ssh daemon will not trust or read their
  3.2292 -  <filename role="special">authorized_keys</filename> file.  For example, a group-writable
  3.2293 -  home or <filename role="special" class="directory">.ssh</filename> directory will often cause this symptom.
  3.2294 -</para>
  3.2295 -</listitem>
  3.2296 -<listitem><para>The user's <filename role="special">authorized_keys</filename> file may have a problem.
  3.2297 -  If anyone other than the user owns or can write to that file, the
  3.2298 -  ssh daemon will not trust or read it.
  3.2299 -</para>
  3.2300 -</listitem></itemizedlist>
  3.2301 -
  3.2302 -<para>In the ideal world, you should be able to run the following command
  3.2303 -successfully, and it should print exactly one line of output, the
  3.2304 -current date and time.
  3.2305 -</para>
  3.2306 -<programlisting>
  3.2307 -<para>  ssh myserver date
  3.2308 -</para>
  3.2309 -</programlisting>
  3.2310 -
  3.2311 -<para>If, on your server, you have login scripts that print banners or other
  3.2312 -junk even when running non-interactive commands like this, you should
  3.2313 -fix them before you continue, so that they only print output if
  3.2314 -they're run interactively.  Otherwise these banners will at least
  3.2315 -clutter up Mercurial's output.  Worse, they could potentially cause
  3.2316 -problems with running Mercurial commands remotely.  Mercurial makes
  3.2317 -tries to detect and ignore banners in non-interactive <command>ssh</command>
  3.2318 -sessions, but it is not foolproof.  (If you're editing your login
  3.2319 -scripts on your server, the usual way to see if a login script is
  3.2320 -running in an interactive shell is to check the return code from the
  3.2321 -command <literal>tty -s</literal>.)
  3.2322 -</para>
  3.2323 -
  3.2324 -<para>Once you've verified that plain old ssh is working with your server,
  3.2325 -the next step is to ensure that Mercurial runs on the server.  The
  3.2326 -following command should run successfully:
  3.2327 -</para>
  3.2328 -<programlisting>
  3.2329 -<para>  ssh myserver hg version
  3.2330 -</para>
  3.2331 -</programlisting>
  3.2332 -<para>If you see an error message instead of normal <command role="hg-cmd">hg version</command> output,
  3.2333 -this is usually because you haven't installed Mercurial to
  3.2334 -<filename class="directory">/usr/bin</filename>.  Don't worry if this is the case; you don't need
  3.2335 -to do that.  But you should check for a few possible problems.
  3.2336 -</para>
  3.2337 -<itemizedlist>
  3.2338 -<listitem><para>Is Mercurial really installed on the server at all?  I know this
  3.2339 -  sounds trivial, but it's worth checking!
  3.2340 -</para>
  3.2341 -</listitem>
  3.2342 -<listitem><para>Maybe your shell's search path (usually set via the <envar>PATH</envar>
  3.2343 -  environment variable) is simply misconfigured.
  3.2344 -</para>
  3.2345 -</listitem>
  3.2346 -<listitem><para>Perhaps your <envar>PATH</envar> environment variable is only being set
  3.2347 -  to point to the location of the <command>hg</command> executable if the login
  3.2348 -  session is interactive.  This can happen if you're setting the path
  3.2349 -  in the wrong shell login script.  See your shell's documentation for
  3.2350 -  details.
  3.2351 -</para>
  3.2352 -</listitem>
  3.2353 -<listitem><para>The <envar>PYTHONPATH</envar> environment variable may need to contain
  3.2354 -  the path to the Mercurial Python modules.  It might not be set at
  3.2355 -  all; it could be incorrect; or it may be set only if the login is
  3.2356 -  interactive.
  3.2357 -</para>
  3.2358 -</listitem></itemizedlist>
  3.2359 -
  3.2360 -<para>If you can run <command role="hg-cmd">hg version</command> over an ssh connection, well done!
  3.2361 -You've got the server and client sorted out.  You should now be able
  3.2362 -to use Mercurial to access repositories hosted by that username on
  3.2363 -that server.  If you run into problems with Mercurial and ssh at this
  3.2364 -point, try using the <option role="hg-opt-global">--debug</option> option to get a clearer picture
  3.2365 -of what's going on.
  3.2366 -</para>
  3.2367 -
  3.2368 -</sect2>
  3.2369 -<sect2>
  3.2370 -<title>Using compression with ssh</title>
  3.2371 -
  3.2372 -<para>Mercurial does not compress data when it uses the ssh protocol,
  3.2373 -because the ssh protocol can transparently compress data.  However,
  3.2374 -the default behaviour of ssh clients is <emphasis>not</emphasis> to request
  3.2375 -compression.
  3.2376 -</para>
  3.2377 -
  3.2378 -<para>Over any network other than a fast LAN (even a wireless network),
  3.2379 -using compression is likely to significantly speed up Mercurial's
  3.2380 -network operations.  For example, over a WAN, someone measured
  3.2381 -compression as reducing the amount of time required to clone a
  3.2382 -particularly large repository from 51 minutes to 17 minutes.
  3.2383 -</para>
  3.2384 -
  3.2385 -<para>Both <command>ssh</command> and <command>plink</command> accept a <option role="cmd-opt-ssh">-C</option>
  3.2386 -option which turns on compression.  You can easily edit your <filename role="special"> /.hgrc</filename>\ to
  3.2387 -enable compression for all of Mercurial's uses of the ssh protocol.
  3.2388 -</para>
  3.2389 -<programlisting>
  3.2390 -<para>  [ui]
  3.2391 -  ssh = ssh -C
  3.2392 -</para>
  3.2393 -</programlisting>
  3.2394 -
  3.2395 -<para>If you use <command>ssh</command>, you can configure it to always use
  3.2396 -compression when talking to your server.  To do this, edit your
  3.2397 -<filename role="special">.ssh/config</filename> file (which may not yet exist), as follows.
  3.2398 -</para>
  3.2399 -<programlisting>
  3.2400 -<para>  Host hg
  3.2401 -    Compression yes
  3.2402 -    HostName hg.example.com
  3.2403 -</para>
  3.2404 -</programlisting>
  3.2405 -<para>This defines an alias, <literal>hg</literal>.  When you use it on the
  3.2406 -<command>ssh</command> command line or in a Mercurial <literal>ssh</literal>-protocol
  3.2407 -URL, it will cause <command>ssh</command> to connect to <literal>hg.example.com</literal>
  3.2408 -and use compression.  This gives you both a shorter name to type and
  3.2409 -compression, each of which is a good thing in its own right.
  3.2410 -</para>
  3.2411 -
  3.2412 -</sect2>
  3.2413 -</sect1>
  3.2414 -<sect1>
  3.2415 -<title>Serving over HTTP using CGI</title>
  3.2416 -<para>\label{sec:collab:cgi}
  3.2417 -</para>
  3.2418 -
  3.2419 -<para>Depending on how ambitious you are, configuring Mercurial's CGI
  3.2420 -interface can take anything from a few moments to several hours.
  3.2421 -</para>
  3.2422 -
  3.2423 -<para>We'll begin with the simplest of examples, and work our way towards a
  3.2424 -more complex configuration.  Even for the most basic case, you're
  3.2425 -almost certainly going to need to read and modify your web server's
  3.2426 -configuration.
  3.2427 -</para>
  3.2428 -
  3.2429 -<note>
  3.2430 -<para>  Configuring a web server is a complex, fiddly, and highly
  3.2431 -  system-dependent activity.  I can't possibly give you instructions
  3.2432 -  that will cover anything like all of the cases you will encounter.
  3.2433 -  Please use your discretion and judgment in following the sections
  3.2434 -  below.  Be prepared to make plenty of mistakes, and to spend a lot
  3.2435 -  of time reading your server's error logs.
  3.2436 -</para>
  3.2437 -</note>
  3.2438 -
  3.2439 -<sect2>
  3.2440 -<title>Web server configuration checklist</title>
  3.2441 -
  3.2442 -<para>Before you continue, do take a few moments to check a few aspects of
  3.2443 -your system's setup.
  3.2444 -</para>
  3.2445 -
  3.2446 -<orderedlist>
  3.2447 -<listitem><para>Do you have a web server installed at all?  Mac OS X ships with
  3.2448 -  Apache, but many other systems may not have a web server installed.
  3.2449 -</para>
  3.2450 -</listitem>
  3.2451 -<listitem><para>If you have a web server installed, is it actually running?  On
  3.2452 -  most systems, even if one is present, it will be disabled by
  3.2453 -  default.
  3.2454 -</para>
  3.2455 -</listitem>
  3.2456 -<listitem><para>Is your server configured to allow you to run CGI programs in
  3.2457 -  the directory where you plan to do so?  Most servers default to
  3.2458 -  explicitly disabling the ability to run CGI programs.
  3.2459 -</para>
  3.2460 -</listitem></orderedlist>
  3.2461 -
  3.2462 -<para>If you don't have a web server installed, and don't have substantial
  3.2463 -experience configuring Apache, you should consider using the
  3.2464 -<literal>lighttpd</literal> web server instead of Apache.  Apache has a
  3.2465 -well-deserved reputation for baroque and confusing configuration.
  3.2466 -While <literal>lighttpd</literal> is less capable in some ways than Apache, most
  3.2467 -of these capabilities are not relevant to serving Mercurial
  3.2468 -repositories.  And <literal>lighttpd</literal> is undeniably <emphasis>much</emphasis> easier
  3.2469 -to get started with than Apache.
  3.2470 -</para>
  3.2471 -
  3.2472 -</sect2>
  3.2473 -<sect2>
  3.2474 -<title>Basic CGI configuration</title>
  3.2475 -
  3.2476 -<para>On Unix-like systems, it's common for users to have a subdirectory
  3.2477 -named something like <filename class="directory">public_html</filename> in their home directory,
  3.2478 -from which they can serve up web pages.  A file named <filename>foo</filename>
  3.2479 -in this directory will be accessible at a URL of the form
  3.2480 -<literal>http://www.example.com/\ {</literal>username/foo}.
  3.2481 -</para>
  3.2482 -
  3.2483 -<para>To get started, find the <filename role="special">hgweb.cgi</filename> script that should be
  3.2484 -present in your Mercurial installation.  If you can't quickly find a
  3.2485 -local copy on your system, simply download one from the master
  3.2486 -Mercurial repository at
  3.2487 -<ulink url="http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi</ulink>.
  3.2488 -</para>
  3.2489 -
  3.2490 -<para>You'll need to copy this script into your <filename class="directory">public_html</filename>
  3.2491 -directory, and ensure that it's executable.
  3.2492 -</para>
  3.2493 -<programlisting>
  3.2494 -<para>  cp .../hgweb.cgi  /public_html
  3.2495 -  chmod 755  /public_html/hgweb.cgi
  3.2496 -</para>
  3.2497 -</programlisting>
  3.2498 -<para>The <literal>755</literal> argument to <command>chmod</command> is a little more general
  3.2499 -than just making the script executable: it ensures that the script is
  3.2500 -executable by anyone, and that <quote>group</quote> and <quote>other</quote> write
  3.2501 -permissions are <emphasis>not</emphasis> set.  If you were to leave those write
  3.2502 -permissions enabled, Apache's <literal>suexec</literal> subsystem would likely
  3.2503 -refuse to execute the script.  In fact, <literal>suexec</literal> also insists
  3.2504 -that the <emphasis>directory</emphasis> in which the script resides must not be
  3.2505 -writable by others.
  3.2506 -</para>
  3.2507 -<programlisting>
  3.2508 -<para>  chmod 755  /public_html
  3.2509 -</para>
  3.2510 -</programlisting>
  3.2511 -
  3.2512 -<sect3>
  3.2513 -<title>What could <emphasis>possibly</emphasis> go wrong?</title>
  3.2514 -<para>\label{sec:collab:wtf}
  3.2515 -</para>
  3.2516 -
  3.2517 -<para>Once you've copied the CGI script into place, go into a web browser,
  3.2518 -and try to open the URL <ulink url="http://myhostname/ myuser/hgweb.cgi">http://myhostname/ myuser/hgweb.cgi</ulink>,
  3.2519 -<emphasis>but</emphasis> brace yourself for instant failure.  There's a high
  3.2520 -probability that trying to visit this URL will fail, and there are
  3.2521 -many possible reasons for this.  In fact, you're likely to stumble
  3.2522 -over almost every one of the possible errors below, so please read
  3.2523 -carefully.  The following are all of the problems I ran into on a
  3.2524 -system running Fedora 7, with a fresh installation of Apache, and a
  3.2525 -user account that I created specially to perform this exercise.
  3.2526 -</para>
  3.2527 -
  3.2528 -<para>Your web server may have per-user directories disabled.  If you're
  3.2529 -using Apache, search your config file for a <literal>UserDir</literal>
  3.2530 -directive.  If there's none present, per-user directories will be
  3.2531 -disabled.  If one exists, but its value is <literal>disabled</literal>, then
  3.2532 -per-user directories will be disabled.  Otherwise, the string after
  3.2533 -<literal>UserDir</literal> gives the name of the subdirectory that Apache will
  3.2534 -look in under your home directory, for example <filename class="directory">public_html</filename>.
  3.2535 -</para>
  3.2536 -
  3.2537 -<para>Your file access permissions may be too restrictive.  The web server
  3.2538 -must be able to traverse your home directory and directories under
  3.2539 -your <filename class="directory">public_html</filename> directory, and read files under the latter
  3.2540 -too.  Here's a quick recipe to help you to make your permissions more
  3.2541 -appropriate.
  3.2542 -</para>
  3.2543 -<programlisting>
  3.2544 -<para>  chmod 755  
  3.2545 -  find  /public_html -type d -print0 | xargs -0r chmod 755
  3.2546 -  find  /public_html -type f -print0 | xargs -0r chmod 644
  3.2547 -</para>
  3.2548 -</programlisting>
  3.2549 -
  3.2550 -<para>The other possibility with permissions is that you might get a
  3.2551 -completely empty window when you try to load the script.  In this
  3.2552 -case, it's likely that your access permissions are \emph{too
  3.2553 -  permissive}.  Apache's <literal>suexec</literal> subsystem won't execute a
  3.2554 -script that's group- or world-writable, for example.
  3.2555 -</para>
  3.2556 -
  3.2557 -<para>Your web server may be configured to disallow execution of CGI
  3.2558 -programs in your per-user web directory.  Here's Apache's
  3.2559 -default per-user configuration from my Fedora system.
  3.2560 -</para>
  3.2561 -<programlisting>
  3.2562 -<para>  &lt;Directory /home/*/public_html&gt;
  3.2563 -      AllowOverride FileInfo AuthConfig Limit
  3.2564 -      Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
  3.2565 -      &lt;Limit GET POST OPTIONS&gt;
  3.2566 -          Order allow,deny
  3.2567 -          Allow from all
  3.2568 -      &lt;/Limit&gt;
  3.2569 -      &lt;LimitExcept GET POST OPTIONS&gt;
  3.2570 -          Order deny,allow
  3.2571 -          Deny from all
  3.2572 -      &lt;/LimitExcept&gt;
  3.2573 -  &lt;/Directory&gt;
  3.2574 -</para>
  3.2575 -</programlisting>
  3.2576 -<para>If you find a similar-looking <literal>Directory</literal> group in your Apache
  3.2577 -configuration, the directive to look at inside it is <literal>Options</literal>.
  3.2578 -Add <literal>ExecCGI</literal> to the end of this list if it's missing, and
  3.2579 -restart the web server.
  3.2580 -</para>
  3.2581 -
  3.2582 -<para>If you find that Apache serves you the text of the CGI script instead
  3.2583 -of executing it, you may need to either uncomment (if already present)
  3.2584 -or add a directive like this.
  3.2585 -</para>
  3.2586 -<programlisting>
  3.2587 -<para>  AddHandler cgi-script .cgi
  3.2588 -</para>
  3.2589 -</programlisting>
  3.2590 -
  3.2591 -<para>The next possibility is that you might be served with a colourful
  3.2592 -Python backtrace claiming that it can't import a
  3.2593 -<literal>mercurial</literal>-related module.  This is actually progress!  The
  3.2594 -server is now capable of executing your CGI script.  This error is
  3.2595 -only likely to occur if you're running a private installation of
  3.2596 -Mercurial, instead of a system-wide version.  Remember that the web
  3.2597 -server runs the CGI program without any of the environment variables
  3.2598 -that you take for granted in an interactive session.  If this error
  3.2599 -happens to you, edit your copy of <filename role="special">hgweb.cgi</filename> and follow the
  3.2600 -directions inside it to correctly set your <envar>PYTHONPATH</envar>
  3.2601 -environment variable.
  3.2602 -</para>
  3.2603 -
  3.2604 -<para>Finally, you are <emphasis>certain</emphasis> to by served with another colourful
  3.2605 -Python backtrace: this one will complain that it can't find
  3.2606 -<filename class="directory">/path/to/repository</filename>.  Edit your <filename role="special">hgweb.cgi</filename> script
  3.2607 -and replace the <filename class="directory">/path/to/repository</filename> string with the complete
  3.2608 -path to the repository you want to serve up.
  3.2609 -</para>
  3.2610 -
  3.2611 -<para>At this point, when you try to reload the page, you should be
  3.2612 -presented with a nice HTML view of your repository's history.  Whew!
  3.2613 -</para>
  3.2614 -
  3.2615 -</sect3>
  3.2616 -<sect3>
  3.2617 -<title>Configuring lighttpd</title>
  3.2618 -
  3.2619 -<para>To be exhaustive in my experiments, I tried configuring the
  3.2620 -increasingly popular <literal>lighttpd</literal> web server to serve the same
  3.2621 -repository as I described with Apache above.  I had already overcome
  3.2622 -all of the problems I outlined with Apache, many of which are not
  3.2623 -server-specific.  As a result, I was fairly sure that my file and
  3.2624 -directory permissions were good, and that my <filename role="special">hgweb.cgi</filename>
  3.2625 -script was properly edited.
  3.2626 -</para>
  3.2627 -
  3.2628 -<para>Once I had Apache running, getting <literal>lighttpd</literal> to serve the
  3.2629 -repository was a snap (in other words, even if you're trying to use
  3.2630 -<literal>lighttpd</literal>, you should read the Apache section).  I first had
  3.2631 -to edit the <literal>mod_access</literal> section of its config file to enable
  3.2632 -<literal>mod_cgi</literal> and <literal>mod_userdir</literal>, both of which were
  3.2633 -disabled by default on my system.  I then added a few lines to the end
  3.2634 -of the config file, to configure these modules.
  3.2635 -</para>
  3.2636 -<programlisting>
  3.2637 -<para>  userdir.path = "public_html"
  3.2638 -  cgi.assign = ( ".cgi" =&gt; "" )
  3.2639 -</para>
  3.2640 -</programlisting>
  3.2641 -<para>With this done, <literal>lighttpd</literal> ran immediately for me.  If I had
  3.2642 -configured <literal>lighttpd</literal> before Apache, I'd almost certainly have
  3.2643 -run into many of the same system-level configuration problems as I did
  3.2644 -with Apache.  However, I found <literal>lighttpd</literal> to be noticeably
  3.2645 -easier to configure than Apache, even though I've used Apache for over
  3.2646 -a decade, and this was my first exposure to <literal>lighttpd</literal>.
  3.2647 -</para>
  3.2648 -
  3.2649 -</sect3>
  3.2650 -</sect2>
  3.2651 -<sect2>
  3.2652 -<title>Sharing multiple repositories with one CGI script</title>
  3.2653 -
  3.2654 -<para>The <filename role="special">hgweb.cgi</filename> script only lets you publish a single
  3.2655 -repository, which is an annoying restriction.  If you want to publish
  3.2656 -more than one without wracking yourself with multiple copies of the
  3.2657 -same script, each with different names, a better choice is to use the
  3.2658 -<filename role="special">hgwebdir.cgi</filename> script.
  3.2659 -</para>
  3.2660 -
  3.2661 -<para>The procedure to configure <filename role="special">hgwebdir.cgi</filename> is only a little
  3.2662 -more involved than for <filename role="special">hgweb.cgi</filename>.  First, you must obtain
  3.2663 -a copy of the script.  If you don't have one handy, you can download a
  3.2664 -copy from the master Mercurial repository at
  3.2665 -<ulink url="http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi</ulink>.
  3.2666 -</para>
  3.2667 -
  3.2668 -<para>You'll need to copy this script into your <filename class="directory">public_html</filename>
  3.2669 -directory, and ensure that it's executable.
  3.2670 -</para>
  3.2671 -<programlisting>
  3.2672 -<para>  cp .../hgwebdir.cgi  /public_html
  3.2673 -  chmod 755  /public_html  /public_html/hgwebdir.cgi
  3.2674 -</para>
  3.2675 -</programlisting>
  3.2676 -<para>With basic configuration out of the way, try to visit
  3.2677 -<ulink url="http://myhostname/ myuser/hgwebdir.cgi">http://myhostname/ myuser/hgwebdir.cgi</ulink> in your browser.  It
  3.2678 -should display an empty list of repositories.  If you get a blank
  3.2679 -window or error message, try walking through the list of potential
  3.2680 -problems in section <xref linkend="sec:collab:wtf"/>.
  3.2681 -</para>
  3.2682 -
  3.2683 -<para>The <filename role="special">hgwebdir.cgi</filename> script relies on an external
  3.2684 -configuration file.  By default, it searches for a file named
  3.2685 -<filename role="special">hgweb.config</filename> in the same directory as itself.  You'll need
  3.2686 -to create this file, and make it world-readable.  The format of the
  3.2687 -file is similar to a Windows <quote>ini</quote> file, as understood by Python's
  3.2688 -<literal>ConfigParser</literal> <citation>web:configparser</citation> module.
  3.2689 -</para>
  3.2690 -
  3.2691 -<para>The easiest way to configure <filename role="special">hgwebdir.cgi</filename> is with a
  3.2692 -section named <literal>collections</literal>.  This will automatically publish
  3.2693 -<emphasis>every</emphasis> repository under the directories you name.  The section
  3.2694 -should look like this:
  3.2695 -</para>
  3.2696 -<programlisting>
  3.2697 -<para>  [collections]
  3.2698 -  /my/root = /my/root
  3.2699 -</para>
  3.2700 -</programlisting>
  3.2701 -<para>Mercurial interprets this by looking at the directory name on the
  3.2702 -<emphasis>right</emphasis> hand side of the <quote><literal>=</literal></quote> sign; finding
  3.2703 -repositories in that directory hierarchy; and using the text on the
  3.2704 -<emphasis>left</emphasis> to strip off matching text from the names it will actually
  3.2705 -list in the web interface.  The remaining component of a path after
  3.2706 -this stripping has occurred is called a <quote>virtual path</quote>.
  3.2707 -</para>
  3.2708 -
  3.2709 -<para>Given the example above, if we have a repository whose local path is
  3.2710 -<filename class="directory">/my/root/this/repo</filename>, the CGI script will strip the leading
  3.2711 -<filename class="directory">/my/root</filename> from the name, and publish the repository with a
  3.2712 -virtual path of <filename class="directory">this/repo</filename>.  If the base URL for our CGI
  3.2713 -script is <ulink url="http://myhostname/ myuser/hgwebdir.cgi">http://myhostname/ myuser/hgwebdir.cgi</ulink>, the complete
  3.2714 -URL for that repository will be
  3.2715 -<ulink url="http://myhostname/ myuser/hgwebdir.cgi/this/repo">http://myhostname/ myuser/hgwebdir.cgi/this/repo</ulink>.
  3.2716 -</para>
  3.2717 -
  3.2718 -<para>If we replace <filename class="directory">/my/root</filename> on the left hand side of this example
  3.2719 -with <filename class="directory">/my</filename>, then <filename role="special">hgwebdir.cgi</filename> will only strip off
  3.2720 -<filename class="directory">/my</filename> from the repository name, and will give us a virtual
  3.2721 -path of <filename class="directory">root/this/repo</filename> instead of <filename class="directory">this/repo</filename>.
  3.2722 -</para>
  3.2723 -
  3.2724 -<para>The <filename role="special">hgwebdir.cgi</filename> script will recursively search each
  3.2725 -directory listed in the <literal>collections</literal> section of its
  3.2726 -configuration file, but it will <literal>not</literal> recurse into the
  3.2727 -repositories it finds.
  3.2728 -</para>
  3.2729 -
  3.2730 -<para>The <literal>collections</literal> mechanism makes it easy to publish many
  3.2731 -repositories in a <quote>fire and forget</quote> manner.  You only need to set up
  3.2732 -the CGI script and configuration file one time.  Afterwards, you can
  3.2733 -publish or unpublish a repository at any time by simply moving it
  3.2734 -into, or out of, the directory hierarchy in which you've configured
  3.2735 -<filename role="special">hgwebdir.cgi</filename> to look.
  3.2736 -</para>
  3.2737 -
  3.2738 -<sect3>
  3.2739 -<title>Explicitly specifying which repositories to publish</title>
  3.2740 -
  3.2741 -<para>In addition to the <literal>collections</literal> mechanism, the
  3.2742 -<filename role="special">hgwebdir.cgi</filename> script allows you to publish a specific list
  3.2743 -of repositories.  To do so, create a <literal>paths</literal> section, with
  3.2744 -contents of the following form.
  3.2745 -</para>
  3.2746 -<programlisting>
  3.2747 -<para>  [paths]
  3.2748 -  repo1 = /my/path/to/some/repo
  3.2749 -  repo2 = /some/path/to/another
  3.2750 -</para>
  3.2751 -</programlisting>
  3.2752 -<para>In this case, the virtual path (the component that will appear in a
  3.2753 -URL) is on the left hand side of each definition, while the path to
  3.2754 -the repository is on the right.  Notice that there does not need to be
  3.2755 -any relationship between the virtual path you choose and the location
  3.2756 -of a repository in your filesystem.
  3.2757 -</para>
  3.2758 -
  3.2759 -<para>If you wish, you can use both the <literal>collections</literal> and
  3.2760 -<literal>paths</literal> mechanisms simultaneously in a single configuration
  3.2761 -file.
  3.2762 -</para>
  3.2763 -
  3.2764 -<note>
  3.2765 -<para>  If multiple repositories have the same virtual path,
  3.2766 -  <filename role="special">hgwebdir.cgi</filename> will not report an error.  Instead, it will
  3.2767 -  behave unpredictably.
  3.2768 -</para>
  3.2769 -</note>
  3.2770 -
  3.2771 -</sect3>
  3.2772 -</sect2>
  3.2773 -<sect2>
  3.2774 -<title>Downloading source archives</title>
  3.2775 -
  3.2776 -<para>Mercurial's web interface lets users download an archive of any
  3.2777 -revision.  This archive will contain a snapshot of the working
  3.2778 -directory as of that revision, but it will not contain a copy of the
  3.2779 -repository data.
  3.2780 -</para>
  3.2781 -
  3.2782 -<para>By default, this feature is not enabled.  To enable it, you'll need to
  3.2783 -add an <envar role="rc-item-web">allow_archive</envar> item to the <literal role="rc-web">web</literal>
  3.2784 -section of your <filename role="special"> /.hgrc</filename>.
  3.2785 -</para>
  3.2786 -
  3.2787 -</sect2>
  3.2788 -<sect2>
  3.2789 -<title>Web configuration options</title>
  3.2790 -
  3.2791 -<para>Mercurial's web interfaces (the <command role="hg-cmd">hg serve</command> command, and the
  3.2792 -<filename role="special">hgweb.cgi</filename> and <filename role="special">hgwebdir.cgi</filename> scripts) have a
  3.2793 -number of configuration options that you can set.  These belong in a
  3.2794 -section named <literal role="rc-web">web</literal>.
  3.2795 -</para>
  3.2796 -<itemizedlist>
  3.2797 -<listitem><para><envar role="rc-item-web">allow_archive</envar>: Determines which (if any) archive
  3.2798 -  download mechanisms Mercurial supports.  If you enable this
  3.2799 -  feature, users of the web interface will be able to download an
  3.2800 -  archive of whatever revision of a repository they are viewing.
  3.2801 -  To enable the archive feature, this item must take the form of a
  3.2802 -  sequence of words drawn from the list below.
  3.2803 -</para>
  3.2804 -</listitem><itemizedlist>
  3.2805 -<listitem><para>  \item <literal>bz2</literal>: A <command>tar</command> archive, compressed using
  3.2806 -    <literal>bzip2</literal> compression.  This has the best compression ratio,
  3.2807 -    but uses the most CPU time on the server.
  3.2808 -  \item <literal>gz</literal>: A <command>tar</command> archive, compressed using
  3.2809 -    <literal>gzip</literal> compression.
  3.2810 -  \item <literal>zip</literal>: A <command>zip</command> archive, compressed using LZW
  3.2811 -    compression.  This format has the worst compression ratio, but is
  3.2812 -    widely used in the Windows world.
  3.2813 -</para>
  3.2814 -</listitem></itemizedlist>
  3.2815 -<para>  If you provide an empty list, or don't have an
  3.2816 -  <envar role="rc-item-web">allow_archive</envar> entry at all, this feature will be
  3.2817 -  disabled.  Here is an example of how to enable all three supported
  3.2818 -  formats.
  3.2819 -</para>
  3.2820 -<programlisting>
  3.2821 -<para>    [web]
  3.2822 -    allow_archive = bz2 gz zip
  3.2823 -</para>
  3.2824 -</programlisting>
  3.2825 -<listitem><para><envar role="rc-item-web">allowpull</envar>: Boolean.  Determines whether the web
  3.2826 -  interface allows remote users to <command role="hg-cmd">hg pull</command> and <command role="hg-cmd">hg clone</command> this
  3.2827 -  repository over HTTP.  If set to <literal>no</literal> or <literal>false</literal>, only
  3.2828 -  the <quote>human-oriented</quote> portion of the web interface is available.
  3.2829 -</para>
  3.2830 -</listitem>
  3.2831 -<listitem><para><envar role="rc-item-web">contact</envar>: String.  A free-form (but preferably
  3.2832 -  brief) string identifying the person or group in charge of the
  3.2833 -  repository.  This often contains the name and email address of a
  3.2834 -  person or mailing list.  It often makes sense to place this entry in
  3.2835 -  a repository's own <filename role="special">.hg/hgrc</filename> file, but it can make sense
  3.2836 -  to use in a global <filename role="special"> /.hgrc</filename>\ if every repository has a single
  3.2837 -  maintainer.
  3.2838 -</para>
  3.2839 -</listitem>
  3.2840 -<listitem><para><envar role="rc-item-web">maxchanges</envar>: Integer.  The default maximum number
  3.2841 -  of changesets to display in a single page of output.
  3.2842 -</para>
  3.2843 -</listitem>
  3.2844 -<listitem><para><envar role="rc-item-web">maxfiles</envar>: Integer.  The default maximum number
  3.2845 -  of modified files to display in a single page of output.
  3.2846 -</para>
  3.2847 -</listitem>
  3.2848 -<listitem><para><envar role="rc-item-web">stripes</envar>: Integer.  If the web interface displays
  3.2849 -  alternating <quote>stripes</quote> to make it easier to visually align rows
  3.2850 -  when you are looking at a table, this number controls the number of
  3.2851 -  rows in each stripe.
  3.2852 -</para>
  3.2853 -</listitem>
  3.2854 -<listitem><para><envar role="rc-item-web">style</envar>: Controls the template Mercurial uses to
  3.2855 -  display the web interface.  Mercurial ships with two web templates,
  3.2856 -  named <literal>default</literal> and <literal>gitweb</literal> (the latter is much more
  3.2857 -  visually attractive).  You can also specify a custom template of
  3.2858 -  your own; see chapter <xref linkend="chap:template"/> for details.  Here, you
  3.2859 -  can see how to enable the <literal>gitweb</literal> style.
  3.2860 -</para>
  3.2861 -</listitem><programlisting>
  3.2862 -<listitem><para>    [web]
  3.2863 -    style = gitweb
  3.2864 -</para>
  3.2865 -</listitem></programlisting>
  3.2866 -</para>
  3.2867 -</listitem>
  3.2868 -<listitem><para><envar role="rc-item-web">templates</envar>: Path.  The directory in which to search
  3.2869 -  for template files.  By default, Mercurial searches in the directory
  3.2870 -  in which it was installed.
  3.2871 -</para>
  3.2872 -</listitem></itemizedlist>
  3.2873 -<para>If you are using <filename role="special">hgwebdir.cgi</filename>, you can place a few
  3.2874 -configuration items in a <literal role="rc-web">web</literal> section of the
  3.2875 -<filename role="special">hgweb.config</filename> file instead of a <filename role="special"> /.hgrc</filename>\ file, for
  3.2876 -convenience.  These items are <envar role="rc-item-web">motd</envar> and
  3.2877 -<envar role="rc-item-web">style</envar>.
  3.2878 -</para>
  3.2879 -
  3.2880 -<sect3>
  3.2881 -<title>Options specific to an individual repository</title>
  3.2882 -
  3.2883 -<para>A few <literal role="rc-web">web</literal> configuration items ought to be placed in a
  3.2884 -repository's local <filename role="special">.hg/hgrc</filename>, rather than a user's or
  3.2885 -global <filename role="special"> /.hgrc</filename>.
  3.2886 -</para>
  3.2887 -<itemizedlist>
  3.2888 -<listitem><para><envar role="rc-item-web">description</envar>: String.  A free-form (but preferably
  3.2889 -  brief) string that describes the contents or purpose of the
  3.2890 -  repository.
  3.2891 -</para>
  3.2892 -</listitem>
  3.2893 -<listitem><para><envar role="rc-item-web">name</envar>: String.  The name to use for the repository
  3.2894 -  in the web interface.  This overrides the default name, which is the
  3.2895 -  last component of the repository's path.
  3.2896 -</para>
  3.2897 -</listitem></itemizedlist>
  3.2898 -
  3.2899 -</sect3>
  3.2900 -<sect3>
  3.2901 -<title>Options specific to the <command role="hg-cmd">hg serve</command> command</title>
  3.2902 -
  3.2903 -<para>Some of the items in the <literal role="rc-web">web</literal> section of a <filename role="special"> /.hgrc</filename>\ file are
  3.2904 -only for use with the <command role="hg-cmd">hg serve</command> command.
  3.2905 -</para>
  3.2906 -<itemizedlist>
  3.2907 -<listitem><para><envar role="rc-item-web">accesslog</envar>: Path.  The name of a file into which to
  3.2908 -  write an access log.  By default, the <command role="hg-cmd">hg serve</command> command writes
  3.2909 -  this information to standard output, not to a file.  Log entries are
  3.2910 -  written in the standard <quote>combined</quote> file format used by almost all
  3.2911 -  web servers.
  3.2912 -</para>
  3.2913 -</listitem>
  3.2914 -<listitem><para><envar role="rc-item-web">address</envar>: String.  The local address on which the
  3.2915 -  server should listen for incoming connections.  By default, the
  3.2916 -  server listens on all addresses.
  3.2917 -</para>
  3.2918 -</listitem>
  3.2919 -<listitem><para><envar role="rc-item-web">errorlog</envar>: Path.  The name of a file into which to
  3.2920 -  write an error log.  By default, the <command role="hg-cmd">hg serve</command> command writes this
  3.2921 -  information to standard error, not to a file.
  3.2922 -</para>
  3.2923 -</listitem>
  3.2924 -<listitem><para><envar role="rc-item-web">ipv6</envar>: Boolean.  Whether to use the IPv6 protocol.
  3.2925 -  By default, IPv6 is not used.
  3.2926 -</para>
  3.2927 -</listitem>
  3.2928 -<listitem><para><envar role="rc-item-web">port</envar>: Integer.  The TCP port number on which the
  3.2929 -  server should listen.  The default port number used is 8000.
  3.2930 -</para>
  3.2931 -</listitem></itemizedlist>
  3.2932 -
  3.2933 -<para>\subsubsection{Choosing the right <filename role="special"> /.hgrc</filename>\ file to add <literal role="rc-web">web</literal>
  3.2934 -  items to}
  3.2935 -</para>
  3.2936 -
  3.2937 -<para>It is important to remember that a web server like Apache or
  3.2938 -<literal>lighttpd</literal> will run under a user ID that is different to yours.
  3.2939 -CGI scripts run by your server, such as <filename role="special">hgweb.cgi</filename>, will
  3.2940 -usually also run under that user ID.
  3.2941 -</para>
  3.2942 -
  3.2943 -<para>If you add <literal role="rc-web">web</literal> items to your own personal <filename role="special"> /.hgrc</filename>\ file, CGI
  3.2944 -scripts won't read that <filename role="special"> /.hgrc</filename>\ file.  Those settings will thus only
  3.2945 -affect the behaviour of the <command role="hg-cmd">hg serve</command> command when you run it.  To
  3.2946 -cause CGI scripts to see your settings, either create a <filename role="special"> /.hgrc</filename>\ file in
  3.2947 -the home directory of the user ID that runs your web server, or add
  3.2948 -those settings to a system-wide <filename role="special"> /.hgrc</filename>\ file.
  3.2949 -</para>
  3.2950 -
  3.2951 -
  3.2952 -</sect3>
  3.2953 -</sect2>
  3.2954 -</sect1>
  3.2955 +    </sect2>
  3.2956 +  </sect1>
  3.2957  </chapter>
  3.2958  
  3.2959  <!--
  3.2960  local variables: 
  3.2961  sgml-parent-document: ("00book.xml" "book" "chapter")
  3.2962  end:
  3.2963 --->
  3.2964 \ No newline at end of file
  3.2965 +-->