hgbook
view en/ch06-collab.xml @ 567:8fcd44708f41
Uncomment all the mangled interaction examples.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Mon Mar 09 23:22:09 2009 -0700 (2009-03-09) |
| parents | 21c62e09b99f |
| children | 13513d2a128d |
line source
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
3 <chapter id="cha:collab">
4 <title>Collaborating with other people</title>
6 <para>As a completely decentralised tool, Mercurial doesn't impose
7 any policy on how people ought to work with each other. However,
8 if you're new to distributed revision control, it helps to have
9 some tools and examples in mind when you're thinking about
10 possible workflow models.</para>
12 <sect1>
13 <title>Mercurial's web interface</title>
15 <para>Mercurial has a powerful web interface that provides several
16 useful capabilities.</para>
18 <para>For interactive use, the web interface lets you browse a
19 single repository or a collection of repositories. You can view
20 the history of a repository, examine each change (comments and
21 diffs), and view the contents of each directory and file.</para>
23 <para>Also for human consumption, the web interface provides an
24 RSS feed of the changes in a repository. This lets you
25 <quote>subscribe</quote> to a repository using your favourite
26 feed reader, and be automatically notified of activity in that
27 repository as soon as it happens. I find this capability much
28 more convenient than the model of subscribing to a mailing list
29 to which notifications are sent, as it requires no additional
30 configuration on the part of whoever is serving the
31 repository.</para>
33 <para>The web interface also lets remote users clone a repository,
34 pull changes from it, and (when the server is configured to
35 permit it) push changes back to it. Mercurial's HTTP tunneling
36 protocol aggressively compresses data, so that it works
37 efficiently even over low-bandwidth network connections.</para>
39 <para>The easiest way to get started with the web interface is to
40 use your web browser to visit an existing repository, such as
41 the master Mercurial repository at <ulink
42 url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para>
44 <para>If you're interested in providing a web interface to your
45 own repositories, Mercurial provides two ways to do this. The
46 first is using the <command role="hg-cmd">hg serve</command>
47 command, which is best suited to short-term
48 <quote>lightweight</quote> serving. See section <xref
49 linkend="sec:collab:serve"/> below for details of how to use
50 this command. If you have a long-lived repository that you'd
51 like to make permanently available, Mercurial has built-in
52 support for the CGI (Common Gateway Interface) standard, which
53 all common web servers support. See section <xref
54 linkend="sec:collab:cgi"/> for details of CGI
55 configuration.</para>
57 </sect1>
58 <sect1>
59 <title>Collaboration models</title>
61 <para>With a suitably flexible tool, making decisions about
62 workflow is much more of a social engineering challenge than a
63 technical one. Mercurial imposes few limitations on how you can
64 structure the flow of work in a project, so it's up to you and
65 your group to set up and live with a model that matches your own
66 particular needs.</para>
68 <sect2>
69 <title>Factors to keep in mind</title>
71 <para>The most important aspect of any model that you must keep
72 in mind is how well it matches the needs and capabilities of
73 the people who will be using it. This might seem
74 self-evident; even so, you still can't afford to forget it for
75 a moment.</para>
77 <para>I once put together a workflow model that seemed to make
78 perfect sense to me, but that caused a considerable amount of
79 consternation and strife within my development team. In spite
80 of my attempts to explain why we needed a complex set of
81 branches, and how changes ought to flow between them, a few
82 team members revolted. Even though they were smart people,
83 they didn't want to pay attention to the constraints we were
84 operating under, or face the consequences of those constraints
85 in the details of the model that I was advocating.</para>
87 <para>Don't sweep foreseeable social or technical problems under
88 the rug. Whatever scheme you put into effect, you should plan
89 for mistakes and problem scenarios. Consider adding automated
90 machinery to prevent, or quickly recover from, trouble that
91 you can anticipate. As an example, if you intend to have a
92 branch with not-for-release changes in it, you'd do well to
93 think early about the possibility that someone might
94 accidentally merge those changes into a release branch. You
95 could avoid this particular problem by writing a hook that
96 prevents changes from being merged from an inappropriate
97 branch.</para>
99 </sect2>
100 <sect2>
101 <title>Informal anarchy</title>
103 <para>I wouldn't suggest an <quote>anything goes</quote>
104 approach as something sustainable, but it's a model that's
105 easy to grasp, and it works perfectly well in a few unusual
106 situations.</para>
108 <para>As one example, many projects have a loose-knit group of
109 collaborators who rarely physically meet each other. Some
110 groups like to overcome the isolation of working at a distance
111 by organising occasional <quote>sprints</quote>. In a sprint,
112 a number of people get together in a single location (a
113 company's conference room, a hotel meeting room, that kind of
114 place) and spend several days more or less locked in there,
115 hacking intensely on a handful of projects.</para>
117 <para>A sprint is the perfect place to use the <command
118 role="hg-cmd">hg serve</command> command, since <command
119 role="hg-cmd">hg serve</command> does not require any fancy
120 server infrastructure. You can get started with <command
121 role="hg-cmd">hg serve</command> in moments, by reading
122 section <xref linkend="sec:collab:serve"/> below. Then simply
123 tell
124 the person next to you that you're running a server, send the
125 URL to them in an instant message, and you immediately have a
126 quick-turnaround way to work together. They can type your URL
127 into their web browser and quickly review your changes; or
128 they can pull a bugfix from you and verify it; or they can
129 clone a branch containing a new feature and try it out.</para>
131 <para>The charm, and the problem, with doing things in an ad hoc
132 fashion like this is that only people who know about your
133 changes, and where they are, can see them. Such an informal
134 approach simply doesn't scale beyond a handful people, because
135 each individual needs to know about $n$ different repositories
136 to pull from.</para>
138 </sect2>
139 <sect2>
140 <title>A single central repository</title>
142 <para>For smaller projects migrating from a centralised revision
143 control tool, perhaps the easiest way to get started is to
144 have changes flow through a single shared central repository.
145 This is also the most common <quote>building block</quote> for
146 more ambitious workflow schemes.</para>
148 <para>Contributors start by cloning a copy of this repository.
149 They can pull changes from it whenever they need to, and some
150 (perhaps all) developers have permission to push a change back
151 when they're ready for other people to see it.</para>
153 <para>Under this model, it can still often make sense for people
154 to pull changes directly from each other, without going
155 through the central repository. Consider a case in which I
156 have a tentative bug fix, but I am worried that if I were to
157 publish it to the central repository, it might subsequently
158 break everyone else's trees as they pull it. To reduce the
159 potential for damage, I can ask you to clone my repository
160 into a temporary repository of your own and test it. This
161 lets us put off publishing the potentially unsafe change until
162 it has had a little testing.</para>
164 <para>In this kind of scenario, people usually use the
165 <command>ssh</command> protocol to securely push changes to
166 the central repository, as documented in section <xref
167 linkend="sec:collab:ssh"/>. It's also
168 usual to publish a read-only copy of the repository over HTTP
169 using CGI, as in section <xref linkend="sec:collab:cgi"/>.
170 Publishing over HTTP
171 satisfies the needs of people who don't have push access, and
172 those who want to use web browsers to browse the repository's
173 history.</para>
175 </sect2>
176 <sect2>
177 <title>Working with multiple branches</title>
179 <para>Projects of any significant size naturally tend to make
180 progress on several fronts simultaneously. In the case of
181 software, it's common for a project to go through periodic
182 official releases. A release might then go into
183 <quote>maintenance mode</quote> for a while after its first
184 publication; maintenance releases tend to contain only bug
185 fixes, not new features. In parallel with these maintenance
186 releases, one or more future releases may be under
187 development. People normally use the word
188 <quote>branch</quote> to refer to one of these many slightly
189 different directions in which development is
190 proceeding.</para>
192 <para>Mercurial is particularly well suited to managing a number
193 of simultaneous, but not identical, branches. Each
194 <quote>development direction</quote> can live in its own
195 central repository, and you can merge changes from one to
196 another as the need arises. Because repositories are
197 independent of each other, unstable changes in a development
198 branch will never affect a stable branch unless someone
199 explicitly merges those changes in.</para>
201 <para>Here's an example of how this can work in practice. Let's
202 say you have one <quote>main branch</quote> on a central
203 server.</para>
205 &interaction.branching.init;
207 <para>People clone it, make changes locally, test them, and push
208 them back.</para>
210 <para>Once the main branch reaches a release milestone, you can
211 use the <command role="hg-cmd">hg tag</command> command to
212 give a permanent name to the milestone revision.</para>
214 &interaction.branching.tag;
216 <para>Let's say some ongoing
217 development occurs on the main branch.</para>
219 &interaction.branching.main;
221 <para>Using the tag that was recorded at the milestone, people
222 who clone that repository at any time in the future can use
223 <command role="hg-cmd">hg update</command> to get a copy of
224 the working directory exactly as it was when that tagged
225 revision was committed.</para>
227 &interaction.branching.update;
229 <para>In addition, immediately after the main branch is tagged,
230 someone can then clone the main branch on the server to a new
231 <quote>stable</quote> branch, also on the server.</para>
233 &interaction.branching.clone;
235 <para>Someone who needs to make a change to the stable branch
236 can then clone <emphasis>that</emphasis> repository, make
237 their changes, commit, and push their changes back there.</para>
239 &interaction.branching.stable;
241 <para>Because Mercurial repositories are independent, and
242 Mercurial doesn't move changes around automatically, the
243 stable and main branches are <emphasis>isolated</emphasis>
244 from each other. The changes that you made on the main branch
245 don't <quote>leak</quote> to the stable branch, and vice
246 versa.</para>
248 <para>You'll often want all of your bugfixes on the stable
249 branch to show up on the main branch, too. Rather than
250 rewrite a bugfix on the main branch, you can simply pull and
251 merge changes from the stable to the main branch, and
252 Mercurial will bring those bugfixes in for you.</para>
254 &interaction.branching.merge;
256 <para>The main branch will still contain changes that are not on
257 the stable branch, but it will also contain all of the
258 bugfixes from the stable branch. The stable branch remains
259 unaffected by these changes.</para>
261 </sect2>
262 <sect2>
263 <title>Feature branches</title>
265 <para>For larger projects, an effective way to manage change is
266 to break up a team into smaller groups. Each group has a
267 shared branch of its own, cloned from a single
268 <quote>master</quote> branch used by the entire project.
269 People working on an individual branch are typically quite
270 isolated from developments on other branches.</para>
272 <informalfigure id="fig:collab:feature-branches">
273 <mediaobject><imageobject><imagedata
274 fileref="feature-branches"/></imageobject><textobject><phrase>XXX
275 add text</phrase></textobject><caption><para>Feature
276 branches</para></caption></mediaobject>
277 </informalfigure>
279 <para>When a particular feature is deemed to be in suitable
280 shape, someone on that feature team pulls and merges from the
281 master branch into the feature branch, then pushes back up to
282 the master branch.</para>
284 </sect2>
285 <sect2>
286 <title>The release train</title>
288 <para>Some projects are organised on a <quote>train</quote>
289 basis: a release is scheduled to happen every few months, and
290 whatever features are ready when the <quote>train</quote> is
291 ready to leave are allowed in.</para>
293 <para>This model resembles working with feature branches. The
294 difference is that when a feature branch misses a train,
295 someone on the feature team pulls and merges the changes that
296 went out on that train release into the feature branch, and
297 the team continues its work on top of that release so that
298 their feature can make the next release.</para>
300 </sect2>
301 <sect2>
302 <title>The Linux kernel model</title>
304 <para>The development of the Linux kernel has a shallow
305 hierarchical structure, surrounded by a cloud of apparent
306 chaos. Because most Linux developers use
307 <command>git</command>, a distributed revision control tool
308 with capabilities similar to Mercurial, it's useful to
309 describe the way work flows in that environment; if you like
310 the ideas, the approach translates well across tools.</para>
312 <para>At the center of the community sits Linus Torvalds, the
313 creator of Linux. He publishes a single source repository
314 that is considered the <quote>authoritative</quote> current
315 tree by the entire developer community. Anyone can clone
316 Linus's tree, but he is very choosy about whose trees he pulls
317 from.</para>
319 <para>Linus has a number of <quote>trusted lieutenants</quote>.
320 As a general rule, he pulls whatever changes they publish, in
321 most cases without even reviewing those changes. Some of
322 those lieutenants are generally agreed to be
323 <quote>maintainers</quote>, responsible for specific
324 subsystems within the kernel. If a random kernel hacker wants
325 to make a change to a subsystem that they want to end up in
326 Linus's tree, they must find out who the subsystem's
327 maintainer is, and ask that maintainer to take their change.
328 If the maintainer reviews their changes and agrees to take
329 them, they'll pass them along to Linus in due course.</para>
331 <para>Individual lieutenants have their own approaches to
332 reviewing, accepting, and publishing changes; and for deciding
333 when to feed them to Linus. In addition, there are several
334 well known branches that people use for different purposes.
335 For example, a few people maintain <quote>stable</quote>
336 repositories of older versions of the kernel, to which they
337 apply critical fixes as needed. Some maintainers publish
338 multiple trees: one for experimental changes; one for changes
339 that they are about to feed upstream; and so on. Others just
340 publish a single tree.</para>
342 <para>This model has two notable features. The first is that
343 it's <quote>pull only</quote>. You have to ask, convince, or
344 beg another developer to take a change from you, because there
345 are almost no trees to which more than one person can push,
346 and there's no way to push changes into a tree that someone
347 else controls.</para>
349 <para>The second is that it's based on reputation and acclaim.
350 If you're an unknown, Linus will probably ignore changes from
351 you without even responding. But a subsystem maintainer will
352 probably review them, and will likely take them if they pass
353 their criteria for suitability. The more <quote>good</quote>
354 changes you contribute to a maintainer, the more likely they
355 are to trust your judgment and accept your changes. If you're
356 well-known and maintain a long-lived branch for something
357 Linus hasn't yet accepted, people with similar interests may
358 pull your changes regularly to keep up with your work.</para>
360 <para>Reputation and acclaim don't necessarily cross subsystem
361 or <quote>people</quote> boundaries. If you're a respected
362 but specialised storage hacker, and you try to fix a
363 networking bug, that change will receive a level of scrutiny
364 from a network maintainer comparable to a change from a
365 complete stranger.</para>
367 <para>To people who come from more orderly project backgrounds,
368 the comparatively chaotic Linux kernel development process
369 often seems completely insane. It's subject to the whims of
370 individuals; people make sweeping changes whenever they deem
371 it appropriate; and the pace of development is astounding.
372 And yet Linux is a highly successful, well-regarded piece of
373 software.</para>
375 </sect2>
376 <sect2>
377 <title>Pull-only versus shared-push collaboration</title>
379 <para>A perpetual source of heat in the open source community is
380 whether a development model in which people only ever pull
381 changes from others is <quote>better than</quote> one in which
382 multiple people can push changes to a shared
383 repository.</para>
385 <para>Typically, the backers of the shared-push model use tools
386 that actively enforce this approach. If you're using a
387 centralised revision control tool such as Subversion, there's
388 no way to make a choice over which model you'll use: the tool
389 gives you shared-push, and if you want to do anything else,
390 you'll have to roll your own approach on top (such as applying
391 a patch by hand).</para>
393 <para>A good distributed revision control tool, such as
394 Mercurial, will support both models. You and your
395 collaborators can then structure how you work together based
396 on your own needs and preferences, not on what contortions
397 your tools force you into.</para>
399 </sect2>
400 <sect2>
401 <title>Where collaboration meets branch management</title>
403 <para>Once you and your team set up some shared repositories and
404 start propagating changes back and forth between local and
405 shared repos, you begin to face a related, but slightly
406 different challenge: that of managing the multiple directions
407 in which your team may be moving at once. Even though this
408 subject is intimately related to how your team collaborates,
409 it's dense enough to merit treatment of its own, in chapter
410 <xref linkend="chap:branch"/>.</para>
412 </sect2>
413 </sect1>
414 <sect1>
415 <title>The technical side of sharing</title>
417 <para>The remainder of this chapter is devoted to the question of
418 serving data to your collaborators.</para>
420 </sect1>
421 <sect1 id="sec:collab:serve">
422 <title>Informal sharing with <command role="hg-cmd">hg
423 serve</command></title>
425 <para>Mercurial's <command role="hg-cmd">hg serve</command>
426 command is wonderfully suited to small, tight-knit, and
427 fast-paced group environments. It also provides a great way to
428 get a feel for using Mercurial commands over a network.</para>
430 <para>Run <command role="hg-cmd">hg serve</command> inside a
431 repository, and in under a second it will bring up a specialised
432 HTTP server; this will accept connections from any client, and
433 serve up data for that repository until you terminate it.
434 Anyone who knows the URL of the server you just started, and can
435 talk to your computer over the network, can then use a web
436 browser or Mercurial to read data from that repository. A URL
437 for a <command role="hg-cmd">hg serve</command> instance running
438 on a laptop is likely to look something like
439 <literal>http://my-laptop.local:8000/</literal>.</para>
441 <para>The <command role="hg-cmd">hg serve</command> command is
442 <emphasis>not</emphasis> a general-purpose web server. It can do
443 only two things:</para>
444 <itemizedlist>
445 <listitem><para>Allow people to browse the history of the
446 repository it's serving, from their normal web
447 browsers.</para>
448 </listitem>
449 <listitem><para>Speak Mercurial's wire protocol, so that people
450 can <command role="hg-cmd">hg clone</command> or <command
451 role="hg-cmd">hg pull</command> changes from that
452 repository.</para>
453 </listitem></itemizedlist>
454 <para>In particular, <command role="hg-cmd">hg serve</command>
455 won't allow remote users to <emphasis>modify</emphasis> your
456 repository. It's intended for read-only use.</para>
458 <para>If you're getting started with Mercurial, there's nothing to
459 prevent you from using <command role="hg-cmd">hg serve</command>
460 to serve up a repository on your own computer, then use commands
461 like <command role="hg-cmd">hg clone</command>, <command
462 role="hg-cmd">hg incoming</command>, and so on to talk to that
463 server as if the repository was hosted remotely. This can help
464 you to quickly get acquainted with using commands on
465 network-hosted repositories.</para>
467 <sect2>
468 <title>A few things to keep in mind</title>
470 <para>Because it provides unauthenticated read access to all
471 clients, you should only use <command role="hg-cmd">hg
472 serve</command> in an environment where you either don't
473 care, or have complete control over, who can access your
474 network and pull data from your repository.</para>
476 <para>The <command role="hg-cmd">hg serve</command> command
477 knows nothing about any firewall software you might have
478 installed on your system or network. It cannot detect or
479 control your firewall software. If other people are unable to
480 talk to a running <command role="hg-cmd">hg serve</command>
481 instance, the second thing you should do
482 (<emphasis>after</emphasis> you make sure that they're using
483 the correct URL) is check your firewall configuration.</para>
485 <para>By default, <command role="hg-cmd">hg serve</command>
486 listens for incoming connections on port 8000. If another
487 process is already listening on the port you want to use, you
488 can specify a different port to listen on using the <option
489 role="hg-opt-serve">-p</option> option.</para>
491 <para>Normally, when <command role="hg-cmd">hg serve</command>
492 starts, it prints no output, which can be a bit unnerving. If
493 you'd like to confirm that it is indeed running correctly, and
494 find out what URL you should send to your collaborators, start
495 it with the <option role="hg-opt-global">-v</option>
496 option.</para>
498 </sect2>
499 </sect1>
500 <sect1 id="sec:collab:ssh">
501 <title>Using the Secure Shell (ssh) protocol</title>
503 <para>You can pull and push changes securely over a network
504 connection using the Secure Shell (<literal>ssh</literal>)
505 protocol. To use this successfully, you may have to do a little
506 bit of configuration on the client or server sides.</para>
508 <para>If you're not familiar with ssh, it's a network protocol
509 that lets you securely communicate with another computer. To
510 use it with Mercurial, you'll be setting up one or more user
511 accounts on a server so that remote users can log in and execute
512 commands.</para>
514 <para>(If you <emphasis>are</emphasis> familiar with ssh, you'll
515 probably find some of the material that follows to be elementary
516 in nature.)</para>
518 <sect2>
519 <title>How to read and write ssh URLs</title>
521 <para>An ssh URL tends to look like this:</para>
522 <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting>
523 <orderedlist>
524 <listitem><para>The <quote><literal>ssh://</literal></quote>
525 part tells Mercurial to use the ssh protocol.</para>
526 </listitem>
527 <listitem><para>The <quote><literal>bos@</literal></quote>
528 component indicates what username to log into the server
529 as. You can leave this out if the remote username is the
530 same as your local username.</para>
531 </listitem>
532 <listitem><para>The
533 <quote><literal>hg.serpentine.com</literal></quote> gives
534 the hostname of the server to log into.</para>
535 </listitem>
536 <listitem><para>The <quote>:22</quote> identifies the port
537 number to connect to the server on. The default port is
538 22, so you only need to specify this part if you're
539 <emphasis>not</emphasis> using port 22.</para>
540 </listitem>
541 <listitem><para>The remainder of the URL is the local path to
542 the repository on the server.</para>
543 </listitem></orderedlist>
545 <para>There's plenty of scope for confusion with the path
546 component of ssh URLs, as there is no standard way for tools
547 to interpret it. Some programs behave differently than others
548 when dealing with these paths. This isn't an ideal situation,
549 but it's unlikely to change. Please read the following
550 paragraphs carefully.</para>
552 <para>Mercurial treats the path to a repository on the server as
553 relative to the remote user's home directory. For example, if
554 user <literal>foo</literal> on the server has a home directory
555 of <filename class="directory">/home/foo</filename>, then an
556 ssh URL that contains a path component of <filename
557 class="directory">bar</filename> <emphasis>really</emphasis>
558 refers to the directory <filename
559 class="directory">/home/foo/bar</filename>.</para>
561 <para>If you want to specify a path relative to another user's
562 home directory, you can use a path that starts with a tilde
563 character followed by the user's name (let's call them
564 <literal>otheruser</literal>), like this.</para>
565 <programlisting>ssh://server/~otheruser/hg/repo</programlisting>
567 <para>And if you really want to specify an
568 <emphasis>absolute</emphasis> path on the server, begin the
569 path component with two slashes, as in this example.</para>
570 <programlisting>ssh://server//absolute/path</programlisting>
572 </sect2>
573 <sect2>
574 <title>Finding an ssh client for your system</title>
576 <para>Almost every Unix-like system comes with OpenSSH
577 preinstalled. If you're using such a system, run
578 <literal>which ssh</literal> to find out if the
579 <command>ssh</command> command is installed (it's usually in
580 <filename class="directory">/usr/bin</filename>). In the
581 unlikely event that it isn't present, take a look at your
582 system documentation to figure out how to install it.</para>
584 <para>On Windows, you'll first need to download a suitable ssh
585 client. There are two alternatives.</para>
586 <itemizedlist>
587 <listitem><para>Simon Tatham's excellent PuTTY package
588 <citation>web:putty</citation> provides a complete suite
589 of ssh client commands.</para>
590 </listitem>
591 <listitem><para>If you have a high tolerance for pain, you can
592 use the Cygwin port of OpenSSH.</para>
593 </listitem></itemizedlist>
594 <para>In either case, you'll need to edit your \hgini\ file to
595 tell Mercurial where to find the actual client command. For
596 example, if you're using PuTTY, you'll need to use the
597 <command>plink</command> command as a command-line ssh
598 client.</para>
599 <programlisting>[ui] ssh = C:/path/to/plink.exe -ssh -i
600 "C:/path/to/my/private/key"</programlisting>
602 <note>
603 <para> The path to <command>plink</command> shouldn't contain
604 any whitespace characters, or Mercurial may not be able to
605 run it correctly (so putting it in <filename
606 class="directory">C:\\Program Files</filename> is probably
607 not a good idea).</para>
608 </note>
610 </sect2>
611 <sect2>
612 <title>Generating a key pair</title>
614 <para>To avoid the need to repetitively type a password every
615 time you need to use your ssh client, I recommend generating a
616 key pair. On a Unix-like system, the
617 <command>ssh-keygen</command> command will do the trick. On
618 Windows, if you're using PuTTY, the
619 <command>puttygen</command> command is what you'll
620 need.</para>
622 <para>When you generate a key pair, it's usually
623 <emphasis>highly</emphasis> advisable to protect it with a
624 passphrase. (The only time that you might not want to do this
625 is when you're using the ssh protocol for automated tasks on a
626 secure network.)</para>
628 <para>Simply generating a key pair isn't enough, however.
629 You'll need to add the public key to the set of authorised
630 keys for whatever user you're logging in remotely as. For
631 servers using OpenSSH (the vast majority), this will mean
632 adding the public key to a list in a file called <filename
633 role="special">authorized_keys</filename> in their <filename
634 role="special" class="directory">.ssh</filename>
635 directory.</para>
637 <para>On a Unix-like system, your public key will have a
638 <filename>.pub</filename> extension. If you're using
639 <command>puttygen</command> on Windows, you can save the
640 public key to a file of your choosing, or paste it from the
641 window it's displayed in straight into the <filename
642 role="special">authorized_keys</filename> file.</para>
644 </sect2>
645 <sect2>
646 <title>Using an authentication agent</title>
648 <para>An authentication agent is a daemon that stores
649 passphrases in memory (so it will forget passphrases if you
650 log out and log back in again). An ssh client will notice if
651 it's running, and query it for a passphrase. If there's no
652 authentication agent running, or the agent doesn't store the
653 necessary passphrase, you'll have to type your passphrase
654 every time Mercurial tries to communicate with a server on
655 your behalf (e.g. whenever you pull or push changes).</para>
657 <para>The downside of storing passphrases in an agent is that
658 it's possible for a well-prepared attacker to recover the
659 plain text of your passphrases, in some cases even if your
660 system has been power-cycled. You should make your own
661 judgment as to whether this is an acceptable risk. It
662 certainly saves a lot of repeated typing.</para>
664 <para>On Unix-like systems, the agent is called
665 <command>ssh-agent</command>, and it's often run automatically
666 for you when you log in. You'll need to use the
667 <command>ssh-add</command> command to add passphrases to the
668 agent's store. On Windows, if you're using PuTTY, the
669 <command>pageant</command> command acts as the agent. It adds
670 an icon to your system tray that will let you manage stored
671 passphrases.</para>
673 </sect2>
674 <sect2>
675 <title>Configuring the server side properly</title>
677 <para>Because ssh can be fiddly to set up if you're new to it,
678 there's a variety of things that can go wrong. Add Mercurial
679 on top, and there's plenty more scope for head-scratching.
680 Most of these potential problems occur on the server side, not
681 the client side. The good news is that once you've gotten a
682 configuration working, it will usually continue to work
683 indefinitely.</para>
685 <para>Before you try using Mercurial to talk to an ssh server,
686 it's best to make sure that you can use the normal
687 <command>ssh</command> or <command>putty</command> command to
688 talk to the server first. If you run into problems with using
689 these commands directly, Mercurial surely won't work. Worse,
690 it will obscure the underlying problem. Any time you want to
691 debug ssh-related Mercurial problems, you should drop back to
692 making sure that plain ssh client commands work first,
693 <emphasis>before</emphasis> you worry about whether there's a
694 problem with Mercurial.</para>
696 <para>The first thing to be sure of on the server side is that
697 you can actually log in from another machine at all. If you
698 can't use <command>ssh</command> or <command>putty</command>
699 to log in, the error message you get may give you a few hints
700 as to what's wrong. The most common problems are as
701 follows.</para>
702 <itemizedlist>
703 <listitem><para>If you get a <quote>connection refused</quote>
704 error, either there isn't an SSH daemon running on the
705 server at all, or it's inaccessible due to firewall
706 configuration.</para>
707 </listitem>
708 <listitem><para>If you get a <quote>no route to host</quote>
709 error, you either have an incorrect address for the server
710 or a seriously locked down firewall that won't admit its
711 existence at all.</para>
712 </listitem>
713 <listitem><para>If you get a <quote>permission denied</quote>
714 error, you may have mistyped the username on the server,
715 or you could have mistyped your key's passphrase or the
716 remote user's password.</para>
717 </listitem></itemizedlist>
718 <para>In summary, if you're having trouble talking to the
719 server's ssh daemon, first make sure that one is running at
720 all. On many systems it will be installed, but disabled, by
721 default. Once you're done with this step, you should then
722 check that the server's firewall is configured to allow
723 incoming connections on the port the ssh daemon is listening
724 on (usually 22). Don't worry about more exotic possibilities
725 for misconfiguration until you've checked these two
726 first.</para>
728 <para>If you're using an authentication agent on the client side
729 to store passphrases for your keys, you ought to be able to
730 log into the server without being prompted for a passphrase or
731 a password. If you're prompted for a passphrase, there are a
732 few possible culprits.</para>
733 <itemizedlist>
734 <listitem><para>You might have forgotten to use
735 <command>ssh-add</command> or <command>pageant</command>
736 to store the passphrase.</para>
737 </listitem>
738 <listitem><para>You might have stored the passphrase for the
739 wrong key.</para>
740 </listitem></itemizedlist>
741 <para>If you're being prompted for the remote user's password,
742 there are another few possible problems to check.</para>
743 <itemizedlist>
744 <listitem><para>Either the user's home directory or their
745 <filename role="special" class="directory">.ssh</filename>
746 directory might have excessively liberal permissions. As
747 a result, the ssh daemon will not trust or read their
748 <filename role="special">authorized_keys</filename> file.
749 For example, a group-writable home or <filename
750 role="special" class="directory">.ssh</filename>
751 directory will often cause this symptom.</para>
752 </listitem>
753 <listitem><para>The user's <filename
754 role="special">authorized_keys</filename> file may have
755 a problem. If anyone other than the user owns or can write
756 to that file, the ssh daemon will not trust or read
757 it.</para>
758 </listitem></itemizedlist>
760 <para>In the ideal world, you should be able to run the
761 following command successfully, and it should print exactly
762 one line of output, the current date and time.</para>
763 <programlisting>ssh myserver date</programlisting>
765 <para>If, on your server, you have login scripts that print
766 banners or other junk even when running non-interactive
767 commands like this, you should fix them before you continue,
768 so that they only print output if they're run interactively.
769 Otherwise these banners will at least clutter up Mercurial's
770 output. Worse, they could potentially cause problems with
771 running Mercurial commands remotely. Mercurial makes tries to
772 detect and ignore banners in non-interactive
773 <command>ssh</command> sessions, but it is not foolproof. (If
774 you're editing your login scripts on your server, the usual
775 way to see if a login script is running in an interactive
776 shell is to check the return code from the command
777 <literal>tty -s</literal>.)</para>
779 <para>Once you've verified that plain old ssh is working with
780 your server, the next step is to ensure that Mercurial runs on
781 the server. The following command should run
782 successfully:</para>
783 <programlisting>ssh myserver hg version</programlisting>
784 <para>If you see an error message instead of normal <command
785 role="hg-cmd">hg version</command> output, this is usually
786 because you haven't installed Mercurial to <filename
787 class="directory">/usr/bin</filename>. Don't worry if this
788 is the case; you don't need to do that. But you should check
789 for a few possible problems.</para>
790 <itemizedlist>
791 <listitem><para>Is Mercurial really installed on the server at
792 all? I know this sounds trivial, but it's worth
793 checking!</para>
794 </listitem>
795 <listitem><para>Maybe your shell's search path (usually set
796 via the <envar>PATH</envar> environment variable) is
797 simply misconfigured.</para>
798 </listitem>
799 <listitem><para>Perhaps your <envar>PATH</envar> environment
800 variable is only being set to point to the location of the
801 <command>hg</command> executable if the login session is
802 interactive. This can happen if you're setting the path
803 in the wrong shell login script. See your shell's
804 documentation for details.</para>
805 </listitem>
806 <listitem><para>The <envar>PYTHONPATH</envar> environment
807 variable may need to contain the path to the Mercurial
808 Python modules. It might not be set at all; it could be
809 incorrect; or it may be set only if the login is
810 interactive.</para>
811 </listitem></itemizedlist>
813 <para>If you can run <command role="hg-cmd">hg version</command>
814 over an ssh connection, well done! You've got the server and
815 client sorted out. You should now be able to use Mercurial to
816 access repositories hosted by that username on that server.
817 If you run into problems with Mercurial and ssh at this point,
818 try using the <option role="hg-opt-global">--debug</option>
819 option to get a clearer picture of what's going on.</para>
821 </sect2>
822 <sect2>
823 <title>Using compression with ssh</title>
825 <para>Mercurial does not compress data when it uses the ssh
826 protocol, because the ssh protocol can transparently compress
827 data. However, the default behaviour of ssh clients is
828 <emphasis>not</emphasis> to request compression.</para>
830 <para>Over any network other than a fast LAN (even a wireless
831 network), using compression is likely to significantly speed
832 up Mercurial's network operations. For example, over a WAN,
833 someone measured compression as reducing the amount of time
834 required to clone a particularly large repository from 51
835 minutes to 17 minutes.</para>
837 <para>Both <command>ssh</command> and <command>plink</command>
838 accept a <option role="cmd-opt-ssh">-C</option> option which
839 turns on compression. You can easily edit your <filename
840 role="special"> /.hgrc</filename>\ to enable compression for
841 all of Mercurial's uses of the ssh protocol.</para>
842 <programlisting>[ui] ssh = ssh -C</programlisting>
844 <para>If you use <command>ssh</command>, you can configure it to
845 always use compression when talking to your server. To do
846 this, edit your <filename
847 role="special">.ssh/config</filename> file (which may not
848 yet exist), as follows.</para>
849 <programlisting>Host hg Compression yes HostName
850 hg.example.com</programlisting>
851 <para>This defines an alias, <literal>hg</literal>. When you
852 use it on the <command>ssh</command> command line or in a
853 Mercurial <literal>ssh</literal>-protocol URL, it will cause
854 <command>ssh</command> to connect to
855 <literal>hg.example.com</literal> and use compression. This
856 gives you both a shorter name to type and compression, each of
857 which is a good thing in its own right.</para>
859 </sect2>
860 </sect1>
861 <sect1 id="sec:collab:cgi">
862 <title>Serving over HTTP using CGI</title>
864 <para>Depending on how ambitious you are, configuring Mercurial's
865 CGI interface can take anything from a few moments to several
866 hours.</para>
868 <para>We'll begin with the simplest of examples, and work our way
869 towards a more complex configuration. Even for the most basic
870 case, you're almost certainly going to need to read and modify
871 your web server's configuration.</para>
873 <note>
874 <para> Configuring a web server is a complex, fiddly, and
875 highly system-dependent activity. I can't possibly give you
876 instructions that will cover anything like all of the cases
877 you will encounter. Please use your discretion and judgment in
878 following the sections below. Be prepared to make plenty of
879 mistakes, and to spend a lot of time reading your server's
880 error logs.</para>
881 </note>
883 <sect2>
884 <title>Web server configuration checklist</title>
886 <para>Before you continue, do take a few moments to check a few
887 aspects of your system's setup.</para>
889 <orderedlist>
890 <listitem><para>Do you have a web server installed at all?
891 Mac OS X ships with Apache, but many other systems may not
892 have a web server installed.</para>
893 </listitem>
894 <listitem><para>If you have a web server installed, is it
895 actually running? On most systems, even if one is
896 present, it will be disabled by default.</para>
897 </listitem>
898 <listitem><para>Is your server configured to allow you to run
899 CGI programs in the directory where you plan to do so?
900 Most servers default to explicitly disabling the ability
901 to run CGI programs.</para>
902 </listitem></orderedlist>
904 <para>If you don't have a web server installed, and don't have
905 substantial experience configuring Apache, you should consider
906 using the <literal>lighttpd</literal> web server instead of
907 Apache. Apache has a well-deserved reputation for baroque and
908 confusing configuration. While <literal>lighttpd</literal> is
909 less capable in some ways than Apache, most of these
910 capabilities are not relevant to serving Mercurial
911 repositories. And <literal>lighttpd</literal> is undeniably
912 <emphasis>much</emphasis> easier to get started with than
913 Apache.</para>
915 </sect2>
916 <sect2>
917 <title>Basic CGI configuration</title>
919 <para>On Unix-like systems, it's common for users to have a
920 subdirectory named something like <filename
921 class="directory">public_html</filename> in their home
922 directory, from which they can serve up web pages. A file
923 named <filename>foo</filename> in this directory will be
924 accessible at a URL of the form
925 <literal>http://www.example.com/\
926 {</literal>username/foo}.</para>
928 <para>To get started, find the <filename
929 role="special">hgweb.cgi</filename> script that should be
930 present in your Mercurial installation. If you can't quickly
931 find a local copy on your system, simply download one from the
932 master Mercurial repository at <ulink
933 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>
935 <para>You'll need to copy this script into your <filename
936 class="directory">public_html</filename> directory, and
937 ensure that it's executable.</para>
938 <programlisting>cp .../hgweb.cgi ~/public_html chmod 755
939 ~/public_html/hgweb.cgi</programlisting>
940 <para>The <literal>755</literal> argument to
941 <command>chmod</command> is a little more general than just
942 making the script executable: it ensures that the script is
943 executable by anyone, and that <quote>group</quote> and
944 <quote>other</quote> write permissions are
945 <emphasis>not</emphasis> set. If you were to leave those
946 write permissions enabled, Apache's <literal>suexec</literal>
947 subsystem would likely refuse to execute the script. In fact,
948 <literal>suexec</literal> also insists that the
949 <emphasis>directory</emphasis> in which the script resides
950 must not be writable by others.</para>
951 <programlisting>chmod 755 ~/public_html</programlisting>
953 <sect3 id="sec:collab:wtf">
954 <title>What could <emphasis>possibly</emphasis> go
955 wrong?</title>
957 <para>Once you've copied the CGI script into place, go into a
958 web browser, and try to open the URL <ulink
959 url="http://myhostname/
960 myuser/hgweb.cgi">http://myhostname/
961 myuser/hgweb.cgi</ulink>, <emphasis>but</emphasis> brace
962 yourself for instant failure. There's a high probability
963 that trying to visit this URL will fail, and there are many
964 possible reasons for this. In fact, you're likely to
965 stumble over almost every one of the possible errors below,
966 so please read carefully. The following are all of the
967 problems I ran into on a system running Fedora 7, with a
968 fresh installation of Apache, and a user account that I
969 created specially to perform this exercise.</para>
971 <para>Your web server may have per-user directories disabled.
972 If you're using Apache, search your config file for a
973 <literal>UserDir</literal> directive. If there's none
974 present, per-user directories will be disabled. If one
975 exists, but its value is <literal>disabled</literal>, then
976 per-user directories will be disabled. Otherwise, the
977 string after <literal>UserDir</literal> gives the name of
978 the subdirectory that Apache will look in under your home
979 directory, for example <filename
980 class="directory">public_html</filename>.</para>
982 <para>Your file access permissions may be too restrictive.
983 The web server must be able to traverse your home directory
984 and directories under your <filename
985 class="directory">public_html</filename> directory, and
986 read files under the latter too. Here's a quick recipe to
987 help you to make your permissions more appropriate.</para>
988 <programlisting>chmod 755 ~ find ~/public_html -type d -print0
989 | xargs -0r chmod 755 find ~/public_html -type f -print0 |
990 xargs -0r chmod 644</programlisting>
992 <para>The other possibility with permissions is that you might
993 get a completely empty window when you try to load the
994 script. In this case, it's likely that your access
995 permissions are <emphasis>too permissive</emphasis>. Apache's
996 <literal>suexec</literal> subsystem won't execute a script
997 that's group- or world-writable, for example.</para>
999 <para>Your web server may be configured to disallow execution
1000 of CGI programs in your per-user web directory. Here's
1001 Apache's default per-user configuration from my Fedora
1002 system.</para>
1003 <programlisting><Directory /home/*/public_html>
1004 AllowOverride FileInfo AuthConfig Limit Options MultiViews
1005 Indexes SymLinksIfOwnerMatch IncludesNoExec <Limit GET
1006 POST OPTIONS> Order allow,deny Allow from all
1007 </Limit> <LimitExcept GET POST OPTIONS> Order
1008 deny,allow Deny from all </LimitExcept>
1009 </Directory></programlisting>
1010 <para>If you find a similar-looking
1011 <literal>Directory</literal> group in your Apache
1012 configuration, the directive to look at inside it is
1013 <literal>Options</literal>. Add <literal>ExecCGI</literal>
1014 to the end of this list if it's missing, and restart the web
1015 server.</para>
1017 <para>If you find that Apache serves you the text of the CGI
1018 script instead of executing it, you may need to either
1019 uncomment (if already present) or add a directive like
1020 this.</para>
1021 <programlisting>AddHandler cgi-script .cgi</programlisting>
1023 <para>The next possibility is that you might be served with a
1024 colourful Python backtrace claiming that it can't import a
1025 <literal>mercurial</literal>-related module. This is
1026 actually progress! The server is now capable of executing
1027 your CGI script. This error is only likely to occur if
1028 you're running a private installation of Mercurial, instead
1029 of a system-wide version. Remember that the web server runs
1030 the CGI program without any of the environment variables
1031 that you take for granted in an interactive session. If
1032 this error happens to you, edit your copy of <filename
1033 role="special">hgweb.cgi</filename> and follow the
1034 directions inside it to correctly set your
1035 <envar>PYTHONPATH</envar> environment variable.</para>
1037 <para>Finally, you are <emphasis>certain</emphasis> to by
1038 served with another colourful Python backtrace: this one
1039 will complain that it can't find <filename
1040 class="directory">/path/to/repository</filename>. Edit
1041 your <filename role="special">hgweb.cgi</filename> script
1042 and replace the <filename
1043 class="directory">/path/to/repository</filename> string
1044 with the complete path to the repository you want to serve
1045 up.</para>
1047 <para>At this point, when you try to reload the page, you
1048 should be presented with a nice HTML view of your
1049 repository's history. Whew!</para>
1051 </sect3>
1052 <sect3>
1053 <title>Configuring lighttpd</title>
1055 <para>To be exhaustive in my experiments, I tried configuring
1056 the increasingly popular <literal>lighttpd</literal> web
1057 server to serve the same repository as I described with
1058 Apache above. I had already overcome all of the problems I
1059 outlined with Apache, many of which are not server-specific.
1060 As a result, I was fairly sure that my file and directory
1061 permissions were good, and that my <filename
1062 role="special">hgweb.cgi</filename> script was properly
1063 edited.</para>
1065 <para>Once I had Apache running, getting
1066 <literal>lighttpd</literal> to serve the repository was a
1067 snap (in other words, even if you're trying to use
1068 <literal>lighttpd</literal>, you should read the Apache
1069 section). I first had to edit the
1070 <literal>mod_access</literal> section of its config file to
1071 enable <literal>mod_cgi</literal> and
1072 <literal>mod_userdir</literal>, both of which were disabled
1073 by default on my system. I then added a few lines to the
1074 end of the config file, to configure these modules.</para>
1075 <programlisting>userdir.path = "public_html" cgi.assign = (
1076 ".cgi" => "" )</programlisting>
1077 <para>With this done, <literal>lighttpd</literal> ran
1078 immediately for me. If I had configured
1079 <literal>lighttpd</literal> before Apache, I'd almost
1080 certainly have run into many of the same system-level
1081 configuration problems as I did with Apache. However, I
1082 found <literal>lighttpd</literal> to be noticeably easier to
1083 configure than Apache, even though I've used Apache for over
1084 a decade, and this was my first exposure to
1085 <literal>lighttpd</literal>.</para>
1087 </sect3>
1088 </sect2>
1089 <sect2>
1090 <title>Sharing multiple repositories with one CGI script</title>
1092 <para>The <filename role="special">hgweb.cgi</filename> script
1093 only lets you publish a single repository, which is an
1094 annoying restriction. If you want to publish more than one
1095 without wracking yourself with multiple copies of the same
1096 script, each with different names, a better choice is to use
1097 the <filename role="special">hgwebdir.cgi</filename>
1098 script.</para>
1100 <para>The procedure to configure <filename
1101 role="special">hgwebdir.cgi</filename> is only a little more
1102 involved than for <filename
1103 role="special">hgweb.cgi</filename>. First, you must obtain
1104 a copy of the script. If you don't have one handy, you can
1105 download a copy from the master Mercurial repository at <ulink
1106 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>
1108 <para>You'll need to copy this script into your <filename
1109 class="directory">public_html</filename> directory, and
1110 ensure that it's executable.</para>
1111 <programlisting>cp .../hgwebdir.cgi ~/public_html chmod 755
1112 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
1113 <para>With basic configuration out of the way, try to visit
1114 <ulink url="http://myhostname/
1115 myuser/hgwebdir.cgi">http://myhostname/
1116 myuser/hgwebdir.cgi</ulink> in your browser. It should
1117 display an empty list of repositories. If you get a blank
1118 window or error message, try walking through the list of
1119 potential problems in section <xref
1120 linkend="sec:collab:wtf"/>.</para>
1122 <para>The <filename role="special">hgwebdir.cgi</filename>
1123 script relies on an external configuration file. By default,
1124 it searches for a file named <filename
1125 role="special">hgweb.config</filename> in the same directory
1126 as itself. You'll need to create this file, and make it
1127 world-readable. The format of the file is similar to a
1128 Windows <quote>ini</quote> file, as understood by Python's
1129 <literal>ConfigParser</literal>
1130 <citation>web:configparser</citation> module.</para>
1132 <para>The easiest way to configure <filename
1133 role="special">hgwebdir.cgi</filename> is with a section
1134 named <literal>collections</literal>. This will automatically
1135 publish <emphasis>every</emphasis> repository under the
1136 directories you name. The section should look like
1137 this:</para>
1138 <programlisting>[collections] /my/root =
1139 /my/root</programlisting>
1140 <para>Mercurial interprets this by looking at the directory name
1141 on the <emphasis>right</emphasis> hand side of the
1142 <quote><literal>=</literal></quote> sign; finding repositories
1143 in that directory hierarchy; and using the text on the
1144 <emphasis>left</emphasis> to strip off matching text from the
1145 names it will actually list in the web interface. The
1146 remaining component of a path after this stripping has
1147 occurred is called a <quote>virtual path</quote>.</para>
1149 <para>Given the example above, if we have a repository whose
1150 local path is <filename
1151 class="directory">/my/root/this/repo</filename>, the CGI
1152 script will strip the leading <filename
1153 class="directory">/my/root</filename> from the name, and
1154 publish the repository with a virtual path of <filename
1155 class="directory">this/repo</filename>. If the base URL for
1156 our CGI script is <ulink url="http://myhostname/
1157 myuser/hgwebdir.cgi">http://myhostname/
1158 myuser/hgwebdir.cgi</ulink>, the complete URL for that
1159 repository will be <ulink url="http://myhostname/
1160 myuser/hgwebdir.cgi/this/repo">http://myhostname/
1161 myuser/hgwebdir.cgi/this/repo</ulink>.</para>
1163 <para>If we replace <filename
1164 class="directory">/my/root</filename> on the left hand side
1165 of this example with <filename
1166 class="directory">/my</filename>, then <filename
1167 role="special">hgwebdir.cgi</filename> will only strip off
1168 <filename class="directory">/my</filename> from the repository
1169 name, and will give us a virtual path of <filename
1170 class="directory">root/this/repo</filename> instead of
1171 <filename class="directory">this/repo</filename>.</para>
1173 <para>The <filename role="special">hgwebdir.cgi</filename>
1174 script will recursively search each directory listed in the
1175 <literal>collections</literal> section of its configuration
1176 file, but it will <literal>not</literal> recurse into the
1177 repositories it finds.</para>
1179 <para>The <literal>collections</literal> mechanism makes it easy
1180 to publish many repositories in a <quote>fire and
1181 forget</quote> manner. You only need to set up the CGI
1182 script and configuration file one time. Afterwards, you can
1183 publish or unpublish a repository at any time by simply moving
1184 it into, or out of, the directory hierarchy in which you've
1185 configured <filename role="special">hgwebdir.cgi</filename> to
1186 look.</para>
1188 <sect3>
1189 <title>Explicitly specifying which repositories to
1190 publish</title>
1192 <para>In addition to the <literal>collections</literal>
1193 mechanism, the <filename
1194 role="special">hgwebdir.cgi</filename> script allows you
1195 to publish a specific list of repositories. To do so,
1196 create a <literal>paths</literal> section, with contents of
1197 the following form.</para>
1198 <programlisting>[paths] repo1 = /my/path/to/some/repo repo2 =
1199 /some/path/to/another</programlisting>
1200 <para>In this case, the virtual path (the component that will
1201 appear in a URL) is on the left hand side of each
1202 definition, while the path to the repository is on the
1203 right. Notice that there does not need to be any
1204 relationship between the virtual path you choose and the
1205 location of a repository in your filesystem.</para>
1207 <para>If you wish, you can use both the
1208 <literal>collections</literal> and <literal>paths</literal>
1209 mechanisms simultaneously in a single configuration
1210 file.</para>
1212 <note>
1213 <para> If multiple repositories have the same virtual path,
1214 <filename role="special">hgwebdir.cgi</filename> will not
1215 report an error. Instead, it will behave
1216 unpredictably.</para>
1217 </note>
1219 </sect3>
1220 </sect2>
1221 <sect2>
1222 <title>Downloading source archives</title>
1224 <para>Mercurial's web interface lets users download an archive
1225 of any revision. This archive will contain a snapshot of the
1226 working directory as of that revision, but it will not contain
1227 a copy of the repository data.</para>
1229 <para>By default, this feature is not enabled. To enable it,
1230 you'll need to add an <envar
1231 role="rc-item-web">allow_archive</envar> item to the
1232 <literal role="rc-web">web</literal> section of your <filename
1233 role="special"> /.hgrc</filename>.</para>
1235 </sect2>
1236 <sect2>
1237 <title>Web configuration options</title>
1239 <para>Mercurial's web interfaces (the <command role="hg-cmd">hg
1240 serve</command> command, and the <filename
1241 role="special">hgweb.cgi</filename> and <filename
1242 role="special">hgwebdir.cgi</filename> scripts) have a
1243 number of configuration options that you can set. These
1244 belong in a section named <literal
1245 role="rc-web">web</literal>.</para>
1246 <itemizedlist>
1247 <listitem><para><envar
1248 role="rc-item-web">allow_archive</envar>: Determines
1249 which (if any) archive download mechanisms Mercurial
1250 supports. If you enable this feature, users of the web
1251 interface will be able to download an archive of whatever
1252 revision of a repository they are viewing. To enable the
1253 archive feature, this item must take the form of a
1254 sequence of words drawn from the list below.</para>
1255 <itemizedlist>
1256 <listitem><para><literal>bz2</literal>: A
1257 <command>tar</command> archive, compressed using
1258 <literal>bzip2</literal> compression. This has the
1259 best compression ratio, but uses the most CPU time on
1260 the server.</para>
1261 </listitem>
1262 <listitem><para><literal>gz</literal>: A
1263 <command>tar</command> archive, compressed using
1264 <literal>gzip</literal> compression.</para>
1265 </listitem>
1266 <listitem><para><literal>zip</literal>: A
1267 <command>zip</command> archive, compressed using LZW
1268 compression. This format has the worst compression
1269 ratio, but is widely used in the Windows world.</para>
1270 </listitem>
1271 </itemizedlist>
1272 <para> If you provide an empty list, or don't have an
1273 <envar role="rc-item-web">allow_archive</envar> entry at
1274 all, this feature will be disabled. Here is an example of
1275 how to enable all three supported formats.</para>
1276 <programlisting>[web] allow_archive = bz2 gz
1277 zip</programlisting>
1278 </listitem>
1279 <listitem><para><envar role="rc-item-web">allowpull</envar>:
1280 Boolean. Determines whether the web interface allows
1281 remote users to <command role="hg-cmd">hg pull</command>
1282 and <command role="hg-cmd">hg clone</command> this
1283 repository over HTTP. If set to <literal>no</literal> or
1284 <literal>false</literal>, only the
1285 <quote>human-oriented</quote> portion of the web interface
1286 is available.</para>
1287 </listitem>
1288 <listitem><para><envar role="rc-item-web">contact</envar>:
1289 String. A free-form (but preferably brief) string
1290 identifying the person or group in charge of the
1291 repository. This often contains the name and email
1292 address of a person or mailing list. It often makes sense
1293 to place this entry in a repository's own <filename
1294 role="special">.hg/hgrc</filename> file, but it can make
1295 sense to use in a global <filename role="special">
1296 /.hgrc</filename>\ if every repository has a single
1297 maintainer.</para>
1298 </listitem>
1299 <listitem><para><envar role="rc-item-web">maxchanges</envar>:
1300 Integer. The default maximum number of changesets to
1301 display in a single page of output.</para>
1302 </listitem>
1303 <listitem><para><envar role="rc-item-web">maxfiles</envar>:
1304 Integer. The default maximum number of modified files to
1305 display in a single page of output.</para>
1306 </listitem>
1307 <listitem><para><envar role="rc-item-web">stripes</envar>:
1308 Integer. If the web interface displays alternating
1309 <quote>stripes</quote> to make it easier to visually align
1310 rows when you are looking at a table, this number controls
1311 the number of rows in each stripe.</para>
1312 </listitem>
1313 <listitem><para><envar role="rc-item-web">style</envar>:
1314 Controls the template Mercurial uses to display the web
1315 interface. Mercurial ships with two web templates, named
1316 <literal>default</literal> and <literal>gitweb</literal>
1317 (the latter is much more visually attractive). You can
1318 also specify a custom template of your own; see chapter
1319 <xref linkend="chap:template"/> for details.
1320 Here, you can see how to enable the
1321 <literal>gitweb</literal> style.</para>
1322 <programlisting>[web] style = gitweb</programlisting>
1323 </listitem>
1324 <listitem><para><envar role="rc-item-web">templates</envar>:
1325 Path. The directory in which to search for template
1326 files. By default, Mercurial searches in the directory in
1327 which it was installed.</para>
1328 </listitem></itemizedlist>
1329 <para>If you are using <filename
1330 role="special">hgwebdir.cgi</filename>, you can place a few
1331 configuration items in a <literal role="rc-web">web</literal>
1332 section of the <filename
1333 role="special">hgweb.config</filename> file instead of a
1334 <filename role="special"> /.hgrc</filename>\ file, for
1335 convenience. These items are <envar
1336 role="rc-item-web">motd</envar> and <envar
1337 role="rc-item-web">style</envar>.</para>
1339 <sect3>
1340 <title>Options specific to an individual repository</title>
1342 <para>A few <literal role="rc-web">web</literal> configuration
1343 items ought to be placed in a repository's local <filename
1344 role="special">.hg/hgrc</filename>, rather than a user's
1345 or global <filename role="special">
1346 /.hgrc</filename>.</para>
1347 <itemizedlist>
1348 <listitem><para><envar
1349 role="rc-item-web">description</envar>: String. A
1350 free-form (but preferably brief) string that describes
1351 the contents or purpose of the repository.</para>
1352 </listitem>
1353 <listitem><para><envar role="rc-item-web">name</envar>:
1354 String. The name to use for the repository in the web
1355 interface. This overrides the default name, which is
1356 the last component of the repository's path.</para>
1357 </listitem></itemizedlist>
1359 </sect3>
1360 <sect3>
1361 <title>Options specific to the <command role="hg-cmd">hg
1362 serve</command> command</title>
1364 <para>Some of the items in the <literal
1365 role="rc-web">web</literal> section of a <filename
1366 role="special"> /.hgrc</filename>\ file are only for use
1367 with the <command role="hg-cmd">hg serve</command>
1368 command.</para>
1369 <itemizedlist>
1370 <listitem><para><envar role="rc-item-web">accesslog</envar>:
1371 Path. The name of a file into which to write an access
1372 log. By default, the <command role="hg-cmd">hg
1373 serve</command> command writes this information to
1374 standard output, not to a file. Log entries are written
1375 in the standard <quote>combined</quote> file format used
1376 by almost all web servers.</para>
1377 </listitem>
1378 <listitem><para><envar role="rc-item-web">address</envar>:
1379 String. The local address on which the server should
1380 listen for incoming connections. By default, the server
1381 listens on all addresses.</para>
1382 </listitem>
1383 <listitem><para><envar role="rc-item-web">errorlog</envar>:
1384 Path. The name of a file into which to write an error
1385 log. By default, the <command role="hg-cmd">hg
1386 serve</command> command writes this information to
1387 standard error, not to a file.</para>
1388 </listitem>
1389 <listitem><para><envar role="rc-item-web">ipv6</envar>:
1390 Boolean. Whether to use the IPv6 protocol. By default,
1391 IPv6 is not used.</para>
1392 </listitem>
1393 <listitem><para><envar role="rc-item-web">port</envar>:
1394 Integer. The TCP port number on which the server should
1395 listen. The default port number used is 8000.</para>
1396 </listitem></itemizedlist>
1398 </sect3>
1399 <sect3>
1400 <title>Choosing the right <filename role="special">
1401 /.hgrc</filename>\ file to add <literal
1402 role="rc-web">web</literal> items to</title>
1404 <para>It is important to remember that a web server like
1405 Apache or <literal>lighttpd</literal> will run under a user
1406 ID that is different to yours. CGI scripts run by your
1407 server, such as <filename
1408 role="special">hgweb.cgi</filename>, will usually also run
1409 under that user ID.</para>
1411 <para>If you add <literal role="rc-web">web</literal> items to
1412 your own personal <filename role="special">
1413 /.hgrc</filename>\ file, CGI scripts won't read that
1414 <filename role="special"> /.hgrc</filename>\ file. Those
1415 settings will thus only affect the behaviour of the <command
1416 role="hg-cmd">hg serve</command> command when you run it.
1417 To cause CGI scripts to see your settings, either create a
1418 <filename role="special"> /.hgrc</filename>\ file in the
1419 home directory of the user ID that runs your web server, or
1420 add those settings to a system-wide <filename
1421 role="special"> /.hgrc</filename>\ file.</para>
1424 </sect3>
1425 </sect2>
1426 </sect1>
1427 </chapter>
1429 <!--
1430 local variables:
1431 sgml-parent-document: ("00book.xml" "book" "chapter")
1432 end:
1433 -->