annotate en/ch06-collab.xml @ 831:acf9dc5f088d

Add a skeletal preface.
author Bryan O'Sullivan <bos@serpentine.com>
date Thu, 07 May 2009 21:07:35 -0700
parents en/ch05-collab.xml@477d6a3e5023
children
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
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
22 diffs), and view the contents of each directory and file. You
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
23 can even get a view of history that gives a graphical view of
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
24 the relationships between individual changes and merges.</para>
209
8b599dcca584 Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents: 187
diff changeset
25
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
26 <para id="x_44d">Also for human consumption, the web interface provides
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
27 Atom and RSS feeds of the changes in a repository. This lets you
773
3b640272a966 Progres on resolve
Bryan O'Sullivan <bos@serpentine.com>
parents: 771
diff changeset
28 <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
29 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
30 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
31 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
32 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
33 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
34 repository.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
35
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
36 <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
37 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
38 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
39 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
40 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
41
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
42 <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
43 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
44 the master Mercurial repository at <ulink
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
45 url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para>
209
8b599dcca584 Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents: 187
diff changeset
46
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
47 <para id="x_450">If you're interested in providing a web interface
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
48 to your own repositories, there are several good ways to do
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
49 this.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
50
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
51 <para id="x_69d">The easiest and fastest way to get started in an informal
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
52 environment is to use the <command role="hg-cmd">hg
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
53 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
54 <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
55 linkend="sec:collab:serve"/> below for details of how to use
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
56 this command.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
57
828
477d6a3e5023 Many final changes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 806
diff changeset
58 <para id="x_69e">For longer-lived repositories that you'd like to
477d6a3e5023 Many final changes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 806
diff changeset
59 have permanently available, there are several public hosting
477d6a3e5023 Many final changes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 806
diff changeset
60 services available. Some are free to open source projects,
477d6a3e5023 Many final changes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 806
diff changeset
61 while others offer paid commercial hosting. An up-to-date list
477d6a3e5023 Many final changes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 806
diff changeset
62 is available at <ulink
477d6a3e5023 Many final changes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 806
diff changeset
63 url="http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting">http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting</ulink>.</para>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
64
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
65 <para id="x_6a0">If you would prefer to host your own repositories, Mercurial
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
66 has built-in support for several popular hosting technologies,
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
67 most notably CGI (Common Gateway Interface), and WSGI (Web
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
68 Services Gateway Interface). See <xref
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
69 linkend="sec:collab:cgi"/> for details of CGI and WSGI
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
70 configuration.</para>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
71 </sect1>
209
8b599dcca584 Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents: 187
diff changeset
72
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
73 <sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
74 <title>Collaboration models</title>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
75
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
76 <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
77 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
78 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
79 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
80 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
81 particular needs.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
82
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
83 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
84 <title>Factors to keep in mind</title>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
85
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
86 <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
87 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
88 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
89 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
90 a moment.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
91
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
92 <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
93 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
94 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
95 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
96 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
97 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
98 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
99 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
100 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
101
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
102 <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
103 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
104 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
105 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
106 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
107 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
108 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
109 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
110 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
111 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
112 branch.</para>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
113 </sect2>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
114
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
115 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
116 <title>Informal anarchy</title>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
117
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
118 <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
119 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
120 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
121 situations.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
122
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
123 <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
124 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
125 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
126 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
127 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
128 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
129 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
130 hacking intensely on a handful of projects.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
131
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
132 <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
133 <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
134 <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
135 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
136 <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
137 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
138 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
139 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
140 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
141 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
142 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
143 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
144 out.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
145
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
146 <para id="x_458">The charm, and the problem, with doing things
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
147 in an ad hoc fashion like this is that only people who know
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
148 about your changes, and where they are, can see them. Such an
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
149 informal approach simply doesn't scale beyond a handful
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
150 people, because each individual needs to know about
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
151 <emphasis>n</emphasis> different repositories to pull
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
152 from.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
153 </sect2>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
154
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
155 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
156 <title>A single central repository</title>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
157
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
158 <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
159 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
160 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
161 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
162 more ambitious workflow schemes.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
163
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
164 <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
165 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
166 (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
167 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
168
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
169 <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
170 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
171 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
172 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
173 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
174 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
175 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
176 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
177 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
178 it has had a little testing.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
179
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
180 <para id="x_45c">If a team is hosting its own repository in this
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
181 kind of scenario, people will usually use the
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
182 <command>ssh</command> protocol to securely push changes to
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
183 the central repository, as documented in <xref
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
184 linkend="sec:collab:ssh"/>. It's also usual to publish a
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
185 read-only copy of the repository over HTTP, as in
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
186 <xref linkend="sec:collab:cgi"/>. Publishing over HTTP
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
187 satisfies the needs of people who don't have push access, and
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
188 those who want to use web browsers to browse the repository's
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
189 history.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
190 </sect2>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
191
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
192 <sect2>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
193 <title>A hosted central repository</title>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
194
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
195 <para id="x_6a1">A wonderful thing about public hosting services like
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
196 <ulink url="http://bitbucket.org/">Bitbucket</ulink> is that
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
197 not only do they handle the fiddly server configuration
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
198 details, such as user accounts, authentication, and secure
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
199 wire protocols, they provide additional infrastructure to make
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
200 this model work well.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
201
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
202 <para id="x_6a2">For instance, a well-engineered hosting service will let
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
203 people clone their own copies of a repository with a single
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
204 click. This lets people work in separate spaces and share
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
205 their changes when they're ready.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
206
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
207 <para id="x_6a3">In addition, a good hosting service will let people
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
208 communicate with each other, for instance to say <quote>there
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
209 are changes ready for you to review in this
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
210 tree</quote>.</para>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
211 </sect2>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
212
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
213 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
214 <title>Working with multiple branches</title>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
215
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
216 <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
217 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
218 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
219 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
220 <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
221 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
222 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
223 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
224 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
225 <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
226 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
227 proceeding.</para>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
228
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
229 <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
230 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
231 <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
232 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
233 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
234 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
235 branch will never affect a stable branch unless someone
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
236 explicitly merges those changes into the stable branch.</para>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
237
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
238 <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
239 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
240 server.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
241
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
242 &interaction.branching.init;
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
243
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
244 <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
245 them back.</para>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
246
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
247 <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
248 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
249 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
250
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
251 &interaction.branching.tag;
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
252
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
253 <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
254 development occurs on the main branch.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
255
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
256 &interaction.branching.main;
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
257
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
258 <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
259 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
260 <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
261 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
262 revision was committed.</para>
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
263
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
264 &interaction.branching.update;
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
265
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
266 <para id="x_464">In addition, immediately after the main branch is tagged,
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
267 we 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
268 <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
269
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
270 &interaction.branching.clone;
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
271
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
272 <para id="x_465">If we need to make a change to the stable
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
273 branch, we can then clone <emphasis>that</emphasis>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
274 repository, make our changes, commit, and push our changes
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
275 back there.</para>
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
276
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
277 &interaction.branching.stable;
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
278
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
279 <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
280 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
281 stable and main branches are <emphasis>isolated</emphasis>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
282 from each other. The changes that we made on the main branch
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
283 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
284 versa.</para>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
285
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
286 <para id="x_467">We'll often want all of our bugfixes on the stable
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
287 branch to show up on the main branch, too. Rather than
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
288 rewrite a bugfix on the main branch, we can simply pull and
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
289 merge changes from the stable to the main branch, and
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
290 Mercurial will bring those bugfixes in for us.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
291
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
292 &interaction.branching.merge;
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
293
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
294 <para id="x_468">The main branch will still contain changes that
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
295 are not on the stable branch, but it will also contain all of
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
296 the bugfixes from the stable branch. The stable branch
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
297 remains unaffected by these changes, since changes are only
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
298 flowing from the stable to the main branch, and not the other
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
299 way.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
300 </sect2>
666
8fcd44708f41 Uncomment all the mangled interaction examples.
Bryan O'Sullivan <bos@serpentine.com>
parents: 660
diff changeset
301
658
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>Feature branches</title>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
304
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
305 <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
306 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
307 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
308 <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
309 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
310 isolated from developments on other branches.</para>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
311
690
b788b405e141 Replace uses of <informalfigure> with <figure>
Bryan O'Sullivan <bos@serpentine.com>
parents: 683
diff changeset
312 <figure id="fig:collab:feature-branches">
b788b405e141 Replace uses of <informalfigure> with <figure>
Bryan O'Sullivan <bos@serpentine.com>
parents: 683
diff changeset
313 <title>Feature branches</title>
b788b405e141 Replace uses of <informalfigure> with <figure>
Bryan O'Sullivan <bos@serpentine.com>
parents: 683
diff changeset
314 <mediaobject>
754
65e9a18d2c7e Shrink large images to fit page
Dongsheng Song <dongsheng.song@gmail.com>
parents: 753
diff changeset
315 <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
316 <textobject><phrase>XXX add text</phrase></textobject>
b788b405e141 Replace uses of <informalfigure> with <figure>
Bryan O'Sullivan <bos@serpentine.com>
parents: 683
diff changeset
317 </mediaobject>
b788b405e141 Replace uses of <informalfigure> with <figure>
Bryan O'Sullivan <bos@serpentine.com>
parents: 683
diff changeset
318 </figure>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
319
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
320 <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
321 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
322 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
323 the master branch.</para>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
324 </sect2>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
325
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
326 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
327 <title>The release train</title>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
328
773
3b640272a966 Progres on resolve
Bryan O'Sullivan <bos@serpentine.com>
parents: 771
diff changeset
329 <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
330 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
331 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
332 ready to leave are allowed in.</para>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
333
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
334 <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
335 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
336 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
337 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
338 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
339 their feature can make the next release.</para>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
340 </sect2>
179
5fc4a45c069f Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents: 159
diff changeset
341
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
342 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
343 <title>The Linux kernel model</title>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
344
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
345 <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
346 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
347 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
348 <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
349 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
350 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
351 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
352
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
353 <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
354 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
355 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
356 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
357 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
358 from.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
359
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
360 <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
361 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
362 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
363 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
364 <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
365 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
366 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
367 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
368 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
369 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
370 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
371
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
372 <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
373 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
374 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
375 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
376 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
377 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
378 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
379 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
380 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
381 publish a single tree.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
382
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
383 <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
384 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
385 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
386 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
387 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
388 else controls.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
389
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
390 <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
391 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
392 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
393 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
394 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
395 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
396 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
397 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
398 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
399 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
400
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
401 <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
402 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
403 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
404 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
405 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
406 complete stranger.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
407
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
408 <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
409 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
410 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
411 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
412 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
413 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
414 software.</para>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
415 </sect2>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
416
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
417 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
418 <title>Pull-only versus shared-push collaboration</title>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
419
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
420 <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
421 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
422 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
423 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
424 repository.</para>
187
b60e2de6dbc3 Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents: 184
diff changeset
425
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
426 <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
427 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
428 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
429 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
430 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
431 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
432 a patch by hand).</para>
187
b60e2de6dbc3 Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents: 184
diff changeset
433
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
434 <para id="x_478">A good distributed revision control tool will
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
435 support both models. You and your collaborators can then
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
436 structure how you work together based on your own needs and
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
437 preferences, not on what contortions your tools force you
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
438 into.</para>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
439 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
440 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
441 <title>Where collaboration meets branch management</title>
187
b60e2de6dbc3 Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents: 184
diff changeset
442
691
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
443 <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
444 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
445 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
446 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
447 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
448 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
449 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
450 own, in <xref linkend="chap:branch"/>.</para>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
451 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
452 </sect1>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
453
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
454 <sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
455 <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
456
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
457 <para id="x_47a">The remainder of this chapter is devoted to the question of
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
458 sharing changes with your collaborators.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
459 </sect1>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
460
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
461 <sect1 id="sec:collab:serve">
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
462 <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
463 serve</command></title>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
464
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
465 <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
466 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
467 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
468 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
469
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
470 <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
471 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
472 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
473 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
474 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
475 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
476 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
477 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
478 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
479 <literal>http://my-laptop.local:8000/</literal>.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
480
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
481 <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
482 <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
483 only two things:</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
484 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
485 <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
486 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
487 browsers.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
488 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
489 <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
490 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
491 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
492 repository.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
493 </listitem></itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
494 <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
495 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
496 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
497
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
498 <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
499 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
500 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
501 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
502 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
503 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
504 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
505 network-hosted repositories.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
506
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
507 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
508 <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
509
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
510 <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
511 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
512 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
513 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
514 network and pull data from your repository.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
515
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
516 <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
517 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
518 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
519 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
520 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
521 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
522 (<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
523 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
524
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
525 <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
526 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
527 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
528 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
529 role="hg-opt-serve">-p</option> option.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
530
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
531 <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
532 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
533 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
534 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
535 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
536 option.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
537 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
538 </sect1>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
539
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
540 <sect1 id="sec:collab:ssh">
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
541 <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
542
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
543 <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
544 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
545 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
546 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
547
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
548 <para id="x_487">If you're not familiar with ssh, it's the name of
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
549 both a command and a network protocol that let you securely
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
550 communicate with another computer. To use it with Mercurial,
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
551 you'll be setting up one or more user accounts on a server so
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
552 that remote users can log in and execute commands.</para>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
553
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
554 <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
555 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
556 in nature.)</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
557
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
558 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
559 <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
560
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
561 <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
562 <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
563 <orderedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
564 <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
565 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
566 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
567 <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
568 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
569 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
570 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
571 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
572 <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
573 <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
574 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
575 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
576 <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
577 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
578 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
579 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
580 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
581 <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
582 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
583 </listitem></orderedlist>
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_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
586 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
587 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
588 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
589 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
590 paragraphs carefully.</para>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
591
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
592 <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
593 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
594 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
595 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
596 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
597 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
598 refers to the directory <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
599 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
600
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
601 <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
602 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
603 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
604 <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
605 <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
606
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
607 <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
608 <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
609 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
610 <programlisting>ssh://server//absolute/path</programlisting>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
611 </sect2>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
612
658
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>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
615
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
616 <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
617 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
618 <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
619 <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
620 <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
621 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
622 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
623
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
624 <para id="x_494">On Windows, the TortoiseHg package is bundled
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
625 with a version of Simon Tatham's excellent
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
626 <command>plink</command> command, and you should not need to
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
627 do any further configuration.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
628 </sect2>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
629
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
630 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
631 <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
632
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
633 <para id="x_499">To avoid the need to repetitively type a
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
634 password every time you need to use your ssh client, I
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
635 recommend generating a key pair.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
636
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
637 <tip>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
638 <title>Key pairs are not mandatory</title>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
639
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
640 <para id="x_6a4">Mercurial knows nothing about ssh authentication or key
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
641 pairs. You can, if you like, safely ignore this section and
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
642 the one that follows until you grow tired of repeatedly
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
643 typing ssh passwords.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
644 </tip>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
645
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
646 <itemizedlist>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
647 <listitem>
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
648 <para id="x_6a5">On a Unix-like system, the
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
649 <command>ssh-keygen</command> command will do the
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
650 trick.</para>
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
651 <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
652 to download a command named <command>puttygen</command>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
653 from <ulink
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
654 url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
655 PuTTY web site</ulink> to generate a key pair. See
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
656 <ulink
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
657 url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
658 <command>puttygen</command> documentation</ulink> for
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
659 details of how use the command.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
660 </listitem>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
661 </itemizedlist>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
662
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
663 <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
664 <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
665 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
666 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
667 secure network.)</para>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
668
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
669 <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
670 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
671 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
672 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
673 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
674 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
675 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
676 directory.</para>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
677
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
678 <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
679 <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
680 <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
681 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
682 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
683 role="special">authorized_keys</filename> file.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
684 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
685 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
686 <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
687
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
688 <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
689 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
690 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
691 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
692 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
693 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
694 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
695 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
696
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
697 <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
698 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
699 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
700 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
701 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
702 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
703
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
704 <itemizedlist>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
705 <listitem>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
706 <para id="x_49f">On Unix-like systems, the agent is called
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
707 <command>ssh-agent</command>, and it's often run
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
708 automatically for you when you log in. You'll need to use
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
709 the <command>ssh-add</command> command to add passphrases
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
710 to the agent's store.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
711 </listitem>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
712 <listitem>
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
713 <para id="x_6a7">On Windows, if you're using TortoiseHg, the
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
714 <command>pageant</command> command acts as the agent. As
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
715 with <command>puttygen</command>, you'll need to <ulink
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
716 url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
717 <command>pageant</command></ulink> from the PuTTY web
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
718 site and read <ulink
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
719 url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
720 documentation</ulink>. The <command>pageant</command>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
721 command adds an icon to your system tray that will let you
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
722 manage stored passphrases.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
723 </listitem>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
724 </itemizedlist>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
725 </sect2>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
726
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
727 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
728 <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
729
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
730 <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
731 a variety of things can go wrong. Add Mercurial
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
732 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
733 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
734 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
735 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
736 indefinitely.</para>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
737
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
738 <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
739 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
740 <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
741 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
742 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
743 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
744 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
745 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
746 <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
747 problem with Mercurial.</para>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
748
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
749 <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
750 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
751 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
752 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
753 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
754 follows.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
755 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
756 <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
757 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
758 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
759 configuration.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
760 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
761 <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
762 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
763 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
764 existence at all.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
765 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
766 <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
767 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
768 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
769 remote user's password.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
770 </listitem></itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
771 <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
772 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
773 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
774 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
775 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
776 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
777 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
778 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
779 first.</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_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
782 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
783 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
784 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
785 few possible culprits.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
786 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
787 <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
788 <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
789 to store the passphrase.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
790 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
791 <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
792 wrong key.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
793 </listitem></itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
794 <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
795 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
796 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
797 <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
798 <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
799 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
800 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
801 <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
802 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
803 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
804 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
805 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
806 <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
807 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
808 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
809 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
810 it.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
811 </listitem></itemizedlist>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
812
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
813 <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
814 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
815 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
816 <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
817
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
818 <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
819 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
820 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
821 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
822 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
823 output. Worse, they could potentially cause problems with
828
477d6a3e5023 Many final changes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 806
diff changeset
824 running Mercurial commands remotely. Mercurial tries to
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
825 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
826 <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
827 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
828 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
829 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
830 <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
831
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
832 <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
833 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
834 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
835 successfully:</para>
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
836
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
837 <programlisting>ssh myserver hg version</programlisting>
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
838
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
839 <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
840 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
841 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
842 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
843 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
844 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
845 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
846 <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
847 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
848 checking!</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
849 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
850 <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
851 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
852 simply misconfigured.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
853 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
854 <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
855 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
856 <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
857 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
858 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
859 documentation for details.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
860 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
861 <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
862 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
863 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
864 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
865 interactive.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
866 </listitem></itemizedlist>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
867
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
868 <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
869 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
870 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
871 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
872 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
873 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
874 option to get a clearer picture of what's going on.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
875 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
876 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
877 <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
878
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
879 <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
880 protocol, because the ssh protocol can transparently compress
771
b338f5490029 Americanize spellings :-(
Bryan O'Sullivan <bos@serpentine.com>
parents: 754
diff changeset
881 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
882 <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
883
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
884 <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
885 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
886 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
887 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
888 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
889 minutes to 17 minutes.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
890
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
891 <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
892 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
893 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
894 role="special">~/.hgrc</filename> to enable compression for
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
895 all of Mercurial's uses of the ssh protocol. Here is how to
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
896 do so for regular <command>ssh</command> on Unix-like systems,
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
897 for example.</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
898 <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
899 ssh = ssh -C</programlisting>
184
7b812c428074 Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 179
diff changeset
900
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
901 <para id="x_4b9">If you use <command>ssh</command> on a
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
902 Unix-like system, you can configure it to always use
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
903 compression when talking to your server. To do this, edit
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
904 your <filename role="special">.ssh/config</filename> file
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
905 (which may not yet exist), as follows.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
906
679
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
907 <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
908 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
909 HostName hg.example.com</programlisting>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
910
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
911 <para id="x_4ba">This defines a hostname alias,
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
912 <literal>hg</literal>. When you use that hostname on the
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
913 <command>ssh</command> command line or in a Mercurial
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
914 <literal>ssh</literal>-protocol URL, it will cause
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
915 <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
916 <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
917 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
918 which is a good thing in its own right.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
919 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
920 </sect1>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
921
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
922 <sect1 id="sec:collab:cgi">
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
923 <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
924
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
925 <para id="x_6a8">The simplest way to host one or more repositories in a
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
926 permanent way is to use a web server and Mercurial's CGI
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
927 support.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
928
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
929 <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
930 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
931 hours.</para>
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_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
934 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
935 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
936 your web server's configuration.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
937
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
938 <note>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
939 <title>High pain tolerance required</title>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
940
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
941 <para id="x_4bd">Configuring a web server is a complex, fiddly,
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
942 and highly system-dependent activity. I can't possibly give
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
943 you instructions that will cover anything like all of the
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
944 cases you will encounter. Please use your discretion and
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
945 judgment in following the sections below. Be prepared to make
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
946 plenty of mistakes, and to spend a lot of time reading your
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
947 server's error logs.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
948
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
949 <para id="x_6a9">If you don't have a strong stomach for tweaking
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
950 configurations over and over, or a compelling need to host
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
951 your own services, you might want to try one of the public
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
952 hosting services that I mentioned earlier.</para>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
953 </note>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
954
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
955 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
956 <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
957
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
958 <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
959 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
960
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
961 <orderedlist>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
962 <listitem><para id="x_4bf">Do you have a web server installed
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
963 at all? Mac OS X and some Linux distributions ship with
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
964 Apache, but many other systems may not have a web server
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
965 installed.</para>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
966 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
967 <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
968 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
969 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
970 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
971 <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
972 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
973 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
974 to run CGI programs.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
975 </listitem></orderedlist>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
976
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
977 <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
978 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
979 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
980 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
981 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
982 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
983 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
984 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
985 <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
986 Apache.</para>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
987 </sect2>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
988
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
989 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
990 <title>Basic CGI configuration</title>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
991
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
992 <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
993 subdirectory named something like <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
994 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
995 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
996 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
997 accessible at a URL of the form
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
998 <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
999
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1000 <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
1001 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
1002 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
1003 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
1004 master Mercurial repository at <ulink
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1005 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
1006
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1007 <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
1008 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
1009 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
1010 <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
1011 chmod 755 ~/public_html/hgweb.cgi</programlisting>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1012 <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
1013 <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
1014 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
1015 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
1016 <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
1017 <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
1018 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
1019 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
1020 <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
1021 <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
1022 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
1023 <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
1024
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1025 <sect3 id="sec:collab:wtf">
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1026 <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
1027 wrong?</title>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
1028
804
83540574ee49 removed whitespace from URLs
Raphael Borun Das Gupta <hg@raphael.dasgupta.ch>
parents: 773
diff changeset
1029 <para id="x_4c7">Once you've copied the CGI script into place,
806
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1030 go into a web browser, and try to open the URL
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1031 <literal>http://myhostname/~myuser/hgweb.cgi</literal>,
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1032 <emphasis>but</emphasis> brace yourself for instant failure.
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1033 There's a high probability that trying to visit this URL
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1034 will fail, and there are many possible reasons for this. In
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1035 fact, you're likely to stumble over almost every one of the
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1036 possible errors below, so please read carefully. The
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1037 following are all of the problems I ran into on a system
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1038 running Fedora 7, with a fresh installation of Apache, and a
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1039 user account that I created specially to perform this
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1040 exercise.</para>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
1041
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1042 <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
1043 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
1044 <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
1045 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
1046 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
1047 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
1048 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
1049 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
1050 directory, for example <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1051 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
1052
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1053 <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
1054 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
1055 and directories under your <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1056 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
1057 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
1058 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
1059 <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
1060 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
1061 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
1062
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1063 <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
1064 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
1065 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
1066 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
1067 <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
1068 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
1069
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1070 <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
1071 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
1072 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
1073 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
1074
80928ea6e7ae Add the ability to include text files and have them XML-mangled.
Bryan O'Sullivan <bos@serpentine.com>
parents: 671
diff changeset
1075 &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
1076
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1077 <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
1078 <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
1079 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
1080 <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
1081 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
1082 server.</para>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
1083
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1084 <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
1085 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
1086 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
1087 this.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1088 <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
1089
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1090 <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
1091 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
1092 <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
1093 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
1094 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
1095 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
1096 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
1097 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
1098 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
1099 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
1100 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
1101 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
1102 <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
1103
828
477d6a3e5023 Many final changes.
Bryan O'Sullivan <bos@serpentine.com>
parents: 806
diff changeset
1104 <para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1105 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
1106 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
1107 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
1108 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
1109 and replace the <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1110 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
1111 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
1112 up.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1113
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1114 <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
1115 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
1116 repository's history. Whew!</para>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1117 </sect3>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1118
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1119 <sect3>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1120 <title>Configuring lighttpd</title>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
1121
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1122 <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
1123 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
1124 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
1125 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
1126 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
1127 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
1128 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
1129 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
1130 edited.</para>
210
27b2c7c46af3 Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 209
diff changeset
1131
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1132 <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
1133 <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
1134 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
1135 <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
1136 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
1137 <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
1138 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
1139 <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
1140 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
1141 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
1142 <programlisting>userdir.path = "public_html"
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1143 cgi.assign = (".cgi" =&gt; "" )</programlisting>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1144 <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
1145 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
1146 <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
1147 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
1148 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
1149 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
1150 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
1151 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
1152 <literal>lighttpd</literal>.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1153 </sect3>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1154 </sect2>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1155
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1156 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1157 <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
1158
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1159 <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
1160 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
1161 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
1162 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
1163 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
1164 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
1165 script.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1166
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1167 <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
1168 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
1169 involved than for <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1170 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
1171 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
1172 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
1173 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
1174
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1175 <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
1176 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
1177 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
1178
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1179 <programlisting>cp .../hgwebdir.cgi ~/public_html
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1180 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
1181
4ce9d0754af3 Remove the words "section", "chapter", etc from in front of xref tags.
Bryan O'Sullivan <bos@serpentine.com>
parents: 690
diff changeset
1182 <para id="x_4d7">With basic configuration out of the way, try to
806
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1183 visit <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>
804
83540574ee49 removed whitespace from URLs
Raphael Borun Das Gupta <hg@raphael.dasgupta.ch>
parents: 773
diff changeset
1184 in your browser. It should
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1185 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
1186 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
1187 potential problems in <xref
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1188 linkend="sec:collab:wtf"/>.</para>
211
b461d7ead9e1 Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents: 210
diff changeset
1189
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1190 <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
1191 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
1192 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
1193 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
1194 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
1195 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
1196 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
1197 <literal>ConfigParser</literal>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1198 <citation>web:configparser</citation> module.</para>
211
b461d7ead9e1 Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents: 210
diff changeset
1199
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1200 <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
1201 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
1202 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
1203 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
1204 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
1205 this:</para>
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1206 <programlisting>[collections]
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1207 /my/root = /my/root</programlisting>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1208 <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
1209 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
1210 <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
1211 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
1212 <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
1213 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
1214 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
1215 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
1216
806
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1217 <para id="x_4db">Given the example above, if we have a
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1218 repository whose local path is <filename
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1219 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
1220 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
1221 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
1222 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
1223 class="directory">this/repo</filename>. If the base URL for
806
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1224 our CGI script is
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1225 <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>, the
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1226 complete URL for that repository will be
06458701453c Fix up some links to example URLs that aren't actually real.
Bryan O'Sullivan <bos@serpentine.com>
parents: 805
diff changeset
1227 <literal>http://myhostname/~myuser/hgwebdir.cgi/this/repo</literal>.</para>
211
b461d7ead9e1 Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents: 210
diff changeset
1228
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1229 <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
1230 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
1231 of this example with <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1232 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
1233 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
1234 <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
1235 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
1236 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
1237 <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
1238
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1239 <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
1240 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
1241 <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
1242 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
1243 repositories it finds.</para>
211
b461d7ead9e1 Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents: 210
diff changeset
1244
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1245 <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
1246 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
1247 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
1248 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
1249 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
1250 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
1251 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
1252 look.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1253
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1254 <sect3>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1255 <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
1256 publish</title>
211
b461d7ead9e1 Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents: 210
diff changeset
1257
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1258 <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
1259 mechanism, the <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1260 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
1261 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
1262 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
1263 the following form.</para>
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1264 <programlisting>[paths]
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1265 repo1 = /my/path/to/some/repo
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1266 repo2 = /some/path/to/another</programlisting>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1267 <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
1268 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
1269 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
1270 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
1271 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
1272 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
1273
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1274 <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
1275 <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
1276 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
1277 file.</para>
159
7355af913937 First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
1278
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1279 <note>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1280 <title>Beware duplicate virtual paths</title>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1281
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1282 <para id="x_4e2"> If several repositories have the same
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1283 virtual path, <filename
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1284 role="special">hgwebdir.cgi</filename> will not report
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1285 an error. Instead, it will behave unpredictably.</para>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1286 </note>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1287 </sect3>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1288 </sect2>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1289
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1290 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1291 <title>Downloading source archives</title>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1292
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1293 <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
1294 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
1295 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
1296 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
1297
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1298 <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
1299 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
1300 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
1301 <literal role="rc-web">web</literal> section of your <filename
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1302 role="special">~/.hgrc</filename>; see below for details.</para>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1303 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1304 <sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1305 <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
1306
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1307 <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
1308 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
1309 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
1310 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
1311 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
1312 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
1313 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
1314 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1315 <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
1316 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
1317 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
1318 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
1319 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
1320 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
1321 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
1322 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
1323 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1324 <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
1325 <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
1326 <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
1327 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
1328 the server.</para>
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_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
1331 <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
1332 <literal>gzip</literal> compression.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1333 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1334 <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
1335 <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
1336 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
1337 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
1338 </listitem>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1339 </itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1340 <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
1341 <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
1342 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
1343 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
1344 <programlisting>[web]
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1345 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
1346 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1347 <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
1348 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
1349 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
1350 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
1351 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
1352 <literal>false</literal>, only the
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1353 <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
1354 is available.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1355 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1356 <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
1357 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
1358 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
1359 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
1360 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
1361 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
1362 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
1363 sense to use in a global <filename
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1364 role="special">~/.hgrc</filename> if every repository
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1365 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
1366 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1367 <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
1368 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
1369 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
1370 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1371 <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
1372 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
1373 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
1374 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1375 <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
1376 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
1377 <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
1378 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
1379 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
1380 </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
1381 <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
1382 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
1383 Mercurial uses to display the web interface. Mercurial
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1384 ships with several web templates.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1385 <itemizedlist>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1386 <listitem>
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
1387 <para id="x_6aa"><literal>coal</literal> is monochromatic.</para>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1388 </listitem>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1389 <listitem>
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
1390 <para id="x_6ab"><literal>gitweb</literal> emulates the visual
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1391 style of git's web interface.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1392 </listitem>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1393 <listitem>
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
1394 <para id="x_6ac"><literal>monoblue</literal> uses solid blues and
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1395 greys.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1396 </listitem>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1397 <listitem>
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
1398 <para id="x_6ad"><literal>paper</literal> is the default.</para>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1399 </listitem>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1400 <listitem>
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
1401 <para id="x_6ae"><literal>spartan</literal> was the default for a
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1402 long time.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1403 </listitem>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1404 </itemizedlist>
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
1405 <para id="x_6af">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
1406 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
1407 <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
1408 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
1409 style.</para>
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1410 <programlisting>[web]
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1411 style = gitweb</programlisting>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1412 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1413 <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
1414 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
1415 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
1416 which it was installed.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1417 </listitem></itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1418 <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
1419 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
1420 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
1421 section of the <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1422 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
1423 <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
1424 convenience. These items are <envar
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1425 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
1426 role="rc-item-web">style</envar>.</para>
215
70e1f8448699 Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents: 212
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 <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
1430
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1431 <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
1432 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
1433 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
1434 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
1435 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1436 <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
1437 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
1438 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
1439 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
1440 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1441 <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
1442 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
1443 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
1444 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
1445 </listitem></itemizedlist>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1446 </sect3>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1447
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1448 <sect3>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1449 <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
1450 serve</command> command</title>
215
70e1f8448699 Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents: 212
diff changeset
1451
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1452 <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
1453 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
1454 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
1455 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
1456 command.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1457 <itemizedlist>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1458 <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
1459 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
1460 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
1461 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
1462 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
1463 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
1464 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
1465 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1466 <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
1467 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
1468 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
1469 listens on all addresses.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1470 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1471 <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
1472 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
1473 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
1474 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
1475 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
1476 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1477 <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
1478 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
1479 IPv6 is not used.</para>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1480 </listitem>
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1481 <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
1482 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
1483 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
1484 </listitem></itemizedlist>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1485 </sect3>
215
70e1f8448699 Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents: 212
diff changeset
1486
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1487 <sect3>
680
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1488 <title>Choosing the right <filename
8366882f67f2 Fix up more formatting goop
Bryan O'Sullivan <bos@serpentine.com>
parents: 679
diff changeset
1489 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
1490 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
1491
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1492 <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
1493 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
1494 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
1495 server, such as <filename
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1496 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
1497 under that user ID.</para>
216
699771d085c6 More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 215
diff changeset
1498
683
c838b3975bc6 Add IDs to paragraphs.
Bryan O'Sullivan <bos@serpentine.com>
parents: 682
diff changeset
1499 <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
1500 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
1501 <filename role="special">~/.hgrc</filename> file. Those
771
b338f5490029 Americanize spellings :-(
Bryan O'Sullivan <bos@serpentine.com>
parents: 754
diff changeset
1502 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
1503 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
1504 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
1505 <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
1506 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
1507 add those settings to a system-wide <filename
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1508 role="special">hgrc</filename> file.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1509 </sect3>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1510 </sect2>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1511 </sect1>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1512
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1513 <sect1>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1514 <title>System-wide configuration</title>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1515
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
1516 <para id="x_6b0">On Unix-like systems shared by multiple users (such as a
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1517 server to which people publish changes), it often makes sense to
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1518 set up some global default behaviors, such as what theme to use
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1519 in web interfaces.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1520
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
1521 <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1522 exists, Mercurial will read it at startup time and apply any
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1523 configuration settings it finds in that file. It will also look
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1524 for files ending in a <literal>.rc</literal> extension in a
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1525 directory named <filename>/etc/mercurial/hgrc.d</filename>, and
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1526 apply any configuration settings it finds in each of those
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1527 files.</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1528
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1529 <sect2>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1530 <title>Making Mercurial more trusting</title>
216
699771d085c6 More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 215
diff changeset
1531
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
1532 <para id="x_6b2">One situation in which a global <filename>hgrc</filename>
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1533 can be useful is if users are pulling changes owned by other
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1534 users. By default, Mercurial will not trust most of the
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1535 configuration items in a <filename>.hg/hgrc</filename> file
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1536 inside a repository that is owned by a different user. If we
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1537 clone or pull changes from such a repository, Mercurial will
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1538 print a warning stating that it does not trust their
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1539 <filename>.hg/hgrc</filename>.</para>
216
699771d085c6 More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents: 215
diff changeset
1540
775
29f0f79cf614 Update paragraph IDs
Bryan O'Sullivan <bos@serpentine.com>
parents: 774
diff changeset
1541 <para id="x_6b3">If everyone in a particular Unix group is on the same team
774
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1542 and <emphasis>should</emphasis> trust each other's
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1543 configuration settings, or we want to trust particular users,
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1544 we can override Mercurial's skeptical defaults by creating a
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1545 system-wide <filename>hgrc</filename> file such as the
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1546 following:</para>
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1547
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1548 <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1549 [trusted]
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1550 # Trust all entries in any hgrc file owned by the "editors" or
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1551 # "www-data" groups.
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1552 groups = editors, www-data
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1553
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1554 # Trust entries in hgrc files owned by the following users.
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1555 users = apache, bobo
e6c99cbd0abd Updates to chapters 5, 6, and 7
Bryan O'Sullivan <bos@serpentine.com>
parents: 773
diff changeset
1556 </programlisting>
658
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1557 </sect2>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1558 </sect1>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1559 </chapter>
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1560
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1561 <!--
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1562 local variables:
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1563 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
1564 end:
b90b024729f1 WIP DocBook snapshot that all compiles. Mirabile dictu!
Bryan O'Sullivan <bos@serpentine.com>
parents: 650
diff changeset
1565 -->