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