annotate ja/collab.tex @ 370:47830e17cd00

more collab.tex

%\chapter{Collaborating with other people}
\chapter{$BB>$N?M!9$H$N6&F1:n6H(B}
\label{cha:collab}

%As a completely decentralised tool, Mercurial doesn't impose any
%policy on how people ought to work with each other.  However, if
%you're new to distributed revision control, it helps to have some
%tools and examples in mind when you're thinking about possible
%workflow models.

$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
$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
$B%k%D!<%k$r;H$&$N$G$"$l$P!$$$$/$D$+$N%D!<%k$N;HMQK!$H;HMQNc$rCN$k$3$H$,(B
$B<h$jF@$k%o!<%/%U%m!<%b%G%k$r9M$($k:]$K=u$1$H$J$k$G$"$m$&!%(B

%\section{Mercurial's web interface}
\section{Mercurial$B$N%&%'%V%$%s%?%U%'!<%9(B}

%Mercurial has a powerful web interface that provides several
%useful capabilities.

Mercurial$B$O$$$/$D$+$NM-MQ$J5!G=$r;}$D6/NO$J%&%'%V%$%s%?%U%'!<%9$rHw$($F(B
$B$$$k!%(B

%For interactive use, the web interface lets you browse a single
%repository or a collection of repositories.  You can view the history
%of a repository, examine each change (comments and diffs), and view
%the contents of each directory and file.

$BBPOCE*$JMxMQ$G$O!$%&%'%V%$%s%?%U%'!<%9$K$h$j(B1$B$D$N%j%]%8%H%j$^$?$O$$$/$D$+(B
$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
$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
$B$NFbMF$r8+$k$3$H$,$G$-$k!%(B

%Also for human consumption, the web interface provides an RSS feed of
%the changes in a repository.  This lets you ``subscribe'' to a
%repository using your favourite feed reader, and be automatically
%notified of activity in that repository as soon as it happens.  I find
%this capability much more convenient than the model of subscribing to
%a mailing list to which notifications are sent, as it requires no
%additional configuration on the part of whoever is serving the
%repository.

$B%&%'%V%$%s%?%U%'!<%9$O1\MwMQ$K%j%]%8%H%j$NJQ99$N(BRSS$B%U%#!<%I$rDs6!$9$k!%$3(B
$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
$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
$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
$B%s%0%j%9%H$r9XFI$7$FDLCN$r<u$1$k%b%G%k$h$j$b$:$C$HJXMx$G$"$k!%(B

%The web interface also lets remote users clone a repository, pull
%changes from it, and (when the server is configured to permit it) push
%changes back to it.  Mercurial's HTTP tunneling protocol aggressively
%compresses data, so that it works efficiently even over low-bandwidth
%network connections.

$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
$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
$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
$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
$BG=$9$k!%(B

%The easiest way to get started with the web interface is to use your
%web browser to visit an existing repository, such as the master
%Mercurial repository at
%\url{http://www.selenic.com/repo/hg?style=gitweb}.

$B%&%'%V%$%s%?%U%'!<%9$N:G$b4JC1$J;O$aJ}$O%&%'%V%V%i%&%6$r;H$C$F(BMercurial$B$N(B
$B%^%9%?%j%]%8%H%j(B\url{http://www.selenic.com/repo/hg?style=gitweb}$B$N$h$&$J(B
$B4{B8$N%j%]%8%H%j$r;2>H$9$k$3$H$G$"$k!%(B

%If you're interested in providing a web interface to your own
%repositories, Mercurial provides two ways to do this.  The first is
%using the \hgcmd{serve} command, which is best suited to short-term
%``lightweight'' serving.  See section~\ref{sec:collab:serve} below for
%details of how to use this command.  If you have a long-lived
%repository that you'd like to make permanently available, Mercurial
%has built-in support for the CGI (Common Gateway Interface) standard,
%which all common web servers support.  See
%section~\ref{sec:collab:cgi} for details of CGI configuration.

$B<+J,$N%j%]%8%H%j$K%&%'%V%$%s%?%U%'!<%9$rMQ0U$9$k>l9g!$(B2$BDL$j$N$d$jJ}$,$"(B
$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
$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
$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
$B$K%5!<%S%9$7$?$$>l9g$O!$(BMercurial$B$KFbB"$N(BCGI(Common Gateway Interface)$B%5(B
$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
$B$r;2>H$N$3$H!%(B

%\section{Collaboration models}
\section{$B6&F1:n6H%b%G%k(B}

%With a suitably flexible tool, making decisions about workflow is much
%more of a social engineering challenge than a technical one.
%Mercurial imposes few limitations on how you can structure the flow of
%work in a project, so it's up to you and your group to set up and live
%with a model that matches your own particular needs.

$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
$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
$B%o!<%/%U%m!<$K2]$9@)8B$O$[$H$s$I$J$$$?$a!$$3$l$r$$$+$K9=C[$9$k$+$O$"$J$?(B
$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
$B$-$k!%(B

%\subsection{Factors to keep in mind}
\subsection{$B9MN8$9$Y$-MWAG(B}

%The most important aspect of any model that you must keep in mind is
%how well it matches the needs and capabilities of the people who will
%be using it.  This might seem self-evident; even so, you still can't
%afford to forget it for a moment.

$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
$B$N$G$"$k$+$r>o$KG0F,$KCV$/$3$H$,:G$b=EMW$G$"$k!%(B
$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

%I once put together a workflow model that seemed to make perfect sense
%to me, but that caused a considerable amount of consternation and
%strife within my development team.  In spite of my attempts to explain
%why we needed a complex set of branches, and how changes ought to flow
%between them, a few team members revolted.  Even though they were
%smart people, they didn't want to pay attention to the constraints we
%were operating under, or face the consequences of those constraints in
%the details of the model that I was advocating.

$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
$B%`$K$H$C$F$OBg$-$J6C$-$H3kF#$rM?$($F$7$^$C$?$3$H$,$"$k!%J#;($J%V%i%s%A$N(B
$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
$B$b$+$+$o$i$:!$4v?M$+$N%A!<%`%a%s%P!<$OH?H/$7$?!%H`$i$OAoL@$G$"$C$?$,!$;d(B
$B$,94$C$?%k!<%k$,:n6H$KM?$($k@)8B$d!$%b%G%k$N:YIt$KM?$($k1F6A$KCm0U$rJ'$&(B
$B$3$H$OK>$^$J$+$C$?!%(B

%Don't sweep foreseeable social or technical problems under the rug.
%Whatever scheme you put into effect, you should plan for mistakes and
%problem scenarios.  Consider adding automated machinery to prevent, or
%quickly recover from, trouble that you can anticipate.  As an example,
%if you intend to have a branch with not-for-release changes in it,
%you'd do well to think early about the possibility that someone might
%accidentally merge those changes into a release branch.  You could
%avoid this particular problem by writing a hook that prevents changes
%from being merged from an inappropriate branch.

$B>-Mh5/$3$jF@$k<R2qE*$^$?$O5;=QE*LdBj$KL\$rbT$C$F$O$J$i$J$$!%$I$N$h$&$JJ}(B
$BK!$r$H$k$K$7$F$b!$4V0c$$$dLdBj$,5/$-$?>l9g$KHw$($F$*$/I,MW$,$"$k!%A[A|$7(B
$BF@$k%H%i%V%k$rKI;_$7$?$j!$%H%i%V%k$+$iAGAa$/2sI|$5$;$k$?$a$N<+F02=$5$l$?(B
$BJ}K!$r9M$($F$*$/I,MW$,$"$k!%$?$H$($P!$%j%j!<%9$K4^$a$J$$JQ99$r9T$C$?%V%i(B
$B%s%A$,$"$k$H$7$?$i!$C/$+$,8m$C$F$=$3$+$i%j%j!<%9%V%i%s%A$KJQ99$r%^!<%8$7(B
$B$F$7$^$&2DG=@-$K$D$$$F8!F$$7$F$*$/$Y$-$G$"$k!%$3$N>l9g$G$"$l$P!$ITE,@Z$J(B
$B%V%i%s%A$+$i$N%^!<%8$r6X;_$9$k%U%C%/$rMQ0U$9$k$3$H$GLdBj$r2sHr$9$k$3$H$,(B
$B$G$-$k!%(B

%\subsection{Informal anarchy}
\subsection{$BHs8x<0$J:.Mp(B}

%I wouldn't suggest an ``anything goes'' approach as something
%sustainable, but it's a model that's easy to grasp, and it works
%perfectly well in a few unusual situations.

$B$3$3$G=R$Y$k(B``$B$J$s$G$b$"$j(B''$B%"%W%m!<%A$,;}B32DG=$G$"$k$H8@$$$?$$$o$1$G$O(B
$B$J$$$N$@$,!$$3$N%b%G%k$OGD0.$7$d$9$/!$$$$/$D$+$N>u67$G$O$&$^$/5!G=$9$k$b(B
$B$N$@!%(B

%As one example, many projects have a loose-knit group of collaborators
%who rarely physically meet each other.  Some groups like to overcome
%the isolation of working at a distance by organising occasional
%``sprints''.  In a sprint, a number of people get together in a single
%location (a company's conference room, a hotel meeting room, that kind
%of place) and spend several days more or less locked in there, hacking
%intensely on a handful of projects.

$BNc$($P%W%m%8%'%/%H$NB?$/$O<B:]$K$O$[$H$s$I2q$&$3$H$N$J$$6(NO<T$?$A$N4K$d(B
$B$+$J%0%k!<%W$r;}$D!%%0%k!<%W$N$$$/$D$+$O5!2qKh$KC;$$(B``$B%9%W%j%s%H(B''$B$r7A@.(B
$B$7!$N%$l$?>l=j$G$N3V@d$7$?:n6H$r9nI~$7$F$$$k!%%9%W%j%s%H$G$O!$!J4k6H$N2q(B
$B5D<<!$%[%F%k$N%_!<%F%#%s%0%k!<%`$N$h$&$J!K0l%+=j$K=8$^$C$F?tF|4V$K$o$?$C(B
$B$F>/?t$N%W%m%8%'%/%H$r=8CfE*$K%O%C%/$9$k!%(B

%A sprint is the perfect place to use the \hgcmd{serve} command, since
%\hgcmd{serve} does not requires any fancy server infrastructure.  You
%can get started with \hgcmd{serve} in moments, by reading
%section~\ref{sec:collab:serve} below.  Then simply tell the person
%next to you that you're running a server, send the URL to them in an
%instant message, and you immediately have a quick-turnaround way to
%work together.  They can type your URL into their web browser and
%quickly review your changes; or they can pull a bugfix from you and
%verify it; or they can clone a branch containing a new feature and try
%it out.

$B%9%W%j%s%H$O(B\hgcmd{serve}$B%3%^%s%I$r;H$&$N$^$5$K$K$&$C$F$D$1$N4D6-$G$"$k!%(B
\hgcmd{serve}$B$O<j$N9~$s$@%5!<%P@_Hw$rI,MW$H$7$J$$!%2<$N(B
\ref{sec:collab:serve}$B%;%/%7%g%s$rFI$s$G$9$0$K(B\hgcmd{serve}$B%3%^%s%I$r;H$&(B
$B$3$H$,$G$-$k!%%5!<%P$r5/F0$7$F$$$k$3$H$rNY$N3+H/<T$KOC$7$?$j!$%0%k!<%W$K(B
URL$B$r%$%s%9%?%s%H%a%C%;!<%8$GAw$l$P!$$9$0$K?WB.$J6&F1:n6H$,$G$-$k!%(B
$BAw$C$?(BURL$B$rB>$N3+H/<T$,%V%i%&%6$KF~NO$9$l$P!$H`$i$O4JC1$K$"$J$?$NJQ99$r%l(B
$B%S%e!<$9$k$3$H$,$G$-$k$7!$$"$J$?$N9T$C$?%P%0%U%#%C%/%9$r(Bpull$B$7$F8!>Z$9$k(B
$B$3$H$b$G$-$k!%$5$i$K!$?75!G=$N<BAu$5$l$?%V%i%s%A$r%/%m!<%s$7$F;n$9$3$H$b(B
$B$G$-$k!%(B

%The charm, and the problem, with doing things in an ad hoc fashion
%like this is that only people who know about your changes, and where
%they are, can see them.  Such an informal approach simply doesn't
%scale beyond a handful people, because each individual needs to know
%about $n$ different repositories to pull from.

$B%"%I%[%C%/$J$d$jJ}$G9T$&6&F1:n6H$NL%NO$HLdBj$O!$$"$J$?$NJQ99$rCN$C$F$$(B
$B$F!$>l=j$bJ,$+$C$F$$$k?M!9$7$+JQ99$r;2>H$G$-$J$$$3$H$G$"$k!%$3$N$h$&$JHs(B
$B8x<0$J%"%W%m!<%A$O!$3F?M$,(B$n$$B8D$N0[$J$C$?%j%]%8%H%j$N$I$l$+$i(Bpull$B$r9T$($P(B
$B$$$$$+J,$+$C$F$$$kI,MW$,$"$k$?$a!$>/?M?t0J>e$K%9%1!<%k$7$J$$!%(B


%\subsection{A single central repository}
\subsection{1$B$D$N=8Cf%j%]%8%H%j(B}

%For smaller projects migrating from a centralised revision control
%tool, perhaps the easiest way to get started is to have changes flow
%through a single shared central repository.  This is also the
%most common ``building block'' for more ambitious workflow schemes.

$B=8Cf7?%j%S%8%g%s%3%s%H%m!<%k%D!<%k$r;H$C$F$$$?>.5,LO$J%W%m%8%'%/%H$,0\9T(B
$B$9$k>l9g$K$O!$Cf1{$KC10l$N6&M-%j%]%8%H%j$r@_$1$F!$$=$NCf$GJQ99$r4IM}$9$k(B
$B$N$,:G$b4JC1$JJ}K!$G$"$m$&!%$3$N$h$&$J%j%]%8%H%j$O$b$C$H[#Kf$J%o!<%/%U%m!<(B
$B%9%-!<%`$K$H$C$F$b6&DL$N4pHW$H$J$k!%(B

%Contributors start by cloning a copy of this repository.  They can
%pull changes from it whenever they need to, and some (perhaps all)
%developers have permission to push a change back when they're ready
%for other people to see it.

$B6(NO<T$O%j%]%8%H%j$N%3%T!<$r%/%m!<%s$9$k$3$H$+$i;O$a$k!%$=$7$FI,MW$J;~$K(B
$BJQ99$r(Bpull$B$7!$4v?M$+$N!JA40w$+$b$7$l$J$$!K3+H/<T$O!$<+J,$N9T$C$?JQ99$rI,(B
$BMW$J;~$K(Bpush$B$9$k8"8B$r;}$D!%(B

%Under this model, it can still often make sense for people to pull
%changes directly from each other, without going through the central
%repository.  Consider a case in which I have a tentative bug fix, but
%I am worried that if I were to publish it to the central repository,
%it might subsequently break everyone else's trees as they pull it.  To
%reduce the potential for damage, I can ask you to clone my repository
%into a temporary repository of your own and test it.  This lets us put
%off publishing the potentially unsafe change until it has had a little
%testing.

$B$3$N%b%G%k$G$b!$Cf1{$N%j%]%8%H%j$r;2>H$;$:B>$N3+H/<T$N%j%]%8%H%j$+$iD>@\(B
$BJQ99$r(Bpull$B$9$k$3$H$K$O0UL#$,$"$k!%<j85$G2>$N%P%0=$@5$r9T$C$?$,!$$3$l$rCf(B
$B1{$N%j%]%8%H%j$G8x3+$7!$B>$N3+H/<TC#$,(Bpull$B$9$k$H3F!9$N%=!<%9%D%j!<$,2u$l(B
$B$k$*$=$l$,$"$k>l9g$r9M$($k!%%@%a!<%8$N2DG=@-$r2<$2$k$?$a$K!$JL$N3+H/<T$K(B
$B<+J,$N%j%]%8%H%j$r%/%m!<%s$7!$%F%9%H$9$k$3$H$r0MMj$9$k$3$H$,9M$($i$l$k!%(B
$B$3$NJ}K!$r<h$k$3$H$G!$:GDc8B$N%F%9%H$r9T$&$^$G!$LdBj$N$"$k2DG=@-$N$"$kJQ(B
$B99$r8x3+$9$k$3$H$r0z$-1d$P$9$3$H$,$G$-$k!%(B

%In this kind of scenario, people usually use the \command{ssh}
%protocol to securely push changes to the central repository, as
%documented in section~\ref{sec:collab:ssh}.  It's also usual to
%publish a read-only copy of the repository over HTTP using CGI, as in
%section~\ref{sec:collab:cgi}.  Publishing over HTTP satisfies the
%needs of people who don't have push access, and those who want to use
%web browsers to browse the repository's history.

$B$3$N>u67$G$O!$3+H/<T$?$A$ODL>o!$Cf1{$N%j%]%8%H%j$XJQ99$r%W%C%7%e$9$k$?$a(B
$B$K!$(B~\ref{sec:collab:ssh}$B@a$G@bL@$7$?$h$&$K(B\command{ssh}$B%W%m%H%3%k$rMQ$$(B
$B$k!%$^$?(B~\ref{sec:collab:cgi}$B@a$G=R$Y$?$h$&$K!$%j%]%8%H%j$NFI$_<h$j@lMQ%3(B
$B%T!<$r(BCGI$B$rMQ$$$?(BHTTP$B$G8x3+$9$k$N$b0lHLE*$G$"$k!%(B HTTP$B$K$h$k8x3+$G!$%W%C(B
$B%7%e%"%/%;%98"$r;}$?$J$$?M!9$d%j%]%8%H%j$NMzNr$r%V%i%&%6$G;2>H$7$?$$?M$N(B
$B%K!<%:$rK~$?$9$3$H$,$G$-$k!%(B

%\subsection{Working with multiple branches}
\subsection{$BJ#?t$N%V%i%s%A$G$N:n6H(B}

%Projects of any significant size naturally tend to make progress on
%several fronts simultaneously.  In the case of software, it's common
%for a project to go through periodic official releases.  A release
%might then go into ``maintenance mode'' for a while after its first
%publication; maintenance releases tend to contain only bug fixes, not
%new features.  In parallel with these maintenance releases, one or
%more future releases may be under development.  People normally use
%the word ``branch'' to refer to one of these many slightly different
%directions in which development is proceeding.

$B$"$kDxEY$N5,LO$N%W%m%8%'%/%H$G$O!$<+$:$H$$$/$D$b$NA0@~$G3+H/$r?J$a$F$$$/(B
$B$h$&$K$J$k!%%=%U%H%&%'%"$N>l9g!$Dj4|E*$K8x<0%j%j!<%9$r9T$&$N$,DLNc$G$"(B
$B$k!%%j%j!<%9$O!$8x3+8e;C$/$7$F(B``$B%a%s%F%J%s%9%b!<%I(B''$B$K0\9T$9$k$+$b$7$l$J(B
$B$$!%%a%s%F%J%s%9%j%j!<%9$G$O%P%0$N=$@5$@$1$r9T$$!$?75!G=$NDI2C$O9T$o$J$$(B
$B$N$,DLNc$G$"$k!%$3$l$i$N%a%s%F%J%s%9%j%j!<%9$HJB9T$7$F!$>-Mh$N%j%j!<%9$,(B
$B3+H/$5$l$k!%DL>o!$3+H/$N?J9T$7$F$$$/<c430[$J$C$?J}8~$N3F!9$rI=$9$?$a$K(B
``$B%V%i%s%A(B''$B$H$$$&8F>N$rMQ$$$k!%(B

%Mercurial is particularly well suited to managing a number of
%simultaneous, but not identical, branches.  Each ``development
%direction'' can live in its own central repository, and you can merge
%changes from one to another as the need arises.  Because repositories
%are independent of each other, unstable changes in a development
%branch will never affect a stable branch unless someone explicitly
%merges those changes in.

Mercurial$B$OJ#?t%V%i%s%A$K$h$kF1;~3+H/$r<h$j07$&$3$H$KFC$KE,$7$F$$$k!%3F!9(B
$B$N(B``$B3+H/J}8~(B''$B$OCf1{%j%]%8%H%j$KCV$/$3$H$,2DG=$G!$I,MW$K$J$kEY$K$"$k%V%i(B
$B%s%A$+$iJL$N%V%i%s%A$X%^!<%8$G$-$k!%%j%]%8%H%j$O$=$l$>$lFHN)$G$"$k$?$a!$(B
$B3+H/%V%i%s%A$G$NIT0BDj$JJQ99$O!$3+H/<T$NC/$+$,L@<(E*$K%^!<%8$r9T$o$J$$8B(B
$B$j0BDjHG%V%i%s%A$K$O$J$s$N1F6A$bM?$($J$$!%(B

%Here's an example of how this can work in practice.  Let's say you
%have one ``main branch'' on a central server.
%\interaction{branching.init}
%People clone it, make changes locally, test them, and push them back.

$B<B:]$K$I$N$h$&$KF0:n$9$k$N$+$rNc$G<($9!%Cf1{$N%5!<%P$K(B1$B$D$N(B``$B%a%$%s%V%i(B
$B%s%A(B''$B$,$"$k$H$7$h$&!%(B
\interaction{branching.init}
$B3+H/<T$O$3$l$r%/%m!<%s$7!$%m!<%+%k$GJQ99$r2C$(!$%F%9%H$7!$$^$?(Bpush$B$9$k$H(B
$B$9$k!%(B

%Once the main branch reaches a release milestone, you can use the
%\hgcmd{tag} command to give a permanent name to the milestone
%revision.
%\interaction{branching.tag}
%Let's say some ongoing development occurs on the main branch.
%\interaction{branching.main}
%Using the tag that was recorded at the milestone, people who clone
%that repository at any time in the future can use \hgcmd{update} to
%get a copy of the working directory exactly as it was when that tagged
%revision was committed.
%\interaction{branching.update}

$B%a%$%s%V%i%s%A$,%j%j!<%9%^%$%k%9%H!<%s$KE~C#$7$?:]$K!$(B\hgcmd{tag}$B$G1JB3E*(B
$B$JL>A0$r%^%$%k%9%H!<%s%j%S%8%g%s$KIU$1$k$3$H$,$G$-$k!%(B
\interaction{branching.tag}
$B%a%$%s%V%i%s%A$G?J9TCf$N3+H/$K$D$$$F8+$F$_$h$&!%(B
\interaction{branching.main}
$B$3$l0J8e%j%]%8%H%j$r%/%m!<%s$7$??M$O%^%$%k%9%H!<%s$G5-O?$5$l$?%?%0$H(B
\hgcmd{update}$B%3%^%s%I$r;H$C$F!$%?%0$NIU$1$i$l$?%j%S%8%g%s$HA4$/F1$8%o!<(B
$B%-%s%0%G%#%l%/%H%j$rI|85$9$k$3$H$,$G$-$k!%(B
\interaction{branching.update}

%In addition, immediately after the main branch is tagged, someone can
%then clone the main branch on the server to a new ``stable'' branch,
%also on the server.
%\interaction{branching.clone}

$B$5$i$K!$%a%$%s%V%i%s%A$,%?%0IU$1$5$l$?D>8e$+$i%5!<%P>e$N%a%$%s%V%i%s%A$r(B
$B?7$?$J(B``stable''$B%V%i%s%A$K%/%m!<%s$G$-$k!%$3$l$O%5!<%P>e$G9T$&$3$H$b2DG=(B
$B$G$"$k!%(B
\interaction{branching.clone}

%Someone who needs to make a change to the stable branch can then clone
%\emph{that} repository, make their changes, commit, and push their
%changes back there.
%\interaction{branching.stable}
%Because Mercurial repositories are independent, and Mercurial doesn't
%move changes around automatically, the stable and main branches are
%\emph{isolated} from each other.  The changes that you made on the
%main branch don't ``leak'' to the stable branch, and vice versa.

stable$B%V%i%s%A$KJQ99$r2C$($?$$>l9g!$(B\emph{$B$=$N(B}$B%j%]%8%H%j$r%/%m!<%s$7!$(B
$BJQ99$r9T$$!$%3%_%C%H$7$?8e$K$=$NJQ99$r%5!<%P$K(Bpush$B$7$FLa$9$3$H$,$G$-$k!%(B
\interaction{branching.stable}
Mercurial$B%j%]%8%H%j$OFHN)$G!$JQ99$r<+F0E*$KGH5Z$5$;$k$3$H$b$J$$$N$G!$(B
stable$B$H(Bmain$B%V%i%s%A$O8_$$$K(B\emph{$B3VN%$5$l$F$$$k(B}$B!%%a%$%s%V%i%s%A$K9T$C(B
$B$?JQ99$,(Bstable$B%V%i%s%A$KO3$l=P$7$?$j!$$=$N5U$K$J$C$?$j$9$k$3$H$O$J$$!%(B

%You'll often want all of your bugfixes on the stable branch to show up

%on the main branch, too.  Rather than rewrite a bugfix on the main
%branch, you can simply pull and merge changes from the stable to the
%main branch, and Mercurial will bring those bugfixes in for you.
%\interaction{branching.merge}
%The main branch will still contain changes that are not on the stable
%branch, but it will also contain all of the bugfixes from the stable
%branch.  The stable branch remains unaffected by these changes.

$BB?$/$N>l9g!$(Bstable$B%V%i%s%A$KBP$7$F9T$C$?%P%0=$@5$r%a%$%s%V%i%s%A$KBP$7$F(B
$B$b<h$j9~$_$?$$$H9M$($k$@$m$&!%%P%0=$@5$r%a%$%s%V%i%s%A$G$b$&0lEY9T$&$N$G(B
$B$O$J$/!$(BMercurial$B$r;H$C$FJQ99$r(Bstable$B%V%i%s%A$+$i(Bpull$B$7$F4JC1$K%a%$%s%V%i(B
$B%s%A$X%^!<%8$9$k$3$H$,$G$-$k!%(B
\interaction{branching.merge}
$B%a%$%s%V%i%s%A$K$O(Bstable$B%V%i%s%A$K$J$$JQ99$,$"$k$,!$(Bstable$B%V%i%s%A$K$"$k(B
$B%P%0=$@5$O$9$Y$F<h$j9~$s$G$$$k!%$3$NA`:n$N8e$G$b(Bstable$B%V%i%s%A$O0JA0$HJQ(B
$B$o$i$J$$$^$^$G$"$k!%(B

%\subsection{Feature branches}
\subsection{$B5!G=$K$h$k%V%i%s%A(B}

%For larger projects, an effective way to manage change is to break up
%a team into smaller groups.  Each group has a shared branch of its
%own, cloned from a single ``master'' branch used by the entire
%project.  People working on an individual branch are typically quite
%isolated from developments on other branches.

$BBg5,LO$J%W%m%8%'%/%H$GJQ99$r8z2LE*$K4IM}$9$kJ}K!$O!$%A!<%`$r>.$5$J%0%k!<(B
$B%W$KJ,3d$9$k$3$H$G$"$k!%3F!9$N%0%k!<%W$O%W%m%8%'%/%HA4BN$G;H$o$l$kC10l$N(B
$B%^%9%?!<%V%i%s%A$+$i%/%m!<%s$7$?8GM-$N6&M-%V%i%s%A$r;}$D!%3F!9$N%V%i%s%A(B
$B$G:n6H$9$k?MC#$O!$B>$N%V%i%s%A$G$N3+H/$+$i3VN%$5$l$F$$$k$N$,DLNc$G$"$k!%(B

\begin{figure}[ht]
  \centering
  \grafix{feature-branches}
%  \caption{Feature branches}
  \caption{$B5!G=$K$h$k%V%i%s%A(B}
  \label{fig:collab:feature-branches}
\end{figure}

%When a particular feature is deemed to be in suitable shape, someone
%on that feature team pulls and merges from the master branch into the
%feature branch, then pushes back up to the master branch.

$BFCDj$N5!G=$,==J,$J>uBV$K$J$C$?$H$-!$$=$N5!G=$N%A!<%`%a%s%P!<$O%^%9%?!<%V(B
$B%i%s%A$+$i5!G=%V%i%s%A$K(Bpull$B$H%^!<%8$r9T$$!$%^%9%?!<%V%i%s%A$K(Bpush$B$7$FLa(B
$B$9!%(B

%\subsection{The release train}
\subsection{$B%j%j!<%9%H%l%$%s(B}

%Some projects are organised on a ``train'' basis: a release is
%scheduled to happen every few months, and whatever features are ready
%when the ``train'' is ready to leave are allowed in.

$B$$$/$D$+$N%W%m%8%'%/%H$O%H%l%$%sJ}<0$GAH?%$5$l$F$$$k!%?t%+7n$K0lEY%j%j!<(B
$B%9$r9T$&$h$&$K%9%1%8%e!<%k$5$l!$%H%l%$%s$,=PH/$G$-$k$h$&$K?75!G=$,=`Hw$5(B
$B$l$k!%(B

%This model resembles working with feature branches.  The difference is
%that when a feature branch misses a train, someone on the feature team
%pulls and merges the changes that went out on that train release into
%the feature branch, and the team continues its work on top of that
%release so that their feature can make the next release.

$B$3$N%b%G%k$O5!G=%V%i%s%A$G$N:n6H$H;w$F$$$k!%0c$$$O!$5!G=%V%i%s%A$O%H%l%$(B
$B%s$rF($7$?>l9g!$5!G=%A!<%`$N%a%s%P!<$,5!G=%V%i%s%A$N%H%l%$%s%j%j!<%9$X9T(B
$B$/$Y$-JQ99$r5!G=%j%j!<%9$K(Bpull$B$*$h$S%^!<%8$7!$3+H/Cf$N5!G=$,<!$N%j%j!<%9(B
$B$KF~$k$h$&$K%A!<%`$O$=$N%j%j!<%9$N>e$G:n6H$rB3$1$k!%(B

%\subsection{The Linux kernel model}
\subsection{Linux$B%+!<%M%k%b%G%k(B}

%The development of the Linux kernel has a shallow hierarchical
%structure, surrounded by a cloud of apparent chaos.  Because most
%Linux developers use \command{git}, a distributed revision control
%tool with capabilities similar to Mercurial, it's useful to describe
%the way work flows in that environment; if you like the ideas, the
%approach translates well across tools.

Linux$B%+!<%M%k$N3+H/$G$O!$<~$j$K:.FY$H$7$?9-$,$j$r;}$D@u$$3,AX9=B$$,<h$i$l(B
$B$F$$$k!%KX$s$I$N(BLinux$B3+H/<T$O(BMercurial$B$HF1MM$N5!G=$r;}$D(B\command{git}$B$H$$(B
$B$&J,;6%j%S%8%g%s4IM}%D!<%k$rMxMQ$7$F$$$k$?$a!$H`$i$,<h$C$F$$$k%o!<%/%U%m!<(B
$B$r=R$Y$k$3$H$O2f!9$K$bLrN)$D!%H`$i$N%"%$%G%#%"$r5$$KF~$l$P!$$=$N%"%W%m!<(B
$B%A$O%D!<%k$N0c$$$r1[$($FM-8z$G$"$k!%(B

%At the center of the community sits Linus Torvalds, the creator of
%Linux.  He publishes a single source repository that is considered the
%``authoritative'' current tree by the entire developer community.
%Anyone can clone Linus's tree, but he is very choosy about whose trees
%he pulls from.

$B3+H/%3%_%e%K%F%#$NCf?4$O(BLinux$B$NAOB$<T$G$"$k(BLinus Torvalds$B$G$"$k!%H`$O%j%](B
$B%8%H%j$r(B1$B$D8x3+$7$F$*$j!$$=$l$O3+H/%3%_%e%K%F%#A4BN$N8x<0%+%l%s%H%D%j!<$H(B
$B8+Pv$5$l$F$$$k!%C/$G$b(BLinus$B$N%D%j!<$r%/%m!<%s$G$-$k$,!$H`<+?H$O$I$3$+$i(B
pull$B$9$k$+$r87$7$/A*$s$G$$$k!%(B

%Linus has a number of ``trusted lieutenants''.  As a general rule, he
%pulls whatever changes they publish, in most cases without even
%reviewing those changes.  Some of those lieutenants are generally
%agreed to be ``maintainers'', responsible for specific subsystems
%within the kernel.  If a random kernel hacker wants to make a change
%to a subsystem that they want to end up in Linus's tree, they must
%find out who the subsystem's maintainer is, and ask that maintainer to
%take their change.  If the maintainer reviews their changes and agrees
%to take them, they'll pass them along to Linus in due course.

Linus$B$OB?$/$N(B``$B?.Mj$G$-$kBe9T<T(B''$B$r;}$C$F$$$k!%86B'E*$K$OH`$OH`$i$,8x3+$7(B
$B$?$b$N$O2?$G$b(Bpull$B$9$k!%B?$/$N>l9g!$H`$i$NJQ99$r%l%S%e!<$9$k$3$H$b$7$J(B
$B$$!%Be9T<T$N2??M$+$O%a%s%F%J!<$H$J$k$3$H$rF10U$7$F$*$j!$%+!<%M%kFb$NFCDj(B
$B$N%5%V%7%9%F%`$KBP$7$F@UG$$r;}$D!%%+!<%M%k%O%C%+!<$NC/$+$,(BLinus$B$N%D%j!<$N(B
$B%5%V%7%9%F%`$KJQ99$r2C$($?$$$H;W$C$?$i!$%5%V%7%9%F%`$N%a%s%F%J!<$r8+$D$1(B
$B=P$7$?>e$G!$%a%s%F%J!<$KJQ99$r<h$j9~$s$GLc$&$h$&$K0MMj$9$kI,MW$,$"$k!%%a(B
$B%s%F%J!<$,JQ99$r%l%S%e!<$7!$<h$j9~$`$3$H$KF10U$9$l$P!$@5<0$J%3!<%9$GJQ99(B
$B$r(BLinus$B$K<jEO$9!%(B

%Individual lieutenants have their own approaches to reviewing,
%accepting, and publishing changes; and for deciding when to feed them
%to Linus.  In addition, there are several well known branches that
%people use for different purposes.  For example, a few people maintain
%``stable'' repositories of older versions of the kernel, to which they
%apply critical fixes as needed.  Some maintainers publish multiple
%trees: one for experimental changes; one for changes that they are
%about to feed upstream; and so on.  Others just publish a single
%tree.

$B$=$l$>$l$NBeM}?M$O%l%S%e!<!$JQ99$N8x3+!$$$$D(BLinus$B$KDs=P$9$k$+$K$D$$$F$=$l(B
$B$>$lFH<+$N%"%W%m!<%A$r<h$C$F$$$k!%$^$?!$JL$NMQES8~$1$K$h$/CN$i$l$?%V%i%s(B
$B%A$,$$$/$D$+$"$j!$Nc$($P4v?M$+$N?M$O%+!<%M%k$N2a5n$N%P!<%8%g%s$N(B
``stable''$B%j%]%8%H%j$r%a%s%F%J%s%9$7!$=EMW$J=$@5$r9T$C$F$$$k!%JL$N%a%s%F(B
$B%J$O!$<B83E*$JJQ99$r<h$j9~$`%D%j!<!$>eN.$K<jEO$9@#A0$NJQ99$r<h$j9~$`%D%j!<(B
$B$J$I$N$h$&$KJ#?t$N%D%j!<$r8x3+$7$F$$$k!%$^$?(B1$B$D$N%D%j!<$@$1$r8x3+$7$F$$$k(B
$B%a%s%F%J$bB?$$!%(B

%This model has two notable features.  The first is that it's ``pull
%only''.  You have to ask, convince, or beg another developer to take a
%change from you, because there are almost no trees to which more than
%one person can push, and there's no way to push changes into a tree
%that someone else controls.

$B$3$N%b%G%k$OCmL\$9$Y$-FCD9$r(B2$B$D;}$C$F$$$k!%Bh0l$K!$$3$l$i$O(Bpull$B%*%s%j!<$G(B
$B$"$k!%JQ99$r<h$j9~$s$GLc$&$?$a$K$O!$B>$N3+H/<T$K0MMj$7$?$j!$@bF@$7$?$j!$(B
$B:)4j$7$?$j$7$J$1$l$P$J$i$J$$!%$J$<$J$i(B2$B?M0J>e$,%W%C%7%e$G$-$k%D%j!<$O$[$H(B
$B$s$I$J$/!$JL$N?M$,%3%s%H%m!<%k$7$F$$$k%D%j!<$KJQ99$r(Bpush$B$9$k=Q$O$J$$$+$i(B
$B$G$"$k!%(B

%The second is that it's based on reputation and acclaim.  If you're an
%unknown, Linus will probably ignore changes from you without even
%responding.  But a subsystem maintainer will probably review them, and
%will likely take them if they pass their criteria for suitability.
%The more ``good'' changes you contribute to a maintainer, the more
%likely they are to trust your judgment and accept your changes.  If
%you're well-known and maintain a long-lived branch for something Linus
%hasn't yet accepted, people with similar interests may pull your
%changes regularly to keep up with your work.

$BBhFs$K!$$3$l$OI>H=$H>N;?$H$K$h$k%7%9%F%`$G$"$k$H$$$&$3$H$@!%L5L>$N3+H/<T(B
$B$NJQ99$KBP$7$F$O(BLinus$B$O$*$=$i$/H?1~$9$k$3$H$J$/L5;k$9$k!%$7$+$7%5%V%7%9%F(B
$B%`%a%s%F%J$OJQ99$r%l%S%e!<$7!$E,@Z$G$"$k$HH=CG$9$l$P:N$jF~$l$k!%3+H/<T$,(B
$BNI$$JQ99$r9T$($P9T$&$[$I!$%a%s%F%J$O3+H/<T$NH=CG$r?.MQ$7!$JQ99$r:N$jF~$l(B
$B$k$h$&$K$J$k$@$m$&!%3+H/<T$,CxL>$G!$(BLinus$B$,$$$^$@$K<u$1F~$l$F$$$J$$!$D94|(B
$B4V$K$o$?$k%V%i%s%A$N%a%s%F%J$G$"$k$J$i$P!$F1$86=L#$r;}$D?M!9$,H`$N:n6H$r(B
$B<h$j9~$`$?$a$KJQ99$rDj4|E*$K(Bpull$B$9$k$3$H$@$m$&!%(B

%Reputation and acclaim don't necessarily cross subsystem or ``people''
%boundaries.  If you're a respected but specialised storage hacker, and
%you try to fix a networking bug, that change will receive a level of
%scrutiny from a network maintainer comparable to a change from a
%complete stranger.

$BI>H=$H>N;?$O%5%V%7%9%F%`$r1[$($?$j!$<~JU$K$$$k?M!9$r1[$($k$3$H$O$J$$$@$m(B
$B$&!%$b$7$"$J$?$,%9%H%l!<%8$NJ,Ln$G7I0U$r=8$a$k%O%C%+!<$G$"$C$?$H$7$F$b!$(B
$B%M%C%H%o!<%/$N%P%0$r=$@5$7$h$&$H$7$?$N$J$i!$9T$C$?JQ99$O%M%C%H%o!<%/$N%a(B
$B%s%F%J$+$i40A4$JIt30<T$HF1Ey$N@:::$r<u$1$k$3$H$K$J$k$@$m$&!%(B

%To people who come from more orderly project backgrounds, the
%comparatively chaotic Linux kernel development process often seems
%completely insane.  It's subject to the whims of individuals; people
%make sweeping changes whenever they deem it appropriate; and the pace
%of development is astounding.  And yet Linux is a highly successful,
%well-regarded piece of software.

$B@0A3$H$7$?%W%m%8%'%/%H$+$iMh$?3+H/<T$K$H$C$F$O!$(BLinux$B%+!<%M%k$N:.FY$H$7$?(B
$B3+H/%W%m%;%9$O$7$P$7$P40A4$K685$$N:;BA$H;W$($k$3$H$@$m$&!%(BLinux$B%+!<%M%k$G(B
$B$O!$3+H/%W%m%;%9$O8D!9?M$N5$$^$0$l$K0MB8$7$F$*$j!$E,@Z$H9M$($?;~$OA4LLE*(B
$B$JJQ99$r9T$$!$3+H/%Z!<%9$OESJ}$b$J$$!%$=$l$G$b$7$+$7(BLinux$B$OBg$$$K@.8y$7$?(B
$BCmL\$9$Y$-%=%U%H%&%'%"$J$N$G$"$k!%(B

%\subsection{Pull-only versus shared-push collaboration}
\subsection{Pull$B$N$_(B vs $B6&M-(Bpush$B%3%i%\%l!<%7%g%s(B}

%A perpetual source of heat in the open source community is whether a
%development model in which people only ever pull changes from others
%is ``better than'' one in which multiple people can push changes to a
%shared repository.

$B%*!<%W%s%=!<%9%3%_%e%K%F%#$G$OB>$N3+H/<T$N$H$3$m$+$iJQ99$r(Bpull$B$9$k$@$1$N(B
$B3+H/%b%G%k$,!$6&M-%j%]%8%H%j$KB??t$N3+H/<T$,(Bpush$B$G$-$k%b%G%k$h$j$b(B``$BM%$l(B
$B$F$$$k(B''$B$+$I$&$+$,>o$K7c$7$$O@Ah$N<o$K$J$k!%(B

%Typically, the backers of the shared-push model use tools that
%actively enforce this approach.  If you're using a centralised
%revision control tool such as Subversion, there's no way to make a
%choice over which model you'll use: the tool gives you shared-push,
%and if you want to do anything else, you'll have to roll your own
%approach on top (such as applying a patch by hand).

$B6&M-%W%C%7%e%b%G%k$N;Y;}<T$O!$$3$N%"%W%m!<%A$r6/@)$9$k$h$&$J%D!<%k$r;H$C(B
$B$F$$$k$3$H$,B?$$!%$b$7(BSubversion$B$N$h$&$JCf1{=8Cf7?$N%j%S%8%g%s4IM}%D!<%k(B
$B$r;H$C$F$$$k$N$J$i!$;H$&%b%G%k$rA*$VM>CO$O$=$b$=$bB8:_$7$J$$!%(B
$B$3$l$i$N%D!<%k$G$O6&M-(Bpush$B%b%G%k$r;H$&B>$J$/!$$=$l0J30$N2?$+$r$7$?$$$N$G(B
$B$"$l$P!$!J<+NO$G%Q%C%A$rEv$F$k$J$I$NJ}K!$G!K30It$G9T$&I,MW$,$"$k!%(B

%A good distributed revision control tool, such as Mercurial, will
%support both models.  You and your collaborators can then structure
%how you work together based on your own needs and preferences, not on
%what contortions your tools force you into.

Mercurial$B$N$h$&$JNI$$J,;6%j%S%8%g%s%3%s%H%m!<%k%D!<%k$O!$N>J}$N%b%G%k$r%5(B
$B%]!<%H$9$k!%%f!<%6$d6(NO<T$O%D!<%k$K$h$C$F6/MW$5$l$k%b%G%k$G$O$J$/!$MW5a(B
$B$d9%$_$K1~$8$?6&F1:n6H$N9=@.$r7h$a$k$3$H$,$G$-$k!%(B

%\subsection{Where collaboration meets branch management}
\subsection{$B6&F1:n6H$,%V%i%s%A4IM}$HD>LL$9$k$H$3$m(B}

%Once you and your team set up some shared repositories and start
%propagating changes back and forth between local and shared repos, you
%begin to face a related, but slightly different challenge: that of
%managing the multiple directions in which your team may be moving at
%once.  Even though this subject is intimately related to how your team
%collaborates, it's dense enough to merit treatment of its own, in
%chapter~\ref{chap:branch}.

$B3+H/<T$H$=$N%A!<%`$,6&M-%j%]%8%H%j$r%;%C%H%"%C%W$7!$%m!<%+%k$H6&M-%j%]%8(B
$B%H%j$N4V$GJQ99$r$d$j$H$j$7;O$a$k$H!$$3$l$H4XO"$9$k$,!$$d$d0[$J$C$?:$Fq$K(B
$BD>LL$9$k$h$&$K$J$k$@$m$&!%$=$l$O!$%A!<%`$,F1;~$K?J$a$kB?J}LL$X$N3+H/$r$I(B
$B$N$h$&$K4IM}$9$k$+$H$$$&LdBj$G$"$k!%$3$N2]Bj$O!$%A!<%`$,$I$N$h$&$K6&F1$9(B
$B$k$+$H:,8;E*$K4X78$7$F$*$j!$$3$l$@$1$N$?$a$K(B~\ref{chap:branch}$B$H$$$&0l>O$r(B
$BHq$d$92ACM$,$"$k$@$m$&!%(B

%\section{The technical side of sharing}
\section{$B6&M-$N5;=QE*B&LL(B}

%The remainder of this chapter is devoted to the question of serving
%data to your collaborators.

$B$3$N>O$N;D$j$NItJ,$G$O!$6(NO<T$K%G!<%?$r%5!<%S%9$9$k:]$N5?LdE@$K$D$$$F=R(B
$B$Y$k!%(B

%\section{Informal sharing with \hgcmd{serve}}
\section{\hgcmd{serve}$B$K$h$kHs8x<0$J6&M-(B}
\label{sec:collab:serve}

%Mercurial's \hgcmd{serve} command is wonderfully suited to small,
%tight-knit, and fast-paced group environments.  It also provides a
%great way to get a feel for using Mercurial commands over a network.

Mercurial$B$N(B\hgcmd{serve}$B%3%^%s%I$O!$>.5,LO$G6[L)$J3+H/%Z!<%9$NB.$$%0%k!<(B
$B%W4D6-$K$H$F$bE,$7$F$$$k!%(BMercurial$B%3%^%s%I$r%M%C%H%o!<%/1[$7$K;H$&AG@2(B
$B$i$7$5$rBN46$G$-$k$@$m$&!%(B

%Run \hgcmd{serve} inside a repository, and in under a second it will
%bring up a specialised HTTP server; this will accept connections from
%any client, and serve up data for that repository until you terminate
%it.  Anyone who knows the URL of the server you just started, and can
%talk to your computer over the network, can then use a web browser or
%Mercurial to read data from that repository.  A URL for a
%\hgcmd{serve} instance running on a laptop is likely to look something
%like \Verb|http://my-laptop.local:8000/|.

$B%j%]%8%H%jFb$G(B\hgcmd{serve}$B%3%^%s%I$r5/F0$9$k$H!$$9$0$5$^FCJL$J(BHTTP$B%5!<%P(B
$B$,N)$A>e$2$i$l$k!%$3$l$O$"$i$f$k%/%i%$%"%s%H$+$i$N@\B3$r<u$1F~$l!$%j%]%8(B
$B%H%j$N%G!<%?$r%5!<%S%9$9$k!%5/F0$7$?%5!<%P$N(BURL$B$rCN$C$F$$$k?M$d$"$J$?$N%3(B
$B%s%T%e!<%?$K%M%C%H%o!<%/$r2p$7$F@\B32DG=$J?M$OC/$G$b!$%&%'%V%V%i%&%6$d(B
Mercurial$B$r;H$C$F%j%]%8%H%j$+$i%G!<%?$rFI$_=P$9$3$H$,$G$-$k!%%i%C%W%H%C%W(B
$B$G5/F0$5$l$?(B\hgcmd{serve}$B%$%s%9%?%s%9$X$N(BURL$B$O(B
\Verb|http://my-laptop.local:8000/|$B$N$h$&$K$J$k!%(B

%The \hgcmd{serve} command is \emph{not} a general-purpose web server.
%It can do only two things:
\hgcmd{serve}$B%3%^%s%I$O0lHLMQES8~$1$N%&%'%V%5!<%P$G$O(B\emph{$B$J$$(B}$B!%$3$N%3(B
$B%^%s%I$O<!$N(B2$B$D$N$3$H$@$1$r9T$&!'(B
\begin{itemize}
%\item Allow people to browse the history of the repository it's
%  serving, from their normal web browsers.
 \item $BIaDL$N%&%'%V%V%i%&%6$r;H$C$F$$$k%f!<%6$KBP$7$F$O%j%]%8%H%j$NMzNr(B
       $B$X$N;2>H!%(B
%\item Speak Mercurial's wire protocol, so that people can
%  \hgcmd{clone} or \hgcmd{pull} changes from that repository.
 \item Mercurial$B$r;H$C$F$$$k%f!<%6$KBP$7$F$O!$(B\hgcmd{clone}$B$^$?$O(B
       \hgcmd{pull}$B$,$G$-$k$h$&$K(BMercurial$B%o%$%d%W%m%H%3%k$N%5%]!<%H!%(B

\end{itemize}
%In particular, \hgcmd{serve} won't allow remote users to \emph{modify}
%your repository.  It's intended for read-only use.

\hgcmd{serve}$B$O%j%b!<%H%f!<%6$K%j%]%8%H%j$NJQ99$r5v2D$7$J$$!%$3$N%3%^%s(B
$B%I$OFI$_=P$7$N$_$N;HMQ$r0U?^$7$F$$$k!%(B

%If you're getting started with Mercurial, there's nothing to prevent
%you from using \hgcmd{serve} to serve up a repository on your own
%computer, then use commands like \hgcmd{clone}, \hgcmd{incoming}, and
%so on to talk to that server as if the repository was hosted remotely.
%This can help you to quickly get acquainted with using commands on
%network-hosted repositories.

Mercurial$B$N(B\hgcmd{serve}$B%3%^%s%I$r;H$C$F!$<j85$N%3%s%T%e!<%?$G%j%]%8%H%j(B
$B%5!<%S%9$r9T$&$N$O4JC1$G$"$k!%1sJ}$K$"$k%5!<%P$H$d$j$H$j$9$k$N$HF1MM$K(B
\hgcmd{clone}$B!$(B\hgcmd{incoming}$BEy$N%3%^%s%I$r;H$&$3$H$,$G$-$k!%$3$l$O%j%](B
$B%8%H%j$r%M%C%H%o!<%/$GDs6!$9$k$3$H$K47$l$k$N$KLrN)$D$@$m$&!%(B

%\subsection{A few things to keep in mind}
\subsection{$B3P$($F$*$/$Y$-(B2, 3$B$NE@(B}

%Because it provides unauthenticated read access to all clients, you
%should only use \hgcmd{serve} in an environment where you either don't
%care, or have complete control over, who can access your network and
%pull data from your repository.

\hgcmd{serve}$B$O!$G'>Z$J$7$G%"%/%;%9$r5v$9$?$a!$%M%C%H%o!<%/$X$N%"%/%;%9(B
$B$d!$%j%]%8%H%j$+$i$N%G!<%?(Bpull$B$rC/$,9T$C$F$b9=$o$J$$$h$&$J%M%C%H%o!<%/4D(B
$B6-$d!$40A4$J@)8f$,2DG=$J%M%C%H%o!<%/4D6-$G$N$_;HMQ$9$Y$-$G$"$k!%(B

%The \hgcmd{serve} command knows nothing about any firewall software
%you might have installed on your system or network.  It cannot detect
%or control your firewall software.  If other people are unable to talk
%to a running \hgcmd{serve} instance, the second thing you should do
%(\emph{after} you make sure that they're using the correct URL) is
%check your firewall configuration.

\hgcmd{serve}$B%3%^%s%I$O!$%7%9%F%`$d%M%C%H%o!<%/$K%$%s%9%H!<%k$5$l$F$$$k%U%!(B
$B%$%"%&%)!<%k%=%U%H%&%'%"$K$D$$$F$O2?$b4XCN$7$J$$!%$3$N%3%^%s%I$O%U%!%$%"(B
$B%&%)!<%k$NH/8+$d@)8f$O$G$-$J$$!%B>$N%f!<%6$,(B\hgcmd{serve}$B%3%^%s%I$K%"%/%;(B
$B%9$G$-$J$$>l9g!$$^$:H`$i$,@5$7$$(BURL$B$r;HMQ$7$F$$$k$+3NG'$7!$$=$N<!$K$9$Y$-(B
$B$3$H$O!$%U%!%$%"%&%)!<%k$N@_Dj$r3NG'$9$k$3$H$G$"$k!%(B

%By default, \hgcmd{serve} listens for incoming connections on
%port~8000.  If another process is already listening on the port you
%want to use, you can specify a different port to listen on using the
%\hgopt{serve}{-p} option.

$B%G%U%)%k%H$G$O(B\hgcmd{serve}$B$OE~Ce$9$k@\B3$r%]!<%H(B~8000$B$GBT$D!%(B
$B;HMQ$7$?$$%]!<%H$r$9$G$KB>$N%W%m%;%9$,;HMQ$7$F$$$k>l9g$O(B
\hgopt{serve}{-p}$B%*%W%7%g%s$r;H$C$FJL$N%]!<%H$GBT5!$9$k$h$&$K;XDj$9$k$3(B
$B$H$,$G$-$k!%(B

%Normally, when \hgcmd{serve} starts, it prints no output, which can be
%a bit unnerving.  If you'd like to confirm that it is indeed running
%correctly, and find out what URL you should send to your
%collaborators, start it with the \hggopt{-v} option.

$BDL>o!$(B\hgcmd{serve}$B$O;OF0$7$F$b%a%C%;!<%8$N=PNO$r9T$o$J$$!%$3$l$OB?>/:.Mp(B
$B$5$;$k$+$b$7$l$J$$!%<B:]$K@5$7$/F0:n$7$F$$$k$+$I$&$+3NG'$7$?$$>l9g$d!$6((B
$BNO<T$K65$($k(BURL$B$,CN$j$?$$>l9g$O(B\hggopt{-v}$B%*%W%7%g%s$r;XDj$9$k!%(B

%\section{Using the Secure Shell (ssh) protocol}
\section{Secure Shell (ssh)$B%W%m%H%3%k$N;HMQ(B}
\label{sec:collab:ssh}

%You can pull and push changes securely over a network connection using
%the Secure Shell (\texttt{ssh}) protocol.  To use this successfully,
%you may have to do a little bit of configuration on the client or
%server sides.

Secure Shell (\texttt{ssh})$B%W%m%H%3%k$r;H$&$3$H$G!$JQ99$r%M%C%H%o!<%/>e$G(B
$B0BA4$K(Bpush$B$G$-$k!%$3$N%W%m%H%3%k$NMxMQ$K$O!$%/%i%$%"%s%HB&$+%5!<%PB&$K>/!9(B
$B@_Dj$,I,MW$G$"$k!%(B

%If you're not familiar with ssh, it's a network protocol that lets you
%securely communicate with another computer.  To use it with Mercurial,
%you'll be setting up one or more user accounts on a server so that
%remote users can log in and execute commands.

ssh$B$r$"$^$j;H$C$?$3$H$,$J$$%f!<%6$N$?$a$K@bL@$9$k$H!$(Bssh$B$OB>$N%3%s%T%e!<(B
$B%?$H0BA4$KDL?.$r9T$&$?$a$N%M%C%H%o!<%/%W%m%H%3%k$G$"$k!%(B Mercurial$B$G;H$&(B
$B$?$a$K$O!$(B1$B$D0J>e$N%"%+%&%s%H$r%5!<%P$K@_Dj$7!$%j%b!<%H%f!<%6$,%m%0%$%s(B
$B$7!$%3%^%s%I$r<B9T$G$-$k$h$&$K$9$kI,MW$,$"$k!%(B

%(If you \emph{are} familiar with ssh, you'll probably find some of the
%material that follows to be elementary in nature.)

$B!J(Bssh$B$KFk@w$_$N$"$k%f!<%6$K$O0J2<$NOC$O=iJbE*$K46$8$i$l$k$K0c$$$J$$!%!K(B

%\subsection{How to read and write ssh URLs}
\subsection{ssh$B$N(BURL$B$r$I$N$h$&$KFI$`$+(B}

%An ssh URL tends to look like this:
ssh URL$B$O0lHL$K<!$N$h$&$K$J$k!'(B
\begin{codesample2}
  ssh://[e-mail]:22/hg/hgbook
\end{codesample2}
\begin{enumerate}
%\item The ``\texttt{ssh://}'' part tells Mercurial to use the ssh
%  protocol.
 \item ``\texttt{ssh://}''$BIt$O(BMercurial$B$K(Bssh$B%W%m%H%3%k$r;H$&$3$H$r;X<($9(B
       $B$k!%(B
%\item The ``\texttt{bos@}'' component indicates what username to log
%  into the server as.  You can leave this out if the remote username
%  is the same as your local username.
 \item ``\texttt{bos@}''$BIt$O%5!<%P$X$N%m%0%$%s$K;H$&%f!<%6L>$r;XDj$9$k!%(B
$B%m!<%+%k%^%7%s$G$N%f!<%6L>$HF1$8$b$N$r;HMQ$9$k>l9g$O;XDj$7$J$/$F$b$h$$!%(B
%\item The ``\texttt{hg.serpentine.com}'' gives the hostname of the
%  server to log into.
 \item ``\texttt{hg.serpentine.com}''$B$O%m%0%$%s$9$k%5!<%P$N%[%9%HL>$G$"(B
       $B$k!%(B
%\item The ``:22'' identifies the port number to connect to the server
%  on.  The default port is~22, so you only need to specify this part
%  if you're \emph{not} using port~22.
 \item ``:22''$B%5!<%P$N@\B3%]!<%H$r@)Dj$9$k!%%G%U%)%k%H%]!<%H$O(B~22$B$J$N(B
       $B$G!$(B22$BHV0J30$r;H$&;~$N$_;XDj$9$kI,MW$,$"$k!%(B
%\item The remainder of the URL is the local path to the repository on
%  the server.
 \item URL$B$N;D$j$NItJ,$O%5!<%P>e$N%j%]%8%H%j$X$N%m!<%+%k%Q%9$G$"$k!%(B
\end{enumerate}

%There's plenty of scope for confusion with the path component of ssh
%URLs, as there is no standard way for tools to interpret it.  Some
%programs behave differently than others when dealing with these paths.
%This isn't an ideal situation, but it's unlikely to change.  Please
%read the following paragraphs carefully.

ssh URL$B$N%Q%9It$K$D$$$F$O!$%D!<%k8~$1$KJQ49$9$kI8=`E*$JJ}K!$,$J$$$?$a!$:.(B
$BMp$,B?$$!%$$$/$D$+$N%W%m%0%i%`$H!$$=$NB>$N%W%m%0%i%`$G$O%Q%9$r07$&:]$N5s(B
$BF0$,0[$J$C$F$$$k!%$3$N>u67$OM}A[$H$O$+$1N%$l$F$$$k$,!$=$@5$9$k$N$O:$Fq$@(B
$B$H;W$o$l$k!%0J2<$NCJMn$rCm0U?<$/FI$s$GM_$7$$!%(B

%Mercurial treats the path to a repository on the server as relative to
%the remote user's home directory.  For example, if user \texttt{foo}
%on the server has a home directory of \dirname{/home/foo}, then an ssh
%URL that contains a path component of \dirname{bar}
%\emph{really} refers to the directory \dirname{/home/foo/bar}.
Mercurial$B$O%j%]%8%H%j$X$N%Q%9$r%j%b!<%H%f!<%6$N%[!<%`%G%#%l%/%H%j$+$i$NAj(B
$BBP%Q%9$H$7$F<h$j07$&!%Nc$($P%5!<%P$G%f!<%6(B\texttt{foo}$B$O%[!<%`%G%#%l%/%H(B
$B%j(B\dirname{/home/foo}$B$r;}$D!%=>$C$F(B\dirname{bar}$B$r4^$`(Bssh URL$B$N%Q%9It$O(B
\dirname{/home/foo/bar}$B$H$J$k!%(B

%If you want to specify a path relative to another user's home
%directory, you can use a path that starts with a tilde character
%followed by the user's name (let's call them \texttt{otheruser}), like
%this.
$BB>$N%f!<%6$N%[!<%`%G%#%l%/%H%j$X$NAjBP%Q%9$r;XDj$7$?$$>l9g$O!$<!$NNc$N$h(B
$B$&$K%A%k%@$K%f!<%6L>$rB3$1$?%Q%9$r;H$&$3$H$,$G$-$k!%!J$3$3$G$OB>$N%f!<%6(B
$B$N%f!<%6L>$r(B\texttt{otheruser}$B$H$9$k!%!K(B
\begin{codesample2}
  ssh://server/~otheruser/hg/repo
\end{codesample2}

%And if you really want to specify an \emph{absolute} path on the
%server, begin the path component with two slashes, as in this example.
$B%5!<%P>e$G@dBP%Q%9$r;XDj$7$?$$>l9g$O!$<!$NNc$N$h$&$K%Q%9It$r(B2$B$D$N%9%i%C%7%e(B
$B$G;O$a$k!%(B
\begin{codesample2}
  ssh://server//absolute/path
\end{codesample2}

%\subsection{Finding an ssh client for your system}
\subsection{$BMxMQCf$N%7%9%F%`8~$1$N(Bssh client$B$r8+$D$1$k(B}

%Almost every Unix-like system comes with OpenSSH preinstalled.  If
%you're using such a system, run \Verb|which ssh| to find out if
%the \command{ssh} command is installed (it's usually in
%\dirname{/usr/bin}).  In the unlikely event that it isn't present,
%take a look at your system documentation to figure out how to install
%it.

Unix$B7O%7%9%F%`$NKX$s$I$O(BOpenSSH$B$,%W%j%$%s%9%H!<%k$5$l$F$$$k!%$=$N$h$&$J%7(B
$B%9%F%`$G$O!$(B\Verb|which ssh|$B$r<B9T$7$F(B\command{ssh}$B%3%^%s%I$,%$%s%9%H!<%k(B
$B$5$l$F$$$k$+$I$&$+D4$Y$k$3$H$,$G$-$k!%!JIaDL$O(B\dirname{/usr/bin}$B$K%$%s%9(B
$B%H!<%k$5$l$F$$$k$O$:$@!%!KK|$,0l%$%s%9%H!<%k$5$l$F$$$J$+$C$?>l9g$O!$%7%9(B
$B%F%`$N%I%-%e%a%s%H$r;2>H$7$F%$%s%9%H!<%kJ}K!$rD4$Y$FM_$7$$!%(B

%On Windows, you'll first need to choose download a suitable ssh
%client.  There are two alternatives.
Windows$B$G$O!$$^$:E,@Z$J(Bssh$B%/%i%$%"%s%H$r%@%&%s%m!<%I$9$kI,MW$,$"$k!%MxMQ(B
$B2DG=$J%/%i%$%"%s%H$O(B2$B$D$"$k!%(B
\begin{itemize}
%\item Simon Tatham's excellent PuTTY package~\cite{web:putty} provides
%  a complete suite of ssh client commands.
 \item Simon Tatham$B$K$h$kHs>o$KM%$l$?(BPuTTY$B%Q%C%1!<%8(B~\cite{web:putty}$B$O(B
       ssh$B%/%i%$%"%s%H$N40A4$J%3%^%s%I72$rDs6!$9$k!%(B
%\item If you have a high tolerance for pain, you can use the Cygwin
%  port of OpenSSH.
 \item $BLLE]$r1^$o$J$$$N$G$"$l$P!$(BCygwin$BHG$N(BOpenSSH$B$r;H$&$3$H$b$G$-$k!%(B
\end{itemize}
%In either case, you'll need to edit your \hgini\ file to tell
%Mercurial where to find the actual client command.  For example, if
%you're using PuTTY, you'll need to use the \command{plink} command as
%a command-line ssh client.

$B$I$N>l9g$b(B\hgini\ $B%U%!%$%k$rJT=8$7!$(BMercurial$B$K<B:]$N%3%^%s%I$,$I$3$K$"$k(B
$B$N$+$r;X<($7$J$1$l$P$J$i$J$$!%Nc$($P(BPuTTY$B$r;H$&>l9g$O!$(B\command{plink}$B%3(B
$B%^%s%I$r%3%^%s%I%i%$%sHG(Bssh$B%/%i%$%"%s%H$H$7$F;HMQ$9$k!%(B


\begin{codesample2}
  [ui]
  ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"
\end{codesample2}

\begin{note}
%  The path to \command{plink} shouldn't contain any whitespace
%  characters, or Mercurial may not be able to run it correctly (so
%  putting it in \dirname{C:\\Program Files} is probably not a good
%  idea).
\command{plink}$B$X$N%Q%9$O6uGrJ8;z$r4^$s$G$O$J$i$J$$!%6uGr$r4^$`$H(B
Mercurial$B$O@5$7$/<B9T$9$k$3$H$,$G$-$J$$!%!J=>$C$F(B\dirname{C:\\Program
Files}$B$XCV$/$N$O$$$$9M$($H$O8@$($J$$!%!K(B
\end{note}

%\subsection{Generating a key pair}
\subsection{$B80%Z%"$N:n@.(B}

%To avoid the need to repetitively type a password every time you need
%to use your ssh client, I recommend generating a key pair.  On a
%Unix-like system, the \command{ssh-keygen} command will do the trick.
%On Windows, if you're using PuTTY, the \command{puttygen} command is
%what you'll need.

ssh$B%/%i%$%"%s%H$r;H$&EY$K7+JV$7%Q%9%o!<%I$rF~NO$9$k$N$rHr$1$k$?$a$K!$80(B
$B%Z%"$r:n@.$9$k$3$H$r4+$a$k!%(BUnix$B7O%7%9%F%`$G$O!$(B\command{ssh-keygen}$B%3%^(B
$B%s%I$G:n@.$G$-$k!%(BWindows$B$G(BPuTTY$B$r;H$C$F$$$k$N$G$"$l(B
$B$P!$(B\command{puttygen}$B$G:n@.$G$-$k!%(B

%When you generate a key pair, it's usually \emph{highly} advisable to
%protect it with a passphrase.  (The only time that you might not want
%to do this id when you're using the ssh protocol for automated tasks
%on a secure network.)

$B80%Z%"$r:n$k:]$K$O$G$-$k$@$1%Q%9%U%l!<%:$GJ]8n$9$k$3$H$r6/$/4+$a$k!%!J0B(B
$BA4$J%M%C%H%o!<%/$G(Bssh$B%W%m%H%3%k$K$h$C$F<+F0%?%9%/$N<B9T$r$9$k>l9g$K$O$3(B
$B$&$7$?$/$J$$$@$m$&!%!K(B

%Simply generating a key pair isn't enough, however.  You'll need to
%add the public key to the set of authorised keys for whatever user
%you're logging in remotely as.  For servers using OpenSSH (the vast
%majority), this will mean adding the public key to a list in a file
%called \sfilename{authorized\_keys} in their \sdirname{.ssh}
%directory.

$B$7$+$780%Z%"$r:n$k$@$1$G$O==J,$G$J$$!%%j%b!<%H$K%m%0%$%s$7$?$$%^%7%s$N%f!<(B
$B%6$N(Bauthorised keys$B$H$7$F8x3+80$rDI2C$9$kI,MW$,$"$k!%(BOpenSSH$B$r;H$C$F$$$k(B
$B%5!<%P!JBgItJ,$,AjEv$9$k!K$G$O(B\sdirname{.ssh}$B%G%#%l%/%H%j$N(B
\sfilename{authorized\_keys}$B%U%!%$%k$X8x3+80$rDI2C$9$k!%(B

%On a Unix-like system, your public key will have a \filename{.pub}
%extension.  If you're using \command{puttygen} on Windows, you can
%save the public key to a file of your choosing, or paste it from the
%window it's displayed in straight into the
%\sfilename{authorized\_keys} file.

Unix$B7O%7%9%F%`$G$O8x3+80$O(B\filename{.pub}$B$H$$$&3HD%;R$r;}$D!%(BWindows$B$G(B
\command{puttygen}$B$r;HMQ$9$k>l9g$O!$%U%!%$%k%;!<%V$7$?8x3+80$+!$80$rI=<((B
$B$7$F$$$k%&%#%s%I%&$+$i(B\sfilename{authorized\_keys}$B%U%!%$%k$K%Z!<%9%H$9$l(B
$B$P$h$$!%(B

%\subsection{Using an authentication agent}
\subsection{$BG'>Z%(!<%8%'%s%H$N;HMQ(B}

%An authentication agent is a daemon that stores passphrases in memory
%(so it will forget passphrases if you log out and log back in again).
%An ssh client will notice if it's running, and query it for a
%passphrase.  If there's no authentication agent running, or the agent
%doesn't store the necessary passphrase, you'll have to type your
%passphrase every time Mercurial tries to communicate with a server on
%your behalf (e.g.~whenever you pull or push changes).

$BG'>Z%(!<%8%'%s%H$O%Q%9%U%l!<%:$r%a%b%j$KJ]B8$9$k%(!<%8%'%s%H$G$"$k!%!J%m(B
$B%0%"%&%H$7!$:F$S%m%0%$%s$7$?;~$K$O%Q%9%U%l!<%:$O<:$o$l$F$$$k!%!K(Bssh$B%/%i%$(B
$B%"%s%H$O$3$N%G!<%b%s$,F0:n$7$F$$$k$3$H$rG'<1$7!$%Q%9%U%l!<%:$NLd$$9g$o$;(B
$B$r9T$&!%G'>Z%(!<%8%'%s%H$,F0:n$7$F$$$J$$>l9g$d%(!<%8%'%s%H$,I,MW$J%Q%9%U(B
$B%l!<%:$rJ]B8$7$F$$$J$$>l9g$O!$(BMercurial$B$,%5!<%P$H!JJQ99$r(Bpull$B$d(Bpush$B$9$k!K(B
$BDL?.$N;~$K%Q%9%U%l!<%:$rF~NO$9$kI,MW$,$"$k!%(B

%The downside of storing passphrases in an agent is that it's possible
%for a well-prepared attacker to recover the plain text of your
%passphrases, in some cases even if your system has been power-cycled.
%You should make your own judgment as to whether this is an acceptable
%risk.  It certainly saves a lot of repeated typing.

$B%Q%9%U%l!<%:$r%(!<%8%'%s%H$K5-21$5$;$kJ@32$O!$%Q%o!<%5%$%/%k$r9T$C$F$b>l(B
$B9g$K$h$C$F$O<~E~$J<jCJ$rMQ$$$k967b<T$K%Q%9%U%l!<%:$N%W%l!<%s%F%-%9%H>pJs(B
$B$r<hF@$5$l$k2DG=@-$,$"$k$3$H$G$"$k!%$3$N%j%9%/$,5vMF$GCe$kJ*2TF/$+$O<+J,(B
$B<+?H$GH=CG$7$FM_$7$$!%$3$NJ}K!$rMQ$$$k$3$H$G!$%?%$%W2s?t$r8:$i$;$k$3$H$O(B
$B3N$+$G$"$k!%(B

%On Unix-like systems, the agent is called \command{ssh-agent}, and
%it's often run automatically for you when you log in.  You'll need to
%use the \command{ssh-add} command to add passphrases to the agent's
%store.  On Windows, if you're using PuTTY, the \command{pageant}
%command acts as the agent.  It adds an icon to your system tray that
%will let you manage stored passphrases.

Unix$B7O%7%9%F%`$G$O%(!<%8%'%s%H$O(B\command{ssh-agent}$B$H8F$P$l!$%m%0%$%s$9$k(B
$B$H<+F0E*$K5/F0$5$l$k!%(B\command{ssh-add}$B%3%^%s%I$rMQ$$$F%Q%9%U%l!<%:$r%(!<(B
$B%8%'%s%H$K5-21$5$;$k!%(BWindows$B$G(BPuTTY$B$r;H$C$F$$$k>l9g$O!$(B\command{pageant}$B%3(B
$B%^%s%I$,%(!<%8%'%s%H$H$7$FF0:n$9$k!%$3$N%3%^%s%I$O5-21$7$?%Q%9%U%l!<%:$r(B
$B4IM}$9$k$?$a$K%7%9%F%`%H%l%$$K%"%$%3%s$rDI2C$9$k!%(B


%\subsection{Configuring the server side properly}
\subsection{$B%5!<%P$N@5$7$$@_Dj(B}

Because ssh can be fiddly to set up if you're new to it, there's a
variety of things that can go wrong.  Add Mercurial on top, and
there's plenty more scope for head-scratching.  Most of these
potential problems occur on the server side, not the client side.  The
good news is that once you've gotten a configuration working, it will
usually continue to work indefinitely.

Before you try using Mercurial to talk to an ssh server, it's best to
make sure that you can use the normal \command{ssh} or \command{putty}
command to talk to the server first.  If you run into problems with
using these commands directly, Mercurial surely won't work.  Worse, it
will obscure the underlying problem.  Any time you want to debug
ssh-related Mercurial problems, you should drop back to making sure
that plain ssh client commands work first, \emph{before} you worry
about whether there's a problem with Mercurial.

The first thing to be sure of on the server side is that you can
actually log in from another machine at all.  If you can't use
\command{ssh} or \command{putty} to log in, the error message you get
may give you a few hints as to what's wrong.  The most common problems
are as follows.
\begin{itemize}
\item If you get a ``connection refused'' error, either there isn't an
  SSH daemon running on the server at all, or it's inaccessible due to
  firewall configuration.
\item If you get a ``no route to host'' error, you either have an
  incorrect address for the server or a seriously locked down firewall
  that won't admit its existence at all.
\item If you get a ``permission denied'' error, you may have mistyped
  the username on the server, or you could have mistyped your key's
  passphrase or the remote user's password.
\end{itemize}
In summary, if you're having trouble talking to the server's ssh
daemon, first make sure that one is running at all.  On many systems
it will be installed, but disabled, by default.  Once you're done with
this step, you should then check that the server's firewall is
configured to allow incoming connections on the port the ssh daemon is
listening on (usually~22).  Don't worry about more exotic
possibilities for misconfiguration until you've checked these two
first.

If you're using an authentication agent on the client side to store
passphrases for your keys, you ought to be able to log into the server
without being prompted for a passphrase or a password.  If you're
prompted for a passphrase, there are a few possible culprits.
\begin{itemize}
\item You might have forgotten to use \command{ssh-add} or
  \command{pageant} to store the passphrase.
\item You might have stored the passphrase for the wrong key.
\end{itemize}
If you're being prompted for the remote user's password, there are
another few possible problems to check.
\begin{itemize}
\item Either the user's home directory or their \sdirname{.ssh}
  directory might have excessively liberal permissions.  As a result,
  the ssh daemon will not trust or read their
  \sfilename{authorized\_keys} file.  For example, a group-writable
  home or \sdirname{.ssh} directory will often cause this symptom.
\item The user's \sfilename{authorized\_keys} file may have a problem.
  If anyone other than the user owns or can write to that file, the
  ssh daemon will not trust or read it.
\end{itemize}

%In the ideal world, you should be able to run the following command
%successfully, and it should print exactly one line of output, the
%current date and time.
$BM}A[$G$O!$<!$N%3%^%s%I$r<B9T$7!$(B1$B9T$G8=:_$NF|;~$rI=<($G$-$k$Y$-$G$"$k!%(B
\begin{codesample2}
  ssh myserver date
\end{codesample2}

If, on your server, you have login scripts that print banners or other
junk even when running non-interactive commands like this, you should
fix them before you continue, so that they only print output if
they're run interactively.  Otherwise these banners will at least
clutter up Mercurial's output.  Worse, they could potentially cause
problems with running Mercurial commands remotely.  Mercurial makes
tries to detect and ignore banners in non-interactive \command{ssh}
sessions, but it is not foolproof.  (If you're editing your login
scripts on your server, the usual way to see if a login script is
running in an interactive shell is to check the return code from the
command \Verb|tty -s|.)

Once you've verified that plain old ssh is working with your server,
the next step is to ensure that Mercurial runs on the server.  The
following command should run successfully:
\begin{codesample2}
  ssh myserver hg version
\end{codesample2}
If you see an error message instead of normal \hgcmd{version} output,
this is usually because you haven't installed Mercurial to
\dirname{/usr/bin}.  Don't worry if this is the case; you don't need
to do that.  But you should check for a few possible problems.
\begin{itemize}
\item Is Mercurial really installed on the server at all?  I know this
  sounds trivial, but it's worth checking!
\item Maybe your shell's search path (usually set via the \envar{PATH}
  environment variable) is simply misconfigured.
\item Perhaps your \envar{PATH} environment variable is only being set
  to point to the location of the \command{hg} executable if the login
  session is interactive.  This can happen if you're setting the path
  in the wrong shell login script.  See your shell's documentation for
  details.
\item The \envar{PYTHONPATH} environment variable may need to contain
  the path to the Mercurial Python modules.  It might not be set at
  all; it could be incorrect; or it may be set only if the login is
  interactive.
\end{itemize}

If you can run \hgcmd{version} over an ssh connection, well done!
You've got the server and client sorted out.  You should now be able
to use Mercurial to access repositories hosted by that username on
that server.  If you run into problems with Mercurial and ssh at this
point, try using the \hggopt{--debug} option to get a clearer picture
of what's going on.

%\subsection{Using compression with ssh}
\subsection{ssh$B$G$N05=L$NMxMQ(B}

%Mercurial does not compress data when it uses the ssh protocol,
%because the ssh protocol can transparently compress data.  However,
%the default behaviour of ssh clients is \emph{not} to request
%compression.

Mercurial$B$O!$(Bssh$B%W%m%H%3%k$r;H$C$?>l9g$O!$%G!<%?$N05=L$O9T$o$J$$!%$J$<$J(B
$B$i(Bssh$B%W%m%H%3%k$,F)2aE*$K%G!<%?$N05=L$r9T$&$3$H$,$G$-$k$?$a$G$"$k!%(B
$B$7$+$7(Bssh$B%/%i%$%"%s%H$N%G%U%)%k%H$N5sF0$G$O!$05=L$r9T$o(B\emph{$B$J$$(B}$B!%(B

Over any network other than a fast LAN (even a wireless network),
using compression is likely to significantly speed up Mercurial's
network operations.  For example, over a WAN, someone measured
compression as reducing the amount of time required to clone a
particularly large repository from~51 minutes to~17 minutes.

Both \command{ssh} and \command{plink} accept a \cmdopt{ssh}{-C}
option which turns on compression.  You can easily edit your \hgrc\ to
enable compression for all of Mercurial's uses of the ssh protocol.
\begin{codesample2}
  [ui]
  ssh = ssh -C
\end{codesample2}

If you use \command{ssh}, you can configure it to always use
compression when talking to your server.  To do this, edit your
\sfilename{.ssh/config} file (which may not yet exist), as follows.
\begin{codesample2}
  Host hg
    Compression yes
    HostName hg.example.com
\end{codesample2}
This defines an alias, \texttt{hg}.  When you use it on the
\command{ssh} command line or in a Mercurial \texttt{ssh}-protocol
URL, it will cause \command{ssh} to connect to \texttt{hg.example.com}
and use compression.  This gives you both a shorter name to type and
compression, each of which is a good thing in its own right.

%\section{Serving over HTTP using CGI}
\section{CGI$B$r;HMQ$7$?(BHTTP$B$G$N%5!<%S%9(B}
\label{sec:collab:cgi}

Depending on how ambitious you are, configuring Mercurial's CGI
interface can take anything from a few moments to several hours.

We'll begin with the simplest of examples, and work our way towards a
more complex configuration.  Even for the most basic case, you're
almost certainly going to need to read and modify your web server's
configuration.

\begin{note}
  Configuring a web server is a complex, fiddly, and highly
  system-dependent activity.  I can't possibly give you instructions
  that will cover anything like all of the cases you will encounter.
  Please use your discretion and judgment in following the sections
  below.  Be prepared to make plenty of mistakes, and to spend a lot
  of time reading your server's error logs.
\end{note}

%\subsection{Web server configuration checklist}
\subsection{Web$B%5!<%P@_Dj$N%A%'%C%/%j%9%H(B}

Before you continue, do take a few moments to check a few aspects of
your system's setup.

\begin{enumerate}
\item Do you have a web server installed at all?  Mac OS X ships with
  Apache, but many other systems may not have a web server installed.
\item If you have a web server installed, is it actually running?  On
  most systems, even if one is present, it will be disabled by
  default.
\item Is your server configured to allow you to run CGI programs in
  the directory where you plan to do so?  Most servers default to
  explicitly disabling the ability to run CGI programs.
\end{enumerate}

If you don't have a web server installed, and don't have substantial
experience configuring Apache, you should consider using the
\texttt{lighttpd} web server instead of Apache.  Apache has a
well-deserved reputation for baroque and confusing configuration.
While \texttt{lighttpd} is less capable in some ways than Apache, most
of these capabilities are not relevant to serving Mercurial
repositories.  And \texttt{lighttpd} is undeniably \emph{much} easier
to get started with than Apache.

%\subsection{Basic CGI configuration}
\subsection{CGI$B$N4pK\E*$J@_Dj(B}

On Unix-like systems, it's common for users to have a subdirectory
named something like \dirname{public\_html} in their home directory,
from which they can serve up web pages.  A file named \filename{foo}
in this directory will be accessible at a URL of the form
\texttt{http://www.example.com/\~username/foo}.

To get started, find the \sfilename{hgweb.cgi} script that should be
present in your Mercurial installation.  If you can't quickly find a
local copy on your system, simply download one from the master
Mercurial repository at
\url{http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi}.

You'll need to copy this script into your \dirname{public\_html}
directory, and ensure that it's executable.
\begin{codesample2}
  cp .../hgweb.cgi ~/public_html
  chmod 755 ~/public_html/hgweb.cgi
\end{codesample2}
The \texttt{755} argument to \command{chmod} is a little more general
than just making the script executable: it ensures that the script is
executable by anyone, and that ``group'' and ``other'' write
permissions are \emph{not} set.  If you were to leave those write
permissions enabled, Apache's \texttt{suexec} subsystem would likely
refuse to execute the script.  In fact, \texttt{suexec} also insists
that the \emph{directory} in which the script resides must not be
writable by others.
\begin{codesample2}
  chmod 755 ~/public_html
\end{codesample2}

%\subsubsection{What could \emph{possibly} go wrong?}
\subsubsection{$B$I$3$,LdBj$H@.$jF@$k$+(B?}
\label{sec:collab:wtf}

Once you've copied the CGI script into place, go into a web browser,
and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi},
\emph{but} brace yourself for instant failure.  There's a high
probability that trying to visit this URL will fail, and there are
many possible reasons for this.  In fact, you're likely to stumble
over almost every one of the possible errors below, so please read
carefully.  The following are all of the problems I ran into on a
system running Fedora~7, with a fresh installation of Apache, and a
user account that I created specially to perform this exercise.

Your web server may have per-user directories disabled.  If you're
using Apache, search your config file for a \texttt{UserDir}
directive.  If there's none present, per-user directories will be
disabled.  If one exists, but its value is \texttt{disabled}, then
per-user directories will be disabled.  Otherwise, the string after
\texttt{UserDir} gives the name of the subdirectory that Apache will
look in under your home directory, for example \dirname{public\_html}.

Your file access permissions may be too restrictive.  The web server
must be able to traverse your home directory and directories under
your \dirname{public\_html} directory, and read files under the latter
too.  Here's a quick recipe to help you to make your permissions more
appropriate.
\begin{codesample2}
  chmod 755 ~
  find ~/public_html -type d -print0 | xargs -0r chmod 755
  find ~/public_html -type f -print0 | xargs -0r chmod 644
\end{codesample2}

The other possibility with permissions is that you might get a
completely empty window when you try to load the script.  In this
case, it's likely that your access permissions are \emph{too
  permissive}.  Apache's \texttt{suexec} subsystem won't execute a
script that's group-~or world-writable, for example.

Your web server may be configured to disallow execution of CGI
programs in your per-user web directory.  Here's Apache's
default per-user configuration from my Fedora system.
\begin{codesample2}
  <Directory /home/*/public_html>
      AllowOverride FileInfo AuthConfig Limit
      Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
      <Limit GET POST OPTIONS>
          Order allow,deny
          Allow from all
      </Limit>
      <LimitExcept GET POST OPTIONS>
          Order deny,allow
          Deny from all
      </LimitExcept>
  </Directory>
\end{codesample2}
If you find a similar-looking \texttt{Directory} group in your Apache
configuration, the directive to look at inside it is \texttt{Options}.
Add \texttt{ExecCGI} to the end of this list if it's missing, and
restart the web server.

If you find that Apache serves you the text of the CGI script instead
of executing it, you may need to either uncomment (if already present)
or add a directive like this.
\begin{codesample2}
  AddHandler cgi-script .cgi
\end{codesample2}

The next possibility is that you might be served with a colourful
Python backtrace claiming that it can't import a
\texttt{mercurial}-related module.  This is actually progress!  The
server is now capable of executing your CGI script.  This error is
only likely to occur if you're running a private installation of
Mercurial, instead of a system-wide version.  Remember that the web
server runs the CGI program without any of the environment variables
that you take for granted in an interactive session.  If this error
happens to you, edit your copy of \sfilename{hgweb.cgi} and follow the
directions inside it to correctly set your \envar{PYTHONPATH}
environment variable.

Finally, you are \emph{certain} to by served with another colourful
Python backtrace: this one will complain that it can't find
\dirname{/path/to/repository}.  Edit your \sfilename{hgweb.cgi} script
and replace the \dirname{/path/to/repository} string with the complete
path to the repository you want to serve up.

At this point, when you try to reload the page, you should be
presented with a nice HTML view of your repository's history.  Whew!

%\subsubsection{Configuring lighttpd}
\subsubsection{lighttpd$B$N@_Dj(B}

To be exhaustive in my experiments, I tried configuring the
increasingly popular \texttt{lighttpd} web server to serve the same
repository as I described with Apache above.  I had already overcome
all of the problems I outlined with Apache, many of which are not
server-specific.  As a result, I was fairly sure that my file and
directory permissions were good, and that my \sfilename{hgweb.cgi}
script was properly edited.

Once I had Apache running, getting \texttt{lighttpd} to serve the
repository was a snap (in other words, even if you're trying to use
\texttt{lighttpd}, you should read the Apache section).  I first had
to edit the \texttt{mod\_access} section of its config file to enable
\texttt{mod\_cgi} and \texttt{mod\_userdir}, both of which were
disabled by default on my system.  I then added a few lines to the end
of the config file, to configure these modules.
\begin{codesample2}
  userdir.path = "public_html"
  cgi.assign = ( ".cgi" => "" )
\end{codesample2}
With this done, \texttt{lighttpd} ran immediately for me.  If I had
configured \texttt{lighttpd} before Apache, I'd almost certainly have
run into many of the same system-level configuration problems as I did
with Apache.  However, I found \texttt{lighttpd} to be noticeably
easier to configure than Apache, even though I've used Apache for over
a decade, and this was my first exposure to \texttt{lighttpd}.

%\subsection{Sharing multiple repositories with one CGI script}
\subsection{1$B$D$N(BCGI$B%9%/%j%W%H$GJ#?t$N%j%]%8%H%j$r6&M-$9$k(B}

The \sfilename{hgweb.cgi} script only lets you publish a single
repository, which is an annoying restriction.  If you want to publish
more than one without wracking yourself with multiple copies of the
same script, each with different names, a better choice is to use the
\sfilename{hgwebdir.cgi} script.

The procedure to configure \sfilename{hgwebdir.cgi} is only a little
more involved than for \sfilename{hgweb.cgi}.  First, you must obtain
a copy of the script.  If you don't have one handy, you can download a
copy from the master Mercurial repository at
\url{http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi}.

You'll need to copy this script into your \dirname{public\_html}
directory, and ensure that it's executable.
\begin{codesample2}
  cp .../hgwebdir.cgi ~/public_html
  chmod 755 ~/public_html ~/public_html/hgwebdir.cgi
\end{codesample2}
With basic configuration out of the way, try to visit
\url{http://myhostname/~myuser/hgwebdir.cgi} in your browser.  It
should display an empty list of repositories.  If you get a blank
window or error message, try walking through the list of potential
problems in section~\ref{sec:collab:wtf}.

The \sfilename{hgwebdir.cgi} script relies on an external
configuration file.  By default, it searches for a file named
\sfilename{hgweb.config} in the same directory as itself.  You'll need
to create this file, and make it world-readable.  The format of the
file is similar to a Windows ``ini'' file, as understood by Python's
\texttt{ConfigParser}~\cite{web:configparser} module.

The easiest way to configure \sfilename{hgwebdir.cgi} is with a
section named \texttt{collections}.  This will automatically publish
\emph{every} repository under the directories you name.  The section
should look like this:
\begin{codesample2}
  [collections]
  /my/root = /my/root
\end{codesample2}
Mercurial interprets this by looking at the directory name on the
\emph{right} hand side of the ``\texttt{=}'' sign; finding
repositories in that directory hierarchy; and using the text on the
\emph{left} to strip off matching text from the names it will actually
list in the web interface.  The remaining component of a path after
this stripping has occurred is called a ``virtual path''.

Given the example above, if we have a repository whose local path is
\dirname{/my/root/this/repo}, the CGI script will strip the leading
\dirname{/my/root} from the name, and publish the repository with a
virtual path of \dirname{this/repo}.  If the base URL for our CGI
script is \url{http://myhostname/~myuser/hgwebdir.cgi}, the complete
URL for that repository will be
\url{http://myhostname/~myuser/hgwebdir.cgi/this/repo}.

If we replace \dirname{/my/root} on the left hand side of this example
with \dirname{/my}, then \sfilename{hgwebdir.cgi} will only strip off
\dirname{/my} from the repository name, and will give us a virtual
path of \dirname{root/this/repo} instead of \dirname{this/repo}.

The \sfilename{hgwebdir.cgi} script will recursively search each
directory listed in the \texttt{collections} section of its
configuration file, but it will \texttt{not} recurse into the
repositories it finds.

The \texttt{collections} mechanism makes it easy to publish many
repositories in a ``fire and forget'' manner.  You only need to set up
the CGI script and configuration file one time.  Afterwards, you can
publish or unpublish a repository at any time by simply moving it
into, or out of, the directory hierarchy in which you've configured
\sfilename{hgwebdir.cgi} to look.

%\subsubsection{Explicitly specifying which repositories to publish}
\subsubsection{$B$I$N%j%]%8%H%j$rI=<($9$k$+L@<(E*$K;XDj$9$k(B}

%In addition to the \texttt{collections} mechanism, the
%\sfilename{hgwebdir.cgi} script allows you to publish a specific list
%of repositories.  To do so, create a \texttt{paths} section, with
%contents of the following form.
\sfilename{hgwebdir.cgi}$B%9%/%j%W%H$O(B\texttt{collections}$B$N%a%+%K%:%`$NB>(B
$B$K$b%j%]%8%H%j$NFCDj$N%j%9%H$r8x3+$9$kJ}K!$rMQ0U$7$F$$$k!%2<5-$N$h$&$J(B
$BFbMF$N(B\texttt{paths}$B%;%/%7%g%s$r:n$k!%(B
\begin{codesample2}
  [paths]
  repo1 = /my/path/to/some/repo
  repo2 = /some/path/to/another
\end{codesample2}
%In this case, the virtual path (the component that will appear in a
%URL) is on the left hand side of each definition, while the path to
%the repository is on the right.  Notice that there does not need to be
%any relationship between the virtual path you choose and the location
%of a repository in your filesystem.
$B$3$N>l9g!$3F!9$NDj5A$N:8JU$K2>A[%Q%9!J(BURL$B$K8=$l$kMWAG!K$,!$%j%]%8%H%j$X$N(B
$B%Q%9$,1&JU$K8=$l$k!%A*$s$@2>A[%Q%9$H%U%!%$%k%7%9%F%`Cf$G$N0LCV$N4V$K$O$$(B
$B$+$J$k4XO"@-$bI,MW$J$$!%(B

%If you wish, you can use both the \texttt{collections} and
%\texttt{paths} mechanisms simultaneously in a single configuration
%file.
\texttt{collections}$B$H(B\texttt{paths}$B$NN>J}$N5!9=$rF10l$N@_Dj%U%!%$%kFb$G(B
$BF1;~$KMQ$$$k$3$H$b$G$-$k!%(B

%\begin{note}
%  If multiple repositories have the same virtual path,
%  \sfilename{hgwebdir.cgi} will not report an error.  Instead, it will
%  behave unpredictably.
%\end{note}
\begin{note}
$BJ#?t$N%j%]%8%H%j$,F1$82>A[%Q%9$r;}$D>l9g!$(B\sfilename{hgwebdir.cgi}$B$O%(%i!<(B
 $B$r@8$8$J$$$,!$5sF0$OM=B,$N$D$+$J$$$b$N$H$J$k!%(B
\end{note}

%\subsection{Downloading source archives}
\subsection{$B%=!<%9%"!<%+%$%V$N%@%&%s%m!<%I(B}

%Mercurial's web interface lets users download an archive of any
%revision.  This archive will contain a snapshot of the working
%directory as of that revision, but it will not contain a copy of the
%repository data.
$B%f!<%6$O(BMercurial$B$N%&%'%V%$%s%?%U%'!<%9$+$i$I$N%j%S%8%g%s$N%"!<%+%$%V$b(B
$B%@%&%s%m!<%I$9$k$3$H$,$G$-$k!%%"!<%+%$%V$OEv3:%j%S%8%g%s$N%o!<%-%s%0%G%#(B
$B%l%/%H%j$N%9%J%C%W%7%g%C%H$r4^$`$,!$%j%]%8%H%j<+BN$N%G!<%?$O4^$^$J$$!%(B

%By default, this feature is not enabled.  To enable it, you'll need to
%add an \rcitem{web}{allow\_archive} item to the \rcsection{web}
%section of your \hgrc.
$B%G%U%)%k%H$G$O$3$N5!G=$OL58z$K$5$l$F$$$k!%M-8z$K$9$k$K$O(B
\rcitem{web}{allow\_archive}$B9`L\$r(B\hgrc $B$N(B\rcsection{web}$B%;%/%7%g%s$KDI(B
$B2C$9$kI,MW$,$"$k!%(B

%\subsection{Web configuration options}
\subsection{Web$B@_Dj%*%W%7%g%s(B}

%Mercurial's web interfaces (the \hgcmd{serve} command, and the
%\sfilename{hgweb.cgi} and \sfilename{hgwebdir.cgi} scripts) have a
%number of configuration options that you can set.  These belong in a
%section named \rcsection{web}.
Mercurial$B%&%'%V%$%s%?%U%'!<%9(B(the \hgcmd{serve}$B%3%^%s(B
$B%I!$(B\sfilename{hgweb.cgi}$B$*$h$S(B\sfilename{hgwebdir.cgi}$B%9%/%j%W%H(B)$B$K$OB?(B
$B$/$N@_Dj%*%W%7%g%s$,$"$k!%$3$l$i$O(B\rcsection{web}$B%;%/%7%g%s$K4^$^$l$k!%(B

\begin{itemize}
%\item[\rcitem{web}{allow\_archive}] Determines which (if any) archive
%  download mechanisms Mercurial supports.  If you enable this
%  feature, users of the web interface will be able to download an
%  archive of whatever revision of a repository they are viewing.
%  To enable the archive feature, this item must take the form of a
%  sequence of words drawn from the list below.
\item[\rcitem{web}{allow\_archive}] $B$I$N%"!<%+%$%V%@%&%s%m!<%I%a%+%K%:%`(B
	     $B$r(BMercurial$B$,%5%]!<%H$9$k$N$+$r7hDj$9$k!%$3$N5!G=$rM-8z$K$9(B
	     $B$k$H!$%&%'%V%$%s%?%U%'!<%9$N%f!<%6$O%j%]%8%H%j$NG$0U$N%j%S%8%g(B
	     $B%s$N%"!<%+%$%V$r%@%&%s%m!<%I$G$-$k$h$&$K$J$k!%%"!<%+%$%V:r(B
	     $BF|$rM-8z$K$9$k$K$O$3$N9`L\$O!$2<$N%j%9%H$K<($98l$+$i9=@.$5(B
	     $B$l$J$1$l$P$J$i$J$$!%(B

  \begin{itemize}
%  \item[\texttt{bz2}] A \command{tar} archive, compressed using
%    \texttt{bzip2} compression.  This has the best compression ratio,
%    but uses the most CPU time on the server.
\item[\texttt{bz2}] \texttt{bzip2}$B05=L$5$l$?(B\command{tar}$B%"!<%+%$%V!%05=LN($,:G(B
	     $B$b9b$$$,!$%5!<%P$N(BCPU$B;~4V$b0lHV;HMQ$9$k!%(B

%  \item[\texttt{gz}] A \command{tar} archive, compressed using
%    \texttt{gzip} compression.
\item[\texttt{gz}] \texttt{gzip}$B05=L$5$l$?(B\command{tar}$B%"!<%+%$%V!%(B

%  \item[\texttt{zip}] A \command{zip} archive, compressed using LZW
%    compression.  This format has the worst compression ratio, but is
%    widely used in the Windows world.
\item[\texttt{zip}] LZW$B05=L$5$l$?(B\command{zip}$B%"!<%+%$%V!%$3$NCf$G05=LN((B
	     $B$O:GDc$@$,!$(BWindows$B$N4D6-$G$O9-$/MQ$$$i$l$F$$$k!%(B
  \end{itemize}

%  If you provide an empty list, or don't have an
%  \rcitem{web}{allow\_archive} entry at all, this feature will be
%  disabled.  Here is an example of how to enable all three supported
%  formats.
$B6u$N%j%9%H$rM?$($k$+!$(B\rcitem{web}{allow\_archive}$B$r5-=R$7$J$1$l$P!$$3$N(B
	     $B:rF|$OL58z2=$5$l$k!%%5%]!<%H$5$l$F$$$k(B3$B$D$N%U%)!<%^%C%HA4$F(B
	     $B$rM-8z$K$9$kNc$r<($9!%(B
  \begin{codesample4}
    [web]
    allow_archive = bz2 gz zip
  \end{codesample4}

%\item[\rcitem{web}{allowpull}] Boolean.  Determines whether the web
%  interface allows remote users to \hgcmd{pull} and \hgcmd{clone} this
%  repository over~HTTP.  If set to \texttt{no} or \texttt{false}, only
%  the ``human-oriented'' portion of the web interface is available.
\item[\rcitem{web}{allowpull}] $B%V!<%kCM!%%j%b!<%H%f!<%6$K%&%'%V%$%s%?%U%'!<(B
	     $B%9$rMQ$$$?(B~HTTP$B$K$h$k(B\hgcmd{pull}$B5Z$S(B\hgcmd{clone}$B$r5v2D$9(B
	     $B$k$+$I$&$+$r7h$a$k!%(B\texttt{no}$B$^$?$O(B\texttt{false}$B$N>l9g!$(B
	     $B%&%'%V%$%s%?%U%'!<%9$O?M4V$N1\Mw$N$_$,2DG=$K$J$k!%(B

%\item[\rcitem{web}{contact}] String.  A free-form (but preferably
%  brief) string identifying the person or group in charge of the
%  repository.  This often contains the name and email address of a
%  person or mailing list.  It often makes sense to place this entry in
%  a repository's own \sfilename{.hg/hgrc} file, but it can make sense
%  to use in a global \hgrc\ if every repository has a single
%  maintainer.
\item[\rcitem{web}{contact}] $BJ8;zNs!%<+M37A<0!J4J7i$JI=5-$,9%$^$7$$!K$G%j(B
	     $B%]%8%H%j$rC4Ev$9$k?MJ*$d%0%k!<%W$r5-=R$9$k!%DL>o$O?ML>$H!$8D(B
	     $B?M$^$?$O%a!<%j%s%0%j%9%H$N%"%I%l%9$r4^$`!%B?$/$N>l(B
	     $B9g!$(B\sfilename{.hg/hgrc}$B$K$3$N5-=R$rCV$/$N$,NI$$!%$b$7A4$F$N(B
	     $B%j%]%8%H%j$rF10l?MJ*$,4IM}$9$k$N$G$"$l$P!$%0%m!<%P%k$J(B
	     \hgrc\ $B$KCV$/$N$b$h$$!%(B

%\item[\rcitem{web}{maxchanges}] Integer.  The default maximum number
%  of changesets to display in a single page of output.
\item[\rcitem{web}{maxchanges}] $B@0?t!%(B1$B%Z!<%8$KI=<($9$k%A%'%s%8%;%C%H$N(B
	     $B%G%U%)%k%H$N:GBg?t!%(B

%\item[\rcitem{web}{maxfiles}] Integer.  The default maximum number
%  of modified files to display in a single page of output.
\item[\rcitem{web}{maxfiles}] $B@0?t!%(B1$B%Z!<%8$KI=<($9$k99?7$5$l$?%U%!%$%k(B
	     $B$N%G%U%)%k%H$N:GBg?t!%(B

%\item[\rcitem{web}{stripes}] Integer.  If the web interface displays
%  alternating ``stripes'' to make it easier to visually align rows
%  when you are looking at a table, this number controls the number of
%  rows in each stripe.
\item[\rcitem{web}{stripes}] $B@0?t!%I=$NI=<($r9T$&:]$K!$9T$r8+0W$/$9$k$?$a(B
	     $B%&%'%V%$%s%?%U%'!<%9$,8r8_$K(B``$B%9%H%i%$%W(B''$BI=<($9$k>l9g!$$3$N(B
	     $BCM$G$=$l$>$l$N%9%H%i%$%W$N9T?t$r@_Dj$9$k!%(B

%\item[\rcitem{web}{style}] Controls the template Mercurial uses to
%  display the web interface.  Mercurial ships with two web templates,
%  named \texttt{default} and \texttt{gitweb} (the latter is much more
%  visually attractive).  You can also specify a custom template of
%  your own; see chapter~\ref{chap:template} for details.  Here, you
%  can see how to enable the \texttt{gitweb} style.
\item[\rcitem{web}{style}] Mercurial$B$,%&%'%V%$%s%?!<%U%'!<%9$rI=<($9$k$?(B
	     $B$a$K;HMQ$9$k%F%s%W%l!<%H$r@)8f$9$k!%(BMercurial$B$K$O(B
	     \texttt{default}$B$H(B\texttt{gitweb}$B$H$$$&(B2$B$D$N%&%'%V%F%s%W%l!<(B
	     $B%H$,F1:-$5$l$F$$$k!%!J8e<T$NJ}$,8+1I$($,$9$k!%!KFH<+$N%F%s%W(B
	     $B%l!<%H$r;XDj$9$k$3$H$b2DG=$G$"$k!%>\:Y$O(B~\ref{chap:template}$B$r(B
	     $B;2>H$N$3$H!%$3$3$G$O(B\texttt{gitweb}$B%9%?%$%k$rM-8z$K$9$kJ}K!(B
	     $B$r<($9!%(B
  \begin{codesample4}
    [web]
    style = gitweb
  \end{codesample4}
%\item[\rcitem{web}{templates}] Path.  The directory in which to search
%  for template files.  By default, Mercurial searches in the directory
%  in which it was installed.
\item[\rcitem{web}{templates}] $B%Q%9!%%F%s%W%l!<%H%U%!%$%k$r8!:w$9$k%G%#%l(B
	     $B%/%H%j!%%G%U%)%k%H$G$O(BMercurial$B$O%$%s%9%H!<%k$5$l$?%G%#%l%/(B
	     $B%H%j$+$i%F%s%W%l!<%H$rC5$9!%(B
\end{itemize}
%If you are using \sfilename{hgwebdir.cgi}, you can place a few
%configuration items in a \rcsection{web} section of the
%\sfilename{hgweb.config} file instead of a \hgrc\ file, for
%convenience.  These items are \rcitem{web}{motd} and
%\rcitem{web}{style}.
\sfilename{hgwebdir.cgi}$B$rMxMQ$9$k>l9g!$JXMx$N$?$a!$(B\hgrc\ $B%U%!%$%k$G$O$J$/(B
\sfilename{hgweb.config}$B%U%!%$%k$N(B\rcsection{web}$B%;%/%7%g%s$K(B\rcitem{web}{motd}$B$*$h$S(B\rcitem{web}{style}$B9`L\$rCV$/$3$H$,$G$-$k!%(B

%\subsubsection{Options specific to an individual repository}
\subsubsection{$B8D!9$N%j%]%8%H%j$KFCM-$N%*%W%7%g%s(B}

%A few \rcsection{web} configuration items ought to be placed in a
%repository's local \sfilename{.hg/hgrc}, rather than a user's or
%global \hgrc.
$B$$$/$D$+$N(B\rcsection{web} $B@_Dj9`L\$O%f!<%6$d%0%m!<%P%k$N(B \hgrc $B$G$O$J$/!$(B
$B%j%]%8%H%j%m!<%+%k$N(B\sfilename{.hg/hgrc}$B%U%!%$%k$K=q$+$l$k$N$,<+A3$G$"$k!%(B
\begin{itemize}
%\item[\rcitem{web}{description}] String.  A free-form (but preferably
%  brief) string that describes the contents or purpose of the
%  repository.
\item[\rcitem{web}{description}] $BJ8;zNs!%%j%]%8%H%j$NFbMF$dL\E*$K$D$$$F(B
	     $B$N@bL@!%7A<0$O<+M3$@$,!$4J7i$J$b$N$,9%$^$l$k!%(B
%\item[\rcitem{web}{name}] String.  The name to use for the repository
%  in the web interface.  This overrides the default name, which is the
%  last component of the repository's path.
\item[\rcitem{web}{name}] $BJ8;zNs!%%&%'%V%$%s%?%U%'!<%9$G$N%j%]%8%H%jL>!%(B
	     $B$3$NL>A0$O%j%]%8%H%j%Q%9Cf$N:G8e$NMWAG$+$i:n$i$l$k%G%U%)%k%H(B
	     $BL>$r%*!<%P%i%$%I$9$k!%(B
\end{itemize}

%\subsubsection{Options specific to the \hgcmd{serve} command}
\subsubsection{\hgcmd{serve}$B%3%^%s%IFCM-$N%*%W%7%g%s(B}

%Some of the items in the \rcsection{web} section of a \hgrc\ file are
%only for use with the \hgcmd{serve} command.

\hgrc\ $B%U%!%$%k$N(B\rcsection{web}$B%;%/%7%g%s$N9`L\$O(B\hgcmd{serve}$B%3%^%s%I(B
$B$G$N$_MQ$$$i$l$k!%(B

\begin{itemize}
%\item[\rcitem{web}{accesslog}] Path.  The name of a file into which to
%  write an access log.  By default, the \hgcmd{serve} command writes
%  this information to standard output, not to a file.  Log entries are
%  written in the standard ``combined'' file format used by almost all
%  web servers.
\item[\rcitem{web}{accesslog}] $B%Q%9!%%"%/%;%9%m%0$r=PNO$9$k%U%!%$%k$NL>(B
	     $BA0!%%G%U%)%k%H$G$O(B\hgcmd{serve}$B%3%^%s%I$O%U%!%$%k$G$O$J$/I8(B
	     $B=`=PNO$X=PNO$r9T$&!%%m%0%(%s%H%j$O$[$H$s$I$N%&%'%V%5!<%P$G(B
	     $BI8=`$N%3%s%P%$%s%I%U%!%$%k7A<0$G9T$o$l$k!%(B

%\item[\rcitem{web}{address}] String.  The local address on which the
%  server should listen for incoming connections.  By default, the
%  server listens on all addresses.
\item[\rcitem{web}{address}] $BJ8;zNs!%@\B3$KBP$7$F%5!<%P$,BT5!$9$k%m!<%+(B
	     $B%k%"%I%l%9!%%G%U%)%k%H$G$OA4$F$N%"%I%l%9$KBP$7$FBT5!$9$k!%(B

%\item[\rcitem{web}{errorlog}] Path.  The name of a file into which to
%  write an error log.  By default, the \hgcmd{serve} command writes this
%  information to standard error, not to a file.
\item[\rcitem{web}{errorlog}] $B%Q%9!%%(%i!<$r5-O?$9$k%U%!%$%k$NL>A0!%%G%U%)(B
	     $B%k%H$G$O(B \hgcmd{serve}$B%3%^%s%I$O%U%!%$%k$G$O$J$/I8=`%(%i!<(B
	     $B=PNO$X=PNO$r9T$&!%(B

%\item[\rcitem{web}{ipv6}] Boolean.  Whether to use the IPv6 protocol.
%  By default, IPv6 is not used.
\item[\rcitem{web}{ipv6}] $B%V!<%kCM!%(BIPv6$B%W%m%H%3%kMxMQ$NM-L5!%%G%U%)%k%H(B
	     $B$O(BIPv6$BIT;HMQ!%(B

%\item[\rcitem{web}{port}] Integer.  The TCP~port number on which the
%  server should listen.  The default port number used is~8000.
\item[\rcitem{web}{port}] $B@0?t!%%5!<%P$,BT5!$9$k(BTCP$B%]!<%HHV9f!%%G%U%)%k(B
	     $B%H$O(B8000$BHV(B.

\end{itemize}

%\subsubsection{Choosing the right \hgrc\ file to add \rcsection{web}
  %items to}
\subsubsection{\rcsection{web}$B%"%$%F%`$rDI2C$9$k@5$7$$(B\hgrc $B%U%!%$%k$rA*$V(B}

%It is important to remember that a web server like Apache or
%\texttt{lighttpd} will run under a user~ID that is different to yours.
%CGI scripts run by your server, such as \sfilename{hgweb.cgi}, will
%usually also run under that user~ID.

Apache$B$d(B\texttt{lighttpd}$B$N$h$&$J%&%'%V%5!<%P$OFH<+$N%f!<%6(B~ID$B$GF0:n$9$k(B
$B$3$H$KN10U$9$kI,MW$,$"$k!%(B\sfilename{hgweb.cgi}$B$N$h$&$J(BCGI$B%9%/%j%W%H$ODL(B
$B>o%5!<%P$,%5!<%P$N%f!<%6(B~ID$B$GF0:n$5$;$k!%(B

%If you add \rcsection{web} items to your own personal \hgrc\ file, CGI
%scripts won't read that \hgrc\ file.  Those settings will thus only
%affect the behaviour of the \hgcmd{serve} command when you run it.  To
%cause CGI scripts to see your settings, either create a \hgrc\ file in
%the home directory of the user ID that runs your web server, or add
%those settings to a system-wide \hgrc\ file.

\rcsection{web}$B%"%$%F%`$r%f!<%68D?M$N(B\hgrc\ $B%U%!%$%k$KDI2C$7$F$b(BCGI$B%9%/%j(B
$B%W%H$O$=$N(B\hgrc\ $B$r;2>H$7$J$$!%$3$l$i$N@_Dj$O!$%f!<%6$,5/F0$9$k(B
\hgcmd{serve}$B%3%^%s%I$K$N$_1F6A$rM?$($k!%$"$J$?$,9T$C$?@_Dj$r(BCGI$B%9%/%j%W(B
$B%H$+$i;2>H$5$;$k$?$a$K$O!$%&%'%V%5!<%P$r5/F0$9$k%f!<%6(BID$B$N%[!<%`%G%#%l%/(B
$B%H%j$K(B\hgrc\ $B%U%!%$%k$r:n$j!$@_Dj$r%7%9%F%`$N(B\hgrc\ $B%U%!%$%k$K$bDI2C$9$k(B
$BI,MW$,$"$k!%(B

%%% Local Variables:
%%% mode: yatex
%%% TeX-master: "00book"
%%% End: