annotate en/ch06-collab.xml @ 659:dbe91bb622d8

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