annotate en/ch05-collab.xml @ 773:3b640272a966

Progres on resolve
author Bryan O'Sullivan <bos@serpentine.com>
date Sun, 12 Apr 2009 00:05:30 -0700
parents b338f5490029
children e6c99cbd0abd 83540574ee49
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">
671
13513d2a128d Add sensible names to chapters.
Bryan O'Sullivan <bos@serpentine.com>
parents: 666
diff changeset
4 <?dbhtml filename="collaborating-with-other-people.html"?>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
5 <title>Collaborating with other people</title>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
6
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
7 <para id="x_44a">As a completely decentralised tool, Mercurial doesn't impose
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
8 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
9 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
10 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
11 possible workflow models.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
12
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
13 <sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
14 <title>Mercurial's web interface</title>
209
8b599dcca584 Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents: 187
diff changeset
15
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
16 <para id="x_44b">Mercurial has a powerful web interface that provides several
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
17 useful capabilities.</para>
209
8b599dcca584 Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents: 187
diff changeset
18
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
19 <para id="x_44c">For interactive use, the web interface lets you browse a
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
20 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
21 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
22 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
23
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
24 <para id="x_44d">Also for human consumption, the web interface provides an
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
25 RSS feed of the changes in a repository. This lets you
773
3b640272a966 Progres on resolve
Bryan O'Sullivan <bos@serpentine.com>
parents: 771
diff changeset
26 <quote>subscribe</quote> to a repository using your favorite
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
27 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
28 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
29 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
30 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
31 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
32 repository.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
33
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
34 <para id="x_44e">The web interface also lets remote users clone a repository,
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
35 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
36 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
37 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
38 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
39
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
40 <para id="x_44f">The easiest way to get started with the web interface is to
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
41 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
42 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
43 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
44
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
45 <para id="x_450">If you're interested in providing a web interface
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
46 to your own repositories, Mercurial provides two ways to do
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
47 this. The first is using the <command role="hg-cmd">hg
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
48 serve</command> command, which is best suited to short-term
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
49 <quote>lightweight</quote> serving. See <xref
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
50 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
51 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
52 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
53 support for the CGI (Common Gateway Interface) standard, which
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
54 all common web servers support. See <xref
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
55 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
56 configuration.</para>
209
8b599dcca584 Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents: 187
diff changeset
57
658
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 <sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
60 <title>Collaboration models</title>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
61
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
62 <para id="x_451">With a suitably flexible tool, making decisions about
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
63 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
64 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
65 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
66 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
67 particular needs.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
68
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
69 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
70 <title>Factors to keep in mind</title>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
71
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
72 <para id="x_452">The most important aspect of any model that you must keep
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
73 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
74 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
75 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
76 a moment.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
77
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
78 <para id="x_453">I once put together a workflow model that seemed to make
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
79 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
80 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
81 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
82 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
83 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
84 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
85 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
86 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
87
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
88 <para id="x_454">Don't sweep foreseeable social or technical problems under
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
89 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
90 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
91 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
92 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
93 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
94 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
95 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
96 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
97 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
98 branch.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
99
658
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 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
102 <title>Informal anarchy</title>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
103
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
104 <para id="x_455">I wouldn't suggest an <quote>anything goes</quote>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
105 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
106 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
107 situations.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
108
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
109 <para id="x_456">As one example, many projects have a loose-knit group of
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
110 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
111 groups like to overcome the isolation of working at a distance
773
3b640272a966 Progres on resolve
Bryan O'Sullivan <bos@serpentine.com>
parents: 771
diff changeset
112 by organizing occasional <quote>sprints</quote>. In a sprint,
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
113 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
114 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
115 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
116 hacking intensely on a handful of projects.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
117
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
118 <para id="x_457">A sprint is the perfect place to use the
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
119 <command role="hg-cmd">hg serve</command> command, since
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
120 <command role="hg-cmd">hg serve</command> does not require any
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
121 fancy server infrastructure. You can get started with
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
122 <command role="hg-cmd">hg serve</command> in moments, by
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
123 reading <xref linkend="sec:collab:serve"/> below. Then simply
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
124 tell the person next to you that you're running a server, send
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
125 the URL to them in an instant message, and you immediately
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
126 have a quick-turnaround way to work together. They can type
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
127 your URL into their web browser and quickly review your
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
128 changes; or they can pull a bugfix from you and verify it; or
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
129 they can clone a branch containing a new feature and try it
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
130 out.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
131
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
132 <para id="x_458">The charm, and the problem, with doing things in an ad hoc
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
133 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
134 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
135 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
136 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
137 to pull from.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
138
658
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 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
141 <title>A single central repository</title>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
142
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
143 <para id="x_459">For smaller projects migrating from a centralised revision
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
144 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
145 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
146 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
147 more ambitious workflow schemes.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
148
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
149 <para id="x_45a">Contributors start by cloning a copy of this repository.
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
150 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
151 (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
152 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
153
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
154 <para id="x_45b">Under this model, it can still often make sense for people
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
155 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
156 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
157 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
158 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
159 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
160 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
161 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
162 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
163 it has had a little testing.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
164
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
165 <para id="x_45c">In this kind of scenario, people usually use
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
166 the <command>ssh</command> protocol to securely push changes
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
167 to the central repository, as documented in <xref
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
168 linkend="sec:collab:ssh"/>. It's also usual to publish a
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
169 read-only copy of the repository over HTTP using CGI, as in
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
170 <xref linkend="sec:collab:cgi"/>. Publishing
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
171 over HTTP satisfies the needs of people who don't have push
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
172 access, and those who want to use web browsers to browse the
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
173 repository's 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
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
179 <para id="x_45d">Projects of any significant size naturally tend to make
658
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
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
192 <para id="x_45e">Mercurial is particularly well suited to managing a number
658
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
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
201 <para id="x_45f">Here's an example of how this can work in practice. Let's
658
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
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
203 server.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
204
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
205 &interaction.branching.init;
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
206
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
207 <para id="x_460">People clone it, make changes locally, test them, and push
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
208 them back.</para>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
209
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
210 <para id="x_461">Once the main branch reaches a release milestone, you can
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
211 use the <command role="hg-cmd">hg tag</command> command to
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
212 give a permanent name to the milestone revision.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
213
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
214 &interaction.branching.tag;
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
215
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
216 <para id="x_462">Let's say some ongoing
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
217 development occurs on the main branch.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
218
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
219 &interaction.branching.main;
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
220
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
221 <para id="x_463">Using the tag that was recorded at the milestone, people
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
222 who clone that repository at any time in the future can use
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
223 <command role="hg-cmd">hg update</command> to get a copy of
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
224 the working directory exactly as it was when that tagged
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
225 revision was committed.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
226
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
227 &interaction.branching.update;
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
228
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
229 <para id="x_464">In addition, immediately after the main branch is tagged,
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
230 someone can then clone the main branch on the server to a new
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
231 <quote>stable</quote> branch, also on the server.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
232
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
233 &interaction.branching.clone;
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
234
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
235 <para id="x_465">Someone who needs to make a change to the stable branch
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
236 can then clone <emphasis>that</emphasis> repository, make
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
237 their changes, commit, and push their changes back there.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
238
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
239 &interaction.branching.stable;
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
240
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
241 <para id="x_466">Because Mercurial repositories are independent, and
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
242 Mercurial doesn't move changes around automatically, the
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
243 stable and main branches are <emphasis>isolated</emphasis>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
244 from each other. The changes that you made on the main branch
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
245 don't <quote>leak</quote> to the stable branch, and vice
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
246 versa.</para>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
247
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
248 <para id="x_467">You'll often want all of your bugfixes on the stable
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
249 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
250 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
251 merge changes from the stable to the main branch, and
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
252 Mercurial will bring those bugfixes in for you.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
253
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
254 &interaction.branching.merge;
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
255
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
256 <para id="x_468">The main branch will still contain changes that are not on
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
257 the stable branch, but it will also contain all of the
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
258 bugfixes from the stable branch. The stable branch remains
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
259 unaffected by these changes.</para>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
260
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
261 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
262 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
263 <title>Feature branches</title>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
264
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
265 <para id="x_469">For larger projects, an effective way to manage change is
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
266 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
267 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
268 <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
269 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
270 isolated from developments on other branches.</para>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
271
690
b788b405e141 Replace uses of <informalfigure> with <figure>
Bryan O'Sullivan <bos@serpentine.com>
parents: 683
diff changeset
272 <figure id="fig:collab:feature-branches">
b788b405e141 Replace uses of <informalfigure> with <figure>
Bryan O'Sullivan <bos@serpentine.com>
parents: 683
diff changeset
273 <title>Feature branches</title>
b788b405e141 Replace uses of <informalfigure> with <figure>
Bryan O'Sullivan <bos@serpentine.com>
parents: 683
diff changeset
274 <mediaobject>
754
65e9a18d2c7e Shrink large images to fit page
Dongsheng Song <dongsheng.song@gmail.com>
parents: 753
diff changeset
275 <imageobject><imagedata width="100%" fileref="figs/feature-branches.png"/></imageobject>
690
b788b405e141 Replace uses of <informalfigure> with <figure>
Bryan O'Sullivan <bos@serpentine.com>
parents: 683
diff changeset
276 <textobject><phrase>XXX add text</phrase></textobject>
b788b405e141 Replace uses of <informalfigure> with <figure>
Bryan O'Sullivan <bos@serpentine.com>
parents: 683
diff changeset
277 </mediaobject>
b788b405e141 Replace uses of <informalfigure> with <figure>
Bryan O'Sullivan <bos@serpentine.com>
parents: 683
diff changeset
278 </figure>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
279
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
280 <para id="x_46b">When a particular feature is deemed to be in suitable
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
281 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
282 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
283 the master branch.</para>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
284
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
285 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
286 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
287 <title>The release train</title>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
288
773
3b640272a966 Progres on resolve
Bryan O'Sullivan <bos@serpentine.com>
parents: 771
diff changeset
289 <para id="x_46c">Some projects are organized on a <quote>train</quote>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
290 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
291 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
292 ready to leave are allowed in.</para>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
293
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
294 <para id="x_46d">This model resembles working with feature branches. The
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
295 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
296 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
297 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
298 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
299 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
300
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
301 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
302 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
303 <title>The Linux kernel model</title>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
304
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
305 <para id="x_46e">The development of the Linux kernel has a shallow
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
306 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
307 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
308 <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
309 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
310 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
311 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
312
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
313 <para id="x_46f">At the center of the community sits Linus Torvalds, the
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
314 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
315 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
316 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
317 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
318 from.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
319
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
320 <para id="x_470">Linus has a number of <quote>trusted lieutenants</quote>.
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
321 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
322 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
323 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
324 <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
325 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
326 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
327 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
328 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
329 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
330 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
331
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
332 <para id="x_471">Individual lieutenants have their own approaches to
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
333 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
334 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
335 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
336 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
337 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
338 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
339 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
340 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
341 publish a single tree.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
342
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
343 <para id="x_472">This model has two notable features. The first is that
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
344 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
345 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
346 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
347 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
348 else controls.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
349
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
350 <para id="x_473">The second is that it's based on reputation and acclaim.
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
351 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
352 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
353 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
354 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
355 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
356 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
357 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
358 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
359 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
360
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
361 <para id="x_474">Reputation and acclaim don't necessarily cross subsystem
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
362 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
363 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
364 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
365 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
366 complete stranger.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
367
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
368 <para id="x_475">To people who come from more orderly project backgrounds,
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
369 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
370 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
371 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
372 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
373 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
374 software.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
375
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
376 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
377 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
378 <title>Pull-only versus shared-push collaboration</title>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
379
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
380 <para id="x_476">A perpetual source of heat in the open source community is
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
381 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
382 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
383 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
384 repository.</para>
187
b60e2de6dbc3 Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents: 184
diff changeset
385
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
386 <para id="x_477">Typically, the backers of the shared-push model use tools
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
387 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
388 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
389 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
390 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
391 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
392 a patch by hand).</para>
187
b60e2de6dbc3 Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents: 184
diff changeset
393
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
394 <para id="x_478">A good distributed revision control tool, such as
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
395 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
396 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
397 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
398 your tools force you into.</para>
187
b60e2de6dbc3 Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents: 184
diff changeset
399
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
400 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
401 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
402 <title>Where collaboration meets branch management</title>
187
b60e2de6dbc3 Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents: 184
diff changeset
403
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
404 <para id="x_479">Once you and your team set up some shared
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
405 repositories and start propagating changes back and forth
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
406 between local and shared repos, you begin to face a related,
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
407 but slightly different challenge: that of managing the
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
408 multiple directions in which your team may be moving at once.
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
409 Even though this subject is intimately related to how your
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
410 team collaborates, it's dense enough to merit treatment of its
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
411 own, in <xref linkend="chap:branch"/>.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
412
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
413 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
414 </sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
415 <sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
416 <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
417
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
418 <para id="x_47a">The remainder of this chapter is devoted to the question of
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
419 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
420
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
421 </sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
422 <sect1 id="sec:collab:serve">
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
423 <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
424 serve</command></title>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
425
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
426 <para id="x_47b">Mercurial's <command role="hg-cmd">hg serve</command>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
427 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
428 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
429 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
430
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
431 <para id="x_47c">Run <command role="hg-cmd">hg serve</command> inside a
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
432 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
433 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
434 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
435 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
436 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
437 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
438 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
439 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
440 <literal>http://my-laptop.local:8000/</literal>.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
441
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
442 <para id="x_47d">The <command role="hg-cmd">hg serve</command> command is
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
443 <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
444 only two things:</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
445 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
446 <listitem><para id="x_47e">Allow people to browse the history of the
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
447 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
448 browsers.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
449 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
450 <listitem><para id="x_47f">Speak Mercurial's wire protocol, so that people
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
451 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
452 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
453 repository.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
454 </listitem></itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
455 <para id="x_480">In particular, <command role="hg-cmd">hg serve</command>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
456 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
457 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
458
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
459 <para id="x_481">If you're getting started with Mercurial, there's nothing to
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
460 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
461 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
462 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
463 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
464 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
465 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
466 network-hosted repositories.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
467
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
468 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
469 <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
470
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
471 <para id="x_482">Because it provides unauthenticated read access to all
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
472 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
473 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
474 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
475 network and pull data from your repository.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
476
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
477 <para id="x_483">The <command role="hg-cmd">hg serve</command> command
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
478 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
479 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
480 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
481 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
482 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
483 (<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
484 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
485
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
486 <para id="x_484">By default, <command role="hg-cmd">hg serve</command>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
487 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
488 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
489 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
490 role="hg-opt-serve">-p</option> option.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
491
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
492 <para id="x_485">Normally, when <command role="hg-cmd">hg serve</command>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
493 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
494 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
495 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
496 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
497 option.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
498
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
499 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
500 </sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
501 <sect1 id="sec:collab:ssh">
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
502 <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
503
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
504 <para id="x_486">You can pull and push changes securely over a network
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
505 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
506 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
507 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
508
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
509 <para id="x_487">If you're not familiar with ssh, it's a network protocol
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
510 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
511 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
512 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
513 commands.</para>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
514
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
515 <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
516 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
517 in nature.)</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
518
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
519 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
520 <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
521
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
522 <para id="x_489">An ssh URL tends to look like this:</para>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
523 <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
524 <orderedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
525 <listitem><para id="x_48a">The <quote><literal>ssh://</literal></quote>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
526 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
527 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
528 <listitem><para id="x_48b">The <quote><literal>bos@</literal></quote>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
529 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
530 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
531 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
532 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
533 <listitem><para id="x_48c">The
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
534 <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
535 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
536 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
537 <listitem><para id="x_48d">The <quote>:22</quote> identifies the port
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
538 number to connect to the server on. The default port is
679
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
539 22, so you only need to specify a colon and port number if
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
540 you're <emphasis>not</emphasis> using port 22.</para>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
541 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
542 <listitem><para id="x_48e">The remainder of the URL is the local path to
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
543 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
544 </listitem></orderedlist>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
545
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
546 <para id="x_48f">There's plenty of scope for confusion with the path
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
547 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
548 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
549 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
550 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
551 paragraphs carefully.</para>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
552
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
553 <para id="x_490">Mercurial treats the path to a repository on the server as
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
554 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
555 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
556 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
557 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
558 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
559 refers to the directory <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
560 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
561
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
562 <para id="x_491">If you want to specify a path relative to another user's
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
563 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
564 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
565 <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
566 <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
567
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
568 <para id="x_492">And if you really want to specify an
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
569 <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
570 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
571 <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
572
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
573 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
574 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
575 <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
576
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
577 <para id="x_493">Almost every Unix-like system comes with OpenSSH
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
578 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
579 <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
580 <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
581 <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
582 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
583 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
584
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
585 <para id="x_494">On Windows, you'll first need to download a suitable ssh
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
586 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
587 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
588 <listitem><para id="x_495">Simon Tatham's excellent PuTTY package
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
589 <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
590 of ssh client commands.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
591 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
592 <listitem><para id="x_496">If you have a high tolerance for pain, you can
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
593 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
594 </listitem></itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
595 <para id="x_497">In either case, you'll need to edit your <filename
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
596 role="special">hg.ini</filename> file to
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
597 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
598 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
599 <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
600 client.</para>
679
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
601 <programlisting>[ui]
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
602 ssh = C:/path/to/plink.exe -ssh -i "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
603
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
604 <note>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
605 <para id="x_498"> The path to <command>plink</command> shouldn't contain
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
606 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
607 run it correctly (so putting it in <filename
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
608 class="directory">C:\Program Files</filename> is probably
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
609 not a good idea).</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
610 </note>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
611
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
612 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
613 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
614 <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
615
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
616 <para id="x_499">To avoid the need to repetitively type a password every
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
617 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
618 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
619 <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
620 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
621 <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
622 need.</para>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
623
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
624 <para id="x_49a">When you generate a key pair, it's usually
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
625 <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
626 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
627 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
628 secure network.)</para>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
629
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
630 <para id="x_49b">Simply generating a key pair isn't enough, however.
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
631 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
632 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
633 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
634 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
635 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
636 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
637 directory.</para>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
638
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
639 <para id="x_49c">On a Unix-like system, your public key will have a
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
640 <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
641 <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
642 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
643 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
644 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
645
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
646 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
647 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
648 <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
649
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
650 <para id="x_49d">An authentication agent is a daemon that stores
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
651 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
652 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
653 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
654 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
655 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
656 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
657 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
658
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
659 <para id="x_49e">The downside of storing passphrases in an agent is that
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
660 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
661 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
662 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
663 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
664 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
665
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
666 <para id="x_49f">On Unix-like systems, the agent is called
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
667 <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
668 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
669 <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
670 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
671 <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
672 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
673 passphrases.</para>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
674
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
675 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
676 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
677 <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
678
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
679 <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
680 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
681 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
682 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
683 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
684 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
685 indefinitely.</para>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
686
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
687 <para id="x_4a1">Before you try using Mercurial to talk to an ssh server,
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
688 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
689 <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
690 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
691 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
692 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
693 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
694 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
695 <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
696 problem with Mercurial.</para>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
697
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
698 <para id="x_4a2">The first thing to be sure of on the server side is that
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
699 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
700 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
701 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
702 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
703 follows.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
704 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
705 <listitem><para id="x_4a3">If you get a <quote>connection refused</quote>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
706 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
707 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
708 configuration.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
709 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
710 <listitem><para id="x_4a4">If you get a <quote>no route to host</quote>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
711 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
712 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
713 existence at all.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
714 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
715 <listitem><para id="x_4a5">If you get a <quote>permission denied</quote>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
716 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
717 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
718 remote user's password.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
719 </listitem></itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
720 <para id="x_4a6">In summary, if you're having trouble talking to the
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
721 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
722 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
723 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
724 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
725 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
726 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
727 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
728 first.</para>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
729
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
730 <para id="x_4a7">If you're using an authentication agent on the client side
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
731 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
732 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
733 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
734 few possible culprits.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
735 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
736 <listitem><para id="x_4a8">You might have forgotten to use
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
737 <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
738 to store the passphrase.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
739 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
740 <listitem><para id="x_4a9">You might have stored the passphrase for the
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
741 wrong key.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
742 </listitem></itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
743 <para id="x_4aa">If you're being prompted for the remote user's password,
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
744 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
745 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
746 <listitem><para id="x_4ab">Either the user's home directory or their
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
747 <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
748 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
749 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
750 <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
751 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
752 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
753 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
754 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
755 <listitem><para id="x_4ac">The user's <filename
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
756 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
757 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
758 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
759 it.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
760 </listitem></itemizedlist>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
761
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
762 <para id="x_4ad">In the ideal world, you should be able to run the
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
763 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
764 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
765 <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
766
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
767 <para id="x_4ae">If, on your server, you have login scripts that print
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
768 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
769 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
770 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
771 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
772 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
773 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
774 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
775 <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
776 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
777 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
778 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
779 <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
780
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
781 <para id="x_4af">Once you've verified that plain old ssh is working with
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
782 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
783 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
784 successfully:</para>
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
785
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
786 <programlisting>ssh myserver hg version</programlisting>
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
787
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
788 <para id="x_4b0">If you see an error message instead of normal <command
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
789 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
790 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
791 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
792 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
793 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
794 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
795 <listitem><para id="x_4b1">Is Mercurial really installed on the server at
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
796 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
797 checking!</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
798 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
799 <listitem><para id="x_4b2">Maybe your shell's search path (usually set
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
800 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
801 simply misconfigured.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
802 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
803 <listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
804 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
805 <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
806 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
807 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
808 documentation for details.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
809 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
810 <listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
811 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
812 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
813 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
814 interactive.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
815 </listitem></itemizedlist>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
816
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
817 <para id="x_4b5">If you can run <command role="hg-cmd">hg version</command>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
818 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
819 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
820 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
821 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
822 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
823 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
824
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
825 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
826 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
827 <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
828
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
829 <para id="x_4b6">Mercurial does not compress data when it uses the ssh
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
830 protocol, because the ssh protocol can transparently compress
771
b338f5490029 Americanize spellings :-(
Bryan O'Sullivan <bos@serpentine.com>
parents: 754
diff changeset
831 data. However, the default behavior of ssh clients is
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
832 <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
833
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
834 <para id="x_4b7">Over any network other than a fast LAN (even a wireless
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
835 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
836 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
837 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
838 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
839 minutes to 17 minutes.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
840
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
841 <para id="x_4b8">Both <command>ssh</command> and <command>plink</command>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
842 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
843 turns on compression. You can easily edit your <filename
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
844 role="special">~/.hgrc</filename> to enable compression for
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
845 all of Mercurial's uses of the ssh protocol.</para>
679
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
846 <programlisting>[ui]
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
847 ssh = ssh -C</programlisting>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
848
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
849 <para id="x_4b9">If you use <command>ssh</command>, you can configure it to
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
850 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
851 this, edit your <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
852 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
853 yet exist), as follows.</para>
679
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
854 <programlisting>Host hg
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
855 Compression yes
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
856 HostName hg.example.com</programlisting>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
857 <para id="x_4ba">This defines an alias, <literal>hg</literal>. When you
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
858 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
859 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
860 <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
861 <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
862 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
863 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
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 </sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
867 <sect1 id="sec:collab:cgi">
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
868 <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
869
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
870 <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
871 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
872 hours.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
873
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
874 <para id="x_4bc">We'll begin with the simplest of examples, and work our way
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
875 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
876 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
877 your web server's configuration.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
878
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
879 <note>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
880 <para id="x_4bd"> Configuring a web server is a complex, fiddly, and
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
881 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
882 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
883 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
884 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
885 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
886 error logs.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
887 </note>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
888
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
889 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
890 <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
891
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
892 <para id="x_4be">Before you continue, do take a few moments to check a few
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
893 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
894
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
895 <orderedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
896 <listitem><para id="x_4bf">Do you have a web server installed at all?
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
897 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
898 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
899 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
900 <listitem><para id="x_4c0">If you have a web server installed, is it
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
901 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
902 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
903 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
904 <listitem><para id="x_4c1">Is your server configured to allow you to run
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
905 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
906 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
907 to run CGI programs.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
908 </listitem></orderedlist>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
909
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
910 <para id="x_4c2">If you don't have a web server installed, and don't have
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
911 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
912 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
913 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
914 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
915 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
916 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
917 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
918 <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
919 Apache.</para>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
920
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
921 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
922 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
923 <title>Basic CGI configuration</title>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
924
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
925 <para id="x_4c3">On Unix-like systems, it's common for users to have a
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
926 subdirectory named something like <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
927 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
928 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
929 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
930 accessible at a URL of the form
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
931 <literal>http://www.example.com/username/foo</literal>.</para>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
932
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
933 <para id="x_4c4">To get started, find the <filename
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
934 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
935 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
936 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
937 master Mercurial repository at <ulink
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
938 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
939
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
940 <para id="x_4c5">You'll need to copy this script into your <filename
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
941 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
942 ensure that it's executable.</para>
679
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
943 <programlisting>cp .../hgweb.cgi ~/public_html
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
944 chmod 755 ~/public_html/hgweb.cgi</programlisting>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
945 <para id="x_4c6">The <literal>755</literal> argument to
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
946 <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
947 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
948 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
949 <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
950 <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
951 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
952 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
953 <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
954 <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
955 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
956 <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
957
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
958 <sect3 id="sec:collab:wtf">
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
959 <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
960 wrong?</title>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
961
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
962 <para id="x_4c7">Once you've copied the CGI script into place, go into a
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
963 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
964 url="http://myhostname/
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
965 myuser/hgweb.cgi">http://myhostname/
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
966 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
967 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
968 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
969 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
970 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
971 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
972 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
973 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
974 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
975
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
976 <para id="x_4c8">Your web server may have per-user directories disabled.
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
977 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
978 <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
979 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
980 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
981 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
982 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
983 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
984 directory, for example <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
985 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
986
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
987 <para id="x_4c9">Your file access permissions may be too restrictive.
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
988 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
989 and directories under your <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
990 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
991 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
992 help you to make your permissions more appropriate.</para>
679
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
993 <programlisting>chmod 755 ~
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
994 find ~/public_html -type d -print0 | xargs -0r chmod 755
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
995 find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
996
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
997 <para id="x_4ca">The other possibility with permissions is that you might
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
998 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
999 script. In this case, it's likely that your access
660
21c62e09b99f Typo and spelling corrections. Removed tex tags.
Ori Avtalion <ori@avtalion.name>
parents: 659
diff changeset
1000 permissions are <emphasis>too permissive</emphasis>. Apache's
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1001 <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
1002 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
1003
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1004 <para id="x_4cb">Your web server may be configured to disallow execution
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1005 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
1006 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
1007 system.</para>
679
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
1008
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
1009 &ch06-apache-config.lst;
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
1010
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1011 <para id="x_4cc">If you find a similar-looking
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1012 <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
1013 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
1014 <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
1015 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
1016 server.</para>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
1017
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1018 <para id="x_4cd">If you find that Apache serves you the text of the CGI
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1019 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
1020 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
1021 this.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1022 <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
1023
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1024 <para id="x_4ce">The next possibility is that you might be served with a
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1025 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
1026 <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
1027 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
1028 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
1029 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
1030 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
1031 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
1032 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
1033 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
1034 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
1035 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
1036 <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
1037
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1038 <para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to by
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1039 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
1040 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
1041 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
1042 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
1043 and replace the <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1044 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
1045 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
1046 up.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1047
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1048 <para id="x_4d0">At this point, when you try to reload the page, you
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1049 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
1050 repository's history. Whew!</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1051
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1052 </sect3>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1053 <sect3>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1054 <title>Configuring lighttpd</title>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
1055
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1056 <para id="x_4d1">To be exhaustive in my experiments, I tried configuring
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1057 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
1058 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
1059 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
1060 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
1061 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
1062 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
1063 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
1064 edited.</para>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
1065
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1066 <para id="x_4d2">Once I had Apache running, getting
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1067 <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
1068 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
1069 <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
1070 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
1071 <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
1072 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
1073 <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
1074 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
1075 end of the config file, to configure these modules.</para>
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1076 <programlisting>userdir.path = "public_html"
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1077 cgi.assign = (".cgi" =&gt; "" )</programlisting>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1078 <para id="x_4d3">With this done, <literal>lighttpd</literal> ran
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1079 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
1080 <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
1081 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
1082 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
1083 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
1084 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
1085 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
1086 <literal>lighttpd</literal>.</para>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
1087
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1088 </sect3>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1089 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1090 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1091 <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
1092
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1093 <para id="x_4d4">The <filename role="special">hgweb.cgi</filename> script
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1094 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
1095 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
1096 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
1097 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
1098 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
1099 script.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1100
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1101 <para id="x_4d5">The procedure to configure <filename
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1102 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
1103 involved than for <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1104 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
1105 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
1106 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
1107 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
1108
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1109 <para id="x_4d6">You'll need to copy this script into your <filename
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1110 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
1111 ensure that it's executable.</para>
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
1112
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1113 <programlisting>cp .../hgwebdir.cgi ~/public_html
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1114 chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
1115
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
1116 <para id="x_4d7">With basic configuration out of the way, try to
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
1117 visit <ulink url="http://myhostname/
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1118 myuser/hgwebdir.cgi">http://myhostname/
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1119 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
1120 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
1121 window or error message, try walking through the list of
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
1122 potential problems in <xref
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1123 linkend="sec:collab:wtf"/>.</para>
211
b461d7ead9e1 Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents: 210
diff changeset
1124
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1125 <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1126 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
1127 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
1128 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
1129 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
1130 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
1131 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
1132 <literal>ConfigParser</literal>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1133 <citation>web:configparser</citation> module.</para>
211
b461d7ead9e1 Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents: 210
diff changeset
1134
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1135 <para id="x_4d9">The easiest way to configure <filename
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1136 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
1137 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
1138 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
1139 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
1140 this:</para>
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1141 <programlisting>[collections]
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1142 /my/root = /my/root</programlisting>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1143 <para id="x_4da">Mercurial interprets this by looking at the directory name
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1144 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
1145 <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
1146 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
1147 <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
1148 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
1149 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
1150 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
1151
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1152 <para id="x_4db">Given the example above, if we have a repository whose
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1153 local path is <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1154 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
1155 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
1156 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
1157 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
1158 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
1159 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
1160 myuser/hgwebdir.cgi">http://myhostname/
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1161 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
1162 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
1163 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
1164 myuser/hgwebdir.cgi/this/repo</ulink>.</para>
211
b461d7ead9e1 Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents: 210
diff changeset
1165
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1166 <para id="x_4dc">If we replace <filename
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1167 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
1168 of this example with <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1169 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
1170 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
1171 <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
1172 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
1173 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
1174 <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
1175
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1176 <para id="x_4dd">The <filename role="special">hgwebdir.cgi</filename>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1177 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
1178 <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
1179 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
1180 repositories it finds.</para>
211
b461d7ead9e1 Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents: 210
diff changeset
1181
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1182 <para id="x_4de">The <literal>collections</literal> mechanism makes it easy
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1183 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
1184 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
1185 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
1186 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
1187 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
1188 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
1189 look.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1190
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1191 <sect3>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1192 <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
1193 publish</title>
211
b461d7ead9e1 Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents: 210
diff changeset
1194
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1195 <para id="x_4df">In addition to the <literal>collections</literal>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1196 mechanism, the <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1197 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
1198 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
1199 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
1200 the following form.</para>
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1201 <programlisting>[paths]
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1202 repo1 = /my/path/to/some/repo
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1203 repo2 = /some/path/to/another</programlisting>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1204 <para id="x_4e0">In this case, the virtual path (the component that will
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1205 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
1206 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
1207 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
1208 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
1209 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
1210
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1211 <para id="x_4e1">If you wish, you can use both the
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1212 <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
1213 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
1214 file.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
1215
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1216 <note>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1217 <para id="x_4e2"> If multiple repositories have the same virtual path,
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1218 <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
1219 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
1220 unpredictably.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1221 </note>
212
ef8a5e393103 Mention the paths section of a hgwebdir config file.
Bryan O'Sullivan <bos@serpentine.com>
parents: 211
diff changeset
1222
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1223 </sect3>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1224 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1225 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1226 <title>Downloading source archives</title>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1227
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1228 <para id="x_4e3">Mercurial's web interface lets users download an archive
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1229 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
1230 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
1231 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
1232
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1233 <para id="x_4e4">By default, this feature is not enabled. To enable it,
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1234 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
1235 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
1236 <literal role="rc-web">web</literal> section of your <filename
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1237 role="special">~/.hgrc</filename>.</para>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1238
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1239 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1240 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1241 <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
1242
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1243 <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd">hg
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1244 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
1245 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
1246 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
1247 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
1248 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
1249 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
1250 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1251 <listitem><para id="x_4e6"><envar
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1252 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
1253 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
1254 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
1255 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
1256 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
1257 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
1258 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
1259 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1260 <listitem><para id="x_4e7"><literal>bz2</literal>: A
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1261 <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
1262 <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
1263 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
1264 the server.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1265 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1266 <listitem><para id="x_4e8"><literal>gz</literal>: A
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1267 <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
1268 <literal>gzip</literal> compression.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1269 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1270 <listitem><para id="x_4e9"><literal>zip</literal>: A
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1271 <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
1272 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
1273 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
1274 </listitem>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1275 </itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1276 <para id="x_4ea"> If you provide an empty list, or don't have an
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1277 <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
1278 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
1279 how to enable all three supported formats.</para>
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1280 <programlisting>[web]
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1281 allow_archive = bz2 gz zip</programlisting>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1282 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1283 <listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>:
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1284 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
1285 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
1286 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
1287 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
1288 <literal>false</literal>, only the
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1289 <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
1290 is available.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1291 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1292 <listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>:
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1293 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
1294 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
1295 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
1296 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
1297 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
1298 role="special">.hg/hgrc</filename> file, but it can make
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1299 sense to use in a global <filename
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1300 role="special">~/.hgrc</filename> if every repository
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1301 has a single maintainer.</para>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1302 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1303 <listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>:
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1304 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
1305 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
1306 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1307 <listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>:
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1308 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
1309 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
1310 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1311 <listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>:
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1312 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
1313 <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
1314 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
1315 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
1316 </listitem>
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
1317 <listitem><para id="x_4f0"><envar
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
1318 role="rc-item-web">style</envar>: Controls the template
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
1319 Mercurial uses to display the web interface. Mercurial
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
1320 ships with two web templates, named
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1321 <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
1322 (the latter is much more visually attractive). You can
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
1323 also specify a custom template of your own; see
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
1324 <xref linkend="chap:template"/> for details. Here, you can
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
1325 see how to enable the <literal>gitweb</literal>
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
1326 style.</para>
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1327 <programlisting>[web]
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1328 style = gitweb</programlisting>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1329 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1330 <listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>:
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1331 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
1332 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
1333 which it was installed.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1334 </listitem></itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1335 <para id="x_4f2">If you are using <filename
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1336 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
1337 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
1338 section of the <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1339 role="special">hgweb.config</filename> file instead of a
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1340 <filename role="special">~/.hgrc</filename> file, for
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1341 convenience. These items are <envar
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1342 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
1343 role="rc-item-web">style</envar>.</para>
215
70e1f8448699 Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents: 212
diff changeset
1344
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1345 <sect3>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1346 <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
1347
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1348 <para id="x_4f3">A few <literal role="rc-web">web</literal> configuration
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1349 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
1350 role="special">.hg/hgrc</filename>, rather than a user's
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1351 or global <filename role="special">~/.hgrc</filename>.</para>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1352 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1353 <listitem><para id="x_4f4"><envar
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1354 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
1355 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
1356 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
1357 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1358 <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>:
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1359 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
1360 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
1361 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
1362 </listitem></itemizedlist>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1363
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1364 </sect3>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1365 <sect3>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1366 <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
1367 serve</command> command</title>
215
70e1f8448699 Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents: 212
diff changeset
1368
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1369 <para id="x_4f6">Some of the items in the <literal
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1370 role="rc-web">web</literal> section of a <filename
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1371 role="special">~/.hgrc</filename> file are only for use
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1372 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
1373 command.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1374 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1375 <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>:
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1376 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
1377 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
1378 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
1379 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
1380 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
1381 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
1382 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1383 <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>:
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1384 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
1385 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
1386 listens on all addresses.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1387 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1388 <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>:
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1389 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
1390 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
1391 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
1392 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
1393 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1394 <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>:
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1395 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
1396 IPv6 is not used.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1397 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1398 <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>:
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1399 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
1400 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
1401 </listitem></itemizedlist>
215
70e1f8448699 Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents: 212
diff changeset
1402
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1403 </sect3>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1404 <sect3>
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1405 <title>Choosing the right <filename
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1406 role="special">~/.hgrc</filename> file to add <literal
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1407 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
1408
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1409 <para id="x_4fc">It is important to remember that a web server like
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1410 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
1411 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
1412 server, such as <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1413 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
1414 under that user ID.</para>
216
699771d085c6 More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 215
diff changeset
1415
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1416 <para id="x_4fd">If you add <literal role="rc-web">web</literal> items to
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1417 your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1418 <filename role="special">~/.hgrc</filename> file. Those
771
b338f5490029 Americanize spellings :-(
Bryan O'Sullivan <bos@serpentine.com>
parents: 754
diff changeset
1419 settings will thus only affect the behavior of the <command
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1420 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
1421 To cause CGI scripts to see your settings, either create a
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1422 <filename role="special">~/.hgrc</filename> file in the
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1423 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
1424 add those settings to a system-wide <filename
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1425 role="special">~/.hgrc</filename> file.</para>
216
699771d085c6 More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 215
diff changeset
1426
699771d085c6 More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 215
diff changeset
1427
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1428 </sect3>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1429 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1430 </sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1431 </chapter>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1432
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1433 <!--
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1434 local variables:
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1435 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
1436 end:
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1437 -->