hgbook
view fr/ch06-collab.xml @ 996:6f8c48362758
merge with trunk
| author | Romain PELISSE <belaran@gmail.com> |
|---|---|
| date | Sat Sep 12 17:58:56 2009 +0200 (2009-09-12) |
| parents | 6b680d569bb4 f0110009e946 |
| children | 304c6a1758ae |
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. You
23 can even get a view of history that gives a graphical view of
24 the relationships between individual changes and merges.</para>
26 <para id="x_44d">Also for human consumption, the web interface provides
27 Atom and RSS feeds of the changes in a repository. This lets you
28 <quote>subscribe</quote> to a repository using your favorite
29 feed reader, and be automatically notified of activity in that
30 repository as soon as it happens. I find this capability much
31 more convenient than the model of subscribing to a mailing list
32 to which notifications are sent, as it requires no additional
33 configuration on the part of whoever is serving the
34 repository.</para>
36 <para id="x_44e">The web interface also lets remote users clone a repository,
37 pull changes from it, and (when the server is configured to
38 permit it) push changes back to it. Mercurial's HTTP tunneling
39 protocol aggressively compresses data, so that it works
40 efficiently even over low-bandwidth network connections.</para>
42 <para id="x_44f">The easiest way to get started with the web interface is to
43 use your web browser to visit an existing repository, such as
44 the master Mercurial repository at <ulink
45 url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para>
47 <para id="x_450">If you're interested in providing a web interface
48 to your own repositories, there are several good ways to do
49 this.</para>
51 <para id="x_69d">The easiest and fastest way to get started in an informal
52 environment is to use the <command role="hg-cmd">hg
53 serve</command> command, which is best suited to short-term
54 <quote>lightweight</quote> serving. See <xref
55 linkend="sec:collab:serve"/> below for details of how to use
56 this command.</para>
58 <para id="x_69e">For longer-lived repositories that you'd like to
59 have permanently available, there are several public hosting
60 services available. Some are free to open source projects,
61 while others offer paid commercial hosting. An up-to-date list
62 is available at <ulink
63 url="http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting">http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting</ulink>.</para>
65 <para id="x_6a0">If you would prefer to host your own repositories, Mercurial
66 has built-in support for several popular hosting technologies,
67 most notably CGI (Common Gateway Interface), and WSGI (Web
68 Services Gateway Interface). See <xref
69 linkend="sec:collab:cgi"/> for details of CGI and WSGI
70 configuration.</para>
71 </sect1>
73 <sect1>
74 <title>Collaboration models</title>
76 <para id="x_451">With a suitably flexible tool, making decisions about
77 workflow is much more of a social engineering challenge than a
78 technical one. Mercurial imposes few limitations on how you can
79 structure the flow of work in a project, so it's up to you and
80 your group to set up and live with a model that matches your own
81 particular needs.</para>
83 <sect2>
84 <title>Factors to keep in mind</title>
86 <para id="x_452">The most important aspect of any model that you must keep
87 in mind is how well it matches the needs and capabilities of
88 the people who will be using it. This might seem
89 self-evident; even so, you still can't afford to forget it for
90 a moment.</para>
92 <para id="x_453">I once put together a workflow model that seemed to make
93 perfect sense to me, but that caused a considerable amount of
94 consternation and strife within my development team. In spite
95 of my attempts to explain why we needed a complex set of
96 branches, and how changes ought to flow between them, a few
97 team members revolted. Even though they were smart people,
98 they didn't want to pay attention to the constraints we were
99 operating under, or face the consequences of those constraints
100 in the details of the model that I was advocating.</para>
102 <para id="x_454">Don't sweep foreseeable social or technical problems under
103 the rug. Whatever scheme you put into effect, you should plan
104 for mistakes and problem scenarios. Consider adding automated
105 machinery to prevent, or quickly recover from, trouble that
106 you can anticipate. As an example, if you intend to have a
107 branch with not-for-release changes in it, you'd do well to
108 think early about the possibility that someone might
109 accidentally merge those changes into a release branch. You
110 could avoid this particular problem by writing a hook that
111 prevents changes from being merged from an inappropriate
112 branch.</para>
113 </sect2>
115 <sect2>
116 <title>Informal anarchy</title>
118 <para id="x_455">I wouldn't suggest an <quote>anything goes</quote>
119 approach as something sustainable, but it's a model that's
120 easy to grasp, and it works perfectly well in a few unusual
121 situations.</para>
123 <para id="x_456">As one example, many projects have a loose-knit group of
124 collaborators who rarely physically meet each other. Some
125 groups like to overcome the isolation of working at a distance
126 by organizing occasional <quote>sprints</quote>. In a sprint,
127 a number of people get together in a single location (a
128 company's conference room, a hotel meeting room, that kind of
129 place) and spend several days more or less locked in there,
130 hacking intensely on a handful of projects.</para>
132 <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the
133 <command role="hg-cmd">hg serve</command> command, since
134 <command role="hg-cmd">hg serve</command> does not require any
135 fancy server infrastructure. You can get started with
136 <command role="hg-cmd">hg serve</command> in moments, by
137 reading <xref linkend="sec:collab:serve"/> below. Then simply
138 tell the person next to you that you're running a server, send
139 the URL to them in an instant message, and you immediately
140 have a quick-turnaround way to work together. They can type
141 your URL into their web browser and quickly review your
142 changes; or they can pull a bugfix from you and verify it; or
143 they can clone a branch containing a new feature and try it
144 out.</para>
146 <para id="x_458">The charm, and the problem, with doing things
147 in an ad hoc fashion like this is that only people who know
148 about your changes, and where they are, can see them. Such an
149 informal approach simply doesn't scale beyond a handful
150 people, because each individual needs to know about
151 <emphasis>n</emphasis> different repositories to pull
152 from.</para>
153 </sect2>
155 <sect2>
156 <title>A single central repository</title>
158 <para id="x_459">For smaller projects migrating from a centralised revision
159 control tool, perhaps the easiest way to get started is to
160 have changes flow through a single shared central repository.
161 This is also the most common <quote>building block</quote> for
162 more ambitious workflow schemes.</para>
164 <para id="x_45a">Contributors start by cloning a copy of this repository.
165 They can pull changes from it whenever they need to, and some
166 (perhaps all) developers have permission to push a change back
167 when they're ready for other people to see it.</para>
169 <para id="x_45b">Under this model, it can still often make sense for people
170 to pull changes directly from each other, without going
171 through the central repository. Consider a case in which I
172 have a tentative bug fix, but I am worried that if I were to
173 publish it to the central repository, it might subsequently
174 break everyone else's trees as they pull it. To reduce the
175 potential for damage, I can ask you to clone my repository
176 into a temporary repository of your own and test it. This
177 lets us put off publishing the potentially unsafe change until
178 it has had a little testing.</para>
180 <para id="x_45c">If a team is hosting its own repository in this
181 kind of scenario, people will usually use the
182 <command>ssh</command> protocol to securely push changes to
183 the central repository, as documented in <xref
184 linkend="sec:collab:ssh"/>. It's also usual to publish a
185 read-only copy of the repository over HTTP, as in
186 <xref linkend="sec:collab:cgi"/>. Publishing over HTTP
187 satisfies the needs of people who don't have push access, and
188 those who want to use web browsers to browse the repository's
189 history.</para>
190 </sect2>
192 <sect2>
193 <title>A hosted central repository</title>
195 <para id="x_6a1">A wonderful thing about public hosting services like
196 <ulink url="http://bitbucket.org/">Bitbucket</ulink> is that
197 not only do they handle the fiddly server configuration
198 details, such as user accounts, authentication, and secure
199 wire protocols, they provide additional infrastructure to make
200 this model work well.</para>
202 <para id="x_6a2">For instance, a well-engineered hosting service will let
203 people clone their own copies of a repository with a single
204 click. This lets people work in separate spaces and share
205 their changes when they're ready.</para>
207 <para id="x_6a3">In addition, a good hosting service will let people
208 communicate with each other, for instance to say <quote>there
209 are changes ready for you to review in this
210 tree</quote>.</para>
211 </sect2>
213 <sect2>
214 <title>Working with multiple branches</title>
216 <para id="x_45d">Projects of any significant size naturally tend to make
217 progress on several fronts simultaneously. In the case of
218 software, it's common for a project to go through periodic
219 official releases. A release might then go into
220 <quote>maintenance mode</quote> for a while after its first
221 publication; maintenance releases tend to contain only bug
222 fixes, not new features. In parallel with these maintenance
223 releases, one or more future releases may be under
224 development. People normally use the word
225 <quote>branch</quote> to refer to one of these many slightly
226 different directions in which development is
227 proceeding.</para>
229 <para id="x_45e">Mercurial is particularly well suited to managing a number
230 of simultaneous, but not identical, branches. Each
231 <quote>development direction</quote> can live in its own
232 central repository, and you can merge changes from one to
233 another as the need arises. Because repositories are
234 independent of each other, unstable changes in a development
235 branch will never affect a stable branch unless someone
236 explicitly merges those changes into the stable branch.</para>
238 <para id="x_45f">Here's an example of how this can work in practice. Let's
239 say you have one <quote>main branch</quote> on a central
240 server.</para>
242 &interaction.branching.init;
244 <para id="x_460">People clone it, make changes locally, test them, and push
245 them back.</para>
247 <para id="x_461">Once the main branch reaches a release milestone, you can
248 use the <command role="hg-cmd">hg tag</command> command to
249 give a permanent name to the milestone revision.</para>
251 &interaction.branching.tag;
253 <para id="x_462">Let's say some ongoing
254 development occurs on the main branch.</para>
256 &interaction.branching.main;
258 <para id="x_463">Using the tag that was recorded at the milestone, people
259 who clone that repository at any time in the future can use
260 <command role="hg-cmd">hg update</command> to get a copy of
261 the working directory exactly as it was when that tagged
262 revision was committed.</para>
264 &interaction.branching.update;
266 <para id="x_464">In addition, immediately after the main branch is tagged,
267 we can then clone the main branch on the server to a new
268 <quote>stable</quote> branch, also on the server.</para>
270 &interaction.branching.clone;
272 <para id="x_465">If we need to make a change to the stable
273 branch, we can then clone <emphasis>that</emphasis>
274 repository, make our changes, commit, and push our changes
275 back there.</para>
277 &interaction.branching.stable;
279 <para id="x_466">Because Mercurial repositories are independent, and
280 Mercurial doesn't move changes around automatically, the
281 stable and main branches are <emphasis>isolated</emphasis>
282 from each other. The changes that we made on the main branch
283 don't <quote>leak</quote> to the stable branch, and vice
284 versa.</para>
286 <para id="x_467">We'll often want all of our bugfixes on the stable
287 branch to show up on the main branch, too. Rather than
288 rewrite a bugfix on the main branch, we can simply pull and
289 merge changes from the stable to the main branch, and
290 Mercurial will bring those bugfixes in for us.</para>
292 &interaction.branching.merge;
294 <para id="x_468">The main branch will still contain changes that
295 are not on the stable branch, but it will also contain all of
296 the bugfixes from the stable branch. The stable branch
297 remains unaffected by these changes, since changes are only
298 flowing from the stable to the main branch, and not the other
299 way.</para>
300 </sect2>
302 <sect2>
303 <title>Feature branches</title>
305 <para id="x_469">For larger projects, an effective way to manage change is
306 to break up a team into smaller groups. Each group has a
307 shared branch of its own, cloned from a single
308 <quote>master</quote> branch used by the entire project.
309 People working on an individual branch are typically quite
310 isolated from developments on other branches.</para>
312 <figure id="fig:collab:feature-branches">
313 <title>Feature branches</title>
314 <mediaobject>
315 <imageobject><imagedata width="100%" fileref="figs/feature-branches.png"/></imageobject>
316 <textobject><phrase>XXX add text</phrase></textobject>
317 </mediaobject>
318 </figure>
320 <para id="x_46b">When a particular feature is deemed to be in suitable
321 shape, someone on that feature team pulls and merges from the
322 master branch into the feature branch, then pushes back up to
323 the master branch.</para>
324 </sect2>
326 <sect2>
327 <title>The release train</title>
329 <para id="x_46c">Some projects are organized on a <quote>train</quote>
330 basis: a release is scheduled to happen every few months, and
331 whatever features are ready when the <quote>train</quote> is
332 ready to leave are allowed in.</para>
334 <para id="x_46d">This model resembles working with feature branches. The
335 difference is that when a feature branch misses a train,
336 someone on the feature team pulls and merges the changes that
337 went out on that train release into the feature branch, and
338 the team continues its work on top of that release so that
339 their feature can make the next release.</para>
340 </sect2>
342 <sect2>
343 <title>The Linux kernel model</title>
345 <para id="x_46e">The development of the Linux kernel has a shallow
346 hierarchical structure, surrounded by a cloud of apparent
347 chaos. Because most Linux developers use
348 <command>git</command>, a distributed revision control tool
349 with capabilities similar to Mercurial, it's useful to
350 describe the way work flows in that environment; if you like
351 the ideas, the approach translates well across tools.</para>
353 <para id="x_46f">At the center of the community sits Linus Torvalds, the
354 creator of Linux. He publishes a single source repository
355 that is considered the <quote>authoritative</quote> current
356 tree by the entire developer community. Anyone can clone
357 Linus's tree, but he is very choosy about whose trees he pulls
358 from.</para>
360 <para id="x_470">Linus has a number of <quote>trusted lieutenants</quote>.
361 As a general rule, he pulls whatever changes they publish, in
362 most cases without even reviewing those changes. Some of
363 those lieutenants are generally agreed to be
364 <quote>maintainers</quote>, responsible for specific
365 subsystems within the kernel. If a random kernel hacker wants
366 to make a change to a subsystem that they want to end up in
367 Linus's tree, they must find out who the subsystem's
368 maintainer is, and ask that maintainer to take their change.
369 If the maintainer reviews their changes and agrees to take
370 them, they'll pass them along to Linus in due course.</para>
372 <para id="x_471">Individual lieutenants have their own approaches to
373 reviewing, accepting, and publishing changes; and for deciding
374 when to feed them to Linus. In addition, there are several
375 well known branches that people use for different purposes.
376 For example, a few people maintain <quote>stable</quote>
377 repositories of older versions of the kernel, to which they
378 apply critical fixes as needed. Some maintainers publish
379 multiple trees: one for experimental changes; one for changes
380 that they are about to feed upstream; and so on. Others just
381 publish a single tree.</para>
383 <para id="x_472">This model has two notable features. The first is that
384 it's <quote>pull only</quote>. You have to ask, convince, or
385 beg another developer to take a change from you, because there
386 are almost no trees to which more than one person can push,
387 and there's no way to push changes into a tree that someone
388 else controls.</para>
390 <para id="x_473">The second is that it's based on reputation and acclaim.
391 If you're an unknown, Linus will probably ignore changes from
392 you without even responding. But a subsystem maintainer will
393 probably review them, and will likely take them if they pass
394 their criteria for suitability. The more <quote>good</quote>
395 changes you contribute to a maintainer, the more likely they
396 are to trust your judgment and accept your changes. If you're
397 well-known and maintain a long-lived branch for something
398 Linus hasn't yet accepted, people with similar interests may
399 pull your changes regularly to keep up with your work.</para>
401 <para id="x_474">Reputation and acclaim don't necessarily cross subsystem
402 or <quote>people</quote> boundaries. If you're a respected
403 but specialised storage hacker, and you try to fix a
404 networking bug, that change will receive a level of scrutiny
405 from a network maintainer comparable to a change from a
406 complete stranger.</para>
408 <para id="x_475">To people who come from more orderly project backgrounds,
409 the comparatively chaotic Linux kernel development process
410 often seems completely insane. It's subject to the whims of
411 individuals; people make sweeping changes whenever they deem
412 it appropriate; and the pace of development is astounding.
413 And yet Linux is a highly successful, well-regarded piece of
414 software.</para>
415 </sect2>
417 <sect2>
418 <title>Pull-only versus shared-push collaboration</title>
420 <para id="x_476">A perpetual source of heat in the open source community is
421 whether a development model in which people only ever pull
422 changes from others is <quote>better than</quote> one in which
423 multiple people can push changes to a shared
424 repository.</para>
426 <para id="x_477">Typically, the backers of the shared-push model use tools
427 that actively enforce this approach. If you're using a
428 centralised revision control tool such as Subversion, there's
429 no way to make a choice over which model you'll use: the tool
430 gives you shared-push, and if you want to do anything else,
431 you'll have to roll your own approach on top (such as applying
432 a patch by hand).</para>
434 <para id="x_478">A good distributed revision control tool will
435 support both models. You and your collaborators can then
436 structure how you work together based on your own needs and
437 preferences, not on what contortions your tools force you
438 into.</para>
439 </sect2>
440 <sect2>
441 <title>Where collaboration meets branch management</title>
443 <para id="x_479">Once you and your team set up some shared
444 repositories and start propagating changes back and forth
445 between local and shared repos, you begin to face a related,
446 but slightly different challenge: that of managing the
447 multiple directions in which your team may be moving at once.
448 Even though this subject is intimately related to how your
449 team collaborates, it's dense enough to merit treatment of its
450 own, in <xref linkend="chap:branch"/>.</para>
451 </sect2>
452 </sect1>
454 <sect1>
455 <title>The technical side of sharing</title>
457 <para id="x_47a">The remainder of this chapter is devoted to the question of
458 sharing changes with your collaborators.</para>
459 </sect1>
461 <sect1 id="sec:collab:serve">
462 <title>Informal sharing with <command role="hg-cmd">hg
463 serve</command></title>
465 <para id="x_47b">Mercurial's <command role="hg-cmd">hg serve</command>
466 command is wonderfully suited to small, tight-knit, and
467 fast-paced group environments. It also provides a great way to
468 get a feel for using Mercurial commands over a network.</para>
470 <para id="x_47c">Run <command role="hg-cmd">hg serve</command> inside a
471 repository, and in under a second it will bring up a specialised
472 HTTP server; this will accept connections from any client, and
473 serve up data for that repository until you terminate it.
474 Anyone who knows the URL of the server you just started, and can
475 talk to your computer over the network, can then use a web
476 browser or Mercurial to read data from that repository. A URL
477 for a <command role="hg-cmd">hg serve</command> instance running
478 on a laptop is likely to look something like
479 <literal>http://my-laptop.local:8000/</literal>.</para>
481 <para id="x_47d">The <command role="hg-cmd">hg serve</command> command is
482 <emphasis>not</emphasis> a general-purpose web server. It can do
483 only two things:</para>
484 <itemizedlist>
485 <listitem><para id="x_47e">Allow people to browse the history of the
486 repository it's serving, from their normal web
487 browsers.</para>
488 </listitem>
489 <listitem><para id="x_47f">Speak Mercurial's wire protocol, so that people
490 can <command role="hg-cmd">hg clone</command> or <command
491 role="hg-cmd">hg pull</command> changes from that
492 repository.</para>
493 </listitem></itemizedlist>
494 <para id="x_480">In particular, <command role="hg-cmd">hg serve</command>
495 won't allow remote users to <emphasis>modify</emphasis> your
496 repository. It's intended for read-only use.</para>
498 <para id="x_481">If you're getting started with Mercurial, there's nothing to
499 prevent you from using <command role="hg-cmd">hg serve</command>
500 to serve up a repository on your own computer, then use commands
501 like <command role="hg-cmd">hg clone</command>, <command
502 role="hg-cmd">hg incoming</command>, and so on to talk to that
503 server as if the repository was hosted remotely. This can help
504 you to quickly get acquainted with using commands on
505 network-hosted repositories.</para>
507 <sect2>
508 <title>A few things to keep in mind</title>
510 <para id="x_482">Because it provides unauthenticated read access to all
511 clients, you should only use <command role="hg-cmd">hg
512 serve</command> in an environment where you either don't
513 care, or have complete control over, who can access your
514 network and pull data from your repository.</para>
516 <para id="x_483">The <command role="hg-cmd">hg serve</command> command
517 knows nothing about any firewall software you might have
518 installed on your system or network. It cannot detect or
519 control your firewall software. If other people are unable to
520 talk to a running <command role="hg-cmd">hg serve</command>
521 instance, the second thing you should do
522 (<emphasis>after</emphasis> you make sure that they're using
523 the correct URL) is check your firewall configuration.</para>
525 <para id="x_484">By default, <command role="hg-cmd">hg serve</command>
526 listens for incoming connections on port 8000. If another
527 process is already listening on the port you want to use, you
528 can specify a different port to listen on using the <option
529 role="hg-opt-serve">-p</option> option.</para>
531 <para id="x_485">Normally, when <command role="hg-cmd">hg serve</command>
532 starts, it prints no output, which can be a bit unnerving. If
533 you'd like to confirm that it is indeed running correctly, and
534 find out what URL you should send to your collaborators, start
535 it with the <option role="hg-opt-global">-v</option>
536 option.</para>
537 </sect2>
538 </sect1>
540 <sect1 id="sec:collab:ssh">
541 <title>Using the Secure Shell (ssh) protocol</title>
543 <para id="x_486">You can pull and push changes securely over a network
544 connection using the Secure Shell (<literal>ssh</literal>)
545 protocol. To use this successfully, you may have to do a little
546 bit of configuration on the client or server sides.</para>
548 <para id="x_487">If you're not familiar with ssh, it's the name of
549 both a command and a network protocol that let you securely
550 communicate with another computer. To use it with Mercurial,
551 you'll be setting up one or more user accounts on a server so
552 that remote users can log in and execute commands.</para>
554 <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll
555 probably find some of the material that follows to be elementary
556 in nature.)</para>
558 <sect2>
559 <title>How to read and write ssh URLs</title>
561 <para id="x_489">An ssh URL tends to look like this:</para>
562 <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting>
563 <orderedlist>
564 <listitem><para id="x_48a">The <quote><literal>ssh://</literal></quote>
565 part tells Mercurial to use the ssh protocol.</para>
566 </listitem>
567 <listitem><para id="x_48b">The <quote><literal>bos@</literal></quote>
568 component indicates what username to log into the server
569 as. You can leave this out if the remote username is the
570 same as your local username.</para>
571 </listitem>
572 <listitem><para id="x_48c">The
573 <quote><literal>hg.serpentine.com</literal></quote> gives
574 the hostname of the server to log into.</para>
575 </listitem>
576 <listitem><para id="x_48d">The <quote>:22</quote> identifies the port
577 number to connect to the server on. The default port is
578 22, so you only need to specify a colon and port number if
579 you're <emphasis>not</emphasis> using port 22.</para>
580 </listitem>
581 <listitem><para id="x_48e">The remainder of the URL is the local path to
582 the repository on the server.</para>
583 </listitem></orderedlist>
585 <para id="x_48f">There's plenty of scope for confusion with the path
586 component of ssh URLs, as there is no standard way for tools
587 to interpret it. Some programs behave differently than others
588 when dealing with these paths. This isn't an ideal situation,
589 but it's unlikely to change. Please read the following
590 paragraphs carefully.</para>
592 <para id="x_490">Mercurial treats the path to a repository on the server as
593 relative to the remote user's home directory. For example, if
594 user <literal>foo</literal> on the server has a home directory
595 of <filename class="directory">/home/foo</filename>, then an
596 ssh URL that contains a path component of <filename
597 class="directory">bar</filename> <emphasis>really</emphasis>
598 refers to the directory <filename
599 class="directory">/home/foo/bar</filename>.</para>
601 <para id="x_491">If you want to specify a path relative to another user's
602 home directory, you can use a path that starts with a tilde
603 character followed by the user's name (let's call them
604 <literal>otheruser</literal>), like this.</para>
605 <programlisting>ssh://server/~otheruser/hg/repo</programlisting>
607 <para id="x_492">And if you really want to specify an
608 <emphasis>absolute</emphasis> path on the server, begin the
609 path component with two slashes, as in this example.</para>
610 <programlisting>ssh://server//absolute/path</programlisting>
611 </sect2>
613 <sect2>
614 <title>Finding an ssh client for your system</title>
616 <para id="x_493">Almost every Unix-like system comes with OpenSSH
617 preinstalled. If you're using such a system, run
618 <literal>which ssh</literal> to find out if the
619 <command>ssh</command> command is installed (it's usually in
620 <filename class="directory">/usr/bin</filename>). In the
621 unlikely event that it isn't present, take a look at your
622 system documentation to figure out how to install it.</para>
624 <para id="x_494">On Windows, the TortoiseHg package is bundled
625 with a version of Simon Tatham's excellent
626 <command>plink</command> command, and you should not need to
627 do any further configuration.</para>
628 </sect2>
630 <sect2>
631 <title>Generating a key pair</title>
633 <para id="x_499">To avoid the need to repetitively type a
634 password every time you need to use your ssh client, I
635 recommend generating a key pair.</para>
637 <tip>
638 <title>Key pairs are not mandatory</title>
640 <para id="x_6a4">Mercurial knows nothing about ssh authentication or key
641 pairs. You can, if you like, safely ignore this section and
642 the one that follows until you grow tired of repeatedly
643 typing ssh passwords.</para>
644 </tip>
646 <itemizedlist>
647 <listitem>
648 <para id="x_6a5">On a Unix-like system, the
649 <command>ssh-keygen</command> command will do the
650 trick.</para>
651 <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need
652 to download a command named <command>puttygen</command>
653 from <ulink
654 url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the
655 PuTTY web site</ulink> to generate a key pair. See
656 <ulink
657 url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the
658 <command>puttygen</command> documentation</ulink> for
659 details of how use the command.</para>
660 </listitem>
661 </itemizedlist>
663 <para id="x_49a">When you generate a key pair, it's usually
664 <emphasis>highly</emphasis> advisable to protect it with a
665 passphrase. (The only time that you might not want to do this
666 is when you're using the ssh protocol for automated tasks on a
667 secure network.)</para>
669 <para id="x_49b">Simply generating a key pair isn't enough, however.
670 You'll need to add the public key to the set of authorised
671 keys for whatever user you're logging in remotely as. For
672 servers using OpenSSH (the vast majority), this will mean
673 adding the public key to a list in a file called <filename
674 role="special">authorized_keys</filename> in their <filename
675 role="special" class="directory">.ssh</filename>
676 directory.</para>
678 <para id="x_49c">On a Unix-like system, your public key will have a
679 <filename>.pub</filename> extension. If you're using
680 <command>puttygen</command> on Windows, you can save the
681 public key to a file of your choosing, or paste it from the
682 window it's displayed in straight into the <filename
683 role="special">authorized_keys</filename> file.</para>
684 </sect2>
685 <sect2>
686 <title>Using an authentication agent</title>
688 <para id="x_49d">An authentication agent is a daemon that stores
689 passphrases in memory (so it will forget passphrases if you
690 log out and log back in again). An ssh client will notice if
691 it's running, and query it for a passphrase. If there's no
692 authentication agent running, or the agent doesn't store the
693 necessary passphrase, you'll have to type your passphrase
694 every time Mercurial tries to communicate with a server on
695 your behalf (e.g. whenever you pull or push changes).</para>
697 <para id="x_49e">The downside of storing passphrases in an agent is that
698 it's possible for a well-prepared attacker to recover the
699 plain text of your passphrases, in some cases even if your
700 system has been power-cycled. You should make your own
701 judgment as to whether this is an acceptable risk. It
702 certainly saves a lot of repeated typing.</para>
704 <itemizedlist>
705 <listitem>
706 <para id="x_49f">On Unix-like systems, the agent is called
707 <command>ssh-agent</command>, and it's often run
708 automatically for you when you log in. You'll need to use
709 the <command>ssh-add</command> command to add passphrases
710 to the agent's store.</para>
711 </listitem>
712 <listitem>
713 <para id="x_6a7">On Windows, if you're using TortoiseHg, the
714 <command>pageant</command> command acts as the agent. As
715 with <command>puttygen</command>, you'll need to <ulink
716 url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download
717 <command>pageant</command></ulink> from the PuTTY web
718 site and read <ulink
719 url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its
720 documentation</ulink>. The <command>pageant</command>
721 command adds an icon to your system tray that will let you
722 manage stored passphrases.</para>
723 </listitem>
724 </itemizedlist>
725 </sect2>
727 <sect2>
728 <title>Configuring the server side properly</title>
730 <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
731 a variety of things can go wrong. Add Mercurial
732 on top, and there's plenty more scope for head-scratching.
733 Most of these potential problems occur on the server side, not
734 the client side. The good news is that once you've gotten a
735 configuration working, it will usually continue to work
736 indefinitely.</para>
738 <para id="x_4a1">Before you try using Mercurial to talk to an ssh server,
739 it's best to make sure that you can use the normal
740 <command>ssh</command> or <command>putty</command> command to
741 talk to the server first. If you run into problems with using
742 these commands directly, Mercurial surely won't work. Worse,
743 it will obscure the underlying problem. Any time you want to
744 debug ssh-related Mercurial problems, you should drop back to
745 making sure that plain ssh client commands work first,
746 <emphasis>before</emphasis> you worry about whether there's a
747 problem with Mercurial.</para>
749 <para id="x_4a2">The first thing to be sure of on the server side is that
750 you can actually log in from another machine at all. If you
751 can't use <command>ssh</command> or <command>putty</command>
752 to log in, the error message you get may give you a few hints
753 as to what's wrong. The most common problems are as
754 follows.</para>
755 <itemizedlist>
756 <listitem><para id="x_4a3">If you get a <quote>connection refused</quote>
757 error, either there isn't an SSH daemon running on the
758 server at all, or it's inaccessible due to firewall
759 configuration.</para>
760 </listitem>
761 <listitem><para id="x_4a4">If you get a <quote>no route to host</quote>
762 error, you either have an incorrect address for the server
763 or a seriously locked down firewall that won't admit its
764 existence at all.</para>
765 </listitem>
766 <listitem><para id="x_4a5">If you get a <quote>permission denied</quote>
767 error, you may have mistyped the username on the server,
768 or you could have mistyped your key's passphrase or the
769 remote user's password.</para>
770 </listitem></itemizedlist>
771 <para id="x_4a6">In summary, if you're having trouble talking to the
772 server's ssh daemon, first make sure that one is running at
773 all. On many systems it will be installed, but disabled, by
774 default. Once you're done with this step, you should then
775 check that the server's firewall is configured to allow
776 incoming connections on the port the ssh daemon is listening
777 on (usually 22). Don't worry about more exotic possibilities
778 for misconfiguration until you've checked these two
779 first.</para>
781 <para id="x_4a7">If you're using an authentication agent on the client side
782 to store passphrases for your keys, you ought to be able to
783 log into the server without being prompted for a passphrase or
784 a password. If you're prompted for a passphrase, there are a
785 few possible culprits.</para>
786 <itemizedlist>
787 <listitem><para id="x_4a8">You might have forgotten to use
788 <command>ssh-add</command> or <command>pageant</command>
789 to store the passphrase.</para>
790 </listitem>
791 <listitem><para id="x_4a9">You might have stored the passphrase for the
792 wrong key.</para>
793 </listitem></itemizedlist>
794 <para id="x_4aa">If you're being prompted for the remote user's password,
795 there are another few possible problems to check.</para>
796 <itemizedlist>
797 <listitem><para id="x_4ab">Either the user's home directory or their
798 <filename role="special" class="directory">.ssh</filename>
799 directory might have excessively liberal permissions. As
800 a result, the ssh daemon will not trust or read their
801 <filename role="special">authorized_keys</filename> file.
802 For example, a group-writable home or <filename
803 role="special" class="directory">.ssh</filename>
804 directory will often cause this symptom.</para>
805 </listitem>
806 <listitem><para id="x_4ac">The user's <filename
807 role="special">authorized_keys</filename> file may have
808 a problem. If anyone other than the user owns or can write
809 to that file, the ssh daemon will not trust or read
810 it.</para>
811 </listitem></itemizedlist>
813 <para id="x_4ad">In the ideal world, you should be able to run the
814 following command successfully, and it should print exactly
815 one line of output, the current date and time.</para>
816 <programlisting>ssh myserver date</programlisting>
818 <para id="x_4ae">If, on your server, you have login scripts that print
819 banners or other junk even when running non-interactive
820 commands like this, you should fix them before you continue,
821 so that they only print output if they're run interactively.
822 Otherwise these banners will at least clutter up Mercurial's
823 output. Worse, they could potentially cause problems with
824 running Mercurial commands remotely. Mercurial tries to
825 detect and ignore banners in non-interactive
826 <command>ssh</command> sessions, but it is not foolproof. (If
827 you're editing your login scripts on your server, the usual
828 way to see if a login script is running in an interactive
829 shell is to check the return code from the command
830 <literal>tty -s</literal>.)</para>
832 <para id="x_4af">Once you've verified that plain old ssh is working with
833 your server, the next step is to ensure that Mercurial runs on
834 the server. The following command should run
835 successfully:</para>
837 <programlisting>ssh myserver hg version</programlisting>
839 <para id="x_4b0">If you see an error message instead of normal <command
840 role="hg-cmd">hg version</command> output, this is usually
841 because you haven't installed Mercurial to <filename
842 class="directory">/usr/bin</filename>. Don't worry if this
843 is the case; you don't need to do that. But you should check
844 for a few possible problems.</para>
845 <itemizedlist>
846 <listitem><para id="x_4b1">Is Mercurial really installed on the server at
847 all? I know this sounds trivial, but it's worth
848 checking!</para>
849 </listitem>
850 <listitem><para id="x_4b2">Maybe your shell's search path (usually set
851 via the <envar>PATH</envar> environment variable) is
852 simply misconfigured.</para>
853 </listitem>
854 <listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment
855 variable is only being set to point to the location of the
856 <command>hg</command> executable if the login session is
857 interactive. This can happen if you're setting the path
858 in the wrong shell login script. See your shell's
859 documentation for details.</para>
860 </listitem>
861 <listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment
862 variable may need to contain the path to the Mercurial
863 Python modules. It might not be set at all; it could be
864 incorrect; or it may be set only if the login is
865 interactive.</para>
866 </listitem></itemizedlist>
868 <para id="x_4b5">If you can run <command role="hg-cmd">hg version</command>
869 over an ssh connection, well done! You've got the server and
870 client sorted out. You should now be able to use Mercurial to
871 access repositories hosted by that username on that server.
872 If you run into problems with Mercurial and ssh at this point,
873 try using the <option role="hg-opt-global">--debug</option>
874 option to get a clearer picture of what's going on.</para>
875 </sect2>
876 <sect2>
877 <title>Using compression with ssh</title>
879 <para id="x_4b6">Mercurial does not compress data when it uses the ssh
880 protocol, because the ssh protocol can transparently compress
881 data. However, the default behavior of ssh clients is
882 <emphasis>not</emphasis> to request compression.</para>
884 <para id="x_4b7">Over any network other than a fast LAN (even a wireless
885 network), using compression is likely to significantly speed
886 up Mercurial's network operations. For example, over a WAN,
887 someone measured compression as reducing the amount of time
888 required to clone a particularly large repository from 51
889 minutes to 17 minutes.</para>
891 <para id="x_4b8">Both <command>ssh</command> and <command>plink</command>
892 accept a <option role="cmd-opt-ssh">-C</option> option which
893 turns on compression. You can easily edit your <filename
894 role="special">~/.hgrc</filename> to enable compression for
895 all of Mercurial's uses of the ssh protocol. Here is how to
896 do so for regular <command>ssh</command> on Unix-like systems,
897 for example.</para>
898 <programlisting>[ui]
899 ssh = ssh -C</programlisting>
901 <para id="x_4b9">If you use <command>ssh</command> on a
902 Unix-like system, you can configure it to always use
903 compression when talking to your server. To do this, edit
904 your <filename role="special">.ssh/config</filename> file
905 (which may not yet exist), as follows.</para>
907 <programlisting>Host hg
908 Compression yes
909 HostName hg.example.com</programlisting>
911 <para id="x_4ba">This defines a hostname alias,
912 <literal>hg</literal>. When you use that hostname on the
913 <command>ssh</command> command line or in a Mercurial
914 <literal>ssh</literal>-protocol URL, it will cause
915 <command>ssh</command> to connect to
916 <literal>hg.example.com</literal> and use compression. This
917 gives you both a shorter name to type and compression, each of
918 which is a good thing in its own right.</para>
919 </sect2>
920 </sect1>
922 <sect1 id="sec:collab:cgi">
923 <title>Serving over HTTP using CGI</title>
925 <para id="x_6a8">The simplest way to host one or more repositories in a
926 permanent way is to use a web server and Mercurial's CGI
927 support.</para>
929 <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
930 CGI interface can take anything from a few moments to several
931 hours.</para>
933 <para id="x_4bc">We'll begin with the simplest of examples, and work our way
934 towards a more complex configuration. Even for the most basic
935 case, you're almost certainly going to need to read and modify
936 your web server's configuration.</para>
938 <note>
939 <title>High pain tolerance required</title>
941 <para id="x_4bd">Configuring a web server is a complex, fiddly,
942 and highly system-dependent activity. I can't possibly give
943 you instructions that will cover anything like all of the
944 cases you will encounter. Please use your discretion and
945 judgment in following the sections below. Be prepared to make
946 plenty of mistakes, and to spend a lot of time reading your
947 server's error logs.</para>
949 <para id="x_6a9">If you don't have a strong stomach for tweaking
950 configurations over and over, or a compelling need to host
951 your own services, you might want to try one of the public
952 hosting services that I mentioned earlier.</para>
953 </note>
955 <sect2>
956 <title>Web server configuration checklist</title>
958 <para id="x_4be">Before you continue, do take a few moments to check a few
959 aspects of your system's setup.</para>
961 <orderedlist>
962 <listitem><para id="x_4bf">Do you have a web server installed
963 at all? Mac OS X and some Linux distributions ship with
964 Apache, but many other systems may not have a web server
965 installed.</para>
966 </listitem>
967 <listitem><para id="x_4c0">If you have a web server installed, is it
968 actually running? On most systems, even if one is
969 present, it will be disabled by default.</para>
970 </listitem>
971 <listitem><para id="x_4c1">Is your server configured to allow you to run
972 CGI programs in the directory where you plan to do so?
973 Most servers default to explicitly disabling the ability
974 to run CGI programs.</para>
975 </listitem></orderedlist>
977 <para id="x_4c2">If you don't have a web server installed, and don't have
978 substantial experience configuring Apache, you should consider
979 using the <literal>lighttpd</literal> web server instead of
980 Apache. Apache has a well-deserved reputation for baroque and
981 confusing configuration. While <literal>lighttpd</literal> is
982 less capable in some ways than Apache, most of these
983 capabilities are not relevant to serving Mercurial
984 repositories. And <literal>lighttpd</literal> is undeniably
985 <emphasis>much</emphasis> easier to get started with than
986 Apache.</para>
987 </sect2>
989 <sect2>
990 <title>Basic CGI configuration</title>
992 <para id="x_4c3">On Unix-like systems, it's common for users to have a
993 subdirectory named something like <filename
994 class="directory">public_html</filename> in their home
995 directory, from which they can serve up web pages. A file
996 named <filename>foo</filename> in this directory will be
997 accessible at a URL of the form
998 <literal>http://www.example.com/username/foo</literal>.</para>
1000 <para id="x_4c4">To get started, find the <filename
1001 role="special">hgweb.cgi</filename> script that should be
1002 present in your Mercurial installation. If you can't quickly
1003 find a local copy on your system, simply download one from the
1004 master Mercurial repository at <ulink
1005 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>
1007 <para id="x_4c5">You'll need to copy this script into your <filename
1008 class="directory">public_html</filename> directory, and
1009 ensure that it's executable.</para>
1010 <programlisting>cp .../hgweb.cgi ~/public_html
1011 chmod 755 ~/public_html/hgweb.cgi</programlisting>
1012 <para id="x_4c6">The <literal>755</literal> argument to
1013 <command>chmod</command> is a little more general than just
1014 making the script executable: it ensures that the script is
1015 executable by anyone, and that <quote>group</quote> and
1016 <quote>other</quote> write permissions are
1017 <emphasis>not</emphasis> set. If you were to leave those
1018 write permissions enabled, Apache's <literal>suexec</literal>
1019 subsystem would likely refuse to execute the script. In fact,
1020 <literal>suexec</literal> also insists that the
1021 <emphasis>directory</emphasis> in which the script resides
1022 must not be writable by others.</para>
1023 <programlisting>chmod 755 ~/public_html</programlisting>
1025 <sect3 id="sec:collab:wtf">
1026 <title>What could <emphasis>possibly</emphasis> go
1027 wrong?</title>
1029 <para id="x_4c7">Once you've copied the CGI script into place,
1030 go into a web browser, and try to open the URL
1031 <literal>http://myhostname/~myuser/hgweb.cgi</literal>,
1032 <emphasis>but</emphasis> brace yourself for instant failure.
1033 There's a high probability that trying to visit this URL
1034 will fail, and there are many possible reasons for this. In
1035 fact, you're likely to stumble over almost every one of the
1036 possible errors below, so please read carefully. The
1037 following are all of the problems I ran into on a system
1038 running Fedora 7, with a fresh installation of Apache, and a
1039 user account that I created specially to perform this
1040 exercise.</para>
1042 <para id="x_4c8">Your web server may have per-user directories disabled.
1043 If you're using Apache, search your config file for a
1044 <literal>UserDir</literal> directive. If there's none
1045 present, per-user directories will be disabled. If one
1046 exists, but its value is <literal>disabled</literal>, then
1047 per-user directories will be disabled. Otherwise, the
1048 string after <literal>UserDir</literal> gives the name of
1049 the subdirectory that Apache will look in under your home
1050 directory, for example <filename
1051 class="directory">public_html</filename>.</para>
1053 <para id="x_4c9">Your file access permissions may be too restrictive.
1054 The web server must be able to traverse your home directory
1055 and directories under your <filename
1056 class="directory">public_html</filename> directory, and
1057 read files under the latter too. Here's a quick recipe to
1058 help you to make your permissions more appropriate.</para>
1059 <programlisting>chmod 755 ~
1060 find ~/public_html -type d -print0 | xargs -0r chmod 755
1061 find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting>
1063 <para id="x_4ca">The other possibility with permissions is that you might
1064 get a completely empty window when you try to load the
1065 script. In this case, it's likely that your access
1066 permissions are <emphasis>too permissive</emphasis>. Apache's
1067 <literal>suexec</literal> subsystem won't execute a script
1068 that's group- or world-writable, for example.</para>
1070 <para id="x_4cb">Your web server may be configured to disallow execution
1071 of CGI programs in your per-user web directory. Here's
1072 Apache's default per-user configuration from my Fedora
1073 system.</para>
1075 &ch06-apache-config.lst;
1077 <para id="x_4cc">If you find a similar-looking
1078 <literal>Directory</literal> group in your Apache
1079 configuration, the directive to look at inside it is
1080 <literal>Options</literal>. Add <literal>ExecCGI</literal>
1081 to the end of this list if it's missing, and restart the web
1082 server.</para>
1084 <para id="x_4cd">If you find that Apache serves you the text of the CGI
1085 script instead of executing it, you may need to either
1086 uncomment (if already present) or add a directive like
1087 this.</para>
1088 <programlisting>AddHandler cgi-script .cgi</programlisting>
1090 <para id="x_4ce">The next possibility is that you might be served with a
1091 colourful Python backtrace claiming that it can't import a
1092 <literal>mercurial</literal>-related module. This is
1093 actually progress! The server is now capable of executing
1094 your CGI script. This error is only likely to occur if
1095 you're running a private installation of Mercurial, instead
1096 of a system-wide version. Remember that the web server runs
1097 the CGI program without any of the environment variables
1098 that you take for granted in an interactive session. If
1099 this error happens to you, edit your copy of <filename
1100 role="special">hgweb.cgi</filename> and follow the
1101 directions inside it to correctly set your
1102 <envar>PYTHONPATH</envar> environment variable.</para>
1104 <para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be
1105 served with another colourful Python backtrace: this one
1106 will complain that it can't find <filename
1107 class="directory">/path/to/repository</filename>. Edit
1108 your <filename role="special">hgweb.cgi</filename> script
1109 and replace the <filename
1110 class="directory">/path/to/repository</filename> string
1111 with the complete path to the repository you want to serve
1112 up.</para>
1114 <para id="x_4d0">At this point, when you try to reload the page, you
1115 should be presented with a nice HTML view of your
1116 repository's history. Whew!</para>
1117 </sect3>
1119 <sect3>
1120 <title>Configuring lighttpd</title>
1122 <para id="x_4d1">To be exhaustive in my experiments, I tried configuring
1123 the increasingly popular <literal>lighttpd</literal> web
1124 server to serve the same repository as I described with
1125 Apache above. I had already overcome all of the problems I
1126 outlined with Apache, many of which are not server-specific.
1127 As a result, I was fairly sure that my file and directory
1128 permissions were good, and that my <filename
1129 role="special">hgweb.cgi</filename> script was properly
1130 edited.</para>
1132 <para id="x_4d2">Once I had Apache running, getting
1133 <literal>lighttpd</literal> to serve the repository was a
1134 snap (in other words, even if you're trying to use
1135 <literal>lighttpd</literal>, you should read the Apache
1136 section). I first had to edit the
1137 <literal>mod_access</literal> section of its config file to
1138 enable <literal>mod_cgi</literal> and
1139 <literal>mod_userdir</literal>, both of which were disabled
1140 by default on my system. I then added a few lines to the
1141 end of the config file, to configure these modules.</para>
1142 <programlisting>userdir.path = "public_html"
1143 cgi.assign = (".cgi" => "" )</programlisting>
1144 <para id="x_4d3">With this done, <literal>lighttpd</literal> ran
1145 immediately for me. If I had configured
1146 <literal>lighttpd</literal> before Apache, I'd almost
1147 certainly have run into many of the same system-level
1148 configuration problems as I did with Apache. However, I
1149 found <literal>lighttpd</literal> to be noticeably easier to
1150 configure than Apache, even though I've used Apache for over
1151 a decade, and this was my first exposure to
1152 <literal>lighttpd</literal>.</para>
1153 </sect3>
1154 </sect2>
1156 <sect2>
1157 <title>Sharing multiple repositories with one CGI script</title>
1159 <para id="x_4d4">The <filename role="special">hgweb.cgi</filename> script
1160 only lets you publish a single repository, which is an
1161 annoying restriction. If you want to publish more than one
1162 without wracking yourself with multiple copies of the same
1163 script, each with different names, a better choice is to use
1164 the <filename role="special">hgwebdir.cgi</filename>
1165 script.</para>
1167 <para id="x_4d5">The procedure to configure <filename
1168 role="special">hgwebdir.cgi</filename> is only a little more
1169 involved than for <filename
1170 role="special">hgweb.cgi</filename>. First, you must obtain
1171 a copy of the script. If you don't have one handy, you can
1172 download a copy from the master Mercurial repository at <ulink
1173 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>
1175 <para id="x_4d6">You'll need to copy this script into your <filename
1176 class="directory">public_html</filename> directory, and
1177 ensure that it's executable.</para>
1179 <programlisting>cp .../hgwebdir.cgi ~/public_html
1180 chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
1182 <para id="x_4d7">With basic configuration out of the way, try to
1183 visit <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>
1184 in your browser. It should
1185 display an empty list of repositories. If you get a blank
1186 window or error message, try walking through the list of
1187 potential problems in <xref
1188 linkend="sec:collab:wtf"/>.</para>
1190 <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename>
1191 script relies on an external configuration file. By default,
1192 it searches for a file named <filename
1193 role="special">hgweb.config</filename> in the same directory
1194 as itself. You'll need to create this file, and make it
1195 world-readable. The format of the file is similar to a
1196 Windows <quote>ini</quote> file, as understood by Python's
1197 <literal>ConfigParser</literal>
1198 <citation>web:configparser</citation> module.</para>
1200 <para id="x_4d9">The easiest way to configure <filename
1201 role="special">hgwebdir.cgi</filename> is with a section
1202 named <literal>collections</literal>. This will automatically
1203 publish <emphasis>every</emphasis> repository under the
1204 directories you name. The section should look like
1205 this:</para>
1206 <programlisting>[collections]
1207 /my/root = /my/root</programlisting>
1208 <para id="x_4da">Mercurial interprets this by looking at the directory name
1209 on the <emphasis>right</emphasis> hand side of the
1210 <quote><literal>=</literal></quote> sign; finding repositories
1211 in that directory hierarchy; and using the text on the
1212 <emphasis>left</emphasis> to strip off matching text from the
1213 names it will actually list in the web interface. The
1214 remaining component of a path after this stripping has
1215 occurred is called a <quote>virtual path</quote>.</para>
1217 <para id="x_4db">Given the example above, if we have a
1218 repository whose local path is <filename
1219 class="directory">/my/root/this/repo</filename>, the CGI
1220 script will strip the leading <filename
1221 class="directory">/my/root</filename> from the name, and
1222 publish the repository with a virtual path of <filename
1223 class="directory">this/repo</filename>. If the base URL for
1224 our CGI script is
1225 <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>, the
1226 complete URL for that repository will be
1227 <literal>http://myhostname/~myuser/hgwebdir.cgi/this/repo</literal>.</para>
1229 <para id="x_4dc">If we replace <filename
1230 class="directory">/my/root</filename> on the left hand side
1231 of this example with <filename
1232 class="directory">/my</filename>, then <filename
1233 role="special">hgwebdir.cgi</filename> will only strip off
1234 <filename class="directory">/my</filename> from the repository
1235 name, and will give us a virtual path of <filename
1236 class="directory">root/this/repo</filename> instead of
1237 <filename class="directory">this/repo</filename>.</para>
1239 <para id="x_4dd">The <filename role="special">hgwebdir.cgi</filename>
1240 script will recursively search each directory listed in the
1241 <literal>collections</literal> section of its configuration
1242 file, but it will <literal>not</literal> recurse into the
1243 repositories it finds.</para>
1245 <para id="x_4de">The <literal>collections</literal> mechanism makes it easy
1246 to publish many repositories in a <quote>fire and
1247 forget</quote> manner. You only need to set up the CGI
1248 script and configuration file one time. Afterwards, you can
1249 publish or unpublish a repository at any time by simply moving
1250 it into, or out of, the directory hierarchy in which you've
1251 configured <filename role="special">hgwebdir.cgi</filename> to
1252 look.</para>
1254 <sect3>
1255 <title>Explicitly specifying which repositories to
1256 publish</title>
1258 <para id="x_4df">In addition to the <literal>collections</literal>
1259 mechanism, the <filename
1260 role="special">hgwebdir.cgi</filename> script allows you
1261 to publish a specific list of repositories. To do so,
1262 create a <literal>paths</literal> section, with contents of
1263 the following form.</para>
1264 <programlisting>[paths]
1265 repo1 = /my/path/to/some/repo
1266 repo2 = /some/path/to/another</programlisting>
1267 <para id="x_4e0">In this case, the virtual path (the component that will
1268 appear in a URL) is on the left hand side of each
1269 definition, while the path to the repository is on the
1270 right. Notice that there does not need to be any
1271 relationship between the virtual path you choose and the
1272 location of a repository in your filesystem.</para>
1274 <para id="x_4e1">If you wish, you can use both the
1275 <literal>collections</literal> and <literal>paths</literal>
1276 mechanisms simultaneously in a single configuration
1277 file.</para>
1279 <note>
1280 <title>Beware duplicate virtual paths</title>
1282 <para id="x_4e2"> If several repositories have the same
1283 virtual path, <filename
1284 role="special">hgwebdir.cgi</filename> will not report
1285 an error. Instead, it will behave unpredictably.</para>
1286 </note>
1287 </sect3>
1288 </sect2>
1290 <sect2>
1291 <title>Downloading source archives</title>
1293 <para id="x_4e3">Mercurial's web interface lets users download an archive
1294 of any revision. This archive will contain a snapshot of the
1295 working directory as of that revision, but it will not contain
1296 a copy of the repository data.</para>
1298 <para id="x_4e4">By default, this feature is not enabled. To enable it,
1299 you'll need to add an <envar
1300 role="rc-item-web">allow_archive</envar> item to the
1301 <literal role="rc-web">web</literal> section of your <filename
1302 role="special">~/.hgrc</filename>; see below for details.</para>
1303 </sect2>
1304 <sect2>
1305 <title>Web configuration options</title>
1307 <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd">hg
1308 serve</command> command, and the <filename
1309 role="special">hgweb.cgi</filename> and <filename
1310 role="special">hgwebdir.cgi</filename> scripts) have a
1311 number of configuration options that you can set. These
1312 belong in a section named <literal
1313 role="rc-web">web</literal>.</para>
1314 <itemizedlist>
1315 <listitem><para id="x_4e6"><envar
1316 role="rc-item-web">allow_archive</envar>: Determines
1317 which (if any) archive download mechanisms Mercurial
1318 supports. If you enable this feature, users of the web
1319 interface will be able to download an archive of whatever
1320 revision of a repository they are viewing. To enable the
1321 archive feature, this item must take the form of a
1322 sequence of words drawn from the list below.</para>
1323 <itemizedlist>
1324 <listitem><para id="x_4e7"><literal>bz2</literal>: A
1325 <command>tar</command> archive, compressed using
1326 <literal>bzip2</literal> compression. This has the
1327 best compression ratio, but uses the most CPU time on
1328 the server.</para>
1329 </listitem>
1330 <listitem><para id="x_4e8"><literal>gz</literal>: A
1331 <command>tar</command> archive, compressed using
1332 <literal>gzip</literal> compression.</para>
1333 </listitem>
1334 <listitem><para id="x_4e9"><literal>zip</literal>: A
1335 <command>zip</command> archive, compressed using LZW
1336 compression. This format has the worst compression
1337 ratio, but is widely used in the Windows world.</para>
1338 </listitem>
1339 </itemizedlist>
1340 <para id="x_4ea"> If you provide an empty list, or don't have an
1341 <envar role="rc-item-web">allow_archive</envar> entry at
1342 all, this feature will be disabled. Here is an example of
1343 how to enable all three supported formats.</para>
1344 <programlisting>[web]
1345 allow_archive = bz2 gz zip</programlisting>
1346 </listitem>
1347 <listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>:
1348 Boolean. Determines whether the web interface allows
1349 remote users to <command role="hg-cmd">hg pull</command>
1350 and <command role="hg-cmd">hg clone</command> this
1351 repository over HTTP. If set to <literal>no</literal> or
1352 <literal>false</literal>, only the
1353 <quote>human-oriented</quote> portion of the web interface
1354 is available.</para>
1355 </listitem>
1356 <listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>:
1357 String. A free-form (but preferably brief) string
1358 identifying the person or group in charge of the
1359 repository. This often contains the name and email
1360 address of a person or mailing list. It often makes sense
1361 to place this entry in a repository's own <filename
1362 role="special">.hg/hgrc</filename> file, but it can make
1363 sense to use in a global <filename
1364 role="special">~/.hgrc</filename> if every repository
1365 has a single maintainer.</para>
1366 </listitem>
1367 <listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>:
1368 Integer. The default maximum number of changesets to
1369 display in a single page of output.</para>
1370 </listitem>
1371 <listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>:
1372 Integer. The default maximum number of modified files to
1373 display in a single page of output.</para>
1374 </listitem>
1375 <listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>:
1376 Integer. If the web interface displays alternating
1377 <quote>stripes</quote> to make it easier to visually align
1378 rows when you are looking at a table, this number controls
1379 the number of rows in each stripe.</para>
1380 </listitem>
1381 <listitem><para id="x_4f0"><envar
1382 role="rc-item-web">style</envar>: Controls the template
1383 Mercurial uses to display the web interface. Mercurial
1384 ships with several web templates.</para>
1385 <itemizedlist>
1386 <listitem>
1387 <para id="x_6aa"><literal>coal</literal> is monochromatic.</para>
1388 </listitem>
1389 <listitem>
1390 <para id="x_6ab"><literal>gitweb</literal> emulates the visual
1391 style of git's web interface.</para>
1392 </listitem>
1393 <listitem>
1394 <para id="x_6ac"><literal>monoblue</literal> uses solid blues and
1395 greys.</para>
1396 </listitem>
1397 <listitem>
1398 <para id="x_6ad"><literal>paper</literal> is the default.</para>
1399 </listitem>
1400 <listitem>
1401 <para id="x_6ae"><literal>spartan</literal> was the default for a
1402 long time.</para>
1403 </listitem>
1404 </itemizedlist>
1405 <para id="x_6af">You can
1406 also specify a custom template of your own; see
1407 <xref linkend="chap:template"/> for details. Here, you can
1408 see how to enable the <literal>gitweb</literal>
1409 style.</para>
1410 <programlisting>[web]
1411 style = gitweb</programlisting>
1412 </listitem>
1413 <listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>:
1414 Path. The directory in which to search for template
1415 files. By default, Mercurial searches in the directory in
1416 which it was installed.</para>
1417 </listitem></itemizedlist>
1418 <para id="x_4f2">If you are using <filename
1419 role="special">hgwebdir.cgi</filename>, you can place a few
1420 configuration items in a <literal role="rc-web">web</literal>
1421 section of the <filename
1422 role="special">hgweb.config</filename> file instead of a
1423 <filename role="special">~/.hgrc</filename> file, for
1424 convenience. These items are <envar
1425 role="rc-item-web">motd</envar> and <envar
1426 role="rc-item-web">style</envar>.</para>
1428 <sect3>
1429 <title>Options specific to an individual repository</title>
1431 <para id="x_4f3">A few <literal role="rc-web">web</literal> configuration
1432 items ought to be placed in a repository's local <filename
1433 role="special">.hg/hgrc</filename>, rather than a user's
1434 or global <filename role="special">~/.hgrc</filename>.</para>
1435 <itemizedlist>
1436 <listitem><para id="x_4f4"><envar
1437 role="rc-item-web">description</envar>: String. A
1438 free-form (but preferably brief) string that describes
1439 the contents or purpose of the repository.</para>
1440 </listitem>
1441 <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>:
1442 String. The name to use for the repository in the web
1443 interface. This overrides the default name, which is
1444 the last component of the repository's path.</para>
1445 </listitem></itemizedlist>
1446 </sect3>
1448 <sect3>
1449 <title>Options specific to the <command role="hg-cmd">hg
1450 serve</command> command</title>
1452 <para id="x_4f6">Some of the items in the <literal
1453 role="rc-web">web</literal> section of a <filename
1454 role="special">~/.hgrc</filename> file are only for use
1455 with the <command role="hg-cmd">hg serve</command>
1456 command.</para>
1457 <itemizedlist>
1458 <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>:
1459 Path. The name of a file into which to write an access
1460 log. By default, the <command role="hg-cmd">hg
1461 serve</command> command writes this information to
1462 standard output, not to a file. Log entries are written
1463 in the standard <quote>combined</quote> file format used
1464 by almost all web servers.</para>
1465 </listitem>
1466 <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>:
1467 String. The local address on which the server should
1468 listen for incoming connections. By default, the server
1469 listens on all addresses.</para>
1470 </listitem>
1471 <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>:
1472 Path. The name of a file into which to write an error
1473 log. By default, the <command role="hg-cmd">hg
1474 serve</command> command writes this information to
1475 standard error, not to a file.</para>
1476 </listitem>
1477 <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>:
1478 Boolean. Whether to use the IPv6 protocol. By default,
1479 IPv6 is not used.</para>
1480 </listitem>
1481 <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>:
1482 Integer. The TCP port number on which the server should
1483 listen. The default port number used is 8000.</para>
1484 </listitem></itemizedlist>
1485 </sect3>
1487 <sect3>
1488 <title>Choosing the right <filename
1489 role="special">~/.hgrc</filename> file to add <literal
1490 role="rc-web">web</literal> items to</title>
1492 <para id="x_4fc">It is important to remember that a web server like
1493 Apache or <literal>lighttpd</literal> will run under a user
1494 ID that is different to yours. CGI scripts run by your
1495 server, such as <filename
1496 role="special">hgweb.cgi</filename>, will usually also run
1497 under that user ID.</para>
1499 <para id="x_4fd">If you add <literal role="rc-web">web</literal> items to
1500 your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that
1501 <filename role="special">~/.hgrc</filename> file. Those
1502 settings will thus only affect the behavior of the <command
1503 role="hg-cmd">hg serve</command> command when you run it.
1504 To cause CGI scripts to see your settings, either create a
1505 <filename role="special">~/.hgrc</filename> file in the
1506 home directory of the user ID that runs your web server, or
1507 add those settings to a system-wide <filename
1508 role="special">hgrc</filename> file.</para>
1509 </sect3>
1510 </sect2>
1511 </sect1>
1513 <sect1>
1514 <title>System-wide configuration</title>
1516 <para id="x_6b0">On Unix-like systems shared by multiple users (such as a
1517 server to which people publish changes), it often makes sense to
1518 set up some global default behaviors, such as what theme to use
1519 in web interfaces.</para>
1521 <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename>
1522 exists, Mercurial will read it at startup time and apply any
1523 configuration settings it finds in that file. It will also look
1524 for files ending in a <literal>.rc</literal> extension in a
1525 directory named <filename>/etc/mercurial/hgrc.d</filename>, and
1526 apply any configuration settings it finds in each of those
1527 files.</para>
1529 <sect2>
1530 <title>Making Mercurial more trusting</title>
1532 <para id="x_6b2">One situation in which a global <filename>hgrc</filename>
1533 can be useful is if users are pulling changes owned by other
1534 users. By default, Mercurial will not trust most of the
1535 configuration items in a <filename>.hg/hgrc</filename> file
1536 inside a repository that is owned by a different user. If we
1537 clone or pull changes from such a repository, Mercurial will
1538 print a warning stating that it does not trust their
1539 <filename>.hg/hgrc</filename>.</para>
1541 <para id="x_6b3">If everyone in a particular Unix group is on the same team
1542 and <emphasis>should</emphasis> trust each other's
1543 configuration settings, or we want to trust particular users,
1544 we can override Mercurial's skeptical defaults by creating a
1545 system-wide <filename>hgrc</filename> file such as the
1546 following:</para>
1548 <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
1549 [trusted]
1550 # Trust all entries in any hgrc file owned by the "editors" or
1551 # "www-data" groups.
1552 groups = editors, www-data
1554 # Trust entries in hgrc files owned by the following users.
1555 users = apache, bobo
1556 </programlisting>
1557 </sect2>
1558 </sect1>
1559 </chapter>
1561 <!--
1562 local variables:
1563 sgml-parent-document: ("00book.xml" "book" "chapter")
1564 end:
1565 -->