annotate en/collab.tex @ 264:f8a2fe77908d

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