1.1 --- a/fr/ch06-collab.xml	Sun Aug 16 04:58:01 2009 +0200
     1.2 +++ b/fr/ch06-collab.xml	Sun Sep 13 14:08:00 2009 +0200
     1.3 @@ -1,1405 +1,1565 @@
     1.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5  
     1.6 -<chapter>
     1.7 -<title>Collaborating with other people</title>
     1.8 -<para>\label{cha:collab}</para>
     1.9 -
    1.10 -<para>As a completely decentralised tool, Mercurial doesn't impose any
    1.11 -policy on how people ought to work with each other.  However, if
    1.12 -you're new to distributed revision control, it helps to have some
    1.13 -tools and examples in mind when you're thinking about possible
    1.14 -workflow models.</para>
    1.15 -
    1.16 -<sect1>
    1.17 -<title>Mercurial's web interface</title>
    1.18 -
    1.19 -<para>Mercurial has a powerful web interface that provides several
    1.20 -useful capabilities.</para>
    1.21 -
    1.22 -<para>For interactive use, the web interface lets you browse a single
    1.23 -repository or a collection of repositories.  You can view the history
    1.24 -of a repository, examine each change (comments and diffs), and view
    1.25 -the contents of each directory and file.</para>
    1.26 -
    1.27 -<para>Also for human consumption, the web interface provides an RSS feed of
    1.28 -the changes in a repository.  This lets you <quote>subscribe</quote> to a
    1.29 -repository using your favourite feed reader, and be automatically
    1.30 -notified of activity in that repository as soon as it happens.  I find
    1.31 -this capability much more convenient than the model of subscribing to
    1.32 -a mailing list to which notifications are sent, as it requires no
    1.33 -additional configuration on the part of whoever is serving the
    1.34 -repository.</para>
    1.35 -
    1.36 -<para>The web interface also lets remote users clone a repository, pull
    1.37 -changes from it, and (when the server is configured to permit it) push
    1.38 -changes back to it.  Mercurial's HTTP tunneling protocol aggressively
    1.39 -compresses data, so that it works efficiently even over low-bandwidth
    1.40 -network connections.</para>
    1.41 -
    1.42 -<para>The easiest way to get started with the web interface is to use your
    1.43 -web browser to visit an existing repository, such as the master
    1.44 -Mercurial repository at
    1.45 -<ulink url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para>
    1.46 -
    1.47 -<para>If you're interested in providing a web interface to your own
    1.48 -repositories, Mercurial provides two ways to do this.  The first is
    1.49 -using the <command role="hg-cmd">hg serve</command> command, which is best suited to short-term
    1.50 -<quote>lightweight</quote> serving.  See section <xref linkend="sec:collab:serve"/> below for
    1.51 -details of how to use this command.  If you have a long-lived
    1.52 -repository that you'd like to make permanently available, Mercurial
    1.53 -has built-in support for the CGI (Common Gateway Interface) standard,
    1.54 -which all common web servers support.  See
    1.55 -section <xref linkend="sec:collab:cgi"/> for details of CGI configuration.</para>
    1.56 -
    1.57 -</sect1>
    1.58 -<sect1>
    1.59 -<title>Collaboration models</title>
    1.60 -
    1.61 -<para>With a suitably flexible tool, making decisions about workflow is much
    1.62 -more of a social engineering challenge than a technical one.
    1.63 -Mercurial imposes few limitations on how you can structure the flow of
    1.64 -work in a project, so it's up to you and your group to set up and live
    1.65 -with a model that matches your own particular needs.
    1.66 -</para>
    1.67 -
    1.68 -<sect2>
    1.69 -<title>Factors to keep in mind</title>
    1.70 -
    1.71 -<para>The most important aspect of any model that you must keep in mind is
    1.72 -how well it matches the needs and capabilities of the people who will
    1.73 -be using it.  This might seem self-evident; even so, you still can't
    1.74 -afford to forget it for a moment.
    1.75 -</para>
    1.76 -
    1.77 -<para>I once put together a workflow model that seemed to make perfect sense
    1.78 -to me, but that caused a considerable amount of consternation and
    1.79 -strife within my development team.  In spite of my attempts to explain
    1.80 -why we needed a complex set of branches, and how changes ought to flow
    1.81 -between them, a few team members revolted.  Even though they were
    1.82 -smart people, they didn't want to pay attention to the constraints we
    1.83 -were operating under, or face the consequences of those constraints in
    1.84 -the details of the model that I was advocating.
    1.85 -</para>
    1.86 -
    1.87 -<para>Don't sweep foreseeable social or technical problems under the rug.
    1.88 -Whatever scheme you put into effect, you should plan for mistakes and
    1.89 -problem scenarios.  Consider adding automated machinery to prevent, or
    1.90 -quickly recover from, trouble that you can anticipate.  As an example,
    1.91 -if you intend to have a branch with not-for-release changes in it,
    1.92 -you'd do well to think early about the possibility that someone might
    1.93 -accidentally merge those changes into a release branch.  You could
    1.94 -avoid this particular problem by writing a hook that prevents changes
    1.95 -from being merged from an inappropriate branch.
    1.96 -</para>
    1.97 -
    1.98 -</sect2>
    1.99 -<sect2>
   1.100 -<title>Informal anarchy</title>
   1.101 -
   1.102 -<para>I wouldn't suggest an <quote>anything goes</quote> approach as something
   1.103 -sustainable, but it's a model that's easy to grasp, and it works
   1.104 -perfectly well in a few unusual situations.
   1.105 -</para>
   1.106 -
   1.107 -<para>As one example, many projects have a loose-knit group of collaborators
   1.108 -who rarely physically meet each other.  Some groups like to overcome
   1.109 -the isolation of working at a distance by organising occasional
   1.110 -<quote>sprints</quote>.  In a sprint, a number of people get together in a single
   1.111 -location (a company's conference room, a hotel meeting room, that kind
   1.112 -of place) and spend several days more or less locked in there, hacking
   1.113 -intensely on a handful of projects.
   1.114 -</para>
   1.115 -
   1.116 -<para>A sprint is the perfect place to use the <command role="hg-cmd">hg serve</command> command, since
   1.117 -<command role="hg-cmd">hg serve</command> does not requires any fancy server infrastructure.  You
   1.118 -can get started with <command role="hg-cmd">hg serve</command> in moments, by reading
   1.119 -section <xref linkend="sec:collab:serve"/> below.  Then simply tell the person
   1.120 -next to you that you're running a server, send the URL to them in an
   1.121 -instant message, and you immediately have a quick-turnaround way to
   1.122 -work together.  They can type your URL into their web browser and
   1.123 -quickly review your changes; or they can pull a bugfix from you and
   1.124 -verify it; or they can clone a branch containing a new feature and try
   1.125 -it out.
   1.126 -</para>
   1.127 -
   1.128 -<para>The charm, and the problem, with doing things in an ad hoc fashion
   1.129 -like this is that only people who know about your changes, and where
   1.130 -they are, can see them.  Such an informal approach simply doesn't
   1.131 -scale beyond a handful people, because each individual needs to know
   1.132 -about $n$ different repositories to pull from.
   1.133 -</para>
   1.134 -
   1.135 -</sect2>
   1.136 -<sect2>
   1.137 -<title>A single central repository</title>
   1.138 -
   1.139 -<para>For smaller projects migrating from a centralised revision control
   1.140 -tool, perhaps the easiest way to get started is to have changes flow
   1.141 -through a single shared central repository.  This is also the
   1.142 -most common <quote>building block</quote> for more ambitious workflow schemes.
   1.143 -</para>
   1.144 -
   1.145 -<para>Contributors start by cloning a copy of this repository.  They can
   1.146 -pull changes from it whenever they need to, and some (perhaps all)
   1.147 -developers have permission to push a change back when they're ready
   1.148 -for other people to see it.
   1.149 -</para>
   1.150 -
   1.151 -<para>Under this model, it can still often make sense for people to pull
   1.152 -changes directly from each other, without going through the central
   1.153 -repository.  Consider a case in which I have a tentative bug fix, but
   1.154 -I am worried that if I were to publish it to the central repository,
   1.155 -it might subsequently break everyone else's trees as they pull it.  To
   1.156 -reduce the potential for damage, I can ask you to clone my repository
   1.157 -into a temporary repository of your own and test it.  This lets us put
   1.158 -off publishing the potentially unsafe change until it has had a little
   1.159 -testing.
   1.160 -</para>
   1.161 -
   1.162 -<para>In this kind of scenario, people usually use the <command>ssh</command>
   1.163 -protocol to securely push changes to the central repository, as
   1.164 -documented in section <xref linkend="sec:collab:ssh"/>.  It's also usual to
   1.165 -publish a read-only copy of the repository over HTTP using CGI, as in
   1.166 -section <xref linkend="sec:collab:cgi"/>.  Publishing over HTTP satisfies the
   1.167 -needs of people who don't have push access, and those who want to use
   1.168 -web browsers to browse the repository's history.
   1.169 -</para>
   1.170 -
   1.171 -</sect2>
   1.172 -<sect2>
   1.173 -<title>Working with multiple branches</title>
   1.174 -
   1.175 -<para>Projects of any significant size naturally tend to make progress on
   1.176 -several fronts simultaneously.  In the case of software, it's common
   1.177 -for a project to go through periodic official releases.  A release
   1.178 -might then go into <quote>maintenance mode</quote> for a while after its first
   1.179 -publication; maintenance releases tend to contain only bug fixes, not
   1.180 -new features.  In parallel with these maintenance releases, one or
   1.181 -more future releases may be under development.  People normally use
   1.182 -the word <quote>branch</quote> to refer to one of these many slightly different
   1.183 -directions in which development is proceeding.
   1.184 -</para>
   1.185 -
   1.186 -<para>Mercurial is particularly well suited to managing a number of
   1.187 -simultaneous, but not identical, branches.  Each <quote>development
   1.188 -direction</quote> can live in its own central repository, and you can merge
   1.189 -changes from one to another as the need arises.  Because repositories
   1.190 -are independent of each other, unstable changes in a development
   1.191 -branch will never affect a stable branch unless someone explicitly
   1.192 -merges those changes in.
   1.193 -</para>
   1.194 -
   1.195 -<para>Here's an example of how this can work in practice.  Let's say you
   1.196 -have one <quote>main branch</quote> on a central server.
   1.197 -<!-- &interaction.branching.init; -->
   1.198 -People clone it, make changes locally, test them, and push them back.
   1.199 -</para>
   1.200 -
   1.201 -<para>Once the main branch reaches a release milestone, you can use the
   1.202 -<command role="hg-cmd">hg tag</command> command to give a permanent name to the milestone
   1.203 -revision.
   1.204 -<!-- &interaction.branching.tag; -->
   1.205 -Let's say some ongoing development occurs on the main branch.
   1.206 -<!-- &interaction.branching.main; -->
   1.207 -Using the tag that was recorded at the milestone, people who clone
   1.208 -that repository at any time in the future can use <command role="hg-cmd">hg update</command> to
   1.209 -get a copy of the working directory exactly as it was when that tagged
   1.210 -revision was committed.
   1.211 -<!-- &interaction.branching.update; -->
   1.212 -</para>
   1.213 -
   1.214 -<para>In addition, immediately after the main branch is tagged, someone can
   1.215 -then clone the main branch on the server to a new <quote>stable</quote> branch,
   1.216 -also on the server.
   1.217 -<!-- &interaction.branching.clone; -->
   1.218 -</para>
   1.219 -
   1.220 -<para>Someone who needs to make a change to the stable branch can then clone
   1.221 -<emphasis>that</emphasis> repository, make their changes, commit, and push their
   1.222 -changes back there.
   1.223 -<!-- &interaction.branching.stable; -->
   1.224 -Because Mercurial repositories are independent, and Mercurial doesn't
   1.225 -move changes around automatically, the stable and main branches are
   1.226 -<emphasis>isolated</emphasis> from each other.  The changes that you made on the
   1.227 -main branch don't <quote>leak</quote> to the stable branch, and vice versa.
   1.228 -</para>
   1.229 -
   1.230 -<para>You'll often want all of your bugfixes on the stable branch to show up
   1.231 -on the main branch, too.  Rather than rewrite a bugfix on the main
   1.232 -branch, you can simply pull and merge changes from the stable to the
   1.233 -main branch, and Mercurial will bring those bugfixes in for you.
   1.234 -<!-- &interaction.branching.merge; -->
   1.235 -The main branch will still contain changes that are not on the stable
   1.236 -branch, but it will also contain all of the bugfixes from the stable
   1.237 -branch.  The stable branch remains unaffected by these changes.
   1.238 -</para>
   1.239 -
   1.240 -</sect2>
   1.241 -<sect2>
   1.242 -<title>Feature branches</title>
   1.243 -
   1.244 -<para>For larger projects, an effective way to manage change is to break up
   1.245 -a team into smaller groups.  Each group has a shared branch of its
   1.246 -own, cloned from a single <quote>master</quote> branch used by the entire
   1.247 -project.  People working on an individual branch are typically quite
   1.248 -isolated from developments on other branches.
   1.249 -</para>
   1.250 -
   1.251 -<informalfigure>
   1.252 -
   1.253 -<para>  <mediaobject><imageobject><imagedata fileref="feature-branches"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject>
   1.254 -  <caption><para>Feature branches</para></caption>
   1.255 -  \label{fig:collab:feature-branches}
   1.256 -</para>
   1.257 -</informalfigure>
   1.258 -
   1.259 -<para>When a particular feature is deemed to be in suitable shape, someone
   1.260 -on that feature team pulls and merges from the master branch into the
   1.261 -feature branch, then pushes back up to the master branch.
   1.262 -</para>
   1.263 -
   1.264 -</sect2>
   1.265 -<sect2>
   1.266 -<title>The release train</title>
   1.267 -
   1.268 -<para>Some projects are organised on a <quote>train</quote> basis: a release is
   1.269 -scheduled to happen every few months, and whatever features are ready
   1.270 -when the <quote>train</quote> is ready to leave are allowed in.
   1.271 -</para>
   1.272 -
   1.273 -<para>This model resembles working with feature branches.  The difference is
   1.274 -that when a feature branch misses a train, someone on the feature team
   1.275 -pulls and merges the changes that went out on that train release into
   1.276 -the feature branch, and the team continues its work on top of that
   1.277 -release so that their feature can make the next release.
   1.278 -</para>
   1.279 -
   1.280 -</sect2>
   1.281 -<sect2>
   1.282 -<title>The Linux kernel model</title>
   1.283 -
   1.284 -<para>The development of the Linux kernel has a shallow hierarchical
   1.285 -structure, surrounded by a cloud of apparent chaos.  Because most
   1.286 -Linux developers use <command>git</command>, a distributed revision control
   1.287 -tool with capabilities similar to Mercurial, it's useful to describe
   1.288 -the way work flows in that environment; if you like the ideas, the
   1.289 -approach translates well across tools.
   1.290 -</para>
   1.291 -
   1.292 -<para>At the center of the community sits Linus Torvalds, the creator of
   1.293 -Linux.  He publishes a single source repository that is considered the
   1.294 -<quote>authoritative</quote> current tree by the entire developer community.
   1.295 -Anyone can clone Linus's tree, but he is very choosy about whose trees
   1.296 -he pulls from.
   1.297 -</para>
   1.298 -
   1.299 -<para>Linus has a number of <quote>trusted lieutenants</quote>.  As a general rule, he
   1.300 -pulls whatever changes they publish, in most cases without even
   1.301 -reviewing those changes.  Some of those lieutenants are generally
   1.302 -agreed to be <quote>maintainers</quote>, responsible for specific subsystems
   1.303 -within the kernel.  If a random kernel hacker wants to make a change
   1.304 -to a subsystem that they want to end up in Linus's tree, they must
   1.305 -find out who the subsystem's maintainer is, and ask that maintainer to
   1.306 -take their change.  If the maintainer reviews their changes and agrees
   1.307 -to take them, they'll pass them along to Linus in due course.
   1.308 -</para>
   1.309 -
   1.310 -<para>Individual lieutenants have their own approaches to reviewing,
   1.311 -accepting, and publishing changes; and for deciding when to feed them
   1.312 -to Linus.  In addition, there are several well known branches that
   1.313 -people use for different purposes.  For example, a few people maintain
   1.314 -<quote>stable</quote> repositories of older versions of the kernel, to which they
   1.315 -apply critical fixes as needed.  Some maintainers publish multiple
   1.316 -trees: one for experimental changes; one for changes that they are
   1.317 -about to feed upstream; and so on.  Others just publish a single
   1.318 -tree.
   1.319 -</para>
   1.320 -
   1.321 -<para>This model has two notable features.  The first is that it's <quote>pull
   1.322 -only</quote>.  You have to ask, convince, or beg another developer to take a
   1.323 -change from you, because there are almost no trees to which more than
   1.324 -one person can push, and there's no way to push changes into a tree
   1.325 -that someone else controls.
   1.326 -</para>
   1.327 -
   1.328 -<para>The second is that it's based on reputation and acclaim.  If you're an
   1.329 -unknown, Linus will probably ignore changes from you without even
   1.330 -responding.  But a subsystem maintainer will probably review them, and
   1.331 -will likely take them if they pass their criteria for suitability.
   1.332 -The more <quote>good</quote> changes you contribute to a maintainer, the more
   1.333 -likely they are to trust your judgment and accept your changes.  If
   1.334 -you're well-known and maintain a long-lived branch for something Linus
   1.335 -hasn't yet accepted, people with similar interests may pull your
   1.336 -changes regularly to keep up with your work.
   1.337 -</para>
   1.338 -
   1.339 -<para>Reputation and acclaim don't necessarily cross subsystem or <quote>people</quote>
   1.340 -boundaries.  If you're a respected but specialised storage hacker, and
   1.341 -you try to fix a networking bug, that change will receive a level of
   1.342 -scrutiny from a network maintainer comparable to a change from a
   1.343 -complete stranger.
   1.344 -</para>
   1.345 -
   1.346 -<para>To people who come from more orderly project backgrounds, the
   1.347 -comparatively chaotic Linux kernel development process often seems
   1.348 -completely insane.  It's subject to the whims of individuals; people
   1.349 -make sweeping changes whenever they deem it appropriate; and the pace
   1.350 -of development is astounding.  And yet Linux is a highly successful,
   1.351 -well-regarded piece of software.
   1.352 -</para>
   1.353 -
   1.354 -</sect2>
   1.355 -<sect2>
   1.356 -<title>Pull-only versus shared-push collaboration</title>
   1.357 -
   1.358 -<para>A perpetual source of heat in the open source community is whether a
   1.359 -development model in which people only ever pull changes from others
   1.360 -is <quote>better than</quote> one in which multiple people can push changes to a
   1.361 -shared repository.
   1.362 -</para>
   1.363 -
   1.364 -<para>Typically, the backers of the shared-push model use tools that
   1.365 -actively enforce this approach.  If you're using a centralised
   1.366 -revision control tool such as Subversion, there's no way to make a
   1.367 -choice over which model you'll use: the tool gives you shared-push,
   1.368 -and if you want to do anything else, you'll have to roll your own
   1.369 -approach on top (such as applying a patch by hand).
   1.370 -</para>
   1.371 -
   1.372 -<para>A good distributed revision control tool, such as Mercurial, will
   1.373 -support both models.  You and your collaborators can then structure
   1.374 -how you work together based on your own needs and preferences, not on
   1.375 -what contortions your tools force you into.
   1.376 -</para>
   1.377 -
   1.378 -</sect2>
   1.379 -<sect2>
   1.380 -<title>Where collaboration meets branch management</title>
   1.381 -
   1.382 -<para>Once you and your team set up some shared repositories and start
   1.383 -propagating changes back and forth between local and shared repos, you
   1.384 -begin to face a related, but slightly different challenge: that of
   1.385 -managing the multiple directions in which your team may be moving at
   1.386 -once.  Even though this subject is intimately related to how your team
   1.387 -collaborates, it's dense enough to merit treatment of its own, in
   1.388 -chapter <xref linkend="chap:branch"/>.
   1.389 -</para>
   1.390 -
   1.391 -</sect2>
   1.392 -</sect1>
   1.393 -<sect1>
   1.394 -<title>The technical side of sharing</title>
   1.395 -
   1.396 -<para>The remainder of this chapter is devoted to the question of serving
   1.397 -data to your collaborators.
   1.398 -</para>
   1.399 -
   1.400 -</sect1>
   1.401 -<sect1>
   1.402 -<title>Informal sharing with <command role="hg-cmd">hg serve</command></title>
   1.403 -<para>\label{sec:collab:serve}
   1.404 -</para>
   1.405 -
   1.406 -<para>Mercurial's <command role="hg-cmd">hg serve</command> command is wonderfully suited to small,
   1.407 -tight-knit, and fast-paced group environments.  It also provides a
   1.408 -great way to get a feel for using Mercurial commands over a network.
   1.409 -</para>
   1.410 -
   1.411 -<para>Run <command role="hg-cmd">hg serve</command> inside a repository, and in under a second it will
   1.412 -bring up a specialised HTTP server; this will accept connections from
   1.413 -any client, and serve up data for that repository until you terminate
   1.414 -it.  Anyone who knows the URL of the server you just started, and can
   1.415 -talk to your computer over the network, can then use a web browser or
   1.416 -Mercurial to read data from that repository.  A URL for a
   1.417 -<command role="hg-cmd">hg serve</command> instance running on a laptop is likely to look something
   1.418 -like <literal>http://my-laptop.local:8000/</literal>.
   1.419 -</para>
   1.420 -
   1.421 -<para>The <command role="hg-cmd">hg serve</command> command is <emphasis>not</emphasis> a general-purpose web server.
   1.422 -It can do only two things:
   1.423 -</para>
   1.424 -<itemizedlist>
   1.425 -<listitem><para>Allow people to browse the history of the repository it's
   1.426 -  serving, from their normal web browsers.
   1.427 -</para>
   1.428 -</listitem>
   1.429 -<listitem><para>Speak Mercurial's wire protocol, so that people can
   1.430 -  <command role="hg-cmd">hg clone</command> or <command role="hg-cmd">hg pull</command> changes from that repository.
   1.431 -</para>
   1.432 -</listitem></itemizedlist>
   1.433 -<para>In particular, <command role="hg-cmd">hg serve</command> won't allow remote users to <emphasis>modify</emphasis>
   1.434 -your repository.  It's intended for read-only use.
   1.435 -</para>
   1.436 -
   1.437 -<para>If you're getting started with Mercurial, there's nothing to prevent
   1.438 -you from using <command role="hg-cmd">hg serve</command> to serve up a repository on your own
   1.439 -computer, then use commands like <command role="hg-cmd">hg clone</command>, <command role="hg-cmd">hg incoming</command>, and
   1.440 -so on to talk to that server as if the repository was hosted remotely.
   1.441 -This can help you to quickly get acquainted with using commands on
   1.442 -network-hosted repositories.
   1.443 -</para>
   1.444 -
   1.445 -<sect2>
   1.446 -<title>A few things to keep in mind</title>
   1.447 -
   1.448 -<para>Because it provides unauthenticated read access to all clients, you
   1.449 -should only use <command role="hg-cmd">hg serve</command> in an environment where you either don't
   1.450 -care, or have complete control over, who can access your network and
   1.451 -pull data from your repository.
   1.452 -</para>
   1.453 -
   1.454 -<para>The <command role="hg-cmd">hg serve</command> command knows nothing about any firewall software
   1.455 -you might have installed on your system or network.  It cannot detect
   1.456 -or control your firewall software.  If other people are unable to talk
   1.457 -to a running <command role="hg-cmd">hg serve</command> instance, the second thing you should do
   1.458 -(<emphasis>after</emphasis> you make sure that they're using the correct URL) is
   1.459 -check your firewall configuration.
   1.460 -</para>
   1.461 -
   1.462 -<para>By default, <command role="hg-cmd">hg serve</command> listens for incoming connections on
   1.463 -port 8000.  If another process is already listening on the port you
   1.464 -want to use, you can specify a different port to listen on using the
   1.465 -<option role="hg-opt-serve">-p</option> option.
   1.466 -</para>
   1.467 -
   1.468 -<para>Normally, when <command role="hg-cmd">hg serve</command> starts, it prints no output, which can be
   1.469 -a bit unnerving.  If you'd like to confirm that it is indeed running
   1.470 -correctly, and find out what URL you should send to your
   1.471 -collaborators, start it with the <option role="hg-opt-global">-v</option> option.
   1.472 -</para>
   1.473 -
   1.474 -</sect2>
   1.475 -</sect1>
   1.476 -<sect1>
   1.477 -<title>Using the Secure Shell (ssh) protocol</title>
   1.478 -<para>\label{sec:collab:ssh}
   1.479 -</para>
   1.480 -
   1.481 -<para>You can pull and push changes securely over a network connection using
   1.482 -the Secure Shell (<literal>ssh</literal>) protocol.  To use this successfully,
   1.483 -you may have to do a little bit of configuration on the client or
   1.484 -server sides.
   1.485 -</para>
   1.486 -
   1.487 -<para>If you're not familiar with ssh, it's a network protocol that lets you
   1.488 -securely communicate with another computer.  To use it with Mercurial,
   1.489 -you'll be setting up one or more user accounts on a server so that
   1.490 -remote users can log in and execute commands.
   1.491 -</para>
   1.492 -
   1.493 -<para>(If you <emphasis>are</emphasis> familiar with ssh, you'll probably find some of the
   1.494 -material that follows to be elementary in nature.)
   1.495 -</para>
   1.496 -
   1.497 -<sect2>
   1.498 -<title>How to read and write ssh URLs</title>
   1.499 -
   1.500 -<para>An ssh URL tends to look like this:
   1.501 -</para>
   1.502 -<programlisting>
   1.503 -<para>  ssh://bos@hg.serpentine.com:22/hg/hgbook
   1.504 -</para>
   1.505 +<chapter id="cha:collab">
   1.506 +  <?dbhtml filename="collaborating-with-other-people.html"?>
   1.507 +  <title>Collaborating with other people</title>
   1.508 +
   1.509 +  <para id="x_44a">As a completely decentralised tool, Mercurial doesn't impose
   1.510 +    any policy on how people ought to work with each other.  However,
   1.511 +    if you're new to distributed revision control, it helps to have
   1.512 +    some tools and examples in mind when you're thinking about
   1.513 +    possible workflow models.</para>
   1.514 +
   1.515 +  <sect1>
   1.516 +    <title>Mercurial's web interface</title>
   1.517 +
   1.518 +    <para id="x_44b">Mercurial has a powerful web interface that provides several
   1.519 +      useful capabilities.</para>
   1.520 +
   1.521 +    <para id="x_44c">For interactive use, the web interface lets you browse a
   1.522 +      single repository or a collection of repositories.  You can view
   1.523 +      the history of a repository, examine each change (comments and
   1.524 +      diffs), and view the contents of each directory and file.  You
   1.525 +      can even get a view of history that gives a graphical view of
   1.526 +      the relationships between individual changes and merges.</para>
   1.527 +
   1.528 +    <para id="x_44d">Also for human consumption, the web interface provides
   1.529 +      Atom and RSS feeds of the changes in a repository.  This lets you
   1.530 +      <quote>subscribe</quote> to a repository using your favorite
   1.531 +      feed reader, and be automatically notified of activity in that
   1.532 +      repository as soon as it happens.  I find this capability much
   1.533 +      more convenient than the model of subscribing to a mailing list
   1.534 +      to which notifications are sent, as it requires no additional
   1.535 +      configuration on the part of whoever is serving the
   1.536 +      repository.</para>
   1.537 +
   1.538 +    <para id="x_44e">The web interface also lets remote users clone a repository,
   1.539 +      pull changes from it, and (when the server is configured to
   1.540 +      permit it) push changes back to it.  Mercurial's HTTP tunneling
   1.541 +      protocol aggressively compresses data, so that it works
   1.542 +      efficiently even over low-bandwidth network connections.</para>
   1.543 +
   1.544 +    <para id="x_44f">The easiest way to get started with the web interface is to
   1.545 +      use your web browser to visit an existing repository, such as
   1.546 +      the master Mercurial repository at <ulink
   1.547 +	url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para>
   1.548 +
   1.549 +    <para id="x_450">If you're interested in providing a web interface
   1.550 +      to your own repositories, there are several good ways to do
   1.551 +      this.</para>
   1.552 +
   1.553 +    <para id="x_69d">The easiest and fastest way to get started in an informal
   1.554 +      environment is to use the <command role="hg-cmd">hg
   1.555 +	serve</command> command, which is best suited to short-term
   1.556 +      <quote>lightweight</quote> serving.  See <xref
   1.557 +	linkend="sec:collab:serve"/> below for details of how to use
   1.558 +      this command.</para>
   1.559 +
   1.560 +    <para id="x_69e">For longer-lived repositories that you'd like to
   1.561 +      have permanently available, there are several public hosting
   1.562 +      services available.  Some are free to open source projects,
   1.563 +      while others offer paid commercial hosting.  An up-to-date list
   1.564 +      is available at <ulink
   1.565 +	url="http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting">http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting</ulink>.</para>
   1.566 +
   1.567 +    <para id="x_6a0">If you would prefer to host your own repositories, Mercurial
   1.568 +      has built-in support for several popular hosting technologies,
   1.569 +      most notably CGI (Common Gateway Interface), and WSGI (Web
   1.570 +      Services Gateway Interface).  See <xref
   1.571 +	linkend="sec:collab:cgi"/> for details of CGI and WSGI
   1.572 +      configuration.</para>
   1.573 +  </sect1>
   1.574 +
   1.575 +  <sect1>
   1.576 +    <title>Collaboration models</title>
   1.577 +
   1.578 +    <para id="x_451">With a suitably flexible tool, making decisions about
   1.579 +      workflow is much more of a social engineering challenge than a
   1.580 +      technical one. Mercurial imposes few limitations on how you can
   1.581 +      structure the flow of work in a project, so it's up to you and
   1.582 +      your group to set up and live with a model that matches your own
   1.583 +      particular needs.</para>
   1.584 +
   1.585 +    <sect2>
   1.586 +      <title>Factors to keep in mind</title>
   1.587 +
   1.588 +      <para id="x_452">The most important aspect of any model that you must keep
   1.589 +	in mind is how well it matches the needs and capabilities of
   1.590 +	the people who will be using it.  This might seem
   1.591 +	self-evident; even so, you still can't afford to forget it for
   1.592 +	a moment.</para>
   1.593 +
   1.594 +      <para id="x_453">I once put together a workflow model that seemed to make
   1.595 +	perfect sense to me, but that caused a considerable amount of
   1.596 +	consternation and strife within my development team.  In spite
   1.597 +	of my attempts to explain why we needed a complex set of
   1.598 +	branches, and how changes ought to flow between them, a few
   1.599 +	team members revolted.  Even though they were smart people,
   1.600 +	they didn't want to pay attention to the constraints we were
   1.601 +	operating under, or face the consequences of those constraints
   1.602 +	in the details of the model that I was advocating.</para>
   1.603 +
   1.604 +      <para id="x_454">Don't sweep foreseeable social or technical problems under
   1.605 +	the rug. Whatever scheme you put into effect, you should plan
   1.606 +	for mistakes and problem scenarios.  Consider adding automated
   1.607 +	machinery to prevent, or quickly recover from, trouble that
   1.608 +	you can anticipate.  As an example, if you intend to have a
   1.609 +	branch with not-for-release changes in it, you'd do well to
   1.610 +	think early about the possibility that someone might
   1.611 +	accidentally merge those changes into a release branch.  You
   1.612 +	could avoid this particular problem by writing a hook that
   1.613 +	prevents changes from being merged from an inappropriate
   1.614 +	branch.</para>
   1.615 +    </sect2>
   1.616 +
   1.617 +    <sect2>
   1.618 +      <title>Informal anarchy</title>
   1.619 +
   1.620 +      <para id="x_455">I wouldn't suggest an <quote>anything goes</quote>
   1.621 +	approach as something sustainable, but it's a model that's
   1.622 +	easy to grasp, and it works perfectly well in a few unusual
   1.623 +	situations.</para>
   1.624 +
   1.625 +      <para id="x_456">As one example, many projects have a loose-knit group of
   1.626 +	collaborators who rarely physically meet each other.  Some
   1.627 +	groups like to overcome the isolation of working at a distance
   1.628 +	by organizing occasional <quote>sprints</quote>.  In a sprint,
   1.629 +	a number of people get together in a single location (a
   1.630 +	company's conference room, a hotel meeting room, that kind of
   1.631 +	place) and spend several days more or less locked in there,
   1.632 +	hacking intensely on a handful of projects.</para>
   1.633 +
   1.634 +      <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the
   1.635 +	<command role="hg-cmd">hg serve</command> command, since
   1.636 +	<command role="hg-cmd">hg serve</command> does not require any
   1.637 +	fancy server infrastructure.  You can get started with
   1.638 +	<command role="hg-cmd">hg serve</command> in moments, by
   1.639 +	reading <xref linkend="sec:collab:serve"/> below.  Then simply
   1.640 +	tell the person next to you that you're running a server, send
   1.641 +	the URL to them in an instant message, and you immediately
   1.642 +	have a quick-turnaround way to work together.  They can type
   1.643 +	your URL into their web browser and quickly review your
   1.644 +	changes; or they can pull a bugfix from you and verify it; or
   1.645 +	they can clone a branch containing a new feature and try it
   1.646 +	out.</para>
   1.647 +
   1.648 +      <para id="x_458">The charm, and the problem, with doing things
   1.649 +	in an ad hoc fashion like this is that only people who know
   1.650 +	about your changes, and where they are, can see them.  Such an
   1.651 +	informal approach simply doesn't scale beyond a handful
   1.652 +	people, because each individual needs to know about
   1.653 +	<emphasis>n</emphasis> different repositories to pull
   1.654 +	from.</para>
   1.655 +    </sect2>
   1.656 +
   1.657 +    <sect2>
   1.658 +      <title>A single central repository</title>
   1.659 +
   1.660 +      <para id="x_459">For smaller projects migrating from a centralised revision
   1.661 +	control tool, perhaps the easiest way to get started is to
   1.662 +	have changes flow through a single shared central repository.
   1.663 +	This is also the most common <quote>building block</quote> for
   1.664 +	more ambitious workflow schemes.</para>
   1.665 +
   1.666 +      <para id="x_45a">Contributors start by cloning a copy of this repository.
   1.667 +	They can pull changes from it whenever they need to, and some
   1.668 +	(perhaps all) developers have permission to push a change back
   1.669 +	when they're ready for other people to see it.</para>
   1.670 +
   1.671 +      <para id="x_45b">Under this model, it can still often make sense for people
   1.672 +	to pull changes directly from each other, without going
   1.673 +	through the central repository.  Consider a case in which I
   1.674 +	have a tentative bug fix, but I am worried that if I were to
   1.675 +	publish it to the central repository, it might subsequently
   1.676 +	break everyone else's trees as they pull it.  To reduce the
   1.677 +	potential for damage, I can ask you to clone my repository
   1.678 +	into a temporary repository of your own and test it.  This
   1.679 +	lets us put off publishing the potentially unsafe change until
   1.680 +	it has had a little testing.</para>
   1.681 +
   1.682 +      <para id="x_45c">If a team is hosting its own repository in this
   1.683 +	kind of scenario, people will usually use the
   1.684 +	<command>ssh</command> protocol to securely push changes to
   1.685 +	the central repository, as documented in <xref
   1.686 +	  linkend="sec:collab:ssh"/>.  It's also usual to publish a
   1.687 +	read-only copy of the repository over HTTP, as in
   1.688 +	<xref linkend="sec:collab:cgi"/>. Publishing over HTTP
   1.689 +	satisfies the needs of people who don't have push access, and
   1.690 +	those who want to use web browsers to browse the repository's
   1.691 +	history.</para>
   1.692 +    </sect2>
   1.693 +
   1.694 +    <sect2>
   1.695 +      <title>A hosted central repository</title>
   1.696 +
   1.697 +      <para id="x_6a1">A wonderful thing about public hosting services like
   1.698 +	<ulink url="http://bitbucket.org/">Bitbucket</ulink> is that
   1.699 +	not only do they handle the fiddly server configuration
   1.700 +	details, such as user accounts, authentication, and secure
   1.701 +	wire protocols, they provide additional infrastructure to make
   1.702 +	this model work well.</para>
   1.703 +
   1.704 +      <para id="x_6a2">For instance, a well-engineered hosting service will let
   1.705 +	people clone their own copies of a repository with a single
   1.706 +	click.  This lets people work in separate spaces and share
   1.707 +	their changes when they're ready.</para>
   1.708 +
   1.709 +      <para id="x_6a3">In addition, a good hosting service will let people
   1.710 +	communicate with each other, for instance to say <quote>there
   1.711 +	  are changes ready for you to review in this
   1.712 +	  tree</quote>.</para>
   1.713 +    </sect2>
   1.714 +
   1.715 +    <sect2>
   1.716 +      <title>Working with multiple branches</title>
   1.717 +
   1.718 +      <para id="x_45d">Projects of any significant size naturally tend to make
   1.719 +	progress on several fronts simultaneously.  In the case of
   1.720 +	software, it's common for a project to go through periodic
   1.721 +	official releases.  A release might then go into
   1.722 +	<quote>maintenance mode</quote> for a while after its first
   1.723 +	publication; maintenance releases tend to contain only bug
   1.724 +	fixes, not new features.  In parallel with these maintenance
   1.725 +	releases, one or more future releases may be under
   1.726 +	development.  People normally use the word
   1.727 +	<quote>branch</quote> to refer to one of these many slightly
   1.728 +	different directions in which development is
   1.729 +	proceeding.</para>
   1.730 +
   1.731 +      <para id="x_45e">Mercurial is particularly well suited to managing a number
   1.732 +	of simultaneous, but not identical, branches.  Each
   1.733 +	<quote>development direction</quote> can live in its own
   1.734 +	central repository, and you can merge changes from one to
   1.735 +	another as the need arises.  Because repositories are
   1.736 +	independent of each other, unstable changes in a development
   1.737 +	branch will never affect a stable branch unless someone
   1.738 +	explicitly merges those changes into the stable branch.</para>
   1.739 +
   1.740 +      <para id="x_45f">Here's an example of how this can work in practice.  Let's
   1.741 +	say you have one <quote>main branch</quote> on a central
   1.742 +	server.</para>
   1.743 +
   1.744 +      &interaction.branching.init;
   1.745 +
   1.746 +      <para id="x_460">People clone it, make changes locally, test them, and push
   1.747 +	them back.</para>
   1.748 +
   1.749 +      <para id="x_461">Once the main branch reaches a release milestone, you can
   1.750 +	use the <command role="hg-cmd">hg tag</command> command to
   1.751 +	give a permanent name to the milestone revision.</para>
   1.752 +
   1.753 +	&interaction.branching.tag;
   1.754 +
   1.755 +      <para id="x_462">Let's say some ongoing
   1.756 +	development occurs on the main branch.</para>
   1.757 +
   1.758 +      &interaction.branching.main;
   1.759 +
   1.760 +      <para id="x_463">Using the tag that was recorded at the milestone, people
   1.761 +	who clone that repository at any time in the future can use
   1.762 +	<command role="hg-cmd">hg update</command> to get a copy of
   1.763 +	the working directory exactly as it was when that tagged
   1.764 +	revision was committed.</para>
   1.765 +
   1.766 +      &interaction.branching.update;
   1.767 +
   1.768 +      <para id="x_464">In addition, immediately after the main branch is tagged,
   1.769 +	we can then clone the main branch on the server to a new
   1.770 +	<quote>stable</quote> branch, also on the server.</para>
   1.771 +
   1.772 +      &interaction.branching.clone;
   1.773 +
   1.774 +      <para id="x_465">If we need to make a change to the stable
   1.775 +	branch, we can then clone <emphasis>that</emphasis>
   1.776 +	repository, make our changes, commit, and push our changes
   1.777 +	back there.</para>
   1.778 +
   1.779 +      &interaction.branching.stable;
   1.780 +
   1.781 +      <para id="x_466">Because Mercurial repositories are independent, and
   1.782 +	Mercurial doesn't move changes around automatically, the
   1.783 +	stable and main branches are <emphasis>isolated</emphasis>
   1.784 +	from each other.  The changes that we made on the main branch
   1.785 +	don't <quote>leak</quote> to the stable branch, and vice
   1.786 +	versa.</para>
   1.787 +
   1.788 +      <para id="x_467">We'll often want all of our bugfixes on the stable
   1.789 +	branch to show up on the main branch, too.  Rather than
   1.790 +	rewrite a bugfix on the main branch, we can simply pull and
   1.791 +	merge changes from the stable to the main branch, and
   1.792 +	Mercurial will bring those bugfixes in for us.</para>
   1.793 +
   1.794 +      &interaction.branching.merge;
   1.795 +
   1.796 +      <para id="x_468">The main branch will still contain changes that
   1.797 +	are not on the stable branch, but it will also contain all of
   1.798 +	the bugfixes from the stable branch.  The stable branch
   1.799 +	remains unaffected by these changes, since changes are only
   1.800 +	flowing from the stable to the main branch, and not the other
   1.801 +	way.</para>
   1.802 +    </sect2>
   1.803 +
   1.804 +    <sect2>
   1.805 +      <title>Feature branches</title>
   1.806 +
   1.807 +      <para id="x_469">For larger projects, an effective way to manage change is
   1.808 +	to break up a team into smaller groups.  Each group has a
   1.809 +	shared branch of its own, cloned from a single
   1.810 +	<quote>master</quote> branch used by the entire project.
   1.811 +	People working on an individual branch are typically quite
   1.812 +	isolated from developments on other branches.</para>
   1.813 +
   1.814 +      <figure id="fig:collab:feature-branches">
   1.815 +	<title>Feature branches</title>
   1.816 +	<mediaobject>
   1.817 +	  <imageobject><imagedata width="100%" fileref="figs/feature-branches.png"/></imageobject>
   1.818 +	  <textobject><phrase>XXX add text</phrase></textobject>
   1.819 +	</mediaobject>
   1.820 +      </figure>
   1.821 +
   1.822 +      <para id="x_46b">When a particular feature is deemed to be in suitable
   1.823 +	shape, someone on that feature team pulls and merges from the
   1.824 +	master branch into the feature branch, then pushes back up to
   1.825 +	the master branch.</para>
   1.826 +    </sect2>
   1.827 +
   1.828 +    <sect2>
   1.829 +      <title>The release train</title>
   1.830 +
   1.831 +      <para id="x_46c">Some projects are organized on a <quote>train</quote>
   1.832 +	basis: a release is scheduled to happen every few months, and
   1.833 +	whatever features are ready when the <quote>train</quote> is
   1.834 +	ready to leave are allowed in.</para>
   1.835 +
   1.836 +      <para id="x_46d">This model resembles working with feature branches.  The
   1.837 +	difference is that when a feature branch misses a train,
   1.838 +	someone on the feature team pulls and merges the changes that
   1.839 +	went out on that train release into the feature branch, and
   1.840 +	the team continues its work on top of that release so that
   1.841 +	their feature can make the next release.</para>
   1.842 +    </sect2>
   1.843 +
   1.844 +    <sect2>
   1.845 +      <title>The Linux kernel model</title>
   1.846 +
   1.847 +      <para id="x_46e">The development of the Linux kernel has a shallow
   1.848 +	hierarchical structure, surrounded by a cloud of apparent
   1.849 +	chaos.  Because most Linux developers use
   1.850 +	<command>git</command>, a distributed revision control tool
   1.851 +	with capabilities similar to Mercurial, it's useful to
   1.852 +	describe the way work flows in that environment; if you like
   1.853 +	the ideas, the approach translates well across tools.</para>
   1.854 +
   1.855 +      <para id="x_46f">At the center of the community sits Linus Torvalds, the
   1.856 +	creator of Linux.  He publishes a single source repository
   1.857 +	that is considered the <quote>authoritative</quote> current
   1.858 +	tree by the entire developer community. Anyone can clone
   1.859 +	Linus's tree, but he is very choosy about whose trees he pulls
   1.860 +	from.</para>
   1.861 +
   1.862 +      <para id="x_470">Linus has a number of <quote>trusted lieutenants</quote>.
   1.863 +	As a general rule, he pulls whatever changes they publish, in
   1.864 +	most cases without even reviewing those changes.  Some of
   1.865 +	those lieutenants are generally agreed to be
   1.866 +	<quote>maintainers</quote>, responsible for specific
   1.867 +	subsystems within the kernel.  If a random kernel hacker wants
   1.868 +	to make a change to a subsystem that they want to end up in
   1.869 +	Linus's tree, they must find out who the subsystem's
   1.870 +	maintainer is, and ask that maintainer to take their change.
   1.871 +	If the maintainer reviews their changes and agrees to take
   1.872 +	them, they'll pass them along to Linus in due course.</para>
   1.873 +
   1.874 +      <para id="x_471">Individual lieutenants have their own approaches to
   1.875 +	reviewing, accepting, and publishing changes; and for deciding
   1.876 +	when to feed them to Linus.  In addition, there are several
   1.877 +	well known branches that people use for different purposes.
   1.878 +	For example, a few people maintain <quote>stable</quote>
   1.879 +	repositories of older versions of the kernel, to which they
   1.880 +	apply critical fixes as needed.  Some maintainers publish
   1.881 +	multiple trees: one for experimental changes; one for changes
   1.882 +	that they are about to feed upstream; and so on.  Others just
   1.883 +	publish a single tree.</para>
   1.884 +
   1.885 +      <para id="x_472">This model has two notable features.  The first is that
   1.886 +	it's <quote>pull only</quote>.  You have to ask, convince, or
   1.887 +	beg another developer to take a change from you, because there
   1.888 +	are almost no trees to which more than one person can push,
   1.889 +	and there's no way to push changes into a tree that someone
   1.890 +	else controls.</para>
   1.891 +
   1.892 +      <para id="x_473">The second is that it's based on reputation and acclaim.
   1.893 +	If you're an unknown, Linus will probably ignore changes from
   1.894 +	you without even responding.  But a subsystem maintainer will
   1.895 +	probably review them, and will likely take them if they pass
   1.896 +	their criteria for suitability. The more <quote>good</quote>
   1.897 +	changes you contribute to a maintainer, the more likely they
   1.898 +	are to trust your judgment and accept your changes.  If you're
   1.899 +	well-known and maintain a long-lived branch for something
   1.900 +	Linus hasn't yet accepted, people with similar interests may
   1.901 +	pull your changes regularly to keep up with your work.</para>
   1.902 +
   1.903 +      <para id="x_474">Reputation and acclaim don't necessarily cross subsystem
   1.904 +	or <quote>people</quote> boundaries.  If you're a respected
   1.905 +	but specialised storage hacker, and you try to fix a
   1.906 +	networking bug, that change will receive a level of scrutiny
   1.907 +	from a network maintainer comparable to a change from a
   1.908 +	complete stranger.</para>
   1.909 +
   1.910 +      <para id="x_475">To people who come from more orderly project backgrounds,
   1.911 +	the comparatively chaotic Linux kernel development process
   1.912 +	often seems completely insane.  It's subject to the whims of
   1.913 +	individuals; people make sweeping changes whenever they deem
   1.914 +	it appropriate; and the pace of development is astounding.
   1.915 +	And yet Linux is a highly successful, well-regarded piece of
   1.916 +	software.</para>
   1.917 +    </sect2>
   1.918 +
   1.919 +    <sect2>
   1.920 +      <title>Pull-only versus shared-push collaboration</title>
   1.921 +
   1.922 +      <para id="x_476">A perpetual source of heat in the open source community is
   1.923 +	whether a development model in which people only ever pull
   1.924 +	changes from others is <quote>better than</quote> one in which
   1.925 +	multiple people can push changes to a shared
   1.926 +	repository.</para>
   1.927 +
   1.928 +      <para id="x_477">Typically, the backers of the shared-push model use tools
   1.929 +	that actively enforce this approach.  If you're using a
   1.930 +	centralised revision control tool such as Subversion, there's
   1.931 +	no way to make a choice over which model you'll use: the tool
   1.932 +	gives you shared-push, and if you want to do anything else,
   1.933 +	you'll have to roll your own approach on top (such as applying
   1.934 +	a patch by hand).</para>
   1.935 +
   1.936 +      <para id="x_478">A good distributed revision control tool will
   1.937 +	support both models.  You and your collaborators can then
   1.938 +	structure how you work together based on your own needs and
   1.939 +	preferences, not on what contortions your tools force you
   1.940 +	into.</para>
   1.941 +    </sect2>
   1.942 +    <sect2>
   1.943 +      <title>Where collaboration meets branch management</title>
   1.944 +
   1.945 +      <para id="x_479">Once you and your team set up some shared
   1.946 +	repositories and start propagating changes back and forth
   1.947 +	between local and shared repos, you begin to face a related,
   1.948 +	but slightly different challenge: that of managing the
   1.949 +	multiple directions in which your team may be moving at once.
   1.950 +	Even though this subject is intimately related to how your
   1.951 +	team collaborates, it's dense enough to merit treatment of its
   1.952 +	own, in <xref linkend="chap:branch"/>.</para>
   1.953 +    </sect2>
   1.954 +  </sect1>
   1.955 +
   1.956 +  <sect1>
   1.957 +    <title>The technical side of sharing</title>
   1.958 +
   1.959 +    <para id="x_47a">The remainder of this chapter is devoted to the question of
   1.960 +      sharing changes with your collaborators.</para>
   1.961 +  </sect1>
   1.962 +
   1.963 +  <sect1 id="sec:collab:serve">
   1.964 +    <title>Informal sharing with <command role="hg-cmd">hg
   1.965 +	serve</command></title>
   1.966 +
   1.967 +    <para id="x_47b">Mercurial's <command role="hg-cmd">hg serve</command>
   1.968 +      command is wonderfully suited to small, tight-knit, and
   1.969 +      fast-paced group environments.  It also provides a great way to
   1.970 +      get a feel for using Mercurial commands over a network.</para>
   1.971 +
   1.972 +    <para id="x_47c">Run <command role="hg-cmd">hg serve</command> inside a
   1.973 +      repository, and in under a second it will bring up a specialised
   1.974 +      HTTP server; this will accept connections from any client, and
   1.975 +      serve up data for that repository until you terminate it.
   1.976 +      Anyone who knows the URL of the server you just started, and can
   1.977 +      talk to your computer over the network, can then use a web
   1.978 +      browser or Mercurial to read data from that repository.  A URL
   1.979 +      for a <command role="hg-cmd">hg serve</command> instance running
   1.980 +      on a laptop is likely to look something like
   1.981 +      <literal>http://my-laptop.local:8000/</literal>.</para>
   1.982 +
   1.983 +    <para id="x_47d">The <command role="hg-cmd">hg serve</command> command is
   1.984 +      <emphasis>not</emphasis> a general-purpose web server. It can do
   1.985 +      only two things:</para>
   1.986 +    <itemizedlist>
   1.987 +      <listitem><para id="x_47e">Allow people to browse the history of the
   1.988 +	  repository it's serving, from their normal web
   1.989 +	  browsers.</para>
   1.990 +      </listitem>
   1.991 +      <listitem><para id="x_47f">Speak Mercurial's wire protocol, so that people
   1.992 +	  can <command role="hg-cmd">hg clone</command> or <command
   1.993 +	    role="hg-cmd">hg pull</command> changes from that
   1.994 +	  repository.</para>
   1.995 +      </listitem></itemizedlist>
   1.996 +    <para id="x_480">In particular, <command role="hg-cmd">hg serve</command>
   1.997 +      won't allow remote users to <emphasis>modify</emphasis> your
   1.998 +      repository.  It's intended for read-only use.</para>
   1.999 +
  1.1000 +    <para id="x_481">If you're getting started with Mercurial, there's nothing to
  1.1001 +      prevent you from using <command role="hg-cmd">hg serve</command>
  1.1002 +      to serve up a repository on your own computer, then use commands
  1.1003 +      like <command role="hg-cmd">hg clone</command>, <command
  1.1004 +	role="hg-cmd">hg incoming</command>, and so on to talk to that
  1.1005 +      server as if the repository was hosted remotely. This can help
  1.1006 +      you to quickly get acquainted with using commands on
  1.1007 +      network-hosted repositories.</para>
  1.1008 +
  1.1009 +    <sect2>
  1.1010 +      <title>A few things to keep in mind</title>
  1.1011 +
  1.1012 +      <para id="x_482">Because it provides unauthenticated read access to all
  1.1013 +	clients, you should only use <command role="hg-cmd">hg
  1.1014 +	  serve</command> in an environment where you either don't
  1.1015 +	care, or have complete control over, who can access your
  1.1016 +	network and pull data from your repository.</para>
  1.1017 +
  1.1018 +      <para id="x_483">The <command role="hg-cmd">hg serve</command> command
  1.1019 +	knows nothing about any firewall software you might have
  1.1020 +	installed on your system or network.  It cannot detect or
  1.1021 +	control your firewall software.  If other people are unable to
  1.1022 +	talk to a running <command role="hg-cmd">hg serve</command>
  1.1023 +	instance, the second thing you should do
  1.1024 +	(<emphasis>after</emphasis> you make sure that they're using
  1.1025 +	the correct URL) is check your firewall configuration.</para>
  1.1026 +
  1.1027 +      <para id="x_484">By default, <command role="hg-cmd">hg serve</command>
  1.1028 +	listens for incoming connections on port 8000.  If another
  1.1029 +	process is already listening on the port you want to use, you
  1.1030 +	can specify a different port to listen on using the <option
  1.1031 +	  role="hg-opt-serve">-p</option> option.</para>
  1.1032 +
  1.1033 +      <para id="x_485">Normally, when <command role="hg-cmd">hg serve</command>
  1.1034 +	starts, it prints no output, which can be a bit unnerving.  If
  1.1035 +	you'd like to confirm that it is indeed running correctly, and
  1.1036 +	find out what URL you should send to your collaborators, start
  1.1037 +	it with the <option role="hg-opt-global">-v</option>
  1.1038 +	option.</para>
  1.1039 +    </sect2>
  1.1040 +  </sect1>
  1.1041 +
  1.1042 +  <sect1 id="sec:collab:ssh">
  1.1043 +    <title>Using the Secure Shell (ssh) protocol</title>
  1.1044 +
  1.1045 +    <para id="x_486">You can pull and push changes securely over a network
  1.1046 +      connection using the Secure Shell (<literal>ssh</literal>)
  1.1047 +      protocol.  To use this successfully, you may have to do a little
  1.1048 +      bit of configuration on the client or server sides.</para>
  1.1049 +
  1.1050 +    <para id="x_487">If you're not familiar with ssh, it's the name of
  1.1051 +      both a command and a network protocol that let you securely
  1.1052 +      communicate with another computer.  To use it with Mercurial,
  1.1053 +      you'll be setting up one or more user accounts on a server so
  1.1054 +      that remote users can log in and execute commands.</para>
  1.1055 +
  1.1056 +    <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll
  1.1057 +      probably find some of the material that follows to be elementary
  1.1058 +      in nature.)</para>
  1.1059 +
  1.1060 +    <sect2>
  1.1061 +      <title>How to read and write ssh URLs</title>
  1.1062 +
  1.1063 +      <para id="x_489">An ssh URL tends to look like this:</para>
  1.1064 +      <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting>
  1.1065 +      <orderedlist>
  1.1066 +	<listitem><para id="x_48a">The <quote><literal>ssh://</literal></quote>
  1.1067 +	    part tells Mercurial to use the ssh protocol.</para>
  1.1068 +	</listitem>
  1.1069 +	<listitem><para id="x_48b">The <quote><literal>bos@</literal></quote>
  1.1070 +	    component indicates what username to log into the server
  1.1071 +	    as.  You can leave this out if the remote username is the
  1.1072 +	    same as your local username.</para>
  1.1073 +	</listitem>
  1.1074 +	<listitem><para id="x_48c">The
  1.1075 +	    <quote><literal>hg.serpentine.com</literal></quote> gives
  1.1076 +	    the hostname of the server to log into.</para>
  1.1077 +	</listitem>
  1.1078 +	<listitem><para id="x_48d">The <quote>:22</quote> identifies the port
  1.1079 +	    number to connect to the server on.  The default port is
  1.1080 +	    22, so you only need to specify a colon and port number if
  1.1081 +	    you're <emphasis>not</emphasis> using port 22.</para>
  1.1082 +	</listitem>
  1.1083 +	<listitem><para id="x_48e">The remainder of the URL is the local path to
  1.1084 +	    the repository on the server.</para>
  1.1085 +	</listitem></orderedlist>
  1.1086 +
  1.1087 +      <para id="x_48f">There's plenty of scope for confusion with the path
  1.1088 +	component of ssh URLs, as there is no standard way for tools
  1.1089 +	to interpret it.  Some programs behave differently than others
  1.1090 +	when dealing with these paths. This isn't an ideal situation,
  1.1091 +	but it's unlikely to change.  Please read the following
  1.1092 +	paragraphs carefully.</para>
  1.1093 +
  1.1094 +      <para id="x_490">Mercurial treats the path to a repository on the server as
  1.1095 +	relative to the remote user's home directory.  For example, if
  1.1096 +	user <literal>foo</literal> on the server has a home directory
  1.1097 +	of <filename class="directory">/home/foo</filename>, then an
  1.1098 +	ssh URL that contains a path component of <filename
  1.1099 +	  class="directory">bar</filename> <emphasis>really</emphasis>
  1.1100 +	refers to the directory <filename
  1.1101 +	  class="directory">/home/foo/bar</filename>.</para>
  1.1102 +
  1.1103 +      <para id="x_491">If you want to specify a path relative to another user's
  1.1104 +	home directory, you can use a path that starts with a tilde
  1.1105 +	character followed by the user's name (let's call them
  1.1106 +	<literal>otheruser</literal>), like this.</para>
  1.1107 +      <programlisting>ssh://server/~otheruser/hg/repo</programlisting>
  1.1108 +
  1.1109 +      <para id="x_492">And if you really want to specify an
  1.1110 +	<emphasis>absolute</emphasis> path on the server, begin the
  1.1111 +	path component with two slashes, as in this example.</para>
  1.1112 +      <programlisting>ssh://server//absolute/path</programlisting>
  1.1113 +    </sect2>
  1.1114 +
  1.1115 +    <sect2>
  1.1116 +      <title>Finding an ssh client for your system</title>
  1.1117 +
  1.1118 +      <para id="x_493">Almost every Unix-like system comes with OpenSSH
  1.1119 +	preinstalled.  If you're using such a system, run
  1.1120 +	<literal>which ssh</literal> to find out if the
  1.1121 +	<command>ssh</command> command is installed (it's usually in
  1.1122 +	<filename class="directory">/usr/bin</filename>).  In the
  1.1123 +	unlikely event that it isn't present, take a look at your
  1.1124 +	system documentation to figure out how to install it.</para>
  1.1125 +
  1.1126 +      <para id="x_494">On Windows, the TortoiseHg package is bundled
  1.1127 +	with a version of Simon Tatham's excellent
  1.1128 +	<command>plink</command> command, and you should not need to
  1.1129 +	do any further configuration.</para>
  1.1130 +    </sect2>
  1.1131 +
  1.1132 +    <sect2>
  1.1133 +      <title>Generating a key pair</title>
  1.1134 +
  1.1135 +      <para id="x_499">To avoid the need to repetitively type a
  1.1136 +	password every time you need to use your ssh client, I
  1.1137 +	recommend generating a key pair.</para>
  1.1138 +
  1.1139 +      <tip>
  1.1140 +	<title>Key pairs are not mandatory</title>
  1.1141 +
  1.1142 +	<para id="x_6a4">Mercurial knows nothing about ssh authentication or key
  1.1143 +	  pairs.  You can, if you like, safely ignore this section and
  1.1144 +	  the one that follows until you grow tired of repeatedly
  1.1145 +	  typing ssh passwords.</para>
  1.1146 +      </tip>
  1.1147 +
  1.1148 +      <itemizedlist>
  1.1149 +	<listitem>
  1.1150 +	  <para id="x_6a5">On a Unix-like system, the
  1.1151 +	    <command>ssh-keygen</command> command will do the
  1.1152 +	    trick.</para>
  1.1153 +	  <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need
  1.1154 +	    to download a command named <command>puttygen</command>
  1.1155 +	    from <ulink
  1.1156 +	      url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the 
  1.1157 +	      PuTTY web site</ulink> to generate a key pair.  See
  1.1158 +	    <ulink
  1.1159 +	      url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the 
  1.1160 +	      <command>puttygen</command> documentation</ulink> for
  1.1161 +	    details of how use the command.</para>
  1.1162 +	</listitem>
  1.1163 +      </itemizedlist>
  1.1164 +
  1.1165 +      <para id="x_49a">When you generate a key pair, it's usually
  1.1166 +	<emphasis>highly</emphasis> advisable to protect it with a
  1.1167 +	passphrase.  (The only time that you might not want to do this
  1.1168 +	is when you're using the ssh protocol for automated tasks on a
  1.1169 +	secure network.)</para>
  1.1170 +
  1.1171 +      <para id="x_49b">Simply generating a key pair isn't enough, however.
  1.1172 +	You'll need to add the public key to the set of authorised
  1.1173 +	keys for whatever user you're logging in remotely as.  For
  1.1174 +	servers using OpenSSH (the vast majority), this will mean
  1.1175 +	adding the public key to a list in a file called <filename
  1.1176 +	  role="special">authorized_keys</filename> in their <filename
  1.1177 +	  role="special" class="directory">.ssh</filename>
  1.1178 +	directory.</para>
  1.1179 +
  1.1180 +      <para id="x_49c">On a Unix-like system, your public key will have a
  1.1181 +	<filename>.pub</filename> extension.  If you're using
  1.1182 +	<command>puttygen</command> on Windows, you can save the
  1.1183 +	public key to a file of your choosing, or paste it from the
  1.1184 +	window it's displayed in straight into the <filename
  1.1185 +	  role="special">authorized_keys</filename> file.</para>
  1.1186 +    </sect2>
  1.1187 +    <sect2>
  1.1188 +      <title>Using an authentication agent</title>
  1.1189 +
  1.1190 +      <para id="x_49d">An authentication agent is a daemon that stores
  1.1191 +	passphrases in memory (so it will forget passphrases if you
  1.1192 +	log out and log back in again). An ssh client will notice if
  1.1193 +	it's running, and query it for a passphrase.  If there's no
  1.1194 +	authentication agent running, or the agent doesn't store the
  1.1195 +	necessary passphrase, you'll have to type your passphrase
  1.1196 +	every time Mercurial tries to communicate with a server on
  1.1197 +	your behalf (e.g. whenever you pull or push changes).</para>
  1.1198 +
  1.1199 +      <para id="x_49e">The downside of storing passphrases in an agent is that
  1.1200 +	it's possible for a well-prepared attacker to recover the
  1.1201 +	plain text of your passphrases, in some cases even if your
  1.1202 +	system has been power-cycled. You should make your own
  1.1203 +	judgment as to whether this is an acceptable risk.  It
  1.1204 +	certainly saves a lot of repeated typing.</para>
  1.1205 +
  1.1206 +      <itemizedlist>
  1.1207 +	<listitem>
  1.1208 +	  <para id="x_49f">On Unix-like systems, the agent is called
  1.1209 +	    <command>ssh-agent</command>, and it's often run
  1.1210 +	    automatically for you when you log in.  You'll need to use
  1.1211 +	    the <command>ssh-add</command> command to add passphrases
  1.1212 +	    to the agent's store.</para>
  1.1213 +	</listitem>
  1.1214 +	<listitem>
  1.1215 +	  <para id="x_6a7">On Windows, if you're using TortoiseHg, the
  1.1216 +	    <command>pageant</command> command acts as the agent.  As
  1.1217 +	    with <command>puttygen</command>, you'll need to <ulink
  1.1218 +	      url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download 
  1.1219 +	      <command>pageant</command></ulink> from the PuTTY web
  1.1220 +	    site and read <ulink
  1.1221 +	      url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its 
  1.1222 +	      documentation</ulink>.  The <command>pageant</command>
  1.1223 +	    command adds an icon to your system tray that will let you
  1.1224 +	    manage stored passphrases.</para>
  1.1225 +	</listitem>
  1.1226 +      </itemizedlist>
  1.1227 +    </sect2>
  1.1228 +
  1.1229 +    <sect2>
  1.1230 +      <title>Configuring the server side properly</title>
  1.1231 +
  1.1232 +      <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
  1.1233 +	a variety of things can go wrong.  Add Mercurial
  1.1234 +	on top, and there's plenty more scope for head-scratching.
  1.1235 +	Most of these potential problems occur on the server side, not
  1.1236 +	the client side.  The good news is that once you've gotten a
  1.1237 +	configuration working, it will usually continue to work
  1.1238 +	indefinitely.</para>
  1.1239 +
  1.1240 +      <para id="x_4a1">Before you try using Mercurial to talk to an ssh server,
  1.1241 +	it's best to make sure that you can use the normal
  1.1242 +	<command>ssh</command> or <command>putty</command> command to
  1.1243 +	talk to the server first.  If you run into problems with using
  1.1244 +	these commands directly, Mercurial surely won't work.  Worse,
  1.1245 +	it will obscure the underlying problem.  Any time you want to
  1.1246 +	debug ssh-related Mercurial problems, you should drop back to
  1.1247 +	making sure that plain ssh client commands work first,
  1.1248 +	<emphasis>before</emphasis> you worry about whether there's a
  1.1249 +	problem with Mercurial.</para>
  1.1250 +
  1.1251 +      <para id="x_4a2">The first thing to be sure of on the server side is that
  1.1252 +	you can actually log in from another machine at all.  If you
  1.1253 +	can't use <command>ssh</command> or <command>putty</command>
  1.1254 +	to log in, the error message you get may give you a few hints
  1.1255 +	as to what's wrong.  The most common problems are as
  1.1256 +	follows.</para>
  1.1257 +      <itemizedlist>
  1.1258 +	<listitem><para id="x_4a3">If you get a <quote>connection refused</quote>
  1.1259 +	    error, either there isn't an SSH daemon running on the
  1.1260 +	    server at all, or it's inaccessible due to firewall
  1.1261 +	    configuration.</para>
  1.1262 +	</listitem>
  1.1263 +	<listitem><para id="x_4a4">If you get a <quote>no route to host</quote>
  1.1264 +	    error, you either have an incorrect address for the server
  1.1265 +	    or a seriously locked down firewall that won't admit its
  1.1266 +	    existence at all.</para>
  1.1267 +	</listitem>
  1.1268 +	<listitem><para id="x_4a5">If you get a <quote>permission denied</quote>
  1.1269 +	    error, you may have mistyped the username on the server,
  1.1270 +	    or you could have mistyped your key's passphrase or the
  1.1271 +	    remote user's password.</para>
  1.1272 +	</listitem></itemizedlist>
  1.1273 +      <para id="x_4a6">In summary, if you're having trouble talking to the
  1.1274 +	server's ssh daemon, first make sure that one is running at
  1.1275 +	all.  On many systems it will be installed, but disabled, by
  1.1276 +	default.  Once you're done with this step, you should then
  1.1277 +	check that the server's firewall is configured to allow
  1.1278 +	incoming connections on the port the ssh daemon is listening
  1.1279 +	on (usually 22).  Don't worry about more exotic possibilities
  1.1280 +	for misconfiguration until you've checked these two
  1.1281 +	first.</para>
  1.1282 +
  1.1283 +      <para id="x_4a7">If you're using an authentication agent on the client side
  1.1284 +	to store passphrases for your keys, you ought to be able to
  1.1285 +	log into the server without being prompted for a passphrase or
  1.1286 +	a password.  If you're prompted for a passphrase, there are a
  1.1287 +	few possible culprits.</para>
  1.1288 +      <itemizedlist>
  1.1289 +	<listitem><para id="x_4a8">You might have forgotten to use
  1.1290 +	    <command>ssh-add</command> or <command>pageant</command>
  1.1291 +	    to store the passphrase.</para>
  1.1292 +	</listitem>
  1.1293 +	<listitem><para id="x_4a9">You might have stored the passphrase for the
  1.1294 +	    wrong key.</para>
  1.1295 +	</listitem></itemizedlist>
  1.1296 +      <para id="x_4aa">If you're being prompted for the remote user's password,
  1.1297 +	there are another few possible problems to check.</para>
  1.1298 +      <itemizedlist>
  1.1299 +	<listitem><para id="x_4ab">Either the user's home directory or their
  1.1300 +	    <filename role="special" class="directory">.ssh</filename>
  1.1301 +	    directory might have excessively liberal permissions.  As
  1.1302 +	    a result, the ssh daemon will not trust or read their
  1.1303 +	    <filename role="special">authorized_keys</filename> file.
  1.1304 +	    For example, a group-writable home or <filename
  1.1305 +	      role="special" class="directory">.ssh</filename>
  1.1306 +	    directory will often cause this symptom.</para>
  1.1307 +	</listitem>
  1.1308 +	<listitem><para id="x_4ac">The user's <filename
  1.1309 +	      role="special">authorized_keys</filename> file may have
  1.1310 +	    a problem. If anyone other than the user owns or can write
  1.1311 +	    to that file, the ssh daemon will not trust or read
  1.1312 +	    it.</para>
  1.1313 +	</listitem></itemizedlist>
  1.1314 +
  1.1315 +      <para id="x_4ad">In the ideal world, you should be able to run the
  1.1316 +	following command successfully, and it should print exactly
  1.1317 +	one line of output, the current date and time.</para>
  1.1318 +      <programlisting>ssh myserver date</programlisting>
  1.1319 +
  1.1320 +      <para id="x_4ae">If, on your server, you have login scripts that print
  1.1321 +	banners or other junk even when running non-interactive
  1.1322 +	commands like this, you should fix them before you continue,
  1.1323 +	so that they only print output if they're run interactively.
  1.1324 +	Otherwise these banners will at least clutter up Mercurial's
  1.1325 +	output.  Worse, they could potentially cause problems with
  1.1326 +	running Mercurial commands remotely.  Mercurial tries to
  1.1327 +	detect and ignore banners in non-interactive
  1.1328 +	<command>ssh</command> sessions, but it is not foolproof.  (If
  1.1329 +	you're editing your login scripts on your server, the usual
  1.1330 +	way to see if a login script is running in an interactive
  1.1331 +	shell is to check the return code from the command
  1.1332 +	<literal>tty -s</literal>.)</para>
  1.1333 +
  1.1334 +      <para id="x_4af">Once you've verified that plain old ssh is working with
  1.1335 +	your server, the next step is to ensure that Mercurial runs on
  1.1336 +	the server.  The following command should run
  1.1337 +	successfully:</para>
  1.1338 +
  1.1339 +      <programlisting>ssh myserver hg version</programlisting>
  1.1340 +
  1.1341 +      <para id="x_4b0">If you see an error message instead of normal <command
  1.1342 +	  role="hg-cmd">hg version</command> output, this is usually
  1.1343 +	because you haven't installed Mercurial to <filename
  1.1344 +	  class="directory">/usr/bin</filename>.  Don't worry if this
  1.1345 +	is the case; you don't need to do that.  But you should check
  1.1346 +	for a few possible problems.</para>
  1.1347 +      <itemizedlist>
  1.1348 +	<listitem><para id="x_4b1">Is Mercurial really installed on the server at
  1.1349 +	    all?  I know this sounds trivial, but it's worth
  1.1350 +	    checking!</para>
  1.1351 +	</listitem>
  1.1352 +	<listitem><para id="x_4b2">Maybe your shell's search path (usually set
  1.1353 +	    via the <envar>PATH</envar> environment variable) is
  1.1354 +	    simply misconfigured.</para>
  1.1355 +	</listitem>
  1.1356 +	<listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment
  1.1357 +	    variable is only being set to point to the location of the
  1.1358 +	    <command>hg</command> executable if the login session is
  1.1359 +	    interactive.  This can happen if you're setting the path
  1.1360 +	    in the wrong shell login script.  See your shell's
  1.1361 +	    documentation for details.</para>
  1.1362 +	</listitem>
  1.1363 +	<listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment
  1.1364 +	    variable may need to contain the path to the Mercurial
  1.1365 +	    Python modules.  It might not be set at all; it could be
  1.1366 +	    incorrect; or it may be set only if the login is
  1.1367 +	    interactive.</para>
  1.1368 +	</listitem></itemizedlist>
  1.1369 +
  1.1370 +      <para id="x_4b5">If you can run <command role="hg-cmd">hg version</command>
  1.1371 +	over an ssh connection, well done! You've got the server and
  1.1372 +	client sorted out.  You should now be able to use Mercurial to
  1.1373 +	access repositories hosted by that username on that server.
  1.1374 +	If you run into problems with Mercurial and ssh at this point,
  1.1375 +	try using the <option role="hg-opt-global">--debug</option>
  1.1376 +	option to get a clearer picture of what's going on.</para>
  1.1377 +    </sect2>
  1.1378 +    <sect2>
  1.1379 +      <title>Using compression with ssh</title>
  1.1380 +
  1.1381 +      <para id="x_4b6">Mercurial does not compress data when it uses the ssh
  1.1382 +	protocol, because the ssh protocol can transparently compress
  1.1383 +	data.  However, the default behavior of ssh clients is
  1.1384 +	<emphasis>not</emphasis> to request compression.</para>
  1.1385 +
  1.1386 +      <para id="x_4b7">Over any network other than a fast LAN (even a wireless
  1.1387 +	network), using compression is likely to significantly speed
  1.1388 +	up Mercurial's network operations.  For example, over a WAN,
  1.1389 +	someone measured compression as reducing the amount of time
  1.1390 +	required to clone a particularly large repository from 51
  1.1391 +	minutes to 17 minutes.</para>
  1.1392 +
  1.1393 +      <para id="x_4b8">Both <command>ssh</command> and <command>plink</command>
  1.1394 +	accept a <option role="cmd-opt-ssh">-C</option> option which
  1.1395 +	turns on compression.  You can easily edit your <filename
  1.1396 +	  role="special">~/.hgrc</filename> to enable compression for
  1.1397 +	all of Mercurial's uses of the ssh protocol.  Here is how to
  1.1398 +	do so for regular <command>ssh</command> on Unix-like systems,
  1.1399 +	for example.</para>
  1.1400 +      <programlisting>[ui]
  1.1401 +ssh = ssh -C</programlisting>
  1.1402 +
  1.1403 +      <para id="x_4b9">If you use <command>ssh</command> on a
  1.1404 +	Unix-like system, you can configure it to always use
  1.1405 +	compression when talking to your server.  To do this, edit
  1.1406 +	your <filename role="special">.ssh/config</filename> file
  1.1407 +	(which may not yet exist), as follows.</para>
  1.1408 +
  1.1409 +      <programlisting>Host hg
  1.1410 +  Compression yes
  1.1411 +  HostName hg.example.com</programlisting>
  1.1412 +
  1.1413 +      <para id="x_4ba">This defines a hostname alias,
  1.1414 +	<literal>hg</literal>.  When you use that hostname on the
  1.1415 +	<command>ssh</command> command line or in a Mercurial
  1.1416 +	<literal>ssh</literal>-protocol URL, it will cause
  1.1417 +	<command>ssh</command> to connect to
  1.1418 +	<literal>hg.example.com</literal> and use compression.  This
  1.1419 +	gives you both a shorter name to type and compression, each of
  1.1420 +	which is a good thing in its own right.</para>
  1.1421 +    </sect2>
  1.1422 +  </sect1>
  1.1423 +
  1.1424 +  <sect1 id="sec:collab:cgi">
  1.1425 +    <title>Serving over HTTP using CGI</title>
  1.1426 +
  1.1427 +    <para id="x_6a8">The simplest way to host one or more repositories in a
  1.1428 +      permanent way is to use a web server and Mercurial's CGI
  1.1429 +      support.</para>
  1.1430 +
  1.1431 +    <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
  1.1432 +      CGI interface can take anything from a few moments to several
  1.1433 +      hours.</para>
  1.1434 +
  1.1435 +    <para id="x_4bc">We'll begin with the simplest of examples, and work our way
  1.1436 +      towards a more complex configuration.  Even for the most basic
  1.1437 +      case, you're almost certainly going to need to read and modify
  1.1438 +      your web server's configuration.</para>
  1.1439 +
  1.1440 +    <note>
  1.1441 +      <title>High pain tolerance required</title>
  1.1442 +
  1.1443 +      <para id="x_4bd">Configuring a web server is a complex, fiddly,
  1.1444 +	and highly system-dependent activity.  I can't possibly give
  1.1445 +	you instructions that will cover anything like all of the
  1.1446 +	cases you will encounter. Please use your discretion and
  1.1447 +	judgment in following the sections below.  Be prepared to make
  1.1448 +	plenty of mistakes, and to spend a lot of time reading your
  1.1449 +	server's error logs.</para>
  1.1450 +
  1.1451 +      <para id="x_6a9">If you don't have a strong stomach for tweaking
  1.1452 +	configurations over and over, or a compelling need to host
  1.1453 +	your own services, you might want to try one of the public
  1.1454 +	hosting services that I mentioned earlier.</para>
  1.1455 +    </note>
  1.1456 +
  1.1457 +    <sect2>
  1.1458 +      <title>Web server configuration checklist</title>
  1.1459 +
  1.1460 +      <para id="x_4be">Before you continue, do take a few moments to check a few
  1.1461 +	aspects of your system's setup.</para>
  1.1462 +
  1.1463 +      <orderedlist>
  1.1464 +	<listitem><para id="x_4bf">Do you have a web server installed
  1.1465 +	    at all? Mac OS X and some Linux distributions ship with
  1.1466 +	    Apache, but many other systems may not have a web server
  1.1467 +	    installed.</para>
  1.1468 +	</listitem>
  1.1469 +	<listitem><para id="x_4c0">If you have a web server installed, is it
  1.1470 +	    actually running?  On most systems, even if one is
  1.1471 +	    present, it will be disabled by default.</para>
  1.1472 +	</listitem>
  1.1473 +	<listitem><para id="x_4c1">Is your server configured to allow you to run
  1.1474 +	    CGI programs in the directory where you plan to do so?
  1.1475 +	    Most servers default to explicitly disabling the ability
  1.1476 +	    to run CGI programs.</para>
  1.1477 +	</listitem></orderedlist>
  1.1478 +
  1.1479 +      <para id="x_4c2">If you don't have a web server installed, and don't have
  1.1480 +	substantial experience configuring Apache, you should consider
  1.1481 +	using the <literal>lighttpd</literal> web server instead of
  1.1482 +	Apache.  Apache has a well-deserved reputation for baroque and
  1.1483 +	confusing configuration. While <literal>lighttpd</literal> is
  1.1484 +	less capable in some ways than Apache, most of these
  1.1485 +	capabilities are not relevant to serving Mercurial
  1.1486 +	repositories.  And <literal>lighttpd</literal> is undeniably
  1.1487 +	<emphasis>much</emphasis> easier to get started with than
  1.1488 +	Apache.</para>
  1.1489 +    </sect2>
  1.1490 +
  1.1491 +    <sect2>
  1.1492 +      <title>Basic CGI configuration</title>
  1.1493 +
  1.1494 +      <para id="x_4c3">On Unix-like systems, it's common for users to have a
  1.1495 +	subdirectory named something like <filename
  1.1496 +	  class="directory">public_html</filename> in their home
  1.1497 +	directory, from which they can serve up web pages.  A file
  1.1498 +	named <filename>foo</filename> in this directory will be
  1.1499 +	accessible at a URL of the form
  1.1500 +	<literal>http://www.example.com/username/foo</literal>.</para>
  1.1501 +
  1.1502 +      <para id="x_4c4">To get started, find the <filename
  1.1503 +	  role="special">hgweb.cgi</filename> script that should be
  1.1504 +	present in your Mercurial installation.  If you can't quickly
  1.1505 +	find a local copy on your system, simply download one from the
  1.1506 +	master Mercurial repository at <ulink
  1.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>
  1.1508 +
  1.1509 +      <para id="x_4c5">You'll need to copy this script into your <filename
  1.1510 +	  class="directory">public_html</filename> directory, and
  1.1511 +	ensure that it's executable.</para>
  1.1512 +      <programlisting>cp .../hgweb.cgi ~/public_html
  1.1513 +chmod 755 ~/public_html/hgweb.cgi</programlisting>
  1.1514 +      <para id="x_4c6">The <literal>755</literal> argument to
  1.1515 +	<command>chmod</command> is a little more general than just
  1.1516 +	making the script executable: it ensures that the script is
  1.1517 +	executable by anyone, and that <quote>group</quote> and
  1.1518 +	<quote>other</quote> write permissions are
  1.1519 +	<emphasis>not</emphasis> set.  If you were to leave those
  1.1520 +	write permissions enabled, Apache's <literal>suexec</literal>
  1.1521 +	subsystem would likely refuse to execute the script.  In fact,
  1.1522 +	<literal>suexec</literal> also insists that the
  1.1523 +	<emphasis>directory</emphasis> in which the script resides
  1.1524 +	must not be writable by others.</para>
  1.1525 +      <programlisting>chmod 755 ~/public_html</programlisting>
  1.1526 +
  1.1527 +      <sect3 id="sec:collab:wtf">
  1.1528 +	<title>What could <emphasis>possibly</emphasis> go
  1.1529 +	  wrong?</title>
  1.1530 +
  1.1531 +	<para id="x_4c7">Once you've copied the CGI script into place,
  1.1532 +	  go into a web browser, and try to open the URL
  1.1533 +	  <literal>http://myhostname/~myuser/hgweb.cgi</literal>,
  1.1534 +	  <emphasis>but</emphasis> brace yourself for instant failure.
  1.1535 +	  There's a high probability that trying to visit this URL
  1.1536 +	  will fail, and there are many possible reasons for this.  In
  1.1537 +	  fact, you're likely to stumble over almost every one of the
  1.1538 +	  possible errors below, so please read carefully.  The
  1.1539 +	  following are all of the problems I ran into on a system
  1.1540 +	  running Fedora 7, with a fresh installation of Apache, and a
  1.1541 +	  user account that I created specially to perform this
  1.1542 +	  exercise.</para>
  1.1543 +
  1.1544 +	<para id="x_4c8">Your web server may have per-user directories disabled.
  1.1545 +	  If you're using Apache, search your config file for a
  1.1546 +	  <literal>UserDir</literal> directive.  If there's none
  1.1547 +	  present, per-user directories will be disabled.  If one
  1.1548 +	  exists, but its value is <literal>disabled</literal>, then
  1.1549 +	  per-user directories will be disabled.  Otherwise, the
  1.1550 +	  string after <literal>UserDir</literal> gives the name of
  1.1551 +	  the subdirectory that Apache will look in under your home
  1.1552 +	  directory, for example <filename
  1.1553 +	    class="directory">public_html</filename>.</para>
  1.1554 +
  1.1555 +	<para id="x_4c9">Your file access permissions may be too restrictive.
  1.1556 +	  The web server must be able to traverse your home directory
  1.1557 +	  and directories under your <filename
  1.1558 +	    class="directory">public_html</filename> directory, and
  1.1559 +	  read files under the latter too.  Here's a quick recipe to
  1.1560 +	  help you to make your permissions more appropriate.</para>
  1.1561 +	<programlisting>chmod 755 ~
  1.1562 +find ~/public_html -type d -print0 | xargs -0r chmod 755
  1.1563 +find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting>
  1.1564 +
  1.1565 +	<para id="x_4ca">The other possibility with permissions is that you might
  1.1566 +	  get a completely empty window when you try to load the
  1.1567 +	  script.  In this case, it's likely that your access
  1.1568 +	  permissions are <emphasis>too permissive</emphasis>.  Apache's
  1.1569 +	  <literal>suexec</literal> subsystem won't execute a script
  1.1570 +	  that's group- or world-writable, for example.</para>
  1.1571 +
  1.1572 +	<para id="x_4cb">Your web server may be configured to disallow execution
  1.1573 +	  of CGI programs in your per-user web directory.  Here's
  1.1574 +	  Apache's default per-user configuration from my Fedora
  1.1575 +	  system.</para>
  1.1576 +
  1.1577 +	&ch06-apache-config.lst;
  1.1578 +
  1.1579 +	<para id="x_4cc">If you find a similar-looking
  1.1580 +	  <literal>Directory</literal> group in your Apache
  1.1581 +	  configuration, the directive to look at inside it is
  1.1582 +	  <literal>Options</literal>. Add <literal>ExecCGI</literal>
  1.1583 +	  to the end of this list if it's missing, and restart the web
  1.1584 +	  server.</para>
  1.1585 +
  1.1586 +	<para id="x_4cd">If you find that Apache serves you the text of the CGI
  1.1587 +	  script instead of executing it, you may need to either
  1.1588 +	  uncomment (if already present) or add a directive like
  1.1589 +	  this.</para>
  1.1590 +	<programlisting>AddHandler cgi-script .cgi</programlisting>
  1.1591 +
  1.1592 +	<para id="x_4ce">The next possibility is that you might be served with a
  1.1593 +	  colourful Python backtrace claiming that it can't import a
  1.1594 +	  <literal>mercurial</literal>-related module.  This is
  1.1595 +	  actually progress!  The server is now capable of executing
  1.1596 +	  your CGI script.  This error is only likely to occur if
  1.1597 +	  you're running a private installation of Mercurial, instead
  1.1598 +	  of a system-wide version.  Remember that the web server runs
  1.1599 +	  the CGI program without any of the environment variables
  1.1600 +	  that you take for granted in an interactive session.  If
  1.1601 +	  this error happens to you, edit your copy of <filename
  1.1602 +	    role="special">hgweb.cgi</filename> and follow the
  1.1603 +	  directions inside it to correctly set your
  1.1604 +	  <envar>PYTHONPATH</envar> environment variable.</para>
  1.1605 +
  1.1606 +	<para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be
  1.1607 +	  served with another colourful Python backtrace: this one
  1.1608 +	  will complain that it can't find <filename
  1.1609 +	    class="directory">/path/to/repository</filename>.  Edit
  1.1610 +	  your <filename role="special">hgweb.cgi</filename> script
  1.1611 +	  and replace the <filename
  1.1612 +	    class="directory">/path/to/repository</filename> string
  1.1613 +	  with the complete path to the repository you want to serve
  1.1614 +	  up.</para>
  1.1615 +
  1.1616 +	<para id="x_4d0">At this point, when you try to reload the page, you
  1.1617 +	  should be presented with a nice HTML view of your
  1.1618 +	  repository's history.  Whew!</para>
  1.1619 +      </sect3>
  1.1620 +
  1.1621 +      <sect3>
  1.1622 +	<title>Configuring lighttpd</title>
  1.1623 +
  1.1624 +	<para id="x_4d1">To be exhaustive in my experiments, I tried configuring
  1.1625 +	  the increasingly popular <literal>lighttpd</literal> web
  1.1626 +	  server to serve the same repository as I described with
  1.1627 +	  Apache above.  I had already overcome all of the problems I
  1.1628 +	  outlined with Apache, many of which are not server-specific.
  1.1629 +	  As a result, I was fairly sure that my file and directory
  1.1630 +	  permissions were good, and that my <filename
  1.1631 +	    role="special">hgweb.cgi</filename> script was properly
  1.1632 +	  edited.</para>
  1.1633 +
  1.1634 +	<para id="x_4d2">Once I had Apache running, getting
  1.1635 +	  <literal>lighttpd</literal> to serve the repository was a
  1.1636 +	  snap (in other words, even if you're trying to use
  1.1637 +	  <literal>lighttpd</literal>, you should read the Apache
  1.1638 +	  section).  I first had to edit the
  1.1639 +	  <literal>mod_access</literal> section of its config file to
  1.1640 +	  enable <literal>mod_cgi</literal> and
  1.1641 +	  <literal>mod_userdir</literal>, both of which were disabled
  1.1642 +	  by default on my system.  I then added a few lines to the
  1.1643 +	  end of the config file, to configure these modules.</para>
  1.1644 +	<programlisting>userdir.path = "public_html"
  1.1645 +cgi.assign = (".cgi" =&gt; "" )</programlisting>
  1.1646 +	<para id="x_4d3">With this done, <literal>lighttpd</literal> ran
  1.1647 +	  immediately for me.  If I had configured
  1.1648 +	  <literal>lighttpd</literal> before Apache, I'd almost
  1.1649 +	  certainly have run into many of the same system-level
  1.1650 +	  configuration problems as I did with Apache.  However, I
  1.1651 +	  found <literal>lighttpd</literal> to be noticeably easier to
  1.1652 +	  configure than Apache, even though I've used Apache for over
  1.1653 +	  a decade, and this was my first exposure to
  1.1654 +	  <literal>lighttpd</literal>.</para>
  1.1655 +      </sect3>
  1.1656 +    </sect2>
  1.1657 +
  1.1658 +    <sect2>
  1.1659 +      <title>Sharing multiple repositories with one CGI script</title>
  1.1660 +
  1.1661 +      <para id="x_4d4">The <filename role="special">hgweb.cgi</filename> script
  1.1662 +	only lets you publish a single repository, which is an
  1.1663 +	annoying restriction.  If you want to publish more than one
  1.1664 +	without wracking yourself with multiple copies of the same
  1.1665 +	script, each with different names, a better choice is to use
  1.1666 +	the <filename role="special">hgwebdir.cgi</filename>
  1.1667 +	script.</para>
  1.1668 +
  1.1669 +      <para id="x_4d5">The procedure to configure <filename
  1.1670 +	  role="special">hgwebdir.cgi</filename> is only a little more
  1.1671 +	involved than for <filename
  1.1672 +	  role="special">hgweb.cgi</filename>.  First, you must obtain
  1.1673 +	a copy of the script.  If you don't have one handy, you can
  1.1674 +	download a copy from the master Mercurial repository at <ulink
  1.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>
  1.1676 +
  1.1677 +      <para id="x_4d6">You'll need to copy this script into your <filename
  1.1678 +	  class="directory">public_html</filename> directory, and
  1.1679 +	ensure that it's executable.</para>
  1.1680 +
  1.1681 +      <programlisting>cp .../hgwebdir.cgi ~/public_html
  1.1682 +chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
  1.1683 +
  1.1684 +      <para id="x_4d7">With basic configuration out of the way, try to
  1.1685 +	visit <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>
  1.1686 +	in your	browser.  It should
  1.1687 +	display an empty list of repositories.  If you get a blank
  1.1688 +	window or error message, try walking through the list of
  1.1689 +	potential problems in <xref
  1.1690 +	  linkend="sec:collab:wtf"/>.</para>
  1.1691 +
  1.1692 +      <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename>
  1.1693 +	script relies on an external configuration file.  By default,
  1.1694 +	it searches for a file named <filename
  1.1695 +	  role="special">hgweb.config</filename> in the same directory
  1.1696 +	as itself.  You'll need to create this file, and make it
  1.1697 +	world-readable.  The format of the file is similar to a
  1.1698 +	Windows <quote>ini</quote> file, as understood by Python's
  1.1699 +	<literal>ConfigParser</literal>
  1.1700 +	<citation>web:configparser</citation> module.</para>
  1.1701 +
  1.1702 +      <para id="x_4d9">The easiest way to configure <filename
  1.1703 +	  role="special">hgwebdir.cgi</filename> is with a section
  1.1704 +	named <literal>collections</literal>.  This will automatically
  1.1705 +	publish <emphasis>every</emphasis> repository under the
  1.1706 +	directories you name.  The section should look like
  1.1707 +	this:</para>
  1.1708 +      <programlisting>[collections]
  1.1709 +/my/root = /my/root</programlisting>
  1.1710 +      <para id="x_4da">Mercurial interprets this by looking at the directory name
  1.1711 +	on the <emphasis>right</emphasis> hand side of the
  1.1712 +	<quote><literal>=</literal></quote> sign; finding repositories
  1.1713 +	in that directory hierarchy; and using the text on the
  1.1714 +	<emphasis>left</emphasis> to strip off matching text from the
  1.1715 +	names it will actually list in the web interface.  The
  1.1716 +	remaining component of a path after this stripping has
  1.1717 +	occurred is called a <quote>virtual path</quote>.</para>
  1.1718 +
  1.1719 +      <para id="x_4db">Given the example above, if we have a
  1.1720 +	repository whose local path is <filename
  1.1721 +	  class="directory">/my/root/this/repo</filename>, the CGI
  1.1722 +	script will strip the leading <filename
  1.1723 +	  class="directory">/my/root</filename> from the name, and
  1.1724 +	publish the repository with a virtual path of <filename
  1.1725 +	  class="directory">this/repo</filename>.  If the base URL for
  1.1726 +	our CGI script is
  1.1727 +	<literal>http://myhostname/~myuser/hgwebdir.cgi</literal>, the
  1.1728 +	complete URL for that repository will be
  1.1729 +	<literal>http://myhostname/~myuser/hgwebdir.cgi/this/repo</literal>.</para>
  1.1730 +
  1.1731 +      <para id="x_4dc">If we replace <filename
  1.1732 +	  class="directory">/my/root</filename> on the left hand side
  1.1733 +	of this example with <filename
  1.1734 +	  class="directory">/my</filename>, then <filename
  1.1735 +	  role="special">hgwebdir.cgi</filename> will only strip off
  1.1736 +	<filename class="directory">/my</filename> from the repository
  1.1737 +	name, and will give us a virtual path of <filename
  1.1738 +	  class="directory">root/this/repo</filename> instead of
  1.1739 +	<filename class="directory">this/repo</filename>.</para>
  1.1740 +
  1.1741 +      <para id="x_4dd">The <filename role="special">hgwebdir.cgi</filename>
  1.1742 +	script will recursively search each directory listed in the
  1.1743 +	<literal>collections</literal> section of its configuration
  1.1744 +	file, but it will <literal>not</literal> recurse into the
  1.1745 +	repositories it finds.</para>
  1.1746 +
  1.1747 +      <para id="x_4de">The <literal>collections</literal> mechanism makes it easy
  1.1748 +	to publish many repositories in a <quote>fire and
  1.1749 +	  forget</quote> manner.  You only need to set up the CGI
  1.1750 +	script and configuration file one time.  Afterwards, you can
  1.1751 +	publish or unpublish a repository at any time by simply moving
  1.1752 +	it into, or out of, the directory hierarchy in which you've
  1.1753 +	configured <filename role="special">hgwebdir.cgi</filename> to
  1.1754 +	look.</para>
  1.1755 +
  1.1756 +      <sect3>
  1.1757 +	<title>Explicitly specifying which repositories to
  1.1758 +	  publish</title>
  1.1759 +
  1.1760 +	<para id="x_4df">In addition to the <literal>collections</literal>
  1.1761 +	  mechanism, the <filename
  1.1762 +	    role="special">hgwebdir.cgi</filename> script allows you
  1.1763 +	  to publish a specific list of repositories.  To do so,
  1.1764 +	  create a <literal>paths</literal> section, with contents of
  1.1765 +	  the following form.</para>
  1.1766 +	<programlisting>[paths]
  1.1767 +repo1 = /my/path/to/some/repo
  1.1768 +repo2 = /some/path/to/another</programlisting>
  1.1769 +	<para id="x_4e0">In this case, the virtual path (the component that will
  1.1770 +	  appear in a URL) is on the left hand side of each
  1.1771 +	  definition, while the path to the repository is on the
  1.1772 +	  right.  Notice that there does not need to be any
  1.1773 +	  relationship between the virtual path you choose and the
  1.1774 +	  location of a repository in your filesystem.</para>
  1.1775 +
  1.1776 +	<para id="x_4e1">If you wish, you can use both the
  1.1777 +	  <literal>collections</literal> and <literal>paths</literal>
  1.1778 +	  mechanisms simultaneously in a single configuration
  1.1779 +	  file.</para>
  1.1780 +
  1.1781 +	<note>
  1.1782 +	  <title>Beware duplicate virtual paths</title>
  1.1783 +
  1.1784 +	  <para id="x_4e2">  If several repositories have the same
  1.1785 +	    virtual path, <filename
  1.1786 +	      role="special">hgwebdir.cgi</filename> will not report
  1.1787 +	    an error.  Instead, it will behave unpredictably.</para>
  1.1788 +	</note>
  1.1789 +      </sect3>
  1.1790 +    </sect2>
  1.1791 +
  1.1792 +    <sect2>
  1.1793 +      <title>Downloading source archives</title>
  1.1794 +
  1.1795 +      <para id="x_4e3">Mercurial's web interface lets users download an archive
  1.1796 +	of any revision.  This archive will contain a snapshot of the
  1.1797 +	working directory as of that revision, but it will not contain
  1.1798 +	a copy of the repository data.</para>
  1.1799 +
  1.1800 +      <para id="x_4e4">By default, this feature is not enabled.  To enable it,
  1.1801 +	you'll need to add an <envar
  1.1802 +	  role="rc-item-web">allow_archive</envar> item to the
  1.1803 +	<literal role="rc-web">web</literal> section of your <filename
  1.1804 +	  role="special">~/.hgrc</filename>; see below for details.</para>
  1.1805 +    </sect2>
  1.1806 +    <sect2>
  1.1807 +      <title>Web configuration options</title>
  1.1808 +
  1.1809 +      <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd">hg
  1.1810 +	  serve</command> command, and the <filename
  1.1811 +	  role="special">hgweb.cgi</filename> and <filename
  1.1812 +	  role="special">hgwebdir.cgi</filename> scripts) have a
  1.1813 +	number of configuration options that you can set.  These
  1.1814 +	belong in a section named <literal
  1.1815 +	  role="rc-web">web</literal>.</para>
  1.1816 +      <itemizedlist>
  1.1817 +	<listitem><para id="x_4e6"><envar
  1.1818 +	      role="rc-item-web">allow_archive</envar>: Determines
  1.1819 +	    which (if any) archive download mechanisms Mercurial
  1.1820 +	    supports.  If you enable this feature, users of the web
  1.1821 +	    interface will be able to download an archive of whatever
  1.1822 +	    revision of a repository they are viewing. To enable the
  1.1823 +	    archive feature, this item must take the form of a
  1.1824 +	    sequence of words drawn from the list below.</para>
  1.1825 +	  <itemizedlist>
  1.1826 +	    <listitem><para id="x_4e7"><literal>bz2</literal>: A
  1.1827 +		<command>tar</command> archive, compressed using
  1.1828 +		<literal>bzip2</literal> compression.  This has the
  1.1829 +		best compression ratio, but uses the most CPU time on
  1.1830 +		the server.</para>
  1.1831 +	    </listitem>
  1.1832 +	    <listitem><para id="x_4e8"><literal>gz</literal>: A
  1.1833 +		<command>tar</command> archive, compressed using
  1.1834 +		<literal>gzip</literal> compression.</para>
  1.1835 +	    </listitem>
  1.1836 +	    <listitem><para id="x_4e9"><literal>zip</literal>: A
  1.1837 +		<command>zip</command> archive, compressed using LZW
  1.1838 +		compression.  This format has the worst compression
  1.1839 +		ratio, but is widely used in the Windows world.</para>
  1.1840 +	    </listitem>
  1.1841 +	  </itemizedlist>
  1.1842 +	  <para id="x_4ea">  If you provide an empty list, or don't have an
  1.1843 +	    <envar role="rc-item-web">allow_archive</envar> entry at
  1.1844 +	    all, this feature will be disabled.  Here is an example of
  1.1845 +	    how to enable all three supported formats.</para>
  1.1846 +	  <programlisting>[web]
  1.1847 +allow_archive = bz2 gz zip</programlisting>
  1.1848 +	</listitem>
  1.1849 +	<listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>:
  1.1850 +	    Boolean.  Determines whether the web interface allows
  1.1851 +	    remote users to <command role="hg-cmd">hg pull</command>
  1.1852 +	    and <command role="hg-cmd">hg clone</command> this
  1.1853 +	    repository over HTTP.  If set to <literal>no</literal> or
  1.1854 +	    <literal>false</literal>, only the
  1.1855 +	    <quote>human-oriented</quote> portion of the web interface
  1.1856 +	    is available.</para>
  1.1857 +	</listitem>
  1.1858 +	<listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>:
  1.1859 +	    String.  A free-form (but preferably brief) string
  1.1860 +	    identifying the person or group in charge of the
  1.1861 +	    repository.  This often contains the name and email
  1.1862 +	    address of a person or mailing list.  It often makes sense
  1.1863 +	    to place this entry in a repository's own <filename
  1.1864 +	      role="special">.hg/hgrc</filename> file, but it can make
  1.1865 +	    sense to use in a global <filename
  1.1866 +	      role="special">~/.hgrc</filename> if every repository
  1.1867 +	    has a single maintainer.</para>
  1.1868 +	</listitem>
  1.1869 +	<listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>:
  1.1870 +	    Integer.  The default maximum number of changesets to
  1.1871 +	    display in a single page of output.</para>
  1.1872 +	</listitem>
  1.1873 +	<listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>:
  1.1874 +	    Integer.  The default maximum number of modified files to
  1.1875 +	    display in a single page of output.</para>
  1.1876 +	</listitem>
  1.1877 +	<listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>:
  1.1878 +	    Integer.  If the web interface displays alternating
  1.1879 +	    <quote>stripes</quote> to make it easier to visually align
  1.1880 +	    rows when you are looking at a table, this number controls
  1.1881 +	    the number of rows in each stripe.</para>
  1.1882 +	</listitem>
  1.1883 +	<listitem><para id="x_4f0"><envar
  1.1884 +	      role="rc-item-web">style</envar>: Controls the template
  1.1885 +	    Mercurial uses to display the web interface.  Mercurial
  1.1886 +	    ships with several web templates.</para>
  1.1887 +	  <itemizedlist>
  1.1888 +	    <listitem>
  1.1889 +	      <para id="x_6aa"><literal>coal</literal> is monochromatic.</para>
  1.1890 +	    </listitem>
  1.1891 +	    <listitem>
  1.1892 +	      <para id="x_6ab"><literal>gitweb</literal> emulates the visual
  1.1893 +		style of git's web interface.</para>
  1.1894 +	    </listitem>
  1.1895 +	    <listitem>
  1.1896 +	      <para id="x_6ac"><literal>monoblue</literal> uses solid blues and
  1.1897 +		greys.</para>
  1.1898 +	    </listitem>
  1.1899 +	    <listitem>
  1.1900 +	      <para id="x_6ad"><literal>paper</literal> is the default.</para>
  1.1901 +	    </listitem>
  1.1902 +	    <listitem>
  1.1903 +	      <para id="x_6ae"><literal>spartan</literal> was the default for a
  1.1904 +		long time.</para>
  1.1905 +	    </listitem>
  1.1906 +	  </itemizedlist>
  1.1907 +	  <para id="x_6af">You can
  1.1908 +	    also specify a custom template of your own; see 
  1.1909 +	    <xref linkend="chap:template"/> for details. Here, you can
  1.1910 +	    see how to enable the <literal>gitweb</literal>
  1.1911 +	    style.</para>
  1.1912 +	  <programlisting>[web]
  1.1913 +style = gitweb</programlisting>
  1.1914 +	</listitem>
  1.1915 +	<listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>:
  1.1916 +	    Path.  The directory in which to search for template
  1.1917 +	    files.  By default, Mercurial searches in the directory in
  1.1918 +	    which it was installed.</para>
  1.1919 +	</listitem></itemizedlist>
  1.1920 +      <para id="x_4f2">If you are using <filename
  1.1921 +	  role="special">hgwebdir.cgi</filename>, you can place a few
  1.1922 +	configuration items in a <literal role="rc-web">web</literal>
  1.1923 +	section of the <filename
  1.1924 +	  role="special">hgweb.config</filename> file instead of a
  1.1925 +	<filename role="special">~/.hgrc</filename> file, for
  1.1926 +	convenience.  These items are <envar
  1.1927 +	  role="rc-item-web">motd</envar> and <envar
  1.1928 +	  role="rc-item-web">style</envar>.</para>
  1.1929 +
  1.1930 +      <sect3>
  1.1931 +	<title>Options specific to an individual repository</title>
  1.1932 +
  1.1933 +	<para id="x_4f3">A few <literal role="rc-web">web</literal> configuration
  1.1934 +	  items ought to be placed in a repository's local <filename
  1.1935 +	    role="special">.hg/hgrc</filename>, rather than a user's
  1.1936 +	  or global <filename role="special">~/.hgrc</filename>.</para>
  1.1937 +	<itemizedlist>
  1.1938 +	  <listitem><para id="x_4f4"><envar
  1.1939 +		role="rc-item-web">description</envar>: String.  A
  1.1940 +	      free-form (but preferably brief) string that describes
  1.1941 +	      the contents or purpose of the repository.</para>
  1.1942 +	  </listitem>
  1.1943 +	  <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>:
  1.1944 +	      String.  The name to use for the repository in the web
  1.1945 +	      interface.  This overrides the default name, which is
  1.1946 +	      the last component of the repository's path.</para>
  1.1947 +	  </listitem></itemizedlist>
  1.1948 +      </sect3>
  1.1949 +
  1.1950 +      <sect3>
  1.1951 +	<title>Options specific to the <command role="hg-cmd">hg
  1.1952 +	    serve</command> command</title>
  1.1953 +
  1.1954 +	<para id="x_4f6">Some of the items in the <literal
  1.1955 +	    role="rc-web">web</literal> section of a <filename
  1.1956 +	    role="special">~/.hgrc</filename> file are only for use
  1.1957 +	  with the <command role="hg-cmd">hg serve</command>
  1.1958 +	  command.</para>
  1.1959 +	<itemizedlist>
  1.1960 +	  <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>:
  1.1961 +	      Path.  The name of a file into which to write an access
  1.1962 +	      log.  By default, the <command role="hg-cmd">hg
  1.1963 +		serve</command> command writes this information to
  1.1964 +	      standard output, not to a file.  Log entries are written
  1.1965 +	      in the standard <quote>combined</quote> file format used
  1.1966 +	      by almost all web servers.</para>
  1.1967 +	  </listitem>
  1.1968 +	  <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>:
  1.1969 +	      String.  The local address on which the server should
  1.1970 +	      listen for incoming connections.  By default, the server
  1.1971 +	      listens on all addresses.</para>
  1.1972 +	  </listitem>
  1.1973 +	  <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>:
  1.1974 +	      Path.  The name of a file into which to write an error
  1.1975 +	      log.  By default, the <command role="hg-cmd">hg
  1.1976 +		serve</command> command writes this information to
  1.1977 +	      standard error, not to a file.</para>
  1.1978 +	  </listitem>
  1.1979 +	  <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>:
  1.1980 +	      Boolean.  Whether to use the IPv6 protocol. By default,
  1.1981 +	      IPv6 is not used.</para>
  1.1982 +	  </listitem>
  1.1983 +	  <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>:
  1.1984 +	      Integer.  The TCP port number on which the server should
  1.1985 +	      listen.  The default port number used is 8000.</para>
  1.1986 +	  </listitem></itemizedlist>
  1.1987 +      </sect3>
  1.1988 +
  1.1989 +      <sect3>
  1.1990 +	<title>Choosing the right <filename
  1.1991 +	    role="special">~/.hgrc</filename> file to add <literal
  1.1992 +	    role="rc-web">web</literal> items to</title>
  1.1993 +
  1.1994 +	<para id="x_4fc">It is important to remember that a web server like
  1.1995 +	  Apache or <literal>lighttpd</literal> will run under a user
  1.1996 +	  ID that is different to yours. CGI scripts run by your
  1.1997 +	  server, such as <filename
  1.1998 +	    role="special">hgweb.cgi</filename>, will usually also run
  1.1999 +	  under that user ID.</para>
  1.2000 +
  1.2001 +	<para id="x_4fd">If you add <literal role="rc-web">web</literal> items to
  1.2002 +	  your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that
  1.2003 +	  <filename role="special">~/.hgrc</filename> file.  Those
  1.2004 +	  settings will thus only affect the behavior of the <command
  1.2005 +	    role="hg-cmd">hg serve</command> command when you run it.
  1.2006 +	  To cause CGI scripts to see your settings, either create a
  1.2007 +	  <filename role="special">~/.hgrc</filename> file in the
  1.2008 +	  home directory of the user ID that runs your web server, or
  1.2009 +	  add those settings to a system-wide <filename
  1.2010 +	    role="special">hgrc</filename> file.</para>
  1.2011 +      </sect3>
  1.2012 +    </sect2>
  1.2013 +  </sect1>
  1.2014 +
  1.2015 +  <sect1>
  1.2016 +    <title>System-wide configuration</title>
  1.2017 +
  1.2018 +    <para id="x_6b0">On Unix-like systems shared by multiple users (such as a
  1.2019 +      server to which people publish changes), it often makes sense to
  1.2020 +      set up some global default behaviors, such as what theme to use
  1.2021 +      in web interfaces.</para>
  1.2022 +
  1.2023 +    <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename>
  1.2024 +      exists, Mercurial will read it at startup time and apply any
  1.2025 +      configuration settings it finds in that file.  It will also look
  1.2026 +      for files ending in a <literal>.rc</literal> extension in a
  1.2027 +      directory named <filename>/etc/mercurial/hgrc.d</filename>, and
  1.2028 +      apply any configuration settings it finds in each of those
  1.2029 +      files.</para>
  1.2030 +
  1.2031 +    <sect2>
  1.2032 +      <title>Making Mercurial more trusting</title>
  1.2033 +
  1.2034 +      <para id="x_6b2">One situation in which a global <filename>hgrc</filename>
  1.2035 +	can be useful is if users are pulling changes owned by other
  1.2036 +	users.  By default, Mercurial will not trust most of the
  1.2037 +	configuration items in a <filename>.hg/hgrc</filename> file
  1.2038 +	inside a repository that is owned by a different user. If we
  1.2039 +	clone or pull changes from such a repository, Mercurial will
  1.2040 +	print a warning stating that it does not trust their
  1.2041 +	<filename>.hg/hgrc</filename>.</para>
  1.2042 +
  1.2043 +      <para id="x_6b3">If everyone in a particular Unix group is on the same team
  1.2044 +	and <emphasis>should</emphasis> trust each other's
  1.2045 +	configuration settings, or we want to trust particular users,
  1.2046 +	we can override Mercurial's skeptical defaults by creating a
  1.2047 +	system-wide <filename>hgrc</filename> file such as the
  1.2048 +	following:</para>
  1.2049 +
  1.2050 +    <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
  1.2051 +[trusted]
  1.2052 +# Trust all entries in any hgrc file owned by the "editors" or
  1.2053 +# "www-data" groups.
  1.2054 +groups = editors, www-data
  1.2055 +
  1.2056 +# Trust entries in hgrc files owned by the following users.
  1.2057 +users = apache, bobo
  1.2058  </programlisting>
  1.2059 -<orderedlist>
  1.2060 -<listitem><para>The <quote><literal>ssh://</literal></quote> part tells Mercurial to use the ssh
  1.2061 -  protocol.
  1.2062 -</para>
  1.2063 -</listitem>
  1.2064 -<listitem><para>The <quote><literal>bos@</literal></quote> component indicates what username to log
  1.2065 -  into the server as.  You can leave this out if the remote username
  1.2066 -  is the same as your local username.
  1.2067 -</para>
  1.2068 -</listitem>
  1.2069 -<listitem><para>The <quote><literal>hg.serpentine.com</literal></quote> gives the hostname of the
  1.2070 -  server to log into.
  1.2071 -</para>
  1.2072 -</listitem>
  1.2073 -<listitem><para>The <quote>:22</quote> identifies the port number to connect to the server
  1.2074 -  on.  The default port is 22, so you only need to specify this part
  1.2075 -  if you're <emphasis>not</emphasis> using port 22.
  1.2076 -</para>
  1.2077 -</listitem>
  1.2078 -<listitem><para>The remainder of the URL is the local path to the repository on
  1.2079 -  the server.
  1.2080 -</para>
  1.2081 -</listitem></orderedlist>
  1.2082 -
  1.2083 -<para>There's plenty of scope for confusion with the path component of ssh
  1.2084 -URLs, as there is no standard way for tools to interpret it.  Some
  1.2085 -programs behave differently than others when dealing with these paths.
  1.2086 -This isn't an ideal situation, but it's unlikely to change.  Please
  1.2087 -read the following paragraphs carefully.
  1.2088 -</para>
  1.2089 -
  1.2090 -<para>Mercurial treats the path to a repository on the server as relative to
  1.2091 -the remote user's home directory.  For example, if user <literal>foo</literal>
  1.2092 -on the server has a home directory of <filename class="directory">/home/foo</filename>, then an ssh
  1.2093 -URL that contains a path component of <filename class="directory">bar</filename>
  1.2094 -<emphasis>really</emphasis> refers to the directory <filename class="directory">/home/foo/bar</filename>.
  1.2095 -</para>
  1.2096 -
  1.2097 -<para>If you want to specify a path relative to another user's home
  1.2098 -directory, you can use a path that starts with a tilde character
  1.2099 -followed by the user's name (let's call them <literal>otheruser</literal>), like
  1.2100 -this.
  1.2101 -</para>
  1.2102 -<programlisting>
  1.2103 -<para>  ssh://server/ otheruser/hg/repo
  1.2104 -</para>
  1.2105 -</programlisting>
  1.2106 -
  1.2107 -<para>And if you really want to specify an <emphasis>absolute</emphasis> path on the
  1.2108 -server, begin the path component with two slashes, as in this example.
  1.2109 -</para>
  1.2110 -<programlisting>
  1.2111 -<para>  ssh://server//absolute/path
  1.2112 -</para>
  1.2113 -</programlisting>
  1.2114 -
  1.2115 -</sect2>
  1.2116 -<sect2>
  1.2117 -<title>Finding an ssh client for your system</title>
  1.2118 -
  1.2119 -<para>Almost every Unix-like system comes with OpenSSH preinstalled.  If
  1.2120 -you're using such a system, run <literal>which ssh</literal> to find out if
  1.2121 -the <command>ssh</command> command is installed (it's usually in
  1.2122 -<filename class="directory">/usr/bin</filename>).  In the unlikely event that it isn't present,
  1.2123 -take a look at your system documentation to figure out how to install
  1.2124 -it.
  1.2125 -</para>
  1.2126 -
  1.2127 -<para>On Windows, you'll first need to download a suitable ssh
  1.2128 -client.  There are two alternatives.
  1.2129 -</para>
  1.2130 -<itemizedlist>
  1.2131 -<listitem><para>Simon Tatham's excellent PuTTY package <citation>web:putty</citation> provides
  1.2132 -  a complete suite of ssh client commands.
  1.2133 -</para>
  1.2134 -</listitem>
  1.2135 -<listitem><para>If you have a high tolerance for pain, you can use the Cygwin
  1.2136 -  port of OpenSSH.
  1.2137 -</para>
  1.2138 -</listitem></itemizedlist>
  1.2139 -<para>In either case, you'll need to edit your \hgini\ file to tell
  1.2140 -Mercurial where to find the actual client command.  For example, if
  1.2141 -you're using PuTTY, you'll need to use the <command>plink</command> command as
  1.2142 -a command-line ssh client.
  1.2143 -</para>
  1.2144 -<programlisting>
  1.2145 -<para>  [ui]
  1.2146 -  ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"
  1.2147 -</para>
  1.2148 -</programlisting>
  1.2149 -
  1.2150 -<note>
  1.2151 -<para>  The path to <command>plink</command> shouldn't contain any whitespace
  1.2152 -  characters, or Mercurial may not be able to run it correctly (so
  1.2153 -  putting it in <filename class="directory">C:\\Program Files</filename> is probably not a good
  1.2154 -  idea).
  1.2155 -</para>
  1.2156 -</note>
  1.2157 -
  1.2158 -</sect2>
  1.2159 -<sect2>
  1.2160 -<title>Generating a key pair</title>
  1.2161 -
  1.2162 -<para>To avoid the need to repetitively type a password every time you need
  1.2163 -to use your ssh client, I recommend generating a key pair.  On a
  1.2164 -Unix-like system, the <command>ssh-keygen</command> command will do the trick.
  1.2165 -On Windows, if you're using PuTTY, the <command>puttygen</command> command is
  1.2166 -what you'll need.
  1.2167 -</para>
  1.2168 -
  1.2169 -<para>When you generate a key pair, it's usually <emphasis>highly</emphasis> advisable to
  1.2170 -protect it with a passphrase.  (The only time that you might not want
  1.2171 -to do this is when you're using the ssh protocol for automated tasks
  1.2172 -on a secure network.)
  1.2173 -</para>
  1.2174 -
  1.2175 -<para>Simply generating a key pair isn't enough, however.  You'll need to
  1.2176 -add the public key to the set of authorised keys for whatever user
  1.2177 -you're logging in remotely as.  For servers using OpenSSH (the vast
  1.2178 -majority), this will mean adding the public key to a list in a file
  1.2179 -called <filename role="special">authorized_keys</filename> in their <filename role="special" class="directory">.ssh</filename>
  1.2180 -directory.
  1.2181 -</para>
  1.2182 -
  1.2183 -<para>On a Unix-like system, your public key will have a <filename>.pub</filename>
  1.2184 -extension.  If you're using <command>puttygen</command> on Windows, you can
  1.2185 -save the public key to a file of your choosing, or paste it from the
  1.2186 -window it's displayed in straight into the
  1.2187 -<filename role="special">authorized_keys</filename> file.
  1.2188 -</para>
  1.2189 -
  1.2190 -</sect2>
  1.2191 -<sect2>
  1.2192 -<title>Using an authentication agent</title>
  1.2193 -
  1.2194 -<para>An authentication agent is a daemon that stores passphrases in memory
  1.2195 -(so it will forget passphrases if you log out and log back in again).
  1.2196 -An ssh client will notice if it's running, and query it for a
  1.2197 -passphrase.  If there's no authentication agent running, or the agent
  1.2198 -doesn't store the necessary passphrase, you'll have to type your
  1.2199 -passphrase every time Mercurial tries to communicate with a server on
  1.2200 -your behalf (e.g. whenever you pull or push changes).
  1.2201 -</para>
  1.2202 -
  1.2203 -<para>The downside of storing passphrases in an agent is that it's possible
  1.2204 -for a well-prepared attacker to recover the plain text of your
  1.2205 -passphrases, in some cases even if your system has been power-cycled.
  1.2206 -You should make your own judgment as to whether this is an acceptable
  1.2207 -risk.  It certainly saves a lot of repeated typing.
  1.2208 -</para>
  1.2209 -
  1.2210 -<para>On Unix-like systems, the agent is called <command>ssh-agent</command>, and
  1.2211 -it's often run automatically for you when you log in.  You'll need to
  1.2212 -use the <command>ssh-add</command> command to add passphrases to the agent's
  1.2213 -store.  On Windows, if you're using PuTTY, the <command>pageant</command>
  1.2214 -command acts as the agent.  It adds an icon to your system tray that
  1.2215 -will let you manage stored passphrases.
  1.2216 -</para>
  1.2217 -
  1.2218 -</sect2>
  1.2219 -<sect2>
  1.2220 -<title>Configuring the server side properly</title>
  1.2221 -
  1.2222 -<para>Because ssh can be fiddly to set up if you're new to it, there's a
  1.2223 -variety of things that can go wrong.  Add Mercurial on top, and
  1.2224 -there's plenty more scope for head-scratching.  Most of these
  1.2225 -potential problems occur on the server side, not the client side.  The
  1.2226 -good news is that once you've gotten a configuration working, it will
  1.2227 -usually continue to work indefinitely.
  1.2228 -</para>
  1.2229 -
  1.2230 -<para>Before you try using Mercurial to talk to an ssh server, it's best to
  1.2231 -make sure that you can use the normal <command>ssh</command> or <command>putty</command>
  1.2232 -command to talk to the server first.  If you run into problems with
  1.2233 -using these commands directly, Mercurial surely won't work.  Worse, it
  1.2234 -will obscure the underlying problem.  Any time you want to debug
  1.2235 -ssh-related Mercurial problems, you should drop back to making sure
  1.2236 -that plain ssh client commands work first, <emphasis>before</emphasis> you worry
  1.2237 -about whether there's a problem with Mercurial.
  1.2238 -</para>
  1.2239 -
  1.2240 -<para>The first thing to be sure of on the server side is that you can
  1.2241 -actually log in from another machine at all.  If you can't use
  1.2242 -<command>ssh</command> or <command>putty</command> to log in, the error message you get
  1.2243 -may give you a few hints as to what's wrong.  The most common problems
  1.2244 -are as follows.
  1.2245 -</para>
  1.2246 -<itemizedlist>
  1.2247 -<listitem><para>If you get a <quote>connection refused</quote> error, either there isn't an
  1.2248 -  SSH daemon running on the server at all, or it's inaccessible due to
  1.2249 -  firewall configuration.
  1.2250 -</para>
  1.2251 -</listitem>
  1.2252 -<listitem><para>If you get a <quote>no route to host</quote> error, you either have an
  1.2253 -  incorrect address for the server or a seriously locked down firewall
  1.2254 -  that won't admit its existence at all.
  1.2255 -</para>
  1.2256 -</listitem>
  1.2257 -<listitem><para>If you get a <quote>permission denied</quote> error, you may have mistyped
  1.2258 -  the username on the server, or you could have mistyped your key's
  1.2259 -  passphrase or the remote user's password.
  1.2260 -</para>
  1.2261 -</listitem></itemizedlist>
  1.2262 -<para>In summary, if you're having trouble talking to the server's ssh
  1.2263 -daemon, first make sure that one is running at all.  On many systems
  1.2264 -it will be installed, but disabled, by default.  Once you're done with
  1.2265 -this step, you should then check that the server's firewall is
  1.2266 -configured to allow incoming connections on the port the ssh daemon is
  1.2267 -listening on (usually 22).  Don't worry about more exotic
  1.2268 -possibilities for misconfiguration until you've checked these two
  1.2269 -first.
  1.2270 -</para>
  1.2271 -
  1.2272 -<para>If you're using an authentication agent on the client side to store
  1.2273 -passphrases for your keys, you ought to be able to log into the server
  1.2274 -without being prompted for a passphrase or a password.  If you're
  1.2275 -prompted for a passphrase, there are a few possible culprits.
  1.2276 -</para>
  1.2277 -<itemizedlist>
  1.2278 -<listitem><para>You might have forgotten to use <command>ssh-add</command> or
  1.2279 -  <command>pageant</command> to store the passphrase.
  1.2280 -</para>
  1.2281 -</listitem>
  1.2282 -<listitem><para>You might have stored the passphrase for the wrong key.
  1.2283 -</para>
  1.2284 -</listitem></itemizedlist>
  1.2285 -<para>If you're being prompted for the remote user's password, there are
  1.2286 -another few possible problems to check.
  1.2287 -</para>
  1.2288 -<itemizedlist>
  1.2289 -<listitem><para>Either the user's home directory or their <filename role="special" class="directory">.ssh</filename>
  1.2290 -  directory might have excessively liberal permissions.  As a result,
  1.2291 -  the ssh daemon will not trust or read their
  1.2292 -  <filename role="special">authorized_keys</filename> file.  For example, a group-writable
  1.2293 -  home or <filename role="special" class="directory">.ssh</filename> directory will often cause this symptom.
  1.2294 -</para>
  1.2295 -</listitem>
  1.2296 -<listitem><para>The user's <filename role="special">authorized_keys</filename> file may have a problem.
  1.2297 -  If anyone other than the user owns or can write to that file, the
  1.2298 -  ssh daemon will not trust or read it.
  1.2299 -</para>
  1.2300 -</listitem></itemizedlist>
  1.2301 -
  1.2302 -<para>In the ideal world, you should be able to run the following command
  1.2303 -successfully, and it should print exactly one line of output, the
  1.2304 -current date and time.
  1.2305 -</para>
  1.2306 -<programlisting>
  1.2307 -<para>  ssh myserver date
  1.2308 -</para>
  1.2309 -</programlisting>
  1.2310 -
  1.2311 -<para>If, on your server, you have login scripts that print banners or other
  1.2312 -junk even when running non-interactive commands like this, you should
  1.2313 -fix them before you continue, so that they only print output if
  1.2314 -they're run interactively.  Otherwise these banners will at least
  1.2315 -clutter up Mercurial's output.  Worse, they could potentially cause
  1.2316 -problems with running Mercurial commands remotely.  Mercurial makes
  1.2317 -tries to detect and ignore banners in non-interactive <command>ssh</command>
  1.2318 -sessions, but it is not foolproof.  (If you're editing your login
  1.2319 -scripts on your server, the usual way to see if a login script is
  1.2320 -running in an interactive shell is to check the return code from the
  1.2321 -command <literal>tty -s</literal>.)
  1.2322 -</para>
  1.2323 -
  1.2324 -<para>Once you've verified that plain old ssh is working with your server,
  1.2325 -the next step is to ensure that Mercurial runs on the server.  The
  1.2326 -following command should run successfully:
  1.2327 -</para>
  1.2328 -<programlisting>
  1.2329 -<para>  ssh myserver hg version
  1.2330 -</para>
  1.2331 -</programlisting>
  1.2332 -<para>If you see an error message instead of normal <command role="hg-cmd">hg version</command> output,
  1.2333 -this is usually because you haven't installed Mercurial to
  1.2334 -<filename class="directory">/usr/bin</filename>.  Don't worry if this is the case; you don't need
  1.2335 -to do that.  But you should check for a few possible problems.
  1.2336 -</para>
  1.2337 -<itemizedlist>
  1.2338 -<listitem><para>Is Mercurial really installed on the server at all?  I know this
  1.2339 -  sounds trivial, but it's worth checking!
  1.2340 -</para>
  1.2341 -</listitem>
  1.2342 -<listitem><para>Maybe your shell's search path (usually set via the <envar>PATH</envar>
  1.2343 -  environment variable) is simply misconfigured.
  1.2344 -</para>
  1.2345 -</listitem>
  1.2346 -<listitem><para>Perhaps your <envar>PATH</envar> environment variable is only being set
  1.2347 -  to point to the location of the <command>hg</command> executable if the login
  1.2348 -  session is interactive.  This can happen if you're setting the path
  1.2349 -  in the wrong shell login script.  See your shell's documentation for
  1.2350 -  details.
  1.2351 -</para>
  1.2352 -</listitem>
  1.2353 -<listitem><para>The <envar>PYTHONPATH</envar> environment variable may need to contain
  1.2354 -  the path to the Mercurial Python modules.  It might not be set at
  1.2355 -  all; it could be incorrect; or it may be set only if the login is
  1.2356 -  interactive.
  1.2357 -</para>
  1.2358 -</listitem></itemizedlist>
  1.2359 -
  1.2360 -<para>If you can run <command role="hg-cmd">hg version</command> over an ssh connection, well done!
  1.2361 -You've got the server and client sorted out.  You should now be able
  1.2362 -to use Mercurial to access repositories hosted by that username on
  1.2363 -that server.  If you run into problems with Mercurial and ssh at this
  1.2364 -point, try using the <option role="hg-opt-global">--debug</option> option to get a clearer picture
  1.2365 -of what's going on.
  1.2366 -</para>
  1.2367 -
  1.2368 -</sect2>
  1.2369 -<sect2>
  1.2370 -<title>Using compression with ssh</title>
  1.2371 -
  1.2372 -<para>Mercurial does not compress data when it uses the ssh protocol,
  1.2373 -because the ssh protocol can transparently compress data.  However,
  1.2374 -the default behaviour of ssh clients is <emphasis>not</emphasis> to request
  1.2375 -compression.
  1.2376 -</para>
  1.2377 -
  1.2378 -<para>Over any network other than a fast LAN (even a wireless network),
  1.2379 -using compression is likely to significantly speed up Mercurial's
  1.2380 -network operations.  For example, over a WAN, someone measured
  1.2381 -compression as reducing the amount of time required to clone a
  1.2382 -particularly large repository from 51 minutes to 17 minutes.
  1.2383 -</para>
  1.2384 -
  1.2385 -<para>Both <command>ssh</command> and <command>plink</command> accept a <option role="cmd-opt-ssh">-C</option>
  1.2386 -option which turns on compression.  You can easily edit your <filename role="special"> /.hgrc</filename>\ to
  1.2387 -enable compression for all of Mercurial's uses of the ssh protocol.
  1.2388 -</para>
  1.2389 -<programlisting>
  1.2390 -<para>  [ui]
  1.2391 -  ssh = ssh -C
  1.2392 -</para>
  1.2393 -</programlisting>
  1.2394 -
  1.2395 -<para>If you use <command>ssh</command>, you can configure it to always use
  1.2396 -compression when talking to your server.  To do this, edit your
  1.2397 -<filename role="special">.ssh/config</filename> file (which may not yet exist), as follows.
  1.2398 -</para>
  1.2399 -<programlisting>
  1.2400 -<para>  Host hg
  1.2401 -    Compression yes
  1.2402 -    HostName hg.example.com
  1.2403 -</para>
  1.2404 -</programlisting>
  1.2405 -<para>This defines an alias, <literal>hg</literal>.  When you use it on the
  1.2406 -<command>ssh</command> command line or in a Mercurial <literal>ssh</literal>-protocol
  1.2407 -URL, it will cause <command>ssh</command> to connect to <literal>hg.example.com</literal>
  1.2408 -and use compression.  This gives you both a shorter name to type and
  1.2409 -compression, each of which is a good thing in its own right.
  1.2410 -</para>
  1.2411 -
  1.2412 -</sect2>
  1.2413 -</sect1>
  1.2414 -<sect1>
  1.2415 -<title>Serving over HTTP using CGI</title>
  1.2416 -<para>\label{sec:collab:cgi}
  1.2417 -</para>
  1.2418 -
  1.2419 -<para>Depending on how ambitious you are, configuring Mercurial's CGI
  1.2420 -interface can take anything from a few moments to several hours.
  1.2421 -</para>
  1.2422 -
  1.2423 -<para>We'll begin with the simplest of examples, and work our way towards a
  1.2424 -more complex configuration.  Even for the most basic case, you're
  1.2425 -almost certainly going to need to read and modify your web server's
  1.2426 -configuration.
  1.2427 -</para>
  1.2428 -
  1.2429 -<note>
  1.2430 -<para>  Configuring a web server is a complex, fiddly, and highly
  1.2431 -  system-dependent activity.  I can't possibly give you instructions
  1.2432 -  that will cover anything like all of the cases you will encounter.
  1.2433 -  Please use your discretion and judgment in following the sections
  1.2434 -  below.  Be prepared to make plenty of mistakes, and to spend a lot
  1.2435 -  of time reading your server's error logs.
  1.2436 -</para>
  1.2437 -</note>
  1.2438 -
  1.2439 -<sect2>
  1.2440 -<title>Web server configuration checklist</title>
  1.2441 -
  1.2442 -<para>Before you continue, do take a few moments to check a few aspects of
  1.2443 -your system's setup.
  1.2444 -</para>
  1.2445 -
  1.2446 -<orderedlist>
  1.2447 -<listitem><para>Do you have a web server installed at all?  Mac OS X ships with
  1.2448 -  Apache, but many other systems may not have a web server installed.
  1.2449 -</para>
  1.2450 -</listitem>
  1.2451 -<listitem><para>If you have a web server installed, is it actually running?  On
  1.2452 -  most systems, even if one is present, it will be disabled by
  1.2453 -  default.
  1.2454 -</para>
  1.2455 -</listitem>
  1.2456 -<listitem><para>Is your server configured to allow you to run CGI programs in
  1.2457 -  the directory where you plan to do so?  Most servers default to
  1.2458 -  explicitly disabling the ability to run CGI programs.
  1.2459 -</para>
  1.2460 -</listitem></orderedlist>
  1.2461 -
  1.2462 -<para>If you don't have a web server installed, and don't have substantial
  1.2463 -experience configuring Apache, you should consider using the
  1.2464 -<literal>lighttpd</literal> web server instead of Apache.  Apache has a
  1.2465 -well-deserved reputation for baroque and confusing configuration.
  1.2466 -While <literal>lighttpd</literal> is less capable in some ways than Apache, most
  1.2467 -of these capabilities are not relevant to serving Mercurial
  1.2468 -repositories.  And <literal>lighttpd</literal> is undeniably <emphasis>much</emphasis> easier
  1.2469 -to get started with than Apache.
  1.2470 -</para>
  1.2471 -
  1.2472 -</sect2>
  1.2473 -<sect2>
  1.2474 -<title>Basic CGI configuration</title>
  1.2475 -
  1.2476 -<para>On Unix-like systems, it's common for users to have a subdirectory
  1.2477 -named something like <filename class="directory">public_html</filename> in their home directory,
  1.2478 -from which they can serve up web pages.  A file named <filename>foo</filename>
  1.2479 -in this directory will be accessible at a URL of the form
  1.2480 -<literal>http://www.example.com/\ {</literal>username/foo}.
  1.2481 -</para>
  1.2482 -
  1.2483 -<para>To get started, find the <filename role="special">hgweb.cgi</filename> script that should be
  1.2484 -present in your Mercurial installation.  If you can't quickly find a
  1.2485 -local copy on your system, simply download one from the master
  1.2486 -Mercurial repository at
  1.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>.
  1.2488 -</para>
  1.2489 -
  1.2490 -<para>You'll need to copy this script into your <filename class="directory">public_html</filename>
  1.2491 -directory, and ensure that it's executable.
  1.2492 -</para>
  1.2493 -<programlisting>
  1.2494 -<para>  cp .../hgweb.cgi  /public_html
  1.2495 -  chmod 755  /public_html/hgweb.cgi
  1.2496 -</para>
  1.2497 -</programlisting>
  1.2498 -<para>The <literal>755</literal> argument to <command>chmod</command> is a little more general
  1.2499 -than just making the script executable: it ensures that the script is
  1.2500 -executable by anyone, and that <quote>group</quote> and <quote>other</quote> write
  1.2501 -permissions are <emphasis>not</emphasis> set.  If you were to leave those write
  1.2502 -permissions enabled, Apache's <literal>suexec</literal> subsystem would likely
  1.2503 -refuse to execute the script.  In fact, <literal>suexec</literal> also insists
  1.2504 -that the <emphasis>directory</emphasis> in which the script resides must not be
  1.2505 -writable by others.
  1.2506 -</para>
  1.2507 -<programlisting>
  1.2508 -<para>  chmod 755  /public_html
  1.2509 -</para>
  1.2510 -</programlisting>
  1.2511 -
  1.2512 -<sect3>
  1.2513 -<title>What could <emphasis>possibly</emphasis> go wrong?</title>
  1.2514 -<para>\label{sec:collab:wtf}
  1.2515 -</para>
  1.2516 -
  1.2517 -<para>Once you've copied the CGI script into place, go into a web browser,
  1.2518 -and try to open the URL <ulink url="http://myhostname/ myuser/hgweb.cgi">http://myhostname/ myuser/hgweb.cgi</ulink>,
  1.2519 -<emphasis>but</emphasis> brace yourself for instant failure.  There's a high
  1.2520 -probability that trying to visit this URL will fail, and there are
  1.2521 -many possible reasons for this.  In fact, you're likely to stumble
  1.2522 -over almost every one of the possible errors below, so please read
  1.2523 -carefully.  The following are all of the problems I ran into on a
  1.2524 -system running Fedora 7, with a fresh installation of Apache, and a
  1.2525 -user account that I created specially to perform this exercise.
  1.2526 -</para>
  1.2527 -
  1.2528 -<para>Your web server may have per-user directories disabled.  If you're
  1.2529 -using Apache, search your config file for a <literal>UserDir</literal>
  1.2530 -directive.  If there's none present, per-user directories will be
  1.2531 -disabled.  If one exists, but its value is <literal>disabled</literal>, then
  1.2532 -per-user directories will be disabled.  Otherwise, the string after
  1.2533 -<literal>UserDir</literal> gives the name of the subdirectory that Apache will
  1.2534 -look in under your home directory, for example <filename class="directory">public_html</filename>.
  1.2535 -</para>
  1.2536 -
  1.2537 -<para>Your file access permissions may be too restrictive.  The web server
  1.2538 -must be able to traverse your home directory and directories under
  1.2539 -your <filename class="directory">public_html</filename> directory, and read files under the latter
  1.2540 -too.  Here's a quick recipe to help you to make your permissions more
  1.2541 -appropriate.
  1.2542 -</para>
  1.2543 -<programlisting>
  1.2544 -<para>  chmod 755  
  1.2545 -  find  /public_html -type d -print0 | xargs -0r chmod 755
  1.2546 -  find  /public_html -type f -print0 | xargs -0r chmod 644
  1.2547 -</para>
  1.2548 -</programlisting>
  1.2549 -
  1.2550 -<para>The other possibility with permissions is that you might get a
  1.2551 -completely empty window when you try to load the script.  In this
  1.2552 -case, it's likely that your access permissions are \emph{too
  1.2553 -  permissive}.  Apache's <literal>suexec</literal> subsystem won't execute a
  1.2554 -script that's group- or world-writable, for example.
  1.2555 -</para>
  1.2556 -
  1.2557 -<para>Your web server may be configured to disallow execution of CGI
  1.2558 -programs in your per-user web directory.  Here's Apache's
  1.2559 -default per-user configuration from my Fedora system.
  1.2560 -</para>
  1.2561 -<programlisting>
  1.2562 -<para>  &lt;Directory /home/*/public_html&gt;
  1.2563 -      AllowOverride FileInfo AuthConfig Limit
  1.2564 -      Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
  1.2565 -      &lt;Limit GET POST OPTIONS&gt;
  1.2566 -          Order allow,deny
  1.2567 -          Allow from all
  1.2568 -      &lt;/Limit&gt;
  1.2569 -      &lt;LimitExcept GET POST OPTIONS&gt;
  1.2570 -          Order deny,allow
  1.2571 -          Deny from all
  1.2572 -      &lt;/LimitExcept&gt;
  1.2573 -  &lt;/Directory&gt;
  1.2574 -</para>
  1.2575 -</programlisting>
  1.2576 -<para>If you find a similar-looking <literal>Directory</literal> group in your Apache
  1.2577 -configuration, the directive to look at inside it is <literal>Options</literal>.
  1.2578 -Add <literal>ExecCGI</literal> to the end of this list if it's missing, and
  1.2579 -restart the web server.
  1.2580 -</para>
  1.2581 -
  1.2582 -<para>If you find that Apache serves you the text of the CGI script instead
  1.2583 -of executing it, you may need to either uncomment (if already present)
  1.2584 -or add a directive like this.
  1.2585 -</para>
  1.2586 -<programlisting>
  1.2587 -<para>  AddHandler cgi-script .cgi
  1.2588 -</para>
  1.2589 -</programlisting>
  1.2590 -
  1.2591 -<para>The next possibility is that you might be served with a colourful
  1.2592 -Python backtrace claiming that it can't import a
  1.2593 -<literal>mercurial</literal>-related module.  This is actually progress!  The
  1.2594 -server is now capable of executing your CGI script.  This error is
  1.2595 -only likely to occur if you're running a private installation of
  1.2596 -Mercurial, instead of a system-wide version.  Remember that the web
  1.2597 -server runs the CGI program without any of the environment variables
  1.2598 -that you take for granted in an interactive session.  If this error
  1.2599 -happens to you, edit your copy of <filename role="special">hgweb.cgi</filename> and follow the
  1.2600 -directions inside it to correctly set your <envar>PYTHONPATH</envar>
  1.2601 -environment variable.
  1.2602 -</para>
  1.2603 -
  1.2604 -<para>Finally, you are <emphasis>certain</emphasis> to by served with another colourful
  1.2605 -Python backtrace: this one will complain that it can't find
  1.2606 -<filename class="directory">/path/to/repository</filename>.  Edit your <filename role="special">hgweb.cgi</filename> script
  1.2607 -and replace the <filename class="directory">/path/to/repository</filename> string with the complete
  1.2608 -path to the repository you want to serve up.
  1.2609 -</para>
  1.2610 -
  1.2611 -<para>At this point, when you try to reload the page, you should be
  1.2612 -presented with a nice HTML view of your repository's history.  Whew!
  1.2613 -</para>
  1.2614 -
  1.2615 -</sect3>
  1.2616 -<sect3>
  1.2617 -<title>Configuring lighttpd</title>
  1.2618 -
  1.2619 -<para>To be exhaustive in my experiments, I tried configuring the
  1.2620 -increasingly popular <literal>lighttpd</literal> web server to serve the same
  1.2621 -repository as I described with Apache above.  I had already overcome
  1.2622 -all of the problems I outlined with Apache, many of which are not
  1.2623 -server-specific.  As a result, I was fairly sure that my file and
  1.2624 -directory permissions were good, and that my <filename role="special">hgweb.cgi</filename>
  1.2625 -script was properly edited.
  1.2626 -</para>
  1.2627 -
  1.2628 -<para>Once I had Apache running, getting <literal>lighttpd</literal> to serve the
  1.2629 -repository was a snap (in other words, even if you're trying to use
  1.2630 -<literal>lighttpd</literal>, you should read the Apache section).  I first had
  1.2631 -to edit the <literal>mod_access</literal> section of its config file to enable
  1.2632 -<literal>mod_cgi</literal> and <literal>mod_userdir</literal>, both of which were
  1.2633 -disabled by default on my system.  I then added a few lines to the end
  1.2634 -of the config file, to configure these modules.
  1.2635 -</para>
  1.2636 -<programlisting>
  1.2637 -<para>  userdir.path = "public_html"
  1.2638 -  cgi.assign = ( ".cgi" =&gt; "" )
  1.2639 -</para>
  1.2640 -</programlisting>
  1.2641 -<para>With this done, <literal>lighttpd</literal> ran immediately for me.  If I had
  1.2642 -configured <literal>lighttpd</literal> before Apache, I'd almost certainly have
  1.2643 -run into many of the same system-level configuration problems as I did
  1.2644 -with Apache.  However, I found <literal>lighttpd</literal> to be noticeably
  1.2645 -easier to configure than Apache, even though I've used Apache for over
  1.2646 -a decade, and this was my first exposure to <literal>lighttpd</literal>.
  1.2647 -</para>
  1.2648 -
  1.2649 -</sect3>
  1.2650 -</sect2>
  1.2651 -<sect2>
  1.2652 -<title>Sharing multiple repositories with one CGI script</title>
  1.2653 -
  1.2654 -<para>The <filename role="special">hgweb.cgi</filename> script only lets you publish a single
  1.2655 -repository, which is an annoying restriction.  If you want to publish
  1.2656 -more than one without wracking yourself with multiple copies of the
  1.2657 -same script, each with different names, a better choice is to use the
  1.2658 -<filename role="special">hgwebdir.cgi</filename> script.
  1.2659 -</para>
  1.2660 -
  1.2661 -<para>The procedure to configure <filename role="special">hgwebdir.cgi</filename> is only a little
  1.2662 -more involved than for <filename role="special">hgweb.cgi</filename>.  First, you must obtain
  1.2663 -a copy of the script.  If you don't have one handy, you can download a
  1.2664 -copy from the master Mercurial repository at
  1.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>.
  1.2666 -</para>
  1.2667 -
  1.2668 -<para>You'll need to copy this script into your <filename class="directory">public_html</filename>
  1.2669 -directory, and ensure that it's executable.
  1.2670 -</para>
  1.2671 -<programlisting>
  1.2672 -<para>  cp .../hgwebdir.cgi  /public_html
  1.2673 -  chmod 755  /public_html  /public_html/hgwebdir.cgi
  1.2674 -</para>
  1.2675 -</programlisting>
  1.2676 -<para>With basic configuration out of the way, try to visit
  1.2677 -<ulink url="http://myhostname/ myuser/hgwebdir.cgi">http://myhostname/ myuser/hgwebdir.cgi</ulink> in your browser.  It
  1.2678 -should display an empty list of repositories.  If you get a blank
  1.2679 -window or error message, try walking through the list of potential
  1.2680 -problems in section <xref linkend="sec:collab:wtf"/>.
  1.2681 -</para>
  1.2682 -
  1.2683 -<para>The <filename role="special">hgwebdir.cgi</filename> script relies on an external
  1.2684 -configuration file.  By default, it searches for a file named
  1.2685 -<filename role="special">hgweb.config</filename> in the same directory as itself.  You'll need
  1.2686 -to create this file, and make it world-readable.  The format of the
  1.2687 -file is similar to a Windows <quote>ini</quote> file, as understood by Python's
  1.2688 -<literal>ConfigParser</literal> <citation>web:configparser</citation> module.
  1.2689 -</para>
  1.2690 -
  1.2691 -<para>The easiest way to configure <filename role="special">hgwebdir.cgi</filename> is with a
  1.2692 -section named <literal>collections</literal>.  This will automatically publish
  1.2693 -<emphasis>every</emphasis> repository under the directories you name.  The section
  1.2694 -should look like this:
  1.2695 -</para>
  1.2696 -<programlisting>
  1.2697 -<para>  [collections]
  1.2698 -  /my/root = /my/root
  1.2699 -</para>
  1.2700 -</programlisting>
  1.2701 -<para>Mercurial interprets this by looking at the directory name on the
  1.2702 -<emphasis>right</emphasis> hand side of the <quote><literal>=</literal></quote> sign; finding
  1.2703 -repositories in that directory hierarchy; and using the text on the
  1.2704 -<emphasis>left</emphasis> to strip off matching text from the names it will actually
  1.2705 -list in the web interface.  The remaining component of a path after
  1.2706 -this stripping has occurred is called a <quote>virtual path</quote>.
  1.2707 -</para>
  1.2708 -
  1.2709 -<para>Given the example above, if we have a repository whose local path is
  1.2710 -<filename class="directory">/my/root/this/repo</filename>, the CGI script will strip the leading
  1.2711 -<filename class="directory">/my/root</filename> from the name, and publish the repository with a
  1.2712 -virtual path of <filename class="directory">this/repo</filename>.  If the base URL for our CGI
  1.2713 -script is <ulink url="http://myhostname/ myuser/hgwebdir.cgi">http://myhostname/ myuser/hgwebdir.cgi</ulink>, the complete
  1.2714 -URL for that repository will be
  1.2715 -<ulink url="http://myhostname/ myuser/hgwebdir.cgi/this/repo">http://myhostname/ myuser/hgwebdir.cgi/this/repo</ulink>.
  1.2716 -</para>
  1.2717 -
  1.2718 -<para>If we replace <filename class="directory">/my/root</filename> on the left hand side of this example
  1.2719 -with <filename class="directory">/my</filename>, then <filename role="special">hgwebdir.cgi</filename> will only strip off
  1.2720 -<filename class="directory">/my</filename> from the repository name, and will give us a virtual
  1.2721 -path of <filename class="directory">root/this/repo</filename> instead of <filename class="directory">this/repo</filename>.
  1.2722 -</para>
  1.2723 -
  1.2724 -<para>The <filename role="special">hgwebdir.cgi</filename> script will recursively search each
  1.2725 -directory listed in the <literal>collections</literal> section of its
  1.2726 -configuration file, but it will <literal>not</literal> recurse into the
  1.2727 -repositories it finds.
  1.2728 -</para>
  1.2729 -
  1.2730 -<para>The <literal>collections</literal> mechanism makes it easy to publish many
  1.2731 -repositories in a <quote>fire and forget</quote> manner.  You only need to set up
  1.2732 -the CGI script and configuration file one time.  Afterwards, you can
  1.2733 -publish or unpublish a repository at any time by simply moving it
  1.2734 -into, or out of, the directory hierarchy in which you've configured
  1.2735 -<filename role="special">hgwebdir.cgi</filename> to look.
  1.2736 -</para>
  1.2737 -
  1.2738 -<sect3>
  1.2739 -<title>Explicitly specifying which repositories to publish</title>
  1.2740 -
  1.2741 -<para>In addition to the <literal>collections</literal> mechanism, the
  1.2742 -<filename role="special">hgwebdir.cgi</filename> script allows you to publish a specific list
  1.2743 -of repositories.  To do so, create a <literal>paths</literal> section, with
  1.2744 -contents of the following form.
  1.2745 -</para>
  1.2746 -<programlisting>
  1.2747 -<para>  [paths]
  1.2748 -  repo1 = /my/path/to/some/repo
  1.2749 -  repo2 = /some/path/to/another
  1.2750 -</para>
  1.2751 -</programlisting>
  1.2752 -<para>In this case, the virtual path (the component that will appear in a
  1.2753 -URL) is on the left hand side of each definition, while the path to
  1.2754 -the repository is on the right.  Notice that there does not need to be
  1.2755 -any relationship between the virtual path you choose and the location
  1.2756 -of a repository in your filesystem.
  1.2757 -</para>
  1.2758 -
  1.2759 -<para>If you wish, you can use both the <literal>collections</literal> and
  1.2760 -<literal>paths</literal> mechanisms simultaneously in a single configuration
  1.2761 -file.
  1.2762 -</para>
  1.2763 -
  1.2764 -<note>
  1.2765 -<para>  If multiple repositories have the same virtual path,
  1.2766 -  <filename role="special">hgwebdir.cgi</filename> will not report an error.  Instead, it will
  1.2767 -  behave unpredictably.
  1.2768 -</para>
  1.2769 -</note>
  1.2770 -
  1.2771 -</sect3>
  1.2772 -</sect2>
  1.2773 -<sect2>
  1.2774 -<title>Downloading source archives</title>
  1.2775 -
  1.2776 -<para>Mercurial's web interface lets users download an archive of any
  1.2777 -revision.  This archive will contain a snapshot of the working
  1.2778 -directory as of that revision, but it will not contain a copy of the
  1.2779 -repository data.
  1.2780 -</para>
  1.2781 -
  1.2782 -<para>By default, this feature is not enabled.  To enable it, you'll need to
  1.2783 -add an <envar role="rc-item-web">allow_archive</envar> item to the <literal role="rc-web">web</literal>
  1.2784 -section of your <filename role="special"> /.hgrc</filename>.
  1.2785 -</para>
  1.2786 -
  1.2787 -</sect2>
  1.2788 -<sect2>
  1.2789 -<title>Web configuration options</title>
  1.2790 -
  1.2791 -<para>Mercurial's web interfaces (the <command role="hg-cmd">hg serve</command> command, and the
  1.2792 -<filename role="special">hgweb.cgi</filename> and <filename role="special">hgwebdir.cgi</filename> scripts) have a
  1.2793 -number of configuration options that you can set.  These belong in a
  1.2794 -section named <literal role="rc-web">web</literal>.
  1.2795 -</para>
  1.2796 -<itemizedlist>
  1.2797 -<listitem><para><envar role="rc-item-web">allow_archive</envar>: Determines which (if any) archive
  1.2798 -  download mechanisms Mercurial supports.  If you enable this
  1.2799 -  feature, users of the web interface will be able to download an
  1.2800 -  archive of whatever revision of a repository they are viewing.
  1.2801 -  To enable the archive feature, this item must take the form of a
  1.2802 -  sequence of words drawn from the list below.
  1.2803 -</para>
  1.2804 -</listitem><itemizedlist>
  1.2805 -<listitem><para>  \item <literal>bz2</literal>: A <command>tar</command> archive, compressed using
  1.2806 -    <literal>bzip2</literal> compression.  This has the best compression ratio,
  1.2807 -    but uses the most CPU time on the server.
  1.2808 -  \item <literal>gz</literal>: A <command>tar</command> archive, compressed using
  1.2809 -    <literal>gzip</literal> compression.
  1.2810 -  \item <literal>zip</literal>: A <command>zip</command> archive, compressed using LZW
  1.2811 -    compression.  This format has the worst compression ratio, but is
  1.2812 -    widely used in the Windows world.
  1.2813 -</para>
  1.2814 -</listitem></itemizedlist>
  1.2815 -<para>  If you provide an empty list, or don't have an
  1.2816 -  <envar role="rc-item-web">allow_archive</envar> entry at all, this feature will be
  1.2817 -  disabled.  Here is an example of how to enable all three supported
  1.2818 -  formats.
  1.2819 -</para>
  1.2820 -<programlisting>
  1.2821 -<para>    [web]
  1.2822 -    allow_archive = bz2 gz zip
  1.2823 -</para>
  1.2824 -</programlisting>
  1.2825 -<listitem><para><envar role="rc-item-web">allowpull</envar>: Boolean.  Determines whether the web
  1.2826 -  interface allows remote users to <command role="hg-cmd">hg pull</command> and <command role="hg-cmd">hg clone</command> this
  1.2827 -  repository over HTTP.  If set to <literal>no</literal> or <literal>false</literal>, only
  1.2828 -  the <quote>human-oriented</quote> portion of the web interface is available.
  1.2829 -</para>
  1.2830 -</listitem>
  1.2831 -<listitem><para><envar role="rc-item-web">contact</envar>: String.  A free-form (but preferably
  1.2832 -  brief) string identifying the person or group in charge of the
  1.2833 -  repository.  This often contains the name and email address of a
  1.2834 -  person or mailing list.  It often makes sense to place this entry in
  1.2835 -  a repository's own <filename role="special">.hg/hgrc</filename> file, but it can make sense
  1.2836 -  to use in a global <filename role="special"> /.hgrc</filename>\ if every repository has a single
  1.2837 -  maintainer.
  1.2838 -</para>
  1.2839 -</listitem>
  1.2840 -<listitem><para><envar role="rc-item-web">maxchanges</envar>: Integer.  The default maximum number
  1.2841 -  of changesets to display in a single page of output.
  1.2842 -</para>
  1.2843 -</listitem>
  1.2844 -<listitem><para><envar role="rc-item-web">maxfiles</envar>: Integer.  The default maximum number
  1.2845 -  of modified files to display in a single page of output.
  1.2846 -</para>
  1.2847 -</listitem>
  1.2848 -<listitem><para><envar role="rc-item-web">stripes</envar>: Integer.  If the web interface displays
  1.2849 -  alternating <quote>stripes</quote> to make it easier to visually align rows
  1.2850 -  when you are looking at a table, this number controls the number of
  1.2851 -  rows in each stripe.
  1.2852 -</para>
  1.2853 -</listitem>
  1.2854 -<listitem><para><envar role="rc-item-web">style</envar>: Controls the template Mercurial uses to
  1.2855 -  display the web interface.  Mercurial ships with two web templates,
  1.2856 -  named <literal>default</literal> and <literal>gitweb</literal> (the latter is much more
  1.2857 -  visually attractive).  You can also specify a custom template of
  1.2858 -  your own; see chapter <xref linkend="chap:template"/> for details.  Here, you
  1.2859 -  can see how to enable the <literal>gitweb</literal> style.
  1.2860 -</para>
  1.2861 -</listitem><programlisting>
  1.2862 -<listitem><para>    [web]
  1.2863 -    style = gitweb
  1.2864 -</para>
  1.2865 -</listitem></programlisting>
  1.2866 -</para>
  1.2867 -</listitem>
  1.2868 -<listitem><para><envar role="rc-item-web">templates</envar>: Path.  The directory in which to search
  1.2869 -  for template files.  By default, Mercurial searches in the directory
  1.2870 -  in which it was installed.
  1.2871 -</para>
  1.2872 -</listitem></itemizedlist>
  1.2873 -<para>If you are using <filename role="special">hgwebdir.cgi</filename>, you can place a few
  1.2874 -configuration items in a <literal role="rc-web">web</literal> section of the
  1.2875 -<filename role="special">hgweb.config</filename> file instead of a <filename role="special"> /.hgrc</filename>\ file, for
  1.2876 -convenience.  These items are <envar role="rc-item-web">motd</envar> and
  1.2877 -<envar role="rc-item-web">style</envar>.
  1.2878 -</para>
  1.2879 -
  1.2880 -<sect3>
  1.2881 -<title>Options specific to an individual repository</title>
  1.2882 -
  1.2883 -<para>A few <literal role="rc-web">web</literal> configuration items ought to be placed in a
  1.2884 -repository's local <filename role="special">.hg/hgrc</filename>, rather than a user's or
  1.2885 -global <filename role="special"> /.hgrc</filename>.
  1.2886 -</para>
  1.2887 -<itemizedlist>
  1.2888 -<listitem><para><envar role="rc-item-web">description</envar>: String.  A free-form (but preferably
  1.2889 -  brief) string that describes the contents or purpose of the
  1.2890 -  repository.
  1.2891 -</para>
  1.2892 -</listitem>
  1.2893 -<listitem><para><envar role="rc-item-web">name</envar>: String.  The name to use for the repository
  1.2894 -  in the web interface.  This overrides the default name, which is the
  1.2895 -  last component of the repository's path.
  1.2896 -</para>
  1.2897 -</listitem></itemizedlist>
  1.2898 -
  1.2899 -</sect3>
  1.2900 -<sect3>
  1.2901 -<title>Options specific to the <command role="hg-cmd">hg serve</command> command</title>
  1.2902 -
  1.2903 -<para>Some of the items in the <literal role="rc-web">web</literal> section of a <filename role="special"> /.hgrc</filename>\ file are
  1.2904 -only for use with the <command role="hg-cmd">hg serve</command> command.
  1.2905 -</para>
  1.2906 -<itemizedlist>
  1.2907 -<listitem><para><envar role="rc-item-web">accesslog</envar>: Path.  The name of a file into which to
  1.2908 -  write an access log.  By default, the <command role="hg-cmd">hg serve</command> command writes
  1.2909 -  this information to standard output, not to a file.  Log entries are
  1.2910 -  written in the standard <quote>combined</quote> file format used by almost all
  1.2911 -  web servers.
  1.2912 -</para>
  1.2913 -</listitem>
  1.2914 -<listitem><para><envar role="rc-item-web">address</envar>: String.  The local address on which the
  1.2915 -  server should listen for incoming connections.  By default, the
  1.2916 -  server listens on all addresses.
  1.2917 -</para>
  1.2918 -</listitem>
  1.2919 -<listitem><para><envar role="rc-item-web">errorlog</envar>: Path.  The name of a file into which to
  1.2920 -  write an error log.  By default, the <command role="hg-cmd">hg serve</command> command writes this
  1.2921 -  information to standard error, not to a file.
  1.2922 -</para>
  1.2923 -</listitem>
  1.2924 -<listitem><para><envar role="rc-item-web">ipv6</envar>: Boolean.  Whether to use the IPv6 protocol.
  1.2925 -  By default, IPv6 is not used.
  1.2926 -</para>
  1.2927 -</listitem>
  1.2928 -<listitem><para><envar role="rc-item-web">port</envar>: Integer.  The TCP port number on which the
  1.2929 -  server should listen.  The default port number used is 8000.
  1.2930 -</para>
  1.2931 -</listitem></itemizedlist>
  1.2932 -
  1.2933 -<para>\subsubsection{Choosing the right <filename role="special"> /.hgrc</filename>\ file to add <literal role="rc-web">web</literal>
  1.2934 -  items to}
  1.2935 -</para>
  1.2936 -
  1.2937 -<para>It is important to remember that a web server like Apache or
  1.2938 -<literal>lighttpd</literal> will run under a user ID that is different to yours.
  1.2939 -CGI scripts run by your server, such as <filename role="special">hgweb.cgi</filename>, will
  1.2940 -usually also run under that user ID.
  1.2941 -</para>
  1.2942 -
  1.2943 -<para>If you add <literal role="rc-web">web</literal> items to your own personal <filename role="special"> /.hgrc</filename>\ file, CGI
  1.2944 -scripts won't read that <filename role="special"> /.hgrc</filename>\ file.  Those settings will thus only
  1.2945 -affect the behaviour of the <command role="hg-cmd">hg serve</command> command when you run it.  To
  1.2946 -cause CGI scripts to see your settings, either create a <filename role="special"> /.hgrc</filename>\ file in
  1.2947 -the home directory of the user ID that runs your web server, or add
  1.2948 -those settings to a system-wide <filename role="special"> /.hgrc</filename>\ file.
  1.2949 -</para>
  1.2950 -
  1.2951 -
  1.2952 -</sect3>
  1.2953 -</sect2>
  1.2954 -</sect1>
  1.2955 +    </sect2>
  1.2956 +  </sect1>
  1.2957  </chapter>
  1.2958  
  1.2959  <!--
  1.2960  local variables: 
  1.2961  sgml-parent-document: ("00book.xml" "book" "chapter")
  1.2962  end:
  1.2963 --->
  1.2964 \ No newline at end of file
  1.2965 +-->