hgbook
diff en/ch05-collab.xml @ 584:c838b3975bc6
Add IDs to paragraphs.
| author | Bryan O'Sullivan <bos@serpentine.com> |
|---|---|
| date | Thu Mar 19 21:18:52 2009 -0700 (2009-03-19) |
| parents | 28b5a5befb08 |
| children | b788b405e141 |
line diff
1.1 --- a/en/ch05-collab.xml Thu Mar 19 20:54:12 2009 -0700 1.2 +++ b/en/ch05-collab.xml Thu Mar 19 21:18:52 2009 -0700 1.3 @@ -4,7 +4,7 @@ 1.4 <?dbhtml filename="collaborating-with-other-people.html"?> 1.5 <title>Collaborating with other people</title> 1.6 1.7 - <para>As a completely decentralised tool, Mercurial doesn't impose 1.8 + <para id="x_44a">As a completely decentralised tool, Mercurial doesn't impose 1.9 any policy on how people ought to work with each other. However, 1.10 if you're new to distributed revision control, it helps to have 1.11 some tools and examples in mind when you're thinking about 1.12 @@ -13,15 +13,15 @@ 1.13 <sect1> 1.14 <title>Mercurial's web interface</title> 1.15 1.16 - <para>Mercurial has a powerful web interface that provides several 1.17 + <para id="x_44b">Mercurial has a powerful web interface that provides several 1.18 useful capabilities.</para> 1.19 1.20 - <para>For interactive use, the web interface lets you browse a 1.21 + <para id="x_44c">For interactive use, the web interface lets you browse a 1.22 single repository or a collection of repositories. You can view 1.23 the history of a repository, examine each change (comments and 1.24 diffs), and view the contents of each directory and file.</para> 1.25 1.26 - <para>Also for human consumption, the web interface provides an 1.27 + <para id="x_44d">Also for human consumption, the web interface provides an 1.28 RSS feed of the changes in a repository. This lets you 1.29 <quote>subscribe</quote> to a repository using your favourite 1.30 feed reader, and be automatically notified of activity in that 1.31 @@ -31,18 +31,18 @@ 1.32 configuration on the part of whoever is serving the 1.33 repository.</para> 1.34 1.35 - <para>The web interface also lets remote users clone a repository, 1.36 + <para id="x_44e">The web interface also lets remote users clone a repository, 1.37 pull changes from it, and (when the server is configured to 1.38 permit it) push changes back to it. Mercurial's HTTP tunneling 1.39 protocol aggressively compresses data, so that it works 1.40 efficiently even over low-bandwidth network connections.</para> 1.41 1.42 - <para>The easiest way to get started with the web interface is to 1.43 + <para id="x_44f">The easiest way to get started with the web interface is to 1.44 use your web browser to visit an existing repository, such as 1.45 the master Mercurial repository at <ulink 1.46 url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para> 1.47 1.48 - <para>If you're interested in providing a web interface to your 1.49 + <para id="x_450">If you're interested in providing a web interface to your 1.50 own repositories, Mercurial provides two ways to do this. The 1.51 first is using the <command role="hg-cmd">hg serve</command> 1.52 command, which is best suited to short-term 1.53 @@ -59,7 +59,7 @@ 1.54 <sect1> 1.55 <title>Collaboration models</title> 1.56 1.57 - <para>With a suitably flexible tool, making decisions about 1.58 + <para id="x_451">With a suitably flexible tool, making decisions about 1.59 workflow is much more of a social engineering challenge than a 1.60 technical one. Mercurial imposes few limitations on how you can 1.61 structure the flow of work in a project, so it's up to you and 1.62 @@ -69,13 +69,13 @@ 1.63 <sect2> 1.64 <title>Factors to keep in mind</title> 1.65 1.66 - <para>The most important aspect of any model that you must keep 1.67 + <para id="x_452">The most important aspect of any model that you must keep 1.68 in mind is how well it matches the needs and capabilities of 1.69 the people who will be using it. This might seem 1.70 self-evident; even so, you still can't afford to forget it for 1.71 a moment.</para> 1.72 1.73 - <para>I once put together a workflow model that seemed to make 1.74 + <para id="x_453">I once put together a workflow model that seemed to make 1.75 perfect sense to me, but that caused a considerable amount of 1.76 consternation and strife within my development team. In spite 1.77 of my attempts to explain why we needed a complex set of 1.78 @@ -85,7 +85,7 @@ 1.79 operating under, or face the consequences of those constraints 1.80 in the details of the model that I was advocating.</para> 1.81 1.82 - <para>Don't sweep foreseeable social or technical problems under 1.83 + <para id="x_454">Don't sweep foreseeable social or technical problems under 1.84 the rug. Whatever scheme you put into effect, you should plan 1.85 for mistakes and problem scenarios. Consider adding automated 1.86 machinery to prevent, or quickly recover from, trouble that 1.87 @@ -101,12 +101,12 @@ 1.88 <sect2> 1.89 <title>Informal anarchy</title> 1.90 1.91 - <para>I wouldn't suggest an <quote>anything goes</quote> 1.92 + <para id="x_455">I wouldn't suggest an <quote>anything goes</quote> 1.93 approach as something sustainable, but it's a model that's 1.94 easy to grasp, and it works perfectly well in a few unusual 1.95 situations.</para> 1.96 1.97 - <para>As one example, many projects have a loose-knit group of 1.98 + <para id="x_456">As one example, many projects have a loose-knit group of 1.99 collaborators who rarely physically meet each other. Some 1.100 groups like to overcome the isolation of working at a distance 1.101 by organising occasional <quote>sprints</quote>. In a sprint, 1.102 @@ -115,7 +115,7 @@ 1.103 place) and spend several days more or less locked in there, 1.104 hacking intensely on a handful of projects.</para> 1.105 1.106 - <para>A sprint is the perfect place to use the <command 1.107 + <para id="x_457">A sprint is the perfect place to use the <command 1.108 role="hg-cmd">hg serve</command> command, since <command 1.109 role="hg-cmd">hg serve</command> does not require any fancy 1.110 server infrastructure. You can get started with <command 1.111 @@ -129,7 +129,7 @@ 1.112 they can pull a bugfix from you and verify it; or they can 1.113 clone a branch containing a new feature and try it out.</para> 1.114 1.115 - <para>The charm, and the problem, with doing things in an ad hoc 1.116 + <para id="x_458">The charm, and the problem, with doing things in an ad hoc 1.117 fashion like this is that only people who know about your 1.118 changes, and where they are, can see them. Such an informal 1.119 approach simply doesn't scale beyond a handful people, because 1.120 @@ -140,18 +140,18 @@ 1.121 <sect2> 1.122 <title>A single central repository</title> 1.123 1.124 - <para>For smaller projects migrating from a centralised revision 1.125 + <para id="x_459">For smaller projects migrating from a centralised revision 1.126 control tool, perhaps the easiest way to get started is to 1.127 have changes flow through a single shared central repository. 1.128 This is also the most common <quote>building block</quote> for 1.129 more ambitious workflow schemes.</para> 1.130 1.131 - <para>Contributors start by cloning a copy of this repository. 1.132 + <para id="x_45a">Contributors start by cloning a copy of this repository. 1.133 They can pull changes from it whenever they need to, and some 1.134 (perhaps all) developers have permission to push a change back 1.135 when they're ready for other people to see it.</para> 1.136 1.137 - <para>Under this model, it can still often make sense for people 1.138 + <para id="x_45b">Under this model, it can still often make sense for people 1.139 to pull changes directly from each other, without going 1.140 through the central repository. Consider a case in which I 1.141 have a tentative bug fix, but I am worried that if I were to 1.142 @@ -162,7 +162,7 @@ 1.143 lets us put off publishing the potentially unsafe change until 1.144 it has had a little testing.</para> 1.145 1.146 - <para>In this kind of scenario, people usually use the 1.147 + <para id="x_45c">In this kind of scenario, people usually use the 1.148 <command>ssh</command> protocol to securely push changes to 1.149 the central repository, as documented in section <xref 1.150 linkend="sec:collab:ssh"/>. It's also 1.151 @@ -177,7 +177,7 @@ 1.152 <sect2> 1.153 <title>Working with multiple branches</title> 1.154 1.155 - <para>Projects of any significant size naturally tend to make 1.156 + <para id="x_45d">Projects of any significant size naturally tend to make 1.157 progress on several fronts simultaneously. In the case of 1.158 software, it's common for a project to go through periodic 1.159 official releases. A release might then go into 1.160 @@ -190,7 +190,7 @@ 1.161 different directions in which development is 1.162 proceeding.</para> 1.163 1.164 - <para>Mercurial is particularly well suited to managing a number 1.165 + <para id="x_45e">Mercurial is particularly well suited to managing a number 1.166 of simultaneous, but not identical, branches. Each 1.167 <quote>development direction</quote> can live in its own 1.168 central repository, and you can merge changes from one to 1.169 @@ -199,27 +199,27 @@ 1.170 branch will never affect a stable branch unless someone 1.171 explicitly merges those changes in.</para> 1.172 1.173 - <para>Here's an example of how this can work in practice. Let's 1.174 + <para id="x_45f">Here's an example of how this can work in practice. Let's 1.175 say you have one <quote>main branch</quote> on a central 1.176 server.</para> 1.177 1.178 &interaction.branching.init; 1.179 1.180 - <para>People clone it, make changes locally, test them, and push 1.181 + <para id="x_460">People clone it, make changes locally, test them, and push 1.182 them back.</para> 1.183 1.184 - <para>Once the main branch reaches a release milestone, you can 1.185 + <para id="x_461">Once the main branch reaches a release milestone, you can 1.186 use the <command role="hg-cmd">hg tag</command> command to 1.187 give a permanent name to the milestone revision.</para> 1.188 1.189 &interaction.branching.tag; 1.190 1.191 - <para>Let's say some ongoing 1.192 + <para id="x_462">Let's say some ongoing 1.193 development occurs on the main branch.</para> 1.194 1.195 &interaction.branching.main; 1.196 1.197 - <para>Using the tag that was recorded at the milestone, people 1.198 + <para id="x_463">Using the tag that was recorded at the milestone, people 1.199 who clone that repository at any time in the future can use 1.200 <command role="hg-cmd">hg update</command> to get a copy of 1.201 the working directory exactly as it was when that tagged 1.202 @@ -227,26 +227,26 @@ 1.203 1.204 &interaction.branching.update; 1.205 1.206 - <para>In addition, immediately after the main branch is tagged, 1.207 + <para id="x_464">In addition, immediately after the main branch is tagged, 1.208 someone can then clone the main branch on the server to a new 1.209 <quote>stable</quote> branch, also on the server.</para> 1.210 1.211 &interaction.branching.clone; 1.212 1.213 - <para>Someone who needs to make a change to the stable branch 1.214 + <para id="x_465">Someone who needs to make a change to the stable branch 1.215 can then clone <emphasis>that</emphasis> repository, make 1.216 their changes, commit, and push their changes back there.</para> 1.217 1.218 &interaction.branching.stable; 1.219 1.220 - <para>Because Mercurial repositories are independent, and 1.221 + <para id="x_466">Because Mercurial repositories are independent, and 1.222 Mercurial doesn't move changes around automatically, the 1.223 stable and main branches are <emphasis>isolated</emphasis> 1.224 from each other. The changes that you made on the main branch 1.225 don't <quote>leak</quote> to the stable branch, and vice 1.226 versa.</para> 1.227 1.228 - <para>You'll often want all of your bugfixes on the stable 1.229 + <para id="x_467">You'll often want all of your bugfixes on the stable 1.230 branch to show up on the main branch, too. Rather than 1.231 rewrite a bugfix on the main branch, you can simply pull and 1.232 merge changes from the stable to the main branch, and 1.233 @@ -254,7 +254,7 @@ 1.234 1.235 &interaction.branching.merge; 1.236 1.237 - <para>The main branch will still contain changes that are not on 1.238 + <para id="x_468">The main branch will still contain changes that are not on 1.239 the stable branch, but it will also contain all of the 1.240 bugfixes from the stable branch. The stable branch remains 1.241 unaffected by these changes.</para> 1.242 @@ -263,7 +263,7 @@ 1.243 <sect2> 1.244 <title>Feature branches</title> 1.245 1.246 - <para>For larger projects, an effective way to manage change is 1.247 + <para id="x_469">For larger projects, an effective way to manage change is 1.248 to break up a team into smaller groups. Each group has a 1.249 shared branch of its own, cloned from a single 1.250 <quote>master</quote> branch used by the entire project. 1.251 @@ -273,11 +273,11 @@ 1.252 <informalfigure id="fig:collab:feature-branches"> 1.253 <mediaobject><imageobject><imagedata 1.254 fileref="feature-branches"/></imageobject><textobject><phrase>XXX 1.255 - add text</phrase></textobject><caption><para>Feature 1.256 + add text</phrase></textobject><caption><para id="x_46a">Feature 1.257 branches</para></caption></mediaobject> 1.258 </informalfigure> 1.259 1.260 - <para>When a particular feature is deemed to be in suitable 1.261 + <para id="x_46b">When a particular feature is deemed to be in suitable 1.262 shape, someone on that feature team pulls and merges from the 1.263 master branch into the feature branch, then pushes back up to 1.264 the master branch.</para> 1.265 @@ -286,12 +286,12 @@ 1.266 <sect2> 1.267 <title>The release train</title> 1.268 1.269 - <para>Some projects are organised on a <quote>train</quote> 1.270 + <para id="x_46c">Some projects are organised on a <quote>train</quote> 1.271 basis: a release is scheduled to happen every few months, and 1.272 whatever features are ready when the <quote>train</quote> is 1.273 ready to leave are allowed in.</para> 1.274 1.275 - <para>This model resembles working with feature branches. The 1.276 + <para id="x_46d">This model resembles working with feature branches. The 1.277 difference is that when a feature branch misses a train, 1.278 someone on the feature team pulls and merges the changes that 1.279 went out on that train release into the feature branch, and 1.280 @@ -302,7 +302,7 @@ 1.281 <sect2> 1.282 <title>The Linux kernel model</title> 1.283 1.284 - <para>The development of the Linux kernel has a shallow 1.285 + <para id="x_46e">The development of the Linux kernel has a shallow 1.286 hierarchical structure, surrounded by a cloud of apparent 1.287 chaos. Because most Linux developers use 1.288 <command>git</command>, a distributed revision control tool 1.289 @@ -310,14 +310,14 @@ 1.290 describe the way work flows in that environment; if you like 1.291 the ideas, the approach translates well across tools.</para> 1.292 1.293 - <para>At the center of the community sits Linus Torvalds, the 1.294 + <para id="x_46f">At the center of the community sits Linus Torvalds, the 1.295 creator of Linux. He publishes a single source repository 1.296 that is considered the <quote>authoritative</quote> current 1.297 tree by the entire developer community. Anyone can clone 1.298 Linus's tree, but he is very choosy about whose trees he pulls 1.299 from.</para> 1.300 1.301 - <para>Linus has a number of <quote>trusted lieutenants</quote>. 1.302 + <para id="x_470">Linus has a number of <quote>trusted lieutenants</quote>. 1.303 As a general rule, he pulls whatever changes they publish, in 1.304 most cases without even reviewing those changes. Some of 1.305 those lieutenants are generally agreed to be 1.306 @@ -329,7 +329,7 @@ 1.307 If the maintainer reviews their changes and agrees to take 1.308 them, they'll pass them along to Linus in due course.</para> 1.309 1.310 - <para>Individual lieutenants have their own approaches to 1.311 + <para id="x_471">Individual lieutenants have their own approaches to 1.312 reviewing, accepting, and publishing changes; and for deciding 1.313 when to feed them to Linus. In addition, there are several 1.314 well known branches that people use for different purposes. 1.315 @@ -340,14 +340,14 @@ 1.316 that they are about to feed upstream; and so on. Others just 1.317 publish a single tree.</para> 1.318 1.319 - <para>This model has two notable features. The first is that 1.320 + <para id="x_472">This model has two notable features. The first is that 1.321 it's <quote>pull only</quote>. You have to ask, convince, or 1.322 beg another developer to take a change from you, because there 1.323 are almost no trees to which more than one person can push, 1.324 and there's no way to push changes into a tree that someone 1.325 else controls.</para> 1.326 1.327 - <para>The second is that it's based on reputation and acclaim. 1.328 + <para id="x_473">The second is that it's based on reputation and acclaim. 1.329 If you're an unknown, Linus will probably ignore changes from 1.330 you without even responding. But a subsystem maintainer will 1.331 probably review them, and will likely take them if they pass 1.332 @@ -358,14 +358,14 @@ 1.333 Linus hasn't yet accepted, people with similar interests may 1.334 pull your changes regularly to keep up with your work.</para> 1.335 1.336 - <para>Reputation and acclaim don't necessarily cross subsystem 1.337 + <para id="x_474">Reputation and acclaim don't necessarily cross subsystem 1.338 or <quote>people</quote> boundaries. If you're a respected 1.339 but specialised storage hacker, and you try to fix a 1.340 networking bug, that change will receive a level of scrutiny 1.341 from a network maintainer comparable to a change from a 1.342 complete stranger.</para> 1.343 1.344 - <para>To people who come from more orderly project backgrounds, 1.345 + <para id="x_475">To people who come from more orderly project backgrounds, 1.346 the comparatively chaotic Linux kernel development process 1.347 often seems completely insane. It's subject to the whims of 1.348 individuals; people make sweeping changes whenever they deem 1.349 @@ -377,13 +377,13 @@ 1.350 <sect2> 1.351 <title>Pull-only versus shared-push collaboration</title> 1.352 1.353 - <para>A perpetual source of heat in the open source community is 1.354 + <para id="x_476">A perpetual source of heat in the open source community is 1.355 whether a development model in which people only ever pull 1.356 changes from others is <quote>better than</quote> one in which 1.357 multiple people can push changes to a shared 1.358 repository.</para> 1.359 1.360 - <para>Typically, the backers of the shared-push model use tools 1.361 + <para id="x_477">Typically, the backers of the shared-push model use tools 1.362 that actively enforce this approach. If you're using a 1.363 centralised revision control tool such as Subversion, there's 1.364 no way to make a choice over which model you'll use: the tool 1.365 @@ -391,7 +391,7 @@ 1.366 you'll have to roll your own approach on top (such as applying 1.367 a patch by hand).</para> 1.368 1.369 - <para>A good distributed revision control tool, such as 1.370 + <para id="x_478">A good distributed revision control tool, such as 1.371 Mercurial, will support both models. You and your 1.372 collaborators can then structure how you work together based 1.373 on your own needs and preferences, not on what contortions 1.374 @@ -401,7 +401,7 @@ 1.375 <sect2> 1.376 <title>Where collaboration meets branch management</title> 1.377 1.378 - <para>Once you and your team set up some shared repositories and 1.379 + <para id="x_479">Once you and your team set up some shared repositories and 1.380 start propagating changes back and forth between local and 1.381 shared repos, you begin to face a related, but slightly 1.382 different challenge: that of managing the multiple directions 1.383 @@ -415,7 +415,7 @@ 1.384 <sect1> 1.385 <title>The technical side of sharing</title> 1.386 1.387 - <para>The remainder of this chapter is devoted to the question of 1.388 + <para id="x_47a">The remainder of this chapter is devoted to the question of 1.389 serving data to your collaborators.</para> 1.390 1.391 </sect1> 1.392 @@ -423,12 +423,12 @@ 1.393 <title>Informal sharing with <command role="hg-cmd">hg 1.394 serve</command></title> 1.395 1.396 - <para>Mercurial's <command role="hg-cmd">hg serve</command> 1.397 + <para id="x_47b">Mercurial's <command role="hg-cmd">hg serve</command> 1.398 command is wonderfully suited to small, tight-knit, and 1.399 fast-paced group environments. It also provides a great way to 1.400 get a feel for using Mercurial commands over a network.</para> 1.401 1.402 - <para>Run <command role="hg-cmd">hg serve</command> inside a 1.403 + <para id="x_47c">Run <command role="hg-cmd">hg serve</command> inside a 1.404 repository, and in under a second it will bring up a specialised 1.405 HTTP server; this will accept connections from any client, and 1.406 serve up data for that repository until you terminate it. 1.407 @@ -439,24 +439,24 @@ 1.408 on a laptop is likely to look something like 1.409 <literal>http://my-laptop.local:8000/</literal>.</para> 1.410 1.411 - <para>The <command role="hg-cmd">hg serve</command> command is 1.412 + <para id="x_47d">The <command role="hg-cmd">hg serve</command> command is 1.413 <emphasis>not</emphasis> a general-purpose web server. It can do 1.414 only two things:</para> 1.415 <itemizedlist> 1.416 - <listitem><para>Allow people to browse the history of the 1.417 + <listitem><para id="x_47e">Allow people to browse the history of the 1.418 repository it's serving, from their normal web 1.419 browsers.</para> 1.420 </listitem> 1.421 - <listitem><para>Speak Mercurial's wire protocol, so that people 1.422 + <listitem><para id="x_47f">Speak Mercurial's wire protocol, so that people 1.423 can <command role="hg-cmd">hg clone</command> or <command 1.424 role="hg-cmd">hg pull</command> changes from that 1.425 repository.</para> 1.426 </listitem></itemizedlist> 1.427 - <para>In particular, <command role="hg-cmd">hg serve</command> 1.428 + <para id="x_480">In particular, <command role="hg-cmd">hg serve</command> 1.429 won't allow remote users to <emphasis>modify</emphasis> your 1.430 repository. It's intended for read-only use.</para> 1.431 1.432 - <para>If you're getting started with Mercurial, there's nothing to 1.433 + <para id="x_481">If you're getting started with Mercurial, there's nothing to 1.434 prevent you from using <command role="hg-cmd">hg serve</command> 1.435 to serve up a repository on your own computer, then use commands 1.436 like <command role="hg-cmd">hg clone</command>, <command 1.437 @@ -468,13 +468,13 @@ 1.438 <sect2> 1.439 <title>A few things to keep in mind</title> 1.440 1.441 - <para>Because it provides unauthenticated read access to all 1.442 + <para id="x_482">Because it provides unauthenticated read access to all 1.443 clients, you should only use <command role="hg-cmd">hg 1.444 serve</command> in an environment where you either don't 1.445 care, or have complete control over, who can access your 1.446 network and pull data from your repository.</para> 1.447 1.448 - <para>The <command role="hg-cmd">hg serve</command> command 1.449 + <para id="x_483">The <command role="hg-cmd">hg serve</command> command 1.450 knows nothing about any firewall software you might have 1.451 installed on your system or network. It cannot detect or 1.452 control your firewall software. If other people are unable to 1.453 @@ -483,13 +483,13 @@ 1.454 (<emphasis>after</emphasis> you make sure that they're using 1.455 the correct URL) is check your firewall configuration.</para> 1.456 1.457 - <para>By default, <command role="hg-cmd">hg serve</command> 1.458 + <para id="x_484">By default, <command role="hg-cmd">hg serve</command> 1.459 listens for incoming connections on port 8000. If another 1.460 process is already listening on the port you want to use, you 1.461 can specify a different port to listen on using the <option 1.462 role="hg-opt-serve">-p</option> option.</para> 1.463 1.464 - <para>Normally, when <command role="hg-cmd">hg serve</command> 1.465 + <para id="x_485">Normally, when <command role="hg-cmd">hg serve</command> 1.466 starts, it prints no output, which can be a bit unnerving. If 1.467 you'd like to confirm that it is indeed running correctly, and 1.468 find out what URL you should send to your collaborators, start 1.469 @@ -501,56 +501,56 @@ 1.470 <sect1 id="sec:collab:ssh"> 1.471 <title>Using the Secure Shell (ssh) protocol</title> 1.472 1.473 - <para>You can pull and push changes securely over a network 1.474 + <para id="x_486">You can pull and push changes securely over a network 1.475 connection using the Secure Shell (<literal>ssh</literal>) 1.476 protocol. To use this successfully, you may have to do a little 1.477 bit of configuration on the client or server sides.</para> 1.478 1.479 - <para>If you're not familiar with ssh, it's a network protocol 1.480 + <para id="x_487">If you're not familiar with ssh, it's a network protocol 1.481 that lets you securely communicate with another computer. To 1.482 use it with Mercurial, you'll be setting up one or more user 1.483 accounts on a server so that remote users can log in and execute 1.484 commands.</para> 1.485 1.486 - <para>(If you <emphasis>are</emphasis> familiar with ssh, you'll 1.487 + <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll 1.488 probably find some of the material that follows to be elementary 1.489 in nature.)</para> 1.490 1.491 <sect2> 1.492 <title>How to read and write ssh URLs</title> 1.493 1.494 - <para>An ssh URL tends to look like this:</para> 1.495 + <para id="x_489">An ssh URL tends to look like this:</para> 1.496 <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting> 1.497 <orderedlist> 1.498 - <listitem><para>The <quote><literal>ssh://</literal></quote> 1.499 + <listitem><para id="x_48a">The <quote><literal>ssh://</literal></quote> 1.500 part tells Mercurial to use the ssh protocol.</para> 1.501 </listitem> 1.502 - <listitem><para>The <quote><literal>bos@</literal></quote> 1.503 + <listitem><para id="x_48b">The <quote><literal>bos@</literal></quote> 1.504 component indicates what username to log into the server 1.505 as. You can leave this out if the remote username is the 1.506 same as your local username.</para> 1.507 </listitem> 1.508 - <listitem><para>The 1.509 + <listitem><para id="x_48c">The 1.510 <quote><literal>hg.serpentine.com</literal></quote> gives 1.511 the hostname of the server to log into.</para> 1.512 </listitem> 1.513 - <listitem><para>The <quote>:22</quote> identifies the port 1.514 + <listitem><para id="x_48d">The <quote>:22</quote> identifies the port 1.515 number to connect to the server on. The default port is 1.516 22, so you only need to specify a colon and port number if 1.517 you're <emphasis>not</emphasis> using port 22.</para> 1.518 </listitem> 1.519 - <listitem><para>The remainder of the URL is the local path to 1.520 + <listitem><para id="x_48e">The remainder of the URL is the local path to 1.521 the repository on the server.</para> 1.522 </listitem></orderedlist> 1.523 1.524 - <para>There's plenty of scope for confusion with the path 1.525 + <para id="x_48f">There's plenty of scope for confusion with the path 1.526 component of ssh URLs, as there is no standard way for tools 1.527 to interpret it. Some programs behave differently than others 1.528 when dealing with these paths. This isn't an ideal situation, 1.529 but it's unlikely to change. Please read the following 1.530 paragraphs carefully.</para> 1.531 1.532 - <para>Mercurial treats the path to a repository on the server as 1.533 + <para id="x_490">Mercurial treats the path to a repository on the server as 1.534 relative to the remote user's home directory. For example, if 1.535 user <literal>foo</literal> on the server has a home directory 1.536 of <filename class="directory">/home/foo</filename>, then an 1.537 @@ -559,13 +559,13 @@ 1.538 refers to the directory <filename 1.539 class="directory">/home/foo/bar</filename>.</para> 1.540 1.541 - <para>If you want to specify a path relative to another user's 1.542 + <para id="x_491">If you want to specify a path relative to another user's 1.543 home directory, you can use a path that starts with a tilde 1.544 character followed by the user's name (let's call them 1.545 <literal>otheruser</literal>), like this.</para> 1.546 <programlisting>ssh://server/~otheruser/hg/repo</programlisting> 1.547 1.548 - <para>And if you really want to specify an 1.549 + <para id="x_492">And if you really want to specify an 1.550 <emphasis>absolute</emphasis> path on the server, begin the 1.551 path component with two slashes, as in this example.</para> 1.552 <programlisting>ssh://server//absolute/path</programlisting> 1.553 @@ -574,7 +574,7 @@ 1.554 <sect2> 1.555 <title>Finding an ssh client for your system</title> 1.556 1.557 - <para>Almost every Unix-like system comes with OpenSSH 1.558 + <para id="x_493">Almost every Unix-like system comes with OpenSSH 1.559 preinstalled. If you're using such a system, run 1.560 <literal>which ssh</literal> to find out if the 1.561 <command>ssh</command> command is installed (it's usually in 1.562 @@ -582,17 +582,17 @@ 1.563 unlikely event that it isn't present, take a look at your 1.564 system documentation to figure out how to install it.</para> 1.565 1.566 - <para>On Windows, you'll first need to download a suitable ssh 1.567 + <para id="x_494">On Windows, you'll first need to download a suitable ssh 1.568 client. There are two alternatives.</para> 1.569 <itemizedlist> 1.570 - <listitem><para>Simon Tatham's excellent PuTTY package 1.571 + <listitem><para id="x_495">Simon Tatham's excellent PuTTY package 1.572 <citation>web:putty</citation> provides a complete suite 1.573 of ssh client commands.</para> 1.574 </listitem> 1.575 - <listitem><para>If you have a high tolerance for pain, you can 1.576 + <listitem><para id="x_496">If you have a high tolerance for pain, you can 1.577 use the Cygwin port of OpenSSH.</para> 1.578 </listitem></itemizedlist> 1.579 - <para>In either case, you'll need to edit your <filename 1.580 + <para id="x_497">In either case, you'll need to edit your <filename 1.581 role="special">hg.ini</filename> file to 1.582 tell Mercurial where to find the actual client command. For 1.583 example, if you're using PuTTY, you'll need to use the 1.584 @@ -602,7 +602,7 @@ 1.585 ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"</programlisting> 1.586 1.587 <note> 1.588 - <para> The path to <command>plink</command> shouldn't contain 1.589 + <para id="x_498"> The path to <command>plink</command> shouldn't contain 1.590 any whitespace characters, or Mercurial may not be able to 1.591 run it correctly (so putting it in <filename 1.592 class="directory">C:\Program Files</filename> is probably 1.593 @@ -613,7 +613,7 @@ 1.594 <sect2> 1.595 <title>Generating a key pair</title> 1.596 1.597 - <para>To avoid the need to repetitively type a password every 1.598 + <para id="x_499">To avoid the need to repetitively type a password every 1.599 time you need to use your ssh client, I recommend generating a 1.600 key pair. On a Unix-like system, the 1.601 <command>ssh-keygen</command> command will do the trick. On 1.602 @@ -621,13 +621,13 @@ 1.603 <command>puttygen</command> command is what you'll 1.604 need.</para> 1.605 1.606 - <para>When you generate a key pair, it's usually 1.607 + <para id="x_49a">When you generate a key pair, it's usually 1.608 <emphasis>highly</emphasis> advisable to protect it with a 1.609 passphrase. (The only time that you might not want to do this 1.610 is when you're using the ssh protocol for automated tasks on a 1.611 secure network.)</para> 1.612 1.613 - <para>Simply generating a key pair isn't enough, however. 1.614 + <para id="x_49b">Simply generating a key pair isn't enough, however. 1.615 You'll need to add the public key to the set of authorised 1.616 keys for whatever user you're logging in remotely as. For 1.617 servers using OpenSSH (the vast majority), this will mean 1.618 @@ -636,7 +636,7 @@ 1.619 role="special" class="directory">.ssh</filename> 1.620 directory.</para> 1.621 1.622 - <para>On a Unix-like system, your public key will have a 1.623 + <para id="x_49c">On a Unix-like system, your public key will have a 1.624 <filename>.pub</filename> extension. If you're using 1.625 <command>puttygen</command> on Windows, you can save the 1.626 public key to a file of your choosing, or paste it from the 1.627 @@ -647,7 +647,7 @@ 1.628 <sect2> 1.629 <title>Using an authentication agent</title> 1.630 1.631 - <para>An authentication agent is a daemon that stores 1.632 + <para id="x_49d">An authentication agent is a daemon that stores 1.633 passphrases in memory (so it will forget passphrases if you 1.634 log out and log back in again). An ssh client will notice if 1.635 it's running, and query it for a passphrase. If there's no 1.636 @@ -656,14 +656,14 @@ 1.637 every time Mercurial tries to communicate with a server on 1.638 your behalf (e.g. whenever you pull or push changes).</para> 1.639 1.640 - <para>The downside of storing passphrases in an agent is that 1.641 + <para id="x_49e">The downside of storing passphrases in an agent is that 1.642 it's possible for a well-prepared attacker to recover the 1.643 plain text of your passphrases, in some cases even if your 1.644 system has been power-cycled. You should make your own 1.645 judgment as to whether this is an acceptable risk. It 1.646 certainly saves a lot of repeated typing.</para> 1.647 1.648 - <para>On Unix-like systems, the agent is called 1.649 + <para id="x_49f">On Unix-like systems, the agent is called 1.650 <command>ssh-agent</command>, and it's often run automatically 1.651 for you when you log in. You'll need to use the 1.652 <command>ssh-add</command> command to add passphrases to the 1.653 @@ -676,7 +676,7 @@ 1.654 <sect2> 1.655 <title>Configuring the server side properly</title> 1.656 1.657 - <para>Because ssh can be fiddly to set up if you're new to it, 1.658 + <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it, 1.659 there's a variety of things that can go wrong. Add Mercurial 1.660 on top, and there's plenty more scope for head-scratching. 1.661 Most of these potential problems occur on the server side, not 1.662 @@ -684,7 +684,7 @@ 1.663 configuration working, it will usually continue to work 1.664 indefinitely.</para> 1.665 1.666 - <para>Before you try using Mercurial to talk to an ssh server, 1.667 + <para id="x_4a1">Before you try using Mercurial to talk to an ssh server, 1.668 it's best to make sure that you can use the normal 1.669 <command>ssh</command> or <command>putty</command> command to 1.670 talk to the server first. If you run into problems with using 1.671 @@ -695,29 +695,29 @@ 1.672 <emphasis>before</emphasis> you worry about whether there's a 1.673 problem with Mercurial.</para> 1.674 1.675 - <para>The first thing to be sure of on the server side is that 1.676 + <para id="x_4a2">The first thing to be sure of on the server side is that 1.677 you can actually log in from another machine at all. If you 1.678 can't use <command>ssh</command> or <command>putty</command> 1.679 to log in, the error message you get may give you a few hints 1.680 as to what's wrong. The most common problems are as 1.681 follows.</para> 1.682 <itemizedlist> 1.683 - <listitem><para>If you get a <quote>connection refused</quote> 1.684 + <listitem><para id="x_4a3">If you get a <quote>connection refused</quote> 1.685 error, either there isn't an SSH daemon running on the 1.686 server at all, or it's inaccessible due to firewall 1.687 configuration.</para> 1.688 </listitem> 1.689 - <listitem><para>If you get a <quote>no route to host</quote> 1.690 + <listitem><para id="x_4a4">If you get a <quote>no route to host</quote> 1.691 error, you either have an incorrect address for the server 1.692 or a seriously locked down firewall that won't admit its 1.693 existence at all.</para> 1.694 </listitem> 1.695 - <listitem><para>If you get a <quote>permission denied</quote> 1.696 + <listitem><para id="x_4a5">If you get a <quote>permission denied</quote> 1.697 error, you may have mistyped the username on the server, 1.698 or you could have mistyped your key's passphrase or the 1.699 remote user's password.</para> 1.700 </listitem></itemizedlist> 1.701 - <para>In summary, if you're having trouble talking to the 1.702 + <para id="x_4a6">In summary, if you're having trouble talking to the 1.703 server's ssh daemon, first make sure that one is running at 1.704 all. On many systems it will be installed, but disabled, by 1.705 default. Once you're done with this step, you should then 1.706 @@ -727,23 +727,23 @@ 1.707 for misconfiguration until you've checked these two 1.708 first.</para> 1.709 1.710 - <para>If you're using an authentication agent on the client side 1.711 + <para id="x_4a7">If you're using an authentication agent on the client side 1.712 to store passphrases for your keys, you ought to be able to 1.713 log into the server without being prompted for a passphrase or 1.714 a password. If you're prompted for a passphrase, there are a 1.715 few possible culprits.</para> 1.716 <itemizedlist> 1.717 - <listitem><para>You might have forgotten to use 1.718 + <listitem><para id="x_4a8">You might have forgotten to use 1.719 <command>ssh-add</command> or <command>pageant</command> 1.720 to store the passphrase.</para> 1.721 </listitem> 1.722 - <listitem><para>You might have stored the passphrase for the 1.723 + <listitem><para id="x_4a9">You might have stored the passphrase for the 1.724 wrong key.</para> 1.725 </listitem></itemizedlist> 1.726 - <para>If you're being prompted for the remote user's password, 1.727 + <para id="x_4aa">If you're being prompted for the remote user's password, 1.728 there are another few possible problems to check.</para> 1.729 <itemizedlist> 1.730 - <listitem><para>Either the user's home directory or their 1.731 + <listitem><para id="x_4ab">Either the user's home directory or their 1.732 <filename role="special" class="directory">.ssh</filename> 1.733 directory might have excessively liberal permissions. As 1.734 a result, the ssh daemon will not trust or read their 1.735 @@ -752,19 +752,19 @@ 1.736 role="special" class="directory">.ssh</filename> 1.737 directory will often cause this symptom.</para> 1.738 </listitem> 1.739 - <listitem><para>The user's <filename 1.740 + <listitem><para id="x_4ac">The user's <filename 1.741 role="special">authorized_keys</filename> file may have 1.742 a problem. If anyone other than the user owns or can write 1.743 to that file, the ssh daemon will not trust or read 1.744 it.</para> 1.745 </listitem></itemizedlist> 1.746 1.747 - <para>In the ideal world, you should be able to run the 1.748 + <para id="x_4ad">In the ideal world, you should be able to run the 1.749 following command successfully, and it should print exactly 1.750 one line of output, the current date and time.</para> 1.751 <programlisting>ssh myserver date</programlisting> 1.752 1.753 - <para>If, on your server, you have login scripts that print 1.754 + <para id="x_4ae">If, on your server, you have login scripts that print 1.755 banners or other junk even when running non-interactive 1.756 commands like this, you should fix them before you continue, 1.757 so that they only print output if they're run interactively. 1.758 @@ -778,43 +778,43 @@ 1.759 shell is to check the return code from the command 1.760 <literal>tty -s</literal>.)</para> 1.761 1.762 - <para>Once you've verified that plain old ssh is working with 1.763 + <para id="x_4af">Once you've verified that plain old ssh is working with 1.764 your server, the next step is to ensure that Mercurial runs on 1.765 the server. The following command should run 1.766 successfully:</para> 1.767 1.768 <programlisting>ssh myserver hg version</programlisting> 1.769 1.770 - <para>If you see an error message instead of normal <command 1.771 + <para id="x_4b0">If you see an error message instead of normal <command 1.772 role="hg-cmd">hg version</command> output, this is usually 1.773 because you haven't installed Mercurial to <filename 1.774 class="directory">/usr/bin</filename>. Don't worry if this 1.775 is the case; you don't need to do that. But you should check 1.776 for a few possible problems.</para> 1.777 <itemizedlist> 1.778 - <listitem><para>Is Mercurial really installed on the server at 1.779 + <listitem><para id="x_4b1">Is Mercurial really installed on the server at 1.780 all? I know this sounds trivial, but it's worth 1.781 checking!</para> 1.782 </listitem> 1.783 - <listitem><para>Maybe your shell's search path (usually set 1.784 + <listitem><para id="x_4b2">Maybe your shell's search path (usually set 1.785 via the <envar>PATH</envar> environment variable) is 1.786 simply misconfigured.</para> 1.787 </listitem> 1.788 - <listitem><para>Perhaps your <envar>PATH</envar> environment 1.789 + <listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment 1.790 variable is only being set to point to the location of the 1.791 <command>hg</command> executable if the login session is 1.792 interactive. This can happen if you're setting the path 1.793 in the wrong shell login script. See your shell's 1.794 documentation for details.</para> 1.795 </listitem> 1.796 - <listitem><para>The <envar>PYTHONPATH</envar> environment 1.797 + <listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment 1.798 variable may need to contain the path to the Mercurial 1.799 Python modules. It might not be set at all; it could be 1.800 incorrect; or it may be set only if the login is 1.801 interactive.</para> 1.802 </listitem></itemizedlist> 1.803 1.804 - <para>If you can run <command role="hg-cmd">hg version</command> 1.805 + <para id="x_4b5">If you can run <command role="hg-cmd">hg version</command> 1.806 over an ssh connection, well done! You've got the server and 1.807 client sorted out. You should now be able to use Mercurial to 1.808 access repositories hosted by that username on that server. 1.809 @@ -826,19 +826,19 @@ 1.810 <sect2> 1.811 <title>Using compression with ssh</title> 1.812 1.813 - <para>Mercurial does not compress data when it uses the ssh 1.814 + <para id="x_4b6">Mercurial does not compress data when it uses the ssh 1.815 protocol, because the ssh protocol can transparently compress 1.816 data. However, the default behaviour of ssh clients is 1.817 <emphasis>not</emphasis> to request compression.</para> 1.818 1.819 - <para>Over any network other than a fast LAN (even a wireless 1.820 + <para id="x_4b7">Over any network other than a fast LAN (even a wireless 1.821 network), using compression is likely to significantly speed 1.822 up Mercurial's network operations. For example, over a WAN, 1.823 someone measured compression as reducing the amount of time 1.824 required to clone a particularly large repository from 51 1.825 minutes to 17 minutes.</para> 1.826 1.827 - <para>Both <command>ssh</command> and <command>plink</command> 1.828 + <para id="x_4b8">Both <command>ssh</command> and <command>plink</command> 1.829 accept a <option role="cmd-opt-ssh">-C</option> option which 1.830 turns on compression. You can easily edit your <filename 1.831 role="special">~/.hgrc</filename> to enable compression for 1.832 @@ -846,7 +846,7 @@ 1.833 <programlisting>[ui] 1.834 ssh = ssh -C</programlisting> 1.835 1.836 - <para>If you use <command>ssh</command>, you can configure it to 1.837 + <para id="x_4b9">If you use <command>ssh</command>, you can configure it to 1.838 always use compression when talking to your server. To do 1.839 this, edit your <filename 1.840 role="special">.ssh/config</filename> file (which may not 1.841 @@ -854,7 +854,7 @@ 1.842 <programlisting>Host hg 1.843 Compression yes 1.844 HostName hg.example.com</programlisting> 1.845 - <para>This defines an alias, <literal>hg</literal>. When you 1.846 + <para id="x_4ba">This defines an alias, <literal>hg</literal>. When you 1.847 use it on the <command>ssh</command> command line or in a 1.848 Mercurial <literal>ssh</literal>-protocol URL, it will cause 1.849 <command>ssh</command> to connect to 1.850 @@ -867,17 +867,17 @@ 1.851 <sect1 id="sec:collab:cgi"> 1.852 <title>Serving over HTTP using CGI</title> 1.853 1.854 - <para>Depending on how ambitious you are, configuring Mercurial's 1.855 + <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's 1.856 CGI interface can take anything from a few moments to several 1.857 hours.</para> 1.858 1.859 - <para>We'll begin with the simplest of examples, and work our way 1.860 + <para id="x_4bc">We'll begin with the simplest of examples, and work our way 1.861 towards a more complex configuration. Even for the most basic 1.862 case, you're almost certainly going to need to read and modify 1.863 your web server's configuration.</para> 1.864 1.865 <note> 1.866 - <para> Configuring a web server is a complex, fiddly, and 1.867 + <para id="x_4bd"> Configuring a web server is a complex, fiddly, and 1.868 highly system-dependent activity. I can't possibly give you 1.869 instructions that will cover anything like all of the cases 1.870 you will encounter. Please use your discretion and judgment in 1.871 @@ -889,25 +889,25 @@ 1.872 <sect2> 1.873 <title>Web server configuration checklist</title> 1.874 1.875 - <para>Before you continue, do take a few moments to check a few 1.876 + <para id="x_4be">Before you continue, do take a few moments to check a few 1.877 aspects of your system's setup.</para> 1.878 1.879 <orderedlist> 1.880 - <listitem><para>Do you have a web server installed at all? 1.881 + <listitem><para id="x_4bf">Do you have a web server installed at all? 1.882 Mac OS X ships with Apache, but many other systems may not 1.883 have a web server installed.</para> 1.884 </listitem> 1.885 - <listitem><para>If you have a web server installed, is it 1.886 + <listitem><para id="x_4c0">If you have a web server installed, is it 1.887 actually running? On most systems, even if one is 1.888 present, it will be disabled by default.</para> 1.889 </listitem> 1.890 - <listitem><para>Is your server configured to allow you to run 1.891 + <listitem><para id="x_4c1">Is your server configured to allow you to run 1.892 CGI programs in the directory where you plan to do so? 1.893 Most servers default to explicitly disabling the ability 1.894 to run CGI programs.</para> 1.895 </listitem></orderedlist> 1.896 1.897 - <para>If you don't have a web server installed, and don't have 1.898 + <para id="x_4c2">If you don't have a web server installed, and don't have 1.899 substantial experience configuring Apache, you should consider 1.900 using the <literal>lighttpd</literal> web server instead of 1.901 Apache. Apache has a well-deserved reputation for baroque and 1.902 @@ -922,7 +922,7 @@ 1.903 <sect2> 1.904 <title>Basic CGI configuration</title> 1.905 1.906 - <para>On Unix-like systems, it's common for users to have a 1.907 + <para id="x_4c3">On Unix-like systems, it's common for users to have a 1.908 subdirectory named something like <filename 1.909 class="directory">public_html</filename> in their home 1.910 directory, from which they can serve up web pages. A file 1.911 @@ -930,19 +930,19 @@ 1.912 accessible at a URL of the form 1.913 <literal>http://www.example.com/username/foo</literal>.</para> 1.914 1.915 - <para>To get started, find the <filename 1.916 + <para id="x_4c4">To get started, find the <filename 1.917 role="special">hgweb.cgi</filename> script that should be 1.918 present in your Mercurial installation. If you can't quickly 1.919 find a local copy on your system, simply download one from the 1.920 master Mercurial repository at <ulink 1.921 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> 1.922 1.923 - <para>You'll need to copy this script into your <filename 1.924 + <para id="x_4c5">You'll need to copy this script into your <filename 1.925 class="directory">public_html</filename> directory, and 1.926 ensure that it's executable.</para> 1.927 <programlisting>cp .../hgweb.cgi ~/public_html 1.928 chmod 755 ~/public_html/hgweb.cgi</programlisting> 1.929 - <para>The <literal>755</literal> argument to 1.930 + <para id="x_4c6">The <literal>755</literal> argument to 1.931 <command>chmod</command> is a little more general than just 1.932 making the script executable: it ensures that the script is 1.933 executable by anyone, and that <quote>group</quote> and 1.934 @@ -959,7 +959,7 @@ 1.935 <title>What could <emphasis>possibly</emphasis> go 1.936 wrong?</title> 1.937 1.938 - <para>Once you've copied the CGI script into place, go into a 1.939 + <para id="x_4c7">Once you've copied the CGI script into place, go into a 1.940 web browser, and try to open the URL <ulink 1.941 url="http://myhostname/ 1.942 myuser/hgweb.cgi">http://myhostname/ 1.943 @@ -973,7 +973,7 @@ 1.944 fresh installation of Apache, and a user account that I 1.945 created specially to perform this exercise.</para> 1.946 1.947 - <para>Your web server may have per-user directories disabled. 1.948 + <para id="x_4c8">Your web server may have per-user directories disabled. 1.949 If you're using Apache, search your config file for a 1.950 <literal>UserDir</literal> directive. If there's none 1.951 present, per-user directories will be disabled. If one 1.952 @@ -984,7 +984,7 @@ 1.953 directory, for example <filename 1.954 class="directory">public_html</filename>.</para> 1.955 1.956 - <para>Your file access permissions may be too restrictive. 1.957 + <para id="x_4c9">Your file access permissions may be too restrictive. 1.958 The web server must be able to traverse your home directory 1.959 and directories under your <filename 1.960 class="directory">public_html</filename> directory, and 1.961 @@ -994,34 +994,34 @@ 1.962 find ~/public_html -type d -print0 | xargs -0r chmod 755 1.963 find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting> 1.964 1.965 - <para>The other possibility with permissions is that you might 1.966 + <para id="x_4ca">The other possibility with permissions is that you might 1.967 get a completely empty window when you try to load the 1.968 script. In this case, it's likely that your access 1.969 permissions are <emphasis>too permissive</emphasis>. Apache's 1.970 <literal>suexec</literal> subsystem won't execute a script 1.971 that's group- or world-writable, for example.</para> 1.972 1.973 - <para>Your web server may be configured to disallow execution 1.974 + <para id="x_4cb">Your web server may be configured to disallow execution 1.975 of CGI programs in your per-user web directory. Here's 1.976 Apache's default per-user configuration from my Fedora 1.977 system.</para> 1.978 1.979 &ch06-apache-config.lst; 1.980 1.981 - <para>If you find a similar-looking 1.982 + <para id="x_4cc">If you find a similar-looking 1.983 <literal>Directory</literal> group in your Apache 1.984 configuration, the directive to look at inside it is 1.985 <literal>Options</literal>. Add <literal>ExecCGI</literal> 1.986 to the end of this list if it's missing, and restart the web 1.987 server.</para> 1.988 1.989 - <para>If you find that Apache serves you the text of the CGI 1.990 + <para id="x_4cd">If you find that Apache serves you the text of the CGI 1.991 script instead of executing it, you may need to either 1.992 uncomment (if already present) or add a directive like 1.993 this.</para> 1.994 <programlisting>AddHandler cgi-script .cgi</programlisting> 1.995 1.996 - <para>The next possibility is that you might be served with a 1.997 + <para id="x_4ce">The next possibility is that you might be served with a 1.998 colourful Python backtrace claiming that it can't import a 1.999 <literal>mercurial</literal>-related module. This is 1.1000 actually progress! The server is now capable of executing 1.1001 @@ -1035,7 +1035,7 @@ 1.1002 directions inside it to correctly set your 1.1003 <envar>PYTHONPATH</envar> environment variable.</para> 1.1004 1.1005 - <para>Finally, you are <emphasis>certain</emphasis> to by 1.1006 + <para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to by 1.1007 served with another colourful Python backtrace: this one 1.1008 will complain that it can't find <filename 1.1009 class="directory">/path/to/repository</filename>. Edit 1.1010 @@ -1045,7 +1045,7 @@ 1.1011 with the complete path to the repository you want to serve 1.1012 up.</para> 1.1013 1.1014 - <para>At this point, when you try to reload the page, you 1.1015 + <para id="x_4d0">At this point, when you try to reload the page, you 1.1016 should be presented with a nice HTML view of your 1.1017 repository's history. Whew!</para> 1.1018 1.1019 @@ -1053,7 +1053,7 @@ 1.1020 <sect3> 1.1021 <title>Configuring lighttpd</title> 1.1022 1.1023 - <para>To be exhaustive in my experiments, I tried configuring 1.1024 + <para id="x_4d1">To be exhaustive in my experiments, I tried configuring 1.1025 the increasingly popular <literal>lighttpd</literal> web 1.1026 server to serve the same repository as I described with 1.1027 Apache above. I had already overcome all of the problems I 1.1028 @@ -1063,7 +1063,7 @@ 1.1029 role="special">hgweb.cgi</filename> script was properly 1.1030 edited.</para> 1.1031 1.1032 - <para>Once I had Apache running, getting 1.1033 + <para id="x_4d2">Once I had Apache running, getting 1.1034 <literal>lighttpd</literal> to serve the repository was a 1.1035 snap (in other words, even if you're trying to use 1.1036 <literal>lighttpd</literal>, you should read the Apache 1.1037 @@ -1075,7 +1075,7 @@ 1.1038 end of the config file, to configure these modules.</para> 1.1039 <programlisting>userdir.path = "public_html" 1.1040 cgi.assign = (".cgi" => "" )</programlisting> 1.1041 - <para>With this done, <literal>lighttpd</literal> ran 1.1042 + <para id="x_4d3">With this done, <literal>lighttpd</literal> ran 1.1043 immediately for me. If I had configured 1.1044 <literal>lighttpd</literal> before Apache, I'd almost 1.1045 certainly have run into many of the same system-level 1.1046 @@ -1090,7 +1090,7 @@ 1.1047 <sect2> 1.1048 <title>Sharing multiple repositories with one CGI script</title> 1.1049 1.1050 - <para>The <filename role="special">hgweb.cgi</filename> script 1.1051 + <para id="x_4d4">The <filename role="special">hgweb.cgi</filename> script 1.1052 only lets you publish a single repository, which is an 1.1053 annoying restriction. If you want to publish more than one 1.1054 without wracking yourself with multiple copies of the same 1.1055 @@ -1098,7 +1098,7 @@ 1.1056 the <filename role="special">hgwebdir.cgi</filename> 1.1057 script.</para> 1.1058 1.1059 - <para>The procedure to configure <filename 1.1060 + <para id="x_4d5">The procedure to configure <filename 1.1061 role="special">hgwebdir.cgi</filename> is only a little more 1.1062 involved than for <filename 1.1063 role="special">hgweb.cgi</filename>. First, you must obtain 1.1064 @@ -1106,12 +1106,12 @@ 1.1065 download a copy from the master Mercurial repository at <ulink 1.1066 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> 1.1067 1.1068 - <para>You'll need to copy this script into your <filename 1.1069 + <para id="x_4d6">You'll need to copy this script into your <filename 1.1070 class="directory">public_html</filename> directory, and 1.1071 ensure that it's executable.</para> 1.1072 <programlisting>cp .../hgwebdir.cgi ~/public_html 1.1073 chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting> 1.1074 - <para>With basic configuration out of the way, try to visit 1.1075 + <para id="x_4d7">With basic configuration out of the way, try to visit 1.1076 <ulink url="http://myhostname/ 1.1077 myuser/hgwebdir.cgi">http://myhostname/ 1.1078 myuser/hgwebdir.cgi</ulink> in your browser. It should 1.1079 @@ -1120,7 +1120,7 @@ 1.1080 potential problems in section <xref 1.1081 linkend="sec:collab:wtf"/>.</para> 1.1082 1.1083 - <para>The <filename role="special">hgwebdir.cgi</filename> 1.1084 + <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename> 1.1085 script relies on an external configuration file. By default, 1.1086 it searches for a file named <filename 1.1087 role="special">hgweb.config</filename> in the same directory 1.1088 @@ -1130,7 +1130,7 @@ 1.1089 <literal>ConfigParser</literal> 1.1090 <citation>web:configparser</citation> module.</para> 1.1091 1.1092 - <para>The easiest way to configure <filename 1.1093 + <para id="x_4d9">The easiest way to configure <filename 1.1094 role="special">hgwebdir.cgi</filename> is with a section 1.1095 named <literal>collections</literal>. This will automatically 1.1096 publish <emphasis>every</emphasis> repository under the 1.1097 @@ -1138,7 +1138,7 @@ 1.1098 this:</para> 1.1099 <programlisting>[collections] 1.1100 /my/root = /my/root</programlisting> 1.1101 - <para>Mercurial interprets this by looking at the directory name 1.1102 + <para id="x_4da">Mercurial interprets this by looking at the directory name 1.1103 on the <emphasis>right</emphasis> hand side of the 1.1104 <quote><literal>=</literal></quote> sign; finding repositories 1.1105 in that directory hierarchy; and using the text on the 1.1106 @@ -1147,7 +1147,7 @@ 1.1107 remaining component of a path after this stripping has 1.1108 occurred is called a <quote>virtual path</quote>.</para> 1.1109 1.1110 - <para>Given the example above, if we have a repository whose 1.1111 + <para id="x_4db">Given the example above, if we have a repository whose 1.1112 local path is <filename 1.1113 class="directory">/my/root/this/repo</filename>, the CGI 1.1114 script will strip the leading <filename 1.1115 @@ -1161,7 +1161,7 @@ 1.1116 myuser/hgwebdir.cgi/this/repo">http://myhostname/ 1.1117 myuser/hgwebdir.cgi/this/repo</ulink>.</para> 1.1118 1.1119 - <para>If we replace <filename 1.1120 + <para id="x_4dc">If we replace <filename 1.1121 class="directory">/my/root</filename> on the left hand side 1.1122 of this example with <filename 1.1123 class="directory">/my</filename>, then <filename 1.1124 @@ -1171,13 +1171,13 @@ 1.1125 class="directory">root/this/repo</filename> instead of 1.1126 <filename class="directory">this/repo</filename>.</para> 1.1127 1.1128 - <para>The <filename role="special">hgwebdir.cgi</filename> 1.1129 + <para id="x_4dd">The <filename role="special">hgwebdir.cgi</filename> 1.1130 script will recursively search each directory listed in the 1.1131 <literal>collections</literal> section of its configuration 1.1132 file, but it will <literal>not</literal> recurse into the 1.1133 repositories it finds.</para> 1.1134 1.1135 - <para>The <literal>collections</literal> mechanism makes it easy 1.1136 + <para id="x_4de">The <literal>collections</literal> mechanism makes it easy 1.1137 to publish many repositories in a <quote>fire and 1.1138 forget</quote> manner. You only need to set up the CGI 1.1139 script and configuration file one time. Afterwards, you can 1.1140 @@ -1190,7 +1190,7 @@ 1.1141 <title>Explicitly specifying which repositories to 1.1142 publish</title> 1.1143 1.1144 - <para>In addition to the <literal>collections</literal> 1.1145 + <para id="x_4df">In addition to the <literal>collections</literal> 1.1146 mechanism, the <filename 1.1147 role="special">hgwebdir.cgi</filename> script allows you 1.1148 to publish a specific list of repositories. To do so, 1.1149 @@ -1199,20 +1199,20 @@ 1.1150 <programlisting>[paths] 1.1151 repo1 = /my/path/to/some/repo 1.1152 repo2 = /some/path/to/another</programlisting> 1.1153 - <para>In this case, the virtual path (the component that will 1.1154 + <para id="x_4e0">In this case, the virtual path (the component that will 1.1155 appear in a URL) is on the left hand side of each 1.1156 definition, while the path to the repository is on the 1.1157 right. Notice that there does not need to be any 1.1158 relationship between the virtual path you choose and the 1.1159 location of a repository in your filesystem.</para> 1.1160 1.1161 - <para>If you wish, you can use both the 1.1162 + <para id="x_4e1">If you wish, you can use both the 1.1163 <literal>collections</literal> and <literal>paths</literal> 1.1164 mechanisms simultaneously in a single configuration 1.1165 file.</para> 1.1166 1.1167 <note> 1.1168 - <para> If multiple repositories have the same virtual path, 1.1169 + <para id="x_4e2"> If multiple repositories have the same virtual path, 1.1170 <filename role="special">hgwebdir.cgi</filename> will not 1.1171 report an error. Instead, it will behave 1.1172 unpredictably.</para> 1.1173 @@ -1223,12 +1223,12 @@ 1.1174 <sect2> 1.1175 <title>Downloading source archives</title> 1.1176 1.1177 - <para>Mercurial's web interface lets users download an archive 1.1178 + <para id="x_4e3">Mercurial's web interface lets users download an archive 1.1179 of any revision. This archive will contain a snapshot of the 1.1180 working directory as of that revision, but it will not contain 1.1181 a copy of the repository data.</para> 1.1182 1.1183 - <para>By default, this feature is not enabled. To enable it, 1.1184 + <para id="x_4e4">By default, this feature is not enabled. To enable it, 1.1185 you'll need to add an <envar 1.1186 role="rc-item-web">allow_archive</envar> item to the 1.1187 <literal role="rc-web">web</literal> section of your <filename 1.1188 @@ -1238,7 +1238,7 @@ 1.1189 <sect2> 1.1190 <title>Web configuration options</title> 1.1191 1.1192 - <para>Mercurial's web interfaces (the <command role="hg-cmd">hg 1.1193 + <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd">hg 1.1194 serve</command> command, and the <filename 1.1195 role="special">hgweb.cgi</filename> and <filename 1.1196 role="special">hgwebdir.cgi</filename> scripts) have a 1.1197 @@ -1246,7 +1246,7 @@ 1.1198 belong in a section named <literal 1.1199 role="rc-web">web</literal>.</para> 1.1200 <itemizedlist> 1.1201 - <listitem><para><envar 1.1202 + <listitem><para id="x_4e6"><envar 1.1203 role="rc-item-web">allow_archive</envar>: Determines 1.1204 which (if any) archive download mechanisms Mercurial 1.1205 supports. If you enable this feature, users of the web 1.1206 @@ -1255,30 +1255,30 @@ 1.1207 archive feature, this item must take the form of a 1.1208 sequence of words drawn from the list below.</para> 1.1209 <itemizedlist> 1.1210 - <listitem><para><literal>bz2</literal>: A 1.1211 + <listitem><para id="x_4e7"><literal>bz2</literal>: A 1.1212 <command>tar</command> archive, compressed using 1.1213 <literal>bzip2</literal> compression. This has the 1.1214 best compression ratio, but uses the most CPU time on 1.1215 the server.</para> 1.1216 </listitem> 1.1217 - <listitem><para><literal>gz</literal>: A 1.1218 + <listitem><para id="x_4e8"><literal>gz</literal>: A 1.1219 <command>tar</command> archive, compressed using 1.1220 <literal>gzip</literal> compression.</para> 1.1221 </listitem> 1.1222 - <listitem><para><literal>zip</literal>: A 1.1223 + <listitem><para id="x_4e9"><literal>zip</literal>: A 1.1224 <command>zip</command> archive, compressed using LZW 1.1225 compression. This format has the worst compression 1.1226 ratio, but is widely used in the Windows world.</para> 1.1227 </listitem> 1.1228 </itemizedlist> 1.1229 - <para> If you provide an empty list, or don't have an 1.1230 + <para id="x_4ea"> If you provide an empty list, or don't have an 1.1231 <envar role="rc-item-web">allow_archive</envar> entry at 1.1232 all, this feature will be disabled. Here is an example of 1.1233 how to enable all three supported formats.</para> 1.1234 <programlisting>[web] 1.1235 allow_archive = bz2 gz zip</programlisting> 1.1236 </listitem> 1.1237 - <listitem><para><envar role="rc-item-web">allowpull</envar>: 1.1238 + <listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>: 1.1239 Boolean. Determines whether the web interface allows 1.1240 remote users to <command role="hg-cmd">hg pull</command> 1.1241 and <command role="hg-cmd">hg clone</command> this 1.1242 @@ -1287,7 +1287,7 @@ 1.1243 <quote>human-oriented</quote> portion of the web interface 1.1244 is available.</para> 1.1245 </listitem> 1.1246 - <listitem><para><envar role="rc-item-web">contact</envar>: 1.1247 + <listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>: 1.1248 String. A free-form (but preferably brief) string 1.1249 identifying the person or group in charge of the 1.1250 repository. This often contains the name and email 1.1251 @@ -1298,21 +1298,21 @@ 1.1252 role="special">~/.hgrc</filename> if every repository 1.1253 has a single maintainer.</para> 1.1254 </listitem> 1.1255 - <listitem><para><envar role="rc-item-web">maxchanges</envar>: 1.1256 + <listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>: 1.1257 Integer. The default maximum number of changesets to 1.1258 display in a single page of output.</para> 1.1259 </listitem> 1.1260 - <listitem><para><envar role="rc-item-web">maxfiles</envar>: 1.1261 + <listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>: 1.1262 Integer. The default maximum number of modified files to 1.1263 display in a single page of output.</para> 1.1264 </listitem> 1.1265 - <listitem><para><envar role="rc-item-web">stripes</envar>: 1.1266 + <listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>: 1.1267 Integer. If the web interface displays alternating 1.1268 <quote>stripes</quote> to make it easier to visually align 1.1269 rows when you are looking at a table, this number controls 1.1270 the number of rows in each stripe.</para> 1.1271 </listitem> 1.1272 - <listitem><para><envar role="rc-item-web">style</envar>: 1.1273 + <listitem><para id="x_4f0"><envar role="rc-item-web">style</envar>: 1.1274 Controls the template Mercurial uses to display the web 1.1275 interface. Mercurial ships with two web templates, named 1.1276 <literal>default</literal> and <literal>gitweb</literal> 1.1277 @@ -1324,12 +1324,12 @@ 1.1278 <programlisting>[web] 1.1279 style = gitweb</programlisting> 1.1280 </listitem> 1.1281 - <listitem><para><envar role="rc-item-web">templates</envar>: 1.1282 + <listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>: 1.1283 Path. The directory in which to search for template 1.1284 files. By default, Mercurial searches in the directory in 1.1285 which it was installed.</para> 1.1286 </listitem></itemizedlist> 1.1287 - <para>If you are using <filename 1.1288 + <para id="x_4f2">If you are using <filename 1.1289 role="special">hgwebdir.cgi</filename>, you can place a few 1.1290 configuration items in a <literal role="rc-web">web</literal> 1.1291 section of the <filename 1.1292 @@ -1342,17 +1342,17 @@ 1.1293 <sect3> 1.1294 <title>Options specific to an individual repository</title> 1.1295 1.1296 - <para>A few <literal role="rc-web">web</literal> configuration 1.1297 + <para id="x_4f3">A few <literal role="rc-web">web</literal> configuration 1.1298 items ought to be placed in a repository's local <filename 1.1299 role="special">.hg/hgrc</filename>, rather than a user's 1.1300 or global <filename role="special">~/.hgrc</filename>.</para> 1.1301 <itemizedlist> 1.1302 - <listitem><para><envar 1.1303 + <listitem><para id="x_4f4"><envar 1.1304 role="rc-item-web">description</envar>: String. A 1.1305 free-form (but preferably brief) string that describes 1.1306 the contents or purpose of the repository.</para> 1.1307 </listitem> 1.1308 - <listitem><para><envar role="rc-item-web">name</envar>: 1.1309 + <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>: 1.1310 String. The name to use for the repository in the web 1.1311 interface. This overrides the default name, which is 1.1312 the last component of the repository's path.</para> 1.1313 @@ -1363,13 +1363,13 @@ 1.1314 <title>Options specific to the <command role="hg-cmd">hg 1.1315 serve</command> command</title> 1.1316 1.1317 - <para>Some of the items in the <literal 1.1318 + <para id="x_4f6">Some of the items in the <literal 1.1319 role="rc-web">web</literal> section of a <filename 1.1320 role="special">~/.hgrc</filename> file are only for use 1.1321 with the <command role="hg-cmd">hg serve</command> 1.1322 command.</para> 1.1323 <itemizedlist> 1.1324 - <listitem><para><envar role="rc-item-web">accesslog</envar>: 1.1325 + <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>: 1.1326 Path. The name of a file into which to write an access 1.1327 log. By default, the <command role="hg-cmd">hg 1.1328 serve</command> command writes this information to 1.1329 @@ -1377,22 +1377,22 @@ 1.1330 in the standard <quote>combined</quote> file format used 1.1331 by almost all web servers.</para> 1.1332 </listitem> 1.1333 - <listitem><para><envar role="rc-item-web">address</envar>: 1.1334 + <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>: 1.1335 String. The local address on which the server should 1.1336 listen for incoming connections. By default, the server 1.1337 listens on all addresses.</para> 1.1338 </listitem> 1.1339 - <listitem><para><envar role="rc-item-web">errorlog</envar>: 1.1340 + <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>: 1.1341 Path. The name of a file into which to write an error 1.1342 log. By default, the <command role="hg-cmd">hg 1.1343 serve</command> command writes this information to 1.1344 standard error, not to a file.</para> 1.1345 </listitem> 1.1346 - <listitem><para><envar role="rc-item-web">ipv6</envar>: 1.1347 + <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>: 1.1348 Boolean. Whether to use the IPv6 protocol. By default, 1.1349 IPv6 is not used.</para> 1.1350 </listitem> 1.1351 - <listitem><para><envar role="rc-item-web">port</envar>: 1.1352 + <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>: 1.1353 Integer. The TCP port number on which the server should 1.1354 listen. The default port number used is 8000.</para> 1.1355 </listitem></itemizedlist> 1.1356 @@ -1403,14 +1403,14 @@ 1.1357 role="special">~/.hgrc</filename> file to add <literal 1.1358 role="rc-web">web</literal> items to</title> 1.1359 1.1360 - <para>It is important to remember that a web server like 1.1361 + <para id="x_4fc">It is important to remember that a web server like 1.1362 Apache or <literal>lighttpd</literal> will run under a user 1.1363 ID that is different to yours. CGI scripts run by your 1.1364 server, such as <filename 1.1365 role="special">hgweb.cgi</filename>, will usually also run 1.1366 under that user ID.</para> 1.1367 1.1368 - <para>If you add <literal role="rc-web">web</literal> items to 1.1369 + <para id="x_4fd">If you add <literal role="rc-web">web</literal> items to 1.1370 your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that 1.1371 <filename role="special">~/.hgrc</filename> file. Those 1.1372 settings will thus only affect the behaviour of the <command