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