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