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