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