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