foozy@708: \chapter{Collaborating with other people}
foozy@708: \label{cha:collab}
foozy@708: 
foozy@708: Mercurial は完全に非中央集約的なツールであるため、
foozy@708: 利用者相互の連携に関しては何ら制約を課すことをしません。
foozy@708: ですが、
foozy@708: 分散構成管理に馴染みが無いのであれば、
foozy@708: いくつかのツールや使用例を知っておくことは、
foozy@708: 妥当な作業手順のモデルを考える際に役に立ちます。
foozy@708: 
foozy@708: \section{Mercurial's web interface}
foozy@708: 
foozy@708: Mercurial は、
foozy@708: いくつかの有用な機能を提供する、
foozy@708: 強力なウェブインタフェースを持っています。
foozy@708: 
foozy@708: 対話的な利用の場合、
foozy@708: ウェブインタフェース経由で１つないし複数のリポジトリの閲覧ができます。
foozy@708: リポジトリ履歴の参照や、
foozy@708: 個々の変更（コミットメッセージや差分）の検証、
foozy@708: および各ディレクトリやファイルの内容の参照、
foozy@708: といったことができます。
foozy@708: 
foozy@708: 通知に関しても、
foozy@708: ウェブインタフェースは、
foozy@708: リポジトリにおける変更に関する RSS 配信機能を提供します。
foozy@708: お気に入りのツールを使ってリポジトリを``購読''することもできますし、
foozy@708: リポジトリにおける活動状況の自動通知を即座に行うこともできます。
foozy@708: リポジトリ提供者側における追加設定が不要であることから、
foozy@708: 筆者自身は、
foozy@708: 変更通知のメーリングリストよりも、
foozy@708: 「RSS 配信を購読」するモデルの方が非常に便利だと思います。
foozy@708: 
foozy@708: ウェブインタフェースにより、
foozy@708: 遠隔ユーザによるリポジトリの複製や変更の取り込み、
foozy@708: および（サーバ側でそれを許可しているならば）
foozy@708: 変更の受理が可能になります。
foozy@708: Mercurial の HTTP トンネリングプロトコルでは、
foozy@708: 積極的にデータの圧縮を行いますので、
foozy@708: 狭い帯域のネットワーク接続経由でも効率よく機能します。
foozy@708: 
foozy@708: ウェブインタフェースを触ってみる最も簡単な方法は、
foozy@708: Mercurial のマスタリポジトリである
foozy@708: \url{http://www.selenic.com/repo/hg?style=gitweb} のような、
foozy@708: 既存のリポジトリにウェブブラウザで接続してみることです。
foozy@708: 
foozy@708: 自身でリポジトリのウェブインタフェースを提供することに興味がある場合、
foozy@708: Mercurial には２つの選択肢があります。
foozy@708: １つは \hgcmd{serve} コマンドを使用するもので、
foozy@708: 短期間の``軽量な''稼動の場合に最適です。
foozy@708: このコマンドの利用に関する詳細は、
foozy@708: \ref{sec:collab:serve}~節を参照してください。
foozy@708: 長期的且つ常時利用可能な稼動を望む場合は、
foozy@708: Mercurial に組み込まれている
foozy@708: CGI （Common Gateway Interface）機能が、
foozy@708: 一般的な全てのウェブサーバで利用可能です。
foozy@708: CGI 設定の詳細は、
foozy@708: \ref{sec:collab:cgi}~節を参照してください。
foozy@708: 
foozy@708: \section{Collaboration models}
foozy@708: 
foozy@708: 適切な柔軟性を持つツールを使うことで、
foozy@708: 作業手順の決定は、
foozy@708: 技術的な問題から組織工学的（social engineering）な問題へと変わります。
foozy@708: Mercurial は、
foozy@708: プロジェクトにおける作業手順の構成に関して殆ど制限を課さないため、
foozy@708: 個別の要望に沿ったモデルの設定と運用は利用者次第となります。
foozy@708: 
foozy@708: \subsection{Factors to keep in mind}
foozy@708: 
foozy@708: いずれのモデルにおいても心得ておくべき最も重要な点は、
foozy@708: それを利用する人々の要望と能力にどれだけ適合するか、
foozy@708: ということです。
foozy@708: これは自明に見えるかもしれませんが、
foozy@708: ほんの少しの間でもこのことを忘れてはいけません。
foozy@708: 
foozy@708: 筆者は以前、完璧と思える作業手順モデルを構築したのですが、
foozy@708: 開発チームに少なからぬ量の驚きと不和をもたらしました。
foozy@708: 複雑なブランチ群が必要な理由と、
foozy@708: それらの間における変更の取り扱いについて説明しようと試みましたが、
foozy@708: チームのメンバーの何人かが異を唱えてきたのです。
foozy@708: 彼らは聡明な人達でしたが、
foozy@708: 作業における制約に注意を払う\footnote{訳注: 「ルールを守る」の意か？}ことも、
foozy@708: 筆者が唱えるモデルの細部における制約の重要性に向き合おうともしませんでした。
foozy@708: 
foozy@708: 近い将来の社会的・技術的な問題から目を背けないでください。
foozy@708: どんな計画を実施しようとも、
foozy@708: 間違いや問題が発生した場合に備えるべきです。
foozy@708: 予想可能な問題に対して、
foozy@708: 自動的な防御や即時復旧のための仕組みの追加を考慮しましょう。
foozy@708: 例えば、
foozy@708: リリース向けではない変更のためのブランチを作成しようとした場合、
foozy@708: 他の作業者がリリース用ブランチにうっかりマージしてしまう可能性について、
foozy@708: 早い時点で考慮したほうが良いでしょう。
foozy@708: 不適切なブランチからチェンジセットをマージさせないフックを記述することで、
foozy@708: この問題に関しては回避可能です。
foozy@708: 
foozy@708: \subsection{Informal anarchy}
foozy@708: 
foozy@708: 持続可能性の点から
foozy@708: ``何でもアリ''なやり方はお薦めしませんが、
foozy@708: 簡単に把握することができるモデルであり、
foozy@708: いくつかの特異な状況では非常に良く機能します。
foozy@708: 
foozy@708: 一つの例として、
foozy@708: 多くのプロジェクトが、
foozy@708: 直接会うことの稀な弱くまとまった協力者グループを持ている
foozy@708: As one example, many projects have a loose-knit group of collaborators
foozy@708: who rarely physically meet each other.  
foozy@708: 時折の``全力疾走''（sprints）\footnote{訳注:
foozy@708: オフ会とかですね。}を設けることで、
foozy@708: 距離によって隔てられた作業に打ち勝つグループもあります。
foozy@708: 全力疾走の機会では、
foozy@708: 多くの人が共に同じ場所（会社の会議室やホテルの会議室の類）
foozy@708: に集まり、
foozy@708: 数日程度を閉じこもって過ごし、
foozy@708: 少量のプロジェクトに集中してハッキングを行います。
foozy@708: 
foozy@708: 全力疾走は、
foozy@708: 大掛かりなサーバインフラを必要としない
foozy@708: \hgcmd{serve} コマンドを利用するのにちょうど良い機会です。
foozy@708: 以下の\ref{sec:collab:serve}~節を読むことで、
foozy@708: すぐにでも \hgcmd{serve} を使い始めることができます。
foozy@708: そうしたなら、
foozy@708: 周囲の人達にサーバを実行中であることを伝え、
foozy@708: インスタントメッセンジャー等を使用して URL を送れば、
foozy@708: 共同作業する上での折り返し地点まで辿り着きました。
foozy@708: ブラウザに教えられた URL を入力すれば、
foozy@708: 彼らはすぐにでもあなたの変更をレビューすることができますし、
foozy@708: あなたからバグフィックスを入手してそれを検証したり、
foozy@708: 新機能が含まれるブランチを複製してそれを試してみたりすることができます。
foozy@708: 
foozy@708: その場限りのこのような形式で事を進めることの利点と欠点は、
foozy@708: あなたによる変更の存在と、どこでアクセス可能かを知る人だけが、
foozy@708: それを参照することができる、という点にあります。
foozy@708: このような非公式な手法は、
foozy@708: 複数の異なるリポジトリからの取り込みが各自に要求されるため、
foozy@708: 数人以上に対しては単純に規模の拡大ができません。
foozy@708: 
foozy@708: \subsection{A single central repository}
foozy@708: 
foozy@708: 小規模なプロジェクトにおいて、
foozy@708: 中央集約的な構成管理ツールからの移行する最も簡単な方法は、
foozy@708: 単一の共有リポジトリを経由して変更のやり取りをする、
foozy@708: というものです。
foozy@708: この体制は、
foozy@708: より野心的な作業手順体系のための最も基本的な``構成要素''でもあります。
foozy@708: 
foozy@708: 開発者（contributor）は、
foozy@708: 共有リポジトリの複製を行うことで作業を開始します。
foozy@708: 必要な時にいつでも変更の取り込みを行えますし、
foozy@708: 開発者の何人かは（全員でも可）、
foozy@708: 外部に公開可能になった際に変更を共有リポジトリに反映させる権限を持ちます。
foozy@708: 
foozy@708: このモデルであっても、
foozy@708: 共有リポジトリを経由せずにお互いの変更を直接 \hgcmd{pull} することは、
foozy@708: 開発者にとっては意義のあることです。
foozy@708: 例えば、
foozy@708: 暫定的なバグ修正を行ったものの、
foozy@708: 共有リポジトリにその修正を公開した場合に、
foozy@708: その修正を取り込んだ他の開発者の作業に支障をきたす恐れがある、
foozy@708: という場合を考えてみましょう。
foozy@708: バグ修正を含む自分のリポジトリから一時的なリポジトリを複製し、
foozy@708: 複製先で修正内容を検証してもらえるように他の開発者にお願いすることで、
foozy@708: 潜在的な損害を低減することができます。
foozy@708: このようにすることで、
foozy@708: 潜在的な危険性を持つ変更であっても、
foozy@708: 簡単な検証が済むまでは公開されないようにすることができます。
foozy@708: 
foozy@708: この種のやり取りの場合は、
foozy@708: 共有リポジトリへの安全な変更反映のために
foozy@708: \command{ssh} プロトコルを使用するのが一般的です
foozy@708: （\ref{sec:collab:ssh}~節参照）。
foozy@708: 読み出し専用リポジトリを、
foozy@708: CGI を使用して HTTP 経由で公開することも可能です
foozy@708: （\ref{sec:collab:cgi}~節参照）。
foozy@708: リポジトリへの変更反映が必要ない場合や、
foozy@708: リポジトリの履歴をウェブブラウザ経由で参照したい場合には、
foozy@708: HTTP 経由での公開で十分ニーズが満たされます。
foozy@708: 
foozy@708: \subsection{Working with multiple branches}
foozy@708: 
foozy@708: 一定以上の規模を持つプロジェクトにおいては、
foozy@708: 作業の進展が同時に複数の「前線」で行われることは自然な成り行きです。
foozy@708: ソフトウェア開発の場合、
foozy@708: どのプロジェクトでも、
foozy@708: 一定期間ごとに公式リリースを行うのが一般的です。
foozy@708: 各リリースは最初の公開の後に、
foozy@708: 一定期間の``保守状態''（maintenance mode）となることがあります。
foozy@708: 保守リリースではバグ修正のみを扱い、
foozy@708: 新規機能については取り扱わないのが通例です。
foozy@708: これら保守リリースと平行して、
foozy@708: （場合によっては複数の）将来のリリースに向けた開発が進行します。
foozy@708: 方向性の少し異なる、これら進行中の個々の開発を指すのに、
foozy@708: 一般的に``ブランチ''という表現を使います。
foozy@708: 
foozy@708: Mercurial は特に、
foozy@708: 複数の異なるブランチを同時に管理することに適しています。
foozy@708: それぞれの``開発指向''ごとに、
foozy@708: 別々の共有用リポジトリを用意することで、
foozy@708: 必要になる都度、
foozy@708: あるリポジトリから別のリポジトリへのマージを行えば良いのです。
foozy@708: 各リポジトリは互いに独立していますから、
foozy@708: 誰かが明示的にマージしない限りは
foozy@708: 開発ブランチにおける不安定な変更が、
foozy@708: 安定版のためのブランチに影響を与えることはありません。
foozy@708: 
foozy@708: ブランチごとにリポジトリを用意する遣り方の実際の例を以下に示します。
foozy@708: 中央のサーバに``メインブランチ''があるものとします。
foozy@708: 
foozy@708: \interaction{branching.init}
foozy@708: 
foozy@708: 開発者はメインブランチから複製し、
foozy@708: 変更、変更のテスト、コミットの後に、
foozy@708: 変更をメインブランチのリポジトリに反映します。
foozy@708: 
foozy@708: メインブランチがリリースのマイルストーンに達したならば、
foozy@708: マイルストーンとなるリビジョンに
foozy@708: \hgcmd{tag} コマンドで永続的な名前を付与します。
foozy@708: 
foozy@708: \interaction{branching.tag}
foozy@708: 
foozy@708: メインブランチでは開発が継続しているとします。
foozy@708: 
foozy@708: \interaction{branching.main}
foozy@708: 
foozy@708: リリースマイルストーン後の任意の時点でリポジトリを複製した開発者は、
foozy@708: リリースマイルストーンで記録されたタグを使うことで、
foozy@708: タグが付与されたリビジョンがコミットされた時点と
foozy@708: 厳密に一致する作業領域ディレクトリを
foozy@708: \hgcmd{update} コマンドにより複製することができます。
foozy@708: 
foozy@708: \interaction{branching.update}
foozy@708: 
foozy@708: それに加えて、
foozy@708: メインブランチでのタグ付けの後で、
foozy@708: サーバ上のメインブランチを、
foozy@708: 新たな``安定版''ブランチ（のリポジトリ）へと複製することもできます\footnote{
foozy@708: 訳注: メインブランチと安定版ブランチの各リポジトリは、
foozy@708: 必ずしも同一サーバで運用される必要はありません。}。
foozy@708: 
foozy@708: \interaction{branching.clone}
foozy@708: 
foozy@708: 安定版ブランチに対して変更する必要がある場合、
foozy@708: 開発者は\emph{安定版ブランチ}のリポジトリから複製し、
foozy@708: 変更、変更のテスト、コミットの後に、
foozy@708: 変更を安定版ブランチのリポジトリに反映します。
foozy@708: 
foozy@708: \interaction{branching.stable}
foozy@708: 
foozy@708: Mercurial のリポジトリはお互いに（物理的に）独立しており、
foozy@708: リポジトリ間での変更の自動的なやり取りは行われないため、
foozy@708: 安定版ブランチととメインブランはお互いに\emph{隔離}されています。
foozy@708: メインブランチに加えた変更が安定版ブランチに``漏れ出す''ことはありませんし、
foozy@708: その逆に関しても同様です。
foozy@708: 
foozy@708: 安定版ブランチにおける全てのバグ修正を、
foozy@708: メインブランチに反映したい場合もあるでしょう。
foozy@708: メインブランチでバグ修正を再度（手動で）行う代わりに、
foozy@708: 安定版ブランチから取り込んだ変更をメインブランに対してマージすることで、
foozy@708: 安定版ブランチにおける変更をメインブランチに持ち込むことができます。
foozy@708: 
foozy@708: \interaction{branching.merge}
foozy@708: 
foozy@708: この時点でのメインブランチは、
foozy@708: 安定版ブランチには無い変更を保持していますが、
foozy@708: 安定版ブランチにおける全てのバグ修正を保持しています。
foozy@708: 安定版ブランチは、
foozy@708: メインブランチにのみ含まれる変更には影響を受けないままです。
foozy@708: 
foozy@708: \subsection{Feature branches}
foozy@708: 
foozy@708: 大規模プロジェクトで有効な変更管理方法は、
foozy@708: 開発チームを小さなグループに分割することです。
foozy@708: プロジェクト全体が参照する単一の``マスター''ブランチから複製した共有ブランチ
foozy@708: （＝ リポジトリ）を、
foozy@708: 各グループごとにそれぞれ持ちます。
foozy@708: 個々のブランチ上で作業する開発メンバーは、
foozy@708: 他のブランチにおける開発作業とは隔離されています。
foozy@708: 
foozy@708: \begin{figure}[ht]
foozy@708:   \centering
foozy@708:   \grafix[width=\textwidth]{feature-branches}
foozy@708:   \caption{Feature branches}
foozy@708:   \label{fig:collab:feature-branches}
foozy@708: \end{figure}
foozy@708: 
foozy@708: とある機能が適切な状況\footnote{訳注:
foozy@708: ``コンパイルエラーが無くなった''状況なのか、
foozy@708: ``単体テストが完了した''状況なのかは、
foozy@708: 各プロジェクトの構成管理方針次第となります。}に到達したと判断されたなら、
foozy@708: 当該機能の担当チームでは、
foozy@708: マスターブランチ（のリポジトリ）
foozy@708: から反映した変更を自チームのブランチ（のリポジトリ）へとマージしてから、
foozy@708: マスターブランチへとマージ結果を反映すれば良いのです。
foozy@708: 
foozy@708: \subsection{The release train}
foozy@708: 
foozy@708: プロジェクトによっては、
foozy@708: ``train''モデルで運用されている場合もあります。
foozy@708: ``train'' モデルで運用されているプロジェクトでは、
foozy@708: リリースは数ヶ月ごとに設定されており、
foozy@708: ``train''が出発準備完了した段階\footnote{訳注: 
foozy@708: 「数ヶ月ごとに設定されたリリーススケジュール」を
foozy@708: 「時刻表通りの発車時刻」に例えている模様。
foozy@708: }で提供可能な機能だけがリリースに含まれます。
foozy@708: 
foozy@708: このモデルは、先に説明した機能別ブランチによる作業と似ています。
foozy@708: ``train''モデルの場合、
foozy@708: 機能別ブランチが列車に乗りそこなった場合、
foozy@708: 当該機能の担当チームでは、
foozy@708: 自チームの機能ブランチ（リポジトリ）に対して、
foozy@708: リリース列車に含まれる変更の取り込みおよびマージを行い、
foozy@708: マージ結果に対して作業を継続する必要がある点が異なります。
foozy@708: このマージ作業を行うことで、
foozy@708: 次回リリースの際に、
foozy@708: 当該機能が整合性を保つことができます。
foozy@708: 
foozy@708: \subsection{The Linux kernel model}
foozy@708: 
foozy@708: Linux カーネルの開発体制は、
foozy@708: 浅い階層構造と、それを取り囲む一見混沌とした群集から成り立っています。
foozy@708: 殆どの Linux 開発者が、
foozy@708: Mercurial と同等の機能を持った分散構成管理ツールである
foozy@708: \command{git} コマンドを使用しているので、
foozy@708: Linux カーネル開発における作業手順の説明は
foozy@708: Mercurial 利用にとっても有用性を持っています。
foozy@708: 気に入ったアイデアがあれば、
foozy@708: ツールを超えて手法を利用することは可能なのですから。
foozy@708: 
foozy@708: コミュニティの中心には、
foozy@708: Linux を創り出した Linus Torvalds 氏がいます。
foozy@708: 彼は単一のソースリポジトリを公開しており、
foozy@708: 開発コミュニティ全体にとっては、
foozy@708: このリポジトリが``権威ある''現行ソースツリーとみなされます。
foozy@708: 誰もが Torvalds 氏のソースツリーを複製できますが、
foozy@708: 誰のツリーから変更を取り込むかという点に関して、
foozy@708: Torvalds 氏は非常に慎重な選択をしています。
foozy@708: 
foozy@708: Torvalds 氏には``信頼できる補佐役''が何人かいます。
foozy@708: 彼ら補佐役が公開している変更は、
foozy@708: レビューが行われていなくても、
foozy@708: 大概は Torvalds 氏により取り込まれます。
foozy@708: 補佐役のうちの何人かは、
foozy@708: ``保守担当者''として承認されており、
foozy@708: カーネルの特定のサブシステムに関する責任を負っています
foozy@708: とあるカーネルハッカーがサブシステムへの変更を行い、
foozy@708: その変更を最終的に Torvalds 氏のツリーに取り込んで欲しいと考えた場合、
foozy@708: 当該サブシステムの保守担当者が誰であるかを調べて、
foozy@708: その担当者に変更の採用をお願いする必要があります。
foozy@708: 保守担当者が変更のレビューの後に採用に同意した場合、
foozy@708: その変更は手順に従い Torvalds 氏へと渡されます。
foozy@708: 
foozy@708: 個々の補佐役は、
foozy@708: 変更のレビュー・承認および公開に関するそれぞれの手法を持っており、
foozy@708: Torvalds 氏への変更送付時期の判断に関しても、それは当てはまります。
foozy@708: それに加えて、
foozy@708: 異なる目的向けの良く知られたブランチがいくつか存在します。
foozy@708: 例えば、
foozy@708: 古い版のカーネルの``安定版''リポジトリが、
foozy@708: 必要に応じて深刻な障害の修正を適用するために、
foozy@708: 少数の人々により保守されています。
foozy@708: 何人かの保守担当者は、
foozy@708: 複数のソースツリーを公開しています。
foozy@708: １つは実験的な変更のためのもの、
foozy@708: １つは上流リポジトリから配布しようとしている変更のためのもの、
foozy@708: といった按配です。
foozy@708: 他の保守担当者は、ソースツリーを１つだけ公開しています。
foozy@708: 
foozy@708: Linux におけるこのモデルは、
foozy@708: ２つの注目に値する特徴を持っています。
foozy@708: １つ目は``取り込み限定''（pull only）である点です。
foozy@708: 保守担当者以外が変更を反映できるソースツリーが殆ど無く、
foozy@708: 他の人が管理しているソースツリーに変更を反映する方法が無いことから、
foozy@708: 変更を反映させたいソースツリーの保守担当者に対して、
foozy@708: 変更の採用を\emph{お願い}する必要があります。
foozy@708: 
foozy@708: ２つ目の特徴は、
foozy@708: 知名度と評判に基づいている点です。
foozy@708: 名の知られていない開発者からの変更依頼の場合、
foozy@708: Torvalds 氏が依頼メールを受け取ったのなら、
foozy@708: 返信もせずに無視してしまうでしょう。
foozy@708: しかし、
foozy@708: サブシステムの保守担当者が依頼メールを受け取った場合、
foozy@708: 内容がレビューされた上で、
foozy@708: それが保守担当者の基準を満たしていれば、
foozy@708: おそらくその変更は採用されるでしょう。
foozy@708: より``良い''変更で貢献する程、
foozy@708: 保守担当者はあなたの判断を信頼するでしょうし、
foozy@708: あなたの変更依頼が受理度される度合いも増すでしょう。
foozy@708: あなたが有名になり、
foozy@708: Torvalds 氏がまだ受理していない息の長いブランチの保守を行うようになれば、
foozy@708: あなたの作業内容に追従するために、
foozy@708: 似たような興味を持つ人々があなたの変更を定期的に取り込むようになるでしょう。
foozy@708: 
foozy@708: 知名度や評判は、
foozy@708: 必ずしもサブシステムや``人的''境界を越えるわけではありません。
foozy@708: 専らストレージ系で著名なハッカーが、
foozy@708: ネットワークのバグ修正を試みた場合、
foozy@708: ネットワークサブシステムの保守担当者による監査は、
foozy@708: 全くの部外者による変更と同程度となるでしょう。
foozy@708: 
foozy@708: より整然としたプロジェクト従事の経験を持つ人にとって、
foozy@708: 相当に無秩序な Linux カーネルの開発手順は、
foozy@708: 全く非常識なものに見えることでしょう。
foozy@708: この開発形態は、個人の気まぐれの影響を受けやすいのです。
foozy@708: 作業は各自の都合の良い時に、驚くべきペース行われます。
foozy@708: それでもなお  Linux は、
foozy@708: 成功を収めた重要なソフトウェアの１つとなっています。
foozy@708: 
foozy@708: \subsection{Pull-only versus shared-push collaboration}
foozy@708: 
foozy@708: 他の人のリポジトリからは変更の反映のみしかしないモデルと、
foozy@708: 複数の人々が共有リポジトリへの変更反映を行うことができる開発モデルの、
foozy@708: どちらが``より良い''モデルであるかは、
foozy@708: オープンソースコミュニティにおいて継続的な議論の的になっています。
foozy@708: です。
foozy@708: 
foozy@708: 共有リポジトリ＋反映モデルの支持者は、
foozy@708: その手法を積極的に使用するツールを使用する傾向にあります。
foozy@708: Subversion のような中央集約的な構成管理ツールを使用している場合、
foozy@708: 採用するモデルの選択肢はありません。
foozy@708: 共有リポジトリ＋反映モデルがツールによって強制されるため、
foozy@708: 他のモデルを使用するには、
foozy@708: そのツール上で独自の手法（例えば、手動で \command{patch}
foozy@708: を宛てる、など）を駆使する必要があります。
foozy@708: 
foozy@708: Mercurial のような適切な分散構成管理ツールであれば、
foozy@708: 両方のモデルを選択可能です。
foozy@708: 利用者間の連携形態は、
foozy@708: ツールにより強制される歪んだものではなく、
foozy@708: 固有の要望や好みに基づいて構築することができます。
foozy@708: 
foozy@708: \subsection{Where collaboration meets branch management}
foozy@708: 
foozy@708: 共有リポジトリを構築し、
foozy@708: 各作業者が手元のリポジトリと共有リポジトリとの間で、
foozy@708: 変更の伝播を開始し始めたなら、
foozy@708: チーム内の開発の方向性を同時に複数管理するという、
foozy@708: 連携に関することではありつつも、
foozy@708: 微妙に異なる難問に直面することでしょう。
foozy@708: この問題は開発チームの連携方式と密接に関連してはいるものの、
foozy@708: 改めて取り上げる価値があるほど非常に込み入った話であることから、
foozy@708: \ref{chap:branch}~章で改めて説明します。
foozy@708: 
foozy@708: \section{The technical side of sharing}
foozy@708: 
foozy@708: 本章の残りは、
foozy@708: 共同作業者に対してデータの提供を行う上での問題点に割きたいと思います。
foozy@708: 
foozy@708: \section{Informal sharing with \hgcmd{serve}}
foozy@708: \label{sec:collab:serve}
foozy@708: 
foozy@708: Mercurial の \hgcmd{serve} コマンドは、
foozy@708: 小さく緊密で足並みの早い集団での利用に大変適しています。
foozy@708: \hgcmd{serve} コマンドはまた、
foozy@708: ネットワーク越しでの Mercurial コマンドの利用感を掴むための、
foozy@708: 素晴らしい手段を提供しています。
foozy@708: 
foozy@708: リポジトリ配下において \hgcmd{serve} を実行することで、
foozy@708: １秒も経たずに特製の HTTP サーバが起動します。
foozy@708: 実行が停止されるまでの間にこの HTTP サーバは、
foozy@708: 任意のクライアントからの接続を受理し、
foozy@708: 当該リポジトリ中のデータの提供を行います。
foozy@708: たった今起動したばかりのサーバの URL を知っていて、
foozy@708: ネットワーク越しにサーバが稼動しているコンピュータと通信できるなら、
foozy@708: ウェブブラウザや Mercurial を利用して、
foozy@708: 誰もがリポジトリからデータを読み出すことができます。
foozy@708: ノート PC 上で稼動する \hgcmd{serve} プロセスの URL は、
foozy@708: \Verb|http://my-notepc.local:8000/| のような形式になります。
foozy@708: 
foozy@708: \hgcmd{serve} コマンドは汎用ウェブサーバでは\emph{ありません}。
foozy@708: このコマンドを使用することで２つの事が可能になります。
foozy@708: 
foozy@708: \begin{itemize}
foozy@708: \item 一般的なウェブブラウザ経由でのサービス対象リポジトリの履歴の閲覧
foozy@708: 
foozy@708: \item Mercurial プロトコルによる通信を行うことで、
foozy@708:   リポジトリ内チェンジセットの \hgcmd{clone} ないし \hgcmd{pull}
foozy@708: 
foozy@708: \end{itemize}
foozy@708: 
foozy@708: とりわけ遠隔ユーザによる対象リポジトリの\emph{変更}を許可しないことから、
foozy@708: \hgcmd{serve} は読み出し専用としての利用が想定されています。
foozy@708: 
foozy@708: Mercurial を既に利用し始めているのであれば、
foozy@708: 自身のコンピュータ上のリポジトリを対象として
foozy@708: \hgcmd{serve} を利用することができますから、
foozy@708: ネットワーク越しに公開されているリポジトリの場合と同様に、
foozy@708: \hgcmd{clone} や \hgcmd{incoming} 
foozy@708: のようなコマンドを使用して、
foozy@708: \hgcmd{serve} によって起動されたサーバと通信してみましょう。
foozy@708: ネットワーク経由で公開されているリポジトリに対するコマンドの使用方法を、
foozy@708: 手早く習得する一助に \hgcmd{serve} を使用するのも良いでしょう。
foozy@708: 
foozy@708: \subsection{A few things to keep in mind}
foozy@708: 
foozy@708: \hgcmd{serve} は、
foozy@708: ネットワーク越しの読み出し操作を認証無しで全て許可しているため、
foozy@708: 対象リポジトリからデータを読み出すために誰が接続して来るのかを、
foozy@708: 気にしなくて良い（あるいは完全に制御できる）環境でのみ
foozy@708: \hgcmd{serve}  を使うようにすべきです。
foozy@708: 
foozy@708: コンピュータやネットワークへのファイヤウォールの導入状況について、
foozy@708: \hgcmd{serve} コマンドは一切関知しません。
foozy@708: ファイヤウォールの検出も制御もできません。
foozy@708: 実行中の \hgcmd{serve} プロセスとの通信ができない場合は、
foozy@708: （理商社が正しい URL を使用していることを確認した\emph{後}で）
foozy@708: ファイアウォールの設定を確認すべきです。
foozy@708: 
foozy@708: \hgcmd{serve} によるネットワーク接続の受け付けは、
foozy@708: 通常は 8000 番ポートで行われます。
foozy@708: 当該ポートが既に他のプロセスにより使用されていた場合は、
foozy@708: \hgopt{serve}{-p} オプションを使用することで、
foozy@708: 接続受け付けポート番号を指定することができます。
foozy@708: 
foozy@708: \hgcmd{serve} 起動の際には通常何も出力されませんので、
foozy@708: 少々不安になるかもしれません。
foozy@708: \hgcmd{serve} が適切に稼動していることを確認したり、
foozy@708: 共同作業者に送付する URL を知りたいのであれば、
foozy@708: \hggopt{-v} オプション付きで \hgcmd{serve} を起動してください。
foozy@708: 
foozy@708: \section{Using the Secure Shell (ssh) protocol}
foozy@708: \label{sec:collab:ssh}
foozy@708: 
foozy@708: Secure Shell （\texttt{ssh}）プロトコルを使用することで、
foozy@708: ネットワーク接続越しに安全に変更内容の取り込み・反映を行うことができます。
foozy@708: この接続方法を正しく機能させるには、
foozy@708: クライアントあるいはサーバ側で少々設定が必要かもしれません。
foozy@708: 
foozy@708: ssh に馴染みがないのであれば、
foozy@708: 他のコンピュータと安全に通信するためのネットワークプロトコルである、
foozy@708: と理解しておいてください。
foozy@708: Mercurial で ssh を利用するには、
foozy@708: サーバへのログインおよびコマンド実行ができるように、
foozy@708: サーバ側にユーザアカウントを（必要であれば複数）用意する必要があります。
foozy@708: 
foozy@708: （ssh について詳しい場合、
foozy@708: 以降の説明はおそらく非常に初歩的に感じるでしょう）
foozy@708: 
foozy@708: \subsection{How to read and write ssh URLs}
foozy@708: 
foozy@708: ssh プロトコルを利用する場合の URL は、
foozy@708: 概ね以下のような形式を持ちます。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   ssh://bos@hg.serpentine.com:22/hg/hgbook
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: \begin{enumerate}
foozy@708: \item ``\texttt{ssh://}' 部分が Mercurial に ssh プロトコルの利用を指示します
foozy@708: 
foozy@708: \item ``\texttt{bos@}''部分がサーバへのログインにおけるユーザ名を表します。
foozy@708:   サーバでのユーザ名がローカルマシン上のユーザ名と一致する場合は、
foozy@708:   この部分を省略できます。
foozy@708: 
foozy@708: \item ``\texttt{hg.serpentine.com}'' 
foozy@708:   部分はログイン先サーバのホスト名を表します。
foozy@708: 
foozy@708: \item ``:22'' 部分はサーバに接続する際のポート番号を表します。
foozy@708:   ssh 接続における既定ポート番号は 22 番ですので、
foozy@708:   22 番\emph{以外}のポートを使用する場合のみ指定が必要です。
foozy@708: 
foozy@708: \item URL の残りの部分はサーバ上におけるリポジトリのパスを表します。
foozy@708: 
foozy@708: \end{enumerate}
foozy@708: 
foozy@708: ssh プロトコルにおける URL 表記のパス要素部分には、
foozy@708: 値の解釈に関する標準的な手法がないために、
foozy@708: 混乱の余地が多々あります。
foozy@708: 一群のプログラムは、
foozy@708: パス要素部分に関して他のプログラムと異なる振る舞いをします。
foozy@708: このような状況は理想的ではありませんが、
foozy@708: 状況が変わりそうにはありません。
foozy@708: ですから以降の説明は注意深く読んでください。
foozy@708: 
foozy@708: Mercurial はパス部分を、
foozy@708: サーバにログインするユーザの、
foozy@708: ホームディレクトリに対する相対パスとみなします。
foozy@708: 例えば、
foozy@708: サーバにおける \texttt{foo} ユーザのホームディレクトリが
foozy@708: \dirname{/home/foo} である場合、
foozy@708: ssh プロトコルにおける URL のパス要素が \dirname{bar} であれば、
foozy@708: その URL により\emph{実際に}参照されるのは
foozy@708: \dirname{/home/foo/bar} ディレクトリです。
foozy@708: 
foozy@708: 他のユーザのホームディレクトリに対する相対パスを指定する場合は、
foozy@708: チルダ文字（\texttt{~}）にユーザ名（ここでは
foozy@708: \texttt{otheruser} とします）を続けたパスで始まる、
foozy@708: 以下のような表記になります。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   ssh://server/~otheruser/hg/repo
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: \emph{絶対}パスによる指定を行う場合は、
foozy@708: 以下のようにパス要素をダブルスラッシュで始めます。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   ssh://server//absolute/path
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: \subsection{Finding an ssh client for your system}
foozy@708: 
foozy@708: 殆ど全ての Unix ライクなシステムには
foozy@708: OpenSSH が事前導入されています。
foozy@708: Unix ライクなシステムを使用している場合、
foozy@708: \Verb|which ssh| と入力することで
foozy@708: \command{ssh} コマンド（通常は \dirname{/usr/bin} にインストールされています）
foozy@708: のインストールの有無を確認することができます。
foozy@708: 予想に反してインストールされていなかった場合には、
foozy@708: システム添付のドキュメントを参照してインストール方法を調べてください。
foozy@708: 
foozy@708: Windows の場合、
foozy@708: 妥当な ssh クライアントを選択してダウンロードする必要があります。
foozy@708: 主な選択肢は２つあります。
foozy@708: 
foozy@708: \begin{itemize}
foozy@708: \item Simon Tatham 氏による PuTTY~\cite{web:putty} は、
foozy@708:   ssh クライアントコマンド一式を提供しています。
foozy@708: 
foozy@708: \item 面倒な事への耐性が高い方なら、
foozy@708:   Cygwin 上の OpenSSH を使うのも良いでしょう。
foozy@708: 
foozy@708: \end{itemize}
foozy@708: 
foozy@708: どちらの場合でも、
foozy@708: Mercurial が ssh クライアントコマンドを探し出せるように
foozy@708: \hgini\ ファイルを編集する必要があるでしょう。
foozy@708: 例えば PuTTY を使用するなら、
foozy@708: コマンド行で実行する ssh クライアントとして
foozy@708: \command{plink} を実行することになります。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   [ui]
foozy@708:   ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: \begin{note}
foozy@708:   \command{plink} へのパスが空白文字を含む場合、
foozy@708:   Mercurial は \command{plink} コマンドを正しく起動できません
foozy@708:   （ですので \dirname{C:\\Program Files} にインストールするのは、
foozy@708:   よくありません）。
foozy@708: \end{note}
foozy@708: 
foozy@708: \subsection{Generating a key pair}
foozy@708: 
foozy@708: ssh クライアントを使用する度に、
foozy@708: 毎回パスワード入力を繰り返さなくても良い様に、
foozy@708: 鍵対（key pair）\footnote{訳注:
foozy@708: 「公開鍵」（public key）と
foozy@708: 「秘密鍵」（private key）の対が生成されます。
foozy@708: }を生成することをおすすめします。
foozy@708: Unix ライクなシステム\footnote{訳注: Windows の Cygwin 環境含む}では、
foozy@708: \command{ssh-keygen} コマンドで鍵対を生成します。
foozy@708: Windows 上で PuTTY を使用している場合は、
foozy@708: \command{puttygen} コマンドで鍵対を生成します。
foozy@708: 
foozy@708: 鍵対を生成する場合、
foozy@708: パスフレーズで鍵を守るようにするのが、
foozy@708: 一般には\emph{非常に}賢明とされています
foozy@708: （ssh プロトコルによる安全なネットワークを、
foozy@708: 自動化された処理において使用する場合を除く）。
foozy@708: 
foozy@708: しかし、単に鍵対を生成しただけでは不十分です。
foozy@708: ネットワーク経由でログインするサーバ側アカウントにおいて、
foozy@708: 承認鍵一覧に公開鍵を追加登録する必要があります。
foozy@708: OpenSSH が導入されているサーバでの公開鍵の追加は、
foozy@708: 当該アカウントの \sdirname{.ssh} ディレクトリ配下の
foozy@708: \sfilename{authorized\_keys} 
foozy@708: ファイルに公開鍵の内容を追加することで行われます。
foozy@708: 
foozy@708: Unix ライク名システムでは、
foozy@708: 公開鍵は通常 \filename{.pub} 拡張子を持っています。
foozy@708: Windows 上で \command{puttygen} を使用する場合は、
foozy@708: 任意のファイル名で保存可能ですし、
foozy@708: 公開鍵の内容が表示されているウィンドウから
foozy@708: \sfilename{authorized\_keys} へ直接貼り付け（paste）ることも可能です
foozy@708: 
foozy@708: \subsection{Using an authentication agent}
foozy@708: 
foozy@708: 認証エージェントは、
foozy@708: パスフレーズをメモリ上に格納するデーモンプロセスです
foozy@708: （そのため、ログアウト後に再度ログインした場合、
foozy@708: パスフレーズは失われます）。
foozy@708: 認証エージェントの稼動を検知すると、
foozy@708: ssh クライアントは認証エージェントにパスフレーズの問い合わせを行います。
foozy@708: 認証エージェントが稼動していないか、
foozy@708: あるいは必要なパスフレーズを記憶していない場合は、
foozy@708: Mercurial によるサーバ連携（例: \hgcmd{push} や \hgcmd{pull}）の都度、
foozy@708: パスフレーズの入力が必要です。
foozy@708: 
foozy@708: 認証エージェントによるパスフレーズ保存の欠点は、
foozy@708: 入念に準備した攻撃者にとっては、
foozy@708: たとえ定期的に再起動しているシステムであっても XXXXXX power-cycled XXXX
foozy@708: パスフレーズの平分を復元可能である点です。
foozy@708: この問題が許容可能なものか否かは、各自で判断する必要があります。
foozy@708: 認証エージェントを使用することで、
foozy@708: 繰り返しパスフレーズを入力する手間を大幅に低減することができます。
foozy@708: 
foozy@708: Unix ライク名システムでは、
foozy@708: 認証エージェントは \command{ssh-agent} という名前で、
foozy@708: \command{ssh-add} 
foozy@708: コマンドを使ってエージェントの記憶領域にパスフレーズを保存します。
foozy@708: Windows 上で PuTTY を使用する場合は、
foozy@708: \command{pageant} コマンドが認証エージェントして振舞います。
foozy@708: システムトレイに追加されたアイコンをクリックすることで、
foozy@708: 格納されたパスフレーズの管理を行うことができます。
foozy@708: 
foozy@708: \subsection{Configuring the server side properly}
foozy@708: 
foozy@708: 初心者にとって ssh の設定は面倒なので、
foozy@708: 問題が発生する状況も多岐に渡ります。
foozy@708: Add Mercurial on top, and
foozy@708: there's plenty more scope for head-scratching.  XXXXX
foozy@708: 問題発生の可能性は、
foozy@708: クライアント側ではなくサーバ側の方が高いです。
foozy@708: ありがたいことに、
foozy@708: 一旦正しく動作する設定ができてしまえば、
foozy@708: 通常は無期限に正しく動作し続けます。
foozy@708: 
foozy@708: Mercurial で ssh サーバと通信をしてみる前に、
foozy@708: 通常の \command{ssh} ないし 
foozy@708: \command{putty} コマンドによるサーバとの通信を確認するのが無難です。
foozy@708: 直接コマンドを使用した際に問題が発生したならば、
foozy@708: Mercurial が機能しないことは確実です。
foozy@708: 更に悪いことに、
foozy@708: Mercurial を介しての ssh サーバとの連携は、
foozy@708: 根本的な原因が隠れてしまいます。
foozy@708: ssh に関連する Mercurial の問題を解決する場合は、
foozy@708: Mercurial の不具合を疑う\emph{前に}、
foozy@708: ssh クライアントコマンドの直接実行が機能することを確認してください。
foozy@708: 
foozy@708: サーバ側で最初に確認すべき事は、
foozy@708: あるマシンからサーバマシンへの実際のログインの可否です。
foozy@708: \command{ssh} ないし \command{putty} でログインできない場合、
foozy@708: 表示されるエラーメッセージから問題特定のヒントが得られるかもしれません。
foozy@708: よくある問題には以下のようなものがあります。
foozy@708: 
foozy@708: \begin{itemize}
foozy@708: \item ``connection refused'' が表示される場合は、
foozy@708:   ssh サーバプロセスが起動されていないか、
foozy@708:   ファイヤーウォール設定によりネットワーク接続できないことが原因です。
foozy@708: 
foozy@708: \item ``no route to host'' が表示される場合は、
foozy@708:   接続先のサーバアドレスが間違っているか、
foozy@708:   ファイヤーウォールによって接続が厳重に禁止されていることが原因です。
foozy@708: 
foozy@708: \item ``permission denied'' が表示される場合は、
foozy@708:   サーバ接続の際のユーザ名、パスフレーズ、
foozy@708:   ないしサーバ側ユーザのパスワードの入力を間違えていることが原因です。
foozy@708: 
foozy@708: \end{itemize}
foozy@708: 
foozy@708: これまでの話をまとめると、
foozy@708: サーバマシン上の ssh サーバプロセスとの通信に問題がある場合、
foozy@708: まずはサーバプロセスの稼動状況を確認してください。
foozy@708: 多くのシステムでは、
foozy@708: ssh 自体はインストールされていますが、
foozy@708: 初期状態では無効化されている場合があります。
foozy@708: この確認が済んだなら、
foozy@708: 次に確認するのは、
foozy@708: ssh サーバプロセスが外部からの接続を受け付けるポート（通常は 22 番）
foozy@708: に対する外部からの接続を、
foozy@708: サーバのファイヤーウォール設定が許可しているか否かです。
foozy@708: これら２つの確認を済ませるまでは、
foozy@708: 突拍子もない設定ミスの可能性に関して心配する必要はありません。
foozy@708: 
foozy@708: 秘密鍵用パスフレーズの保持のために、
foozy@708: クライアント側で認証エージェントを使用している場合は、
foozy@708: パスフレーズやパスワードの問い合わせを受ける事無く、
foozy@708: サーバにログインできていなければなりません。
foozy@708: パスフレーズを問い合わせるプロンプトが表示される場合、
foozy@708: 問題の可能性のあるものが幾つかあります。
foozy@708: 
foozy@708: \begin{itemize}
foozy@708: \item \command{ssh-add} ないし \command{pageant} 
foozy@708:   によるパスフレーズの格納を忘れているのかもしれません。
foozy@708: 
foozy@708: \item 想定しているものとは別な鍵のパスフレーズを格納しているのかもしれません。
foozy@708: 
foozy@708: \end{itemize}
foozy@708: 
foozy@708: サーバ側ユーザのパスワードの問い合わせがあった場合、
foozy@708: 別な問題の可能性を検討する必要があります。
foozy@708: 
foozy@708: \begin{itemize}
foozy@708: \item サーバ側ユーザの、ホームディレクトリないし
foozy@708:   \sdirname{.ssh} ディレクトリの権限設定が、
foozy@708:   過度に緩く設定されているのかもしれません。
foozy@708:   ssh サーバプロセスはその場合、
foozy@708:   \sfilename{authorized\_keys}
foozy@708:   ファイルの信頼性が低いものとして読み込みを行いません。
foozy@708:   例えば、
foozy@708:   ホームディレクトリないし \sdirname{.ssh} ディレクトリが、
foozy@708:   グループに対する書き込み権限を設定されている場合、
foozy@708:   パスワード問い合わせが行われる、といった症状が見られます。
foozy@708: 
foozy@708: \item \sfilename{authorized\_keys} 
foozy@708:   ファイルそのものに問題がある可能性もあります。
foozy@708:   このファイルへの書き込み権限が所有者以外にも設定されている場合、
foozy@708:   ssh サーバプロセスはファイルの信頼性が低いものとして読み込みを行いません。
foozy@708: 
foozy@708: \end{itemize}
foozy@708: 
foozy@708: 以下のコマンド実行に対して、
foozy@708: （サーバ側の）現在時刻を表示する１行だけが出力される、
foozy@708: という状態が理想的です。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   ssh myserver date
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: 上記のような非対話的なコマンド実行の場合にも、
foozy@708: バナー表示やそれに類する表示が行われるような設定が、
foozy@708: 連携先サーバ側で行われている場合には、
foozy@708: この先の手順に進む前に、
foozy@708: 対話的な実行\footnote{訳注: 「ssh によるログイン時」の意}の時にのみ、
foozy@708: これらが表示されるように設定変更してください。
foozy@708: これを怠ると、
foozy@708: バナー等の表示が Mercurial の出力を混乱させてしまいます。
foozy@708: 更に問題なことに、
foozy@708: バナー等の表示は Mercurial コマンドの遠隔実行における潜在的な問題と成り得ます。
foozy@708: 非対話的な \command{ssh} 連携において、
foozy@708: Mercurial は極力バナー等の表示の検知ならびに無視に努めますが、
foozy@708: 必ずしも全てが無視できるわけではありません
foozy@708: （サーバ側でログイン時実行スクリプトをカスタマイズする場合、
foozy@708: \Verb|tty -s| コマンドの戻り値を判定することで、
foozy@708: 当該スクリプトが現在対話シェルで実行されているか否かを判定することができます）
foozy@708: \footnote{訳注: ログインスクリプトでの出力以外でも、
foozy@708: フック実行時に標準出力に対して何らかの表示があった場合、
foozy@708: Mercurial は「連携における想定外のデータ授受」とみなすため、
foozy@708: 注意が必要です。}。
foozy@708: 
foozy@708: 素の ssh によるサーバ連携が機能することを確認したならば、
foozy@708: 次に確認するのは、
foozy@708: サーバ側での Mercurial 実行の可否です。
foozy@708: 以下のコマンド実行が正しく機能することを確認してください。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   ssh myserver hg version
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: 通常の \hgcmd{version} 出力ではなくエラーメッセージが表示される場合、
foozy@708: 大概は \dirname{/usr/bin} に
foozy@708: Mercurial がインストールされていないことが原因です。
foozy@708: その場合でも、
foozy@708: 必ずしも \dirname{/usr/bin} にインストールする必要はありません。
foozy@708: しかし、考え得る以下の幾つかの原因に関して確認が必要です。
foozy@708: 
foozy@708: \begin{itemize}
foozy@708: \item Mercurial は本当にサーバにインストールされていますか？
foozy@708:   変な質問と思われるかもしれませんが、これは非常に重要な確認事項です。
foozy@708: 
foozy@708: \item シェルのコマンドサーチパス（通常は \envar{PATH} 環境変数で設定）
foozy@708:   の設定が単に不適切なのかもしれません。
foozy@708: 
foozy@708: \item ひょっとしたら、\envar{PATH} 環境変数が 
foozy@708:   \command{hg} 
foozy@708:   コマンドの格納場所を指すように設定されるのは対話的なログイン時にのみ、
foozy@708:   という可能性もあります。
foozy@708:   \envar{PATH} 環境変数の設定を不適当な起動スクリプトで行っている場合に、
foozy@708:   このような現象が発生します。
foozy@708:   各自の使用しているシェルのドキュメントを確認してみましょう\footnote{訳注:
foozy@708:   例えば bash の場合、対話的ログインか否かで
foozy@708:   \sfilename{.bashrc}、
foozy@708:   \sfilename{.bash\_profile}、
foozy@708:   \sfilename{.profile} および
foozy@708:   \sfilename{.login} といった各ファイルの読み込みの有無が変化します。
foozy@708:   また、ディストリビューションによっては、
foozy@708:   非対話的な実行の際には、
foozy@708:   \dirname{/etc/bashrc} による
foozy@708:   \dirname{/etc/profile.d} 
foozy@708:   配下の設定ファイル読み込みが行われない場合があります
foozy@708:   （2.6.x 系カーネルベースのものは読み込まない方針の模様）ので、
foozy@708:   \envar{PYTHONPATH} の件も含めて、
foozy@708:   システムワイドな設定を行う方は注意が必要です。
foozy@708:   \Verb|ssh myserver env| 
foozy@708:   実行で出力される環境変数一覧を確認してみましょう。
foozy@708:   }。
foozy@708: 
foozy@708: \item \envar{PYTHONPATH} 環境変数による
foozy@708:   Mercurial の Python 
foozy@708:   モジュール格納ディレクトリの参照が必要であるケースもあります。
foozy@708:   不適切な設定だったり、対話的ログイン時にのみ設定されている可能性があります。
foozy@708: 
foozy@708: \end{itemize}
foozy@708: 
foozy@708: ssh 経由での \hgcmd{version} コマンド実行が成功したなら準備は完了です。
foozy@708: サーバ・クライアントは共に問題解決済みとなりました。
foozy@708: サーバ上で公開されている リポジトリに、
foozy@708: 当該ユーザ名による Mercurial でのアクセスが可能になっている筈です。
foozy@708: ここまでの確認をクリアした上で、
foozy@708: Mercurial と ssh の連携において問題が発生した場合、
foozy@708: 問題発生の状況をより明確にするために、
foozy@708: \hggopt{--debug} オプションを付けての実行を試してみてください。
foozy@708: 
foozy@708: \subsection{Using compression with ssh}
foozy@708: 
foozy@708: ssh プロトコルを使用する場合、
foozy@708: ssh プロトコル自身が通信時にデータ圧縮を行うため、
foozy@708: Mercurial は圧縮を行いません。
foozy@708: しかし、ssh クライアントの（通常の）基底動作では、
foozy@708: 圧縮を\emph{行いません}。
foozy@708: 
foozy@708: 高速な LAN の場合を除けば（無線ネットワークであっても）、
foozy@708: 通信時の圧縮は Mercurial 
foozy@708: のネットワーク経由の処理を顕著に高速化します。
foozy@708: 例えば WAN 経由での連携の場合、
foozy@708: かなり大きなリポジトリの複製に要する時間が 51 分から 17 分に低減した、
foozy@708: との性能計測報告もあります。
foozy@708: 
foozy@708: \command{ssh} と \command{plink} の両方とも、
foozy@708: 通信時圧縮を有効化する
foozy@708: \cmdopt{ssh}{-C} オプションを受け付けます。
foozy@708: \hgrc\ ファイルを以下のように編集することで、
foozy@708: ssh プロトコル利用の際に常に圧縮を行うように Mercurial に対して指定できます。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   [ui]
foozy@708:   ssh = ssh -C
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: \command{ssh} を使用している場合は、
foozy@708: 連携先サーバとの通信の際には常に圧縮を行うように設定することもできます。
foozy@708: この設定を行うには、
foozy@708: ホームディレクトリ配下の
foozy@708: \sfilename{.ssh/config} ファイル
foozy@708: （無い場合は新規に作成します）に以下のように記述します。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   Host hg
foozy@708:     Compression yes
foozy@708:     HostName hg.example.com
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: 上記の記述は、
foozy@708: \texttt{hg} という別名（alias）を作成します。
foozy@708: \command{ssh} 実行の際のコマンド行記述や、
foozy@708: Mercurial の \texttt{ssh} プロトコルにおける URL として、
foozy@708: \texttt{hg} を（ホスト名として）使用した場合、
foozy@708: \command{ssh} は通信時圧縮を行いつつ \texttt{hg.example.com} に接続します。
foozy@708: この設定により、
foozy@708: 入力の便利な省略名と、圧縮指定の両方を手にすることができます。
foozy@708: 
foozy@708: \section{Serving over HTTP using CGI}
foozy@708: \label{sec:collab:cgi}
foozy@708: 
foozy@708: 意気込み次第では、
foozy@708: Mercurial の CGI インタフェースの設定は、
foozy@708: 数分のものを数時間にしてしまう可能性があります。
foozy@708: 
foozy@708: 最も単純な例から初めて、
foozy@708: より複雑な設定へと向けて進めてゆきましょう。
foozy@708: 最も基本的なケースですら、
foozy@708: ウェブサーバの設定ファウルの読み書きを行う必要が出てくることでしょう。
foozy@708: 
foozy@708: \begin{note}
foozy@708:   ウェブサーバの設定は複雑で、扱いにくく、且つシステム依存性の高い作業です。
foozy@708:   そのため本書では、
foozy@708:   発生するであろう問題のケースを全て網羅するような手順を示すことができません。
foozy@708:   以降の記述は、慎重さと各自の判断をもって読み進めるようにしてください。
foozy@708:   沢山間違えたり、サーバのエラーログ解析に時間を費やす覚悟が必要でしょう。
foozy@708: \end{note}
foozy@708: 
foozy@708: \subsection{Web server configuration checklist}
foozy@708: 
foozy@708: 読み進める前に、
foozy@708: システムの設定状況に関する幾つかの確認を行いましょう。
foozy@708: 
foozy@708: \begin{enumerate}
foozy@708: \item ウェブサーバはインストールされていますか？
foozy@708:   Mac OS X は Apache がインストールされた状態で出荷されますが、
foozy@708:   多くのシステムではウェブサーバはインストールされていません。
foozy@708: 
foozy@708: \item ウェブサーバがインストールされている場合、
foozy@708:   それは実際に稼動していますか？
foozy@708:   ウェブサーバがインストールされていた場合でも、
foozy@708:   多くのシステムの基底状態は、ウェブサーバが無効化されています。
foozy@708: 
foozy@708: \item CGI を稼動させようとしているディレクトリは、
foozy@708:   ウェブサーバの設定で CGI の実行が許可されていますか？
foozy@708:   多くのウェブサーバの基底状態は、
foozy@708:   CGI プログラムの実行機能が明示的に無効化されています。
foozy@708: 
foozy@708: \end{enumerate}
foozy@708: 
foozy@708: ウェブサーバがインストールされていない場合や、
foozy@708: Apache ウェブサーバの設定経験があまり無い場合には、
foozy@708: Apache ウェブサーバの代わりに
foozy@708: \texttt{lighttpd} ウェブサーバの利用をお薦めします。
foozy@708: Apache ウェブサーバの設定は、
foozy@708: 凝っていて且つわかりにくいという評判に見合うものがあります。
foozy@708: \texttt{lighttpd} は Apache ウェブサーバ程の機能は無いものの、
foozy@708: 足りない機能の殆どが Mercurial リポジトリの運用には関係ないものです。
foozy@708: それに加えて、
foozy@708: 明らかに \texttt{lighttpd} は
foozy@708: Apache ウェブサーバよりも簡単に利用が開始できます。
foozy@708: 
foozy@708: \subsection{Basic CGI configuration}
foozy@708: 
foozy@708: Unix 的なシステムを利用している場合、
foozy@708: ウェブページとして公開するための
foozy@708: \dirname{public\_html} のようなディレクトリを、
foozy@708: ホームディレクトリ配下に持つのが共通認識となっています。
foozy@708: このディレクトリ直下に置いた
foozy@708: \filename{foo} という名前のファイルは、
foozy@708: \texttt{http://www.example.com/\~username/foo} という
foozy@708: URL で参照可能になります。
foozy@708: 
foozy@708: 設定を始めるに当たって、
foozy@708: Mercurial のインストール先に格納されている
foozy@708: \sfilename{hgweb.cgi} スクリプトの所在を確認してください。
foozy@708: システム上の所在がすぐにはわからなかった場合は、
foozy@708: Mercurial のマスターリポジトリから
foozy@708: \url{http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi}
foozy@708: を直接ダウンロードしてください。
foozy@708: 
foozy@708: 上記スクリプトを
foozy@708: \dirname{public\_html} 配下に配置し、
foozy@708: 実行可能となるように権限設定を行います。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   cp .../hgweb.cgi ~/public_html
foozy@708:   chmod 755 ~/public_html/hgweb.cgi
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: \command{chmod} コマンドへの \texttt{755} 引数指定は、
foozy@708: スクリプトに実行可能権限を付与する以上の付加的な指定を意味します。
foozy@708: この設定により、スクリプトが誰からも実行可能になると同時に、
foozy@708: ``group'' および ``other'' による書き込み権限が\emph{剥奪}されます。
foozy@708: これらの書き込み権限を有効なままにした場合、
foozy@708: Apache の \texttt{suexec} サブシステムは、
foozy@708: おそらくスクリプトの実行を拒否するでしょう。
foozy@708: 実のところ \texttt{suexec} は、
foozy@708: スクリプトが配置されている\emph{ディレクトリ}に対する
foozy@708: ``group'' および ``other'' による書き込み権限が剥奪されていることも要求します。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   chmod 755 ~/public_html
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: \subsubsection{What could \emph{possibly} go wrong?}
foozy@708: \label{sec:collab:wtf}
foozy@708: 
foozy@708: CGI を配置したならば、
foozy@708: ウェブブラウザを起動して
foozy@708: \url{http://myhostname/~myuser/hgweb.cgi} に相当する
foozy@708: URL にアクセスしてみましょう。
foozy@708: 但し、ちょっとした失敗には\emph{身構えておいてください}。
foozy@708: 所望の URL へのアクセスが失敗する公算は非常に高く、
foozy@708: その理由は多岐に渡ります。
foozy@708: 実際のところ、
foozy@708: 以下の起こり得るエラー要因の全てで躓く可能性がありますから、
foozy@708: この先は注意深く読み進めてください。
foozy@708: 以下で述べる問題は、
foozy@708: まっさらな状態からインストールした Apache を使い、
foozy@708: この実例を行うために新たに生成したユーザアカウントで、
foozy@708: Fedora~7 上で作業を実施した際に、
foozy@708: 筆者が実際に直面した全ての問題です。
foozy@708: 
foozy@708: 使用しているウェブサーバは、
foozy@708: ユーザ毎のディレクトリを無効化しているかもしれません。
foozy@708: Apache を使用している場合は、
foozy@708: 設定ファイル中に \texttt{UserDir} 指定の有無を確認してください。
foozy@708: この指定が無い場合、ユーザ毎ディレクトリは無効になります。
foozy@708: 指定が有っても\texttt{無効化されている}場合も、
foozy@708: ユーザ毎ディレクトリは無効になります。
foozy@708: 有効な \texttt{UserDir} 指定がある場合、
foozy@708: \texttt{UserDir} 指定で記述されている文字列
foozy@708: （例えば \dirname{public\_html}）が、
foozy@708: ホームディレクトリ直下で Apache が参照するサブディレクトリ名になります。
foozy@708: 
foozy@708: ファイルのアクセス権限が厳しすぎる可能性もあります。
foozy@708: ウェブサーバは、
foozy@708: 対象となるユーザのホームディレクトリ、
foozy@708: および \dirname{public\_html} 
foozy@708: 配下のファイル・ディレクトリの読み込みができなければなりません。
foozy@708: 適切な権限設定を行うための簡単な手順を以下に示します。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   chmod 755 ~
foozy@708:   find ~/public_html -type d -print0 | xargs -0r chmod 755
foozy@708:   find ~/public_html -type f -print0 | xargs -0r chmod 644
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: 権限設定に関する他の要因の可能性がある場合は、
foozy@708: ブラウザでの所望の URL アクセス時に、
foozy@708: 完全に空の画面が表示されることでしょう。
foozy@708: この場合は、おそらくアクセス権限が\emph{緩すぎる}のでしょう。
foozy@708: 例えば Apache の \texttt{suexec} サブシステムは、
foozy@708: group ないし other に書き込み権限が付与されたスクリプトは実行しません。
foozy@708: 
foozy@708: 使用しているウェブサーバが、
foozy@708: ユーザ毎ディレクトリ配下の CGI プログラムの実行を、
foozy@708: 禁止するように設定されている可能性も有ります。
foozy@708: 筆者の Fedora~7 システムにおける Apache の、
foozy@708: 初期状態のユーザ毎設定を以下に示します。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   <Directory /home/*/public_html>
foozy@708:       AllowOverride FileInfo AuthConfig Limit
foozy@708:       Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
foozy@708:       <Limit GET POST OPTIONS>
foozy@708:           Order allow,deny
foozy@708:           Allow from all
foozy@708:       </Limit>
foozy@708:       <LimitExcept GET POST OPTIONS>
foozy@708:           Order deny,allow
foozy@708:           Deny from all
foozy@708:       </LimitExcept>
foozy@708:   </Directory>
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: 対象となる Apache 設定ファイル中に似たような
foozy@708: \texttt{Directory} 設定がある場合、
foozy@708: \texttt{Options} 指定に注目してください。
foozy@708: \texttt{ExecCGI} が指定されていない場合は一覧末尾にこれを追加し、
foozy@708: ウェブサーバを再起動してください。
foozy@708: 
foozy@708: Apache が CGI を実行するのではなく、
foozy@708: CGI スクリプトの内容そのものを返却してきた場合は、
foozy@708: 以下の記述を（既に記述があるならば）有効化するなり追加するなりしてください。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   AddHandler cgi-script .cgi
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: 次に問題の発生し得るケースでは、
foozy@708: Python のバックトレースが表示され、
foozy@708: \texttt{mercurial} 関連モジュールがインポート
foozy@708: （import）できない旨を伝えていることでしょう。
foozy@708: 所望の結果は得られていませんが、
foozy@708: ウェブサーバは CGI スクリプトの実行を行うようになったので、
foozy@708: 先程の状態からは前進しています！
foozy@708: インポートができない旨のエラーは、
foozy@708: システムワイドで利用可能な Mercurial ではなく、
foozy@708: おそらく個人的にインストールした Mercurial 
foozy@708: を実行している場合にのみ発生します。
foozy@708: ウェブサーバが CGI プログラムを実行する場合、
foozy@708: 各個人の対話的ログインセッションで実施されている環境変数指定が無い、
foozy@708: ということを忘れないでください。
foozy@708: このエラーが発生した場合は、
foozy@708: \envar{PYTHONPATH} 環境変数設定が適切になるように
foozy@708: \sfilename{hgweb.cgi} の記述を編集してください。
foozy@708: 
foozy@708: 最終的に、
foozy@708: \dirname{/path/to/repository} が見つからない旨を伝える
foozy@708: Python のバックトレースが\emph{確実に}表示されることでしょう。
foozy@708: \sfilename{hgweb.cgi} スクリプトを編集して、
foozy@708: 文字列 \dirname{/path/to/repository} 
foozy@708: を実際に公開したいリポジトリへの絶対パスで置き換えてください。
foozy@708: 
foozy@708: ここまで来れば、
foozy@708: ウェブブラウザでページをリロードした際に、
foozy@708: 綺麗に HTML で整形されたリポジトリ履歴の表示を見ることができる筈です。
foozy@708: お疲れ様です。
foozy@708: 
foozy@708: \subsubsection{Configuring lighttpd}
foozy@708: 
foozy@708: 徹底的に実験するために、
foozy@708: これまで Apache に関して説明したのと同様に、
foozy@708: 近年人気が高まっている \texttt{lighttpd} ウェブサーバで、
foozy@708: 同じリポジトリを公開するための設定記述に挑戦してみました。
foozy@708: Apache についてこれまで概説してきた全ての問題は既に克服済みですし、
foozy@708: その殆どはウェブサーバ実装に依存しません。
foozy@708: 結果として、
foozy@708: ファイル・ディレクトリの権限設定が妥当であることと、
foozy@708: \sfilename{hgweb.cgi} スクリプトが適切に改変済みであることは、
foozy@708: ある程度確信できます。
foozy@708: 
foozy@708: 一旦 Apache での公開に成功していれば、
foozy@708: \texttt{lighttpd} でのリポジトリ公開は簡単
foozy@708: （言い換えるなら、
foozy@708: \texttt{lighttpd} を使用する場合でも、
foozy@708: 前述の Apache に関する説明を読むべきと言えます
foozy@708: ）です。
foozy@708: 初期状態で
foozy@708: \texttt{mod\_cgi} および \texttt{mod\_userdir} が無効化されていた場合、
foozy@708: これらを有効化するために、
foozy@708: まずは、
foozy@708: 設定ファイルの \texttt{mod\_access} セクションを編集する必要があります。
foozy@708: その後、これらのモジュールを設定するために、
foozy@708: 設定ファイル末尾に数行ほど追加します。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   userdir.path = "public_html"
foozy@708:   cgi.assign = ( ".cgi" => "" )
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: この記述により、
foozy@708: \texttt{lighttpd} はユーザ毎のディレクトリおよび CGI を認識します。
foozy@708: Apache よりも前に
foozy@708: \texttt{lighttpd} の設定をしたとしたら、
foozy@708: 殆ど間違いなく、
foozy@708: Apache 
foozy@708: の設定の際に経験したのと同じシステムレベルの設定ミスを犯したことでしょう。
foozy@708: しかし
foozy@708: Apache の使用経験が１０年以上あり、
foozy@708: 且つ初めての \texttt{lighttpd} 使用ではあるものの、
foozy@708: Apache の設定よりも \texttt{lighttpd} のそれは著しく容易であると思われます。
foozy@708: 
foozy@708: \subsection{Sharing multiple repositories with one CGI script}
foozy@708: 
foozy@708: 単一のリポジトリのみしか公開できないというのは、
foozy@708: \sfilename{hgweb.cgi} スクリプトの悩ましい制約です。
foozy@708: 同じスクリプト\footnote{訳注: 厳密には、
foozy@708: 公開対象リポジトリのパスが異なるのですが、
foozy@708: 概ね「同じ」と言って良いでしょう。
foozy@708: }を異なる名前で複製する、
foozy@708: という面倒な方法よりは、
foozy@708: \sfilename{hgwebdir.cgi} スクリプトの使用がお薦めです。
foozy@708: 
foozy@708: \sfilename{hgwebdir.cgi} の設定手順は、
foozy@708: \sfilename{hgweb.cgi} よりも多少込み入っています。
foozy@708: まず始めに
foozy@708: スクリプトのコピーを入手します。
foozy@708: 手近に無い場合は
foozy@708: Mercurial のマスターリポジトリから
foozy@708: \url{http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi}
foozy@708: を直接ダウンロードしてください。
foozy@708: 
foozy@708: \dirname{public\_html} 配下に上記スクリプトを配置し、
foozy@708: 実行可能となるように権限設定を行います。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   cp .../hgwebdir.cgi ~/public_html
foozy@708:   chmod 755 ~/public_html ~/public_html/hgwebdir.cgi
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: 基本的な設定が済んだなら、
foozy@708: ブラウザで \url{http://myhostname/~myuser/hgwebdir.cgi}
foozy@708: にアクセスしてみましょう。
foozy@708: 空のリポジトリリストが表示される筈です。
foozy@708: 何も表示されないか、エラーメッセージが表示される場合は、
foozy@708: \ref{sec:collab:wtf}~節で説明した潜在的問題一覧を一通り確認してください。
foozy@708: 
foozy@708: \sfilename{hgwebdir.cgi} スクリプトは外部設定ファイルを必要とします。
foozy@708: 基底状態の
foozy@708: \sfilename{hgwebdir.cgi} スクリプトは、
foozy@708: 自身と同じディレクトリに格納された
foozy@708: \sfilename{hgweb.config} ファイルを読み込もうとします。
foozy@708: このファイルを生成し、
foozy@708: 誰に対しても読み出し権限を付与しなければなりません。
foozy@708: このファイルの記述形式は、
foozy@708: Windows における ``ini'' ファイルのそれと同じで、
foozy@708: Python の
foozy@708: \texttt{ConfigParser}~\cite{web:configparser} 
foozy@708: により解析可能な形式です。
foozy@708: 
foozy@708: 最も簡単に \sfilename{hgwebdir.cgi} を設定するには、
foozy@708: \texttt{collections} という名前のセクションを設定してください。
foozy@708: このセクションを記述することで、
foozy@708: 名付けたディレクトリ配下の\emph{全ての}リポジトリを自動的に公開します。
foozy@708: このセクションの記述は以下のようになります。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   [collections]
foozy@708:   /my/root = /my/root
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: Mercurial はこの記述を解釈するに当たり、
foozy@708: ``\texttt{=}'' 
foozy@708: 記号の\emph{右辺}に記述されたディレクトリ階層下でリポジトリを探し、
foozy@708: ``\texttt{=}'' 記号の\emph{左辺}のテキストに合致する部分を、
foozy@708: ウェブインタフェースでの一覧表示で実際に公開される名前から除外します。
foozy@708: 除外処理の後に残ったパス要素は、``仮想パス''と呼ばれます。
foozy@708: 
foozy@708: 例として
foozy@708: \dirname{/my/root/this/repo} にリポジトリがあるとした場合、
foozy@708: CGI スクリプトは冒頭の
foozy@708: \dirname{/my/root} 部分を名前から除外し、
foozy@708: 仮想パスとして \dirname{this/repo} を持つリポジトリとして公開します。
foozy@708: CGI スクリプトの基底 URL を
foozy@708: \url{http://myhostname/~myuser/hgwebdir.cgi} とすると、
foozy@708: このリポジトリの完全な URL は、
foozy@708: \url{http://myhostname/~myuser/hgwebdir.cgi/this/repo} となります。
foozy@708: 
foozy@708: この設定記述例での左辺を \dirname{/my/root} から
foozy@708: \dirname{/my} に変更した場合、
foozy@708: \sfilename{hgwebdir.cgi} はリポジトリ名から
foozy@708: \dirname{/my} のみをｚｙ歩外するので、
foozy@708: 仮想パスは \dirname{this/repo} ではなく
foozy@708: \dirname{root/this/repo} となります。
foozy@708: 
foozy@708: \sfilename{hgwebdir.cgi} は、
foozy@708: 設定ファイル中の \texttt{collections}
foozy@708: セクションで列挙された個々のディレクトリに対して、
foozy@708: 再帰的にリポジトリを探しますが、
foozy@708: 見つかったリポジトリから更に下への再帰的探索は\texttt{行いません}。
foozy@708: 
foozy@708: \texttt{collections} の機構は、
foozy@708: 多くのリポジトリを``fire and forget''作法で公開するのに適しています。
foozy@708: CGI や設定ファイルの記述は一度で事足ります。
foozy@708: 設定が済んだなら、
foozy@708: \sfilename{hgwebdir.cgi} 
foozy@708: に探索を指示したディレクトリ階層配下との間でリポジトリの移動を行うだけで、
foozy@708: リポジトリの公開・非公開を任意の時点で行うことができます。
foozy@708: 
foozy@708: \subsubsection{Explicitly specifying which repositories to publish}
foozy@708: 
foozy@708: \sfilename{hgwebdir.cgi} スクリプトは
foozy@708: \texttt{collections} による公開の仕組みに加えて、
foozy@708: 特定の一覧指定によるリポジトリ公開をすることもできます。
foozy@708: この方法での公開をするには、
foozy@708: 以下のような形式の内容を持つ
foozy@708: \texttt{paths} セクションを記述する必要があります。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   [paths]
foozy@708:   repo1 = /my/path/to/some/repo
foozy@708:   repo2 = /some/path/to/another
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: 上記の例では、個々の定義の左辺が仮想パス（URL 中に現れるパス要素）、
foozy@708: 右辺がリポジトリへのパスとなります。
foozy@708: 仮想パスの指定と、
foozy@708: ファイルシステム上のリポジトリ位置には、
foozy@708: 何の関連性も無い点に注意してください。
foozy@708: 
foozy@708: 単一の設定ファイル中で
foozy@708: \texttt{collections} と
foozy@708: \texttt{paths} の両方を同時に使用することも可能です。
foozy@708: 
foozy@708: \begin{note}
foozy@708:   同一の仮想パスに複数のリポジトリが関連付けられている場合、
foozy@708:   \sfilename{hgwebdir.cgi} はエラーを通知しません。
foozy@708:   その代わりに、
foozy@708:   \sfilename{hgwebdir.cgi} の振る舞いは予想できないものとなります。
foozy@708: \end{note}
foozy@708: 
foozy@708: \subsection{Downloading source archives}
foozy@708: 
foozy@708: Mercurial のウェブインタフェース経由で、
foozy@708: 任意のリビジョンのアーカイブをダウンロードすることが可能です。
foozy@708: このアーカイブには、
foozy@708: 当該リビジョンにおける作業領域ディレクトリのスナップショットが格納されますが、
foozy@708: リポジトリデータ部分は含まれません。
foozy@708: 
foozy@708: この機能は既定状態では無効化されています。
foozy@708: この機能を有効化するには、
foozy@708: \rcitem{web}{allow\_archive} 項目を
foozy@708: \hgrc ファイルの \rcsection{web} セクションに追加してください\footnote{訳注:
foozy@708: このことから、
foozy@708: アーカイブダウンロードの有効化・無効化設定が、
foozy@708: \sfilename{hgwebdir.cgi} 単位ではなく、
foozy@708: リポジトリ単位での設定であることがわかります。}。
foozy@708: 
foozy@708: \subsection{Web configuration options}
foozy@708: 
foozy@708: Mercurial のウェブインタフェース
foozy@708: （\hgcmd{serve} コマンドおよび
foozy@708: \sfilename{hgweb.cgi} ないし \sfilename{hgwebdir.cgi} スクリプト）
foozy@708: には変更可能な設定項目が多数あります。
foozy@708: これらの設定項目は
foozy@708: \rcsection{web} セクションに属しています。
foozy@708: 
foozy@708: \begin{description}
foozy@708: 
foozy@708: \item[\rcitem{web}{allow\_archive}] 
foozy@708:   Mercurial のアーカイブダウンロード機能を有効化するか否かを指定。
foozy@708:   この機能を有効化した場合ウェブインタフェースの利用者は、
foozy@708:   リポジトリ中の参照可能な任意のリビジョンのアーカイブをダウンロードできます。
foozy@708:   この機能を有効化するには、
foozy@708:   以下に列挙されるキーワードの並びを
foozy@708:   \rcitem{web}{allow\_archive} 項目に指定する必要があります。
foozy@708: 
foozy@708:   \begin{description}
foozy@708:   \item[\texttt{bz2}] \texttt{bzip2} 圧縮された \command{tar} アーカイブ形式。
foozy@708:     この形式は最も高い圧縮率を得られますが、
foozy@708:     サーバ側の CPU を最も酷使します。
foozy@708: 
foozy@708:   \item[\texttt{gz}] \texttt{gzip} 圧縮された \command{tar} アーカイブ形式。
foozy@708: 
foozy@708:   \item[\texttt{zip}] LZW 圧縮された \command{zip} アーカイブ形式。
foozy@708:     この形式は圧縮率が最も劣りますが、Windows 環境では広く使用されています。
foozy@708: 
foozy@708:   \end{description}
foozy@708: 
foozy@708:   値を指定しなかったり、
foozy@708:   \rcitem{web}{allow\_archive} 項目そのものを指定しなかった場合、
foozy@708:   アーカイブダウンロード機能は無効化されます。
foozy@708:   利用可能な全てのアーカイブ形式を有効化する記述例を以下に示します。
foozy@708: 
foozy@708:   \begin{codesample4}
foozy@708:     [web]
foozy@708:     allow_archive = bz2 gz zip
foozy@708:   \end{codesample4}
foozy@708: 
foozy@708: \item[\rcitem{web}{allowpull}] 
foozy@708:   ウェブインタフェース経由での HTTP 越しの
foozy@708:   \hgcmd{pull} および \hgcmd{clone} を許可するか否かを指定する真偽値。
foozy@708:   \texttt{no} ないし \texttt{false} が指定された場合、
foozy@708:   ウェブインタフェースの``人間向け''部分のみが有効化されます。
foozy@708: 
foozy@708: \item[\rcitem{web}{contact}] 
foozy@708:   リポジトリの管理を行う人物・組織を特定するための任意の
foozy@708:   （但し極力簡潔な）文字列。
foozy@708:   通常この値は、管理者ないしメーリングリストの名前と電子メールアドレスです。
foozy@708:   多くの場合、
foozy@708:   この情報はリポジトリ毎の \sfilename{.hg/hgrc} ファイルに記述しますが、
foozy@708:   全てのリポジトリが同一の保守担当により保守されている場合、
foozy@708:   大域的な \hgrc ファイルに記述するのも良いでしょう。
foozy@708: 
foozy@708: \item[\rcitem{web}{maxchanges}] 
foozy@708:   ページ毎に表示されるチェンジセットの最大数（既定値）を表す数値。
foozy@708: 
foozy@708: \item[\rcitem{web}{maxfiles}] 
foozy@708:   ページ毎に表示される変更ファイルの最大数（既定値）を表す数値。
foozy@708: 
foozy@708: \item[\rcitem{web}{stripes}] 
foozy@708:   テーブル表示における可読性向上のために、
foozy@708:   各行の色を互い違いに``縞模様''とする際に、
foozy@708:   何行毎に色を変更するかの数値。
foozy@708: 
foozy@708: \item[\rcitem{web}{style}] 
foozy@708:   Mercurial がウェブインタフェースを表示する際に使用するテンプレート。
foozy@708:   Mercurial は \texttt{default} および
foozy@708:   \texttt{gitweb} の２つのウェブインタフェース用テンプレートを同梱しています
foozy@708:   （後者の方が見栄えが良いです）。
foozy@708:   自前でカスタマイズしたテンプレートを指定することもできます。
foozy@708:   詳細は\ref{chap:template}~節を参照してください。
foozy@708:   \texttt{gitweb} スタイルの利用方法を以下に示します。
foozy@708: 
foozy@708:   \begin{codesample4}
foozy@708:     [web]
foozy@708:     style = gitweb
foozy@708:   \end{codesample4}
foozy@708: 
foozy@708: \item[\rcitem{web}{templates}] 
foozy@708:   テンプレートファイルの参照先ディレクトリを示すパス。
foozy@708:   Mercurial の既定値では、インストール先ディレクトリを参照します。
foozy@708: 
foozy@708: \end{description}
foozy@708: 
foozy@708: \sfilename{hgwebdir.cgi} を使用する場合、
foozy@708: 幾つかの設定項目に関しては利便性上、
foozy@708: \hgrc ファイルに記述する代わりに、
foozy@708: \sfilename{hgweb.config} ファイルの
foozy@708: \rcsection{web} セクションに記述することができます。
foozy@708: 記述可能な設定項目は、
foozy@708: \rcitem{web}{motd} および \rcitem{web}{style} です。
foozy@708: 
foozy@708: \subsubsection{Options specific to an individual repository}
foozy@708: 
foozy@708: ユーザ毎ないし大域的な \hgrc ファイルではなく、
foozy@708: リポジトリ毎の \sfilename{.hg/hgrc} で記述すべき
foozy@708: \rcsection{web} セクションの設定項目が幾つかあります。
foozy@708: 
foozy@708: \begin{description}
foozy@708: \item[\rcitem{web}{description}] 
foozy@708:   リポジトリの内容ないし目的を記述した任意の
foozy@708:   （但し極力簡潔な）文字列。
foozy@708: 
foozy@708: \item[\rcitem{web}{name}] 
foozy@708:   ウェブインタフェースにおけるリポジトリ参照名を示す文字列。
foozy@708:   この値は、
foozy@708:   リポジトリのパス\footnote{訳注: 仮想パス？
foozy@708:   }の末尾要素を用いた既定名を上書きします。
foozy@708: 
foozy@708: \end{description}
foozy@708: 
foozy@708: \subsubsection{Options specific to the \hgcmd{serve} command}
foozy@708: 
foozy@708: \hgrc ファイルの
foozy@708: \rcsection{web} セクションにおける設定項目の幾つかは、
foozy@708: \hgcmd{serve} コマンド専用の項目です。
foozy@708: 
foozy@708: \begin{description}
foozy@708: 
foozy@708: \item[\rcitem{web}{accesslog}] 
foozy@708:   アクセスログを書き出すファイルのパス。
foozy@708:   \hgcmd{serve} コマンドの基底動作でのアクセスログ出力先は、
foozy@708:   ファイルではなく標準出力です。
foozy@708:   ログ要素は、
foozy@708:   多くのウェブサーバにおいて利用される標準的な``複合''（combined）
foozy@708:   ファイル形式で出力されます。
foozy@708: 
foozy@708: \item[\rcitem{web}{address}] 
foozy@708:   外部からの接続を受け付けるアドレスを指定する文字列。
foozy@708:   基底動作では、\hgcmd{serve} コマンドは全てのアドレスで接続を受け付けます。
foozy@708: 
foozy@708: \item[\rcitem{web}{errorlog}] 
foozy@708:   エラーログを書き出すファイルのパス。
foozy@708:   \hgcmd{serve} コマンドの基底動作でのエラーログ出力先は、
foozy@708:   ファイルではなく標準エラー出力です。
foozy@708: 
foozy@708: \item[\rcitem{web}{ipv6}] 
foozy@708:   IPv6 プロトコル利用の有無を指定する真偽値。
foozy@708:   基底動作では IPv6 はサポートされません。
foozy@708: 
foozy@708: \item[\rcitem{web}{port}] 
foozy@708:   \hgcmd{serve} コマンドが接続を受け付ける TCP ポートの番号を指定する数値。
foozy@708:   基底動作では、8000 番ポートが使用されます。
foozy@708: 
foozy@708: \end{description}
foozy@708: 
foozy@708: \subsubsection{Choosing the right \hgrc\ file to add \rcsection{web}
foozy@708:   items to}
foozy@708: 
foozy@708: Apache や \texttt{lighttpd} のようなウェブサーバは、
foozy@708: リポジトリ所有者とは異なるユーザ権限で稼動する可能性がある、
foozy@708: という点は重要ですので忘れないようにしてください。
foozy@708: ウェブサーバによって起動される
foozy@708: \sfilename{hgweb.cgi} のような
foozy@708: CGI スクリプトは通常、
foozy@708: ウェブサーバと同一のユーザ権限で稼動します。
foozy@708: 
foozy@708: 個人の \hgrc ファイルに
foozy@708: \rcsection{web} セクションを記述しても、
foozy@708: CGI スクリプトはその設定を読み込みません。
foozy@708: 個人の \hgrc ファイルに記述した設定は、
foozy@708: 当該ユーザ自身で \hgcmd{serve} 
foozy@708: コマンドを実行した場合にのみ効力を発揮します。
foozy@708: CGI スクリプトの挙動に所望の設定を反映するには、
foozy@708: ウェブサーバが稼動される際のユーザのホームディレクトリに
foozy@708: \hgrc ファイルを作成して所望の設定を記述するか、
foozy@708: あるいはシステムワイドな \hgrc ファイルに所望の設定を追加してください。
foozy@708: 
foozy@708: 
foozy@708: %%% Local Variables: 
foozy@708: %%% mode: latex
foozy@708: %%% TeX-master: "00book"
foozy@708: %%% End: