hgbook

annotate en/collab.tex @ 209:8b599dcca584

Mention what the web interface does.
author Bryan O'Sullivan <bos@serpentine.com>
date Wed Apr 25 13:06:30 2007 -0700 (2007-04-25)
parents b60e2de6dbc3
children 27b2c7c46af3
rev   line source
bos@159 1 \chapter{Collaborating with other people}
bos@159 2 \label{cha:collab}
bos@159 3
bos@159 4 As a completely decentralised tool, Mercurial doesn't impose any
bos@159 5 policy on how people ought to work with each other. However, if
bos@159 6 you're new to distributed revision control, it helps to have some
bos@159 7 tools and examples in mind when you're thinking about possible
bos@159 8 workflow models.
bos@159 9
bos@209 10 \section{Mercurial's web interface}
bos@209 11
bos@209 12 Mercurial has a powerful web interface that provides several
bos@209 13 useful capabilities.
bos@209 14
bos@209 15 For interactive use, the web interface lets you browse a single
bos@209 16 repository or a collection of repositories. You can view the history
bos@209 17 of a repository, examine each change (comments and diffs), and view
bos@209 18 the contents of each directory and file.
bos@209 19
bos@209 20 Also for human consumption, the web interface provides an RSS feed of
bos@209 21 the changes in a repository. This lets you ``subscribe'' to a
bos@209 22 repository using your favourite feed reader, and be automatically
bos@209 23 notified of activity in that repository as soon as it happens. I find
bos@209 24 this capability much more convenient than the model of subscribing to
bos@209 25 a mailing list to which notifications are sent, as it requires no
bos@209 26 additional configuration on the part of whoever is serving the
bos@209 27 repository.
bos@209 28
bos@209 29 The web interface also lets remote users clone a repository, pull
bos@209 30 changes from it, and (when the server is configured to permit it) push
bos@209 31 changes back to it. Mercurial's HTTP tunneling protocol aggressively
bos@209 32 compresses data, so that it works efficiently even over low-bandwidth
bos@209 33 network connections.
bos@209 34
bos@209 35 The easiest way to get started with the web interface is to use your
bos@209 36 web browser to visit an existing repository, such as the master
bos@209 37 Mercurial repository at
bos@209 38 \url{http://www.selenic.com/repo/hg?style=gitweb}.
bos@209 39
bos@209 40 If you're interested in providing a web interface to your own
bos@209 41 repositories, Mercurial provides two ways to do this. The first is
bos@209 42 using the \hgcmd{serve} command, which is best suited to short-term
bos@209 43 ``lightweight'' serving. See section~\ref{sec:collab:serve} below for
bos@209 44 details of how to use this command. If you have a long-lived
bos@209 45 repository that you'd like to make permanently available, Mercurial
bos@209 46 has built-in support for the CGI (Common Gateway Interface) standard,
bos@209 47 which all common web servers support. See
bos@209 48 section~\ref{sec:collab:cgi} for details of CGI configuration.
bos@209 49
bos@159 50 \section{Collaboration models}
bos@159 51
bos@159 52 With a suitably flexible tool, making decisions about workflow is much
bos@159 53 more of a social engineering challenge than a technical one.
bos@159 54 Mercurial imposes few limitations on how you can structure the flow of
bos@159 55 work in a project, so it's up to you and your group to set up and live
bos@159 56 with a model that matches your own particular needs.
bos@159 57
bos@159 58 \subsection{Factors to keep in mind}
bos@159 59
bos@159 60 The most important aspect of any model that you must keep in mind is
bos@159 61 how well it matches the needs and capabilities of the people who will
bos@159 62 be using it. This might seem self-evident; even so, you still can't
bos@159 63 afford to forget it for a moment.
bos@159 64
bos@159 65 I once put together a workflow model that seemed to make perfect sense
bos@159 66 to me, but that caused a considerable amount of consternation and
bos@159 67 strife within my development team. In spite of my attempts to explain
bos@159 68 why we needed a complex set of branches, and how changes ought to flow
bos@159 69 between them, a few team members revolted. Even though they were
bos@159 70 smart people, they didn't want to pay attention to the constraints we
bos@159 71 were operating under, or face the consequences of those constraints in
bos@159 72 the details of the model that I was advocating.
bos@159 73
bos@159 74 Don't sweep foreseeable social or technical problems under the rug.
bos@159 75 Whatever scheme you put into effect, you should plan for mistakes and
bos@159 76 problem scenarios. Consider adding automated machinery to prevent, or
bos@159 77 quickly recover from, trouble that you can anticipate. As an example,
bos@159 78 if you intend to have a branch with not-for-release changes in it,
bos@159 79 you'd do well to think early about the possibility that someone might
bos@159 80 accidentally merge those changes into a release branch. You could
bos@159 81 avoid this particular problem by writing a hook that prevents changes
bos@159 82 from being merged from an inappropriate branch.
bos@159 83
bos@159 84 \subsection{Informal anarchy}
bos@159 85
bos@159 86 I wouldn't suggest an ``anything goes'' approach as something
bos@159 87 sustainable, but it's a model that's easy to grasp, and it works
bos@159 88 perfectly well in a few unusual situations.
bos@159 89
bos@159 90 As one example, many projects have a loose-knit group of collaborators
bos@159 91 who rarely physically meet each other. Some groups like to overcome
bos@159 92 the isolation of working at a distance by organising occasional
bos@159 93 ``sprints''. In a sprint, a number of people get together in a single
bos@159 94 location (a company's conference room, a hotel meeting room, that kind
bos@159 95 of place) and spend several days more or less locked in there, hacking
bos@159 96 intensely on a handful of projects.
bos@159 97
bos@159 98 A sprint is the perfect place to use the \hgcmd{serve} command, since
bos@159 99 \hgcmd{serve} does not requires any fancy server infrastructure. You
bos@159 100 can get started with \hgcmd{serve} in moments, by reading
bos@159 101 section~\ref{sec:collab:serve} below. Then simply tell the person
bos@159 102 next to you that you're running a server, send the URL to them in an
bos@159 103 instant message, and you immediately have a quick-turnaround way to
bos@159 104 work together. They can type your URL into their web browser and
bos@159 105 quickly review your changes; or they can pull a bugfix from you and
bos@159 106 verify it; or they can clone a branch containing a new feature and try
bos@159 107 it out.
bos@159 108
bos@159 109 The charm, and the problem, with doing things in an ad hoc fashion
bos@159 110 like this is that only people who know about your changes, and where
bos@159 111 they are, can see them. Such an informal approach simply doesn't
bos@159 112 scale beyond a handful people, because each individual needs to know
bos@159 113 about $n$ different repositories to pull from.
bos@159 114
bos@159 115 \subsection{A single central repository}
bos@159 116
bos@179 117 For smaller projects migrating from a centralised revision control
bos@159 118 tool, perhaps the easiest way to get started is to have changes flow
bos@159 119 through a single shared central repository. This is also the
bos@159 120 most common ``building block'' for more ambitious workflow schemes.
bos@159 121
bos@159 122 Contributors start by cloning a copy of this repository. They can
bos@159 123 pull changes from it whenever they need to, and some (perhaps all)
bos@159 124 developers have permission to push a change back when they're ready
bos@159 125 for other people to see it.
bos@159 126
bos@179 127 Under this model, it can still often make sense for people to pull
bos@159 128 changes directly from each other, without going through the central
bos@159 129 repository. Consider a case in which I have a tentative bug fix, but
bos@159 130 I am worried that if I were to publish it to the central repository,
bos@159 131 it might subsequently break everyone else's trees as they pull it. To
bos@159 132 reduce the potential for damage, I can ask you to clone my repository
bos@159 133 into a temporary repository of your own and test it. This lets us put
bos@159 134 off publishing the potentially unsafe change until it has had a little
bos@159 135 testing.
bos@159 136
bos@159 137 In this kind of scenario, people usually use the \command{ssh}
bos@159 138 protocol to securely push changes to the central repository, as
bos@159 139 documented in section~\ref{sec:collab:ssh}. It's also usual to
bos@159 140 publish a read-only copy of the repository over HTTP using CGI, as in
bos@159 141 section~\ref{sec:collab:cgi}. Publishing over HTTP satisfies the
bos@159 142 needs of people who don't have push access, and those who want to use
bos@159 143 web browsers to browse the repository's history.
bos@159 144
bos@179 145 \subsection{Working with multiple branches}
bos@179 146
bos@179 147 Projects of any significant size naturally tend to make progress on
bos@179 148 several fronts simultaneously. In the case of software, it's common
bos@179 149 for a project to go through periodic official releases. A release
bos@179 150 might then go into ``maintenance mode'' for a while after its first
bos@179 151 publication; maintenance releases tend to contain only bug fixes, not
bos@179 152 new features. In parallel with these maintenance releases, one or
bos@179 153 more future releases may be under development. People normally use
bos@179 154 the word ``branch'' to refer to one of these many slightly different
bos@179 155 directions in which development is proceeding.
bos@179 156
bos@179 157 Mercurial is particularly well suited to managing a number of
bos@179 158 simultaneous, but not identical, branches. Each ``development
bos@179 159 direction'' can live in its own central repository, and you can merge
bos@179 160 changes from one to another as the need arises. Because repositories
bos@179 161 are independent of each other, unstable changes in a development
bos@179 162 branch will never affect a stable branch unless someone explicitly
bos@179 163 merges those changes in.
bos@179 164
bos@179 165 Here's an example of how this can work in practice. Let's say you
bos@179 166 have one ``main branch'' on a central server.
bos@179 167 \interaction{branching.init}
bos@179 168 People clone it, make changes locally, test them, and push them back.
bos@179 169
bos@179 170 Once the main branch reaches a release milestone, you can use the
bos@179 171 \hgcmd{tag} command to give a permanent name to the milestone
bos@179 172 revision.
bos@179 173 \interaction{branching.tag}
bos@179 174 Let's say some ongoing development occurs on the main branch.
bos@179 175 \interaction{branching.main}
bos@179 176 Using the tag that was recorded at the milestone, people who clone
bos@179 177 that repository at any time in the future can use \hgcmd{update} to
bos@179 178 get a copy of the working directory exactly as it was when that tagged
bos@179 179 revision was committed.
bos@179 180 \interaction{branching.update}
bos@179 181
bos@179 182 In addition, immediately after the main branch is tagged, someone can
bos@179 183 then clone the main branch on the server to a new ``stable'' branch,
bos@179 184 also on the server.
bos@179 185 \interaction{branching.clone}
bos@179 186
bos@179 187 Someone who needs to make a change to the stable branch can then clone
bos@179 188 \emph{that} repository, make their changes, commit, and push their
bos@179 189 changes back there.
bos@179 190 \interaction{branching.stable}
bos@179 191 Because Mercurial repositories are independent, and Mercurial doesn't
bos@179 192 move changes around automatically, the stable and main branches are
bos@179 193 \emph{isolated} from each other. The changes that you made on the
bos@179 194 main branch don't ``leak'' to the stable branch, and vice versa.
bos@179 195
bos@179 196 You'll often want all of your bugfixes on the stable branch to show up
bos@179 197 on the main branch, too. Rather than rewrite a bugfix on the main
bos@179 198 branch, you can simply pull and merge changes from the stable to the
bos@179 199 main branch, and Mercurial will bring those bugfixes in for you.
bos@179 200 \interaction{branching.merge}
bos@179 201 The main branch will still contain changes that are not on the stable
bos@179 202 branch, but it will also contain all of the bugfixes from the stable
bos@179 203 branch. The stable branch remains unaffected by these changes.
bos@179 204
bos@179 205 \subsection{Feature branches}
bos@179 206
bos@179 207 For larger projects, an effective way to manage change is to break up
bos@179 208 a team into smaller groups. Each group has a shared branch of its
bos@179 209 own, cloned from a single ``master'' branch used by the entire
bos@179 210 project. People working on an individual branch are typically quite
bos@179 211 isolated from developments on other branches.
bos@179 212
bos@179 213 \begin{figure}[ht]
bos@179 214 \centering
bos@179 215 \grafix{feature-branches}
bos@179 216 \caption{Feature branches}
bos@179 217 \label{fig:collab:feature-branches}
bos@179 218 \end{figure}
bos@179 219
bos@179 220 When a particular feature is deemed to be in suitable shape, someone
bos@179 221 on that feature team pulls and merges from the master branch into the
bos@179 222 feature branch, then pushes back up to the master branch.
bos@179 223
bos@179 224 \subsection{The release train}
bos@179 225
bos@179 226 Some projects are organised on a ``train'' basis: a release is
bos@179 227 scheduled to happen every few months, and whatever features are ready
bos@179 228 when the ``train'' is ready to leave are allowed in.
bos@179 229
bos@179 230 This model resembles working with feature branches. The difference is
bos@179 231 that when a feature branch misses a train, someone on the feature team
bos@184 232 pulls and merges the changes that went out on that train release into
bos@184 233 the feature branch, and the team continues its work on top of that
bos@184 234 release so that their feature can make the next release.
bos@179 235
bos@159 236 \subsection{The Linux kernel model}
bos@159 237
bos@159 238 The development of the Linux kernel has a shallow hierarchical
bos@159 239 structure, surrounded by a cloud of apparent chaos. Because most
bos@159 240 Linux developers use \command{git}, a distributed revision control
bos@159 241 tool with capabilities similar to Mercurial, it's useful to describe
bos@159 242 the way work flows in that environment; if you like the ideas, the
bos@159 243 approach translates well across tools.
bos@159 244
bos@159 245 At the center of the community sits Linus Torvalds, the creator of
bos@159 246 Linux. He publishes a single source repository that is considered the
bos@159 247 ``authoritative'' current tree by the entire developer community.
bos@159 248 Anyone can clone Linus's tree, but he is very choosy about whose trees
bos@159 249 he pulls from.
bos@159 250
bos@159 251 Linus has a number of ``trusted lieutenants''. As a general rule, he
bos@159 252 pulls whatever changes they publish, in most cases without even
bos@159 253 reviewing those changes. Some of those lieutenants are generally
bos@159 254 agreed to be ``maintainers'', responsible for specific subsystems
bos@159 255 within the kernel. If a random kernel hacker wants to make a change
bos@159 256 to a subsystem that they want to end up in Linus's tree, they must
bos@159 257 find out who the subsystem's maintainer is, and ask that maintainer to
bos@159 258 take their change. If the maintainer reviews their changes and agrees
bos@159 259 to take them, they'll pass them along to Linus in due course.
bos@159 260
bos@159 261 Individual lieutenants have their own approaches to reviewing,
bos@159 262 accepting, and publishing changes; and for deciding when to feed them
bos@159 263 to Linus. In addition, there are several well known branches that
bos@159 264 people use for different purposes. For example, a few people maintain
bos@159 265 ``stable'' repositories of older versions of the kernel, to which they
bos@184 266 apply critical fixes as needed. Some maintainers publish multiple
bos@184 267 trees: one for experimental changes; one for changes that they are
bos@184 268 about to feed upstream; and so on. Others just publish a single
bos@184 269 tree.
bos@159 270
bos@159 271 This model has two notable features. The first is that it's ``pull
bos@159 272 only''. You have to ask, convince, or beg another developer to take a
bos@184 273 change from you, because there are almost no trees to which more than
bos@184 274 one person can push, and there's no way to push changes into a tree
bos@184 275 that someone else controls.
bos@159 276
bos@159 277 The second is that it's based on reputation and acclaim. If you're an
bos@159 278 unknown, Linus will probably ignore changes from you without even
bos@159 279 responding. But a subsystem maintainer will probably review them, and
bos@159 280 will likely take them if they pass their criteria for suitability.
bos@159 281 The more ``good'' changes you contribute to a maintainer, the more
bos@159 282 likely they are to trust your judgment and accept your changes. If
bos@159 283 you're well-known and maintain a long-lived branch for something Linus
bos@159 284 hasn't yet accepted, people with similar interests may pull your
bos@159 285 changes regularly to keep up with your work.
bos@159 286
bos@159 287 Reputation and acclaim don't necessarily cross subsystem or ``people''
bos@159 288 boundaries. If you're a respected but specialised storage hacker, and
bos@159 289 you try to fix a networking bug, that change will receive a level of
bos@159 290 scrutiny from a network maintainer comparable to a change from a
bos@159 291 complete stranger.
bos@159 292
bos@159 293 To people who come from more orderly project backgrounds, the
bos@159 294 comparatively chaotic Linux kernel development process often seems
bos@159 295 completely insane. It's subject to the whims of individuals; people
bos@159 296 make sweeping changes whenever they deem it appropriate; and the pace
bos@159 297 of development is astounding. And yet Linux is a highly successful,
bos@159 298 well-regarded piece of software.
bos@159 299
bos@187 300 \subsection{Pull-only versus shared-push collaboration}
bos@187 301
bos@187 302 A perpetual source of heat in the open source community is whether a
bos@187 303 development model in which people only ever pull changes from others
bos@187 304 is ``better than'' one in which multiple people can push changes to a
bos@187 305 shared repository.
bos@187 306
bos@187 307 Typically, the backers of the shared-push model use tools that
bos@187 308 actively enforce this approach. If you're using a centralised
bos@187 309 revision control tool such as Subversion, there's no way to make a
bos@187 310 choice over which model you'll use: the tool gives you shared-push,
bos@187 311 and if you want to do anything else, you'll have to roll your own
bos@187 312 approach on top (such as applying a patch by hand).
bos@187 313
bos@187 314 A good distributed revision control tool, such as Mercurial, will
bos@187 315 support both models. You and your collaborators can then structure
bos@187 316 how you work together based on your own needs and preferences, not on
bos@187 317 what contortions your tools force you into.
bos@187 318
bos@187 319 \subsection{Where collaboration meets branch management}
bos@187 320
bos@187 321 Once you and your team set up some shared repositories and start
bos@187 322 propagating changes back and forth between local and shared repos, you
bos@187 323 begin to face a related, but slightly different challenge: that of
bos@187 324 managing the multiple directions in which your team may be moving at
bos@187 325 once. Even though this subject is intimately related to how your team
bos@187 326 collaborates, it's dense enough to merit treatment of its own, in
bos@187 327 chapter~\ref{chap:branch}.
bos@187 328
bos@159 329 \section{The technical side of sharing}
bos@159 330
bos@159 331 \subsection{Informal sharing with \hgcmd{serve}}
bos@159 332 \label{sec:collab:serve}
bos@159 333
bos@159 334 Mercurial's \hgcmd{serve} command is wonderfully suited to small,
bos@159 335 tight-knit, and fast-paced group environments. It also provides a
bos@159 336 great way to get a feel for using Mercurial commands over a network.
bos@159 337
bos@159 338 Run \hgcmd{serve} inside a repository, and in under a second it will
bos@159 339 bring up a specialised HTTP server; this will accept connections from
bos@159 340 any client, and serve up data for that repository until you terminate
bos@159 341 it. Anyone who knows the URL of the server you just started, and can
bos@159 342 talk to your computer over the network, can then use a web browser or
bos@159 343 Mercurial to read data from that repository. A URL for a
bos@159 344 \hgcmd{serve} instance running on a laptop is likely to look something
bos@159 345 like \Verb|http://my-laptop.local:8000/|.
bos@159 346
bos@159 347 The \hgcmd{serve} command is \emph{not} a general-purpose web server.
bos@159 348 It can do only two things:
bos@159 349 \begin{itemize}
bos@159 350 \item Allow people to browse the history of the repository it's
bos@159 351 serving, from their normal web browsers.
bos@159 352 \item Speak Mercurial's wire protocol, so that people can
bos@159 353 \hgcmd{clone} or \hgcmd{pull} changes from that repository.
bos@159 354 \end{itemize}
bos@159 355 In particular, \hgcmd{serve} won't allow remote users to \emph{modify}
bos@159 356 your repository. It's intended for read-only use.
bos@159 357
bos@159 358 If you're getting started with Mercurial, there's nothing to prevent
bos@159 359 you from using \hgcmd{serve} to serve up a repository on your own
bos@159 360 computer, then use commands like \hgcmd{clone}, \hgcmd{incoming}, and
bos@159 361 so on to talk to that server as if the repository was hosted remotely.
bos@159 362 This can help you to quickly get acquainted with using commands on
bos@159 363 network-hosted repositories.
bos@159 364
bos@159 365 \subsubsection{A few things to keep in mind}
bos@159 366
bos@159 367 Because it provides unauthenticated read access to all clients, you
bos@159 368 should only use \hgcmd{serve} in an environment where you either don't
bos@159 369 care, or have complete control over, who can access your network and
bos@159 370 pull data from your repository.
bos@159 371
bos@159 372 The \hgcmd{serve} command knows nothing about any firewall software
bos@159 373 you might have installed on your system or network. It cannot detect
bos@159 374 or control your firewall software. If other people are unable to talk
bos@159 375 to a running \hgcmd{serve} instance, the second thing you should do
bos@159 376 (\emph{after} you make sure that they're using the correct URL) is
bos@159 377 check your firewall configuration.
bos@159 378
bos@159 379 By default, \hgcmd{serve} listens for incoming connections on
bos@159 380 port~8000. If another process is already listening on the port you
bos@159 381 want to use, you can specify a different port to listen on using the
bos@159 382 \hgopt{serve}{-p} option.
bos@159 383
bos@159 384 Normally, when \hgcmd{serve} starts, it prints no output, which can be
bos@159 385 a bit unnerving. If you'd like to confirm that it is indeed running
bos@159 386 correctly, and find out what URL you should send to your
bos@159 387 collaborators, start it with the \hggopt{-v} option.
bos@159 388
bos@184 389 \subsection{Using the Secure Shell (ssh) protocol}
bos@159 390 \label{sec:collab:ssh}
bos@159 391
bos@184 392 You can pull and push changes securely over a network connection using
bos@184 393 the Secure Shell (\texttt{ssh}) protocol. To use this successfully,
bos@184 394 you may have to do a little bit of configuration on the client or
bos@184 395 server sides.
bos@184 396
bos@184 397 If you're not familiar with ssh, it's a network protocol that lets you
bos@184 398 securely communicate with another computer. To use it with Mercurial,
bos@184 399 you'll be setting up one or more user accounts on a server so that
bos@184 400 remote users can log in and execute commands.
bos@184 401
bos@184 402 (If you \emph{are} familiar with ssh, you'll probably find some of the
bos@184 403 material that follows to be elementary in nature.)
bos@184 404
bos@184 405 \subsubsection{How to read and write ssh URLs}
bos@184 406
bos@184 407 An ssh URL tends to look like this:
bos@184 408 \begin{codesample2}
bos@184 409 ssh://bos@hg.serpentine.com:22/hg/hgbook
bos@184 410 \end{codesample2}
bos@184 411 \begin{enumerate}
bos@184 412 \item The ``\texttt{ssh://}'' part tells Mercurial to use the ssh
bos@184 413 protocol.
bos@184 414 \item The ``\texttt{bos@}'' component indicates what username to log
bos@184 415 into the server as. You can leave this out if the remote username
bos@184 416 is the same as your local username.
bos@184 417 \item The ``\texttt{hg.serpentine.com}'' gives the hostname of the
bos@184 418 server to log into.
bos@184 419 \item The ``:22'' identifies the port number to connect to the server
bos@184 420 on. The default port is~22, so you only need to specify this part
bos@184 421 if you're \emph{not} using port~22.
bos@184 422 \item The remainder of the URL is the local path to the repository on
bos@184 423 the server.
bos@184 424 \end{enumerate}
bos@184 425
bos@184 426 There's plenty of scope for confusion with the path component of ssh
bos@184 427 URLs, as there is no standard way for tools to interpret it. Some
bos@184 428 programs behave differently than others when dealing with these paths.
bos@184 429 This isn't an ideal situation, but it's unlikely to change. Please
bos@184 430 read the following paragraphs carefully.
bos@184 431
bos@184 432 Mercurial treats the path to a repository on the server as relative to
bos@184 433 the remote user's home directory. For example, if user \texttt{foo}
bos@184 434 on the server has a home directory of \dirname{/home/foo}, then an ssh
bos@184 435 URL that contains a path component of \dirname{bar}
bos@184 436 \emph{really} refers to the directory \dirname{/home/foo/bar}.
bos@184 437
bos@184 438 If you want to specify a path relative to another user's home
bos@184 439 directory, you can use a path that starts with a tilde character
bos@184 440 followed by the user's name (let's call them \texttt{otheruser}), like
bos@184 441 this.
bos@184 442 \begin{codesample2}
bos@184 443 ssh://server/~otheruser/hg/repo
bos@184 444 \end{codesample2}
bos@184 445
bos@184 446 And if you really want to specify an \emph{absolute} path on the
bos@184 447 server, begin the path component with two slashes, as in this example.
bos@184 448 \begin{codesample2}
bos@184 449 ssh://server//absolute/path
bos@184 450 \end{codesample2}
bos@184 451
bos@184 452 \subsubsection{Finding an ssh client for your system}
bos@184 453
bos@184 454 Almost every Unix-like system comes with OpenSSH preinstalled. If
bos@184 455 you're using such a system, run \Verb|which ssh| to find out if
bos@184 456 the \command{ssh} command is installed (it's usually in
bos@184 457 \dirname{/usr/bin}). In the unlikely event that it isn't present,
bos@184 458 take a look at your system documentation to figure out how to install
bos@184 459 it.
bos@184 460
bos@184 461 On Windows, you'll first need to choose download a suitable ssh
bos@184 462 client. There are two alternatives.
bos@184 463 \begin{itemize}
bos@184 464 \item Simon Tatham's excellent PuTTY package~\cite{web:putty} provides
bos@184 465 a complete suite of ssh client commands.
bos@184 466 \item If you have a high tolerance for pain, you can use the Cygwin
bos@184 467 port of OpenSSH.
bos@184 468 \end{itemize}
bos@184 469 In either case, you'll need to edit your \hgini\ file to tell
bos@184 470 Mercurial where to find the actual client command. For example, if
bos@184 471 you're using PuTTY, you'll need to use the \command{plink} command as
bos@184 472 a command-line ssh client.
bos@184 473 \begin{codesample2}
bos@184 474 [ui]
bos@184 475 ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"
bos@184 476 \end{codesample2}
bos@184 477
bos@184 478 \begin{note}
bos@184 479 The path to \command{plink} shouldn't contain any whitespace
bos@184 480 characters, or Mercurial may not be able to run it correctly (so
bos@184 481 putting it in \dirname{C:\\Program Files} is probably not be a good
bos@184 482 idea).
bos@184 483 \end{note}
bos@184 484
bos@184 485 \subsubsection{Generating a key pair}
bos@184 486
bos@184 487 To avoid the need to repetitively type a password every time you need
bos@184 488 to use your ssh client, I recommend generating a key pair. On a
bos@184 489 Unix-like system, the \command{ssh-keygen} command will do the trick.
bos@184 490 On Windows, if you're using PuTTY, the \command{puttygen} command is
bos@184 491 what you'll need.
bos@184 492
bos@184 493 When you generate a key pair, it's usually \emph{highly} advisable to
bos@184 494 protect it with a passphrase. (The only time that you might not want
bos@184 495 to do this id when you're using the ssh protocol for automated tasks
bos@184 496 on a secure network.)
bos@184 497
bos@184 498 Simply generating a key pair isn't enough, however. You'll need to
bos@184 499 add the public key to the set of authorised keys for whatever user
bos@184 500 you're logging in remotely as. For servers using OpenSSH (the vast
bos@184 501 majority), this will mean adding the public key to a list in a file
bos@184 502 called \sfilename{authorized\_keys} in their \sdirname{.ssh}
bos@184 503 directory.
bos@184 504
bos@184 505 On a Unix-like system, your public key will have a \filename{.pub}
bos@184 506 extension. If you're using \command{puttygen} on Windows, you can
bos@184 507 save the public key to a file of your choosing, or paste it from the
bos@184 508 window it's displayed in straight into the
bos@184 509 \sfilename{authorized\_keys} file.
bos@184 510
bos@184 511 \subsubsection{Using an authentication agent}
bos@184 512
bos@184 513 An authentication agent is a daemon that stores passphrases in memory
bos@184 514 (so it will forget passphrases if you log out and log back in again).
bos@184 515 An ssh client will notice if it's running, and query it for a
bos@184 516 passphrase. If there's no authentication agent running, or the agent
bos@184 517 doesn't store the necessary passphrase, you'll have to type your
bos@184 518 passphrase every time Mercurial tries to communicate with a server on
bos@184 519 your behalf (e.g.~whenever you pull or push changes).
bos@184 520
bos@184 521 The downside of storing passphrases in an agent is that it's possible
bos@184 522 for a well-prepared attacker to recover the plain text of your
bos@184 523 passphrases, in some cases even if your system has been power-cycled.
bos@184 524 You should make your own judgment as to whether this is an acceptable
bos@184 525 risk. It certainly saves a lot of repeated typing.
bos@184 526
bos@184 527 On Unix-like systems, the agent is called \command{ssh-agent}, and
bos@184 528 it's often run automatically for you when you log in. You'll need to
bos@184 529 use the \command{ssh-add} command to add passphrases to the agent's
bos@184 530 store. On Windows, if you're using PuTTY, the \command{pageant}
bos@184 531 command acts as the agent. It adds an icon to your system tray that
bos@184 532 will let you manage stored passphrases.
bos@184 533
bos@184 534 \subsubsection{Configuring the server side properly}
bos@184 535
bos@184 536 Because ssh can be fiddly to set up if you're new to it, there's a
bos@184 537 variety of things that can go wrong. Add Mercurial on top, and
bos@184 538 there's plenty more scope for head-scratching. Most of these
bos@184 539 potential problems occur on the server side, not the client side. The
bos@184 540 good news is that once you've gotten a configuration working, it will
bos@184 541 usually continue to work indefinitely.
bos@184 542
bos@184 543 Before you try using Mercurial to talk to an ssh server, it's best to
bos@184 544 make sure that you can use the normal \command{ssh} or \command{putty}
bos@184 545 command to talk to the server first. If you run into problems with
bos@184 546 using these commands directly, Mercurial surely won't work. Worse, it
bos@184 547 will obscure the underlying problem. Any time you want to debug
bos@184 548 ssh-related Mercurial problems, you should drop back to making sure
bos@184 549 that plain ssh client commands work first, \emph{before} you worry
bos@184 550 about whether there's a problem with Mercurial.
bos@184 551
bos@184 552 The first thing to be sure of on the server side is that you can
bos@184 553 actually log in from another machine at all. If you can't use
bos@184 554 \command{ssh} or \command{putty} to log in, the error message you get
bos@184 555 may give you a few hints as to what's wrong. The most common problems
bos@184 556 are as follows.
bos@184 557 \begin{itemize}
bos@184 558 \item If you get a ``connection refused'' error, either there isn't an
bos@184 559 SSH daemon running on the server at all, or it's inaccessible due to
bos@184 560 firewall configuration.
bos@184 561 \item If you get a ``no route to host'' error, you either have an
bos@184 562 incorrect address for the server or a seriously locked down firewall
bos@184 563 that won't admit its existence at all.
bos@184 564 \item If you get a ``permission denied'' error, you may have mistyped
bos@184 565 the username on the server, or you could have mistyped your key's
bos@184 566 passphrase or the remote user's password.
bos@184 567 \end{itemize}
bos@184 568 In summary, if you're having trouble talking to the server's ssh
bos@184 569 daemon, first make sure that one is running at all. On many systems
bos@184 570 it will be installed, but disabled, by default. Once you're done with
bos@184 571 this step, you should then check that the server's firewall is
bos@184 572 configured to allow incoming connections on the port the ssh daemon is
bos@184 573 listening on (usually~22). Don't worry about more exotic
bos@184 574 possibilities for misconfiguration until you've checked these two
bos@184 575 first.
bos@184 576
bos@184 577 If you're using an authentication agent on the client side to store
bos@184 578 passphrases for your keys, you ought to be able to log into the server
bos@184 579 without being prompted for a passphrase or a password. If you're
bos@184 580 prompted for a passphrase, there are a few possible culprits.
bos@184 581 \begin{itemize}
bos@184 582 \item You might have forgotten to use \command{ssh-add} or
bos@184 583 \command{pageant} to store the passphrase.
bos@184 584 \item You might have stored the passphrase for the wrong key.
bos@184 585 \end{itemize}
bos@184 586 If you're being prompted for the remote user's password, there are
bos@184 587 another few possible problems to check.
bos@184 588 \begin{itemize}
bos@184 589 \item Either the user's home directory or their \sdirname{.ssh}
bos@184 590 directory might have excessively liberal permissions. As a result,
bos@184 591 the ssh daemon will not trust or read their
bos@184 592 \sfilename{authorized\_keys} file. For example, a group-writable
bos@184 593 home or \sdirname{.ssh} directory will often cause this symptom.
bos@184 594 \item The user's \sfilename{authorized\_keys} file may have a problem.
bos@184 595 If anyone other than the user owns or can write to that file, the
bos@184 596 ssh daemon will not trust or read it.
bos@184 597 \end{itemize}
bos@184 598
bos@184 599 In the ideal world, you should be able to run the following command
bos@184 600 successfully, and it should print exactly one line of output, the
bos@184 601 current date and time.
bos@184 602 \begin{codesample2}
bos@184 603 ssh myserver date
bos@184 604 \end{codesample2}
bos@184 605
bos@209 606 If, on your server, you have login scripts that print banners or other
bos@184 607 junk even when running non-interactive commands like this, you should
bos@184 608 fix them before you continue, so that they only print output if
bos@184 609 they're run interactively. Otherwise these banners will at least
bos@184 610 clutter up Mercurial's output. Worse, they could potentially cause
bos@209 611 problems with running Mercurial commands remotely. Mercurial makes
bos@209 612 tries to detect and ignore banners in non-interactive \command{ssh}
bos@209 613 sessions, but it is not foolproof. (If you're editing your login
bos@209 614 scripts on your server, the usual way to see if a login script is
bos@209 615 running in an interactive shell is to check the return code from the
bos@209 616 command \Verb|tty -s|.)
bos@184 617
bos@184 618 Once you've verified that plain old ssh is working with your server,
bos@184 619 the next step is to ensure that Mercurial runs on the server. The
bos@184 620 following command should run successfully:
bos@184 621 \begin{codesample2}
bos@184 622 ssh myserver hg version
bos@184 623 \end{codesample2}
bos@184 624 If you see an error message instead of normal \hgcmd{version} output,
bos@184 625 this is usually because you haven't installed Mercurial to
bos@184 626 \dirname{/usr/bin}. Don't worry if this is the case; you don't need
bos@184 627 to do that. But you should check for a few possible problems.
bos@184 628 \begin{itemize}
bos@184 629 \item Is Mercurial really installed on the server at all? I know this
bos@184 630 sounds trivial, but it's worth checking!
bos@184 631 \item Maybe your shell's search path (usually set via the \envar{PATH}
bos@184 632 environment variable) is simply misconfigured.
bos@184 633 \item Perhaps your \envar{PATH} environment variable is only being set
bos@184 634 to point to the location of the \command{hg} executable if the login
bos@184 635 session is interactive. This can happen if you're setting the path
bos@184 636 in the wrong shell login script. See your shell's documentation for
bos@184 637 details.
bos@184 638 \item The \envar{PYTHONPATH} environment variable may need to contain
bos@184 639 the path to the Mercurial Python modules. It might not be set at
bos@184 640 all; it could be incorrect; or it may be set only if the login is
bos@184 641 interactive.
bos@184 642 \end{itemize}
bos@184 643
bos@184 644 If you can run \hgcmd{version} over an ssh connection, well done!
bos@184 645 You've got the server and client sorted out. You should now be able
bos@184 646 to use Mercurial to access repositories hosted by that username on
bos@184 647 that server. If you run into problems with Mercurial and ssh at this
bos@184 648 point, try using the \hggopt{--debug} option to get a clearer picture
bos@184 649 of what's going on.
bos@184 650
bos@184 651 \subsubsection{Using compression with ssh}
bos@184 652
bos@184 653 Mercurial does not compress data when it uses the ssh protocol,
bos@184 654 because the ssh protocol can transparently compress data. However,
bos@184 655 the default behaviour of ssh clients is \emph{not} to request
bos@184 656 compression.
bos@184 657
bos@184 658 Over any network other than a fast LAN (even a wireless network),
bos@184 659 using compression is likely to significantly speed up Mercurial's
bos@184 660 network operations. For example, over a WAN, someone measured
bos@184 661 compression as reducing the amount of time required to clone a
bos@184 662 particularly large repository from~51 minutes to~17 minutes.
bos@184 663
bos@184 664 Both \command{ssh} and \command{plink} accept a \cmdopt{ssh}{-C}
bos@184 665 option which turns on compression. You can easily edit your \hgrc\ to
bos@184 666 enable compression for all of Mercurial's uses of the ssh protocol.
bos@184 667 \begin{codesample2}
bos@184 668 [ui]
bos@184 669 ssh = ssh -C
bos@184 670 \end{codesample2}
bos@184 671
bos@209 672 If you use \command{ssh}, you can configure it to always use
bos@209 673 compression when talking to your server. To do this, edit your
bos@209 674 \sfilename{.ssh/config} file (which may not yet exist), as follows.
bos@209 675 \begin{codesample2}
bos@209 676 Host hg
bos@209 677 Compression yes
bos@209 678 HostName hg.example.com
bos@209 679 \end{codesample2}
bos@209 680 This defines an alias, \texttt{hg}. When you use it on the
bos@209 681 \command{ssh} command line or in a Mercurial \texttt{ssh}-protocol
bos@209 682 URL, it will cause \command{ssh} to connect to \texttt{hg.example.com}
bos@209 683 and use compression. This gives you both a shorter name to type and
bos@209 684 compression, each of which is a good thing in its own right.
bos@209 685
bos@184 686 \subsection{Serving over HTTP with a CGI script}
bos@159 687 \label{sec:collab:cgi}
bos@159 688
bos@159 689
bos@159 690
bos@159 691 %%% Local Variables:
bos@159 692 %%% mode: latex
bos@159 693 %%% TeX-master: "00book"
bos@159 694 %%% End: