1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/fr/collab.tex	Sun Feb 22 16:15:40 2009 +0100
     1.3 @@ -0,0 +1,1118 @@
     1.4 +\chapter{Collaborating with other people}
     1.5 +\label{cha:collab}
     1.6 +
     1.7 +As a completely decentralised tool, Mercurial doesn't impose any
     1.8 +policy on how people ought to work with each other.  However, if
     1.9 +you're new to distributed revision control, it helps to have some
    1.10 +tools and examples in mind when you're thinking about possible
    1.11 +workflow models.
    1.12 +
    1.13 +\section{Mercurial's web interface}
    1.14 +
    1.15 +Mercurial has a powerful web interface that provides several 
    1.16 +useful capabilities.
    1.17 +
    1.18 +For interactive use, the web interface lets you browse a single
    1.19 +repository or a collection of repositories.  You can view the history
    1.20 +of a repository, examine each change (comments and diffs), and view
    1.21 +the contents of each directory and file.
    1.22 +
    1.23 +Also for human consumption, the web interface provides an RSS feed of
    1.24 +the changes in a repository.  This lets you ``subscribe'' to a
    1.25 +repository using your favourite feed reader, and be automatically
    1.26 +notified of activity in that repository as soon as it happens.  I find
    1.27 +this capability much more convenient than the model of subscribing to
    1.28 +a mailing list to which notifications are sent, as it requires no
    1.29 +additional configuration on the part of whoever is serving the
    1.30 +repository.
    1.31 +
    1.32 +The web interface also lets remote users clone a repository, pull
    1.33 +changes from it, and (when the server is configured to permit it) push
    1.34 +changes back to it.  Mercurial's HTTP tunneling protocol aggressively
    1.35 +compresses data, so that it works efficiently even over low-bandwidth
    1.36 +network connections.
    1.37 +
    1.38 +The easiest way to get started with the web interface is to use your
    1.39 +web browser to visit an existing repository, such as the master
    1.40 +Mercurial repository at
    1.41 +\url{http://www.selenic.com/repo/hg?style=gitweb}.
    1.42 +
    1.43 +If you're interested in providing a web interface to your own
    1.44 +repositories, Mercurial provides two ways to do this.  The first is
    1.45 +using the \hgcmd{serve} command, which is best suited to short-term
    1.46 +``lightweight'' serving.  See section~\ref{sec:collab:serve} below for
    1.47 +details of how to use this command.  If you have a long-lived
    1.48 +repository that you'd like to make permanently available, Mercurial
    1.49 +has built-in support for the CGI (Common Gateway Interface) standard,
    1.50 +which all common web servers support.  See
    1.51 +section~\ref{sec:collab:cgi} for details of CGI configuration.
    1.52 +
    1.53 +\section{Collaboration models}
    1.54 +
    1.55 +With a suitably flexible tool, making decisions about workflow is much
    1.56 +more of a social engineering challenge than a technical one.
    1.57 +Mercurial imposes few limitations on how you can structure the flow of
    1.58 +work in a project, so it's up to you and your group to set up and live
    1.59 +with a model that matches your own particular needs.
    1.60 +
    1.61 +\subsection{Factors to keep in mind}
    1.62 +
    1.63 +The most important aspect of any model that you must keep in mind is
    1.64 +how well it matches the needs and capabilities of the people who will
    1.65 +be using it.  This might seem self-evident; even so, you still can't
    1.66 +afford to forget it for a moment.
    1.67 +
    1.68 +I once put together a workflow model that seemed to make perfect sense
    1.69 +to me, but that caused a considerable amount of consternation and
    1.70 +strife within my development team.  In spite of my attempts to explain
    1.71 +why we needed a complex set of branches, and how changes ought to flow
    1.72 +between them, a few team members revolted.  Even though they were
    1.73 +smart people, they didn't want to pay attention to the constraints we
    1.74 +were operating under, or face the consequences of those constraints in
    1.75 +the details of the model that I was advocating.
    1.76 +
    1.77 +Don't sweep foreseeable social or technical problems under the rug.
    1.78 +Whatever scheme you put into effect, you should plan for mistakes and
    1.79 +problem scenarios.  Consider adding automated machinery to prevent, or
    1.80 +quickly recover from, trouble that you can anticipate.  As an example,
    1.81 +if you intend to have a branch with not-for-release changes in it,
    1.82 +you'd do well to think early about the possibility that someone might
    1.83 +accidentally merge those changes into a release branch.  You could
    1.84 +avoid this particular problem by writing a hook that prevents changes
    1.85 +from being merged from an inappropriate branch.
    1.86 +
    1.87 +\subsection{Informal anarchy}
    1.88 +
    1.89 +I wouldn't suggest an ``anything goes'' approach as something
    1.90 +sustainable, but it's a model that's easy to grasp, and it works
    1.91 +perfectly well in a few unusual situations.
    1.92 +
    1.93 +As one example, many projects have a loose-knit group of collaborators
    1.94 +who rarely physically meet each other.  Some groups like to overcome
    1.95 +the isolation of working at a distance by organising occasional
    1.96 +``sprints''.  In a sprint, a number of people get together in a single
    1.97 +location (a company's conference room, a hotel meeting room, that kind
    1.98 +of place) and spend several days more or less locked in there, hacking
    1.99 +intensely on a handful of projects.
   1.100 +
   1.101 +A sprint is the perfect place to use the \hgcmd{serve} command, since
   1.102 +\hgcmd{serve} does not requires any fancy server infrastructure.  You
   1.103 +can get started with \hgcmd{serve} in moments, by reading
   1.104 +section~\ref{sec:collab:serve} below.  Then simply tell the person
   1.105 +next to you that you're running a server, send the URL to them in an
   1.106 +instant message, and you immediately have a quick-turnaround way to
   1.107 +work together.  They can type your URL into their web browser and
   1.108 +quickly review your changes; or they can pull a bugfix from you and
   1.109 +verify it; or they can clone a branch containing a new feature and try
   1.110 +it out.
   1.111 +
   1.112 +The charm, and the problem, with doing things in an ad hoc fashion
   1.113 +like this is that only people who know about your changes, and where
   1.114 +they are, can see them.  Such an informal approach simply doesn't
   1.115 +scale beyond a handful people, because each individual needs to know
   1.116 +about $n$ different repositories to pull from.
   1.117 +
   1.118 +\subsection{A single central repository}
   1.119 +
   1.120 +For smaller projects migrating from a centralised revision control
   1.121 +tool, perhaps the easiest way to get started is to have changes flow
   1.122 +through a single shared central repository.  This is also the
   1.123 +most common ``building block'' for more ambitious workflow schemes.
   1.124 +
   1.125 +Contributors start by cloning a copy of this repository.  They can
   1.126 +pull changes from it whenever they need to, and some (perhaps all)
   1.127 +developers have permission to push a change back when they're ready
   1.128 +for other people to see it.
   1.129 +
   1.130 +Under this model, it can still often make sense for people to pull
   1.131 +changes directly from each other, without going through the central
   1.132 +repository.  Consider a case in which I have a tentative bug fix, but
   1.133 +I am worried that if I were to publish it to the central repository,
   1.134 +it might subsequently break everyone else's trees as they pull it.  To
   1.135 +reduce the potential for damage, I can ask you to clone my repository
   1.136 +into a temporary repository of your own and test it.  This lets us put
   1.137 +off publishing the potentially unsafe change until it has had a little
   1.138 +testing.
   1.139 +
   1.140 +In this kind of scenario, people usually use the \command{ssh}
   1.141 +protocol to securely push changes to the central repository, as
   1.142 +documented in section~\ref{sec:collab:ssh}.  It's also usual to
   1.143 +publish a read-only copy of the repository over HTTP using CGI, as in
   1.144 +section~\ref{sec:collab:cgi}.  Publishing over HTTP satisfies the
   1.145 +needs of people who don't have push access, and those who want to use
   1.146 +web browsers to browse the repository's history.
   1.147 +
   1.148 +\subsection{Working with multiple branches}
   1.149 +
   1.150 +Projects of any significant size naturally tend to make progress on
   1.151 +several fronts simultaneously.  In the case of software, it's common
   1.152 +for a project to go through periodic official releases.  A release
   1.153 +might then go into ``maintenance mode'' for a while after its first
   1.154 +publication; maintenance releases tend to contain only bug fixes, not
   1.155 +new features.  In parallel with these maintenance releases, one or
   1.156 +more future releases may be under development.  People normally use
   1.157 +the word ``branch'' to refer to one of these many slightly different
   1.158 +directions in which development is proceeding.
   1.159 +
   1.160 +Mercurial is particularly well suited to managing a number of
   1.161 +simultaneous, but not identical, branches.  Each ``development
   1.162 +direction'' can live in its own central repository, and you can merge
   1.163 +changes from one to another as the need arises.  Because repositories
   1.164 +are independent of each other, unstable changes in a development
   1.165 +branch will never affect a stable branch unless someone explicitly
   1.166 +merges those changes in.
   1.167 +
   1.168 +Here's an example of how this can work in practice.  Let's say you
   1.169 +have one ``main branch'' on a central server.
   1.170 +\interaction{branching.init}
   1.171 +People clone it, make changes locally, test them, and push them back.
   1.172 +
   1.173 +Once the main branch reaches a release milestone, you can use the
   1.174 +\hgcmd{tag} command to give a permanent name to the milestone
   1.175 +revision.
   1.176 +\interaction{branching.tag}
   1.177 +Let's say some ongoing development occurs on the main branch.
   1.178 +\interaction{branching.main}
   1.179 +Using the tag that was recorded at the milestone, people who clone
   1.180 +that repository at any time in the future can use \hgcmd{update} to
   1.181 +get a copy of the working directory exactly as it was when that tagged
   1.182 +revision was committed.  
   1.183 +\interaction{branching.update}
   1.184 +
   1.185 +In addition, immediately after the main branch is tagged, someone can
   1.186 +then clone the main branch on the server to a new ``stable'' branch,
   1.187 +also on the server.
   1.188 +\interaction{branching.clone}
   1.189 +
   1.190 +Someone who needs to make a change to the stable branch can then clone
   1.191 +\emph{that} repository, make their changes, commit, and push their
   1.192 +changes back there.
   1.193 +\interaction{branching.stable}
   1.194 +Because Mercurial repositories are independent, and Mercurial doesn't
   1.195 +move changes around automatically, the stable and main branches are
   1.196 +\emph{isolated} from each other.  The changes that you made on the
   1.197 +main branch don't ``leak'' to the stable branch, and vice versa.
   1.198 +
   1.199 +You'll often want all of your bugfixes on the stable branch to show up
   1.200 +on the main branch, too.  Rather than rewrite a bugfix on the main
   1.201 +branch, you can simply pull and merge changes from the stable to the
   1.202 +main branch, and Mercurial will bring those bugfixes in for you.
   1.203 +\interaction{branching.merge}
   1.204 +The main branch will still contain changes that are not on the stable
   1.205 +branch, but it will also contain all of the bugfixes from the stable
   1.206 +branch.  The stable branch remains unaffected by these changes.
   1.207 +
   1.208 +\subsection{Feature branches}
   1.209 +
   1.210 +For larger projects, an effective way to manage change is to break up
   1.211 +a team into smaller groups.  Each group has a shared branch of its
   1.212 +own, cloned from a single ``master'' branch used by the entire
   1.213 +project.  People working on an individual branch are typically quite
   1.214 +isolated from developments on other branches.
   1.215 +
   1.216 +\begin{figure}[ht]
   1.217 +  \centering
   1.218 +  \grafix{feature-branches}
   1.219 +  \caption{Feature branches}
   1.220 +  \label{fig:collab:feature-branches}
   1.221 +\end{figure}
   1.222 +
   1.223 +When a particular feature is deemed to be in suitable shape, someone
   1.224 +on that feature team pulls and merges from the master branch into the
   1.225 +feature branch, then pushes back up to the master branch.
   1.226 +
   1.227 +\subsection{The release train}
   1.228 +
   1.229 +Some projects are organised on a ``train'' basis: a release is
   1.230 +scheduled to happen every few months, and whatever features are ready
   1.231 +when the ``train'' is ready to leave are allowed in.
   1.232 +
   1.233 +This model resembles working with feature branches.  The difference is
   1.234 +that when a feature branch misses a train, someone on the feature team
   1.235 +pulls and merges the changes that went out on that train release into
   1.236 +the feature branch, and the team continues its work on top of that
   1.237 +release so that their feature can make the next release.
   1.238 +
   1.239 +\subsection{The Linux kernel model}
   1.240 +
   1.241 +The development of the Linux kernel has a shallow hierarchical
   1.242 +structure, surrounded by a cloud of apparent chaos.  Because most
   1.243 +Linux developers use \command{git}, a distributed revision control
   1.244 +tool with capabilities similar to Mercurial, it's useful to describe
   1.245 +the way work flows in that environment; if you like the ideas, the
   1.246 +approach translates well across tools.
   1.247 +
   1.248 +At the center of the community sits Linus Torvalds, the creator of
   1.249 +Linux.  He publishes a single source repository that is considered the
   1.250 +``authoritative'' current tree by the entire developer community.
   1.251 +Anyone can clone Linus's tree, but he is very choosy about whose trees
   1.252 +he pulls from.
   1.253 +
   1.254 +Linus has a number of ``trusted lieutenants''.  As a general rule, he
   1.255 +pulls whatever changes they publish, in most cases without even
   1.256 +reviewing those changes.  Some of those lieutenants are generally
   1.257 +agreed to be ``maintainers'', responsible for specific subsystems
   1.258 +within the kernel.  If a random kernel hacker wants to make a change
   1.259 +to a subsystem that they want to end up in Linus's tree, they must
   1.260 +find out who the subsystem's maintainer is, and ask that maintainer to
   1.261 +take their change.  If the maintainer reviews their changes and agrees
   1.262 +to take them, they'll pass them along to Linus in due course.
   1.263 +
   1.264 +Individual lieutenants have their own approaches to reviewing,
   1.265 +accepting, and publishing changes; and for deciding when to feed them
   1.266 +to Linus.  In addition, there are several well known branches that
   1.267 +people use for different purposes.  For example, a few people maintain
   1.268 +``stable'' repositories of older versions of the kernel, to which they
   1.269 +apply critical fixes as needed.  Some maintainers publish multiple
   1.270 +trees: one for experimental changes; one for changes that they are
   1.271 +about to feed upstream; and so on.  Others just publish a single
   1.272 +tree.
   1.273 +
   1.274 +This model has two notable features.  The first is that it's ``pull
   1.275 +only''.  You have to ask, convince, or beg another developer to take a
   1.276 +change from you, because there are almost no trees to which more than
   1.277 +one person can push, and there's no way to push changes into a tree
   1.278 +that someone else controls.
   1.279 +
   1.280 +The second is that it's based on reputation and acclaim.  If you're an
   1.281 +unknown, Linus will probably ignore changes from you without even
   1.282 +responding.  But a subsystem maintainer will probably review them, and
   1.283 +will likely take them if they pass their criteria for suitability.
   1.284 +The more ``good'' changes you contribute to a maintainer, the more
   1.285 +likely they are to trust your judgment and accept your changes.  If
   1.286 +you're well-known and maintain a long-lived branch for something Linus
   1.287 +hasn't yet accepted, people with similar interests may pull your
   1.288 +changes regularly to keep up with your work.
   1.289 +
   1.290 +Reputation and acclaim don't necessarily cross subsystem or ``people''
   1.291 +boundaries.  If you're a respected but specialised storage hacker, and
   1.292 +you try to fix a networking bug, that change will receive a level of
   1.293 +scrutiny from a network maintainer comparable to a change from a
   1.294 +complete stranger.
   1.295 +
   1.296 +To people who come from more orderly project backgrounds, the
   1.297 +comparatively chaotic Linux kernel development process often seems
   1.298 +completely insane.  It's subject to the whims of individuals; people
   1.299 +make sweeping changes whenever they deem it appropriate; and the pace
   1.300 +of development is astounding.  And yet Linux is a highly successful,
   1.301 +well-regarded piece of software.
   1.302 +
   1.303 +\subsection{Pull-only versus shared-push collaboration}
   1.304 +
   1.305 +A perpetual source of heat in the open source community is whether a
   1.306 +development model in which people only ever pull changes from others
   1.307 +is ``better than'' one in which multiple people can push changes to a
   1.308 +shared repository.
   1.309 +
   1.310 +Typically, the backers of the shared-push model use tools that
   1.311 +actively enforce this approach.  If you're using a centralised
   1.312 +revision control tool such as Subversion, there's no way to make a
   1.313 +choice over which model you'll use: the tool gives you shared-push,
   1.314 +and if you want to do anything else, you'll have to roll your own
   1.315 +approach on top (such as applying a patch by hand).
   1.316 +
   1.317 +A good distributed revision control tool, such as Mercurial, will
   1.318 +support both models.  You and your collaborators can then structure
   1.319 +how you work together based on your own needs and preferences, not on
   1.320 +what contortions your tools force you into.
   1.321 +
   1.322 +\subsection{Where collaboration meets branch management}
   1.323 +
   1.324 +Once you and your team set up some shared repositories and start
   1.325 +propagating changes back and forth between local and shared repos, you
   1.326 +begin to face a related, but slightly different challenge: that of
   1.327 +managing the multiple directions in which your team may be moving at
   1.328 +once.  Even though this subject is intimately related to how your team
   1.329 +collaborates, it's dense enough to merit treatment of its own, in
   1.330 +chapter~\ref{chap:branch}.
   1.331 +
   1.332 +\section{The technical side of sharing}
   1.333 +
   1.334 +The remainder of this chapter is devoted to the question of serving
   1.335 +data to your collaborators.
   1.336 +
   1.337 +\section{Informal sharing with \hgcmd{serve}}
   1.338 +\label{sec:collab:serve}
   1.339 +
   1.340 +Mercurial's \hgcmd{serve} command is wonderfully suited to small,
   1.341 +tight-knit, and fast-paced group environments.  It also provides a
   1.342 +great way to get a feel for using Mercurial commands over a network.
   1.343 +
   1.344 +Run \hgcmd{serve} inside a repository, and in under a second it will
   1.345 +bring up a specialised HTTP server; this will accept connections from
   1.346 +any client, and serve up data for that repository until you terminate
   1.347 +it.  Anyone who knows the URL of the server you just started, and can
   1.348 +talk to your computer over the network, can then use a web browser or
   1.349 +Mercurial to read data from that repository.  A URL for a
   1.350 +\hgcmd{serve} instance running on a laptop is likely to look something
   1.351 +like \Verb|http://my-laptop.local:8000/|.
   1.352 +
   1.353 +The \hgcmd{serve} command is \emph{not} a general-purpose web server.
   1.354 +It can do only two things:
   1.355 +\begin{itemize}
   1.356 +\item Allow people to browse the history of the repository it's
   1.357 +  serving, from their normal web browsers.
   1.358 +\item Speak Mercurial's wire protocol, so that people can
   1.359 +  \hgcmd{clone} or \hgcmd{pull} changes from that repository.
   1.360 +\end{itemize}
   1.361 +In particular, \hgcmd{serve} won't allow remote users to \emph{modify}
   1.362 +your repository.  It's intended for read-only use.
   1.363 +
   1.364 +If you're getting started with Mercurial, there's nothing to prevent
   1.365 +you from using \hgcmd{serve} to serve up a repository on your own
   1.366 +computer, then use commands like \hgcmd{clone}, \hgcmd{incoming}, and
   1.367 +so on to talk to that server as if the repository was hosted remotely.
   1.368 +This can help you to quickly get acquainted with using commands on
   1.369 +network-hosted repositories.
   1.370 +
   1.371 +\subsection{A few things to keep in mind}
   1.372 +
   1.373 +Because it provides unauthenticated read access to all clients, you
   1.374 +should only use \hgcmd{serve} in an environment where you either don't
   1.375 +care, or have complete control over, who can access your network and
   1.376 +pull data from your repository.
   1.377 +
   1.378 +The \hgcmd{serve} command knows nothing about any firewall software
   1.379 +you might have installed on your system or network.  It cannot detect
   1.380 +or control your firewall software.  If other people are unable to talk
   1.381 +to a running \hgcmd{serve} instance, the second thing you should do
   1.382 +(\emph{after} you make sure that they're using the correct URL) is
   1.383 +check your firewall configuration.
   1.384 +
   1.385 +By default, \hgcmd{serve} listens for incoming connections on
   1.386 +port~8000.  If another process is already listening on the port you
   1.387 +want to use, you can specify a different port to listen on using the
   1.388 +\hgopt{serve}{-p} option.
   1.389 +
   1.390 +Normally, when \hgcmd{serve} starts, it prints no output, which can be
   1.391 +a bit unnerving.  If you'd like to confirm that it is indeed running
   1.392 +correctly, and find out what URL you should send to your
   1.393 +collaborators, start it with the \hggopt{-v} option.
   1.394 +
   1.395 +\section{Using the Secure Shell (ssh) protocol}
   1.396 +\label{sec:collab:ssh}
   1.397 +
   1.398 +You can pull and push changes securely over a network connection using
   1.399 +the Secure Shell (\texttt{ssh}) protocol.  To use this successfully,
   1.400 +you may have to do a little bit of configuration on the client or
   1.401 +server sides.
   1.402 +
   1.403 +If you're not familiar with ssh, it's a network protocol that lets you
   1.404 +securely communicate with another computer.  To use it with Mercurial,
   1.405 +you'll be setting up one or more user accounts on a server so that
   1.406 +remote users can log in and execute commands.
   1.407 +
   1.408 +(If you \emph{are} familiar with ssh, you'll probably find some of the
   1.409 +material that follows to be elementary in nature.)
   1.410 +
   1.411 +\subsection{How to read and write ssh URLs}
   1.412 +
   1.413 +An ssh URL tends to look like this:
   1.414 +\begin{codesample2}
   1.415 +  ssh://bos@hg.serpentine.com:22/hg/hgbook
   1.416 +\end{codesample2}
   1.417 +\begin{enumerate}
   1.418 +\item The ``\texttt{ssh://}'' part tells Mercurial to use the ssh
   1.419 +  protocol.
   1.420 +\item The ``\texttt{bos@}'' component indicates what username to log
   1.421 +  into the server as.  You can leave this out if the remote username
   1.422 +  is the same as your local username.
   1.423 +\item The ``\texttt{hg.serpentine.com}'' gives the hostname of the
   1.424 +  server to log into.
   1.425 +\item The ``:22'' identifies the port number to connect to the server
   1.426 +  on.  The default port is~22, so you only need to specify this part
   1.427 +  if you're \emph{not} using port~22.
   1.428 +\item The remainder of the URL is the local path to the repository on
   1.429 +  the server.
   1.430 +\end{enumerate}
   1.431 +
   1.432 +There's plenty of scope for confusion with the path component of ssh
   1.433 +URLs, as there is no standard way for tools to interpret it.  Some
   1.434 +programs behave differently than others when dealing with these paths.
   1.435 +This isn't an ideal situation, but it's unlikely to change.  Please
   1.436 +read the following paragraphs carefully.
   1.437 +
   1.438 +Mercurial treats the path to a repository on the server as relative to
   1.439 +the remote user's home directory.  For example, if user \texttt{foo}
   1.440 +on the server has a home directory of \dirname{/home/foo}, then an ssh
   1.441 +URL that contains a path component of \dirname{bar}
   1.442 +\emph{really} refers to the directory \dirname{/home/foo/bar}.
   1.443 +
   1.444 +If you want to specify a path relative to another user's home
   1.445 +directory, you can use a path that starts with a tilde character
   1.446 +followed by the user's name (let's call them \texttt{otheruser}), like
   1.447 +this.
   1.448 +\begin{codesample2}
   1.449 +  ssh://server/~otheruser/hg/repo
   1.450 +\end{codesample2}
   1.451 +
   1.452 +And if you really want to specify an \emph{absolute} path on the
   1.453 +server, begin the path component with two slashes, as in this example.
   1.454 +\begin{codesample2}
   1.455 +  ssh://server//absolute/path
   1.456 +\end{codesample2}
   1.457 +
   1.458 +\subsection{Finding an ssh client for your system}
   1.459 +
   1.460 +Almost every Unix-like system comes with OpenSSH preinstalled.  If
   1.461 +you're using such a system, run \Verb|which ssh| to find out if
   1.462 +the \command{ssh} command is installed (it's usually in
   1.463 +\dirname{/usr/bin}).  In the unlikely event that it isn't present,
   1.464 +take a look at your system documentation to figure out how to install
   1.465 +it.
   1.466 +
   1.467 +On Windows, you'll first need to download a suitable ssh
   1.468 +client.  There are two alternatives.
   1.469 +\begin{itemize}
   1.470 +\item Simon Tatham's excellent PuTTY package~\cite{web:putty} provides
   1.471 +  a complete suite of ssh client commands.
   1.472 +\item If you have a high tolerance for pain, you can use the Cygwin
   1.473 +  port of OpenSSH.
   1.474 +\end{itemize}
   1.475 +In either case, you'll need to edit your \hgini\ file to tell
   1.476 +Mercurial where to find the actual client command.  For example, if
   1.477 +you're using PuTTY, you'll need to use the \command{plink} command as
   1.478 +a command-line ssh client.
   1.479 +\begin{codesample2}
   1.480 +  [ui]
   1.481 +  ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"
   1.482 +\end{codesample2}
   1.483 +
   1.484 +\begin{note}
   1.485 +  The path to \command{plink} shouldn't contain any whitespace
   1.486 +  characters, or Mercurial may not be able to run it correctly (so
   1.487 +  putting it in \dirname{C:\\Program Files} is probably not a good
   1.488 +  idea).
   1.489 +\end{note}
   1.490 +
   1.491 +\subsection{Generating a key pair}
   1.492 +
   1.493 +To avoid the need to repetitively type a password every time you need
   1.494 +to use your ssh client, I recommend generating a key pair.  On a
   1.495 +Unix-like system, the \command{ssh-keygen} command will do the trick.
   1.496 +On Windows, if you're using PuTTY, the \command{puttygen} command is
   1.497 +what you'll need.
   1.498 +
   1.499 +When you generate a key pair, it's usually \emph{highly} advisable to
   1.500 +protect it with a passphrase.  (The only time that you might not want
   1.501 +to do this is when you're using the ssh protocol for automated tasks
   1.502 +on a secure network.)
   1.503 +
   1.504 +Simply generating a key pair isn't enough, however.  You'll need to
   1.505 +add the public key to the set of authorised keys for whatever user
   1.506 +you're logging in remotely as.  For servers using OpenSSH (the vast
   1.507 +majority), this will mean adding the public key to a list in a file
   1.508 +called \sfilename{authorized\_keys} in their \sdirname{.ssh}
   1.509 +directory.
   1.510 +
   1.511 +On a Unix-like system, your public key will have a \filename{.pub}
   1.512 +extension.  If you're using \command{puttygen} on Windows, you can
   1.513 +save the public key to a file of your choosing, or paste it from the
   1.514 +window it's displayed in straight into the
   1.515 +\sfilename{authorized\_keys} file.
   1.516 +
   1.517 +\subsection{Using an authentication agent}
   1.518 +
   1.519 +An authentication agent is a daemon that stores passphrases in memory
   1.520 +(so it will forget passphrases if you log out and log back in again).
   1.521 +An ssh client will notice if it's running, and query it for a
   1.522 +passphrase.  If there's no authentication agent running, or the agent
   1.523 +doesn't store the necessary passphrase, you'll have to type your
   1.524 +passphrase every time Mercurial tries to communicate with a server on
   1.525 +your behalf (e.g.~whenever you pull or push changes).
   1.526 +
   1.527 +The downside of storing passphrases in an agent is that it's possible
   1.528 +for a well-prepared attacker to recover the plain text of your
   1.529 +passphrases, in some cases even if your system has been power-cycled.
   1.530 +You should make your own judgment as to whether this is an acceptable
   1.531 +risk.  It certainly saves a lot of repeated typing.
   1.532 +
   1.533 +On Unix-like systems, the agent is called \command{ssh-agent}, and
   1.534 +it's often run automatically for you when you log in.  You'll need to
   1.535 +use the \command{ssh-add} command to add passphrases to the agent's
   1.536 +store.  On Windows, if you're using PuTTY, the \command{pageant}
   1.537 +command acts as the agent.  It adds an icon to your system tray that
   1.538 +will let you manage stored passphrases.
   1.539 +
   1.540 +\subsection{Configuring the server side properly}
   1.541 +
   1.542 +Because ssh can be fiddly to set up if you're new to it, there's a
   1.543 +variety of things that can go wrong.  Add Mercurial on top, and
   1.544 +there's plenty more scope for head-scratching.  Most of these
   1.545 +potential problems occur on the server side, not the client side.  The
   1.546 +good news is that once you've gotten a configuration working, it will
   1.547 +usually continue to work indefinitely.
   1.548 +
   1.549 +Before you try using Mercurial to talk to an ssh server, it's best to
   1.550 +make sure that you can use the normal \command{ssh} or \command{putty}
   1.551 +command to talk to the server first.  If you run into problems with
   1.552 +using these commands directly, Mercurial surely won't work.  Worse, it
   1.553 +will obscure the underlying problem.  Any time you want to debug
   1.554 +ssh-related Mercurial problems, you should drop back to making sure
   1.555 +that plain ssh client commands work first, \emph{before} you worry
   1.556 +about whether there's a problem with Mercurial.
   1.557 +
   1.558 +The first thing to be sure of on the server side is that you can
   1.559 +actually log in from another machine at all.  If you can't use
   1.560 +\command{ssh} or \command{putty} to log in, the error message you get
   1.561 +may give you a few hints as to what's wrong.  The most common problems
   1.562 +are as follows.
   1.563 +\begin{itemize}
   1.564 +\item If you get a ``connection refused'' error, either there isn't an
   1.565 +  SSH daemon running on the server at all, or it's inaccessible due to
   1.566 +  firewall configuration.
   1.567 +\item If you get a ``no route to host'' error, you either have an
   1.568 +  incorrect address for the server or a seriously locked down firewall
   1.569 +  that won't admit its existence at all.
   1.570 +\item If you get a ``permission denied'' error, you may have mistyped
   1.571 +  the username on the server, or you could have mistyped your key's
   1.572 +  passphrase or the remote user's password.
   1.573 +\end{itemize}
   1.574 +In summary, if you're having trouble talking to the server's ssh
   1.575 +daemon, first make sure that one is running at all.  On many systems
   1.576 +it will be installed, but disabled, by default.  Once you're done with
   1.577 +this step, you should then check that the server's firewall is
   1.578 +configured to allow incoming connections on the port the ssh daemon is
   1.579 +listening on (usually~22).  Don't worry about more exotic
   1.580 +possibilities for misconfiguration until you've checked these two
   1.581 +first.
   1.582 +
   1.583 +If you're using an authentication agent on the client side to store
   1.584 +passphrases for your keys, you ought to be able to log into the server
   1.585 +without being prompted for a passphrase or a password.  If you're
   1.586 +prompted for a passphrase, there are a few possible culprits.
   1.587 +\begin{itemize}
   1.588 +\item You might have forgotten to use \command{ssh-add} or
   1.589 +  \command{pageant} to store the passphrase.
   1.590 +\item You might have stored the passphrase for the wrong key.
   1.591 +\end{itemize}
   1.592 +If you're being prompted for the remote user's password, there are
   1.593 +another few possible problems to check.
   1.594 +\begin{itemize}
   1.595 +\item Either the user's home directory or their \sdirname{.ssh}
   1.596 +  directory might have excessively liberal permissions.  As a result,
   1.597 +  the ssh daemon will not trust or read their
   1.598 +  \sfilename{authorized\_keys} file.  For example, a group-writable
   1.599 +  home or \sdirname{.ssh} directory will often cause this symptom.
   1.600 +\item The user's \sfilename{authorized\_keys} file may have a problem.
   1.601 +  If anyone other than the user owns or can write to that file, the
   1.602 +  ssh daemon will not trust or read it.
   1.603 +\end{itemize}
   1.604 +
   1.605 +In the ideal world, you should be able to run the following command
   1.606 +successfully, and it should print exactly one line of output, the
   1.607 +current date and time.
   1.608 +\begin{codesample2}
   1.609 +  ssh myserver date
   1.610 +\end{codesample2}
   1.611 +
   1.612 +If, on your server, you have login scripts that print banners or other
   1.613 +junk even when running non-interactive commands like this, you should
   1.614 +fix them before you continue, so that they only print output if
   1.615 +they're run interactively.  Otherwise these banners will at least
   1.616 +clutter up Mercurial's output.  Worse, they could potentially cause
   1.617 +problems with running Mercurial commands remotely.  Mercurial makes
   1.618 +tries to detect and ignore banners in non-interactive \command{ssh}
   1.619 +sessions, but it is not foolproof.  (If you're editing your login
   1.620 +scripts on your server, the usual way to see if a login script is
   1.621 +running in an interactive shell is to check the return code from the
   1.622 +command \Verb|tty -s|.)
   1.623 +
   1.624 +Once you've verified that plain old ssh is working with your server,
   1.625 +the next step is to ensure that Mercurial runs on the server.  The
   1.626 +following command should run successfully:
   1.627 +\begin{codesample2}
   1.628 +  ssh myserver hg version
   1.629 +\end{codesample2}
   1.630 +If you see an error message instead of normal \hgcmd{version} output,
   1.631 +this is usually because you haven't installed Mercurial to
   1.632 +\dirname{/usr/bin}.  Don't worry if this is the case; you don't need
   1.633 +to do that.  But you should check for a few possible problems.
   1.634 +\begin{itemize}
   1.635 +\item Is Mercurial really installed on the server at all?  I know this
   1.636 +  sounds trivial, but it's worth checking!
   1.637 +\item Maybe your shell's search path (usually set via the \envar{PATH}
   1.638 +  environment variable) is simply misconfigured.
   1.639 +\item Perhaps your \envar{PATH} environment variable is only being set
   1.640 +  to point to the location of the \command{hg} executable if the login
   1.641 +  session is interactive.  This can happen if you're setting the path
   1.642 +  in the wrong shell login script.  See your shell's documentation for
   1.643 +  details.
   1.644 +\item The \envar{PYTHONPATH} environment variable may need to contain
   1.645 +  the path to the Mercurial Python modules.  It might not be set at
   1.646 +  all; it could be incorrect; or it may be set only if the login is
   1.647 +  interactive.
   1.648 +\end{itemize}
   1.649 +
   1.650 +If you can run \hgcmd{version} over an ssh connection, well done!
   1.651 +You've got the server and client sorted out.  You should now be able
   1.652 +to use Mercurial to access repositories hosted by that username on
   1.653 +that server.  If you run into problems with Mercurial and ssh at this
   1.654 +point, try using the \hggopt{--debug} option to get a clearer picture
   1.655 +of what's going on.
   1.656 +
   1.657 +\subsection{Using compression with ssh}
   1.658 +
   1.659 +Mercurial does not compress data when it uses the ssh protocol,
   1.660 +because the ssh protocol can transparently compress data.  However,
   1.661 +the default behaviour of ssh clients is \emph{not} to request
   1.662 +compression.
   1.663 +
   1.664 +Over any network other than a fast LAN (even a wireless network),
   1.665 +using compression is likely to significantly speed up Mercurial's
   1.666 +network operations.  For example, over a WAN, someone measured
   1.667 +compression as reducing the amount of time required to clone a
   1.668 +particularly large repository from~51 minutes to~17 minutes.
   1.669 +
   1.670 +Both \command{ssh} and \command{plink} accept a \cmdopt{ssh}{-C}
   1.671 +option which turns on compression.  You can easily edit your \hgrc\ to
   1.672 +enable compression for all of Mercurial's uses of the ssh protocol.
   1.673 +\begin{codesample2}
   1.674 +  [ui]
   1.675 +  ssh = ssh -C
   1.676 +\end{codesample2}
   1.677 +
   1.678 +If you use \command{ssh}, you can configure it to always use
   1.679 +compression when talking to your server.  To do this, edit your
   1.680 +\sfilename{.ssh/config} file (which may not yet exist), as follows.
   1.681 +\begin{codesample2}
   1.682 +  Host hg
   1.683 +    Compression yes
   1.684 +    HostName hg.example.com
   1.685 +\end{codesample2}
   1.686 +This defines an alias, \texttt{hg}.  When you use it on the
   1.687 +\command{ssh} command line or in a Mercurial \texttt{ssh}-protocol
   1.688 +URL, it will cause \command{ssh} to connect to \texttt{hg.example.com}
   1.689 +and use compression.  This gives you both a shorter name to type and
   1.690 +compression, each of which is a good thing in its own right.
   1.691 +
   1.692 +\section{Serving over HTTP using CGI}
   1.693 +\label{sec:collab:cgi}
   1.694 +
   1.695 +Depending on how ambitious you are, configuring Mercurial's CGI
   1.696 +interface can take anything from a few moments to several hours.
   1.697 +
   1.698 +We'll begin with the simplest of examples, and work our way towards a
   1.699 +more complex configuration.  Even for the most basic case, you're
   1.700 +almost certainly going to need to read and modify your web server's
   1.701 +configuration.
   1.702 +
   1.703 +\begin{note}
   1.704 +  Configuring a web server is a complex, fiddly, and highly
   1.705 +  system-dependent activity.  I can't possibly give you instructions
   1.706 +  that will cover anything like all of the cases you will encounter.
   1.707 +  Please use your discretion and judgment in following the sections
   1.708 +  below.  Be prepared to make plenty of mistakes, and to spend a lot
   1.709 +  of time reading your server's error logs.
   1.710 +\end{note}
   1.711 +
   1.712 +\subsection{Web server configuration checklist}
   1.713 +
   1.714 +Before you continue, do take a few moments to check a few aspects of
   1.715 +your system's setup.
   1.716 +
   1.717 +\begin{enumerate}
   1.718 +\item Do you have a web server installed at all?  Mac OS X ships with
   1.719 +  Apache, but many other systems may not have a web server installed.
   1.720 +\item If you have a web server installed, is it actually running?  On
   1.721 +  most systems, even if one is present, it will be disabled by
   1.722 +  default.
   1.723 +\item Is your server configured to allow you to run CGI programs in
   1.724 +  the directory where you plan to do so?  Most servers default to
   1.725 +  explicitly disabling the ability to run CGI programs.
   1.726 +\end{enumerate}
   1.727 +
   1.728 +If you don't have a web server installed, and don't have substantial
   1.729 +experience configuring Apache, you should consider using the
   1.730 +\texttt{lighttpd} web server instead of Apache.  Apache has a
   1.731 +well-deserved reputation for baroque and confusing configuration.
   1.732 +While \texttt{lighttpd} is less capable in some ways than Apache, most
   1.733 +of these capabilities are not relevant to serving Mercurial
   1.734 +repositories.  And \texttt{lighttpd} is undeniably \emph{much} easier
   1.735 +to get started with than Apache.
   1.736 +
   1.737 +\subsection{Basic CGI configuration}
   1.738 +
   1.739 +On Unix-like systems, it's common for users to have a subdirectory
   1.740 +named something like \dirname{public\_html} in their home directory,
   1.741 +from which they can serve up web pages.  A file named \filename{foo}
   1.742 +in this directory will be accessible at a URL of the form
   1.743 +\texttt{http://www.example.com/\~{}username/foo}.
   1.744 +
   1.745 +To get started, find the \sfilename{hgweb.cgi} script that should be
   1.746 +present in your Mercurial installation.  If you can't quickly find a
   1.747 +local copy on your system, simply download one from the master
   1.748 +Mercurial repository at
   1.749 +\url{http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi}.
   1.750 +
   1.751 +You'll need to copy this script into your \dirname{public\_html}
   1.752 +directory, and ensure that it's executable.
   1.753 +\begin{codesample2}
   1.754 +  cp .../hgweb.cgi ~/public_html
   1.755 +  chmod 755 ~/public_html/hgweb.cgi
   1.756 +\end{codesample2}
   1.757 +The \texttt{755} argument to \command{chmod} is a little more general
   1.758 +than just making the script executable: it ensures that the script is
   1.759 +executable by anyone, and that ``group'' and ``other'' write
   1.760 +permissions are \emph{not} set.  If you were to leave those write
   1.761 +permissions enabled, Apache's \texttt{suexec} subsystem would likely
   1.762 +refuse to execute the script.  In fact, \texttt{suexec} also insists
   1.763 +that the \emph{directory} in which the script resides must not be
   1.764 +writable by others.
   1.765 +\begin{codesample2}
   1.766 +  chmod 755 ~/public_html
   1.767 +\end{codesample2}
   1.768 +
   1.769 +\subsubsection{What could \emph{possibly} go wrong?}
   1.770 +\label{sec:collab:wtf}
   1.771 +
   1.772 +Once you've copied the CGI script into place, go into a web browser,
   1.773 +and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi},
   1.774 +\emph{but} brace yourself for instant failure.  There's a high
   1.775 +probability that trying to visit this URL will fail, and there are
   1.776 +many possible reasons for this.  In fact, you're likely to stumble
   1.777 +over almost every one of the possible errors below, so please read
   1.778 +carefully.  The following are all of the problems I ran into on a
   1.779 +system running Fedora~7, with a fresh installation of Apache, and a
   1.780 +user account that I created specially to perform this exercise.
   1.781 +
   1.782 +Your web server may have per-user directories disabled.  If you're
   1.783 +using Apache, search your config file for a \texttt{UserDir}
   1.784 +directive.  If there's none present, per-user directories will be
   1.785 +disabled.  If one exists, but its value is \texttt{disabled}, then
   1.786 +per-user directories will be disabled.  Otherwise, the string after
   1.787 +\texttt{UserDir} gives the name of the subdirectory that Apache will
   1.788 +look in under your home directory, for example \dirname{public\_html}.
   1.789 +
   1.790 +Your file access permissions may be too restrictive.  The web server
   1.791 +must be able to traverse your home directory and directories under
   1.792 +your \dirname{public\_html} directory, and read files under the latter
   1.793 +too.  Here's a quick recipe to help you to make your permissions more
   1.794 +appropriate.
   1.795 +\begin{codesample2}
   1.796 +  chmod 755 ~
   1.797 +  find ~/public_html -type d -print0 | xargs -0r chmod 755
   1.798 +  find ~/public_html -type f -print0 | xargs -0r chmod 644
   1.799 +\end{codesample2}
   1.800 +
   1.801 +The other possibility with permissions is that you might get a
   1.802 +completely empty window when you try to load the script.  In this
   1.803 +case, it's likely that your access permissions are \emph{too
   1.804 +  permissive}.  Apache's \texttt{suexec} subsystem won't execute a
   1.805 +script that's group-~or world-writable, for example.
   1.806 +
   1.807 +Your web server may be configured to disallow execution of CGI
   1.808 +programs in your per-user web directory.  Here's Apache's
   1.809 +default per-user configuration from my Fedora system.
   1.810 +\begin{codesample2}
   1.811 +  <Directory /home/*/public_html>
   1.812 +      AllowOverride FileInfo AuthConfig Limit
   1.813 +      Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
   1.814 +      <Limit GET POST OPTIONS>
   1.815 +          Order allow,deny
   1.816 +          Allow from all
   1.817 +      </Limit>
   1.818 +      <LimitExcept GET POST OPTIONS>
   1.819 +          Order deny,allow
   1.820 +          Deny from all
   1.821 +      </LimitExcept>
   1.822 +  </Directory>
   1.823 +\end{codesample2}
   1.824 +If you find a similar-looking \texttt{Directory} group in your Apache
   1.825 +configuration, the directive to look at inside it is \texttt{Options}.
   1.826 +Add \texttt{ExecCGI} to the end of this list if it's missing, and
   1.827 +restart the web server.
   1.828 +
   1.829 +If you find that Apache serves you the text of the CGI script instead
   1.830 +of executing it, you may need to either uncomment (if already present)
   1.831 +or add a directive like this.
   1.832 +\begin{codesample2}
   1.833 +  AddHandler cgi-script .cgi
   1.834 +\end{codesample2}
   1.835 +
   1.836 +The next possibility is that you might be served with a colourful
   1.837 +Python backtrace claiming that it can't import a
   1.838 +\texttt{mercurial}-related module.  This is actually progress!  The
   1.839 +server is now capable of executing your CGI script.  This error is
   1.840 +only likely to occur if you're running a private installation of
   1.841 +Mercurial, instead of a system-wide version.  Remember that the web
   1.842 +server runs the CGI program without any of the environment variables
   1.843 +that you take for granted in an interactive session.  If this error
   1.844 +happens to you, edit your copy of \sfilename{hgweb.cgi} and follow the
   1.845 +directions inside it to correctly set your \envar{PYTHONPATH}
   1.846 +environment variable.
   1.847 +
   1.848 +Finally, you are \emph{certain} to by served with another colourful
   1.849 +Python backtrace: this one will complain that it can't find
   1.850 +\dirname{/path/to/repository}.  Edit your \sfilename{hgweb.cgi} script
   1.851 +and replace the \dirname{/path/to/repository} string with the complete
   1.852 +path to the repository you want to serve up.
   1.853 +
   1.854 +At this point, when you try to reload the page, you should be
   1.855 +presented with a nice HTML view of your repository's history.  Whew!
   1.856 +
   1.857 +\subsubsection{Configuring lighttpd}
   1.858 +
   1.859 +To be exhaustive in my experiments, I tried configuring the
   1.860 +increasingly popular \texttt{lighttpd} web server to serve the same
   1.861 +repository as I described with Apache above.  I had already overcome
   1.862 +all of the problems I outlined with Apache, many of which are not
   1.863 +server-specific.  As a result, I was fairly sure that my file and
   1.864 +directory permissions were good, and that my \sfilename{hgweb.cgi}
   1.865 +script was properly edited.
   1.866 +
   1.867 +Once I had Apache running, getting \texttt{lighttpd} to serve the
   1.868 +repository was a snap (in other words, even if you're trying to use
   1.869 +\texttt{lighttpd}, you should read the Apache section).  I first had
   1.870 +to edit the \texttt{mod\_access} section of its config file to enable
   1.871 +\texttt{mod\_cgi} and \texttt{mod\_userdir}, both of which were
   1.872 +disabled by default on my system.  I then added a few lines to the end
   1.873 +of the config file, to configure these modules.
   1.874 +\begin{codesample2}
   1.875 +  userdir.path = "public_html"
   1.876 +  cgi.assign = ( ".cgi" => "" )
   1.877 +\end{codesample2}
   1.878 +With this done, \texttt{lighttpd} ran immediately for me.  If I had
   1.879 +configured \texttt{lighttpd} before Apache, I'd almost certainly have
   1.880 +run into many of the same system-level configuration problems as I did
   1.881 +with Apache.  However, I found \texttt{lighttpd} to be noticeably
   1.882 +easier to configure than Apache, even though I've used Apache for over
   1.883 +a decade, and this was my first exposure to \texttt{lighttpd}.
   1.884 +
   1.885 +\subsection{Sharing multiple repositories with one CGI script}
   1.886 +
   1.887 +The \sfilename{hgweb.cgi} script only lets you publish a single
   1.888 +repository, which is an annoying restriction.  If you want to publish
   1.889 +more than one without wracking yourself with multiple copies of the
   1.890 +same script, each with different names, a better choice is to use the
   1.891 +\sfilename{hgwebdir.cgi} script.
   1.892 +
   1.893 +The procedure to configure \sfilename{hgwebdir.cgi} is only a little
   1.894 +more involved than for \sfilename{hgweb.cgi}.  First, you must obtain
   1.895 +a copy of the script.  If you don't have one handy, you can download a
   1.896 +copy from the master Mercurial repository at
   1.897 +\url{http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi}.
   1.898 +
   1.899 +You'll need to copy this script into your \dirname{public\_html}
   1.900 +directory, and ensure that it's executable.
   1.901 +\begin{codesample2}
   1.902 +  cp .../hgwebdir.cgi ~/public_html
   1.903 +  chmod 755 ~/public_html ~/public_html/hgwebdir.cgi
   1.904 +\end{codesample2}
   1.905 +With basic configuration out of the way, try to visit
   1.906 +\url{http://myhostname/~myuser/hgwebdir.cgi} in your browser.  It
   1.907 +should display an empty list of repositories.  If you get a blank
   1.908 +window or error message, try walking through the list of potential
   1.909 +problems in section~\ref{sec:collab:wtf}.
   1.910 +
   1.911 +The \sfilename{hgwebdir.cgi} script relies on an external
   1.912 +configuration file.  By default, it searches for a file named
   1.913 +\sfilename{hgweb.config} in the same directory as itself.  You'll need
   1.914 +to create this file, and make it world-readable.  The format of the
   1.915 +file is similar to a Windows ``ini'' file, as understood by Python's
   1.916 +\texttt{ConfigParser}~\cite{web:configparser} module.
   1.917 +
   1.918 +The easiest way to configure \sfilename{hgwebdir.cgi} is with a
   1.919 +section named \texttt{collections}.  This will automatically publish
   1.920 +\emph{every} repository under the directories you name.  The section
   1.921 +should look like this:
   1.922 +\begin{codesample2}
   1.923 +  [collections]
   1.924 +  /my/root = /my/root
   1.925 +\end{codesample2}
   1.926 +Mercurial interprets this by looking at the directory name on the
   1.927 +\emph{right} hand side of the ``\texttt{=}'' sign; finding
   1.928 +repositories in that directory hierarchy; and using the text on the
   1.929 +\emph{left} to strip off matching text from the names it will actually
   1.930 +list in the web interface.  The remaining component of a path after
   1.931 +this stripping has occurred is called a ``virtual path''.
   1.932 +
   1.933 +Given the example above, if we have a repository whose local path is
   1.934 +\dirname{/my/root/this/repo}, the CGI script will strip the leading
   1.935 +\dirname{/my/root} from the name, and publish the repository with a
   1.936 +virtual path of \dirname{this/repo}.  If the base URL for our CGI
   1.937 +script is \url{http://myhostname/~myuser/hgwebdir.cgi}, the complete
   1.938 +URL for that repository will be
   1.939 +\url{http://myhostname/~myuser/hgwebdir.cgi/this/repo}.
   1.940 +
   1.941 +If we replace \dirname{/my/root} on the left hand side of this example
   1.942 +with \dirname{/my}, then \sfilename{hgwebdir.cgi} will only strip off
   1.943 +\dirname{/my} from the repository name, and will give us a virtual
   1.944 +path of \dirname{root/this/repo} instead of \dirname{this/repo}.
   1.945 +
   1.946 +The \sfilename{hgwebdir.cgi} script will recursively search each
   1.947 +directory listed in the \texttt{collections} section of its
   1.948 +configuration file, but it will \texttt{not} recurse into the
   1.949 +repositories it finds.
   1.950 +
   1.951 +The \texttt{collections} mechanism makes it easy to publish many
   1.952 +repositories in a ``fire and forget'' manner.  You only need to set up
   1.953 +the CGI script and configuration file one time.  Afterwards, you can
   1.954 +publish or unpublish a repository at any time by simply moving it
   1.955 +into, or out of, the directory hierarchy in which you've configured
   1.956 +\sfilename{hgwebdir.cgi} to look.
   1.957 +
   1.958 +\subsubsection{Explicitly specifying which repositories to publish}
   1.959 +
   1.960 +In addition to the \texttt{collections} mechanism, the
   1.961 +\sfilename{hgwebdir.cgi} script allows you to publish a specific list
   1.962 +of repositories.  To do so, create a \texttt{paths} section, with
   1.963 +contents of the following form.
   1.964 +\begin{codesample2}
   1.965 +  [paths]
   1.966 +  repo1 = /my/path/to/some/repo
   1.967 +  repo2 = /some/path/to/another
   1.968 +\end{codesample2}
   1.969 +In this case, the virtual path (the component that will appear in a
   1.970 +URL) is on the left hand side of each definition, while the path to
   1.971 +the repository is on the right.  Notice that there does not need to be
   1.972 +any relationship between the virtual path you choose and the location
   1.973 +of a repository in your filesystem.
   1.974 +
   1.975 +If you wish, you can use both the \texttt{collections} and
   1.976 +\texttt{paths} mechanisms simultaneously in a single configuration
   1.977 +file.
   1.978 +
   1.979 +\begin{note}
   1.980 +  If multiple repositories have the same virtual path,
   1.981 +  \sfilename{hgwebdir.cgi} will not report an error.  Instead, it will
   1.982 +  behave unpredictably.
   1.983 +\end{note}
   1.984 +
   1.985 +\subsection{Downloading source archives}
   1.986 +
   1.987 +Mercurial's web interface lets users download an archive of any
   1.988 +revision.  This archive will contain a snapshot of the working
   1.989 +directory as of that revision, but it will not contain a copy of the
   1.990 +repository data.
   1.991 +
   1.992 +By default, this feature is not enabled.  To enable it, you'll need to
   1.993 +add an \rcitem{web}{allow\_archive} item to the \rcsection{web}
   1.994 +section of your \hgrc.
   1.995 +
   1.996 +\subsection{Web configuration options}
   1.997 +
   1.998 +Mercurial's web interfaces (the \hgcmd{serve} command, and the
   1.999 +\sfilename{hgweb.cgi} and \sfilename{hgwebdir.cgi} scripts) have a
  1.1000 +number of configuration options that you can set.  These belong in a
  1.1001 +section named \rcsection{web}.
  1.1002 +\begin{itemize}
  1.1003 +\item[\rcitem{web}{allow\_archive}] Determines which (if any) archive
  1.1004 +  download mechanisms Mercurial supports.  If you enable this
  1.1005 +  feature, users of the web interface will be able to download an
  1.1006 +  archive of whatever revision of a repository they are viewing.
  1.1007 +  To enable the archive feature, this item must take the form of a
  1.1008 +  sequence of words drawn from the list below.
  1.1009 +  \begin{itemize}
  1.1010 +  \item[\texttt{bz2}] A \command{tar} archive, compressed using
  1.1011 +    \texttt{bzip2} compression.  This has the best compression ratio,
  1.1012 +    but uses the most CPU time on the server.
  1.1013 +  \item[\texttt{gz}] A \command{tar} archive, compressed using
  1.1014 +    \texttt{gzip} compression.
  1.1015 +  \item[\texttt{zip}] A \command{zip} archive, compressed using LZW
  1.1016 +    compression.  This format has the worst compression ratio, but is
  1.1017 +    widely used in the Windows world.
  1.1018 +  \end{itemize}
  1.1019 +  If you provide an empty list, or don't have an
  1.1020 +  \rcitem{web}{allow\_archive} entry at all, this feature will be
  1.1021 +  disabled.  Here is an example of how to enable all three supported
  1.1022 +  formats.
  1.1023 +  \begin{codesample4}
  1.1024 +    [web]
  1.1025 +    allow_archive = bz2 gz zip
  1.1026 +  \end{codesample4}
  1.1027 +\item[\rcitem{web}{allowpull}] Boolean.  Determines whether the web
  1.1028 +  interface allows remote users to \hgcmd{pull} and \hgcmd{clone} this
  1.1029 +  repository over~HTTP.  If set to \texttt{no} or \texttt{false}, only
  1.1030 +  the ``human-oriented'' portion of the web interface is available.
  1.1031 +\item[\rcitem{web}{contact}] String.  A free-form (but preferably
  1.1032 +  brief) string identifying the person or group in charge of the
  1.1033 +  repository.  This often contains the name and email address of a
  1.1034 +  person or mailing list.  It often makes sense to place this entry in
  1.1035 +  a repository's own \sfilename{.hg/hgrc} file, but it can make sense
  1.1036 +  to use in a global \hgrc\ if every repository has a single
  1.1037 +  maintainer.
  1.1038 +\item[\rcitem{web}{maxchanges}] Integer.  The default maximum number
  1.1039 +  of changesets to display in a single page of output.
  1.1040 +\item[\rcitem{web}{maxfiles}] Integer.  The default maximum number
  1.1041 +  of modified files to display in a single page of output.
  1.1042 +\item[\rcitem{web}{stripes}] Integer.  If the web interface displays
  1.1043 +  alternating ``stripes'' to make it easier to visually align rows
  1.1044 +  when you are looking at a table, this number controls the number of
  1.1045 +  rows in each stripe.
  1.1046 +\item[\rcitem{web}{style}] Controls the template Mercurial uses to
  1.1047 +  display the web interface.  Mercurial ships with two web templates,
  1.1048 +  named \texttt{default} and \texttt{gitweb} (the latter is much more
  1.1049 +  visually attractive).  You can also specify a custom template of
  1.1050 +  your own; see chapter~\ref{chap:template} for details.  Here, you
  1.1051 +  can see how to enable the \texttt{gitweb} style.
  1.1052 +  \begin{codesample4}
  1.1053 +    [web]
  1.1054 +    style = gitweb
  1.1055 +  \end{codesample4}
  1.1056 +\item[\rcitem{web}{templates}] Path.  The directory in which to search
  1.1057 +  for template files.  By default, Mercurial searches in the directory
  1.1058 +  in which it was installed.
  1.1059 +\end{itemize}
  1.1060 +If you are using \sfilename{hgwebdir.cgi}, you can place a few
  1.1061 +configuration items in a \rcsection{web} section of the
  1.1062 +\sfilename{hgweb.config} file instead of a \hgrc\ file, for
  1.1063 +convenience.  These items are \rcitem{web}{motd} and
  1.1064 +\rcitem{web}{style}.
  1.1065 +
  1.1066 +\subsubsection{Options specific to an individual repository}
  1.1067 +
  1.1068 +A few \rcsection{web} configuration items ought to be placed in a
  1.1069 +repository's local \sfilename{.hg/hgrc}, rather than a user's or
  1.1070 +global \hgrc.
  1.1071 +\begin{itemize}
  1.1072 +\item[\rcitem{web}{description}] String.  A free-form (but preferably
  1.1073 +  brief) string that describes the contents or purpose of the
  1.1074 +  repository.
  1.1075 +\item[\rcitem{web}{name}] String.  The name to use for the repository
  1.1076 +  in the web interface.  This overrides the default name, which is the
  1.1077 +  last component of the repository's path.
  1.1078 +\end{itemize}
  1.1079 +
  1.1080 +\subsubsection{Options specific to the \hgcmd{serve} command}
  1.1081 +
  1.1082 +Some of the items in the \rcsection{web} section of a \hgrc\ file are
  1.1083 +only for use with the \hgcmd{serve} command.
  1.1084 +\begin{itemize}
  1.1085 +\item[\rcitem{web}{accesslog}] Path.  The name of a file into which to
  1.1086 +  write an access log.  By default, the \hgcmd{serve} command writes
  1.1087 +  this information to standard output, not to a file.  Log entries are
  1.1088 +  written in the standard ``combined'' file format used by almost all
  1.1089 +  web servers.
  1.1090 +\item[\rcitem{web}{address}] String.  The local address on which the
  1.1091 +  server should listen for incoming connections.  By default, the
  1.1092 +  server listens on all addresses.
  1.1093 +\item[\rcitem{web}{errorlog}] Path.  The name of a file into which to
  1.1094 +  write an error log.  By default, the \hgcmd{serve} command writes this
  1.1095 +  information to standard error, not to a file.
  1.1096 +\item[\rcitem{web}{ipv6}] Boolean.  Whether to use the IPv6 protocol.
  1.1097 +  By default, IPv6 is not used. 
  1.1098 +\item[\rcitem{web}{port}] Integer.  The TCP~port number on which the
  1.1099 +  server should listen.  The default port number used is~8000.
  1.1100 +\end{itemize}
  1.1101 +
  1.1102 +\subsubsection{Choosing the right \hgrc\ file to add \rcsection{web}
  1.1103 +  items to}
  1.1104 +
  1.1105 +It is important to remember that a web server like Apache or
  1.1106 +\texttt{lighttpd} will run under a user~ID that is different to yours.
  1.1107 +CGI scripts run by your server, such as \sfilename{hgweb.cgi}, will
  1.1108 +usually also run under that user~ID.
  1.1109 +
  1.1110 +If you add \rcsection{web} items to your own personal \hgrc\ file, CGI
  1.1111 +scripts won't read that \hgrc\ file.  Those settings will thus only
  1.1112 +affect the behaviour of the \hgcmd{serve} command when you run it.  To
  1.1113 +cause CGI scripts to see your settings, either create a \hgrc\ file in
  1.1114 +the home directory of the user ID that runs your web server, or add
  1.1115 +those settings to a system-wide \hgrc\ file.
  1.1116 +
  1.1117 +
  1.1118 +%%% Local Variables: 
  1.1119 +%%% mode: latex
  1.1120 +%%% TeX-master: "00book"
  1.1121 +%%% End: