1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/en/ch06-collab.xml	Tue Nov 24 22:16:48 2009 -0500
     1.3 @@ -0,0 +1,1565 @@
     1.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5 +
     1.6 +<chapter id="cha:collab">
     1.7 +  <?dbhtml filename="collaborating-with-other-people.html"?>
     1.8 +  <title>Collaborating with other people</title>
     1.9 +
    1.10 +  <para id="x_44a">As a completely decentralised tool, Mercurial doesn't impose
    1.11 +    any policy on how people ought to work with each other.  However,
    1.12 +    if you're new to distributed revision control, it helps to have
    1.13 +    some tools and examples in mind when you're thinking about
    1.14 +    possible workflow models.</para>
    1.15 +
    1.16 +  <sect1>
    1.17 +    <title>Mercurial's web interface</title>
    1.18 +
    1.19 +    <para id="x_44b">Mercurial has a powerful web interface that provides several
    1.20 +      useful capabilities.</para>
    1.21 +
    1.22 +    <para id="x_44c">For interactive use, the web interface lets you browse a
    1.23 +      single repository or a collection of repositories.  You can view
    1.24 +      the history of a repository, examine each change (comments and
    1.25 +      diffs), and view the contents of each directory and file.  You
    1.26 +      can even get a view of history that gives a graphical view of
    1.27 +      the relationships between individual changes and merges.</para>
    1.28 +
    1.29 +    <para id="x_44d">Also for human consumption, the web interface provides
    1.30 +      Atom and RSS feeds of the changes in a repository.  This lets you
    1.31 +      <quote>subscribe</quote> to a repository using your favorite
    1.32 +      feed reader, and be automatically notified of activity in that
    1.33 +      repository as soon as it happens.  I find this capability much
    1.34 +      more convenient than the model of subscribing to a mailing list
    1.35 +      to which notifications are sent, as it requires no additional
    1.36 +      configuration on the part of whoever is serving the
    1.37 +      repository.</para>
    1.38 +
    1.39 +    <para id="x_44e">The web interface also lets remote users clone a repository,
    1.40 +      pull changes from it, and (when the server is configured to
    1.41 +      permit it) push changes back to it.  Mercurial's HTTP tunneling
    1.42 +      protocol aggressively compresses data, so that it works
    1.43 +      efficiently even over low-bandwidth network connections.</para>
    1.44 +
    1.45 +    <para id="x_44f">The easiest way to get started with the web interface is to
    1.46 +      use your web browser to visit an existing repository, such as
    1.47 +      the master Mercurial repository at <ulink
    1.48 +	url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para>
    1.49 +
    1.50 +    <para id="x_450">If you're interested in providing a web interface
    1.51 +      to your own repositories, there are several good ways to do
    1.52 +      this.</para>
    1.53 +
    1.54 +    <para id="x_69d">The easiest and fastest way to get started in an informal
    1.55 +      environment is to use the <command role="hg-cmd">hg
    1.56 +	serve</command> command, which is best suited to short-term
    1.57 +      <quote>lightweight</quote> serving.  See <xref
    1.58 +	linkend="sec:collab:serve"/> below for details of how to use
    1.59 +      this command.</para>
    1.60 +
    1.61 +    <para id="x_69e">For longer-lived repositories that you'd like to
    1.62 +      have permanently available, there are several public hosting
    1.63 +      services available.  Some are free to open source projects,
    1.64 +      while others offer paid commercial hosting.  An up-to-date list
    1.65 +      is available at <ulink
    1.66 +	url="http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting">http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting</ulink>.</para>
    1.67 +
    1.68 +    <para id="x_6a0">If you would prefer to host your own repositories, Mercurial
    1.69 +      has built-in support for several popular hosting technologies,
    1.70 +      most notably CGI (Common Gateway Interface), and WSGI (Web
    1.71 +      Services Gateway Interface).  See <xref
    1.72 +	linkend="sec:collab:cgi"/> for details of CGI and WSGI
    1.73 +      configuration.</para>
    1.74 +  </sect1>
    1.75 +
    1.76 +  <sect1>
    1.77 +    <title>Collaboration models</title>
    1.78 +
    1.79 +    <para id="x_451">With a suitably flexible tool, making decisions about
    1.80 +      workflow is much more of a social engineering challenge than a
    1.81 +      technical one. Mercurial imposes few limitations on how you can
    1.82 +      structure the flow of work in a project, so it's up to you and
    1.83 +      your group to set up and live with a model that matches your own
    1.84 +      particular needs.</para>
    1.85 +
    1.86 +    <sect2>
    1.87 +      <title>Factors to keep in mind</title>
    1.88 +
    1.89 +      <para id="x_452">The most important aspect of any model that you must keep
    1.90 +	in mind is how well it matches the needs and capabilities of
    1.91 +	the people who will be using it.  This might seem
    1.92 +	self-evident; even so, you still can't afford to forget it for
    1.93 +	a moment.</para>
    1.94 +
    1.95 +      <para id="x_453">I once put together a workflow model that seemed to make
    1.96 +	perfect sense to me, but that caused a considerable amount of
    1.97 +	consternation and strife within my development team.  In spite
    1.98 +	of my attempts to explain why we needed a complex set of
    1.99 +	branches, and how changes ought to flow between them, a few
   1.100 +	team members revolted.  Even though they were smart people,
   1.101 +	they didn't want to pay attention to the constraints we were
   1.102 +	operating under, or face the consequences of those constraints
   1.103 +	in the details of the model that I was advocating.</para>
   1.104 +
   1.105 +      <para id="x_454">Don't sweep foreseeable social or technical problems under
   1.106 +	the rug. Whatever scheme you put into effect, you should plan
   1.107 +	for mistakes and problem scenarios.  Consider adding automated
   1.108 +	machinery to prevent, or quickly recover from, trouble that
   1.109 +	you can anticipate.  As an example, if you intend to have a
   1.110 +	branch with not-for-release changes in it, you'd do well to
   1.111 +	think early about the possibility that someone might
   1.112 +	accidentally merge those changes into a release branch.  You
   1.113 +	could avoid this particular problem by writing a hook that
   1.114 +	prevents changes from being merged from an inappropriate
   1.115 +	branch.</para>
   1.116 +    </sect2>
   1.117 +
   1.118 +    <sect2>
   1.119 +      <title>Informal anarchy</title>
   1.120 +
   1.121 +      <para id="x_455">I wouldn't suggest an <quote>anything goes</quote>
   1.122 +	approach as something sustainable, but it's a model that's
   1.123 +	easy to grasp, and it works perfectly well in a few unusual
   1.124 +	situations.</para>
   1.125 +
   1.126 +      <para id="x_456">As one example, many projects have a loose-knit group of
   1.127 +	collaborators who rarely physically meet each other.  Some
   1.128 +	groups like to overcome the isolation of working at a distance
   1.129 +	by organizing occasional <quote>sprints</quote>.  In a sprint,
   1.130 +	a number of people get together in a single location (a
   1.131 +	company's conference room, a hotel meeting room, that kind of
   1.132 +	place) and spend several days more or less locked in there,
   1.133 +	hacking intensely on a handful of projects.</para>
   1.134 +
   1.135 +      <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the
   1.136 +	<command role="hg-cmd">hg serve</command> command, since
   1.137 +	<command role="hg-cmd">hg serve</command> does not require any
   1.138 +	fancy server infrastructure.  You can get started with
   1.139 +	<command role="hg-cmd">hg serve</command> in moments, by
   1.140 +	reading <xref linkend="sec:collab:serve"/> below.  Then simply
   1.141 +	tell the person next to you that you're running a server, send
   1.142 +	the URL to them in an instant message, and you immediately
   1.143 +	have a quick-turnaround way to work together.  They can type
   1.144 +	your URL into their web browser and quickly review your
   1.145 +	changes; or they can pull a bugfix from you and verify it; or
   1.146 +	they can clone a branch containing a new feature and try it
   1.147 +	out.</para>
   1.148 +
   1.149 +      <para id="x_458">The charm, and the problem, with doing things
   1.150 +	in an ad hoc fashion like this is that only people who know
   1.151 +	about your changes, and where they are, can see them.  Such an
   1.152 +	informal approach simply doesn't scale beyond a handful
   1.153 +	people, because each individual needs to know about
   1.154 +	<emphasis>n</emphasis> different repositories to pull
   1.155 +	from.</para>
   1.156 +    </sect2>
   1.157 +
   1.158 +    <sect2>
   1.159 +      <title>A single central repository</title>
   1.160 +
   1.161 +      <para id="x_459">For smaller projects migrating from a centralised revision
   1.162 +	control tool, perhaps the easiest way to get started is to
   1.163 +	have changes flow through a single shared central repository.
   1.164 +	This is also the most common <quote>building block</quote> for
   1.165 +	more ambitious workflow schemes.</para>
   1.166 +
   1.167 +      <para id="x_45a">Contributors start by cloning a copy of this repository.
   1.168 +	They can pull changes from it whenever they need to, and some
   1.169 +	(perhaps all) developers have permission to push a change back
   1.170 +	when they're ready for other people to see it.</para>
   1.171 +
   1.172 +      <para id="x_45b">Under this model, it can still often make sense for people
   1.173 +	to pull changes directly from each other, without going
   1.174 +	through the central repository.  Consider a case in which I
   1.175 +	have a tentative bug fix, but I am worried that if I were to
   1.176 +	publish it to the central repository, it might subsequently
   1.177 +	break everyone else's trees as they pull it.  To reduce the
   1.178 +	potential for damage, I can ask you to clone my repository
   1.179 +	into a temporary repository of your own and test it.  This
   1.180 +	lets us put off publishing the potentially unsafe change until
   1.181 +	it has had a little testing.</para>
   1.182 +
   1.183 +      <para id="x_45c">If a team is hosting its own repository in this
   1.184 +	kind of scenario, people will usually use the
   1.185 +	<command>ssh</command> protocol to securely push changes to
   1.186 +	the central repository, as documented in <xref
   1.187 +	  linkend="sec:collab:ssh"/>.  It's also usual to publish a
   1.188 +	read-only copy of the repository over HTTP, as in
   1.189 +	<xref linkend="sec:collab:cgi"/>. Publishing over HTTP
   1.190 +	satisfies the needs of people who don't have push access, and
   1.191 +	those who want to use web browsers to browse the repository's
   1.192 +	history.</para>
   1.193 +    </sect2>
   1.194 +
   1.195 +    <sect2>
   1.196 +      <title>A hosted central repository</title>
   1.197 +
   1.198 +      <para id="x_6a1">A wonderful thing about public hosting services like
   1.199 +	<ulink url="http://bitbucket.org/">Bitbucket</ulink> is that
   1.200 +	not only do they handle the fiddly server configuration
   1.201 +	details, such as user accounts, authentication, and secure
   1.202 +	wire protocols, they provide additional infrastructure to make
   1.203 +	this model work well.</para>
   1.204 +
   1.205 +      <para id="x_6a2">For instance, a well-engineered hosting service will let
   1.206 +	people clone their own copies of a repository with a single
   1.207 +	click.  This lets people work in separate spaces and share
   1.208 +	their changes when they're ready.</para>
   1.209 +
   1.210 +      <para id="x_6a3">In addition, a good hosting service will let people
   1.211 +	communicate with each other, for instance to say <quote>there
   1.212 +	  are changes ready for you to review in this
   1.213 +	  tree</quote>.</para>
   1.214 +    </sect2>
   1.215 +
   1.216 +    <sect2>
   1.217 +      <title>Working with multiple branches</title>
   1.218 +
   1.219 +      <para id="x_45d">Projects of any significant size naturally tend to make
   1.220 +	progress on several fronts simultaneously.  In the case of
   1.221 +	software, it's common for a project to go through periodic
   1.222 +	official releases.  A release might then go into
   1.223 +	<quote>maintenance mode</quote> for a while after its first
   1.224 +	publication; maintenance releases tend to contain only bug
   1.225 +	fixes, not new features.  In parallel with these maintenance
   1.226 +	releases, one or more future releases may be under
   1.227 +	development.  People normally use the word
   1.228 +	<quote>branch</quote> to refer to one of these many slightly
   1.229 +	different directions in which development is
   1.230 +	proceeding.</para>
   1.231 +
   1.232 +      <para id="x_45e">Mercurial is particularly well suited to managing a number
   1.233 +	of simultaneous, but not identical, branches.  Each
   1.234 +	<quote>development direction</quote> can live in its own
   1.235 +	central repository, and you can merge changes from one to
   1.236 +	another as the need arises.  Because repositories are
   1.237 +	independent of each other, unstable changes in a development
   1.238 +	branch will never affect a stable branch unless someone
   1.239 +	explicitly merges those changes into the stable branch.</para>
   1.240 +
   1.241 +      <para id="x_45f">Here's an example of how this can work in practice.  Let's
   1.242 +	say you have one <quote>main branch</quote> on a central
   1.243 +	server.</para>
   1.244 +
   1.245 +      &interaction.branching.init;
   1.246 +
   1.247 +      <para id="x_460">People clone it, make changes locally, test them, and push
   1.248 +	them back.</para>
   1.249 +
   1.250 +      <para id="x_461">Once the main branch reaches a release milestone, you can
   1.251 +	use the <command role="hg-cmd">hg tag</command> command to
   1.252 +	give a permanent name to the milestone revision.</para>
   1.253 +
   1.254 +	&interaction.branching.tag;
   1.255 +
   1.256 +      <para id="x_462">Let's say some ongoing
   1.257 +	development occurs on the main branch.</para>
   1.258 +
   1.259 +      &interaction.branching.main;
   1.260 +
   1.261 +      <para id="x_463">Using the tag that was recorded at the milestone, people
   1.262 +	who clone that repository at any time in the future can use
   1.263 +	<command role="hg-cmd">hg update</command> to get a copy of
   1.264 +	the working directory exactly as it was when that tagged
   1.265 +	revision was committed.</para>
   1.266 +
   1.267 +      &interaction.branching.update;
   1.268 +
   1.269 +      <para id="x_464">In addition, immediately after the main branch is tagged,
   1.270 +	we can then clone the main branch on the server to a new
   1.271 +	<quote>stable</quote> branch, also on the server.</para>
   1.272 +
   1.273 +      &interaction.branching.clone;
   1.274 +
   1.275 +      <para id="x_465">If we need to make a change to the stable
   1.276 +	branch, we can then clone <emphasis>that</emphasis>
   1.277 +	repository, make our changes, commit, and push our changes
   1.278 +	back there.</para>
   1.279 +
   1.280 +      &interaction.branching.stable;
   1.281 +
   1.282 +      <para id="x_466">Because Mercurial repositories are independent, and
   1.283 +	Mercurial doesn't move changes around automatically, the
   1.284 +	stable and main branches are <emphasis>isolated</emphasis>
   1.285 +	from each other.  The changes that we made on the main branch
   1.286 +	don't <quote>leak</quote> to the stable branch, and vice
   1.287 +	versa.</para>
   1.288 +
   1.289 +      <para id="x_467">We'll often want all of our bugfixes on the stable
   1.290 +	branch to show up on the main branch, too.  Rather than
   1.291 +	rewrite a bugfix on the main branch, we can simply pull and
   1.292 +	merge changes from the stable to the main branch, and
   1.293 +	Mercurial will bring those bugfixes in for us.</para>
   1.294 +
   1.295 +      &interaction.branching.merge;
   1.296 +
   1.297 +      <para id="x_468">The main branch will still contain changes that
   1.298 +	are not on the stable branch, but it will also contain all of
   1.299 +	the bugfixes from the stable branch.  The stable branch
   1.300 +	remains unaffected by these changes, since changes are only
   1.301 +	flowing from the stable to the main branch, and not the other
   1.302 +	way.</para>
   1.303 +    </sect2>
   1.304 +
   1.305 +    <sect2>
   1.306 +      <title>Feature branches</title>
   1.307 +
   1.308 +      <para id="x_469">For larger projects, an effective way to manage change is
   1.309 +	to break up a team into smaller groups.  Each group has a
   1.310 +	shared branch of its own, cloned from a single
   1.311 +	<quote>master</quote> branch used by the entire project.
   1.312 +	People working on an individual branch are typically quite
   1.313 +	isolated from developments on other branches.</para>
   1.314 +
   1.315 +      <figure id="fig:collab:feature-branches">
   1.316 +	<title>Feature branches</title>
   1.317 +	<mediaobject>
   1.318 +	  <imageobject><imagedata width="100%" fileref="figs/feature-branches.png"/></imageobject>
   1.319 +	  <textobject><phrase>XXX add text</phrase></textobject>
   1.320 +	</mediaobject>
   1.321 +      </figure>
   1.322 +
   1.323 +      <para id="x_46b">When a particular feature is deemed to be in suitable
   1.324 +	shape, someone on that feature team pulls and merges from the
   1.325 +	master branch into the feature branch, then pushes back up to
   1.326 +	the master branch.</para>
   1.327 +    </sect2>
   1.328 +
   1.329 +    <sect2>
   1.330 +      <title>The release train</title>
   1.331 +
   1.332 +      <para id="x_46c">Some projects are organized on a <quote>train</quote>
   1.333 +	basis: a release is scheduled to happen every few months, and
   1.334 +	whatever features are ready when the <quote>train</quote> is
   1.335 +	ready to leave are allowed in.</para>
   1.336 +
   1.337 +      <para id="x_46d">This model resembles working with feature branches.  The
   1.338 +	difference is that when a feature branch misses a train,
   1.339 +	someone on the feature team pulls and merges the changes that
   1.340 +	went out on that train release into the feature branch, and
   1.341 +	the team continues its work on top of that release so that
   1.342 +	their feature can make the next release.</para>
   1.343 +    </sect2>
   1.344 +
   1.345 +    <sect2>
   1.346 +      <title>The Linux kernel model</title>
   1.347 +
   1.348 +      <para id="x_46e">The development of the Linux kernel has a shallow
   1.349 +	hierarchical structure, surrounded by a cloud of apparent
   1.350 +	chaos.  Because most Linux developers use
   1.351 +	<command>git</command>, a distributed revision control tool
   1.352 +	with capabilities similar to Mercurial, it's useful to
   1.353 +	describe the way work flows in that environment; if you like
   1.354 +	the ideas, the approach translates well across tools.</para>
   1.355 +
   1.356 +      <para id="x_46f">At the center of the community sits Linus Torvalds, the
   1.357 +	creator of Linux.  He publishes a single source repository
   1.358 +	that is considered the <quote>authoritative</quote> current
   1.359 +	tree by the entire developer community. Anyone can clone
   1.360 +	Linus's tree, but he is very choosy about whose trees he pulls
   1.361 +	from.</para>
   1.362 +
   1.363 +      <para id="x_470">Linus has a number of <quote>trusted lieutenants</quote>.
   1.364 +	As a general rule, he pulls whatever changes they publish, in
   1.365 +	most cases without even reviewing those changes.  Some of
   1.366 +	those lieutenants are generally agreed to be
   1.367 +	<quote>maintainers</quote>, responsible for specific
   1.368 +	subsystems within the kernel.  If a random kernel hacker wants
   1.369 +	to make a change to a subsystem that they want to end up in
   1.370 +	Linus's tree, they must find out who the subsystem's
   1.371 +	maintainer is, and ask that maintainer to take their change.
   1.372 +	If the maintainer reviews their changes and agrees to take
   1.373 +	them, they'll pass them along to Linus in due course.</para>
   1.374 +
   1.375 +      <para id="x_471">Individual lieutenants have their own approaches to
   1.376 +	reviewing, accepting, and publishing changes; and for deciding
   1.377 +	when to feed them to Linus.  In addition, there are several
   1.378 +	well known branches that people use for different purposes.
   1.379 +	For example, a few people maintain <quote>stable</quote>
   1.380 +	repositories of older versions of the kernel, to which they
   1.381 +	apply critical fixes as needed.  Some maintainers publish
   1.382 +	multiple trees: one for experimental changes; one for changes
   1.383 +	that they are about to feed upstream; and so on.  Others just
   1.384 +	publish a single tree.</para>
   1.385 +
   1.386 +      <para id="x_472">This model has two notable features.  The first is that
   1.387 +	it's <quote>pull only</quote>.  You have to ask, convince, or
   1.388 +	beg another developer to take a change from you, because there
   1.389 +	are almost no trees to which more than one person can push,
   1.390 +	and there's no way to push changes into a tree that someone
   1.391 +	else controls.</para>
   1.392 +
   1.393 +      <para id="x_473">The second is that it's based on reputation and acclaim.
   1.394 +	If you're an unknown, Linus will probably ignore changes from
   1.395 +	you without even responding.  But a subsystem maintainer will
   1.396 +	probably review them, and will likely take them if they pass
   1.397 +	their criteria for suitability. The more <quote>good</quote>
   1.398 +	changes you contribute to a maintainer, the more likely they
   1.399 +	are to trust your judgment and accept your changes.  If you're
   1.400 +	well-known and maintain a long-lived branch for something
   1.401 +	Linus hasn't yet accepted, people with similar interests may
   1.402 +	pull your changes regularly to keep up with your work.</para>
   1.403 +
   1.404 +      <para id="x_474">Reputation and acclaim don't necessarily cross subsystem
   1.405 +	or <quote>people</quote> boundaries.  If you're a respected
   1.406 +	but specialised storage hacker, and you try to fix a
   1.407 +	networking bug, that change will receive a level of scrutiny
   1.408 +	from a network maintainer comparable to a change from a
   1.409 +	complete stranger.</para>
   1.410 +
   1.411 +      <para id="x_475">To people who come from more orderly project backgrounds,
   1.412 +	the comparatively chaotic Linux kernel development process
   1.413 +	often seems completely insane.  It's subject to the whims of
   1.414 +	individuals; people make sweeping changes whenever they deem
   1.415 +	it appropriate; and the pace of development is astounding.
   1.416 +	And yet Linux is a highly successful, well-regarded piece of
   1.417 +	software.</para>
   1.418 +    </sect2>
   1.419 +
   1.420 +    <sect2>
   1.421 +      <title>Pull-only versus shared-push collaboration</title>
   1.422 +
   1.423 +      <para id="x_476">A perpetual source of heat in the open source community is
   1.424 +	whether a development model in which people only ever pull
   1.425 +	changes from others is <quote>better than</quote> one in which
   1.426 +	multiple people can push changes to a shared
   1.427 +	repository.</para>
   1.428 +
   1.429 +      <para id="x_477">Typically, the backers of the shared-push model use tools
   1.430 +	that actively enforce this approach.  If you're using a
   1.431 +	centralised revision control tool such as Subversion, there's
   1.432 +	no way to make a choice over which model you'll use: the tool
   1.433 +	gives you shared-push, and if you want to do anything else,
   1.434 +	you'll have to roll your own approach on top (such as applying
   1.435 +	a patch by hand).</para>
   1.436 +
   1.437 +      <para id="x_478">A good distributed revision control tool will
   1.438 +	support both models.  You and your collaborators can then
   1.439 +	structure how you work together based on your own needs and
   1.440 +	preferences, not on what contortions your tools force you
   1.441 +	into.</para>
   1.442 +    </sect2>
   1.443 +    <sect2>
   1.444 +      <title>Where collaboration meets branch management</title>
   1.445 +
   1.446 +      <para id="x_479">Once you and your team set up some shared
   1.447 +	repositories and start propagating changes back and forth
   1.448 +	between local and shared repos, you begin to face a related,
   1.449 +	but slightly different challenge: that of managing the
   1.450 +	multiple directions in which your team may be moving at once.
   1.451 +	Even though this subject is intimately related to how your
   1.452 +	team collaborates, it's dense enough to merit treatment of its
   1.453 +	own, in <xref linkend="chap:branch"/>.</para>
   1.454 +    </sect2>
   1.455 +  </sect1>
   1.456 +
   1.457 +  <sect1>
   1.458 +    <title>The technical side of sharing</title>
   1.459 +
   1.460 +    <para id="x_47a">The remainder of this chapter is devoted to the question of
   1.461 +      sharing changes with your collaborators.</para>
   1.462 +  </sect1>
   1.463 +
   1.464 +  <sect1 id="sec:collab:serve">
   1.465 +    <title>Informal sharing with <command role="hg-cmd">hg
   1.466 +	serve</command></title>
   1.467 +
   1.468 +    <para id="x_47b">Mercurial's <command role="hg-cmd">hg serve</command>
   1.469 +      command is wonderfully suited to small, tight-knit, and
   1.470 +      fast-paced group environments.  It also provides a great way to
   1.471 +      get a feel for using Mercurial commands over a network.</para>
   1.472 +
   1.473 +    <para id="x_47c">Run <command role="hg-cmd">hg serve</command> inside a
   1.474 +      repository, and in under a second it will bring up a specialised
   1.475 +      HTTP server; this will accept connections from any client, and
   1.476 +      serve up data for that repository until you terminate it.
   1.477 +      Anyone who knows the URL of the server you just started, and can
   1.478 +      talk to your computer over the network, can then use a web
   1.479 +      browser or Mercurial to read data from that repository.  A URL
   1.480 +      for a <command role="hg-cmd">hg serve</command> instance running
   1.481 +      on a laptop is likely to look something like
   1.482 +      <literal>http://my-laptop.local:8000/</literal>.</para>
   1.483 +
   1.484 +    <para id="x_47d">The <command role="hg-cmd">hg serve</command> command is
   1.485 +      <emphasis>not</emphasis> a general-purpose web server. It can do
   1.486 +      only two things:</para>
   1.487 +    <itemizedlist>
   1.488 +      <listitem><para id="x_47e">Allow people to browse the history of the
   1.489 +	  repository it's serving, from their normal web
   1.490 +	  browsers.</para>
   1.491 +      </listitem>
   1.492 +      <listitem><para id="x_47f">Speak Mercurial's wire protocol, so that people
   1.493 +	  can <command role="hg-cmd">hg clone</command> or <command
   1.494 +	    role="hg-cmd">hg pull</command> changes from that
   1.495 +	  repository.</para>
   1.496 +      </listitem></itemizedlist>
   1.497 +    <para id="x_480">In particular, <command role="hg-cmd">hg serve</command>
   1.498 +      won't allow remote users to <emphasis>modify</emphasis> your
   1.499 +      repository.  It's intended for read-only use.</para>
   1.500 +
   1.501 +    <para id="x_481">If you're getting started with Mercurial, there's nothing to
   1.502 +      prevent you from using <command role="hg-cmd">hg serve</command>
   1.503 +      to serve up a repository on your own computer, then use commands
   1.504 +      like <command role="hg-cmd">hg clone</command>, <command
   1.505 +	role="hg-cmd">hg incoming</command>, and so on to talk to that
   1.506 +      server as if the repository was hosted remotely. This can help
   1.507 +      you to quickly get acquainted with using commands on
   1.508 +      network-hosted repositories.</para>
   1.509 +
   1.510 +    <sect2>
   1.511 +      <title>A few things to keep in mind</title>
   1.512 +
   1.513 +      <para id="x_482">Because it provides unauthenticated read access to all
   1.514 +	clients, you should only use <command role="hg-cmd">hg
   1.515 +	  serve</command> in an environment where you either don't
   1.516 +	care, or have complete control over, who can access your
   1.517 +	network and pull data from your repository.</para>
   1.518 +
   1.519 +      <para id="x_483">The <command role="hg-cmd">hg serve</command> command
   1.520 +	knows nothing about any firewall software you might have
   1.521 +	installed on your system or network.  It cannot detect or
   1.522 +	control your firewall software.  If other people are unable to
   1.523 +	talk to a running <command role="hg-cmd">hg serve</command>
   1.524 +	instance, the second thing you should do
   1.525 +	(<emphasis>after</emphasis> you make sure that they're using
   1.526 +	the correct URL) is check your firewall configuration.</para>
   1.527 +
   1.528 +      <para id="x_484">By default, <command role="hg-cmd">hg serve</command>
   1.529 +	listens for incoming connections on port 8000.  If another
   1.530 +	process is already listening on the port you want to use, you
   1.531 +	can specify a different port to listen on using the <option
   1.532 +	  role="hg-opt-serve">-p</option> option.</para>
   1.533 +
   1.534 +      <para id="x_485">Normally, when <command role="hg-cmd">hg serve</command>
   1.535 +	starts, it prints no output, which can be a bit unnerving.  If
   1.536 +	you'd like to confirm that it is indeed running correctly, and
   1.537 +	find out what URL you should send to your collaborators, start
   1.538 +	it with the <option role="hg-opt-global">-v</option>
   1.539 +	option.</para>
   1.540 +    </sect2>
   1.541 +  </sect1>
   1.542 +
   1.543 +  <sect1 id="sec:collab:ssh">
   1.544 +    <title>Using the Secure Shell (ssh) protocol</title>
   1.545 +
   1.546 +    <para id="x_486">You can pull and push changes securely over a network
   1.547 +      connection using the Secure Shell (<literal>ssh</literal>)
   1.548 +      protocol.  To use this successfully, you may have to do a little
   1.549 +      bit of configuration on the client or server sides.</para>
   1.550 +
   1.551 +    <para id="x_487">If you're not familiar with ssh, it's the name of
   1.552 +      both a command and a network protocol that let you securely
   1.553 +      communicate with another computer.  To use it with Mercurial,
   1.554 +      you'll be setting up one or more user accounts on a server so
   1.555 +      that remote users can log in and execute commands.</para>
   1.556 +
   1.557 +    <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll
   1.558 +      probably find some of the material that follows to be elementary
   1.559 +      in nature.)</para>
   1.560 +
   1.561 +    <sect2>
   1.562 +      <title>How to read and write ssh URLs</title>
   1.563 +
   1.564 +      <para id="x_489">An ssh URL tends to look like this:</para>
   1.565 +      <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting>
   1.566 +      <orderedlist>
   1.567 +	<listitem><para id="x_48a">The <quote><literal>ssh://</literal></quote>
   1.568 +	    part tells Mercurial to use the ssh protocol.</para>
   1.569 +	</listitem>
   1.570 +	<listitem><para id="x_48b">The <quote><literal>bos@</literal></quote>
   1.571 +	    component indicates what username to log into the server
   1.572 +	    as.  You can leave this out if the remote username is the
   1.573 +	    same as your local username.</para>
   1.574 +	</listitem>
   1.575 +	<listitem><para id="x_48c">The
   1.576 +	    <quote><literal>hg.serpentine.com</literal></quote> gives
   1.577 +	    the hostname of the server to log into.</para>
   1.578 +	</listitem>
   1.579 +	<listitem><para id="x_48d">The <quote>:22</quote> identifies the port
   1.580 +	    number to connect to the server on.  The default port is
   1.581 +	    22, so you only need to specify a colon and port number if
   1.582 +	    you're <emphasis>not</emphasis> using port 22.</para>
   1.583 +	</listitem>
   1.584 +	<listitem><para id="x_48e">The remainder of the URL is the local path to
   1.585 +	    the repository on the server.</para>
   1.586 +	</listitem></orderedlist>
   1.587 +
   1.588 +      <para id="x_48f">There's plenty of scope for confusion with the path
   1.589 +	component of ssh URLs, as there is no standard way for tools
   1.590 +	to interpret it.  Some programs behave differently than others
   1.591 +	when dealing with these paths. This isn't an ideal situation,
   1.592 +	but it's unlikely to change.  Please read the following
   1.593 +	paragraphs carefully.</para>
   1.594 +
   1.595 +      <para id="x_490">Mercurial treats the path to a repository on the server as
   1.596 +	relative to the remote user's home directory.  For example, if
   1.597 +	user <literal>foo</literal> on the server has a home directory
   1.598 +	of <filename class="directory">/home/foo</filename>, then an
   1.599 +	ssh URL that contains a path component of <filename
   1.600 +	  class="directory">bar</filename> <emphasis>really</emphasis>
   1.601 +	refers to the directory <filename
   1.602 +	  class="directory">/home/foo/bar</filename>.</para>
   1.603 +
   1.604 +      <para id="x_491">If you want to specify a path relative to another user's
   1.605 +	home directory, you can use a path that starts with a tilde
   1.606 +	character followed by the user's name (let's call them
   1.607 +	<literal>otheruser</literal>), like this.</para>
   1.608 +      <programlisting>ssh://server/~otheruser/hg/repo</programlisting>
   1.609 +
   1.610 +      <para id="x_492">And if you really want to specify an
   1.611 +	<emphasis>absolute</emphasis> path on the server, begin the
   1.612 +	path component with two slashes, as in this example.</para>
   1.613 +      <programlisting>ssh://server//absolute/path</programlisting>
   1.614 +    </sect2>
   1.615 +
   1.616 +    <sect2>
   1.617 +      <title>Finding an ssh client for your system</title>
   1.618 +
   1.619 +      <para id="x_493">Almost every Unix-like system comes with OpenSSH
   1.620 +	preinstalled.  If you're using such a system, run
   1.621 +	<literal>which ssh</literal> to find out if the
   1.622 +	<command>ssh</command> command is installed (it's usually in
   1.623 +	<filename class="directory">/usr/bin</filename>).  In the
   1.624 +	unlikely event that it isn't present, take a look at your
   1.625 +	system documentation to figure out how to install it.</para>
   1.626 +
   1.627 +      <para id="x_494">On Windows, the TortoiseHg package is bundled
   1.628 +	with a version of Simon Tatham's excellent
   1.629 +	<command>plink</command> command, and you should not need to
   1.630 +	do any further configuration.</para>
   1.631 +    </sect2>
   1.632 +
   1.633 +    <sect2>
   1.634 +      <title>Generating a key pair</title>
   1.635 +
   1.636 +      <para id="x_499">To avoid the need to repetitively type a
   1.637 +	password every time you need to use your ssh client, I
   1.638 +	recommend generating a key pair.</para>
   1.639 +
   1.640 +      <tip>
   1.641 +	<title>Key pairs are not mandatory</title>
   1.642 +
   1.643 +	<para id="x_6a4">Mercurial knows nothing about ssh authentication or key
   1.644 +	  pairs.  You can, if you like, safely ignore this section and
   1.645 +	  the one that follows until you grow tired of repeatedly
   1.646 +	  typing ssh passwords.</para>
   1.647 +      </tip>
   1.648 +
   1.649 +      <itemizedlist>
   1.650 +	<listitem>
   1.651 +	  <para id="x_6a5">On a Unix-like system, the
   1.652 +	    <command>ssh-keygen</command> command will do the
   1.653 +	    trick.</para>
   1.654 +	  <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need
   1.655 +	    to download a command named <command>puttygen</command>
   1.656 +	    from <ulink
   1.657 +	      url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the 
   1.658 +	      PuTTY web site</ulink> to generate a key pair.  See
   1.659 +	    <ulink
   1.660 +	      url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the 
   1.661 +	      <command>puttygen</command> documentation</ulink> for
   1.662 +	    details of how use the command.</para>
   1.663 +	</listitem>
   1.664 +      </itemizedlist>
   1.665 +
   1.666 +      <para id="x_49a">When you generate a key pair, it's usually
   1.667 +	<emphasis>highly</emphasis> advisable to protect it with a
   1.668 +	passphrase.  (The only time that you might not want to do this
   1.669 +	is when you're using the ssh protocol for automated tasks on a
   1.670 +	secure network.)</para>
   1.671 +
   1.672 +      <para id="x_49b">Simply generating a key pair isn't enough, however.
   1.673 +	You'll need to add the public key to the set of authorised
   1.674 +	keys for whatever user you're logging in remotely as.  For
   1.675 +	servers using OpenSSH (the vast majority), this will mean
   1.676 +	adding the public key to a list in a file called <filename
   1.677 +	  role="special">authorized_keys</filename> in their <filename
   1.678 +	  role="special" class="directory">.ssh</filename>
   1.679 +	directory.</para>
   1.680 +
   1.681 +      <para id="x_49c">On a Unix-like system, your public key will have a
   1.682 +	<filename>.pub</filename> extension.  If you're using
   1.683 +	<command>puttygen</command> on Windows, you can save the
   1.684 +	public key to a file of your choosing, or paste it from the
   1.685 +	window it's displayed in straight into the <filename
   1.686 +	  role="special">authorized_keys</filename> file.</para>
   1.687 +    </sect2>
   1.688 +    <sect2>
   1.689 +      <title>Using an authentication agent</title>
   1.690 +
   1.691 +      <para id="x_49d">An authentication agent is a daemon that stores
   1.692 +	passphrases in memory (so it will forget passphrases if you
   1.693 +	log out and log back in again). An ssh client will notice if
   1.694 +	it's running, and query it for a passphrase.  If there's no
   1.695 +	authentication agent running, or the agent doesn't store the
   1.696 +	necessary passphrase, you'll have to type your passphrase
   1.697 +	every time Mercurial tries to communicate with a server on
   1.698 +	your behalf (e.g. whenever you pull or push changes).</para>
   1.699 +
   1.700 +      <para id="x_49e">The downside of storing passphrases in an agent is that
   1.701 +	it's possible for a well-prepared attacker to recover the
   1.702 +	plain text of your passphrases, in some cases even if your
   1.703 +	system has been power-cycled. You should make your own
   1.704 +	judgment as to whether this is an acceptable risk.  It
   1.705 +	certainly saves a lot of repeated typing.</para>
   1.706 +
   1.707 +      <itemizedlist>
   1.708 +	<listitem>
   1.709 +	  <para id="x_49f">On Unix-like systems, the agent is called
   1.710 +	    <command>ssh-agent</command>, and it's often run
   1.711 +	    automatically for you when you log in.  You'll need to use
   1.712 +	    the <command>ssh-add</command> command to add passphrases
   1.713 +	    to the agent's store.</para>
   1.714 +	</listitem>
   1.715 +	<listitem>
   1.716 +	  <para id="x_6a7">On Windows, if you're using TortoiseHg, the
   1.717 +	    <command>pageant</command> command acts as the agent.  As
   1.718 +	    with <command>puttygen</command>, you'll need to <ulink
   1.719 +	      url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download 
   1.720 +	      <command>pageant</command></ulink> from the PuTTY web
   1.721 +	    site and read <ulink
   1.722 +	      url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its 
   1.723 +	      documentation</ulink>.  The <command>pageant</command>
   1.724 +	    command adds an icon to your system tray that will let you
   1.725 +	    manage stored passphrases.</para>
   1.726 +	</listitem>
   1.727 +      </itemizedlist>
   1.728 +    </sect2>
   1.729 +
   1.730 +    <sect2>
   1.731 +      <title>Configuring the server side properly</title>
   1.732 +
   1.733 +      <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
   1.734 +	a variety of things can go wrong.  Add Mercurial
   1.735 +	on top, and there's plenty more scope for head-scratching.
   1.736 +	Most of these potential problems occur on the server side, not
   1.737 +	the client side.  The good news is that once you've gotten a
   1.738 +	configuration working, it will usually continue to work
   1.739 +	indefinitely.</para>
   1.740 +
   1.741 +      <para id="x_4a1">Before you try using Mercurial to talk to an ssh server,
   1.742 +	it's best to make sure that you can use the normal
   1.743 +	<command>ssh</command> or <command>putty</command> command to
   1.744 +	talk to the server first.  If you run into problems with using
   1.745 +	these commands directly, Mercurial surely won't work.  Worse,
   1.746 +	it will obscure the underlying problem.  Any time you want to
   1.747 +	debug ssh-related Mercurial problems, you should drop back to
   1.748 +	making sure that plain ssh client commands work first,
   1.749 +	<emphasis>before</emphasis> you worry about whether there's a
   1.750 +	problem with Mercurial.</para>
   1.751 +
   1.752 +      <para id="x_4a2">The first thing to be sure of on the server side is that
   1.753 +	you can actually log in from another machine at all.  If you
   1.754 +	can't use <command>ssh</command> or <command>putty</command>
   1.755 +	to log in, the error message you get may give you a few hints
   1.756 +	as to what's wrong.  The most common problems are as
   1.757 +	follows.</para>
   1.758 +      <itemizedlist>
   1.759 +	<listitem><para id="x_4a3">If you get a <quote>connection refused</quote>
   1.760 +	    error, either there isn't an SSH daemon running on the
   1.761 +	    server at all, or it's inaccessible due to firewall
   1.762 +	    configuration.</para>
   1.763 +	</listitem>
   1.764 +	<listitem><para id="x_4a4">If you get a <quote>no route to host</quote>
   1.765 +	    error, you either have an incorrect address for the server
   1.766 +	    or a seriously locked down firewall that won't admit its
   1.767 +	    existence at all.</para>
   1.768 +	</listitem>
   1.769 +	<listitem><para id="x_4a5">If you get a <quote>permission denied</quote>
   1.770 +	    error, you may have mistyped the username on the server,
   1.771 +	    or you could have mistyped your key's passphrase or the
   1.772 +	    remote user's password.</para>
   1.773 +	</listitem></itemizedlist>
   1.774 +      <para id="x_4a6">In summary, if you're having trouble talking to the
   1.775 +	server's ssh daemon, first make sure that one is running at
   1.776 +	all.  On many systems it will be installed, but disabled, by
   1.777 +	default.  Once you're done with this step, you should then
   1.778 +	check that the server's firewall is configured to allow
   1.779 +	incoming connections on the port the ssh daemon is listening
   1.780 +	on (usually 22).  Don't worry about more exotic possibilities
   1.781 +	for misconfiguration until you've checked these two
   1.782 +	first.</para>
   1.783 +
   1.784 +      <para id="x_4a7">If you're using an authentication agent on the client side
   1.785 +	to store passphrases for your keys, you ought to be able to
   1.786 +	log into the server without being prompted for a passphrase or
   1.787 +	a password.  If you're prompted for a passphrase, there are a
   1.788 +	few possible culprits.</para>
   1.789 +      <itemizedlist>
   1.790 +	<listitem><para id="x_4a8">You might have forgotten to use
   1.791 +	    <command>ssh-add</command> or <command>pageant</command>
   1.792 +	    to store the passphrase.</para>
   1.793 +	</listitem>
   1.794 +	<listitem><para id="x_4a9">You might have stored the passphrase for the
   1.795 +	    wrong key.</para>
   1.796 +	</listitem></itemizedlist>
   1.797 +      <para id="x_4aa">If you're being prompted for the remote user's password,
   1.798 +	there are another few possible problems to check.</para>
   1.799 +      <itemizedlist>
   1.800 +	<listitem><para id="x_4ab">Either the user's home directory or their
   1.801 +	    <filename role="special" class="directory">.ssh</filename>
   1.802 +	    directory might have excessively liberal permissions.  As
   1.803 +	    a result, the ssh daemon will not trust or read their
   1.804 +	    <filename role="special">authorized_keys</filename> file.
   1.805 +	    For example, a group-writable home or <filename
   1.806 +	      role="special" class="directory">.ssh</filename>
   1.807 +	    directory will often cause this symptom.</para>
   1.808 +	</listitem>
   1.809 +	<listitem><para id="x_4ac">The user's <filename
   1.810 +	      role="special">authorized_keys</filename> file may have
   1.811 +	    a problem. If anyone other than the user owns or can write
   1.812 +	    to that file, the ssh daemon will not trust or read
   1.813 +	    it.</para>
   1.814 +	</listitem></itemizedlist>
   1.815 +
   1.816 +      <para id="x_4ad">In the ideal world, you should be able to run the
   1.817 +	following command successfully, and it should print exactly
   1.818 +	one line of output, the current date and time.</para>
   1.819 +      <programlisting>ssh myserver date</programlisting>
   1.820 +
   1.821 +      <para id="x_4ae">If, on your server, you have login scripts that print
   1.822 +	banners or other junk even when running non-interactive
   1.823 +	commands like this, you should fix them before you continue,
   1.824 +	so that they only print output if they're run interactively.
   1.825 +	Otherwise these banners will at least clutter up Mercurial's
   1.826 +	output.  Worse, they could potentially cause problems with
   1.827 +	running Mercurial commands remotely.  Mercurial tries to
   1.828 +	detect and ignore banners in non-interactive
   1.829 +	<command>ssh</command> sessions, but it is not foolproof.  (If
   1.830 +	you're editing your login scripts on your server, the usual
   1.831 +	way to see if a login script is running in an interactive
   1.832 +	shell is to check the return code from the command
   1.833 +	<literal>tty -s</literal>.)</para>
   1.834 +
   1.835 +      <para id="x_4af">Once you've verified that plain old ssh is working with
   1.836 +	your server, the next step is to ensure that Mercurial runs on
   1.837 +	the server.  The following command should run
   1.838 +	successfully:</para>
   1.839 +
   1.840 +      <programlisting>ssh myserver hg version</programlisting>
   1.841 +
   1.842 +      <para id="x_4b0">If you see an error message instead of normal <command
   1.843 +	  role="hg-cmd">hg version</command> output, this is usually
   1.844 +	because you haven't installed Mercurial to <filename
   1.845 +	  class="directory">/usr/bin</filename>.  Don't worry if this
   1.846 +	is the case; you don't need to do that.  But you should check
   1.847 +	for a few possible problems.</para>
   1.848 +      <itemizedlist>
   1.849 +	<listitem><para id="x_4b1">Is Mercurial really installed on the server at
   1.850 +	    all?  I know this sounds trivial, but it's worth
   1.851 +	    checking!</para>
   1.852 +	</listitem>
   1.853 +	<listitem><para id="x_4b2">Maybe your shell's search path (usually set
   1.854 +	    via the <envar>PATH</envar> environment variable) is
   1.855 +	    simply misconfigured.</para>
   1.856 +	</listitem>
   1.857 +	<listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment
   1.858 +	    variable is only being set to point to the location of the
   1.859 +	    <command>hg</command> executable if the login session is
   1.860 +	    interactive.  This can happen if you're setting the path
   1.861 +	    in the wrong shell login script.  See your shell's
   1.862 +	    documentation for details.</para>
   1.863 +	</listitem>
   1.864 +	<listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment
   1.865 +	    variable may need to contain the path to the Mercurial
   1.866 +	    Python modules.  It might not be set at all; it could be
   1.867 +	    incorrect; or it may be set only if the login is
   1.868 +	    interactive.</para>
   1.869 +	</listitem></itemizedlist>
   1.870 +
   1.871 +      <para id="x_4b5">If you can run <command role="hg-cmd">hg version</command>
   1.872 +	over an ssh connection, well done! You've got the server and
   1.873 +	client sorted out.  You should now be able to use Mercurial to
   1.874 +	access repositories hosted by that username on that server.
   1.875 +	If you run into problems with Mercurial and ssh at this point,
   1.876 +	try using the <option role="hg-opt-global">--debug</option>
   1.877 +	option to get a clearer picture of what's going on.</para>
   1.878 +    </sect2>
   1.879 +    <sect2>
   1.880 +      <title>Using compression with ssh</title>
   1.881 +
   1.882 +      <para id="x_4b6">Mercurial does not compress data when it uses the ssh
   1.883 +	protocol, because the ssh protocol can transparently compress
   1.884 +	data.  However, the default behavior of ssh clients is
   1.885 +	<emphasis>not</emphasis> to request compression.</para>
   1.886 +
   1.887 +      <para id="x_4b7">Over any network other than a fast LAN (even a wireless
   1.888 +	network), using compression is likely to significantly speed
   1.889 +	up Mercurial's network operations.  For example, over a WAN,
   1.890 +	someone measured compression as reducing the amount of time
   1.891 +	required to clone a particularly large repository from 51
   1.892 +	minutes to 17 minutes.</para>
   1.893 +
   1.894 +      <para id="x_4b8">Both <command>ssh</command> and <command>plink</command>
   1.895 +	accept a <option role="cmd-opt-ssh">-C</option> option which
   1.896 +	turns on compression.  You can easily edit your <filename
   1.897 +	  role="special">~/.hgrc</filename> to enable compression for
   1.898 +	all of Mercurial's uses of the ssh protocol.  Here is how to
   1.899 +	do so for regular <command>ssh</command> on Unix-like systems,
   1.900 +	for example.</para>
   1.901 +      <programlisting>[ui]
   1.902 +ssh = ssh -C</programlisting>
   1.903 +
   1.904 +      <para id="x_4b9">If you use <command>ssh</command> on a
   1.905 +	Unix-like system, you can configure it to always use
   1.906 +	compression when talking to your server.  To do this, edit
   1.907 +	your <filename role="special">.ssh/config</filename> file
   1.908 +	(which may not yet exist), as follows.</para>
   1.909 +
   1.910 +      <programlisting>Host hg
   1.911 +  Compression yes
   1.912 +  HostName hg.example.com</programlisting>
   1.913 +
   1.914 +      <para id="x_4ba">This defines a hostname alias,
   1.915 +	<literal>hg</literal>.  When you use that hostname on the
   1.916 +	<command>ssh</command> command line or in a Mercurial
   1.917 +	<literal>ssh</literal>-protocol URL, it will cause
   1.918 +	<command>ssh</command> to connect to
   1.919 +	<literal>hg.example.com</literal> and use compression.  This
   1.920 +	gives you both a shorter name to type and compression, each of
   1.921 +	which is a good thing in its own right.</para>
   1.922 +    </sect2>
   1.923 +  </sect1>
   1.924 +
   1.925 +  <sect1 id="sec:collab:cgi">
   1.926 +    <title>Serving over HTTP using CGI</title>
   1.927 +
   1.928 +    <para id="x_6a8">The simplest way to host one or more repositories in a
   1.929 +      permanent way is to use a web server and Mercurial's CGI
   1.930 +      support.</para>
   1.931 +
   1.932 +    <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
   1.933 +      CGI interface can take anything from a few moments to several
   1.934 +      hours.</para>
   1.935 +
   1.936 +    <para id="x_4bc">We'll begin with the simplest of examples, and work our way
   1.937 +      towards a more complex configuration.  Even for the most basic
   1.938 +      case, you're almost certainly going to need to read and modify
   1.939 +      your web server's configuration.</para>
   1.940 +
   1.941 +    <note>
   1.942 +      <title>High pain tolerance required</title>
   1.943 +
   1.944 +      <para id="x_4bd">Configuring a web server is a complex, fiddly,
   1.945 +	and highly system-dependent activity.  I can't possibly give
   1.946 +	you instructions that will cover anything like all of the
   1.947 +	cases you will encounter. Please use your discretion and
   1.948 +	judgment in following the sections below.  Be prepared to make
   1.949 +	plenty of mistakes, and to spend a lot of time reading your
   1.950 +	server's error logs.</para>
   1.951 +
   1.952 +      <para id="x_6a9">If you don't have a strong stomach for tweaking
   1.953 +	configurations over and over, or a compelling need to host
   1.954 +	your own services, you might want to try one of the public
   1.955 +	hosting services that I mentioned earlier.</para>
   1.956 +    </note>
   1.957 +
   1.958 +    <sect2>
   1.959 +      <title>Web server configuration checklist</title>
   1.960 +
   1.961 +      <para id="x_4be">Before you continue, do take a few moments to check a few
   1.962 +	aspects of your system's setup.</para>
   1.963 +
   1.964 +      <orderedlist>
   1.965 +	<listitem><para id="x_4bf">Do you have a web server installed
   1.966 +	    at all? Mac OS X and some Linux distributions ship with
   1.967 +	    Apache, but many other systems may not have a web server
   1.968 +	    installed.</para>
   1.969 +	</listitem>
   1.970 +	<listitem><para id="x_4c0">If you have a web server installed, is it
   1.971 +	    actually running?  On most systems, even if one is
   1.972 +	    present, it will be disabled by default.</para>
   1.973 +	</listitem>
   1.974 +	<listitem><para id="x_4c1">Is your server configured to allow you to run
   1.975 +	    CGI programs in the directory where you plan to do so?
   1.976 +	    Most servers default to explicitly disabling the ability
   1.977 +	    to run CGI programs.</para>
   1.978 +	</listitem></orderedlist>
   1.979 +
   1.980 +      <para id="x_4c2">If you don't have a web server installed, and don't have
   1.981 +	substantial experience configuring Apache, you should consider
   1.982 +	using the <literal>lighttpd</literal> web server instead of
   1.983 +	Apache.  Apache has a well-deserved reputation for baroque and
   1.984 +	confusing configuration. While <literal>lighttpd</literal> is
   1.985 +	less capable in some ways than Apache, most of these
   1.986 +	capabilities are not relevant to serving Mercurial
   1.987 +	repositories.  And <literal>lighttpd</literal> is undeniably
   1.988 +	<emphasis>much</emphasis> easier to get started with than
   1.989 +	Apache.</para>
   1.990 +    </sect2>
   1.991 +
   1.992 +    <sect2>
   1.993 +      <title>Basic CGI configuration</title>
   1.994 +
   1.995 +      <para id="x_4c3">On Unix-like systems, it's common for users to have a
   1.996 +	subdirectory named something like <filename
   1.997 +	  class="directory">public_html</filename> in their home
   1.998 +	directory, from which they can serve up web pages.  A file
   1.999 +	named <filename>foo</filename> in this directory will be
  1.1000 +	accessible at a URL of the form
  1.1001 +	<literal>http://www.example.com/username/foo</literal>.</para>
  1.1002 +
  1.1003 +      <para id="x_4c4">To get started, find the <filename
  1.1004 +	  role="special">hgweb.cgi</filename> script that should be
  1.1005 +	present in your Mercurial installation.  If you can't quickly
  1.1006 +	find a local copy on your system, simply download one from the
  1.1007 +	master Mercurial repository at <ulink
  1.1008 +	  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.1009 +
  1.1010 +      <para id="x_4c5">You'll need to copy this script into your <filename
  1.1011 +	  class="directory">public_html</filename> directory, and
  1.1012 +	ensure that it's executable.</para>
  1.1013 +      <programlisting>cp .../hgweb.cgi ~/public_html
  1.1014 +chmod 755 ~/public_html/hgweb.cgi</programlisting>
  1.1015 +      <para id="x_4c6">The <literal>755</literal> argument to
  1.1016 +	<command>chmod</command> is a little more general than just
  1.1017 +	making the script executable: it ensures that the script is
  1.1018 +	executable by anyone, and that <quote>group</quote> and
  1.1019 +	<quote>other</quote> write permissions are
  1.1020 +	<emphasis>not</emphasis> set.  If you were to leave those
  1.1021 +	write permissions enabled, Apache's <literal>suexec</literal>
  1.1022 +	subsystem would likely refuse to execute the script.  In fact,
  1.1023 +	<literal>suexec</literal> also insists that the
  1.1024 +	<emphasis>directory</emphasis> in which the script resides
  1.1025 +	must not be writable by others.</para>
  1.1026 +      <programlisting>chmod 755 ~/public_html</programlisting>
  1.1027 +
  1.1028 +      <sect3 id="sec:collab:wtf">
  1.1029 +	<title>What could <emphasis>possibly</emphasis> go
  1.1030 +	  wrong?</title>
  1.1031 +
  1.1032 +	<para id="x_4c7">Once you've copied the CGI script into place,
  1.1033 +	  go into a web browser, and try to open the URL
  1.1034 +	  <literal>http://myhostname/~myuser/hgweb.cgi</literal>,
  1.1035 +	  <emphasis>but</emphasis> brace yourself for instant failure.
  1.1036 +	  There's a high probability that trying to visit this URL
  1.1037 +	  will fail, and there are many possible reasons for this.  In
  1.1038 +	  fact, you're likely to stumble over almost every one of the
  1.1039 +	  possible errors below, so please read carefully.  The
  1.1040 +	  following are all of the problems I ran into on a system
  1.1041 +	  running Fedora 7, with a fresh installation of Apache, and a
  1.1042 +	  user account that I created specially to perform this
  1.1043 +	  exercise.</para>
  1.1044 +
  1.1045 +	<para id="x_4c8">Your web server may have per-user directories disabled.
  1.1046 +	  If you're using Apache, search your config file for a
  1.1047 +	  <literal>UserDir</literal> directive.  If there's none
  1.1048 +	  present, per-user directories will be disabled.  If one
  1.1049 +	  exists, but its value is <literal>disabled</literal>, then
  1.1050 +	  per-user directories will be disabled.  Otherwise, the
  1.1051 +	  string after <literal>UserDir</literal> gives the name of
  1.1052 +	  the subdirectory that Apache will look in under your home
  1.1053 +	  directory, for example <filename
  1.1054 +	    class="directory">public_html</filename>.</para>
  1.1055 +
  1.1056 +	<para id="x_4c9">Your file access permissions may be too restrictive.
  1.1057 +	  The web server must be able to traverse your home directory
  1.1058 +	  and directories under your <filename
  1.1059 +	    class="directory">public_html</filename> directory, and
  1.1060 +	  read files under the latter too.  Here's a quick recipe to
  1.1061 +	  help you to make your permissions more appropriate.</para>
  1.1062 +	<programlisting>chmod 755 ~
  1.1063 +find ~/public_html -type d -print0 | xargs -0r chmod 755
  1.1064 +find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting>
  1.1065 +
  1.1066 +	<para id="x_4ca">The other possibility with permissions is that you might
  1.1067 +	  get a completely empty window when you try to load the
  1.1068 +	  script.  In this case, it's likely that your access
  1.1069 +	  permissions are <emphasis>too permissive</emphasis>.  Apache's
  1.1070 +	  <literal>suexec</literal> subsystem won't execute a script
  1.1071 +	  that's group- or world-writable, for example.</para>
  1.1072 +
  1.1073 +	<para id="x_4cb">Your web server may be configured to disallow execution
  1.1074 +	  of CGI programs in your per-user web directory.  Here's
  1.1075 +	  Apache's default per-user configuration from my Fedora
  1.1076 +	  system.</para>
  1.1077 +
  1.1078 +	&ch06-apache-config.lst;
  1.1079 +
  1.1080 +	<para id="x_4cc">If you find a similar-looking
  1.1081 +	  <literal>Directory</literal> group in your Apache
  1.1082 +	  configuration, the directive to look at inside it is
  1.1083 +	  <literal>Options</literal>. Add <literal>ExecCGI</literal>
  1.1084 +	  to the end of this list if it's missing, and restart the web
  1.1085 +	  server.</para>
  1.1086 +
  1.1087 +	<para id="x_4cd">If you find that Apache serves you the text of the CGI
  1.1088 +	  script instead of executing it, you may need to either
  1.1089 +	  uncomment (if already present) or add a directive like
  1.1090 +	  this.</para>
  1.1091 +	<programlisting>AddHandler cgi-script .cgi</programlisting>
  1.1092 +
  1.1093 +	<para id="x_4ce">The next possibility is that you might be served with a
  1.1094 +	  colourful Python backtrace claiming that it can't import a
  1.1095 +	  <literal>mercurial</literal>-related module.  This is
  1.1096 +	  actually progress!  The server is now capable of executing
  1.1097 +	  your CGI script.  This error is only likely to occur if
  1.1098 +	  you're running a private installation of Mercurial, instead
  1.1099 +	  of a system-wide version.  Remember that the web server runs
  1.1100 +	  the CGI program without any of the environment variables
  1.1101 +	  that you take for granted in an interactive session.  If
  1.1102 +	  this error happens to you, edit your copy of <filename
  1.1103 +	    role="special">hgweb.cgi</filename> and follow the
  1.1104 +	  directions inside it to correctly set your
  1.1105 +	  <envar>PYTHONPATH</envar> environment variable.</para>
  1.1106 +
  1.1107 +	<para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be
  1.1108 +	  served with another colourful Python backtrace: this one
  1.1109 +	  will complain that it can't find <filename
  1.1110 +	    class="directory">/path/to/repository</filename>.  Edit
  1.1111 +	  your <filename role="special">hgweb.cgi</filename> script
  1.1112 +	  and replace the <filename
  1.1113 +	    class="directory">/path/to/repository</filename> string
  1.1114 +	  with the complete path to the repository you want to serve
  1.1115 +	  up.</para>
  1.1116 +
  1.1117 +	<para id="x_4d0">At this point, when you try to reload the page, you
  1.1118 +	  should be presented with a nice HTML view of your
  1.1119 +	  repository's history.  Whew!</para>
  1.1120 +      </sect3>
  1.1121 +
  1.1122 +      <sect3>
  1.1123 +	<title>Configuring lighttpd</title>
  1.1124 +
  1.1125 +	<para id="x_4d1">To be exhaustive in my experiments, I tried configuring
  1.1126 +	  the increasingly popular <literal>lighttpd</literal> web
  1.1127 +	  server to serve the same repository as I described with
  1.1128 +	  Apache above.  I had already overcome all of the problems I
  1.1129 +	  outlined with Apache, many of which are not server-specific.
  1.1130 +	  As a result, I was fairly sure that my file and directory
  1.1131 +	  permissions were good, and that my <filename
  1.1132 +	    role="special">hgweb.cgi</filename> script was properly
  1.1133 +	  edited.</para>
  1.1134 +
  1.1135 +	<para id="x_4d2">Once I had Apache running, getting
  1.1136 +	  <literal>lighttpd</literal> to serve the repository was a
  1.1137 +	  snap (in other words, even if you're trying to use
  1.1138 +	  <literal>lighttpd</literal>, you should read the Apache
  1.1139 +	  section).  I first had to edit the
  1.1140 +	  <literal>mod_access</literal> section of its config file to
  1.1141 +	  enable <literal>mod_cgi</literal> and
  1.1142 +	  <literal>mod_userdir</literal>, both of which were disabled
  1.1143 +	  by default on my system.  I then added a few lines to the
  1.1144 +	  end of the config file, to configure these modules.</para>
  1.1145 +	<programlisting>userdir.path = "public_html"
  1.1146 +cgi.assign = (".cgi" =&gt; "" )</programlisting>
  1.1147 +	<para id="x_4d3">With this done, <literal>lighttpd</literal> ran
  1.1148 +	  immediately for me.  If I had configured
  1.1149 +	  <literal>lighttpd</literal> before Apache, I'd almost
  1.1150 +	  certainly have run into many of the same system-level
  1.1151 +	  configuration problems as I did with Apache.  However, I
  1.1152 +	  found <literal>lighttpd</literal> to be noticeably easier to
  1.1153 +	  configure than Apache, even though I've used Apache for over
  1.1154 +	  a decade, and this was my first exposure to
  1.1155 +	  <literal>lighttpd</literal>.</para>
  1.1156 +      </sect3>
  1.1157 +    </sect2>
  1.1158 +
  1.1159 +    <sect2>
  1.1160 +      <title>Sharing multiple repositories with one CGI script</title>
  1.1161 +
  1.1162 +      <para id="x_4d4">The <filename role="special">hgweb.cgi</filename> script
  1.1163 +	only lets you publish a single repository, which is an
  1.1164 +	annoying restriction.  If you want to publish more than one
  1.1165 +	without wracking yourself with multiple copies of the same
  1.1166 +	script, each with different names, a better choice is to use
  1.1167 +	the <filename role="special">hgwebdir.cgi</filename>
  1.1168 +	script.</para>
  1.1169 +
  1.1170 +      <para id="x_4d5">The procedure to configure <filename
  1.1171 +	  role="special">hgwebdir.cgi</filename> is only a little more
  1.1172 +	involved than for <filename
  1.1173 +	  role="special">hgweb.cgi</filename>.  First, you must obtain
  1.1174 +	a copy of the script.  If you don't have one handy, you can
  1.1175 +	download a copy from the master Mercurial repository at <ulink
  1.1176 +	  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.1177 +
  1.1178 +      <para id="x_4d6">You'll need to copy this script into your <filename
  1.1179 +	  class="directory">public_html</filename> directory, and
  1.1180 +	ensure that it's executable.</para>
  1.1181 +
  1.1182 +      <programlisting>cp .../hgwebdir.cgi ~/public_html
  1.1183 +chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
  1.1184 +
  1.1185 +      <para id="x_4d7">With basic configuration out of the way, try to
  1.1186 +	visit <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>
  1.1187 +	in your	browser.  It should
  1.1188 +	display an empty list of repositories.  If you get a blank
  1.1189 +	window or error message, try walking through the list of
  1.1190 +	potential problems in <xref
  1.1191 +	  linkend="sec:collab:wtf"/>.</para>
  1.1192 +
  1.1193 +      <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename>
  1.1194 +	script relies on an external configuration file.  By default,
  1.1195 +	it searches for a file named <filename
  1.1196 +	  role="special">hgweb.config</filename> in the same directory
  1.1197 +	as itself.  You'll need to create this file, and make it
  1.1198 +	world-readable.  The format of the file is similar to a
  1.1199 +	Windows <quote>ini</quote> file, as understood by Python's
  1.1200 +	<literal>ConfigParser</literal>
  1.1201 +	<citation>web:configparser</citation> module.</para>
  1.1202 +
  1.1203 +      <para id="x_4d9">The easiest way to configure <filename
  1.1204 +	  role="special">hgwebdir.cgi</filename> is with a section
  1.1205 +	named <literal>collections</literal>.  This will automatically
  1.1206 +	publish <emphasis>every</emphasis> repository under the
  1.1207 +	directories you name.  The section should look like
  1.1208 +	this:</para>
  1.1209 +      <programlisting>[collections]
  1.1210 +/my/root = /my/root</programlisting>
  1.1211 +      <para id="x_4da">Mercurial interprets this by looking at the directory name
  1.1212 +	on the <emphasis>right</emphasis> hand side of the
  1.1213 +	<quote><literal>=</literal></quote> sign; finding repositories
  1.1214 +	in that directory hierarchy; and using the text on the
  1.1215 +	<emphasis>left</emphasis> to strip off matching text from the
  1.1216 +	names it will actually list in the web interface.  The
  1.1217 +	remaining component of a path after this stripping has
  1.1218 +	occurred is called a <quote>virtual path</quote>.</para>
  1.1219 +
  1.1220 +      <para id="x_4db">Given the example above, if we have a
  1.1221 +	repository whose local path is <filename
  1.1222 +	  class="directory">/my/root/this/repo</filename>, the CGI
  1.1223 +	script will strip the leading <filename
  1.1224 +	  class="directory">/my/root</filename> from the name, and
  1.1225 +	publish the repository with a virtual path of <filename
  1.1226 +	  class="directory">this/repo</filename>.  If the base URL for
  1.1227 +	our CGI script is
  1.1228 +	<literal>http://myhostname/~myuser/hgwebdir.cgi</literal>, the
  1.1229 +	complete URL for that repository will be
  1.1230 +	<literal>http://myhostname/~myuser/hgwebdir.cgi/this/repo</literal>.</para>
  1.1231 +
  1.1232 +      <para id="x_4dc">If we replace <filename
  1.1233 +	  class="directory">/my/root</filename> on the left hand side
  1.1234 +	of this example with <filename
  1.1235 +	  class="directory">/my</filename>, then <filename
  1.1236 +	  role="special">hgwebdir.cgi</filename> will only strip off
  1.1237 +	<filename class="directory">/my</filename> from the repository
  1.1238 +	name, and will give us a virtual path of <filename
  1.1239 +	  class="directory">root/this/repo</filename> instead of
  1.1240 +	<filename class="directory">this/repo</filename>.</para>
  1.1241 +
  1.1242 +      <para id="x_4dd">The <filename role="special">hgwebdir.cgi</filename>
  1.1243 +	script will recursively search each directory listed in the
  1.1244 +	<literal>collections</literal> section of its configuration
  1.1245 +	file, but it will <literal>not</literal> recurse into the
  1.1246 +	repositories it finds.</para>
  1.1247 +
  1.1248 +      <para id="x_4de">The <literal>collections</literal> mechanism makes it easy
  1.1249 +	to publish many repositories in a <quote>fire and
  1.1250 +	  forget</quote> manner.  You only need to set up the CGI
  1.1251 +	script and configuration file one time.  Afterwards, you can
  1.1252 +	publish or unpublish a repository at any time by simply moving
  1.1253 +	it into, or out of, the directory hierarchy in which you've
  1.1254 +	configured <filename role="special">hgwebdir.cgi</filename> to
  1.1255 +	look.</para>
  1.1256 +
  1.1257 +      <sect3>
  1.1258 +	<title>Explicitly specifying which repositories to
  1.1259 +	  publish</title>
  1.1260 +
  1.1261 +	<para id="x_4df">In addition to the <literal>collections</literal>
  1.1262 +	  mechanism, the <filename
  1.1263 +	    role="special">hgwebdir.cgi</filename> script allows you
  1.1264 +	  to publish a specific list of repositories.  To do so,
  1.1265 +	  create a <literal>paths</literal> section, with contents of
  1.1266 +	  the following form.</para>
  1.1267 +	<programlisting>[paths]
  1.1268 +repo1 = /my/path/to/some/repo
  1.1269 +repo2 = /some/path/to/another</programlisting>
  1.1270 +	<para id="x_4e0">In this case, the virtual path (the component that will
  1.1271 +	  appear in a URL) is on the left hand side of each
  1.1272 +	  definition, while the path to the repository is on the
  1.1273 +	  right.  Notice that there does not need to be any
  1.1274 +	  relationship between the virtual path you choose and the
  1.1275 +	  location of a repository in your filesystem.</para>
  1.1276 +
  1.1277 +	<para id="x_4e1">If you wish, you can use both the
  1.1278 +	  <literal>collections</literal> and <literal>paths</literal>
  1.1279 +	  mechanisms simultaneously in a single configuration
  1.1280 +	  file.</para>
  1.1281 +
  1.1282 +	<note>
  1.1283 +	  <title>Beware duplicate virtual paths</title>
  1.1284 +
  1.1285 +	  <para id="x_4e2">  If several repositories have the same
  1.1286 +	    virtual path, <filename
  1.1287 +	      role="special">hgwebdir.cgi</filename> will not report
  1.1288 +	    an error.  Instead, it will behave unpredictably.</para>
  1.1289 +	</note>
  1.1290 +      </sect3>
  1.1291 +    </sect2>
  1.1292 +
  1.1293 +    <sect2>
  1.1294 +      <title>Downloading source archives</title>
  1.1295 +
  1.1296 +      <para id="x_4e3">Mercurial's web interface lets users download an archive
  1.1297 +	of any revision.  This archive will contain a snapshot of the
  1.1298 +	working directory as of that revision, but it will not contain
  1.1299 +	a copy of the repository data.</para>
  1.1300 +
  1.1301 +      <para id="x_4e4">By default, this feature is not enabled.  To enable it,
  1.1302 +	you'll need to add an <envar
  1.1303 +	  role="rc-item-web">allow_archive</envar> item to the
  1.1304 +	<literal role="rc-web">web</literal> section of your <filename
  1.1305 +	  role="special">~/.hgrc</filename>; see below for details.</para>
  1.1306 +    </sect2>
  1.1307 +    <sect2>
  1.1308 +      <title>Web configuration options</title>
  1.1309 +
  1.1310 +      <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd">hg
  1.1311 +	  serve</command> command, and the <filename
  1.1312 +	  role="special">hgweb.cgi</filename> and <filename
  1.1313 +	  role="special">hgwebdir.cgi</filename> scripts) have a
  1.1314 +	number of configuration options that you can set.  These
  1.1315 +	belong in a section named <literal
  1.1316 +	  role="rc-web">web</literal>.</para>
  1.1317 +      <itemizedlist>
  1.1318 +	<listitem><para id="x_4e6"><envar
  1.1319 +	      role="rc-item-web">allow_archive</envar>: Determines
  1.1320 +	    which (if any) archive download mechanisms Mercurial
  1.1321 +	    supports.  If you enable this feature, users of the web
  1.1322 +	    interface will be able to download an archive of whatever
  1.1323 +	    revision of a repository they are viewing. To enable the
  1.1324 +	    archive feature, this item must take the form of a
  1.1325 +	    sequence of words drawn from the list below.</para>
  1.1326 +	  <itemizedlist>
  1.1327 +	    <listitem><para id="x_4e7"><literal>bz2</literal>: A
  1.1328 +		<command>tar</command> archive, compressed using
  1.1329 +		<literal>bzip2</literal> compression.  This has the
  1.1330 +		best compression ratio, but uses the most CPU time on
  1.1331 +		the server.</para>
  1.1332 +	    </listitem>
  1.1333 +	    <listitem><para id="x_4e8"><literal>gz</literal>: A
  1.1334 +		<command>tar</command> archive, compressed using
  1.1335 +		<literal>gzip</literal> compression.</para>
  1.1336 +	    </listitem>
  1.1337 +	    <listitem><para id="x_4e9"><literal>zip</literal>: A
  1.1338 +		<command>zip</command> archive, compressed using LZW
  1.1339 +		compression.  This format has the worst compression
  1.1340 +		ratio, but is widely used in the Windows world.</para>
  1.1341 +	    </listitem>
  1.1342 +	  </itemizedlist>
  1.1343 +	  <para id="x_4ea">  If you provide an empty list, or don't have an
  1.1344 +	    <envar role="rc-item-web">allow_archive</envar> entry at
  1.1345 +	    all, this feature will be disabled.  Here is an example of
  1.1346 +	    how to enable all three supported formats.</para>
  1.1347 +	  <programlisting>[web]
  1.1348 +allow_archive = bz2 gz zip</programlisting>
  1.1349 +	</listitem>
  1.1350 +	<listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>:
  1.1351 +	    Boolean.  Determines whether the web interface allows
  1.1352 +	    remote users to <command role="hg-cmd">hg pull</command>
  1.1353 +	    and <command role="hg-cmd">hg clone</command> this
  1.1354 +	    repository over HTTP.  If set to <literal>no</literal> or
  1.1355 +	    <literal>false</literal>, only the
  1.1356 +	    <quote>human-oriented</quote> portion of the web interface
  1.1357 +	    is available.</para>
  1.1358 +	</listitem>
  1.1359 +	<listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>:
  1.1360 +	    String.  A free-form (but preferably brief) string
  1.1361 +	    identifying the person or group in charge of the
  1.1362 +	    repository.  This often contains the name and email
  1.1363 +	    address of a person or mailing list.  It often makes sense
  1.1364 +	    to place this entry in a repository's own <filename
  1.1365 +	      role="special">.hg/hgrc</filename> file, but it can make
  1.1366 +	    sense to use in a global <filename
  1.1367 +	      role="special">~/.hgrc</filename> if every repository
  1.1368 +	    has a single maintainer.</para>
  1.1369 +	</listitem>
  1.1370 +	<listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>:
  1.1371 +	    Integer.  The default maximum number of changesets to
  1.1372 +	    display in a single page of output.</para>
  1.1373 +	</listitem>
  1.1374 +	<listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>:
  1.1375 +	    Integer.  The default maximum number of modified files to
  1.1376 +	    display in a single page of output.</para>
  1.1377 +	</listitem>
  1.1378 +	<listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>:
  1.1379 +	    Integer.  If the web interface displays alternating
  1.1380 +	    <quote>stripes</quote> to make it easier to visually align
  1.1381 +	    rows when you are looking at a table, this number controls
  1.1382 +	    the number of rows in each stripe.</para>
  1.1383 +	</listitem>
  1.1384 +	<listitem><para id="x_4f0"><envar
  1.1385 +	      role="rc-item-web">style</envar>: Controls the template
  1.1386 +	    Mercurial uses to display the web interface.  Mercurial
  1.1387 +	    ships with several web templates.</para>
  1.1388 +	  <itemizedlist>
  1.1389 +	    <listitem>
  1.1390 +	      <para id="x_6aa"><literal>coal</literal> is monochromatic.</para>
  1.1391 +	    </listitem>
  1.1392 +	    <listitem>
  1.1393 +	      <para id="x_6ab"><literal>gitweb</literal> emulates the visual
  1.1394 +		style of git's web interface.</para>
  1.1395 +	    </listitem>
  1.1396 +	    <listitem>
  1.1397 +	      <para id="x_6ac"><literal>monoblue</literal> uses solid blues and
  1.1398 +		greys.</para>
  1.1399 +	    </listitem>
  1.1400 +	    <listitem>
  1.1401 +	      <para id="x_6ad"><literal>paper</literal> is the default.</para>
  1.1402 +	    </listitem>
  1.1403 +	    <listitem>
  1.1404 +	      <para id="x_6ae"><literal>spartan</literal> was the default for a
  1.1405 +		long time.</para>
  1.1406 +	    </listitem>
  1.1407 +	  </itemizedlist>
  1.1408 +	  <para id="x_6af">You can
  1.1409 +	    also specify a custom template of your own; see 
  1.1410 +	    <xref linkend="chap:template"/> for details. Here, you can
  1.1411 +	    see how to enable the <literal>gitweb</literal>
  1.1412 +	    style.</para>
  1.1413 +	  <programlisting>[web]
  1.1414 +style = gitweb</programlisting>
  1.1415 +	</listitem>
  1.1416 +	<listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>:
  1.1417 +	    Path.  The directory in which to search for template
  1.1418 +	    files.  By default, Mercurial searches in the directory in
  1.1419 +	    which it was installed.</para>
  1.1420 +	</listitem></itemizedlist>
  1.1421 +      <para id="x_4f2">If you are using <filename
  1.1422 +	  role="special">hgwebdir.cgi</filename>, you can place a few
  1.1423 +	configuration items in a <literal role="rc-web">web</literal>
  1.1424 +	section of the <filename
  1.1425 +	  role="special">hgweb.config</filename> file instead of a
  1.1426 +	<filename role="special">~/.hgrc</filename> file, for
  1.1427 +	convenience.  These items are <envar
  1.1428 +	  role="rc-item-web">motd</envar> and <envar
  1.1429 +	  role="rc-item-web">style</envar>.</para>
  1.1430 +
  1.1431 +      <sect3>
  1.1432 +	<title>Options specific to an individual repository</title>
  1.1433 +
  1.1434 +	<para id="x_4f3">A few <literal role="rc-web">web</literal> configuration
  1.1435 +	  items ought to be placed in a repository's local <filename
  1.1436 +	    role="special">.hg/hgrc</filename>, rather than a user's
  1.1437 +	  or global <filename role="special">~/.hgrc</filename>.</para>
  1.1438 +	<itemizedlist>
  1.1439 +	  <listitem><para id="x_4f4"><envar
  1.1440 +		role="rc-item-web">description</envar>: String.  A
  1.1441 +	      free-form (but preferably brief) string that describes
  1.1442 +	      the contents or purpose of the repository.</para>
  1.1443 +	  </listitem>
  1.1444 +	  <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>:
  1.1445 +	      String.  The name to use for the repository in the web
  1.1446 +	      interface.  This overrides the default name, which is
  1.1447 +	      the last component of the repository's path.</para>
  1.1448 +	  </listitem></itemizedlist>
  1.1449 +      </sect3>
  1.1450 +
  1.1451 +      <sect3>
  1.1452 +	<title>Options specific to the <command role="hg-cmd">hg
  1.1453 +	    serve</command> command</title>
  1.1454 +
  1.1455 +	<para id="x_4f6">Some of the items in the <literal
  1.1456 +	    role="rc-web">web</literal> section of a <filename
  1.1457 +	    role="special">~/.hgrc</filename> file are only for use
  1.1458 +	  with the <command role="hg-cmd">hg serve</command>
  1.1459 +	  command.</para>
  1.1460 +	<itemizedlist>
  1.1461 +	  <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>:
  1.1462 +	      Path.  The name of a file into which to write an access
  1.1463 +	      log.  By default, the <command role="hg-cmd">hg
  1.1464 +		serve</command> command writes this information to
  1.1465 +	      standard output, not to a file.  Log entries are written
  1.1466 +	      in the standard <quote>combined</quote> file format used
  1.1467 +	      by almost all web servers.</para>
  1.1468 +	  </listitem>
  1.1469 +	  <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>:
  1.1470 +	      String.  The local address on which the server should
  1.1471 +	      listen for incoming connections.  By default, the server
  1.1472 +	      listens on all addresses.</para>
  1.1473 +	  </listitem>
  1.1474 +	  <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>:
  1.1475 +	      Path.  The name of a file into which to write an error
  1.1476 +	      log.  By default, the <command role="hg-cmd">hg
  1.1477 +		serve</command> command writes this information to
  1.1478 +	      standard error, not to a file.</para>
  1.1479 +	  </listitem>
  1.1480 +	  <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>:
  1.1481 +	      Boolean.  Whether to use the IPv6 protocol. By default,
  1.1482 +	      IPv6 is not used.</para>
  1.1483 +	  </listitem>
  1.1484 +	  <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>:
  1.1485 +	      Integer.  The TCP port number on which the server should
  1.1486 +	      listen.  The default port number used is 8000.</para>
  1.1487 +	  </listitem></itemizedlist>
  1.1488 +      </sect3>
  1.1489 +
  1.1490 +      <sect3>
  1.1491 +	<title>Choosing the right <filename
  1.1492 +	    role="special">~/.hgrc</filename> file to add <literal
  1.1493 +	    role="rc-web">web</literal> items to</title>
  1.1494 +
  1.1495 +	<para id="x_4fc">It is important to remember that a web server like
  1.1496 +	  Apache or <literal>lighttpd</literal> will run under a user
  1.1497 +	  ID that is different to yours. CGI scripts run by your
  1.1498 +	  server, such as <filename
  1.1499 +	    role="special">hgweb.cgi</filename>, will usually also run
  1.1500 +	  under that user ID.</para>
  1.1501 +
  1.1502 +	<para id="x_4fd">If you add <literal role="rc-web">web</literal> items to
  1.1503 +	  your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that
  1.1504 +	  <filename role="special">~/.hgrc</filename> file.  Those
  1.1505 +	  settings will thus only affect the behavior of the <command
  1.1506 +	    role="hg-cmd">hg serve</command> command when you run it.
  1.1507 +	  To cause CGI scripts to see your settings, either create a
  1.1508 +	  <filename role="special">~/.hgrc</filename> file in the
  1.1509 +	  home directory of the user ID that runs your web server, or
  1.1510 +	  add those settings to a system-wide <filename
  1.1511 +	    role="special">hgrc</filename> file.</para>
  1.1512 +      </sect3>
  1.1513 +    </sect2>
  1.1514 +  </sect1>
  1.1515 +
  1.1516 +  <sect1>
  1.1517 +    <title>System-wide configuration</title>
  1.1518 +
  1.1519 +    <para id="x_6b0">On Unix-like systems shared by multiple users (such as a
  1.1520 +      server to which people publish changes), it often makes sense to
  1.1521 +      set up some global default behaviors, such as what theme to use
  1.1522 +      in web interfaces.</para>
  1.1523 +
  1.1524 +    <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename>
  1.1525 +      exists, Mercurial will read it at startup time and apply any
  1.1526 +      configuration settings it finds in that file.  It will also look
  1.1527 +      for files ending in a <literal>.rc</literal> extension in a
  1.1528 +      directory named <filename>/etc/mercurial/hgrc.d</filename>, and
  1.1529 +      apply any configuration settings it finds in each of those
  1.1530 +      files.</para>
  1.1531 +
  1.1532 +    <sect2>
  1.1533 +      <title>Making Mercurial more trusting</title>
  1.1534 +
  1.1535 +      <para id="x_6b2">One situation in which a global <filename>hgrc</filename>
  1.1536 +	can be useful is if users are pulling changes owned by other
  1.1537 +	users.  By default, Mercurial will not trust most of the
  1.1538 +	configuration items in a <filename>.hg/hgrc</filename> file
  1.1539 +	inside a repository that is owned by a different user. If we
  1.1540 +	clone or pull changes from such a repository, Mercurial will
  1.1541 +	print a warning stating that it does not trust their
  1.1542 +	<filename>.hg/hgrc</filename>.</para>
  1.1543 +
  1.1544 +      <para id="x_6b3">If everyone in a particular Unix group is on the same team
  1.1545 +	and <emphasis>should</emphasis> trust each other's
  1.1546 +	configuration settings, or we want to trust particular users,
  1.1547 +	we can override Mercurial's skeptical defaults by creating a
  1.1548 +	system-wide <filename>hgrc</filename> file such as the
  1.1549 +	following:</para>
  1.1550 +
  1.1551 +    <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
  1.1552 +[trusted]
  1.1553 +# Trust all entries in any hgrc file owned by the "editors" or
  1.1554 +# "www-data" groups.
  1.1555 +groups = editors, www-data
  1.1556 +
  1.1557 +# Trust entries in hgrc files owned by the following users.
  1.1558 +users = apache, bobo
  1.1559 +</programlisting>
  1.1560 +    </sect2>
  1.1561 +  </sect1>
  1.1562 +</chapter>
  1.1563 +
  1.1564 +<!--
  1.1565 +local variables: 
  1.1566 +sgml-parent-document: ("00book.xml" "book" "chapter")
  1.1567 +end:
  1.1568 +-->