Mercurial > hgbook
comparison en/ch06-collab.xml @ 831:acf9dc5f088d
Add a skeletal preface.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Thu, 07 May 2009 21:07:35 -0700 |
parents | en/ch05-collab.xml@477d6a3e5023 |
children |
comparison
equal
deleted
inserted
replaced
830:cbdff5945f9d | 831:acf9dc5f088d |
---|---|
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> | |
2 | |
3 <chapter id="cha:collab"> | |
4 <?dbhtml filename="collaborating-with-other-people.html"?> | |
5 <title>Collaborating with other people</title> | |
6 | |
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> | |
12 | |
13 <sect1> | |
14 <title>Mercurial's web interface</title> | |
15 | |
16 <para id="x_44b">Mercurial has a powerful web interface that provides several | |
17 useful capabilities.</para> | |
18 | |
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> | |
25 | |
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> | |
35 | |
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> | |
41 | |
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> | |
46 | |
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> | |
50 | |
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> | |
57 | |
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> | |
64 | |
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> | |
72 | |
73 <sect1> | |
74 <title>Collaboration models</title> | |
75 | |
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> | |
82 | |
83 <sect2> | |
84 <title>Factors to keep in mind</title> | |
85 | |
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> | |
91 | |
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> | |
101 | |
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> | |
114 | |
115 <sect2> | |
116 <title>Informal anarchy</title> | |
117 | |
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> | |
122 | |
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> | |
131 | |
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> | |
145 | |
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> | |
154 | |
155 <sect2> | |
156 <title>A single central repository</title> | |
157 | |
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> | |
163 | |
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> | |
168 | |
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> | |
179 | |
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> | |
191 | |
192 <sect2> | |
193 <title>A hosted central repository</title> | |
194 | |
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> | |
201 | |
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> | |
206 | |
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> | |
212 | |
213 <sect2> | |
214 <title>Working with multiple branches</title> | |
215 | |
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> | |
228 | |
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> | |
237 | |
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> | |
241 | |
242 &interaction.branching.init; | |
243 | |
244 <para id="x_460">People clone it, make changes locally, test them, and push | |
245 them back.</para> | |
246 | |
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> | |
250 | |
251 &interaction.branching.tag; | |
252 | |
253 <para id="x_462">Let's say some ongoing | |
254 development occurs on the main branch.</para> | |
255 | |
256 &interaction.branching.main; | |
257 | |
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> | |
263 | |
264 &interaction.branching.update; | |
265 | |
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> | |
269 | |
270 &interaction.branching.clone; | |
271 | |
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> | |
276 | |
277 &interaction.branching.stable; | |
278 | |
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> | |
285 | |
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> | |
291 | |
292 &interaction.branching.merge; | |
293 | |
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> | |
301 | |
302 <sect2> | |
303 <title>Feature branches</title> | |
304 | |
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> | |
311 | |
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> | |
319 | |
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> | |
325 | |
326 <sect2> | |
327 <title>The release train</title> | |
328 | |
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> | |
333 | |
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> | |
341 | |
342 <sect2> | |
343 <title>The Linux kernel model</title> | |
344 | |
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> | |
352 | |
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> | |
359 | |
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> | |
371 | |
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> | |
382 | |
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> | |
389 | |
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> | |
400 | |
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> | |
407 | |
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> | |
416 | |
417 <sect2> | |
418 <title>Pull-only versus shared-push collaboration</title> | |
419 | |
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> | |
425 | |
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> | |
433 | |
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> | |
442 | |
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> | |
453 | |
454 <sect1> | |
455 <title>The technical side of sharing</title> | |
456 | |
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> | |
460 | |
461 <sect1 id="sec:collab:serve"> | |
462 <title>Informal sharing with <command role="hg-cmd">hg | |
463 serve</command></title> | |
464 | |
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> | |
469 | |
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> | |
480 | |
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> | |
497 | |
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> | |
506 | |
507 <sect2> | |
508 <title>A few things to keep in mind</title> | |
509 | |
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> | |
515 | |
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> | |
524 | |
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> | |
530 | |
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> | |
539 | |
540 <sect1 id="sec:collab:ssh"> | |
541 <title>Using the Secure Shell (ssh) protocol</title> | |
542 | |
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> | |
547 | |
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> | |
553 | |
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> | |
557 | |
558 <sect2> | |
559 <title>How to read and write ssh URLs</title> | |
560 | |
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> | |
584 | |
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> | |
591 | |
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> | |
600 | |
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> | |
606 | |
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> | |
612 | |
613 <sect2> | |
614 <title>Finding an ssh client for your system</title> | |
615 | |
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> | |
623 | |
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> | |
629 | |
630 <sect2> | |
631 <title>Generating a key pair</title> | |
632 | |
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> | |
636 | |
637 <tip> | |
638 <title>Key pairs are not mandatory</title> | |
639 | |
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> | |
645 | |
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> | |
662 | |
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> | |
668 | |
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> | |
677 | |
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> | |
687 | |
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> | |
696 | |
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> | |
703 | |
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> | |
726 | |
727 <sect2> | |
728 <title>Configuring the server side properly</title> | |
729 | |
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> | |
737 | |
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> | |
748 | |
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> | |
780 | |
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> | |
812 | |
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> | |
817 | |
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> | |
831 | |
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> | |
836 | |
837 <programlisting>ssh myserver hg version</programlisting> | |
838 | |
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> | |
867 | |
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> | |
878 | |
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> | |
883 | |
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> | |
890 | |
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> | |
900 | |
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> | |
906 | |
907 <programlisting>Host hg | |
908 Compression yes | |
909 HostName hg.example.com</programlisting> | |
910 | |
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> | |
921 | |
922 <sect1 id="sec:collab:cgi"> | |
923 <title>Serving over HTTP using CGI</title> | |
924 | |
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> | |
928 | |
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> | |
932 | |
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> | |
937 | |
938 <note> | |
939 <title>High pain tolerance required</title> | |
940 | |
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> | |
948 | |
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> | |
954 | |
955 <sect2> | |
956 <title>Web server configuration checklist</title> | |
957 | |
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> | |
960 | |
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> | |
976 | |
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> | |
988 | |
989 <sect2> | |
990 <title>Basic CGI configuration</title> | |
991 | |
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> | |
999 | |
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> | |
1006 | |
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> | |
1024 | |
1025 <sect3 id="sec:collab:wtf"> | |
1026 <title>What could <emphasis>possibly</emphasis> go | |
1027 wrong?</title> | |
1028 | |
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> | |
1041 | |
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> | |
1052 | |
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> | |
1062 | |
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> | |
1069 | |
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> | |
1074 | |
1075 &ch06-apache-config.lst; | |
1076 | |
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> | |
1083 | |
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> | |
1089 | |
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> | |
1103 | |
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> | |
1113 | |
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> | |
1118 | |
1119 <sect3> | |
1120 <title>Configuring lighttpd</title> | |
1121 | |
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> | |
1131 | |
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> | |
1155 | |
1156 <sect2> | |
1157 <title>Sharing multiple repositories with one CGI script</title> | |
1158 | |
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> | |
1166 | |
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> | |
1174 | |
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> | |
1178 | |
1179 <programlisting>cp .../hgwebdir.cgi ~/public_html | |
1180 chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting> | |
1181 | |
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> | |
1189 | |
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> | |
1199 | |
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> | |
1216 | |
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> | |
1228 | |
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> | |
1238 | |
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> | |
1244 | |
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> | |
1253 | |
1254 <sect3> | |
1255 <title>Explicitly specifying which repositories to | |
1256 publish</title> | |
1257 | |
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> | |
1273 | |
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> | |
1278 | |
1279 <note> | |
1280 <title>Beware duplicate virtual paths</title> | |
1281 | |
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> | |
1289 | |
1290 <sect2> | |
1291 <title>Downloading source archives</title> | |
1292 | |
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> | |
1297 | |
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> | |
1306 | |
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> | |
1427 | |
1428 <sect3> | |
1429 <title>Options specific to an individual repository</title> | |
1430 | |
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> | |
1447 | |
1448 <sect3> | |
1449 <title>Options specific to the <command role="hg-cmd">hg | |
1450 serve</command> command</title> | |
1451 | |
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> | |
1486 | |
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> | |
1491 | |
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> | |
1498 | |
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> | |
1512 | |
1513 <sect1> | |
1514 <title>System-wide configuration</title> | |
1515 | |
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> | |
1520 | |
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> | |
1528 | |
1529 <sect2> | |
1530 <title>Making Mercurial more trusting</title> | |
1531 | |
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> | |
1540 | |
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> | |
1547 | |
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 | |
1553 | |
1554 # Trust entries in hgrc files owned by the following users. | |
1555 users = apache, bobo | |
1556 </programlisting> | |
1557 </sect2> | |
1558 </sect1> | |
1559 </chapter> | |
1560 | |
1561 <!-- | |
1562 local variables: | |
1563 sgml-parent-document: ("00book.xml" "book" "chapter") | |
1564 end: | |
1565 --> |