foozy@708: \chapter{A tour of Mercurial: the basics}
foozy@708: \label{chap:tour-basic}
foozy@708: 
foozy@708: \section{Installing Mercurial on your system}
foozy@708: \label{sec:tour:install}
foozy@708: 
foozy@708: 一般的な全ての OS 向けに、
foozy@708: ビルド済みの Mercurial バイナリ版が提供されています。
foozy@708: バイナリ版を使用することで、
foozy@708: 簡単に Mercurial をセットアップすることができます。
foozy@708: 
foozy@708: \subsection{Linux}
foozy@708: 
foozy@708: Linux ディストリビューションは、
foozy@708: それぞれ固有のパッケージ管理ツール、
foozy@708: パッケージ作成方針、ならびに開発ペースを持っていますので、
foozy@708: 全てのバイナリ版 Mercurial 
foozy@708: のインストール手順に関する包括的な説明を行うのは困難です。
foozy@708: また、
foozy@708: バイナリ版のインストールによって利用可能な Mercurial のバージョンは、
foozy@708: 当該ディストリビューションのパッケージ保守担当者が、
foozy@708: どの程度活発であるかによって異なります。
foozy@708: 
foozy@708: 簡便化のため、
foozy@708: 著名な Linux ディストリビューションにおける、
foozy@708: コマンドラインを用いた Mercurial のインストールに限定して説明します。
foozy@708: 殆どのディストリビューションでは、
foozy@708: \texttt{mercurial} という名前のパッケージを探したならば、
foozy@708: クリックひとつで Mercurial がインストールできるような、
foozy@708: グラフィカルなパッケージ管理ツールが提供されています。
foozy@708: 
foozy@708: \begin{description}
foozy@708: \item[Debian]
foozy@708:   \begin{codesample4}
foozy@708:     apt-get install mercurial
foozy@708:   \end{codesample4}
foozy@708: 
foozy@708: \item[Fedora Core]
foozy@708:   \begin{codesample4}
foozy@708:     yum install mercurial
foozy@708:   \end{codesample4}
foozy@708: 
foozy@708: \item[Gentoo]
foozy@708:   \begin{codesample4}
foozy@708:     emerge mercurial
foozy@708:   \end{codesample4}
foozy@708: 
foozy@708: \item[OpenSUSE]
foozy@708:   \begin{codesample4}
foozy@708:     yum install mercurial
foozy@708:   \end{codesample4}
foozy@708: 
foozy@708: \item[Ubuntu] Ubuntu の Mercurial パッケージは非常に古いので、
foozy@708:   使用すべきではありません。
foozy@708:   できれば、Debian パッケージをリビルドしてインストールしてください。
foozy@708:   おそらく Mercurial をソースからビルドする方が簡単でしょう。
foozy@708:   その場合の詳細は、\ref{sec:srcinstall:unixlike}~節を参照してください。
foozy@708: 
foozy@708: \end{description}
foozy@708: 
foozy@708: \subsection{Mac OS X}
foozy@708: 
foozy@708: Mac OS~X 向けの Mercurial インストーラは、
foozy@708: Lee Cantey によって
foozy@708: \url{http://mercurial.berkwood.com} で公開されています。
foozy@708: このパッケージは、Intel および Power の両 Mac で動作します。
foozy@708: このインストーラを使用する前に、
foozy@708: Universal MacPython~\cite{web:macpython} 
foozy@708: と互換性のある Python をインストールする必要があります。
foozy@708: Lee 氏のサイトにある手順を踏めば、簡単にインストールできます。
foozy@708: 
foozy@708: \subsection{Solaris}
foozy@708: 
foozy@708: 未校。XXX
foozy@708: 
foozy@708: \subsection{Windows}
foozy@708: 
foozy@708: Windows 向けの Mercurial インストーラは、
foozy@708: Lee Cantey によって
foozy@708: \url{http://mercurial.berkwood.com} で公開されています。
foozy@708: このパッケージは他のパッケージへの依存性がありませんので、
foozy@708: 単独で利用できます。
foozy@708: 
foozy@708: \begin{note}
foozy@708:   基底状態の Windows 版 Mercurial は、
foozy@708:   Windows と Unix の改行形式の自動変換は行いません。
foozy@708:   Unix 利用者と変更成果を共有したい場合は、
foozy@708:   少々追加設定を行う必要があります。
foozy@708:   詳細未校 XXX。
foozy@708: \end{note}
foozy@708: 
foozy@708: \section{Getting started}
foozy@708: 
foozy@708: Mercurial を使い始めるにあたり、
foozy@708: 実際に利用可能な Mercurial コマンドのバージョンを確認するため、
foozy@708: \hgcmd{version} コマンドを使ってみましょう。
foozy@708: 実際のバージョン情報にはそれほど重要性はありませんが、
foozy@708: 何も表示されない場合は対処が必要です。
foozy@708: 
foozy@708: \interaction{tour.version}
foozy@708: 
foozy@708: \subsection{Built-in help}
foozy@708: 
foozy@708: Mercurial は組み込みヘルプ機能を持っています。
foozy@708: この機能は、
foozy@708: コマンドの実行方法を思い出せない場合に有用です。
foozy@708: 何をして良いのか完全にわからなくなってしまった場合は、
foozy@708: 単に \hgcmd{help} を実行することで、
foozy@708: それぞれがどのような機能を持っているかの説明が付いた、
foozy@708: 簡単なコマンド一覧が表示されます。
foozy@708: 以下に示すような形式で、
foozy@708: 特定のコマンドについて \hgcmd{help} を実行した場合、
foozy@708: そのコマンドに関する詳細な情報が表示されます。
foozy@708: 
foozy@708: \interaction{tour.help}
foozy@708: 
foozy@708: 更に多くの詳細な（通常は必要としない）情報を表示するには、
foozy@708: \hgcmdargs{help}{\hggopt{-v}} を実行します。
foozy@708: \hggopt{-v} オプションは \hggopt{--verbose} の省略形で、
foozy@708: 通常よりも多くの情報を Mercurial に表示させます。
foozy@708: 
foozy@708: \section{Working with a repository}
foozy@708: 
foozy@708: Mercurial では、
foozy@708: 全てが\emph{リポジトリ}に閉じています。
foozy@708: 例えば、あるプロジェクトのために作成したリポジトリには、
foozy@708: プロジェクトに``属する''全てのファイルだけでなく、
foozy@708: ファイルに関する履歴情報も格納されています。
foozy@708: 
foozy@708: リポジトリはファイルシステム上にある只のディレクトリツリーですので、
foozy@708: Mercurial が特別扱いするということ以外には、
foozy@708: 通常のディレクトリやファイルと比較して特に変わっている点はありません。
foozy@708: コマンド行やファイルブラウザを利用して、
foozy@708: 任意の時点で改名や削除することができます。
foozy@708: 
foozy@708: \subsection{Making a local copy of a repository}
foozy@708: 
foozy@708: リポジトリの\emph{複製}は、少々特別です。
foozy@708: 通常のディレクトリ複製のコマンドでもリポジトリを複製できますが、
foozy@708: Mercurial 組み込みの複製コマンドを使用した方が良いでしょ。
foozy@708: このコマンドは、
foozy@708: 既存のリポジトリと同一の複製を生成するため、
foozy@708: \hgcmd{clone} と呼ばれています。
foozy@708: 
foozy@708: \interaction{tour.clone}
foozy@708: 
foozy@708: チュートリアル用のリポジトリからの複製に成功したなら、
foozy@708: ローカルファイルシステム上に
foozy@708: \dirname{hello} という名前のディレクトリがある筈です。
foozy@708: このディレクトリにはファイルが幾つか格納されていることでしょう。
foozy@708: This directory will contain some files.
foozy@708: 
foozy@708: \interaction{tour.ls}
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: 自身のリポジトリで自由に実験ができるわけです。
foozy@708: 
foozy@708: \subsection{What's in a repository?}
foozy@708: 
foozy@708: リポジトリ内部を仔細に見てみると、
foozy@708: \dirname{.hg} という名前のディレクトリがあることに気が付くことでしょう。
foozy@708: このディレクトリは、
foozy@708: Mercurial がリポジトリのメタデータを格納しているディレクトリです。
foozy@708: 
foozy@708: \interaction{tour.ls-a}
foozy@708: 
foozy@708: \dirname{.hg} およびその配下のディレクトリの内容は、
foozy@708: Mercurial が私的に使用するものです。
foozy@708: リポジトリにおけるそれ以外のディレクトリ・ファイルは、
foozy@708: 自由に利用して構いません。
foozy@708: 
foozy@708: 用語の定義をするにあたり、
foozy@708: \dirname{.hg} ディレクトリを``本当の''リポジトリとするなら、
foozy@708: それと共存する他のファイル・ディレクトリは
foozy@708: \emph{作業領域ディレクトリ}にあるもの、と呼ばれます。
foozy@708: 両者の区分を簡単に言うなら、
foozy@708: \emph{リポジトリ}がプロジェクトの\emph{履歴}を保持する一方で、
foozy@708: \emph{作業領域ディレクトリ}は、
foozy@708: 履歴上のとある時点におけるプロジェクトの\emph{スナップショット}を保持する、
foozy@708: と言えます。
foozy@708: 
foozy@708: \section{A tour through history}
foozy@708: 
foozy@708: 馴染みの無い新しいリポジトリに対しては、
foozy@708: まずはその履歴を参照してみようと思うことでしょう。
foozy@708: \hgcmd{log} コマンドは、履歴情報を出力します。
foozy@708: 
foozy@708: \interaction{tour.log}
foozy@708: 
foozy@708: このコマンドの基底動作では、
foozy@708: プロジェクトに加えられた個々の変更の記録に対して簡単な出力を行います。
foozy@708: Mercurial の用語では、
foozy@708: 複数のファイルに対する変更を保持し得ることから、
foozy@708: 記録されたこれらの出来事を\emph{チェンジセット}と呼称します。
foozy@708: 
foozy@708: \hgcmd{log} の出力形式における各欄は、
foozy@708: 以下のようになっています。
foozy@708: 
foozy@708: \begin{description}
foozy@708: \item[\texttt{changeset}] この欄は、10 進数、コロン（colon: \texttt{:}）
foozy@708:   および 16 進数の連続形式となっています。
foozy@708:   ２つの数値は共にチェンジセットの\emph{識別子}です。
foozy@708:   16 進数のものよりも、10 進数の方が短く、入力が容易であることから、
foozy@708:   ２つの識別氏が存在します。
foozy@708: 
foozy@708: \item[\texttt{user}] チェンジセットの作成者に関する識別情報です。
foozy@708:   この欄は自由形式ですが、殆どの場合、
foozy@708:   人名と電子メールアドレスが格納されます。
foozy@708: 
foozy@708: \item[\texttt{date}] チェンジセットが作成された日時と、そのタイムゾーンです
foozy@708:   （日時は当該タイムゾーンにおける値ですので、
foozy@708:   チェンジセットの作成者にとっての日時を表します）。
foozy@708: 
foozy@708: \item[\texttt{summary}] チェンジセット作成者が、
foozy@708:   作成の際にチェンジセットの説明として入力したメッセージの最初の行です。
foozy@708: 
foozy@708: \end{description}
foozy@708: 
foozy@708: 基底動作における \hgcmd{log} の出力は、
foozy@708: 単純な要約ですので、
foozy@708: 多くの詳細データが欠けています。
foozy@708: 
foozy@708: 図~\ref{fig:tour-basic:history} は、
foozy@708: 履歴の``動向''を把握し易くするために、
foozy@708: \dirname{hello} リポジトリにおける履歴を図示したものです。
foozy@708: 本章および以降の章において、
foozy@708: 何度かこの図に立ち返ることになることでしょう。
foozy@708: 
foozy@708: \begin{figure}[ht]
foozy@708:   \centering
foozy@708:   \grafix{tour-history}
foozy@708:   \label{fig:tour-basic:history}
foozy@708:   \caption{Graphical history of the \dirname{hello} repository}
foozy@708: \end{figure}
foozy@708: 
foozy@708: \subsection{Changesets, revisions, and talking to other people}
foozy@708: 
foozy@708: 英語が不正確さで悪名高い言語であり、
foozy@708: 計算機科学では用語の混乱はいつものことですので、
foozy@708: 構成管理の分野では、
foozy@708: 同じことを表す複数の用語や言い回しが存在します。
foozy@708: Mercurial での履歴管理について話をする場合、
foozy@708: ``チェンジセット''（changeset）という用語が時には
foozy@708: ``チェンジ''（change）や
foozy@708: （文書の場合は）``cset''などと省略されていたり、
foozy@708: チェンジセットという言い回しが、
foozy@708: ``リビジョン''（revision）ないし``rev''
foozy@708: を表すものとして使用されたりするのを目にするかもしれません。
foozy@708: 
foozy@708: ``チェンジセット''の概念をどのような\emph{用語}で表そうが問題ではありませんが、
foozy@708: ``\emph{特定の}チェンジセット''を指すための\emph{識別子}は非常に重要です。
foozy@708: \hgcmd{log} の出力における \texttt{changeset} 欄が、
foozy@708: 10 進数と 16 進数の両方の識別子を使ってチェンジセットを識別している、
foozy@708: ということを思い出してください。
foozy@708: 
foozy@708: \begin{itemize}
foozy@708: \item 10 進数の識別子（＝ リビジョン番号）が、
foozy@708:   \emph{当該リポジトリでのみ有効な値}である一方で、
foozy@708: 
foozy@708: \item 16 進数の識別子は、\emph{全ての}複製リポジトリに渡って、
foozy@708:   厳密にチェンジセットを識別可能な\emph{恒久普遍の識別子}です。
foozy@708: 
foozy@708: \end{itemize}
foozy@708: 
foozy@708: この区別は重要です。
foozy@708: 電子メールで他の人と``リビジョン~33''の話をした場合、
foozy@708: 相手のリビジョン~33は、
foozy@708: 自分の意図するそれとは高い確率で\emph{異なります}。
foozy@708: これは、
foozy@708: リビジョン番号の割り付けが、
foozy@708: 当該チェンジセットがリポジトリに認識された順序に依存しており、
foozy@708: チェンジセットの認識順序が同一であることを、
foozy@708: 異なるリポジトリの間では保障できないためです。
foozy@708: ３つのチェンジセット $a,b,c$ が、
foozy@708: とあるリポジトリでは $0,1,2$ の順序で認識される一方で、
foozy@708: 別なリポジトリでは $1,0,2$ の順序で認識される、
foozy@708: といったことは容易に起こり得ます。
foozy@708: 
foozy@708: Mercurial がリビジョン番号を使用しているのは、
foozy@708: 純粋に記述簡略化の利便性のためです。
foozy@708: 他の人とチェンジセットに関して話をする場合や、
foozy@708: 何らかの理由（例えば、障害報告における記録）
foozy@708: によってチェンジセットに関する記録を残す場合は、
foozy@708: 16 進数の識別子を使いましょう。
foozy@708: 
foozy@708: \subsection{Viewing specific revisions}
foozy@708: 
foozy@708: \hgcmd{log} の出力を単一のリビジョンのものに限定する場合、
foozy@708: \hgopt{log}{-r}（ないし \hgopt{log}{--rev}）オプションを使用します。
foozy@708: 10 進数のリビジョン番号と、
foozy@708: 16 進数のチェンジセット識別子のどちらも使用できますし、
foozy@708: 必要に応じて複数のリビジョンを指定することもできます。
foozy@708: 
foozy@708: \interaction{tour.log-r}
foozy@708: 
foozy@708: 個別に列挙すること無しに複数のリビジョンの履歴を参照したい場合は、
foozy@708: \emph{範囲記法}を使用します。
foozy@708: この記法は、
foozy@708: ``$a$ から $b$ の間の全てのリビジョン''
foozy@708: という意図を表現します。
foozy@708: 
foozy@708: \interaction{tour.log.range}
foozy@708: 
foozy@708: Mercurial はりビジョンの記述順序に忠実に振舞いますので、
foozy@708: \hgcmdargs{log}{-r 2:4} というコマンド起動が
foozy@708: $2,3,4$ の順序で表示する一方、
foozy@708: \hgcmdargs{log}{-r 4:2} というコマンド起動は
foozy@708: $4,3,2$ の順序で表示します。
foozy@708: 
foozy@708: \subsection{More detailed information}
foozy@708: 
foozy@708: 目当てのチェンジセットが既に判明している場合は
foozy@708: \hgcmd{log} が出力する概要情報は有用ですが、
foozy@708: あるチェンジセットが目当てのものか否かを判定しようとする場合には、
foozy@708: 変更についての完全な説明文や、
foozy@708: 変更されたファイルの一覧が必要になることでしょう。
foozy@708: \hgcmd{log} コマンドの
foozy@708: \hggopt{-v}（ないし \hggopt{--verbose}）オプションは、
foozy@708: これら追加の詳細情報を表示します。
foozy@708: 
foozy@708: \interaction{tour.log-v}
foozy@708: 
foozy@708: 説明文と変更内容の両方を見たい場合は、
foozy@708: \hgopt{log}{-p} （ないし \hgopt{log}{--patch}）
foozy@708: オプションを付加してください。
foozy@708: このオプションにより、
foozy@708: 変更内容が \emph{unified diff} 形式
foozy@708: （これまでに unified diff 形式を見たことが無いのでしたら、
foozy@708: \ref{sec:mq:patch}~節に概要の説明があります）で出力されます。
foozy@708: 
foozy@708: \interaction{tour.log-vp}
foozy@708: 
foozy@708: \section{All about command options}
foozy@708: 
foozy@708: Mercurial のコマンド探検をここで少々中断して、
foozy@708: Mercurial コマンドの動作パターンについて説明しましょう。
foozy@708: 本章におけるツアーを続けるにつれて、
foozy@708: このことを覚えておいて良かったと思うことでしょう。
foozy@708: 
foozy@708: Mercurial は、
foozy@708: コマンドに対して指定可能なオプションの取り扱いに関して、
foozy@708: 近年の Linux および Unix システムに共通のオプション記述慣習を踏襲した、
foozy@708: 一貫した素直な扱い方を採用しています。
foozy@708: 
foozy@708: \begin{itemize}
foozy@708: \item 全てのオプションはロングネーム（long name）を持っています。
foozy@708:   例えば、既に見てきたように、
foozy@708:   \hgcmd{log} コマンドは \hgopt{log}{--rev} オプションを受け付けます。
foozy@708: 
foozy@708: \item 殆どのオプションがショートネーム（short name）も持っています。
foozy@708:   \hgopt{log}{--rev} オプションの代わりに
foozy@708:   \hgopt{log}{-r} を使用できます
foozy@708:   （ショートネームを持たないオプションがあるのは、
foozy@708:   それらのオプションが滅多に利用されないためです\footnote{訳注:
foozy@708:   訳者のコマンド開発経験では、
foozy@708:   ショートネームの候補となるアルファベットが複数のオプションの間で重なる場合、
foozy@708:   あえてショートネームを設定しない、
foozy@708:   という場合もあります。}）。
foozy@708: 
foozy@708: \item ロングネームオプションは２つのマイナス記号\footnote{訳注:
foozy@708:   原文では ``dash(es)'' ですが、
foozy@708:   「ダッシュ（ダーシ）」や「ハイフン」よりも、
foozy@708:   PC における入力では直接的な、
foozy@708:   「マイナス記号」を訳語に当てました。}で始まります
foozy@708:   （例: \hgopt{log}{--rev}）が
foozy@708:   ショートネームオプションは１つのマイナス記号で始まります
foozy@708:   （例: \hgopt{log}{-r}）。
foozy@708: 
foozy@708: \item オプションの命名と用法は、コマンド間で一貫性が取られています\footnote{
foozy@708:   訳注： 訳者が以前、オプションを追加するパッチを提案した際には、
foozy@708:   パッチの機能的な話とは別に、
foozy@708:   「○○のコマンドでは××というう命名になっているから、それに倣ってね」
foozy@708:   と指摘されたことがあり、
foozy@708:   「一貫性がとられている」との主張は伊達ではありません。}。
foozy@708:   例えば、チェンジセット識別子やりビジョン番号を指定可能なコマンドは、
foozy@708:   全て \hgopt{log}{-r} および \hgopt{log}{--rev} オプションを受理します。
foozy@708: 
foozy@708: \end{itemize}
foozy@708: 
foozy@708: 本書の実行例では、
foozy@708: ロングネームオプションの代わりにショートネームオプションを使用します。
foozy@708: これは単に筆者の好みというだけのことですので、
foozy@708: 特に気にする必要はありません。
foozy@708: 
foozy@708: 何らかの表示を行うコマンドの多くは、
foozy@708: \hggopt{-v}（ないし \hggopt{--verbose}）
foozy@708: オプションを付与することでより多くの情報の表示を、
foozy@708: \hggopt{-q}（ないし \hggopt{--quiet}）
foozy@708: オプションを付与することで表示を抑止することができます。
foozy@708: 
foozy@708: \section{Making and reviewing changes}
foozy@708: 
foozy@708: この時点で、Mercurial における履歴を把握できていますので、
foozy@708: 変更の実施や、その検証を行ってみましょう。
foozy@708: 
foozy@708: まず始めにすべきことは、
foozy@708: 独自の実験を元々のリポジトリから隔離することです。
foozy@708: リポジトリの複製に、先程は \hgcmd{clone} を使用しましたが、
foozy@708: この時点での遠隔リポジトリからの複製は必要ありません。
foozy@708: 既に手元にある複製リポジトリから複製すれば良いのです。
foozy@708: ローカルリポジトリの複製は、
foozy@708: ネットワーク越しの複製よりも非常に高速ですし、
foozy@708: 多くの場合においてディスク領域消費も少なくて済みます\footnote{訳注:
foozy@708: 詳細は ``Avoiding seeks'' にありますが、
foozy@708: Mercurial はローカルリポジトリの複製の際に、
foozy@708: ディスクヘッドのシーク回避のために、
foozy@708: ファイルの複製ではなく所謂``ハードリンク''を実施します。}。
foozy@708: 
foozy@708: \interaction{tour.reclone}
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: \dirname{my-hello} リポジトリには、
foozy@708: 典型的な ``hello, world'' プログラムが格納された
foozy@708: \filename{hello.c} ファイルがあります。
foozy@708: ではここで、
foozy@708: いにしえの \command{sed} コマンドを使用して、
foozy@708: ２行目を出力するように変更してみましょう。
foozy@708: （変更のために \command{sed} を使用するのは、
foozy@708: 単にスクリプトによる自動化が簡単であるからです。
foozy@708: 自動化の必要が無ければ、
foozy@708: おそらく \command{sed} を使用する必要は無いでしょう。
foozy@708: 好みのエディタで編集をしてください。）。
foozy@708: 
foozy@708: \interaction{tour.sed}
foozy@708: 
foozy@708: \hgcmd{status} コマンドにより、
foozy@708: リポジトリ配下のファイルの状況に関する
foozy@708: Mercurial の認識が表示されます。
foozy@708: 
foozy@708: \interaction{tour.status}
foozy@708: 
foozy@708: 幾つかのファイルに対しては、
foozy@708: \hgcmd{status} コマンドは特に何も表示しませんが、
foozy@708: \filename{hello.c} に対しては
foozy@708: ``\texttt{M}'' で始まる行を表示します。
foozy@708: 明示的に指定しない限り、
foozy@708: 変更されていないファイルに対して
foozy@708: \hgcmd{status} は何も表示しません。
foozy@708: 
foozy@708: ``\texttt{M}'' 表示は、
foozy@708: Mercurial が \filename{hello.c} ファイルの変更を検知していることを表します。
foozy@708: ファイルの変更に先立って（あるいは変更の後に）、
foozy@708: Mercurial に対して\emph{通知}する必要はありません。
foozy@708: Mercurial 自身で変更の実施を検知することができます。
foozy@708: 
foozy@708: \hgcmd{status} の表示は、
foozy@708: \filename{hello.c} を変更したことを知るのに役立ちますが、
foozy@708: \emph{どのような}変更を行ったのかを厳密に知りたい場合も有るでしょう。
foozy@708: 変更内容を知るためには、
foozy@708: \hgcmd{diff} コマンドを使用します。
foozy@708: 
foozy@708: \interaction{tour.diff}
foozy@708: 
foozy@708: \section{Recording changes in a new changeset}
foozy@708: 
foozy@708: 変更内容に満足して、
foozy@708: 新規チェンジセットに変更内容を記録するに足る状況に到達するまでは、
foozy@708: ファイルの内容を変更し、
foozy@708: ビルドと変更内容に対する試験を行い、
foozy@708: \hgcmd{status} および \hgcmd{diff} による変更内容を確認する、
foozy@708: という作業を繰り返します。
foozy@708: 
foozy@708: \hgcmd{commit} コマンドを用いることで、
foozy@708: チェンジセットを新たに作成することができます。
foozy@708: 通常これを``コミットの実施''（``making a commit''）ないし
foozy@708: ``コミットする''（``committing''）と言います。
foozy@708: 
foozy@708: \subsection{Setting up a username}
foozy@708: 
foozy@708: 最初に \hgcmd{commit} 実行を行う際には、
foozy@708: 必ずしも実行が成功\footnote{訳注:
foozy@708: ここで言う``成功''とは、
foozy@708: コマンド実行そのものの成功というよりは、
foozy@708: ``思った通りのチェンジセットを生成''することに対する成功に近いニュアンスです。
foozy@708: }するとは限りません。
foozy@708: チェンジセットのコミットの際に Mercurial は、
foozy@708: コミットしたユーザの名前と電子メールアドレスを、
foozy@708: チェンジセット毎に記録しますので、
foozy@708: 誰もが後からチェンジセット作成者を知ることができます。
foozy@708: Mercurial は以下の手順で、
foozy@708: 変更内容と共に記録する妥当なユーザ名を自動的に検出しようとします。
foozy@708: 
foozy@708: \begin{enumerate}
foozy@708: \item \hgcmd{commit} コマンド起動の際に
foozy@708:   \hgopt{commit}{-u} オプションによってユーザ名を指定した場合、
foozy@708:   常にその値が優先的に使用されます。
foozy@708: 
foozy@708: \item 次に \envar{HGUSER} 環境変数設定の有無が確認されます。
foozy@708: 
foozy@708: \item ホームディレクトリ直下に、
foozy@708:   \rcitem{ui}{username} 要素を持つ
foozy@708:   \sfilename{.hgrc}\footnote{訳注:
foozy@708:   Windows 向けバイナリ版の場合、
foozy@708:   \envar{HOME} 環境変数が指すディレクトリ、
foozy@708:   ないし \dirname{C:\\Documents and Settings\\USERNAME}
foozy@708:   配下の \sfilename{Mercurial.ini} が用いられます。}
foozy@708:   がある場合、その値が使用されます。
foozy@708:   このファイルに書くべき内容に関しては、
foozy@708:   \ref{sec:tour-basic:username}節を参照してください。
foozy@708: 
foozy@708: \item \envar{EMAIL} 環境変数が設定されている場合は、
foozy@708:   その値が使用されます。
foozy@708: 
foozy@708: \item それ以外の場合、
foozy@708:   Mercurial は稼動しているシステムにユーザとホストの名前を問い合わせた上で、
foozy@708:   電子メールアドレス形式のユーザ名を生成し、これを使用します。
foozy@708:   この方法で生成されたユーザ名は往々にして役に立たないため、
foozy@708:   Mercurial は警告を表示します。
foozy@708: 
foozy@708: \end{enumerate}
foozy@708: 
foozy@708: 上記の方法が全て失敗した場合、
foozy@708: Mercurial によるコミットは失敗し、
foozy@708: エラーメッセージを表示します。
foozy@708: そのような場合では、明示的にユーザ名を指定しない限り、
foozy@708: コミットは成功しないでしょう。
foozy@708: 
foozy@708: \envar{HGUSER} 環境変数と
foozy@708: \hgcmd{commit} コマンドへの
foozy@708: \hgopt{commit}{-u} オプション指定は、
foozy@708: Mercurial 設定ファイル中の username 設定を
foozy@708: \emph{無効にする}点に注意してください。
foozy@708: 通常の使用において、
foozy@708: 自身のユーザ名を簡単且つ確実に指定するには、
foozy@708: \sfilename{.hgrc} ファイルで指定するのが良いでしょ。
foozy@708: 記述方法に関する詳細は後述します。
foozy@708: 
foozy@708: \subsubsection{Creating a Mercurial configuration file}
foozy@708: \label{sec:tour-basic:username}
foozy@708: 
foozy@708: ユーザ名を設定するには、
foozy@708: まずは好みのエディタを使って、
foozy@708: ホームディレクトリ直下に
foozy@708: \sfilename{.hgrc}ファイルを作成します。
foozy@708: Mercurial はこのファイルから利用者の個人設定を参照します。
foozy@708: \sfilename{.hgrc} の内容は、
foozy@708: まずは以下のようになるでしょう。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   # This is a Mercurial configuration file.
foozy@708:   [ui]
foozy@708:   username = Firstname Lastname <email.address@domain.net>
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: ``\texttt{[ui]}'' 行は、
foozy@708: 設定ファイルの\emph{セクション}開始を意味し、
foozy@708: ``\texttt{username = ...}'' という記述行は
foozy@708: ``\texttt{ui} セクションにおける \texttt{username} 項目への値の設定''
foozy@708: とみなされます。
foozy@708: 一度セクションが開始されたなら、
foozy@708: 新たなセクションが開始されるか、
foozy@708: ファイルの末尾に達するまで当該セクションが続きます。
foozy@708: 空の行と、
foozy@708: ``\texttt{\#}'' の次の文字から行末までは、
foozy@708: Mercurial によってコメントとみなされ無視されます。
foozy@708: 
foozy@708: \subsubsection{Choosing a user name}
foozy@708: 
foozy@708: \texttt{username} 設定項目は、
foozy@708: Mercurial に与える値ではありますが、
foozy@708: リポジトリを参照する他の利用者のための情報ですので、
foozy@708: 任意の文字を使用可能です。
foozy@708: 殆どの利用者は、
foozy@708: 名前と電子メールアドレスを用いた前述のような形式を用いています。
foozy@708: 
foozy@708: \begin{note}
foozy@708:   Mercurial の組み込みウェブサーバ機能では、
foozy@708:   スパムメールの送付者が利用する電子メールアドレス自動収集ツールに対して、
foozy@708:   電子メールアドレスを難読化することが可能です。
foozy@708:   この機能を用いることで、
foozy@708:   Mercurial リポジトリをウェブ上に公開した際に、
foozy@708:   益体も無いメール受信の増加を抑止することができます。
foozy@708: \end{note}
foozy@708: 
foozy@708: \subsection{Writing a commit message}
foozy@708: 
foozy@708: 当該チェンジセットでの変更内容を説明するメッセージを入力するために、
foozy@708: Mercurial はコミットの際にエディタを起動します。
foozy@708: このメッセージを\emph{コミットメッセージ}と呼び、
foozy@708: 読み手に変更の内容と理由を伝えるために記録されるもので、
foozy@708: コミット後の \hgcmd{log} コマンドにより表示されます。
foozy@708: 
foozy@708: \interaction{tour.commit}
foozy@708: 
foozy@708: \hgcmd{commit} コマンドが起動するエディタは、
foozy@708: ``\texttt{HG:}''で始まる数行が後に続く空行を表示していることでしょう。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   \emph{空行}
foozy@708:   HG: changed hello.c
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: Mercurial は
foozy@708: ``\texttt{HG:}'' で始まる行を無視します。
foozy@708: これらの行は、
foozy@708: チェンジセットへの変更記録対象となるファイルの一覧を、
foozy@708: コミットしようとしているユーザに知らせるためだけのものです。
foozy@708: そのため、これらの行の変更や削除は何も意味を持ちません。
foozy@708: 
foozy@708: \subsection{Writing a good commit message}
foozy@708: 
foozy@708: \hgcmd{log} はコミットメッセージの最初の１行しか表示しませんので、
foozy@708: 最初の１行だけで意味の通じる内容にするのが良いでしょう。
foozy@708: この方針から\emph{外れている}ために、
foozy@708: 読み難いコミットメッセージの実例を以下に示します。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   changeset:   73:584af0e231be
foozy@708:   user:        Censored Person <censored.person@example.org>
foozy@708:   date:        Tue Sep 26 21:37:07 2006 -0700
foozy@708:   summary:     include buildmeister/commondefs.   Add an exports and install
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: コミットメッセージの２行目以降に関しては、
foozy@708: 特に厳密なルールは存在しません。
foozy@708: コミットメッセージに対して、
foozy@708: プロジェクト運用上の方針として何らかの形式を要求するかもしれませんが、
foozy@708: Mercurial 自身が解釈や忖度をすることはありません。
foozy@708: 
foozy@708: 筆者の個人的な好みは、
foozy@708: \hgcmdargs{log}{--patch} を一瞥しただけでは判断できない事柄について、
foozy@708: 簡潔でありながら有益な情報をもたらすようなコミットメッセージです。
foozy@708: 
foozy@708: \subsection{Aborting a commit}
foozy@708: 
foozy@708: コミットメッセージの記述中にコミットを取りやめを決意した場合には、
foozy@708: 編集中のファイルを保存せずにエディタを終了すれば良いのです。
foozy@708: この場合、リポジトリと作業領域ディレクトリのいずれに対しても、
foozy@708: 何ら操作は加えられません。
foozy@708: 
foozy@708: 引数無しで \hgcmd{commit} コマンドを実行した場合、
foozy@708: \hgcmd{status} および \hgcmd{diff} 
foozy@708: によって報告された全ての変更内容が記録されます。
foozy@708: 
foozy@708: \subsection{Admiring our new handiwork}
foozy@708: 
foozy@708: コミットが完了したなら、
foozy@708: 今しがた新規作成したチェンジセットを
foozy@708: \hgcmd{tip} コマンドで表示することができます。
foozy@708: このコマンドは \hgcmd{log} と同一の出力を行いますが、
foozy@708: 表示されるのはリポジトリにおける最新のリビジョンだけです。
foozy@708: 
foozy@708: \interaction{tour.tip}
foozy@708: 
foozy@708: リポジトリにおける最新のリビジョンを tip リビジョン、
foozy@708: あるいは単に tip と呼びます。
foozy@708: 
foozy@708: \section{Sharing changes}
foozy@708: 
foozy@708: 先の記述で、Mercurial におけるリポジトリは、
foozy@708: それ自身で完結している旨述べました。
foozy@708: これは即ち、
foozy@708: たった今新規に作成したチェンジセットは、
foozy@708: 手元の \dirname{my-hello} リポジトリにしか存在しないことを意味します。
foozy@708: この変更内容を他のリポジトリへと伝播する方法を、
foozy@708: 順に見てゆきましょう。
foozy@708: 
foozy@708: \subsection{Pulling changes from another repository}
foozy@708: \label{sec:tour:pull}
foozy@708: 
foozy@708: まず始めに、
foozy@708: 元々の \dirname{hello} リポジトリを複製して、
foozy@708: たった今新規に作成した変更のコミットされていないリポジトリを作成しましょう。
foozy@708: この複製したリポジトリを、
foozy@708: \dirname{hello-pull} と呼びます。
foozy@708: 
foozy@708: \interaction{tour.clone-pull}
foozy@708: 
foozy@708: \hgcmd{pull} コマンドにより、
foozy@708: \dirname{my-hello} から
foozy@708: \dirname{hello-pull} へと変更を取り込みます。
foozy@708: しかしながら、未知の変更を闇雲にリポジトリに取り込むのは、
foozy@708: あまりぞっとしません。
foozy@708: Mercurial が提供する \hgcmd{incoming} コマンドは、
foozy@708: 実際に変更を取り込む事無く、
foozy@708: \hgcmd{pull} 
foozy@708: によってリポジトリに取り込まれる\emph{予定}のチェンジセットを表示します。
foozy@708: 
foozy@708: \interaction{tour.incoming}
foozy@708: 
foozy@708: （勿論、
foozy@708: \hgcmd{incoming} コマンドを実行したリポジトリに対して、
foozy@708: \hgcmd{pull} による変更取り込みの機会よりも前に、
foozy@708: より多くの変更を追加することは可能ですので、
foozy@708: 実際の変更取り込みは予定とは異なる可能性が有ります。）
foozy@708: 
foozy@708: リポジトリへの変更の取り込みは、
foozy@708: どのリポジトリから取り込むかを指示しつつ、
foozy@708: \hgcmd{pull} コマンドを実行するという簡単なものです。
foozy@708: 
foozy@708: \interaction{tour.pull}
foozy@708: 
foozy@708: 実施前後の \hgcmd{tip} 出力から見て取れるように、
foozy@708: 手元のリポジトリへの変更内容の反映が成功しています。
foozy@708: 取り込んだ変更内容を作業領域ディレクトリにおいて参照するためには、
foozy@708: もうひと手順必要です。
foozy@708: 
foozy@708: \subsection{Updating the working directory}
foozy@708: 
foozy@708: リポジトリと作業領域ディレクトリの関係について、
foozy@708: これまでは大雑把にしか説明してきませんでした。
foozy@708: \ref{sec:tour:pull}~節で実行した
foozy@708: \hgcmd{pull} コマンドは、
foozy@708: リポジトリへの変更の取り込みを行いますが、
foozy@708: 確認してみればわかるように、
foozy@708: 作業領域には何ら影響を及ぼしません。
foozy@708: これは、
foozy@708: \hgcmd{pull} の（基底の）挙動が、
foozy@708: 作業領域に影響を及ぼさないものであるためです。
foozy@708: 作業領域の更新には、
foozy@708: \hgcmd{pull} ではなく \hgcmd{update} を用います。
foozy@708: 
foozy@708: \interaction{tour.update}
foozy@708: 
foozy@708: \hgcmd{pull} 実行時に作業領域を自動的に更新しないことは、
foozy@708: 一見奇異に見えるかもしれませんが、
foozy@708: 実はそれには理由が有ります。
foozy@708: \hgcmd{update} を用いることで、
foozy@708: リポジトリに記録された\emph{任意の版}の状態へと、
foozy@708: 作業領域ディレクトリの内容を更新することができます。
foozy@708: 作業領域ディレクトリを
foozy@708: ---例えば、バグの原因調査などのために---
foozy@708: 古い版にして作業していた場合などは、
foozy@708: \hgcmd{pull} 実行が作業領域ディレクトリを最新の版に自動的に更新してしまうのは、
foozy@708: あまりよろしくないでしょう。
foozy@708: 
foozy@708: しかし、\hgcmd{pull} 〜 \hgcmd{update} という流れは非常に頻繁な作業ですから、
foozy@708: \hgcmd{pull} に \hgopt{pull}{-u} オプションを指定することで、
foozy@708: Mercurial はこれら２つを組み合わせた機能を提供します。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   hg pull -u
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: \ref{sec:tour:pull}~節での
foozy@708: \hgopt{pull}{-u} オプションを指定しない
foozy@708: \hgcmd{pull} 実行の出力には、
foozy@708: 作業領域ディレクトリの更新に明示的な手順が必要であることを示す、
foozy@708: 注意喚起のメッセージが表示されているのが見て取れます。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   (run 'hg update' to get a working copy)
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: 作業領域ディレクトリがどの版の内容に基づいているかを見るには、
foozy@708: \hgcmd{parents} コマンドを使用します。
foozy@708: 
foozy@708: \interaction{tour.parents}
foozy@708: 
foozy@708: 図~\ref{fig:tour-basic:history} では、
foozy@708: 個々のチェンジセットを繋ぐ矢印が描かれています。
foozy@708: 矢印の\emph{根元}にあたるチェンジセットが親を、
foozy@708: そして矢印の\emph{先}にあたるチェンジセットが子を表しています。
foozy@708: 同じように、作業領域ディレクトリも親を持っており、
foozy@708: 現時点で保持している作業領域ディレクトリの内容は、
foozy@708: そのチェンジセットに基づいたものです。
foozy@708: 
foozy@708: 作業領域ディレクトリの内容を特定の版のものにする場合、
foozy@708: \hgcmd{update} コマンドにリビジョン番号ないしチェンジセット~IDを指定します。
foozy@708: 
foozy@708: \interaction{tour.older}
foozy@708: 
foozy@708: 明示的な版指定をしなかった場合、
foozy@708: 上記の例における２つ目の \hgcmd{update} 実行で見て取れるように、
foozy@708: \hgcmd{update} は tip が指定されたものとして振舞います。
foozy@708: 
foozy@708: \subsection{Pushing changes to another repository}
foozy@708: 
foozy@708: Mercurial では、
foozy@708: 現在作業を行っているリポジトリから他のリポジトリへの、
foozy@708: 変更内容の反映が可能です。
foozy@708: 先に示した \hgcmd{pull} の例と同様に、
foozy@708: まずは変更反映先とするための一時的なリポジトリを作成します。
foozy@708: 
foozy@708: \interaction{tour.clone-push}
foozy@708: 
foozy@708: \hgcmd{outgoing} コマンドは、
foozy@708: 他のリポジトリへの反映対象となるチェンジセットを一覧表示します。
foozy@708: 
foozy@708: \interaction{tour.outgoing}
foozy@708: 
foozy@708: そして \hgcmd{push} コマンドが実際の反映作業を行います。
foozy@708: 
foozy@708: \interaction{tour.push}
foozy@708: 
foozy@708: \hgcmd{pull} と同様に、
foozy@708: \hgcmd{push} コマンドは変更反映先のリポジトリ側において、
foozy@708: 作業領域ディレクトリの更新は行いません
foozy@708: （\hgcmd{pull} と違い、
foozy@708: \hgcmd{push} は変更反映先のリポジトリ側での作業領域ディレクトリを更新する
foozy@708: \texttt{-u} オプションを持ちません）。
foozy@708: 
foozy@708: 当該リポジトリが既に相当するチェンジセットを持っている場合、
foozy@708: 変更の取り込みあるいは反映を行うとどうなるのでしょう？
foozy@708: 驚くようなことは何も起こりません。
foozy@708: 
foozy@708: \interaction{tour.push.nothing}
foozy@708: 
foozy@708: \subsection{Sharing changes over a network}
foozy@708: 
foozy@708: 先の幾つかの節で触れたコマンドの利用は、
foozy@708: 手元にあるリポジトリにのみ限定されているわけではありません。
foozy@708: 全く同様の形式で、
foozy@708: ネットワーク接続経由でも機能します。
foozy@708: ローカルファイルシステムのパスの代わりに、
foozy@708: URL を指定すれば良いのです。
foozy@708: 
foozy@708: \interaction{tour.outgoing.net}
foozy@708: 
foozy@708: この例では、
foozy@708: 遠隔リポジトリに対して反映可能な変更の一覧を見ることができますが、
foozy@708: このリポジトリは匿名での変更反映を許すようには当然ですが設定されていません。
foozy@708: 
foozy@708: \interaction{tour.push.net}
foozy@708: 
foozy@708: %%% Local Variables: 
foozy@708: %%% mode: latex
foozy@708: %%% TeX-master: "00book"
foozy@708: %%% End: