Mercurial > hgbook
annotate ja/collab.tex @ 367:586bd91d0c84
- translated title page.
- started collab.tex.
author | Yoshiki Yazawa <yaz@honeyplanet.jp> |
---|---|
date | Sat, 01 Nov 2008 13:53:05 +0900 |
parents | 3b1291f24c0d |
children | 73aa295a40da |
rev | line source |
---|---|
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
1 %\chapter{Collaborating with other people} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
2 \chapter{$BB>$N?M!9$H$N6&F1:n6H(B} |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
3 \label{cha:collab} |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
4 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
5 %As a completely decentralised tool, Mercurial doesn't impose any |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
6 %policy on how people ought to work with each other. However, if |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
7 %you're new to distributed revision control, it helps to have some |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
8 %tools and examples in mind when you're thinking about possible |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
9 %workflow models. |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
10 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
11 $B40A4$JJ,;67?%D!<%k$H$7$F!$(BMercurial$B$O%f!<%6$,B>$N%f!<%6$H$I$N$h$&$K:n6H$9(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
12 $B$k$+$N%]%j%7!<$r6/MW$9$k$3$H$O$J$$!%$7$+$7=i$a$FJ,;6%j%S%8%g%s%3%s%H%m!<(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
13 $B%k%D!<%k$r;H$&$N$G$"$l$P!$$$$/$D$+$N%D!<%k$N;HMQK!$H;HMQNc$rCN$k$3$H$,(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
14 $B<h$jF@$k%o!<%/%U%m!<%b%G%k$r9M$($k:]$K=u$1$H$J$k$G$"$m$&!%(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
15 |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
16 %\section{Mercurial's web interface} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
17 \section{Mercurial$B$N%&%'%V%$%s%?%U%'!<%9(B} |
209
8b599dcca584
Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
18 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
19 %Mercurial has a powerful web interface that provides several |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
20 %useful capabilities. |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
21 |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
22 Mercurial$B$O$$$/$D$+$NM-MQ$J5!G=$r;}$D6/NO$J%&%'%V%$%s%?%U%'!<%9$rHw$($F(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
23 $B$$$k!%(B |
209
8b599dcca584
Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
24 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
25 %For interactive use, the web interface lets you browse a single |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
26 %repository or a collection of repositories. You can view the history |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
27 %of a repository, examine each change (comments and diffs), and view |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
28 %the contents of each directory and file. |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
29 |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
30 $BBPOCE*$JMxMQ$G$O!$%&%'%V%$%s%?%U%'!<%9$K$h$j(B1$B$D$N%j%]%8%H%j$^$?$O$$$/$D$+(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
31 $B$N%j%]%8%H%j$N%3%l%/%7%g%s$r1\Mw$9$k$3$H$,$G$-$k!%%j%]%8%H%j$NMzNr$r8+$?(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
32 $B$j!$3F!9$NJQ99!J%3%a%s%H$d:9J,$r4^$`!K$rD4$Y$?$j!$%G%#%l%/%H%j$d%U%!%$%k(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
33 $B$NFbMF$r8+$k$3$H$,$G$-$k!%(B |
209
8b599dcca584
Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
34 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
35 %Also for human consumption, the web interface provides an RSS feed of |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
36 %the changes in a repository. This lets you ``subscribe'' to a |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
37 %repository using your favourite feed reader, and be automatically |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
38 %notified of activity in that repository as soon as it happens. I find |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
39 %this capability much more convenient than the model of subscribing to |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
40 %a mailing list to which notifications are sent, as it requires no |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
41 %additional configuration on the part of whoever is serving the |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
42 %repository. |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
43 |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
44 $B%&%'%V%$%s%?%U%'!<%9$O1\MwMQ$K%j%]%8%H%j$NJQ99$N(BRSS$B%U%#!<%I$rDs6!$9$k!%$3(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
45 $B$l$r;H$($P!$%j%]%8%H%j$NJQ2=$r9%$_$N%U%#!<%I%j!<%@$K$h$C$F(B``$B9XFI(B''$B$9$k$3(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
46 $B$H$,$G$-!$%j%]%8%H%j$G$N3hF0$,5/$3$k$H$9$0$5$^DLCN$r<u$1$i$l$k!%$3$N5!G=(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
47 $B$OC/$,%j%]%8%H%j$N%5!<%S%9$r9T$C$F$bDI2C$N@_Dj$rI,MW$H$7$J$$$?$a!$%a!<%j(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
48 $B%s%0%j%9%H$r9XFI$7$FDLCN$r<u$1$k%b%G%k$h$j$b$:$C$HJXMx$G$"$k!%(B |
209
8b599dcca584
Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
49 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
50 %The web interface also lets remote users clone a repository, pull |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
51 %changes from it, and (when the server is configured to permit it) push |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
52 %changes back to it. Mercurial's HTTP tunneling protocol aggressively |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
53 %compresses data, so that it works efficiently even over low-bandwidth |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
54 %network connections. |
209
8b599dcca584
Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
55 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
56 $B%j%b!<%H%f!<%6$O%&%'%V%$%s%?%U%'!<%9$rMQ$$$F%j%]%8%H%j$r%/%m!<%s$9$k$3$H(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
57 $B$b$G$-$k!%JQ99$r(Bpull$B$7$F!$!J%5!<%P$,5v2D$9$k@_Dj$K$J$C$F$$$l$P!K2C$($?JQ(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
58 $B99$r:F$S(Bpush$B$9$k$3$H$b$G$-$k!%(BMercurial$B$N(BHTTP$B%H%s%M%k%W%m%H%3%k$O%G!<%?$r(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
59 $B@Q6KE*$K05=L$9$k$?$a!$%P%s%II}$NDc$$%M%C%H%o!<%/%3%M%/%7%g%s$G$bM-8z$K5!(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
60 $BG=$9$k!%(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
61 |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
62 %The easiest way to get started with the web interface is to use your |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
63 %web browser to visit an existing repository, such as the master |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
64 %Mercurial repository at |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
65 %\url{http://www.selenic.com/repo/hg?style=gitweb}. |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
66 |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
67 $B%&%'%V%$%s%?%U%'!<%9$N:G$b4JC1$J;O$aJ}$O%&%'%V%V%i%&%6$r;H$C$F(BMercurial$B$N(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
68 $B%^%9%?%j%]%8%H%j(B\url{http://www.selenic.com/repo/hg?style=gitweb}$B$N$h$&$J(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
69 $B4{B8$N%j%]%8%H%j$r;2>H$9$k$3$H$G$"$k!%(B |
209
8b599dcca584
Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
70 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
71 %If you're interested in providing a web interface to your own |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
72 %repositories, Mercurial provides two ways to do this. The first is |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
73 %using the \hgcmd{serve} command, which is best suited to short-term |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
74 %``lightweight'' serving. See section~\ref{sec:collab:serve} below for |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
75 %details of how to use this command. If you have a long-lived |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
76 %repository that you'd like to make permanently available, Mercurial |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
77 %has built-in support for the CGI (Common Gateway Interface) standard, |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
78 %which all common web servers support. See |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
79 %section~\ref{sec:collab:cgi} for details of CGI configuration. |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
80 |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
81 $B<+J,$N%j%]%8%H%j$K%&%'%V%$%s%?%U%'!<%9$rMQ0U$9$k>l9g!$(B2$BDL$j$N$d$jJ}$,$"(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
82 $B$k!%(B 1$B$DL\$NJ}K!$O(B\hgcmd{serve}$B%3%^%s%I$r;H$&J}K!$G!$$3$l$OC;4|4V$N(B``$B<j7Z(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
83 $B$J(B''$B%5!<%S%9$KE*$7$F$$$k!%$3$N%3%^%s%I$N>\:Y$J;HMQK!$K$D$$$F$O2<5-(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
84 $B$N(B~\ref{sec:collab:serve}$B@a$r;2>H$N$3$H!%%j%]%8%H%j$rD94|4V$K$o$?$j1JB3E*(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
85 $B$K%5!<%S%9$7$?$$>l9g$O!$(BMercurial$B$KFbB"$N(BCGI(Common Gateway Interface)$B%5(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
86 $B%]!<%H$rMxMQ$9$k$3$H$,$G$-$k!%(B CGI$B$N@_Dj$K$D$$$F$O(B~\ref{sec:collab:cgi}$B@a(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
87 $B$r;2>H$N$3$H!%(B |
209
8b599dcca584
Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
88 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
89 %\section{Collaboration models} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
90 \section{$B6&F1:n6H%b%G%k(B} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
91 |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
92 %With a suitably flexible tool, making decisions about workflow is much |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
93 %more of a social engineering challenge than a technical one. |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
94 %Mercurial imposes few limitations on how you can structure the flow of |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
95 %work in a project, so it's up to you and your group to set up and live |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
96 %with a model that matches your own particular needs. |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
97 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
98 $BE,@Z$G=@Fp$J%D!<%k$r$b$C$F$7$F$b!$%o!<%/%U%m!<$K4X$9$k7hDj$r$9$k$3$H$O5;(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
99 $B=QE*$H$$$&$h$j$O<R2q9)3XE*$J%A%c%l%s%8$G$"$k!%(B Mercurial$B$,%W%m%8%'%/%H$N(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
100 $B%o!<%/%U%m!<$K2]$9@)8B$O$[$H$s$I$J$$$?$a!$$3$l$r$$$+$K9=C[$9$k$+$O$"$J$?(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
101 $B$H$=$N6&F1:n6H<T$KG$$5$l$F$*$j!$8GM-$NMW5a%^%C%A$9$k%b%G%k$r:n$k$3$H$,$G(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
102 $B$-$k!%(B |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
103 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
104 %\subsection{Factors to keep in mind} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
105 \subsection{$B9MN8$9$Y$-MWAG(B} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
106 |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
107 %The most important aspect of any model that you must keep in mind is |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
108 %how well it matches the needs and capabilities of the people who will |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
109 %be using it. This might seem self-evident; even so, you still can't |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
110 %afford to forget it for a moment. |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
111 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
112 $B$I$N$h$&$J%b%G%k$r;H$&>l9g$G$b!$$=$l$,:n6H$9$k?M!9$NMW5a$HG=NO$KE,$C$?$b(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
113 $B$N$G$"$k$+$r>o$KG0F,$KCV$/$3$H$,:G$b=EMW$G$"$k!%(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
114 $B$3$l$O<+L@$N$3$H$N$h$&$K;W$($k$+$b$7$l$J$$$,!$JR;~$bK:$l$F$O$J$i$J$$!%(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
115 |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
116 %I once put together a workflow model that seemed to make perfect sense |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
117 %to me, but that caused a considerable amount of consternation and |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
118 %strife within my development team. In spite of my attempts to explain |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
119 %why we needed a complex set of branches, and how changes ought to flow |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
120 %between them, a few team members revolted. Even though they were |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
121 %smart people, they didn't want to pay attention to the constraints we |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
122 %were operating under, or face the consequences of those constraints in |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
123 %the details of the model that I was advocating. |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
124 |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
125 $B<+J,$K$H$C$F40A4$H;W$($k%o!<%/%U%m!<%b%G%k$r9=C[$7$?$D$b$j$,!$6&F13+H/%A!<(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
126 $B%`$K$H$C$F$OBg$-$J6C$-$H3kF#$rM?$($F$7$^$C$?$3$H$,$"$k!%J#;($J%V%i%s%A$N(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
127 $B=89g$,$J$<I,MW$J$N$+JQ99$,%V%i%s%A4V$G$I$N$h$&$KEAGE$9$k$N$+$r@bL@$7$?$K(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
128 $B$b$+$+$o$i$:!$4v?M$+$N%A!<%`%a%s%P!<$OH?H/$7$?!%H`$i$OAoL@$G$"$C$?$,!$;d(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
129 $B$,94$C$?%k!<%k$,:n6H$KM?$($k@)8B$d!$%b%G%k$N:YIt$KM?$($k1F6A$KCm0U$rJ'$&(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
130 $B$3$H$OK>$^$J$+$C$?!%(B |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
131 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
132 %Don't sweep foreseeable social or technical problems under the rug. |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
133 %Whatever scheme you put into effect, you should plan for mistakes and |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
134 %problem scenarios. Consider adding automated machinery to prevent, or |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
135 %quickly recover from, trouble that you can anticipate. As an example, |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
136 %if you intend to have a branch with not-for-release changes in it, |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
137 %you'd do well to think early about the possibility that someone might |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
138 %accidentally merge those changes into a release branch. You could |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
139 %avoid this particular problem by writing a hook that prevents changes |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
140 %from being merged from an inappropriate branch. |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
141 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
142 $B>-Mh5/$3$jF@$k<R2qE*$^$?$$$O5;=QE*LdBj$KL\$rbT$C$F$O$J$i$J$$!%$I$N$h$&$J(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
143 $BJ}K!$r$H$k$K;V<j$b!$4V0c$$$dLdBj$,5/$-$?>l9g$KHw$($F$*$/I,MW$,$"$k!%A[A|(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
144 $B$7F@$k%H%i%V%k$rKI;_$7$?$j!$%H%i%V%k$+$iAGAa$/2sI|$5$;$k$?$a$N<+F02=$5$l(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
145 $B$?J}K!$r9M$($F$*$/I,MW$,$"$k!%$?$H$($P!$%j%j!<%9$K4^$a$J$$JQ99$r9T$C$?%V(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
146 $B%i%s%A$,$"$k$H$7$?$i!$C/$+$,8m$C$F$=$3$+$i%j%j!<%9%V%i%s%A$KJQ99$r%^!<%8(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
147 $B$7$F$7$^$&2DG=@-$K$D$$$F8!F$$7$F$*$/$Y$-$G$"$k!%$3$N>l9g$G$"$l$P!$ITE,@Z(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
148 $B$J%V%i%s%A$+$i$N%^!<%8$r6X;_$9$k%U%C%/$rMQ0U$9$k$3$H$GLdBj$r2sHr$9$k$3$H(B |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
149 $B$,$G$-$k!%(B |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
150 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
151 %\subsection{Informal anarchy} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
152 \subsection{$BHs8x<0$J:.Mp(B} |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
153 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
154 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
|
155 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
|
156 perfectly well in a few unusual situations. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
157 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
158 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
|
159 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
|
160 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
|
161 ``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
|
162 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
|
163 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
|
164 intensely on a handful of projects. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
165 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
166 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
|
167 \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
|
168 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
|
169 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
|
170 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
|
171 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
|
172 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
|
173 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
|
174 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
|
175 it out. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
176 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
177 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
|
178 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
|
179 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
|
180 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
|
181 about $n$ different repositories to pull from. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
182 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
183 %\subsection{A single central repository} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
184 \subsection{1$B$D$N=8Cf%j%]%8%H%j(B} |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
185 |
179
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
186 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
|
187 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
|
188 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
|
189 most common ``building block'' for more ambitious workflow schemes. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
190 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
191 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
|
192 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
|
193 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
|
194 for other people to see it. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
195 |
179
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
196 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
|
197 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
|
198 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
|
199 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
|
200 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
|
201 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
|
202 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
|
203 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
|
204 testing. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
205 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
206 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
|
207 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
|
208 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
|
209 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
|
210 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
|
211 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
|
212 web browsers to browse the repository's history. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
213 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
214 %\subsection{Working with multiple branches} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
215 \subsection{$BJ#?t$N%V%i%s%A$G$N:n6H(B} |
179
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
216 |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
217 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
|
218 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
|
219 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
|
220 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
|
221 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
|
222 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
|
223 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
|
224 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
|
225 directions in which development is proceeding. |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
226 |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
227 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
|
228 simultaneous, but not identical, branches. Each ``development |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
229 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
|
230 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
|
231 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
|
232 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
|
233 merges those changes in. |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
234 |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
235 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
|
236 have one ``main branch'' on a central server. |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
237 \interaction{branching.init} |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
238 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
|
239 |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
240 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
|
241 \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
|
242 revision. |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
243 \interaction{branching.tag} |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
244 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
|
245 \interaction{branching.main} |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
246 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
|
247 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
|
248 get a copy of the working directory exactly as it was when that tagged |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
249 revision was committed. |
179
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
250 \interaction{branching.update} |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
251 |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
252 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
|
253 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
|
254 also on the server. |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
255 \interaction{branching.clone} |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
256 |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
257 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
|
258 \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
|
259 changes back there. |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
260 \interaction{branching.stable} |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
261 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
|
262 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
|
263 \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
|
264 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
|
265 |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
266 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
|
267 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
|
268 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
|
269 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
|
270 \interaction{branching.merge} |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
271 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
|
272 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
|
273 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
|
274 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
275 %\subsection{Feature branches} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
276 \subsection{$B5!G=$K$h$k%V%i%s%A(B} |
179
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
277 |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
278 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
|
279 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
|
280 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
|
281 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
|
282 isolated from developments on other branches. |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
283 |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
284 \begin{figure}[ht] |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
285 \centering |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
286 \grafix{feature-branches} |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
287 \caption{Feature branches} |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
288 \label{fig:collab:feature-branches} |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
289 \end{figure} |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
290 |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
291 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
|
292 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
|
293 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
|
294 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
295 %\subsection{The release train} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
296 \subsection{$B%j%j!<%9$N7R$,$j(B} |
179
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
297 |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
298 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
|
299 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
|
300 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
|
301 |
5fc4a45c069f
Continue documentation of collaboration models.
Bryan O'Sullivan <bos@serpentine.com>
parents:
159
diff
changeset
|
302 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
|
303 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
|
304 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
|
305 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
|
306 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
|
307 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
308 %\subsection{The Linux kernel model} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
309 \subsection{Linux$B%+!<%M%k%b%G%k(B} |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
310 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
311 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
|
312 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
|
313 Linux developers use \command{git}, a distributed revision control |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
314 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
|
315 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
|
316 approach translates well across tools. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
317 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
318 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
|
319 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
|
320 ``authoritative'' current tree by the entire developer community. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
321 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
|
322 he pulls from. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
323 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
324 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
|
325 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
|
326 reviewing those changes. Some of those lieutenants are generally |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
327 agreed to be ``maintainers'', responsible for specific subsystems |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
328 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
|
329 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
|
330 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
|
331 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
|
332 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
|
333 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
334 Individual lieutenants have their own approaches to reviewing, |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
335 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
|
336 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
|
337 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
|
338 ``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
|
339 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
|
340 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
|
341 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
|
342 tree. |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
343 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
344 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
|
345 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
|
346 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
|
347 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
|
348 that someone else controls. |
159
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 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
|
351 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
|
352 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
|
353 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
|
354 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
|
355 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
|
356 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
|
357 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
|
358 changes regularly to keep up with your work. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
359 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
360 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
|
361 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
|
362 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
|
363 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
|
364 complete stranger. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
365 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
366 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
|
367 comparatively chaotic Linux kernel development process often seems |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
368 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
|
369 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
|
370 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
|
371 well-regarded piece of software. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
372 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
373 %\subsection{Pull-only versus shared-push collaboration} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
374 \subsection{Pull$B$N$_BP6&M-(Bpush$B%3%i%\%l!<%7%g%s(B} |
187
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
184
diff
changeset
|
375 |
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
184
diff
changeset
|
376 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
|
377 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
|
378 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
|
379 shared repository. |
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
184
diff
changeset
|
380 |
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
184
diff
changeset
|
381 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
|
382 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
|
383 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
|
384 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
|
385 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
|
386 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
|
387 |
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
184
diff
changeset
|
388 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
|
389 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
|
390 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
|
391 what contortions your tools force you into. |
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
184
diff
changeset
|
392 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
393 %\subsection{Where collaboration meets branch management} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
394 \subsection{$B6&F1:n6H$,%V%i%s%A4IM}$HD>LL$9$k$H$3$m(B} |
187
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
184
diff
changeset
|
395 |
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
184
diff
changeset
|
396 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
|
397 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
|
398 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
|
399 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
|
400 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
|
401 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
|
402 chapter~\ref{chap:branch}. |
b60e2de6dbc3
Add chapter on branch management.
Bryan O'Sullivan <bos@serpentine.com>
parents:
184
diff
changeset
|
403 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
404 %\section{The technical side of sharing} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
405 \section{$B6&M-$N5;=QE*B&LL(B} |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
406 |
210
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
407 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
|
408 data to your collaborators. |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
409 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
410 %\section{Informal sharing with \hgcmd{serve}} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
411 \section{\hgcmd{serve}$B$K$h$kHs8x<0$J6&M-(B} |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
412 \label{sec:collab:serve} |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
413 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
414 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
|
415 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
|
416 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
|
417 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
418 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
|
419 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
|
420 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
|
421 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
|
422 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
|
423 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
|
424 \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
|
425 like \Verb|http://my-laptop.local:8000/|. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
426 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
427 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
|
428 It can do only two things: |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
429 \begin{itemize} |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
430 \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
|
431 serving, from their normal web browsers. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
432 \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
|
433 \hgcmd{clone} or \hgcmd{pull} changes from that repository. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
434 \end{itemize} |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
435 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
|
436 your repository. It's intended for read-only use. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
437 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
438 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
|
439 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
|
440 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
|
441 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
|
442 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
|
443 network-hosted repositories. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
444 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
445 %\subsection{A few things to keep in mind} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
446 \subsection{$B3P$($F$*$/$Y$-(B2, 3$B$NE@(B} |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
447 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
448 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
|
449 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
|
450 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
|
451 pull data from your repository. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
452 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
453 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
|
454 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
|
455 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
|
456 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
|
457 (\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
|
458 check your firewall configuration. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
459 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
460 By default, \hgcmd{serve} listens for incoming connections on |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
461 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
|
462 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
|
463 \hgopt{serve}{-p} option. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
464 |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
465 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
|
466 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
|
467 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
|
468 collaborators, start it with the \hggopt{-v} option. |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
469 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
470 %\section{Using the Secure Shell (ssh) protocol} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
471 \section{Secure Shell (ssh)$B%W%m%H%3%k$N;HMQ(B} |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
472 \label{sec:collab:ssh} |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
473 |
184
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
474 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
|
475 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
|
476 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
|
477 server sides. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
478 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
479 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
|
480 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
|
481 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
|
482 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
|
483 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
484 (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
|
485 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
|
486 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
487 %\subsection{How to read and write ssh URLs} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
488 \subsection{ssh$B$N(BURL$B$r$I$N$h$&$KFI$`$+(B} |
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 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
|
491 \begin{codesample2} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
492 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
|
493 \end{codesample2} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
494 \begin{enumerate} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
495 \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
|
496 protocol. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
497 \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
|
498 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
|
499 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
|
500 \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
|
501 server to log into. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
502 \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
|
503 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
|
504 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
|
505 \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
|
506 the server. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
507 \end{enumerate} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
508 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
509 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
|
510 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
|
511 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
|
512 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
|
513 read the following paragraphs carefully. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
514 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
515 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
|
516 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
|
517 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
|
518 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
|
519 \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
|
520 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
521 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
|
522 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
|
523 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
|
524 this. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
525 \begin{codesample2} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
526 ssh://server/~otheruser/hg/repo |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
527 \end{codesample2} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
528 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
529 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
|
530 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
|
531 \begin{codesample2} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
532 ssh://server//absolute/path |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
533 \end{codesample2} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
534 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
535 %\subsection{Finding an ssh client for your system} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
536 \subsection{$BMxMQCf$N%7%9%F%`8~$1$N(Bssh client$B$r8+$D$1$k(B} |
184
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
537 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
538 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
|
539 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
|
540 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
|
541 \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
|
542 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
|
543 it. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
544 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
545 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
|
546 client. There are two alternatives. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
547 \begin{itemize} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
548 \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
|
549 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
|
550 \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
|
551 port of OpenSSH. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
552 \end{itemize} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
553 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
|
554 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
|
555 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
|
556 a command-line ssh client. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
557 \begin{codesample2} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
558 [ui] |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
559 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
|
560 \end{codesample2} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
561 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
562 \begin{note} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
563 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
|
564 characters, or Mercurial may not be able to run it correctly (so |
264 | 565 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
|
566 idea). |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
567 \end{note} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
568 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
569 %\subsection{Generating a key pair} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
570 \subsection{$B%-!<%Z%"$N:n@.(B} |
184
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
571 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
572 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
|
573 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
|
574 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
|
575 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
|
576 what you'll need. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
577 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
578 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
|
579 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
|
580 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
|
581 on a secure network.) |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
582 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
583 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
|
584 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
|
585 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
|
586 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
|
587 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
|
588 directory. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
589 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
590 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
|
591 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
|
592 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
|
593 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
|
594 \sfilename{authorized\_keys} file. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
595 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
596 %\subsection{Using an authentication agent} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
597 \subsection{$BG'>Z%(!<%8%'%s%H$N;HMQ(B} |
184
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
598 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
599 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
|
600 (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
|
601 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
|
602 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
|
603 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
|
604 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
|
605 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
|
606 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
607 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
|
608 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
|
609 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
|
610 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
|
611 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
|
612 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
613 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
|
614 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
|
615 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
|
616 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
|
617 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
|
618 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
|
619 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
620 %\subsection{Configuring the server side properly} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
621 \subsection{$B%5!<%P$N@5$7$$@_Dj(B} |
184
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
622 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
623 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
|
624 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
|
625 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
|
626 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
|
627 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
|
628 usually continue to work indefinitely. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
629 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
630 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
|
631 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
|
632 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
|
633 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
|
634 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
|
635 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
|
636 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
|
637 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
|
638 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
639 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
|
640 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
|
641 \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
|
642 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
|
643 are as follows. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
644 \begin{itemize} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
645 \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
|
646 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
|
647 firewall configuration. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
648 \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
|
649 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
|
650 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
|
651 \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
|
652 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
|
653 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
|
654 \end{itemize} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
655 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
|
656 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
|
657 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
|
658 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
|
659 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
|
660 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
|
661 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
|
662 first. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
663 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
664 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
|
665 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
|
666 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
|
667 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
|
668 \begin{itemize} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
669 \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
|
670 \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
|
671 \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
|
672 \end{itemize} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
673 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
|
674 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
|
675 \begin{itemize} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
676 \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
|
677 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
|
678 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
|
679 \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
|
680 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
|
681 \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
|
682 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
|
683 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
|
684 \end{itemize} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
685 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
686 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
|
687 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
|
688 current date and time. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
689 \begin{codesample2} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
690 ssh myserver date |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
691 \end{codesample2} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
692 |
209
8b599dcca584
Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
693 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
|
694 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
|
695 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
|
696 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
|
697 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
|
698 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
|
699 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
|
700 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
|
701 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
|
702 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
|
703 command \Verb|tty -s|.) |
184
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
704 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
705 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
|
706 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
|
707 following command should run successfully: |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
708 \begin{codesample2} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
709 ssh myserver hg version |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
710 \end{codesample2} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
711 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
|
712 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
|
713 \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
|
714 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
|
715 \begin{itemize} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
716 \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
|
717 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
|
718 \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
|
719 environment variable) is simply misconfigured. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
720 \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
|
721 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
|
722 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
|
723 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
|
724 details. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
725 \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
|
726 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
|
727 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
|
728 interactive. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
729 \end{itemize} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
730 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
731 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
|
732 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
|
733 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
|
734 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
|
735 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
|
736 of what's going on. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
737 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
738 %\subsection{Using compression with ssh} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
739 \subsection{ssh$B$G$N05=L$NMxMQ(B} |
184
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
740 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
741 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
|
742 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
|
743 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
|
744 compression. |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
745 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
746 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
|
747 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
|
748 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
|
749 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
|
750 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
|
751 |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
752 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
|
753 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
|
754 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
|
755 \begin{codesample2} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
756 [ui] |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
757 ssh = ssh -C |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
758 \end{codesample2} |
7b812c428074
Document the ssh protocol, URL syntax, and configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
179
diff
changeset
|
759 |
209
8b599dcca584
Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
760 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
|
761 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
|
762 \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
|
763 \begin{codesample2} |
8b599dcca584
Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
764 Host hg |
8b599dcca584
Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
765 Compression yes |
8b599dcca584
Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
766 HostName hg.example.com |
8b599dcca584
Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
767 \end{codesample2} |
8b599dcca584
Mention what the web interface does.
Bryan O'Sullivan <bos@serpentine.com>
parents:
187
diff
changeset
|
768 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
|
769 \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
|
770 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
|
771 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
|
772 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
|
773 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
774 %\section{Serving over HTTP using CGI} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
775 \section{CGI$B$r;HMQ$7$?(BHTTP$B$G$N%5!<%S%9(B} |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
776 \label{sec:collab:cgi} |
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
777 |
210
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
778 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
|
779 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
|
780 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
781 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
|
782 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
|
783 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
|
784 configuration. |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
785 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
786 \begin{note} |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
787 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
|
788 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
|
789 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
|
790 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
|
791 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
|
792 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
|
793 \end{note} |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
794 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
795 %\subsection{Web server configuration checklist} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
796 \subsection{Web$B%5!<%P@_Dj$N%A%'%C%/%j%9%H(B} |
210
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 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
|
799 your system's setup. |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
800 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
801 \begin{enumerate} |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
802 \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
|
803 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
|
804 \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
|
805 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
|
806 default. |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
807 \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
|
808 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
|
809 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
|
810 \end{enumerate} |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
811 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
812 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
|
813 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
|
814 \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
|
815 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
|
816 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
|
817 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
|
818 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
|
819 to get started with than Apache. |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
820 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
821 %\subsection{Basic CGI configuration} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
822 \subsection{CGI$B$N4pK\E*$J@_Dj(B} |
210
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
823 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
824 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
|
825 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
|
826 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
|
827 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
|
828 \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
|
829 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
830 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
|
831 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
|
832 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
|
833 Mercurial repository at |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
834 \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
|
835 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
836 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
|
837 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
|
838 \begin{codesample2} |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
839 cp .../hgweb.cgi ~/public_html |
211
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
840 chmod 755 ~/public_html/hgweb.cgi |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
841 \end{codesample2} |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
842 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
|
843 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
|
844 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
|
845 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
|
846 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
|
847 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
|
848 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
|
849 writable by others. |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
850 \begin{codesample2} |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
851 chmod 755 ~/public_html |
210
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
852 \end{codesample2} |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
853 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
854 %\subsubsection{What could \emph{possibly} go wrong?} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
855 \subsubsection{$B$I$3$,LdBj$H@.$jF@$k$+(B?} |
211
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
856 \label{sec:collab:wtf} |
210
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
857 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
858 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
|
859 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
|
860 \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
|
861 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
|
862 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
|
863 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
|
864 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
|
865 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
|
866 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
|
867 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
868 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
|
869 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
|
870 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
|
871 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
|
872 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
|
873 \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
|
874 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
|
875 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
876 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
|
877 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
|
878 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
|
879 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
|
880 appropriate. |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
881 \begin{codesample2} |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
882 chmod 755 ~ |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
883 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
|
884 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
|
885 \end{codesample2} |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
886 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
887 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
|
888 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
|
889 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
|
890 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
|
891 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
|
892 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
893 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
|
894 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
|
895 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
|
896 \begin{codesample2} |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
897 <Directory /home/*/public_html> |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
898 AllowOverride FileInfo AuthConfig Limit |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
899 Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
900 <Limit GET POST OPTIONS> |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
901 Order allow,deny |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
902 Allow from all |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
903 </Limit> |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
904 <LimitExcept GET POST OPTIONS> |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
905 Order deny,allow |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
906 Deny from all |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
907 </LimitExcept> |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
908 </Directory> |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
909 \end{codesample2} |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
910 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
|
911 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
|
912 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
|
913 restart the web server. |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
914 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
915 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
|
916 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
|
917 or add a directive like this. |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
918 \begin{codesample2} |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
919 AddHandler cgi-script .cgi |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
920 \end{codesample2} |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
921 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
922 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
|
923 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
|
924 \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
|
925 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
|
926 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
|
927 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
|
928 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
|
929 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
|
930 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
|
931 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
|
932 environment variable. |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
933 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
934 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
|
935 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
|
936 \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
|
937 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
|
938 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
|
939 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
940 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
|
941 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
|
942 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
943 %\subsubsection{Configuring lighttpd} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
944 \subsubsection{lighttpd$B$N@_Dj(B} |
210
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
945 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
946 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
|
947 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
|
948 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
|
949 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
|
950 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
|
951 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
|
952 script was properly edited. |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
953 |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
954 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
|
955 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
|
956 \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
|
957 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
|
958 \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
|
959 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
|
960 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
|
961 \begin{codesample2} |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
962 userdir.path = "public_html" |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
963 cgi.assign = ( ".cgi" => "" ) |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
964 \end{codesample2} |
27b2c7c46af3
Start talking about basic CGI/HTTP configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
209
diff
changeset
|
965 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
|
966 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
|
967 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
|
968 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
|
969 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
|
970 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
|
971 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
972 %\subsection{Sharing multiple repositories with one CGI script} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
973 \subsection{1$B$D$N(BCGI$B%9%/%j%W%H$GJ#?t$N%j%]%8%H%j$r6&M-$9$k(B} |
211
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
974 |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
975 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
|
976 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
|
977 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
|
978 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
|
979 \sfilename{hgwebdir.cgi} script. |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
980 |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
981 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
|
982 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
|
983 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
|
984 copy from the master Mercurial repository at |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
985 \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
|
986 |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
987 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
|
988 directory, and ensure that it's executable. |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
989 \begin{codesample2} |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
990 cp .../hgwebdir.cgi ~/public_html |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
991 chmod 755 ~/public_html ~/public_html/hgwebdir.cgi |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
992 \end{codesample2} |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
993 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
|
994 \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
|
995 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
|
996 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
|
997 problems in section~\ref{sec:collab:wtf}. |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
998 |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
999 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
|
1000 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
|
1001 \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
|
1002 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
|
1003 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
|
1004 \texttt{ConfigParser}~\cite{web:configparser} module. |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
1005 |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
1006 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
|
1007 section named \texttt{collections}. This will automatically publish |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
1008 \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
|
1009 should look like this: |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
1010 \begin{codesample2} |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
1011 [collections] |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
1012 /my/root = /my/root |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
1013 \end{codesample2} |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
1014 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
|
1015 \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
|
1016 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
|
1017 \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
|
1018 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
|
1019 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
|
1020 |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
1021 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
|
1022 \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
|
1023 \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
|
1024 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
|
1025 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
|
1026 URL for that repository will be |
211
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
1027 \url{http://myhostname/~myuser/hgwebdir.cgi/this/repo}. |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
1028 |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
1029 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
|
1030 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
|
1031 \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
|
1032 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
|
1033 |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
1034 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
|
1035 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
|
1036 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
|
1037 repositories it finds. |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
1038 |
b461d7ead9e1
Start to document hgwebdir.cgi.
Bryan O'Sullivan <bos@serpentine.com>
parents:
210
diff
changeset
|
1039 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
|
1040 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
|
1041 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
|
1042 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
|
1043 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
|
1044 \sfilename{hgwebdir.cgi} to look. |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
1045 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
1046 %\subsubsection{Explicitly specifying which repositories to publish} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
1047 \subsubsection{$B$I$N%j%]%8%H%j$rI=<($9$k$+L@<(E*$K;XDj$9$k(B} |
212
ef8a5e393103
Mention the paths section of a hgwebdir config file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
211
diff
changeset
|
1048 |
ef8a5e393103
Mention the paths section of a hgwebdir config file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
211
diff
changeset
|
1049 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
|
1050 \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
|
1051 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
|
1052 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
|
1053 \begin{codesample2} |
ef8a5e393103
Mention the paths section of a hgwebdir config file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
211
diff
changeset
|
1054 [paths] |
ef8a5e393103
Mention the paths section of a hgwebdir config file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
211
diff
changeset
|
1055 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
|
1056 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
|
1057 \end{codesample2} |
ef8a5e393103
Mention the paths section of a hgwebdir config file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
211
diff
changeset
|
1058 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
|
1059 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
|
1060 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
|
1061 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
|
1062 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
|
1063 |
ef8a5e393103
Mention the paths section of a hgwebdir config file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
211
diff
changeset
|
1064 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
|
1065 \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
|
1066 file. |
ef8a5e393103
Mention the paths section of a hgwebdir config file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
211
diff
changeset
|
1067 |
ef8a5e393103
Mention the paths section of a hgwebdir config file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
211
diff
changeset
|
1068 \begin{note} |
ef8a5e393103
Mention the paths section of a hgwebdir config file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
211
diff
changeset
|
1069 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
|
1070 \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
|
1071 behave unpredictably. |
ef8a5e393103
Mention the paths section of a hgwebdir config file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
211
diff
changeset
|
1072 \end{note} |
ef8a5e393103
Mention the paths section of a hgwebdir config file.
Bryan O'Sullivan <bos@serpentine.com>
parents:
211
diff
changeset
|
1073 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
1074 %\subsection{Downloading source archives} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
1075 \subsection{$B%=!<%9%"!<%+%$%V$N%@%&%s%m!<%I(B} |
215
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1076 |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1077 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
|
1078 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
|
1079 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
|
1080 repository data. |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1081 |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1082 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
|
1083 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
|
1084 section of your \hgrc. |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1085 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
1086 %\subsection{Web configuration options} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
1087 \subsection{Web$B@_Dj%*%W%7%g%s(B} |
215
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1088 |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1089 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
|
1090 \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
|
1091 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
|
1092 section named \rcsection{web}. |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1093 \begin{itemize} |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1094 \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
|
1095 download mechanisms Mercurial supports. If you enable this |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1096 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
|
1097 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
|
1098 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
|
1099 sequence of words drawn from the list below. |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1100 \begin{itemize} |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1101 \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
|
1102 \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
|
1103 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
|
1104 \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
|
1105 \texttt{gzip} compression. |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1106 \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
|
1107 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
|
1108 widely used in the Windows world. |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1109 \end{itemize} |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1110 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
|
1111 \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
|
1112 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
|
1113 formats. |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1114 \begin{codesample4} |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1115 [web] |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1116 allow_archive = bz2 gz zip |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1117 \end{codesample4} |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1118 \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
|
1119 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
|
1120 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
|
1121 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
|
1122 \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
|
1123 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
|
1124 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
|
1125 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
|
1126 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
|
1127 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
|
1128 maintainer. |
215
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1129 \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
|
1130 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
|
1131 \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
|
1132 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
|
1133 \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
|
1134 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
|
1135 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
|
1136 rows in each stripe. |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1137 \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
|
1138 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
|
1139 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
|
1140 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
|
1141 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
|
1142 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
|
1143 \begin{codesample4} |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1144 [web] |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1145 style = gitweb |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1146 \end{codesample4} |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1147 \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
|
1148 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
|
1149 in which it was installed. |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1150 \end{itemize} |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1151 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
|
1152 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
|
1153 \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
|
1154 convenience. These items are \rcitem{web}{motd} and |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1155 \rcitem{web}{style}. |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1156 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
1157 %\subsubsection{Options specific to an individual repository} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
1158 \subsubsection{$B8D!9$N%j%]%8%H%j$KFCM-$N%*%W%7%g%s(B} |
216
699771d085c6
More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
215
diff
changeset
|
1159 |
699771d085c6
More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
215
diff
changeset
|
1160 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
|
1161 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
|
1162 global \hgrc. |
699771d085c6
More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
215
diff
changeset
|
1163 \begin{itemize} |
699771d085c6
More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
215
diff
changeset
|
1164 \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
|
1165 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
|
1166 repository. |
699771d085c6
More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
215
diff
changeset
|
1167 \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
|
1168 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
|
1169 last component of the repository's path. |
699771d085c6
More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
215
diff
changeset
|
1170 \end{itemize} |
699771d085c6
More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
215
diff
changeset
|
1171 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
1172 %\subsubsection{Options specific to the \hgcmd{serve} command} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
1173 \subsubsection{\hgcmd{serve}$B%3%^%s%IFCM-$N%*%W%7%g%s(B} |
215
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1174 |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1175 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
|
1176 only for use with the \hgcmd{serve} command. |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1177 \begin{itemize} |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1178 \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
|
1179 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
|
1180 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
|
1181 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
|
1182 web servers. |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1183 \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
|
1184 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
|
1185 server listens on all addresses. |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1186 \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
|
1187 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
|
1188 information to standard error, not to a file. |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1189 \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
|
1190 By default, IPv6 is not used. |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1191 \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
|
1192 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
|
1193 \end{itemize} |
70e1f8448699
Document some hgweb config options.
Bryan O'Sullivan <bos@serpentine.com>
parents:
212
diff
changeset
|
1194 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
1195 %\subsubsection{Choosing the right \hgrc\ file to add \rcsection{web} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
1196 %items to} |
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
1197 \subsubsection{\rcsection{web}$B%"%$%F%`$rDI2C$9$k@5$7$$(B\hgrc $B%U%!%$%k$rA*$V(B} |
216
699771d085c6
More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
215
diff
changeset
|
1198 |
699771d085c6
More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
215
diff
changeset
|
1199 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
|
1200 \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
|
1201 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
|
1202 usually also run under that user~ID. |
699771d085c6
More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
215
diff
changeset
|
1203 |
699771d085c6
More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
215
diff
changeset
|
1204 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
|
1205 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
|
1206 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
|
1207 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
|
1208 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
|
1209 those settings to a system-wide \hgrc\ file. |
699771d085c6
More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
215
diff
changeset
|
1210 |
699771d085c6
More notes on web configuration.
Bryan O'Sullivan <bos@serpentine.com>
parents:
215
diff
changeset
|
1211 |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
1212 %%% Local Variables: |
293
3b1291f24c0d
- replaved latex-mode to yatex-mode
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
290
diff
changeset
|
1213 %%% mode: yatex |
159
7355af913937
First steps on collaboration chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
1214 %%% TeX-master: "00book" |
367
586bd91d0c84
- translated title page.
Yoshiki Yazawa <yaz@honeyplanet.jp>
parents:
293
diff
changeset
|
1215 %%% End: |