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