hgbook

annotate en/ch05-collab.xml @ 711:364d2ce9e055

find changesets by author, revision, files, or words in the commit message
Update Chinese translation

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