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