hgbook
view en/ch06-collab.xml @ 566:27043f385f3f
Get autogeneration of examples more or less working.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Mon Mar 09 22:55:38 2009 -0700 (2009-03-09) |
| parents | dbe91bb622d8 |
| children | 8fcd44708f41 |
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. <!-- &interaction.branching.init; --> People clone it,
204 make changes locally, test them, and push them back.</para>
206 <para>Once the main branch reaches a release milestone, you can
207 use the <command role="hg-cmd">hg tag</command> command to
208 give a permanent name to the milestone revision. <!--
209 &interaction.branching.tag; --> Let's say some ongoing
210 development occurs on the main branch. <!--
211 &interaction.branching.main; --> Using the tag that was
212 recorded at the milestone, people who clone that repository at
213 any time in the future can use <command role="hg-cmd">hg
214 update</command> to get a copy of the working directory
215 exactly as it was when that tagged revision was committed.
216 <!-- &interaction.branching.update; --></para>
218 <para>In addition, immediately after the main branch is tagged,
219 someone can then clone the main branch on the server to a new
220 <quote>stable</quote> branch, also on the server. <!--
221 &interaction.branching.clone; --></para>
223 <para>Someone who needs to make a change to the stable branch
224 can then clone <emphasis>that</emphasis> repository, make
225 their changes, commit, and push their changes back there. <!--
226 &interaction.branching.stable; --> Because Mercurial
227 repositories are independent, and Mercurial doesn't move
228 changes around automatically, the stable and main branches are
229 <emphasis>isolated</emphasis> from each other. The changes
230 that you made on the main branch don't <quote>leak</quote> to
231 the stable branch, and vice versa.</para>
233 <para>You'll often want all of your bugfixes on the stable
234 branch to show up on the main branch, too. Rather than
235 rewrite a bugfix on the main branch, you can simply pull and
236 merge changes from the stable to the main branch, and
237 Mercurial will bring those bugfixes in for you. <!--
238 &interaction.branching.merge; --> The main branch will still
239 contain changes that are not on the stable branch, but it will
240 also contain all of the bugfixes from the stable branch. The
241 stable branch remains unaffected by these changes.</para>
243 </sect2>
244 <sect2>
245 <title>Feature branches</title>
247 <para>For larger projects, an effective way to manage change is
248 to break up a team into smaller groups. Each group has a
249 shared branch of its own, cloned from a single
250 <quote>master</quote> branch used by the entire project.
251 People working on an individual branch are typically quite
252 isolated from developments on other branches.</para>
254 <informalfigure id="fig:collab:feature-branches">
255 <mediaobject><imageobject><imagedata
256 fileref="feature-branches"/></imageobject><textobject><phrase>XXX
257 add text</phrase></textobject><caption><para>Feature
258 branches</para></caption></mediaobject>
259 </informalfigure>
261 <para>When a particular feature is deemed to be in suitable
262 shape, someone on that feature team pulls and merges from the
263 master branch into the feature branch, then pushes back up to
264 the master branch.</para>
266 </sect2>
267 <sect2>
268 <title>The release train</title>
270 <para>Some projects are organised on a <quote>train</quote>
271 basis: a release is scheduled to happen every few months, and
272 whatever features are ready when the <quote>train</quote> is
273 ready to leave are allowed in.</para>
275 <para>This model resembles working with feature branches. The
276 difference is that when a feature branch misses a train,
277 someone on the feature team pulls and merges the changes that
278 went out on that train release into the feature branch, and
279 the team continues its work on top of that release so that
280 their feature can make the next release.</para>
282 </sect2>
283 <sect2>
284 <title>The Linux kernel model</title>
286 <para>The development of the Linux kernel has a shallow
287 hierarchical structure, surrounded by a cloud of apparent
288 chaos. Because most Linux developers use
289 <command>git</command>, a distributed revision control tool
290 with capabilities similar to Mercurial, it's useful to
291 describe the way work flows in that environment; if you like
292 the ideas, the approach translates well across tools.</para>
294 <para>At the center of the community sits Linus Torvalds, the
295 creator of Linux. He publishes a single source repository
296 that is considered the <quote>authoritative</quote> current
297 tree by the entire developer community. Anyone can clone
298 Linus's tree, but he is very choosy about whose trees he pulls
299 from.</para>
301 <para>Linus has a number of <quote>trusted lieutenants</quote>.
302 As a general rule, he pulls whatever changes they publish, in
303 most cases without even reviewing those changes. Some of
304 those lieutenants are generally agreed to be
305 <quote>maintainers</quote>, responsible for specific
306 subsystems within the kernel. If a random kernel hacker wants
307 to make a change to a subsystem that they want to end up in
308 Linus's tree, they must find out who the subsystem's
309 maintainer is, and ask that maintainer to take their change.
310 If the maintainer reviews their changes and agrees to take
311 them, they'll pass them along to Linus in due course.</para>
313 <para>Individual lieutenants have their own approaches to
314 reviewing, accepting, and publishing changes; and for deciding
315 when to feed them to Linus. In addition, there are several
316 well known branches that people use for different purposes.
317 For example, a few people maintain <quote>stable</quote>
318 repositories of older versions of the kernel, to which they
319 apply critical fixes as needed. Some maintainers publish
320 multiple trees: one for experimental changes; one for changes
321 that they are about to feed upstream; and so on. Others just
322 publish a single tree.</para>
324 <para>This model has two notable features. The first is that
325 it's <quote>pull only</quote>. You have to ask, convince, or
326 beg another developer to take a change from you, because there
327 are almost no trees to which more than one person can push,
328 and there's no way to push changes into a tree that someone
329 else controls.</para>
331 <para>The second is that it's based on reputation and acclaim.
332 If you're an unknown, Linus will probably ignore changes from
333 you without even responding. But a subsystem maintainer will
334 probably review them, and will likely take them if they pass
335 their criteria for suitability. The more <quote>good</quote>
336 changes you contribute to a maintainer, the more likely they
337 are to trust your judgment and accept your changes. If you're
338 well-known and maintain a long-lived branch for something
339 Linus hasn't yet accepted, people with similar interests may
340 pull your changes regularly to keep up with your work.</para>
342 <para>Reputation and acclaim don't necessarily cross subsystem
343 or <quote>people</quote> boundaries. If you're a respected
344 but specialised storage hacker, and you try to fix a
345 networking bug, that change will receive a level of scrutiny
346 from a network maintainer comparable to a change from a
347 complete stranger.</para>
349 <para>To people who come from more orderly project backgrounds,
350 the comparatively chaotic Linux kernel development process
351 often seems completely insane. It's subject to the whims of
352 individuals; people make sweeping changes whenever they deem
353 it appropriate; and the pace of development is astounding.
354 And yet Linux is a highly successful, well-regarded piece of
355 software.</para>
357 </sect2>
358 <sect2>
359 <title>Pull-only versus shared-push collaboration</title>
361 <para>A perpetual source of heat in the open source community is
362 whether a development model in which people only ever pull
363 changes from others is <quote>better than</quote> one in which
364 multiple people can push changes to a shared
365 repository.</para>
367 <para>Typically, the backers of the shared-push model use tools
368 that actively enforce this approach. If you're using a
369 centralised revision control tool such as Subversion, there's
370 no way to make a choice over which model you'll use: the tool
371 gives you shared-push, and if you want to do anything else,
372 you'll have to roll your own approach on top (such as applying
373 a patch by hand).</para>
375 <para>A good distributed revision control tool, such as
376 Mercurial, will support both models. You and your
377 collaborators can then structure how you work together based
378 on your own needs and preferences, not on what contortions
379 your tools force you into.</para>
381 </sect2>
382 <sect2>
383 <title>Where collaboration meets branch management</title>
385 <para>Once you and your team set up some shared repositories and
386 start propagating changes back and forth between local and
387 shared repos, you begin to face a related, but slightly
388 different challenge: that of managing the multiple directions
389 in which your team may be moving at once. Even though this
390 subject is intimately related to how your team collaborates,
391 it's dense enough to merit treatment of its own, in chapter
392 <xref linkend="chap:branch"/>.</para>
394 </sect2>
395 </sect1>
396 <sect1>
397 <title>The technical side of sharing</title>
399 <para>The remainder of this chapter is devoted to the question of
400 serving data to your collaborators.</para>
402 </sect1>
403 <sect1 id="sec:collab:serve">
404 <title>Informal sharing with <command role="hg-cmd">hg
405 serve</command></title>
407 <para>Mercurial's <command role="hg-cmd">hg serve</command>
408 command is wonderfully suited to small, tight-knit, and
409 fast-paced group environments. It also provides a great way to
410 get a feel for using Mercurial commands over a network.</para>
412 <para>Run <command role="hg-cmd">hg serve</command> inside a
413 repository, and in under a second it will bring up a specialised
414 HTTP server; this will accept connections from any client, and
415 serve up data for that repository until you terminate it.
416 Anyone who knows the URL of the server you just started, and can
417 talk to your computer over the network, can then use a web
418 browser or Mercurial to read data from that repository. A URL
419 for a <command role="hg-cmd">hg serve</command> instance running
420 on a laptop is likely to look something like
421 <literal>http://my-laptop.local:8000/</literal>.</para>
423 <para>The <command role="hg-cmd">hg serve</command> command is
424 <emphasis>not</emphasis> a general-purpose web server. It can do
425 only two things:</para>
426 <itemizedlist>
427 <listitem><para>Allow people to browse the history of the
428 repository it's serving, from their normal web
429 browsers.</para>
430 </listitem>
431 <listitem><para>Speak Mercurial's wire protocol, so that people
432 can <command role="hg-cmd">hg clone</command> or <command
433 role="hg-cmd">hg pull</command> changes from that
434 repository.</para>
435 </listitem></itemizedlist>
436 <para>In particular, <command role="hg-cmd">hg serve</command>
437 won't allow remote users to <emphasis>modify</emphasis> your
438 repository. It's intended for read-only use.</para>
440 <para>If you're getting started with Mercurial, there's nothing to
441 prevent you from using <command role="hg-cmd">hg serve</command>
442 to serve up a repository on your own computer, then use commands
443 like <command role="hg-cmd">hg clone</command>, <command
444 role="hg-cmd">hg incoming</command>, and so on to talk to that
445 server as if the repository was hosted remotely. This can help
446 you to quickly get acquainted with using commands on
447 network-hosted repositories.</para>
449 <sect2>
450 <title>A few things to keep in mind</title>
452 <para>Because it provides unauthenticated read access to all
453 clients, you should only use <command role="hg-cmd">hg
454 serve</command> in an environment where you either don't
455 care, or have complete control over, who can access your
456 network and pull data from your repository.</para>
458 <para>The <command role="hg-cmd">hg serve</command> command
459 knows nothing about any firewall software you might have
460 installed on your system or network. It cannot detect or
461 control your firewall software. If other people are unable to
462 talk to a running <command role="hg-cmd">hg serve</command>
463 instance, the second thing you should do
464 (<emphasis>after</emphasis> you make sure that they're using
465 the correct URL) is check your firewall configuration.</para>
467 <para>By default, <command role="hg-cmd">hg serve</command>
468 listens for incoming connections on port 8000. If another
469 process is already listening on the port you want to use, you
470 can specify a different port to listen on using the <option
471 role="hg-opt-serve">-p</option> option.</para>
473 <para>Normally, when <command role="hg-cmd">hg serve</command>
474 starts, it prints no output, which can be a bit unnerving. If
475 you'd like to confirm that it is indeed running correctly, and
476 find out what URL you should send to your collaborators, start
477 it with the <option role="hg-opt-global">-v</option>
478 option.</para>
480 </sect2>
481 </sect1>
482 <sect1 id="sec:collab:ssh">
483 <title>Using the Secure Shell (ssh) protocol</title>
485 <para>You can pull and push changes securely over a network
486 connection using the Secure Shell (<literal>ssh</literal>)
487 protocol. To use this successfully, you may have to do a little
488 bit of configuration on the client or server sides.</para>
490 <para>If you're not familiar with ssh, it's a network protocol
491 that lets you securely communicate with another computer. To
492 use it with Mercurial, you'll be setting up one or more user
493 accounts on a server so that remote users can log in and execute
494 commands.</para>
496 <para>(If you <emphasis>are</emphasis> familiar with ssh, you'll
497 probably find some of the material that follows to be elementary
498 in nature.)</para>
500 <sect2>
501 <title>How to read and write ssh URLs</title>
503 <para>An ssh URL tends to look like this:</para>
504 <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting>
505 <orderedlist>
506 <listitem><para>The <quote><literal>ssh://</literal></quote>
507 part tells Mercurial to use the ssh protocol.</para>
508 </listitem>
509 <listitem><para>The <quote><literal>bos@</literal></quote>
510 component indicates what username to log into the server
511 as. You can leave this out if the remote username is the
512 same as your local username.</para>
513 </listitem>
514 <listitem><para>The
515 <quote><literal>hg.serpentine.com</literal></quote> gives
516 the hostname of the server to log into.</para>
517 </listitem>
518 <listitem><para>The <quote>:22</quote> identifies the port
519 number to connect to the server on. The default port is
520 22, so you only need to specify this part if you're
521 <emphasis>not</emphasis> using port 22.</para>
522 </listitem>
523 <listitem><para>The remainder of the URL is the local path to
524 the repository on the server.</para>
525 </listitem></orderedlist>
527 <para>There's plenty of scope for confusion with the path
528 component of ssh URLs, as there is no standard way for tools
529 to interpret it. Some programs behave differently than others
530 when dealing with these paths. This isn't an ideal situation,
531 but it's unlikely to change. Please read the following
532 paragraphs carefully.</para>
534 <para>Mercurial treats the path to a repository on the server as
535 relative to the remote user's home directory. For example, if
536 user <literal>foo</literal> on the server has a home directory
537 of <filename class="directory">/home/foo</filename>, then an
538 ssh URL that contains a path component of <filename
539 class="directory">bar</filename> <emphasis>really</emphasis>
540 refers to the directory <filename
541 class="directory">/home/foo/bar</filename>.</para>
543 <para>If you want to specify a path relative to another user's
544 home directory, you can use a path that starts with a tilde
545 character followed by the user's name (let's call them
546 <literal>otheruser</literal>), like this.</para>
547 <programlisting>ssh://server/~otheruser/hg/repo</programlisting>
549 <para>And if you really want to specify an
550 <emphasis>absolute</emphasis> path on the server, begin the
551 path component with two slashes, as in this example.</para>
552 <programlisting>ssh://server//absolute/path</programlisting>
554 </sect2>
555 <sect2>
556 <title>Finding an ssh client for your system</title>
558 <para>Almost every Unix-like system comes with OpenSSH
559 preinstalled. If you're using such a system, run
560 <literal>which ssh</literal> to find out if the
561 <command>ssh</command> command is installed (it's usually in
562 <filename class="directory">/usr/bin</filename>). In the
563 unlikely event that it isn't present, take a look at your
564 system documentation to figure out how to install it.</para>
566 <para>On Windows, you'll first need to download a suitable ssh
567 client. There are two alternatives.</para>
568 <itemizedlist>
569 <listitem><para>Simon Tatham's excellent PuTTY package
570 <citation>web:putty</citation> provides a complete suite
571 of ssh client commands.</para>
572 </listitem>
573 <listitem><para>If you have a high tolerance for pain, you can
574 use the Cygwin port of OpenSSH.</para>
575 </listitem></itemizedlist>
576 <para>In either case, you'll need to edit your \hgini\ file to
577 tell Mercurial where to find the actual client command. For
578 example, if you're using PuTTY, you'll need to use the
579 <command>plink</command> command as a command-line ssh
580 client.</para>
581 <programlisting>[ui] ssh = C:/path/to/plink.exe -ssh -i
582 "C:/path/to/my/private/key"</programlisting>
584 <note>
585 <para> The path to <command>plink</command> shouldn't contain
586 any whitespace characters, or Mercurial may not be able to
587 run it correctly (so putting it in <filename
588 class="directory">C:\\Program Files</filename> is probably
589 not a good idea).</para>
590 </note>
592 </sect2>
593 <sect2>
594 <title>Generating a key pair</title>
596 <para>To avoid the need to repetitively type a password every
597 time you need to use your ssh client, I recommend generating a
598 key pair. On a Unix-like system, the
599 <command>ssh-keygen</command> command will do the trick. On
600 Windows, if you're using PuTTY, the
601 <command>puttygen</command> command is what you'll
602 need.</para>
604 <para>When you generate a key pair, it's usually
605 <emphasis>highly</emphasis> advisable to protect it with a
606 passphrase. (The only time that you might not want to do this
607 is when you're using the ssh protocol for automated tasks on a
608 secure network.)</para>
610 <para>Simply generating a key pair isn't enough, however.
611 You'll need to add the public key to the set of authorised
612 keys for whatever user you're logging in remotely as. For
613 servers using OpenSSH (the vast majority), this will mean
614 adding the public key to a list in a file called <filename
615 role="special">authorized_keys</filename> in their <filename
616 role="special" class="directory">.ssh</filename>
617 directory.</para>
619 <para>On a Unix-like system, your public key will have a
620 <filename>.pub</filename> extension. If you're using
621 <command>puttygen</command> on Windows, you can save the
622 public key to a file of your choosing, or paste it from the
623 window it's displayed in straight into the <filename
624 role="special">authorized_keys</filename> file.</para>
626 </sect2>
627 <sect2>
628 <title>Using an authentication agent</title>
630 <para>An authentication agent is a daemon that stores
631 passphrases in memory (so it will forget passphrases if you
632 log out and log back in again). An ssh client will notice if
633 it's running, and query it for a passphrase. If there's no
634 authentication agent running, or the agent doesn't store the
635 necessary passphrase, you'll have to type your passphrase
636 every time Mercurial tries to communicate with a server on
637 your behalf (e.g. whenever you pull or push changes).</para>
639 <para>The downside of storing passphrases in an agent is that
640 it's possible for a well-prepared attacker to recover the
641 plain text of your passphrases, in some cases even if your
642 system has been power-cycled. You should make your own
643 judgment as to whether this is an acceptable risk. It
644 certainly saves a lot of repeated typing.</para>
646 <para>On Unix-like systems, the agent is called
647 <command>ssh-agent</command>, and it's often run automatically
648 for you when you log in. You'll need to use the
649 <command>ssh-add</command> command to add passphrases to the
650 agent's store. On Windows, if you're using PuTTY, the
651 <command>pageant</command> command acts as the agent. It adds
652 an icon to your system tray that will let you manage stored
653 passphrases.</para>
655 </sect2>
656 <sect2>
657 <title>Configuring the server side properly</title>
659 <para>Because ssh can be fiddly to set up if you're new to it,
660 there's a variety of things that can go wrong. Add Mercurial
661 on top, and there's plenty more scope for head-scratching.
662 Most of these potential problems occur on the server side, not
663 the client side. The good news is that once you've gotten a
664 configuration working, it will usually continue to work
665 indefinitely.</para>
667 <para>Before you try using Mercurial to talk to an ssh server,
668 it's best to make sure that you can use the normal
669 <command>ssh</command> or <command>putty</command> command to
670 talk to the server first. If you run into problems with using
671 these commands directly, Mercurial surely won't work. Worse,
672 it will obscure the underlying problem. Any time you want to
673 debug ssh-related Mercurial problems, you should drop back to
674 making sure that plain ssh client commands work first,
675 <emphasis>before</emphasis> you worry about whether there's a
676 problem with Mercurial.</para>
678 <para>The first thing to be sure of on the server side is that
679 you can actually log in from another machine at all. If you
680 can't use <command>ssh</command> or <command>putty</command>
681 to log in, the error message you get may give you a few hints
682 as to what's wrong. The most common problems are as
683 follows.</para>
684 <itemizedlist>
685 <listitem><para>If you get a <quote>connection refused</quote>
686 error, either there isn't an SSH daemon running on the
687 server at all, or it's inaccessible due to firewall
688 configuration.</para>
689 </listitem>
690 <listitem><para>If you get a <quote>no route to host</quote>
691 error, you either have an incorrect address for the server
692 or a seriously locked down firewall that won't admit its
693 existence at all.</para>
694 </listitem>
695 <listitem><para>If you get a <quote>permission denied</quote>
696 error, you may have mistyped the username on the server,
697 or you could have mistyped your key's passphrase or the
698 remote user's password.</para>
699 </listitem></itemizedlist>
700 <para>In summary, if you're having trouble talking to the
701 server's ssh daemon, first make sure that one is running at
702 all. On many systems it will be installed, but disabled, by
703 default. Once you're done with this step, you should then
704 check that the server's firewall is configured to allow
705 incoming connections on the port the ssh daemon is listening
706 on (usually 22). Don't worry about more exotic possibilities
707 for misconfiguration until you've checked these two
708 first.</para>
710 <para>If you're using an authentication agent on the client side
711 to store passphrases for your keys, you ought to be able to
712 log into the server without being prompted for a passphrase or
713 a password. If you're prompted for a passphrase, there are a
714 few possible culprits.</para>
715 <itemizedlist>
716 <listitem><para>You might have forgotten to use
717 <command>ssh-add</command> or <command>pageant</command>
718 to store the passphrase.</para>
719 </listitem>
720 <listitem><para>You might have stored the passphrase for the
721 wrong key.</para>
722 </listitem></itemizedlist>
723 <para>If you're being prompted for the remote user's password,
724 there are another few possible problems to check.</para>
725 <itemizedlist>
726 <listitem><para>Either the user's home directory or their
727 <filename role="special" class="directory">.ssh</filename>
728 directory might have excessively liberal permissions. As
729 a result, the ssh daemon will not trust or read their
730 <filename role="special">authorized_keys</filename> file.
731 For example, a group-writable home or <filename
732 role="special" class="directory">.ssh</filename>
733 directory will often cause this symptom.</para>
734 </listitem>
735 <listitem><para>The user's <filename
736 role="special">authorized_keys</filename> file may have
737 a problem. If anyone other than the user owns or can write
738 to that file, the ssh daemon will not trust or read
739 it.</para>
740 </listitem></itemizedlist>
742 <para>In the ideal world, you should be able to run the
743 following command successfully, and it should print exactly
744 one line of output, the current date and time.</para>
745 <programlisting>ssh myserver date</programlisting>
747 <para>If, on your server, you have login scripts that print
748 banners or other junk even when running non-interactive
749 commands like this, you should fix them before you continue,
750 so that they only print output if they're run interactively.
751 Otherwise these banners will at least clutter up Mercurial's
752 output. Worse, they could potentially cause problems with
753 running Mercurial commands remotely. Mercurial makes tries to
754 detect and ignore banners in non-interactive
755 <command>ssh</command> sessions, but it is not foolproof. (If
756 you're editing your login scripts on your server, the usual
757 way to see if a login script is running in an interactive
758 shell is to check the return code from the command
759 <literal>tty -s</literal>.)</para>
761 <para>Once you've verified that plain old ssh is working with
762 your server, the next step is to ensure that Mercurial runs on
763 the server. The following command should run
764 successfully:</para>
765 <programlisting>ssh myserver hg version</programlisting>
766 <para>If you see an error message instead of normal <command
767 role="hg-cmd">hg version</command> output, this is usually
768 because you haven't installed Mercurial to <filename
769 class="directory">/usr/bin</filename>. Don't worry if this
770 is the case; you don't need to do that. But you should check
771 for a few possible problems.</para>
772 <itemizedlist>
773 <listitem><para>Is Mercurial really installed on the server at
774 all? I know this sounds trivial, but it's worth
775 checking!</para>
776 </listitem>
777 <listitem><para>Maybe your shell's search path (usually set
778 via the <envar>PATH</envar> environment variable) is
779 simply misconfigured.</para>
780 </listitem>
781 <listitem><para>Perhaps your <envar>PATH</envar> environment
782 variable is only being set to point to the location of the
783 <command>hg</command> executable if the login session is
784 interactive. This can happen if you're setting the path
785 in the wrong shell login script. See your shell's
786 documentation for details.</para>
787 </listitem>
788 <listitem><para>The <envar>PYTHONPATH</envar> environment
789 variable may need to contain the path to the Mercurial
790 Python modules. It might not be set at all; it could be
791 incorrect; or it may be set only if the login is
792 interactive.</para>
793 </listitem></itemizedlist>
795 <para>If you can run <command role="hg-cmd">hg version</command>
796 over an ssh connection, well done! You've got the server and
797 client sorted out. You should now be able to use Mercurial to
798 access repositories hosted by that username on that server.
799 If you run into problems with Mercurial and ssh at this point,
800 try using the <option role="hg-opt-global">--debug</option>
801 option to get a clearer picture of what's going on.</para>
803 </sect2>
804 <sect2>
805 <title>Using compression with ssh</title>
807 <para>Mercurial does not compress data when it uses the ssh
808 protocol, because the ssh protocol can transparently compress
809 data. However, the default behaviour of ssh clients is
810 <emphasis>not</emphasis> to request compression.</para>
812 <para>Over any network other than a fast LAN (even a wireless
813 network), using compression is likely to significantly speed
814 up Mercurial's network operations. For example, over a WAN,
815 someone measured compression as reducing the amount of time
816 required to clone a particularly large repository from 51
817 minutes to 17 minutes.</para>
819 <para>Both <command>ssh</command> and <command>plink</command>
820 accept a <option role="cmd-opt-ssh">-C</option> option which
821 turns on compression. You can easily edit your <filename
822 role="special"> /.hgrc</filename>\ to enable compression for
823 all of Mercurial's uses of the ssh protocol.</para>
824 <programlisting>[ui] ssh = ssh -C</programlisting>
826 <para>If you use <command>ssh</command>, you can configure it to
827 always use compression when talking to your server. To do
828 this, edit your <filename
829 role="special">.ssh/config</filename> file (which may not
830 yet exist), as follows.</para>
831 <programlisting>Host hg Compression yes HostName
832 hg.example.com</programlisting>
833 <para>This defines an alias, <literal>hg</literal>. When you
834 use it on the <command>ssh</command> command line or in a
835 Mercurial <literal>ssh</literal>-protocol URL, it will cause
836 <command>ssh</command> to connect to
837 <literal>hg.example.com</literal> and use compression. This
838 gives you both a shorter name to type and compression, each of
839 which is a good thing in its own right.</para>
841 </sect2>
842 </sect1>
843 <sect1 id="sec:collab:cgi">
844 <title>Serving over HTTP using CGI</title>
846 <para>Depending on how ambitious you are, configuring Mercurial's
847 CGI interface can take anything from a few moments to several
848 hours.</para>
850 <para>We'll begin with the simplest of examples, and work our way
851 towards a more complex configuration. Even for the most basic
852 case, you're almost certainly going to need to read and modify
853 your web server's configuration.</para>
855 <note>
856 <para> Configuring a web server is a complex, fiddly, and
857 highly system-dependent activity. I can't possibly give you
858 instructions that will cover anything like all of the cases
859 you will encounter. Please use your discretion and judgment in
860 following the sections below. Be prepared to make plenty of
861 mistakes, and to spend a lot of time reading your server's
862 error logs.</para>
863 </note>
865 <sect2>
866 <title>Web server configuration checklist</title>
868 <para>Before you continue, do take a few moments to check a few
869 aspects of your system's setup.</para>
871 <orderedlist>
872 <listitem><para>Do you have a web server installed at all?
873 Mac OS X ships with Apache, but many other systems may not
874 have a web server installed.</para>
875 </listitem>
876 <listitem><para>If you have a web server installed, is it
877 actually running? On most systems, even if one is
878 present, it will be disabled by default.</para>
879 </listitem>
880 <listitem><para>Is your server configured to allow you to run
881 CGI programs in the directory where you plan to do so?
882 Most servers default to explicitly disabling the ability
883 to run CGI programs.</para>
884 </listitem></orderedlist>
886 <para>If you don't have a web server installed, and don't have
887 substantial experience configuring Apache, you should consider
888 using the <literal>lighttpd</literal> web server instead of
889 Apache. Apache has a well-deserved reputation for baroque and
890 confusing configuration. While <literal>lighttpd</literal> is
891 less capable in some ways than Apache, most of these
892 capabilities are not relevant to serving Mercurial
893 repositories. And <literal>lighttpd</literal> is undeniably
894 <emphasis>much</emphasis> easier to get started with than
895 Apache.</para>
897 </sect2>
898 <sect2>
899 <title>Basic CGI configuration</title>
901 <para>On Unix-like systems, it's common for users to have a
902 subdirectory named something like <filename
903 class="directory">public_html</filename> in their home
904 directory, from which they can serve up web pages. A file
905 named <filename>foo</filename> in this directory will be
906 accessible at a URL of the form
907 <literal>http://www.example.com/\
908 {</literal>username/foo}.</para>
910 <para>To get started, find the <filename
911 role="special">hgweb.cgi</filename> script that should be
912 present in your Mercurial installation. If you can't quickly
913 find a local copy on your system, simply download one from the
914 master Mercurial repository at <ulink
915 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>
917 <para>You'll need to copy this script into your <filename
918 class="directory">public_html</filename> directory, and
919 ensure that it's executable.</para>
920 <programlisting>cp .../hgweb.cgi ~/public_html chmod 755
921 ~/public_html/hgweb.cgi</programlisting>
922 <para>The <literal>755</literal> argument to
923 <command>chmod</command> is a little more general than just
924 making the script executable: it ensures that the script is
925 executable by anyone, and that <quote>group</quote> and
926 <quote>other</quote> write permissions are
927 <emphasis>not</emphasis> set. If you were to leave those
928 write permissions enabled, Apache's <literal>suexec</literal>
929 subsystem would likely refuse to execute the script. In fact,
930 <literal>suexec</literal> also insists that the
931 <emphasis>directory</emphasis> in which the script resides
932 must not be writable by others.</para>
933 <programlisting>chmod 755 ~/public_html</programlisting>
935 <sect3 id="sec:collab:wtf">
936 <title>What could <emphasis>possibly</emphasis> go
937 wrong?</title>
939 <para>Once you've copied the CGI script into place, go into a
940 web browser, and try to open the URL <ulink
941 url="http://myhostname/
942 myuser/hgweb.cgi">http://myhostname/
943 myuser/hgweb.cgi</ulink>, <emphasis>but</emphasis> brace
944 yourself for instant failure. There's a high probability
945 that trying to visit this URL will fail, and there are many
946 possible reasons for this. In fact, you're likely to
947 stumble over almost every one of the possible errors below,
948 so please read carefully. The following are all of the
949 problems I ran into on a system running Fedora 7, with a
950 fresh installation of Apache, and a user account that I
951 created specially to perform this exercise.</para>
953 <para>Your web server may have per-user directories disabled.
954 If you're using Apache, search your config file for a
955 <literal>UserDir</literal> directive. If there's none
956 present, per-user directories will be disabled. If one
957 exists, but its value is <literal>disabled</literal>, then
958 per-user directories will be disabled. Otherwise, the
959 string after <literal>UserDir</literal> gives the name of
960 the subdirectory that Apache will look in under your home
961 directory, for example <filename
962 class="directory">public_html</filename>.</para>
964 <para>Your file access permissions may be too restrictive.
965 The web server must be able to traverse your home directory
966 and directories under your <filename
967 class="directory">public_html</filename> directory, and
968 read files under the latter too. Here's a quick recipe to
969 help you to make your permissions more appropriate.</para>
970 <programlisting>chmod 755 ~ find ~/public_html -type d -print0
971 | xargs -0r chmod 755 find ~/public_html -type f -print0 |
972 xargs -0r chmod 644</programlisting>
974 <para>The other possibility with permissions is that you might
975 get a completely empty window when you try to load the
976 script. In this case, it's likely that your access
977 permissions are <emphasis>too permissive</emphasis>. Apache's
978 <literal>suexec</literal> subsystem won't execute a script
979 that's group- or world-writable, for example.</para>
981 <para>Your web server may be configured to disallow execution
982 of CGI programs in your per-user web directory. Here's
983 Apache's default per-user configuration from my Fedora
984 system.</para>
985 <programlisting><Directory /home/*/public_html>
986 AllowOverride FileInfo AuthConfig Limit Options MultiViews
987 Indexes SymLinksIfOwnerMatch IncludesNoExec <Limit GET
988 POST OPTIONS> Order allow,deny Allow from all
989 </Limit> <LimitExcept GET POST OPTIONS> Order
990 deny,allow Deny from all </LimitExcept>
991 </Directory></programlisting>
992 <para>If you find a similar-looking
993 <literal>Directory</literal> group in your Apache
994 configuration, the directive to look at inside it is
995 <literal>Options</literal>. Add <literal>ExecCGI</literal>
996 to the end of this list if it's missing, and restart the web
997 server.</para>
999 <para>If you find that Apache serves you the text of the CGI
1000 script instead of executing it, you may need to either
1001 uncomment (if already present) or add a directive like
1002 this.</para>
1003 <programlisting>AddHandler cgi-script .cgi</programlisting>
1005 <para>The next possibility is that you might be served with a
1006 colourful Python backtrace claiming that it can't import a
1007 <literal>mercurial</literal>-related module. This is
1008 actually progress! The server is now capable of executing
1009 your CGI script. This error is only likely to occur if
1010 you're running a private installation of Mercurial, instead
1011 of a system-wide version. Remember that the web server runs
1012 the CGI program without any of the environment variables
1013 that you take for granted in an interactive session. If
1014 this error happens to you, edit your copy of <filename
1015 role="special">hgweb.cgi</filename> and follow the
1016 directions inside it to correctly set your
1017 <envar>PYTHONPATH</envar> environment variable.</para>
1019 <para>Finally, you are <emphasis>certain</emphasis> to by
1020 served with another colourful Python backtrace: this one
1021 will complain that it can't find <filename
1022 class="directory">/path/to/repository</filename>. Edit
1023 your <filename role="special">hgweb.cgi</filename> script
1024 and replace the <filename
1025 class="directory">/path/to/repository</filename> string
1026 with the complete path to the repository you want to serve
1027 up.</para>
1029 <para>At this point, when you try to reload the page, you
1030 should be presented with a nice HTML view of your
1031 repository's history. Whew!</para>
1033 </sect3>
1034 <sect3>
1035 <title>Configuring lighttpd</title>
1037 <para>To be exhaustive in my experiments, I tried configuring
1038 the increasingly popular <literal>lighttpd</literal> web
1039 server to serve the same repository as I described with
1040 Apache above. I had already overcome all of the problems I
1041 outlined with Apache, many of which are not server-specific.
1042 As a result, I was fairly sure that my file and directory
1043 permissions were good, and that my <filename
1044 role="special">hgweb.cgi</filename> script was properly
1045 edited.</para>
1047 <para>Once I had Apache running, getting
1048 <literal>lighttpd</literal> to serve the repository was a
1049 snap (in other words, even if you're trying to use
1050 <literal>lighttpd</literal>, you should read the Apache
1051 section). I first had to edit the
1052 <literal>mod_access</literal> section of its config file to
1053 enable <literal>mod_cgi</literal> and
1054 <literal>mod_userdir</literal>, both of which were disabled
1055 by default on my system. I then added a few lines to the
1056 end of the config file, to configure these modules.</para>
1057 <programlisting>userdir.path = "public_html" cgi.assign = (
1058 ".cgi" => "" )</programlisting>
1059 <para>With this done, <literal>lighttpd</literal> ran
1060 immediately for me. If I had configured
1061 <literal>lighttpd</literal> before Apache, I'd almost
1062 certainly have run into many of the same system-level
1063 configuration problems as I did with Apache. However, I
1064 found <literal>lighttpd</literal> to be noticeably easier to
1065 configure than Apache, even though I've used Apache for over
1066 a decade, and this was my first exposure to
1067 <literal>lighttpd</literal>.</para>
1069 </sect3>
1070 </sect2>
1071 <sect2>
1072 <title>Sharing multiple repositories with one CGI script</title>
1074 <para>The <filename role="special">hgweb.cgi</filename> script
1075 only lets you publish a single repository, which is an
1076 annoying restriction. If you want to publish more than one
1077 without wracking yourself with multiple copies of the same
1078 script, each with different names, a better choice is to use
1079 the <filename role="special">hgwebdir.cgi</filename>
1080 script.</para>
1082 <para>The procedure to configure <filename
1083 role="special">hgwebdir.cgi</filename> is only a little more
1084 involved than for <filename
1085 role="special">hgweb.cgi</filename>. First, you must obtain
1086 a copy of the script. If you don't have one handy, you can
1087 download a copy from the master Mercurial repository at <ulink
1088 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>
1090 <para>You'll need to copy this script into your <filename
1091 class="directory">public_html</filename> directory, and
1092 ensure that it's executable.</para>
1093 <programlisting>cp .../hgwebdir.cgi ~/public_html chmod 755
1094 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
1095 <para>With basic configuration out of the way, try to visit
1096 <ulink url="http://myhostname/
1097 myuser/hgwebdir.cgi">http://myhostname/
1098 myuser/hgwebdir.cgi</ulink> in your browser. It should
1099 display an empty list of repositories. If you get a blank
1100 window or error message, try walking through the list of
1101 potential problems in section <xref
1102 linkend="sec:collab:wtf"/>.</para>
1104 <para>The <filename role="special">hgwebdir.cgi</filename>
1105 script relies on an external configuration file. By default,
1106 it searches for a file named <filename
1107 role="special">hgweb.config</filename> in the same directory
1108 as itself. You'll need to create this file, and make it
1109 world-readable. The format of the file is similar to a
1110 Windows <quote>ini</quote> file, as understood by Python's
1111 <literal>ConfigParser</literal>
1112 <citation>web:configparser</citation> module.</para>
1114 <para>The easiest way to configure <filename
1115 role="special">hgwebdir.cgi</filename> is with a section
1116 named <literal>collections</literal>. This will automatically
1117 publish <emphasis>every</emphasis> repository under the
1118 directories you name. The section should look like
1119 this:</para>
1120 <programlisting>[collections] /my/root =
1121 /my/root</programlisting>
1122 <para>Mercurial interprets this by looking at the directory name
1123 on the <emphasis>right</emphasis> hand side of the
1124 <quote><literal>=</literal></quote> sign; finding repositories
1125 in that directory hierarchy; and using the text on the
1126 <emphasis>left</emphasis> to strip off matching text from the
1127 names it will actually list in the web interface. The
1128 remaining component of a path after this stripping has
1129 occurred is called a <quote>virtual path</quote>.</para>
1131 <para>Given the example above, if we have a repository whose
1132 local path is <filename
1133 class="directory">/my/root/this/repo</filename>, the CGI
1134 script will strip the leading <filename
1135 class="directory">/my/root</filename> from the name, and
1136 publish the repository with a virtual path of <filename
1137 class="directory">this/repo</filename>. If the base URL for
1138 our CGI script is <ulink url="http://myhostname/
1139 myuser/hgwebdir.cgi">http://myhostname/
1140 myuser/hgwebdir.cgi</ulink>, the complete URL for that
1141 repository will be <ulink url="http://myhostname/
1142 myuser/hgwebdir.cgi/this/repo">http://myhostname/
1143 myuser/hgwebdir.cgi/this/repo</ulink>.</para>
1145 <para>If we replace <filename
1146 class="directory">/my/root</filename> on the left hand side
1147 of this example with <filename
1148 class="directory">/my</filename>, then <filename
1149 role="special">hgwebdir.cgi</filename> will only strip off
1150 <filename class="directory">/my</filename> from the repository
1151 name, and will give us a virtual path of <filename
1152 class="directory">root/this/repo</filename> instead of
1153 <filename class="directory">this/repo</filename>.</para>
1155 <para>The <filename role="special">hgwebdir.cgi</filename>
1156 script will recursively search each directory listed in the
1157 <literal>collections</literal> section of its configuration
1158 file, but it will <literal>not</literal> recurse into the
1159 repositories it finds.</para>
1161 <para>The <literal>collections</literal> mechanism makes it easy
1162 to publish many repositories in a <quote>fire and
1163 forget</quote> manner. You only need to set up the CGI
1164 script and configuration file one time. Afterwards, you can
1165 publish or unpublish a repository at any time by simply moving
1166 it into, or out of, the directory hierarchy in which you've
1167 configured <filename role="special">hgwebdir.cgi</filename> to
1168 look.</para>
1170 <sect3>
1171 <title>Explicitly specifying which repositories to
1172 publish</title>
1174 <para>In addition to the <literal>collections</literal>
1175 mechanism, the <filename
1176 role="special">hgwebdir.cgi</filename> script allows you
1177 to publish a specific list of repositories. To do so,
1178 create a <literal>paths</literal> section, with contents of
1179 the following form.</para>
1180 <programlisting>[paths] repo1 = /my/path/to/some/repo repo2 =
1181 /some/path/to/another</programlisting>
1182 <para>In this case, the virtual path (the component that will
1183 appear in a URL) is on the left hand side of each
1184 definition, while the path to the repository is on the
1185 right. Notice that there does not need to be any
1186 relationship between the virtual path you choose and the
1187 location of a repository in your filesystem.</para>
1189 <para>If you wish, you can use both the
1190 <literal>collections</literal> and <literal>paths</literal>
1191 mechanisms simultaneously in a single configuration
1192 file.</para>
1194 <note>
1195 <para> If multiple repositories have the same virtual path,
1196 <filename role="special">hgwebdir.cgi</filename> will not
1197 report an error. Instead, it will behave
1198 unpredictably.</para>
1199 </note>
1201 </sect3>
1202 </sect2>
1203 <sect2>
1204 <title>Downloading source archives</title>
1206 <para>Mercurial's web interface lets users download an archive
1207 of any revision. This archive will contain a snapshot of the
1208 working directory as of that revision, but it will not contain
1209 a copy of the repository data.</para>
1211 <para>By default, this feature is not enabled. To enable it,
1212 you'll need to add an <envar
1213 role="rc-item-web">allow_archive</envar> item to the
1214 <literal role="rc-web">web</literal> section of your <filename
1215 role="special"> /.hgrc</filename>.</para>
1217 </sect2>
1218 <sect2>
1219 <title>Web configuration options</title>
1221 <para>Mercurial's web interfaces (the <command role="hg-cmd">hg
1222 serve</command> command, and the <filename
1223 role="special">hgweb.cgi</filename> and <filename
1224 role="special">hgwebdir.cgi</filename> scripts) have a
1225 number of configuration options that you can set. These
1226 belong in a section named <literal
1227 role="rc-web">web</literal>.</para>
1228 <itemizedlist>
1229 <listitem><para><envar
1230 role="rc-item-web">allow_archive</envar>: Determines
1231 which (if any) archive download mechanisms Mercurial
1232 supports. If you enable this feature, users of the web
1233 interface will be able to download an archive of whatever
1234 revision of a repository they are viewing. To enable the
1235 archive feature, this item must take the form of a
1236 sequence of words drawn from the list below.</para>
1237 <itemizedlist>
1238 <listitem><para><literal>bz2</literal>: A
1239 <command>tar</command> archive, compressed using
1240 <literal>bzip2</literal> compression. This has the
1241 best compression ratio, but uses the most CPU time on
1242 the server.</para>
1243 </listitem>
1244 <listitem><para><literal>gz</literal>: A
1245 <command>tar</command> archive, compressed using
1246 <literal>gzip</literal> compression.</para>
1247 </listitem>
1248 <listitem><para><literal>zip</literal>: A
1249 <command>zip</command> archive, compressed using LZW
1250 compression. This format has the worst compression
1251 ratio, but is widely used in the Windows world.</para>
1252 </listitem>
1253 </itemizedlist>
1254 <para> If you provide an empty list, or don't have an
1255 <envar role="rc-item-web">allow_archive</envar> entry at
1256 all, this feature will be disabled. Here is an example of
1257 how to enable all three supported formats.</para>
1258 <programlisting>[web] allow_archive = bz2 gz
1259 zip</programlisting>
1260 </listitem>
1261 <listitem><para><envar role="rc-item-web">allowpull</envar>:
1262 Boolean. Determines whether the web interface allows
1263 remote users to <command role="hg-cmd">hg pull</command>
1264 and <command role="hg-cmd">hg clone</command> this
1265 repository over HTTP. If set to <literal>no</literal> or
1266 <literal>false</literal>, only the
1267 <quote>human-oriented</quote> portion of the web interface
1268 is available.</para>
1269 </listitem>
1270 <listitem><para><envar role="rc-item-web">contact</envar>:
1271 String. A free-form (but preferably brief) string
1272 identifying the person or group in charge of the
1273 repository. This often contains the name and email
1274 address of a person or mailing list. It often makes sense
1275 to place this entry in a repository's own <filename
1276 role="special">.hg/hgrc</filename> file, but it can make
1277 sense to use in a global <filename role="special">
1278 /.hgrc</filename>\ if every repository has a single
1279 maintainer.</para>
1280 </listitem>
1281 <listitem><para><envar role="rc-item-web">maxchanges</envar>:
1282 Integer. The default maximum number of changesets to
1283 display in a single page of output.</para>
1284 </listitem>
1285 <listitem><para><envar role="rc-item-web">maxfiles</envar>:
1286 Integer. The default maximum number of modified files to
1287 display in a single page of output.</para>
1288 </listitem>
1289 <listitem><para><envar role="rc-item-web">stripes</envar>:
1290 Integer. If the web interface displays alternating
1291 <quote>stripes</quote> to make it easier to visually align
1292 rows when you are looking at a table, this number controls
1293 the number of rows in each stripe.</para>
1294 </listitem>
1295 <listitem><para><envar role="rc-item-web">style</envar>:
1296 Controls the template Mercurial uses to display the web
1297 interface. Mercurial ships with two web templates, named
1298 <literal>default</literal> and <literal>gitweb</literal>
1299 (the latter is much more visually attractive). You can
1300 also specify a custom template of your own; see chapter
1301 <xref linkend="chap:template"/> for details.
1302 Here, you can see how to enable the
1303 <literal>gitweb</literal> style.</para>
1304 <programlisting>[web] style = gitweb</programlisting>
1305 </listitem>
1306 <listitem><para><envar role="rc-item-web">templates</envar>:
1307 Path. The directory in which to search for template
1308 files. By default, Mercurial searches in the directory in
1309 which it was installed.</para>
1310 </listitem></itemizedlist>
1311 <para>If you are using <filename
1312 role="special">hgwebdir.cgi</filename>, you can place a few
1313 configuration items in a <literal role="rc-web">web</literal>
1314 section of the <filename
1315 role="special">hgweb.config</filename> file instead of a
1316 <filename role="special"> /.hgrc</filename>\ file, for
1317 convenience. These items are <envar
1318 role="rc-item-web">motd</envar> and <envar
1319 role="rc-item-web">style</envar>.</para>
1321 <sect3>
1322 <title>Options specific to an individual repository</title>
1324 <para>A few <literal role="rc-web">web</literal> configuration
1325 items ought to be placed in a repository's local <filename
1326 role="special">.hg/hgrc</filename>, rather than a user's
1327 or global <filename role="special">
1328 /.hgrc</filename>.</para>
1329 <itemizedlist>
1330 <listitem><para><envar
1331 role="rc-item-web">description</envar>: String. A
1332 free-form (but preferably brief) string that describes
1333 the contents or purpose of the repository.</para>
1334 </listitem>
1335 <listitem><para><envar role="rc-item-web">name</envar>:
1336 String. The name to use for the repository in the web
1337 interface. This overrides the default name, which is
1338 the last component of the repository's path.</para>
1339 </listitem></itemizedlist>
1341 </sect3>
1342 <sect3>
1343 <title>Options specific to the <command role="hg-cmd">hg
1344 serve</command> command</title>
1346 <para>Some of the items in the <literal
1347 role="rc-web">web</literal> section of a <filename
1348 role="special"> /.hgrc</filename>\ file are only for use
1349 with the <command role="hg-cmd">hg serve</command>
1350 command.</para>
1351 <itemizedlist>
1352 <listitem><para><envar role="rc-item-web">accesslog</envar>:
1353 Path. The name of a file into which to write an access
1354 log. By default, the <command role="hg-cmd">hg
1355 serve</command> command writes this information to
1356 standard output, not to a file. Log entries are written
1357 in the standard <quote>combined</quote> file format used
1358 by almost all web servers.</para>
1359 </listitem>
1360 <listitem><para><envar role="rc-item-web">address</envar>:
1361 String. The local address on which the server should
1362 listen for incoming connections. By default, the server
1363 listens on all addresses.</para>
1364 </listitem>
1365 <listitem><para><envar role="rc-item-web">errorlog</envar>:
1366 Path. The name of a file into which to write an error
1367 log. By default, the <command role="hg-cmd">hg
1368 serve</command> command writes this information to
1369 standard error, not to a file.</para>
1370 </listitem>
1371 <listitem><para><envar role="rc-item-web">ipv6</envar>:
1372 Boolean. Whether to use the IPv6 protocol. By default,
1373 IPv6 is not used.</para>
1374 </listitem>
1375 <listitem><para><envar role="rc-item-web">port</envar>:
1376 Integer. The TCP port number on which the server should
1377 listen. The default port number used is 8000.</para>
1378 </listitem></itemizedlist>
1380 </sect3>
1381 <sect3>
1382 <title>Choosing the right <filename role="special">
1383 /.hgrc</filename>\ file to add <literal
1384 role="rc-web">web</literal> items to</title>
1386 <para>It is important to remember that a web server like
1387 Apache or <literal>lighttpd</literal> will run under a user
1388 ID that is different to yours. CGI scripts run by your
1389 server, such as <filename
1390 role="special">hgweb.cgi</filename>, will usually also run
1391 under that user ID.</para>
1393 <para>If you add <literal role="rc-web">web</literal> items to
1394 your own personal <filename role="special">
1395 /.hgrc</filename>\ file, CGI scripts won't read that
1396 <filename role="special"> /.hgrc</filename>\ file. Those
1397 settings will thus only affect the behaviour of the <command
1398 role="hg-cmd">hg serve</command> command when you run it.
1399 To cause CGI scripts to see your settings, either create a
1400 <filename role="special"> /.hgrc</filename>\ file in the
1401 home directory of the user ID that runs your web server, or
1402 add those settings to a system-wide <filename
1403 role="special"> /.hgrc</filename>\ file.</para>
1406 </sect3>
1407 </sect2>
1408 </sect1>
1409 </chapter>
1411 <!--
1412 local variables:
1413 sgml-parent-document: ("00book.xml" "book" "chapter")
1414 end:
1415 -->