%\chapter{Managing change with Mercurial Queues}
\chapter{Mercurial Queuesで変更を管理する}
\label{chap:mq}

%\section{The patch management problem}
\section{パッチ管理の問題}
\label{sec:mq:patch-mgmt}

%Here is a common scenario: you need to install a software package from
%source, but you find a bug that you must fix in the source before you
%can start using the package.  You make your changes, forget about the
%package for a while, and a few months later you need to upgrade to a
%newer version of the package.  If the newer version of the package
%still has the bug, you must extract your fix from the older source
%tree and apply it against the newer version.  This is a tedious task,
%and it's easy to make mistakes.

よくあるシナリオ：ソースからソフトウェアパッケージをインストールする必要
がある．しかしパッケージを使う前にソースから直すべきバグを見つけた．変更
を加えて，暫くパッケージのことは忘れている．数ヶ月後，新しいバージョンを
インストールすることになった．もし新しいバージョンが，依然としてそのバグ
を持っていた場合，修正を古いソースから抽出して，新しいバージョンに適用し
なければならない．これは退屈でしかも間違いやすい仕事だ．

%This is a simple case of the ``patch management'' problem.  You have
%an ``upstream'' source tree that you can't change; you need to make
%some local changes on top of the upstream tree; and you'd like to be
%able to keep those changes separate, so that you can apply them to
%newer versions of the upstream source.

これがパッチ管理問題のシンプルな例である．もしあなたが変更できない上流の
ソースツリーがあれば，アップストリームのツリーの上でローカルな変更をしな
ければならない．あなたはアップストリームソースに適用できるようにきっとこ
の変更を分離しておきたいと思うはずだ．

%The patch management problem arises in many situations.  Probably the
%most visible is that a user of an open source software project will
%contribute a bug fix or new feature to the project's maintainers in the
%form of a patch.

パッチ管理問題はいろいろな状況で起こる．おそらく最も明らかなのは，オープ
ンソースソフトウェアプロジェクトのユーザが，プロジェクトのメンテナにバグ
フィックスや新機能をパッチの形で貢献することであろう．

%Distributors of operating systems that include open source software
%often need to make changes to the packages they distribute so that
%they will build properly in their environments.

オープンソフトウェアを含むオペレーティングシステムの配布者は，配布するパッ
ケージが彼らの環境で正しくビルドできるようにパッケージへ変更を加えること
が多い．

%When you have few changes to maintain, it is easy to manage a single
%patch using the standard \command{diff} and \command{patch} programs
%(see section~\ref{sec:mq:patch} for a discussion of these tools).  Once
%the number of changes grows, it starts to make sense to maintain patches
%as discrete ``chunks of work,'' so that for example a single patch will
%contain only one bug fix (the patch might modify several files, but it's
%doing ``only one thing''), and you may have a number of such patches for
%different bugs you need fixed and local changes you require.  In this
%situation, if you submit a bug fix patch to the upstream maintainers of
%a package and they include your fix in a subsequent release, you can
%simply drop that single patch when you're updating to the newer release.

もしメンテナンスしている変更がごくわずかなら，標準の\command{diff}コマン
ドと\command{patch}コマンドを使って単一のパッチを管理するのが簡単だ．（こ
れらのツールについては~\ref{sec:mq:patch}の節を参照．）変更の数が増えてく
ると，単一のバグフィックスを含む個々のパッチを一塊の集合として管理するこ
とが現実味を帯びてくる．（各々のパッチは複数のファイルを変更するかもしれ
ないが，目的は1つきりである．）修正したいバグがいくつもあったり，ローカル
での様々な変更の必要のため，数多くのそのようなパッチを持つことになるかも
しれない．この状況で，アップストリームのメンテナにバグ修正パッチを送り，
彼らがあなたの修正を後のリリースに取り込めば，手元で新しいリリースに切替
えた時には単純にそのパッチを破棄すれば良い．

%Maintaining a single patch against an upstream tree is a little
%tedious and error-prone, but not difficult.  However, the complexity
%of the problem grows rapidly as the number of patches you have to
%maintain increases.With more than a tiny number of patches in hand,
%understanding which ones you have applied and maintaining them moves
%from messy to overwhelming.

単一のパッチをアップストリームのツリーに対してメンテナンスすることはやや
面倒で，間違いの元になりがちであるが，難しくはない．しかし，メンテナンス
するパッチの数が増えるに従って問題の複雑さが急速に増していく．パッチの数
がある程度以上多くなると，どのパッチを適用したか，どのパッチを管理してい
るのかの理解が，厄介という状態から圧倒されるている状態になる．

%Fortunately, Mercurial includes a powerful extension, Mercurial Queues
%(or simply ``MQ''), that massively simplifies the patch management
%problem.

幸いにも，MercurialはMercurial Queues（あるいは単にMQ）という強力なエクス
テンションをもっており，パッチ管理の問題を大幅に単純化する．


%\section{The prehistory of Mercurial Queues}
\section{Mercurial Queues前史}
\label{sec:mq:history}

%During the late 1990s, several Linux kernel developers started to
%maintain ``patch series'' that modified the behaviour of the Linux
%kernel.  Some of these series were focused on stability, some on
%feature coverage, and others were more speculative.

1990年代の終わり頃，Linuxカーネルの開発者達は，Linuxカーネルを改善する一
連のパッチの管理を始めた．それらのうち，あるものは安定性に，別のものは特
定の機能に，また別のものは野心的な内容に特化していた．

%The sizes of these patch series grew rapidly.  In 2002, Andrew Morton
%published some shell scripts he had been using to automate the task of
%managing his patch queues.  Andrew was successfully using these
%scripts to manage hundreds (sometimes thousands) of patches on top of
%the Linux kernel.

これらのパッチシリーズのサイズははすぐに膨れ上がった．2002年にAndrew
Mortonは彼のパッチキューの管理を自動化するいくつかのシェルスクリプトを公
表した．Andrewは数百から数千のLinuxカーネルパッチをこれらのスクリプトで
管理することができていた．

%\subsection{A patchwork quilt}
\subsection{patchwork quilt}
\label{sec:mq:quilt}

%In early 2003, Andreas Gruenbacher and Martin Quinson borrowed the
%approach of Andrew's scripts and published a tool called ``patchwork
%quilt''~\cite{web:quilt}, or simply ``quilt''
%(see~\cite{gruenbacher:2005} for a paper describing it).  Because
%quilt substantially automated patch management, it rapidly gained a
%large following among open source software developers.

2003年の始め，Andreas GruenbacherとMartin QuinsonはAndrewのスクリプトのや
り方を真似て，``patchwork quilt''~\cite{web:quilt}あるいは単に``quilt''と
呼ばれるツールをリリースした．（詳しくは論文~\cite{gruenbacher:2005}を参
照のこと．）quiltは十分に自動化されたパッチ管理を提供していたので，ソフト
ウェア開発者の大きな支持を急速に獲得していった．

%Quilt manages a \emph{stack of patches} on top of a directory tree.
%To begin, you tell quilt to manage a directory tree, and tell it which
%files you want to manage; it stores away the names and contents of
%those files.  To fix a bug, you create a new patch (using a single
%command), edit the files you need to fix, then ``refresh'' the patch.

quiltはディレクトリツリー上で\emph{パッチのスタック}を管理する．パッチの
管理を始めるには，quiltに管理すべきディレクトリツリーと，管理対象のファイ
ルを指定する．quiltはこれらのファイルの名前と中身を保存する．バグを修正
する場合は，まず新しいパッチを（コマンド1つで）作成し，必要なファイルに
修正を加えた後，パッチを``リフレッシュ''すればよい．

%The refresh step causes quilt to scan the directory tree; it updates
%the patch with all of the changes you have made.  You can create
%another patch on top of the first, which will track the changes
%required to modify the tree from ``tree with one patch applied'' to
%``tree with two patches applied''.

リフレッシュでは，quiltはディレクトリツリーをスキャンし，変更全てを反映さ
せてパッチを更新する．``あるパッチが適用された状態のツリー''から``2つのパッ
チが適用されたツリー''へ更新するのに必要な変更を追跡し，別のパッチを作る
こともできる．

%You can \emph{change} which patches are applied to the tree.  If you
%``pop'' a patch, the changes made by that patch will vanish from the
%directory tree.  Quilt remembers which patches you have popped,
%though, so you can ``push'' a popped patch again, and the directory
%tree will be restored to contain the modifications in the patch.Most
%importantly, you can run the ``refresh'' command at any time, and the
%topmost applied patch will be updated.  This means that you can, at
%any time, change both which patches are applied and what
%modifications those patches make.

ユーザはどのパッチがツリーに適用されるかを\emph{変更}できる．あるパッチを
ポップすると，このパッチによる変更はツリーから消滅する．quiltはどのパッチ
をポップしたか記憶しており，一度ポップしたファイルを再びプッシュし，ディ
レクトリツリーをパッチによる変更がなされた状態に戻すことができる．最も重
要なことは，いつでも``refresh''コマンドを実行して一番新しく適用されたパッ
チを更新できることである．これはすなわち，パッチの適用された状態と，パッ
チそれ自体をいつでも更新できるということである．

%Quilt knows nothing about revision control tools, so it works equally
%well on top of an unpacked tarball or a Subversion working copy.

quiltはリビジョン管理ツールについては全く関知しないため，展開されたtarアー
カイブ上でも，Subversionのワーキングコピー上でも同様に動作する．

%\subsection{From patchwork quilt to Mercurial Queues}
\subsection{patchwork quiltからMercurial Queuesへ}
\label{sec:mq:quilt-mq}

%In mid-2005, Chris Mason took the features of quilt and wrote an
%extension that he called Mercurial Queues, which added quilt-like
%behaviour to Mercurial.

2005年の中頃Chris Masonは，quiltの機能を取り入れて，Mercurialにquiltのよ
うな動作を追加するMercurial Queuesというエクステンションを書いた．

%The key difference between quilt and MQ is that quilt knows nothing
%about revision control systems, while MQ is \emph{integrated} into
%Mercurial.  Each patch that you push is represented as a Mercurial
%changeset.  Pop a patch, and the changeset goes away.

quiltとMQの違いは，quiltはリビジョン管理システムについて何も関知しないの
に対して，MQはMercurialに統合されていることである．プッシュした個々のパッ
チはMercurialのチェンジセットとして表現される．パッチをポップすると，チェ
ンジセットは消えてなくなる．

%Because quilt does not care about revision control tools, it is still
%a tremendously useful piece of software to know about for situations
%where you cannot use Mercurial and MQ.

quiltはリビジョン管理ツールと無関係に利用可能なため，MercurialとMQが使え
ない状況では依然として非常に有益なツールであることは記憶に留めておくべき
である．

%\section{The huge advantage of MQ}
\section{MQの大きな利点}

%I cannot overstate the value that MQ offers through the unification of
%patches and revision control.

MQがパッチとリビジョンコントロールの統合によってもたらす価値を誇張するわ
けにはいかない．

%A major reason that patches have persisted in the free software and
%open source world---in spite of the availability of increasingly
%capable revision control tools over the years---is the \emph{agility}
%they offer.  

時を追う毎にリビジョンコントロールツールの利用が広がっているにもかかわら
ず，フリーソフトとオープンソースの世界にパッチが存在する大きな理由はその
\emph{機敏さ}にある．

%Traditional revision control tools make a permanent, irreversible
%record of everything that you do.  While this has great value, it's
%also somewhat stifling.  If you want to perform a wild-eyed
%experiment, you have to be careful in how you go about it, or you risk
%leaving unneeded---or worse, misleading or destabilising---traces of
%your missteps and errors in the permanent revision record.

伝統的なリビジョンコントロールツールは，行った操作の永久的で不可逆的な
記録を残す．これには大きな価値がある一方で，窮屈に感じることもある．もし
過激な実験をするのであれば，どのように進めるか慎重にする必要がある．さも
なければ，不要な，あるいは誤解を招いたり，安定性を損なうトレースとエラー
を永久的なリビジョン履歴に残すことになる．

%By contrast, MQ's marriage of distributed revision control with
%patches makes it much easier to isolate your work.  Your patches live
%on top of normal revision history, and you can make them disappear or
%reappear at will.  If you don't like a patch, you can drop it.  If a
%patch isn't quite as you want it to be, simply fix it---as many times
%as you need to, until you have refined it into the form you desire.

対称的に，MQによる分散リビジョンコントロールとパッチの結合は，作業を隔離
することを遥かに容易にする．パッチは通常のリビジョン履歴の上に乗っており，
望むように消滅させたり再現させることができる．パッチを気に入らなければ，
これを棄却することもできる．パッチがあなたの望むようなものでなければ，希
望通りになるまで何度でも簡単に修正することができる．

%As an example, the integration of patches with revision control makes
%understanding patches and debugging their effects---and their
%interplay with the code they're based on---\emph{enormously} easier.
%Since every applied patch has an associated changeset, you can use
%\hgcmdargs{log}{\emph{filename}} to see which changesets and patches
%affected a file.  You can use the \hgext{bisect} command to
%binary-search through all changesets and applied patches to see where
%a bug got introduced or fixed.  You can use the \hgcmd{annotate}
%command to see which changeset or patch modified a particular line of
%a source file.  And so on.

例えば，リビジョンコントロールへのパッチの統合は，パッチを理解し，その影
響，依って立つベースコードとの相互作用をデバッグすることを可能にする．適
用されたパッチは，関連づけられたチェンジセットを持つため，
\hgcmdargs{log}{\emph{filename}}によってどのチェンジセットとパッチがファ
イルに影響を与えているか調べることができる．\hgext{bisect}コマンドで全て
のチェンジセットと適用されたパッチに対してバイナリサーチを行い，どこで
バグが混入したか，あるいは修正されたかを調べることができる．
\hgcmd{annotate}コマンドでどのチェンジセットかパッチがソースファイルの特
定の行を変更したか見ることができる．


%\section{Understanding patches}
\section{パッチとは何か}
\label{sec:mq:patch}

%Because MQ doesn't hide its patch-oriented nature, it is helpful to
%understand what patches are, and a little about the tools that work
%with them.

MQはパッチ指向である性質を隠蔽していないので，パッチが何であるか，ツール
がパッチをどう扱うかを理解するのはたやすい．

%The traditional Unix \command{diff} command compares two files, and
%prints a list of differences between them. The \command{patch} command
%understands these differences as \emph{modifications} to make to a
%file.  Take a look at figure~\ref{ex:mq:diff} for a simple example of
%these commands in action.

Unixの伝統的な\command{diff}コマンドは2つのファイルを比較し，差分のリス
トを出力する．\command{patch}コマンドはこの差分を変更と解釈し，ファイル
に及ぼす．図~\ref{ex:mq:diff}にこれらのコマンドの動作を示す．

\begin{figure}[ht]
  \interaction{mq.dodiff.diff}
%  \caption{Simple uses of the \command{diff} and \command{patch}
 %  commands}
  \caption{\command{diff}コマンドと\command{patch}コマンドの単純な使用例}
  \label{ex:mq:diff}
\end{figure}

%The type of file that \command{diff} generates (and \command{patch}
%takes as input) is called a ``patch'' or a ``diff''; there is no
%difference between a patch and a diff.  (We'll use the term ``patch'',
%since it's more commonly used.)

\command{diff}が生成する（また\command{patch}が入力に取る）ファイルの種
類は``patch''または``diff''と呼ばれ，これらの間には違いはない．（以下で
は，より多く使われている``patch''という言葉を使うことにする．）

%A patch file can start with arbitrary text; the \command{patch}
%command ignores this text, but MQ uses it as the commit message when
%creating changesets.  To find the beginning of the patch content,
%\command{patch} searches for the first line that starts with the
%string ``\texttt{diff~-}''.

パッチファイルは任意のテキストで始まる．\command{patch}コマンドはこのテ
キストを無視するが，MQはチェンジセットを作る際のコミットメッセージとして
利用する．パッチ内容の先頭を見つけるために\command{patch}は
``\texttt{diff~-}''で始まる最初の行をサーチする．

%MQ works with \emph{unified} diffs (\command{patch} can accept several
%other diff formats, but MQ doesn't).  A unified diff contains two
%kinds of header.  The \emph{file header} describes the file being
%modified; it contains the name of the file to modify.  When
%\command{patch} sees a new file header, it looks for a file with that
%name to start modifying.

MQ\emph{unified} diffs形式を使う．（\command{patch}コマンドはこれ以外に何
種類かのdiffフォーマットを受け付けるが，MQでは利用できない．）unified
diffは2種類のヘッダを持つ．\emph{file ヘッダ}は変更されているファイルを記
述する．\command{patch}コマンドは，新しいファイルヘッダを見つけると，そこ
に記述されているファイル名を持つファイルを探す．

%After the file header comes a series of \emph{hunks}.  Each hunk starts
%with a header; this identifies the range of line numbers within the file
%that the hunk should modify.  Following the header, a hunk starts and
%ends with a few (usually three) lines of text from the unmodified file;
%these are called the \emph{context} for the hunk.If
%there's only a small amount of context between successive hunks,
%\command{diff} doesn't print a new hunk header; it just runs the hunks
%together, with a few lines of context between modifications.

ファイルヘッダの後には一連の\emph{hunks}が続く．各々のhunkはヘッダで始ま
る．このヘッダはファイル内でhunkが改変すべき行番号の範囲を識別するのに使
われる．ヘッダに続き，hunkは数行（通常3）の改変されていないファイルからの
行がある．これらはhunkの\emph{コンテキスト}と呼ばれる．もし連続するhunkの
間にコンテキストが少ししかなければ，\command{diff}は新たなhunkヘッダを出
力せず，各々のhunkと間のコンテキストを合わせて出力する．

%Each line of context begins with a space character.  Within the hunk,
%a line that begins with ``\texttt{-}'' means ``remove this line,''
%while a line that begins with ``\texttt{+}'' means ``insert this
%line.''  For example, a line that is modified is represented by one
%deletion and one insertion.

コンテキストの各行は，空白文字で始まる．hunk内では行は``\texttt{-}''で始
まる．これは``この行を削除せよ''を意味する．
一方，``\texttt{+}''で始まる行は，``この行を挿入せよ''を意味する．例を挙
げると，変更された行は1つの削除と1つの挿入で表される．

%We will return to some of the more subtle aspects of patches later (in
%section~\ref{sec:mq:adv-patch}), but you should have enough information
%now to use MQ.

パッチの些細な点については後で（~\ref{sec:mq:adv-patch}）また触れるが，
これまでで，MQを使うのに十分な情報は述べた．

%\section{Getting started with Mercurial Queues}
\section{Mercurial Queuesを使ってみる}
\label{sec:mq:start}

%Because MQ is implemented as an extension, you must explicitly enable
%before you can use it.  (You don't need to download anything; MQ ships
%with the standard Mercurial distribution.)  To enable MQ, edit your
%\tildefile{.hgrc} file, and add the lines in figure~\ref{ex:mq:config}.

MQはエクステンションとして実装されているので，使う前に明示的に有効にする
必要がある．（何もダウンロードする必要はない．MQは通常のMercurialに同梱さ
れている）MQを有効にするには\tildefile{.hgrc}ファイルを編集し，
図~\ref{ex:mq:config}のように設定を追加する．

\begin{figure}[ht]
  \begin{codesample4}
    [extensions]
    hgext.mq =
  \end{codesample4}
  \label{ex:mq:config}
%  \caption{Contents to add to \tildefile{.hgrc} to enable the MQ
 %  extension}
  \caption{MQエクステンションを有効にするために\tildefile{.hgrc}に追加する内容}
\end{figure}

%Once the extension is enabled, it will make a number of new commands
%available.  To verify that the extension is working, you can use
%\hgcmd{help} to see if the \hgxcmd{mq}{qinit} command is now available; see
%the example in figure~\ref{ex:mq:enabled}.

エクステンションが有効化されると一連のコマンドが利用可能になる．エクステ
ンションが有効であることを確認するためには，\hgcmd{help}で
\hgxcmd{mq}{qinit}があることを確認する．図~\ref{ex:mq:enabled}の例を参照
されたい．

\begin{figure}[ht]
  \interaction{mq.qinit-help.help}
%  \caption{How to verify that MQ is enabled}
  \caption{MQが有効であることの確認法}
  \label{ex:mq:enabled}
\end{figure}

%You can use MQ with \emph{any} Mercurial repository, and its commands
%only operate within that repository.  To get started, simply prepare
%the repository using the \hgxcmd{mq}{qinit} command (see
%figure~\ref{ex:mq:qinit}).  This command creates an empty directory
%called \sdirname{.hg/patches}, where MQ will keep its metadata.  As
%with many Mercurial commands, the \hgxcmd{mq}{qinit} command prints nothing
%if it succeeds.

MQは\emph{あらゆる}Mercurialリポジトリで使うことができ，そのコマンドは各々
のリポジトリの中にだけ作用する．始めるために\hgxcmd{mq}{qinit}コマンドで
リポジトリを用意する．（図~\ref{ex:mq:qinit}を参照） このコマンドはMQがメ
タデータを保存するための\sdirname{.hg/patches}という名前の空のディレクト
リを作成する．他のMercurialコマンドと同様に，\hgxcmd{mq}{qinit}コマンド
も成功すると何も表示しない．

\begin{figure}[ht]
  \interaction{mq.tutorial.qinit}
%  \caption{Preparing a repository for use with MQ}
  \caption{MQを使うためにリポジトリを準備する}
  \label{ex:mq:qinit}
\end{figure}

\begin{figure}[ht]
  \interaction{mq.tutorial.qnew}
%  \caption{Creating a new patch}
  \caption{新しいパッチの作成}
  \label{ex:mq:qnew}
\end{figure}

%\subsection{Creating a new patch}
\subsection{新しいパッチの作成}

%To begin work on a new patch, use the \hgxcmd{mq}{qnew} command.  This
%command takes one argument, the name of the patch to create.  MQ will
%use this as the name of an actual file in the \sdirname{.hg/patches}
%directory, as you can see in figure~\ref{ex:mq:qnew}.

新しいパッチを扱う時は\hgxcmd{mq}{qnew}コマンドを使う．このコマンドは作成
されるパッチの名前として引数を1つ取る．図~\ref{ex:mq:qnew}のように，MQは
これを\sdirname{.hg/patches} ディレクトリ内の実際のファイル名として利用す
る．

%Also newly present in the \sdirname{.hg/patches} directory are two
%other files, \sfilename{series} and \sfilename{status}.  The
%\sfilename{series} file lists all of the patches that MQ knows about
%for this repository, with one patch per line.Mercurial uses the
%\sfilename{status} file for internal book-keeping; it tracks all of the
%patches that MQ has \emph{applied} in this repository.

\sdirname{.hg/patches}ディレクトリの中には，\sfilename{series}と
\sfilename{status}という2つのファイルも新しく作られる．
\sfilename{series}ファイルはMQが関知する，このリポジトリ内の全てのパッチ
のリストがあり，1行に1つのパッチが記述されている．Mercurialは
\sfilename{status}ファイルを内部の管理に用いる．このファイルはリポジトリ
内でMQが適用した全てのパッチが記録されている．

%\begin{note}
%  You may sometimes want to edit the \sfilename{series} file by hand;
%  for example, to change the sequence in which some patches are
%  applied.  However, manually editing the \sfilename{status} file is
%  almost always a bad idea, as it's easy to corrupt MQ's idea of what
%  is happening.
%\end{note}

\begin{note}
 例えば，複数のパッチが適用される手順を変更するなどの目的で
 \sfilename{series}ファイルを手で編集したくなることがあるかもしれない．
 しかし\sfilename{status}を手で編集するのはほとんどの場合良くない考えで，
 MQの状態追跡を簡単に狂わせてしまう．
\end{note}

%Once you have created your new patch, you can edit files in the
%working directory as you usually would.  All of the normal Mercurial
%commands, such as \hgcmd{diff} and \hgcmd{annotate}, work exactly as
%they did before.

新しいパッチを作った後，ワーキングディレクトリ内のファイルを通常通り編集
することができる．\hgcmd{diff}や\hgcmd{annotate}のような全ての通常の
Mercurialコマンドが全く同じように使える．

%\subsection{Refreshing a patch}
\subsection{パッチのリフレッシュ}

%When you reach a point where you want to save your work, use the
%\hgxcmd{mq}{qrefresh} command (figure~\ref{ex:mq:qnew}) to update the patch
%you are working on.  This command folds the changes you have made in
%the working directory into your patch, and updates its corresponding
%changeset to contain those changes.

作業内容をセーブするポイントに差しかかったら，\hgxcmd{mq}{qrefresh}コマ
ンドを使って（図~\ref{ex:mq:qnew}）作業中のパッチを更新する．このコマン
ドはワーキングディレクトリの差分をパッチに取り込み，チェンジセットが変更
を含むように更新する．

\begin{figure}[ht]
  \interaction{mq.tutorial.qrefresh}
%  \caption{Refreshing a patch}
  \caption{パッチのリフレッシュ}
  \label{ex:mq:qrefresh}
\end{figure}

%You can run \hgxcmd{mq}{qrefresh} as often as you like, so it's a good way
%to ``checkpoint'' your work.  Refresh your patch at an opportune
%time; try an experiment; and if the experiment doesn't work out,
%\hgcmd{revert} your modifications back to the last time you refreshed.

\hgxcmd{mq}{qrefresh}はいつでも好きな時に実行でき，作業の状態保存をする
のにも使える．パッチのリフレッシュは都合のよい時に行えばよい．実験的なコー
ドを動かす場合，事前にリフレッシュをしておけば，実験の結果コードが動かな
くても，\hgcmd{revert}すれば，変更は元に戻る．

\begin{figure}[ht]
  \interaction{mq.tutorial.qrefresh2}
%  \caption{Refresh a patch many times to accumulate changes}
  \caption{パッチのリフレッシュで変更を蓄積する}
  \label{ex:mq:qrefresh2}
\end{figure}

%\subsection{Stacking and tracking patches}
\subsection{パッチのスタックと追跡}

%Once you have finished working on a patch, or need to work on another,
%you can use the \hgxcmd{mq}{qnew} command again to create a new patch.
%Mercurial will apply this patch on top of your existing patch.  See
%figure~\ref{ex:mq:qnew2} for an example.  Notice that the patch
%contains the changes in our prior patch as part of its context (you
%can see this more clearly in the output of \hgcmd{annotate}).

パッチへの作業が終了したり，他の作業ををする必要がある場合，
\hgxcmd{mq}{qnew}コマンドを実行し，新しいパッチを作ることができる．
Mercurialはこのパッチを既存のパッチの上から適用する．図~\ref{ex:mq:qnew2}を
参照のこと．パッチは先行するパッチの変更をコンテキストとして持つ．（\hgcmd{annotate}
の出力でより明瞭に確認することができる．）

\begin{figure}[ht]
  \interaction{mq.tutorial.qnew2}
%  \caption{Stacking a second patch on top of the first}
  \caption{最初のパッチの上に2番目のパッチをスタックする}
  \label{ex:mq:qnew2}
\end{figure}

%So far, with the exception of \hgxcmd{mq}{qnew} and
%\hgxcmd{mq}{qrefresh}, we've been careful to only use regular Mercurial
%commands.  However, MQ provides many commands that are easier to use
%when you are thinking about patches, as illustrated in
%figure~\ref{ex:mq:qseries}:

これまでは\hgxcmd{mq}{qnew}と\hgxcmd{mq}{qrefresh}を除いて，通常の
Mercurialコマンドのみを使うように注意してきた．しかしMQはパッチを扱う場
合，図~\ref{ex:mq:qseries}に示すようなより簡単なコマンドを用意している．

%\begin{itemize}
%\item The \hgxcmd{mq}{qseries} command lists every patch that MQ knows
%  about in this repository, from oldest to newest (most recently
%  \emph{created}).
%\item The \hgxcmd{mq}{qapplied} command lists every patch that MQ has
%  \emph{applied} in this repository, again from oldest to newest (most
%  recently applied).
%\end{itemize}

\begin{itemize}
\item \hgxcmd{mq}{qseries}コマンドはMQが関知するリポジトリ内のパッチ全て
      を古いものから新しく\emph{作成された}ものの順にリスト表示する．
\item \hgxcmd{mq}{qapplied}コマンドはMQが\emph{適用した}リポジトリ内の
      パッチ全てをやはり古いものから新しく\emph{作成された}ものの順にリスト表示する．
\end{itemize}

\begin{figure}[ht]
  \interaction{mq.tutorial.qseries}
%  \caption{Understanding the patch stack with \hgxcmd{mq}{qseries} and
%    \hgxcmd{mq}{qapplied}}
  \caption{\hgxcmd{mq}{qseries}と\hgxcmd{mq}{qapplied}でパッチスタックを
 調べる}
  \label{ex:mq:qseries}
\end{figure}


%\subsection{Manipulating the patch stack}
\subsection{パッチスタックの操作}

%The previous discussion implied that there must be a difference
%between ``known'' and ``applied'' patches, and there is.  MQ can
%manage a patch without it being applied in the repository.

これまでの議論は``known''と``applied''パッチに違いがあることを暗黙に仮定
していた．MQは差異のないパッチをリポジトリに対して適用することもできる．

%An \emph{applied} patch has a corresponding changeset in the
%repository, and the effects of the patch and changeset are visible in
%the working directory.  You can undo the application of a patch using
%the \hgxcmd{mq}{qpop} command.  MQ still \emph{knows about}, or manages, a
%popped patch, but the patch no longer has a corresponding changeset in
%the repository, and the working directory does not contain the changes
%made by the patch.  Figure~\ref{fig:mq:stack} illustrates the
%difference between applied and tracked patches.

\emph{適用された}パッチはリポジトリ内に対応するチェンジセットを持ち，パッ
チの効果とチェンジセットはワーキングディレクトリ内で見ることができる．パッ
チの適用は\hgxcmd{mq}{qpop}コマンドで取り消すことができる．ポップされたパッ
チは対応するチェンジセットを持たず，変更もワーキングディレクトリに残って
いないが，MQはポップされたパッチを依然として記憶し，管理している．
図~\ref{fig:mq:stack}は適用されたパッチと管理されているパッチの違いを示
す．

\begin{figure}[ht]
  \centering
  \grafix{mq-stack}
%  \caption{Applied and unapplied patches in the MQ patch stack}
  \caption{MQパッチスタックの中の適用されたパッチと適用されないパッチ}
  \label{fig:mq:stack}
\end{figure}

%You can reapply an unapplied, or popped, patch using the \hgxcmd{mq}{qpush}
%command.  This creates a new changeset to correspond to the patch, and
%the patch's changes once again become present in the working
%directory.  See figure~\ref{ex:mq:qpop} for examples of \hgxcmd{mq}{qpop}
%and \hgxcmd{mq}{qpush} in action.  Notice that once we have popped a patch
%or two patches, the output of \hgxcmd{mq}{qseries} remains the same, while
%that of \hgxcmd{mq}{qapplied} has changed.

適用を外したパッチやポップしたパッチを\hgxcmd{mq}{qpush}コマンドで再適用
することができる．このコマンドは，パッチに対応した新しいチェンジセットを
作り，パッチによる変更はもう一度ワーキングディレクトリに現れる．
\hgxcmd{mq}{qpop}と\hgxcmd{mq}{qpush}の使用例を図~\ref{ex:mq:qpop}に示す．
1つまたは複数のパッチをポップすると\hgxcmd{mq}{qapplied}の出力は変化する
が，\hgxcmd{mq}{qseries}の出力は同じまま残るのに注意されたい．

\begin{figure}[ht]
  \interaction{mq.tutorial.qpop}
%  \caption{Modifying the stack of applied patches}
  \caption{適用されたパッチのスタックを変更する}
  \label{ex:mq:qpop}
\end{figure}

%\subsection{Pushing and popping many patches}
\subsection{パッチのプッシュとポップ}

%While \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} each operate on a single patch at
%a time by default, you can push and pop many patches in one go.  The
%\hgxopt{mq}{qpush}{-a} option to \hgxcmd{mq}{qpush} causes it to push all
%unapplied patches, while the \hgxopt{mq}{qpop}{-a} option to \hgxcmd{mq}{qpop}
%causes it to pop all applied patches.  (For some more ways to push and
%pop many patches, see section~\ref{sec:mq:perf} below.)

\hgxcmd{mq}{qpush}と\hgxcmd{mq}{qpop}は一度に各々のパッチ一つずつを操作す
る（これはデフォルト動作である）一方，複数のパッチを一度にポップ・プッシュ
する操作もある．\hgxcmd{mq}{qpush}コマンドの\hgxopt{mq}{qpush}{-a}オプショ
ンは，未適用のパッチ全体をプッシュし，\hgxcmd{mq}{qpop}コマンドの
\hgxopt{mq}{qpop}{-a} オプションは適用済みのパッチ全体をポップする．
（他の複数のパッチを同時にプッシュ・ポップする方法については下
の~\ref{sec:mq:perf}を参照のこと）

\begin{figure}[ht]
  \interaction{mq.tutorial.qpush-a}
%  \caption{Pushing all unapplied patches}
  \caption{適用されていないパッチを全てプッシュする}
  \label{ex:mq:qpush-a}
\end{figure}

%\subsection{Safety checks, and overriding them}
\subsection{安全性チェックとオーバライド}

%Several MQ commands check the working directory before they do
%anything, and fail if they find any modifications.  They do this to
%ensure that you won't lose any changes that you have made, but not yet
%incorporated into a patch.Figure~\ref{ex:mq:add} illustrates this;
%the \hgxcmd{mq}{qnew} command will not create a new patch if there are
%outstanding changes, caused in this case by the \hgcmd{add} of
%\filename{file3}.

いくつかのMQコマンドは，実行時にまずワーキングディレクトリをチェックし，
変更がなされていたら終了するようになっている．これは，ユーザのまだパッチ
に取り込まれていない変更が失われないようにするためである．
図~\ref{ex:mq:add}はこれを説明したもので，\hgxcmd{mq}{qnew}コマンドは孤立
した変更がある時に新たなパッチを生成しない．この例では，変更は
\hgcmd{add}による\filename{file3}の追加によって生まれている．

\begin{figure}[ht]
  \interaction{mq.tutorial.add}
%  \caption{Forcibly creating a patch}
  \caption{パッチの強制的な生成}
  \label{ex:mq:add}
\end{figure}

%Commands that check the working directory all take an ``I know what
%I'm doing'' option, which is always named \option{-f}.  The exact
%meaning of \option{-f} depends on the command.  For example,
%\hgcmdargs{qnew}{\hgxopt{mq}{qnew}{-f}} will incorporate any outstanding
%changes into the new patch it creates, but
%\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-f}} will revert modifications to any
%files affected by the patch that it is popping.  Be sure to read the
%documentation for a command's \option{-f} option before you use it!

ワーキングディレクトリのチェックを行うコマンドは全て，上級者向けの強制
オプション\option{-f}を持っている．\option{-f}の厳密な意味は，コマンドに
よって異なる．例えば\hgcmdargs{qnew}{\hgxopt{mq}{qnew}{-f}}は孤立した変
更を新しいパッチに取り込むという意味だが，
\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-f}}は，ポップするパッチによるあらゆ
るファイルへの変更を取り消すという意味になる．\option{-f}オプションを使
う時は必ず事前にコマンドのドキュメントを読んで確認するようにして欲しい．

%\subsection{Working on several patches at once}
\subsection{複数のパッチを一度に扱う}

%The \hgxcmd{mq}{qrefresh} command always refreshes the \emph{topmost}
%applied patch.  This means that you can suspend work on one patch (by
%refreshing it), pop or push to make a different patch the top, and
%work on \emph{that} patch for a while.

\hgxcmd{mq}{qrefresh}コマンドは\emph{最も上}に適用されたパッチに対してリ
フレッシュを行う．これはリフレッシュによって1つのパッチに現在の作業をサ
スペンドしたり，別のトップパッチや一時的に作業するためパッチを作るために
ポップやプッシュができるということを意味する．

%Here's an example that illustrates how you can use this ability.
%Let's say you're developing a new feature as two patches.  The first
%is a change to the core of your software, and the second---layered on
%top of the first---changes the user interface to use the code you just
%added to the core.  If you notice a bug in the core while you're
%working on the UI patch, it's easy to fix the core.  Simply
%\hgxcmd{mq}{qrefresh} the UI patch to save your in-progress changes, and
%\hgxcmd{mq}{qpop} down to the core patch.  Fix the core bug,
%\hgxcmd{mq}{qrefresh} the core patch, and \hgxcmd{mq}{qpush} back to the UI
%patch to continue where you left off.

この機能の使い方を示す例を示す．2つのパッチとして新しい機能を開発している
とする．最初のものはあなたのソフトウェアのコアを変更し，2番目のものは1番
目のものの上に展開する，今追加したコアのコードを使ったユーザインタフェー
スだとする．UIパッチで作業中にコアのバグに気付いたとすると，簡単にコアの
修正は行える．単純に\hgxcmd{mq}{qrefresh}によって進行中のUIパッチをセー
ブし，\hgxcmd{mq}{qpop}によってコアパッチへ遡る．コアのバグを修正した後
に\hgxcmd{mq}{qrefresh}をコアパッチについて行い，\hgxcmd{mq}{qpush}で
UIパッチに戻って作業を続ける．

%\section{More about patches}
\section{さらにパッチについて}
\label{sec:mq:adv-patch}

%MQ uses the GNU \command{patch} command to apply patches, so it's
%helpful to know a few more detailed aspects of how \command{patch}
%works, and about patches themselves.

MQはパッチの適用にGNUの\command{patch}コマンドを用いる．そのため，
\command{patch}の動作とパッチ自体についてより詳しく知っておくことは有用
である．

%\subsection{The strip count}
\subsection{ストリップカウント}

%If you look at the file headers in a patch, you will notice that the
%pathnames usually have an extra component on the front that isn't
%present in the actual path name.  This is a holdover from the way that
%people used to generate patches (people still do this, but it's
%somewhat rare with modern revision control tools).

パッチのファイルヘッダを見ると，パスネームの最初に追加の部分がついている
のに気づくはずだ．これは実際のパスネームには存在しないもので，パッチを生
成する時の習慣からの遺物である．（多くの人がいまだこの方法を使っているが，
近代的なリビジョンコントロールツールではほとんど見られない．）

%Alice would unpack a tarball, edit her files, then decide that she
%wanted to create a patch.  So she'd rename her working directory,
%unpack the tarball again (hence the need for the rename), and use the
%\cmdopt{diff}{-r} and \cmdopt{diff}{-N} options to \command{diff} to
%recursively generate a patch between the unmodified directory and the
%modified one.
%The result would be that the name of the unmodified
%directory would be at the front of the left-hand path in every file
%header, and the name of the modified directory would be at the front
%of the right-hand path.

アリスがtarアーカイブを展開し，ファイルを編集し，パッチを作りたいと思って
いるとする．彼女は差分を取るためにまず作業しているディレクトリをリネーム
し， tarアーカイブをもう一度展開する．そしてオリジナルのままのディレクト
リと，変更を行なったディレクトリの間で，そして\command{diff}に
\cmdopt{diff}{-r}と\cmdopt{diff}{-N}オプションを付けて，再帰的な差分を取
り，パッチを生成するだろう．生成されたパッチファイルを見ると，各ファイル
のヘッダ部分で左辺値の先頭にオリジナルの方のディレクトリ名が現れ，右辺値
の先頭に変更した方のディレクトリ名が現れているはずである．

%Since someone receiving a patch from the Alices of the net would be
%unlikely to have unmodified and modified directories with exactly the
%same names, the \command{patch} command has a \cmdopt{patch}{-p}
%option that indicates the number of leading path name components to
%strip when trying to apply a patch.  This number is called the
%\emph{strip count}.

ネット上の多数のアリスたちからパッチを受け取った人は，変更なしのディレク
トリと変更されたディレクトリの両方をアリスと同じ名前で持っている可能性は
まずない．\command{patch}コマンドには\cmdopt{patch}{-p}オプションがあり，
パッチを適用する時にパスの要素を先頭からいくつ削るかを指定できる．この数
は\emph{ストリップカウント}と呼ばれる．

%An option of ``\texttt{-p1}'' means ``use a strip count of one''.  If
%\command{patch} sees a file name \filename{foo/bar/baz} in a file
%header, it will strip \filename{foo} and try to patch a file named
%\filename{bar/baz}.  (Strictly speaking, the strip count refers to the
%number of \emph{path separators} (and the components that go with them
%) to strip.  A strip count of one will turn \filename{foo/bar} into
%\filename{bar}, but \filename{/foo/bar} (notice the extra leading
%slash) into \filename{foo/bar}.)

オプション``\texttt{-p1}''は``ストリップカウント1を使う''という意味であ
る．もし\command{patch}がファイルヘッダに\filename{foo/bar/baz}を見つけ
た時は，\filename{foo}を落して\filename{bar/baz}という名前のファイルにパッ
チを試みる．（厳密に言うとストリップカウントは\emph{パスセパレータ}の数
を参照している（結果として要素も参照される）ストリップカウント1は
\filename{foo/bar}を\filename{bar}に変える．また\filename{/foo/bar}（前
に置かれたスラッシュに注意）は\filename{foo/bar}となる．）

%The ``standard'' strip count for patches is one; almost all patches
%contain one leading path name component that needs to be stripped.
%Mercurial's \hgcmd{diff} command generates path names in this form,
%and the \hgcmd{import} command and MQ expect patches to have a strip
%count of one.

パッチへの``標準的な''ストリップカウントは1である．ほとんど全てのパッチ
は取り除くべきパス要素を一つ持っている．Mercurialの\hgcmd{diff}コマンド
はパス名をこの形式で生成し，\hgcmd{import}コマンドとMQはストリップカウン
ト1を前提としている．

%If you receive a patch from someone that you want to add to your patch
%queue, and the patch needs a strip count other than one, you cannot
%just \hgxcmd{mq}{qimport} the patch, because \hgxcmd{mq}{qimport} does not yet
%have a \texttt{-p} option (see~\bug{311}).  Your best bet is to
%\hgxcmd{mq}{qnew} a patch of your own, then use \cmdargs{patch}{-p\emph{N}}
%to apply their patch, followed by \hgcmd{addremove} to pick up any
%files added or removed by the patch, followed by \hgxcmd{mq}{qrefresh}.
%This complexity may become unnecessary; see~\bug{311} for details.

誰かからパッチを受け取り，パッチキューに追加するとき，ストリップカウント
が1以外であれば単に\hgxcmd{mq}{qimport}することはできない．これは
\hgxcmd{mq}{qimport}コマンドがまだ\texttt{-p}オプションを持っていないため
だ（\bug{311}を参照）．最も上手くいきそうな方法は，\hgxcmd{mq}{qnew}で新
たにパッチを作り，\cmdargs{patch}{-p\emph{N}}を実行して受け取ったパッチを
適用した後，パッチによって追加されたり削除されたファイルを
\hgcmd{addremove}によってピックアップし，\hgxcmd{mq}{qrefresh}を実行する
ことである．この複雑な手順は将来的には必要なくなるはずだ（\bug{311}を参
照）．

%\subsection{Strategies for applying a patch}
\subsection{パッチ適用のための戦略}

%When \command{patch} applies a hunk, it tries a handful of
%successively less accurate strategies to try to make the hunk apply.
%This falling-back technique often makes it possible to take a patch
%that was generated against an old version of a file, and apply it
%against a newer version of that file.

\command{patch}がhunkを適用するとき，いくつかのあまり正確でない戦略を続け
て用いる．このフォールバック手法によって，古いバージョンのファイルに対し
て作成したパッチを新しいファイルに適用することさえしばしば可能となる．

%First, \command{patch} tries an exact match, where the line numbers,
%the context, and the text to be modified must apply exactly.  If it
%cannot make an exact match, it tries to find an exact match for the
%context, without honouring the line numbering information.  If this
%succeeds, it prints a line of output saying that the hunk was applied,
%but at some \emph{offset} from the original line number.

最初に，\command{patch}は行番号，コンテキスト，変更されるテキストの正確な
マッチを試みる．正確なマッチができない場合，行番号を無視してコンテキスト
の正確なマッチを試みる．これが成功すれば，hunkが適用されたが，\emph{オフ
セット}が生じたというメッセージを表示する．

%If a context-only match fails, \command{patch} removes the first and
%last lines of the context, and tries a \emph{reduced} context-only
%match.  If the hunk with reduced context succeeds, it prints a message
%saying that it applied the hunk with a \emph{fuzz factor} (the number
%after the fuzz factor indicates how many lines of context
%\command{patch} had to trim before the patch applied).

コンテキストのみのマッチが失敗すると，\command{patch}はコンテキストの最初
と最後の行を削り，コンテキストの\emph{縮小}マッチを試みる．縮小コンテキス
トによるhunkが成功すると，hunkが適用されたことと\emph{fuzz ファクター}を
含むメッセージを表示する．（fuzzファクターの後ろの数字は，
\command{patch}コマンドが，パッチを適用する前にコンテキストの何行を削除す
る必要があったのかを示す．）

%When neither of these techniques works, \command{patch} prints a message
%saying that the hunk in question was rejected.  It saves rejected hunks
%(also simply called ``rejects'') to a file with the same name, and an
%added \sfilename{.rej} extension.  It also saves an unmodified copy of
%the file with a \sfilename{.orig} extension; the copy of the file
%without any extensions will contain any changes made by hunks that
%\emph{did} apply cleanly.  If you have a patch that modifies
%\filename{foo} with six hunks, and one of them fails to apply, you will
%have: an unmodified \filename{foo.orig}, a \filename{foo.rej} containing
%one hunk, and \filename{foo}, containing the changes made by the five
%successful five hunks.

どちらも上手くいかなかった場合，\command{patch}はhunkがリジェクトされたと
いうメッセージを表示する．コマンドはリジェクトされたhunk（あるいは単に
``rejects''）を同名で拡張子\sfilename{.rej}のファイルにセーブする．コマン
ドは同時に無変更のファイルを\sfilename{.orig}という拡張子でセーブする。拡
張子のないファイルのコピーは，hunkからクリーンに適用された変更を全て含む．
\filename{foo}というファイルを変更する6つのhunkを含むパッチファイルがあり，
その内の1つが適用できなかったとすると，無変更のファイル
\filename{foo.orig}，hunk1つを含むファイル\filename{foo.rej}，正しく適用
された5つのhunkを含むファイル\filename{foo}が生成される．

%\subsection{Some quirks of patch representation}
\subsection{パッチ表現の奇妙な点}

%There are a few useful things to know about how \command{patch} works
%with files.
%\begin{itemize}
%\item This should already be obvious, but \command{patch} cannot
%  handle binary files.
%\item Neither does it care about the executable bit; it creates new
%  files as readable, but not executable.
%\item \command{patch} treats the removal of a file as a diff between
%  the file to be removed and the empty file.  So your idea of ``I
%  deleted this file'' looks like ``every line of this file was
%  deleted'' in a patch.
%\item It treats the addition of a file as a diff between the empty
%  file and the file to be added.  So in a patch, your idea of ``I
%  added this file'' looks like ``every line of this file was added''.
%\item It treats a renamed file as the removal of the old name, and the
%  addition of the new name.  This means that renamed files have a big
%  footprint in patches.  (Note also that Mercurial does not currently
%  try to infer when files have been renamed or copied in a patch.)
%\item \command{patch} cannot represent empty files, so you cannot use
%  a patch to represent the notion ``I added this empty file to the
%  tree''.
%\end{itemize}

\command{patch}がファイルにどのように作用するか，有用な点をいくつか述べ
る．
\begin{itemize}
 \item すでに明白だが，\command{patch}はバイナリファイルを扱うことはでき
       ない．
 \item 実行ビットを考慮しないだけでなく，新しいファイルを読み取り可能属
       性で作成し，実行可能属性は付けない．
 \item \command{patch}コマンドはファイルの削除を削除されるファイルと中身
       が空のファイルとの差分として扱う．従って，ファイルを削除するとい
       うことは，パッチファイルの中ではファイルの中の全ての行を削除するこ
       とと等価である．
 \item \command{patch}コマンドはファイルの追加を空のファイルと追加される
       ファイルの差分として扱う．従ってファイルの追加はパッチファイルの中
       ではファイルに全ての行を追加することと等価である．
 \item \command{patch}コマンドは名前の変更されたファイルを旧名のファイル
       の削除と新しいファイルの追加として扱う．従って名前の変更されたファ
       イルはパッチ内で大きなフットプリントを占める．（Mercurialは現在の
       ところ，パッチ内でファイルがリネームされたのか，コピーされたのか
       を関知しない）
 \item \command{patch}コマンドは中身の空のファイルを表現できない．従って
       パッチファイルを「空のファイルをツリーに追加する」という用途に使
       うことはできない．
\end{itemize}

%\subsection{Beware the fuzz}
\subsection{曖昧な点について}

%While applying a hunk at an offset, or with a fuzz factor, will often
%be completely successful, these inexact techniques naturally leave
%open the possibility of corrupting the patched file.  The most common
%cases typically involve applying a patch twice, or at an incorrect
%location in the file. If \command{patch} or \hgxcmd{mq}{qpush} ever
%mentions an offset or fuzz factor, you should make sure that the
%modified files are correct afterwards.  

あるオフセットやfuzz factorの位置へのhunkの適用は，多くの場合問題なく成功
するが，不正確なマッチを用いた場合，パッチを適用したファイルを壊している
可能性が残る．最もよくあるのは，パッチを二度適用したり，ファイルの間違っ
た場所に適用してしまうことだ．\command{patch}または\hgxcmd{mq}{qpush}がオ
フセットかfuzzファクターを表示している合，変更されたファイルが正常である
か確認する必要がある．

%It's often a good idea to refresh a patch that has applied with an
%offset or fuzz factor; refreshing the patch generates new context
%information that will make it apply cleanly.  I say ``often,'' not
%``always,'' because sometimes refreshing a patch will make it fail to
%apply against a different revision of the underlying files.  In some
%cases, such as when you're maintaining a patch that must sit on top of
%multiple versions of a source tree, it's acceptable to have a patch
%apply with some fuzz, provided you've verified the results of the
%patching process in such cases.

オフセットやfuzz factorの出たパッチをリフレッシュするのは多くの場合良い考
えである．パッチをリフレッシュすると，新しいコンテキスト情報が生成され，
パッチがクリーンに適用できるようになる．「常に」ではなく「多くの場合」と
断ったのは，パッチをリフレッシュすることで，元のファイルの異なったリビジョ
ンでパッチが適用できなくなることがあるからだ．複数のバージョンのソースツ
リーの上で適用可能なパッチを管理しなければならないような場合などは，パッ
チの結果を検証してあるのであればfuzzの出るパッチも許容され得る．

%\subsection{Handling rejection}
\subsection{リジェクトの取り扱い}

%If \hgxcmd{mq}{qpush} fails to apply a patch, it will print an error
%message and exit.  If it has left \sfilename{.rej} files behind, it is
%usually best to fix up the rejected hunks before you push more patches
%or do any further work.

\hgxcmd{mq}{qpush}はパッチの適用に失敗した場合，エラーメッセージを表示し
て終了する．\sfilename{.rej}ファイルが作られている場合は，通常，さらなる
パッチの追加や新しい作業の前にリジェクトされたhunkについて修正を行うべき
である．

%If your patch \emph{used to} apply cleanly, and no longer does because
%you've changed the underlying code that your patches are based on,
%Mercurial Queues can help; see section~\ref{sec:mq:merge} for details.

それまでパッチがクリーンに適用されており，パッチの対象になっているコード
に変更を加えたために適用できなくなったのなら，Mercurial Queuesの支援を受
けることができる．詳しい情報はセクション~\ref{sec:mq:merge}を見て欲しい．

%Unfortunately, there aren't any great techniques for dealing with
%rejected hunks.  Most often, you'll need to view the \sfilename{.rej}
%file and edit the target file, applying the rejected hunks by hand.

残念なことに，リジェクトされたhunkを取り扱う決まった良い方法は存在しな
い．大抵の場合，\sfilename{.rej}ファイルを見てターゲットファイルを編集
し，リジェクトされたhunkを手で適用することになる．

%If you're feeling adventurous, Neil Brown, a Linux kernel hacker,
%wrote a tool called \command{wiggle}~\cite{web:wiggle}, which is more
%vigorous than \command{patch} in its attempts to make a patch apply.

冒険が好きなら，Linux kernerハッカーのNeil Brownが書いた
\command{wiggle}~\cite{web:wiggle}を試してみると良い．このコマンドは
\command{patch}よりも精力的にパッチの適用を試みる．

%Another Linux kernel hacker, Chris Mason (the author of Mercurial
%Queues), wrote a similar tool called
%\command{mpatch}~\cite{web:mpatch}, which takes a simple approach to
%automating the application of hunks rejected by \command{patch}.  The
%\command{mpatch} command can help with four common reasons that a hunk
%may be rejected:

別のLinux kernerハッカー Chris Mason（Mercurial Queuesの作者でもある．）
は\command{mpatch}~\cite{web:mpatch}というツールを書いた．このコマンドは
\command{patch}コマンドでリジェクトされたhunkの適用を自動化す
る．\command{mpatch}コマンドは，hunkがリジェクトされる主な原因4つに対応
する:

\begin{itemize}
%\item The context in the middle of a hunk has changed.
\item hunkの中のコンテキストが変更された
%\item A hunk is missing some context at the beginning or end.
\item hunkの開始部・終端部でコンテキストが見つけられない
%\item A large hunk might apply better---either entirely or in
%  part---if it was broken up into smaller hunks.
\item 大きなhunkはもっと上手に適用できる筈だ---hunkを小さなhunkに分割し
      て適用する
%\item A hunk removes lines with slightly different content than those
%  currently present in the file.
\item hunk内の行が現在ファイルにある行と若干違っている場合，その行を削除
      する
\end{itemize}

%If you use \command{wiggle} or \command{mpatch}, you should be doubly
%careful to check your results when you're done.  In fact,
%\command{mpatch} enforces this method of double-checking the tool's
%output, by automatically dropping you into a merge program when it has
%done its job, so that you can verify its work and finish off any
%remaining merges.

\command{wiggle}または\command{mpatch}を使用した場合は，結果に細心の注意
が必要である．実際には\command{mpatch}はツールの出力で二重チェックを強制
し，動作が終ると自動的にマージプログラムを起動する．これによって作業を確
認し，マージを完了することができる．

%\section{Getting the best performance out of MQ}
\section{MQを最大限に活用する}
\label{sec:mq:perf}

%MQ is very efficient at handling a large number of patches.  I ran
%some performance experiments in mid-2006 for a talk that I gave at the
%2006 EuroPython conference~\cite{web:europython}.  I used as my data
%set the Linux 2.6.17-mm1 patch series, which consists of 1,738
%patches.  I applied these on top of a Linux kernel repository
%containing all 27,472 revisions between Linux 2.6.12-rc2 and Linux
%2.6.17.

MQはとても効率的に大量のパッチを処理することができる．筆者は2006年の中頃，
2006 EuroPython conference~\cite{web:europython}での講演のために性能測定
を行った．測定に用いたデータはLinux 2.6.17-mm1のパッチシリーズで，1,738
のパッチを含む．このパッチをLinux kernelリポジトリに適用した．リポジトリ
はLinux 2.6.12-rc2からLinux 2.6.17までの27,472のリビジョンを含んでいる．

%On my old, slow laptop, I was able to
%\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} all 1,738 patches in 3.5 minutes,
%and \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} them all in 30 seconds.  (On a
%newer laptop, the time to push all patches dropped to two minutes.)  I
%could \hgxcmd{mq}{qrefresh} one of the biggest patches (which made 22,779
%lines of changes to 287 files) in 6.6 seconds.

筆者の古く遅いラップトップで，\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}}で
1738のパッチすべてを処理するのに
3.5分，\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}}を行うのに30秒を要した．(新
しいラップトップではプッシュの所要時間は2分であった．)最大のパッチ
(22.778行で，287のファイルを変更する)に\hgxcmd{mq}{qrefresh}を行ったとこ
ろ，6.6秒を要した．

%Clearly, MQ is well suited to working in large trees, but there are a
%few tricks you can use to get the best performance of it.

MQが巨大なツリーでの作業に適しているのは明らかだが，さらに最高の性能を引
き出すためにいくつかのトリックが使える．

%First of all, try to ``batch'' operations together.  Every time you
%run \hgxcmd{mq}{qpush} or \hgxcmd{mq}{qpop}, these commands scan the working
%directory once to make sure you haven't made some changes and then
%forgotten to run \hgxcmd{mq}{qrefresh}.  On a small tree, the time that
%this scan takes is unnoticeable.  However, on a medium-sized tree
%(containing tens of thousands of files), it can take a second or more.

まず第一に，``batch''オペレーションを併用することができ
る．\hgxcmd{mq}{qpush}または\hgxcmd{mq}{qpop}は，ワーキングディレクトリに
変更を加えたのに\hgxcmd{mq}{qrefresh}の実行を忘れていないかどうか調べるた
め，実行時に常にワーキングディレクトリをスキャンする．小規模なツリーでは
気づかない程度の時間しかかからないが，(数万のファイルを持つような)中規模
のでは数秒の時間を要する．

%The \hgxcmd{mq}{qpush} and \hgxcmd{mq}{qpop} commands allow you to push and pop
%multiple patches at a time.  You can identify the ``destination
%patch'' that you want to end up at.  When you \hgxcmd{mq}{qpush} with a
%destination specified, it will push patches until that patch is at the
%top of the applied stack.  When you \hgxcmd{mq}{qpop} to a destination, MQ
%will pop patches until the destination patch is at the top.

\hgxcmd{mq}{qpush}コマンドと\hgxcmd{mq}{qpop}コマンドは複数のファイルを同
時にpushまたはpopすることができる．最終目的のパッチがあるなら
ば，\hgxcmd{mq}{qpush}に目的のパッチを指定して実行することで，指定したパッ
チが再上位になるまでパッチをpushする．同様に\hgxcmd{mq}{qpop}に目的のパッ
チを指定すれば，指定したパッチが再上位になるまでパッチをpopする．

%You can identify a destination patch using either the name of the
%patch, or by number.  If you use numeric addressing, patches are
%counted from zero; this means that the first patch is zero, the second
%is one, and so on.

目的のパッチは名前でも番号でも指定可能である．番号が用いられる場合は，パッ
チは0からカウントされる．つまり最初のパッチは0となり，2番目は1，という風
になる．

%\section{Updating your patches when the underlying code changes}
\section{対象コードの変化に合わせてパッチを更新する}
\label{sec:mq:merge}

%It's common to have a stack of patches on top of an underlying
%repository that you don't modify directly.  If you're working on
%changes to third-party code, or on a feature that is taking longer to
%develop than the rate of change of the code beneath, you will often
%need to sync up with the underlying code, and fix up any hunks in your
%patches that no longer apply.  This is called \emph{rebasing} your
%patch series.

直接変更しないリポジトリの上にパッチのスタックを管理することはよく行われ
る．サードパーティのコードを変更する作業をしている場合や，元になるコード
の変更頻度に比べて長い時間がかかる機能を開発している場合，しばしば元のコー
ドの同期を行い，パッチの中のもはや適用できなくなったhunkを修正することに
なるだろう．これはパッチの\emph{rebasing}と呼ばれる．

%The simplest way to do this is to \hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}}
%your patches, then \hgcmd{pull} changes into the underlying
%repository, and finally \hgcmdargs{qpush}{\hgxopt{mq}{qpop}{-a}} your
%patches again.  MQ will stop pushing any time it runs across a patch
%that fails to apply during conflicts, allowing you to fix your
%conflicts, \hgxcmd{mq}{qrefresh} the affected patch, and continue pushing
%until you have fixed your entire stack.

これを行う最も簡単な方法は，パッチに対して
\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}}を行い，下位のリポジトリに
\hgcmd{pull}を行う．そして最後にパッチに再び
\hgcmdargs{qpush}{\hgxopt{mq}{qpop}{-a}}を行う． MQはパッチ適用中にコンフ
リクトがあると，いつでもプッシュを停止し，\hgxcmd{mq}{qrefresh}によってコ
ンフリクトを修正する機会を与える．その後にすべてのパッチスタックを適用す
るまでプッシュを続ける．

%This approach is easy to use and works well if you don't expect
%changes to the underlying code to affect how well your patches apply.
%If your patch stack touches code that is modified frequently or
%invasively in the underlying repository, however, fixing up rejected
%hunks by hand quickly becomes tiresome.

このアプローチは簡単で，パッチの適用される下位のコードへの変更がなければ
うまく働く．しかし，パッチスタックが，頻繁に更新されたり，下位リポジトリ
へ侵入的に更新されたりするコードに触れている場合はリジェクトされたコード
の修正は面倒なものになる．

%It's possible to partially automate the rebasing process.  If your
%patches apply cleanly against some revision of the underlying repo, MQ
%can use this information to help you to resolve conflicts between your
%patches and a different revision.

rebaseプロセスを部分的に自動化することは可能である．パッチが下位のリポジ
トリのいずれかのバージョンにクリーンに適用できるのであれば，MQはこの情報
を使ってパッチとその他のリビジョンとの間のコンフリクトを解消するのを援助
する．

%The process is a little involved.
このプロセスはやや込み入っている．
\begin{enumerate}
%\item To begin, \hgcmdargs{qpush}{-a} all of your patches on top of
%  the revision where you know that they apply cleanly.
\item 最初に，パッチがクリーンに適用できるリビジョンの上で，すべてのパッ
      チに対して\hgcmdargs{qpush}{-a}を行う．

%\item Save a backup copy of your patch directory using
%  \hgcmdargs{qsave}{\hgxopt{mq}{qsave}{-e} \hgxopt{mq}{qsave}{-c}}.
%  This prints
%  the name of the directory that it has saved the patches in.  It will
%  save the patches to a directory called
%  \sdirname{.hg/patches.\emph{N}}, where \texttt{\emph{N}} is a small
%  integer.  It also commits a ``save changeset'' on top of your

%  applied patches; this is for internal book-keeping, and records the
%  states of the \sfilename{series} and \sfilename{status} files.

\item パッチディレクトリをセーブを
      \hgcmdargs{qsave}{\hgxopt{mq}{qsave}{-e} \hgxopt{mq}{qsave}{-c}}を
      用いて行う．パッチをセーブしたディレクトリ名が表示される．このコマ
      ンドは，\sdirname{.hg/patches.\emph{N}}というディレクトリにセーブを
      行う．ここで\texttt{\emph{N}}は小さい整数である．このコマンドは``セー
      ブチェンジセット''を適用されたパッチの上にコミットする．これは内部
      的な管理と，\sfilename{series}ファイル及び\sfilename{status}ファイ
      ルの状態を記録するためである．

%\item Use \hgcmd{pull} to bring new changes into the underlying
%  repository.  (Don't run \hgcmdargs{pull}{-u}; see below for why.)

\item \hgcmd{pull}コマンドを使って新たな変更を下位のリポジトリに取り込
      む．(\hgcmdargs{pull}{-u}を実行してはいけない．理由については下記
      を参照．)

%\item Update to the new tip revision, using
%  \hgcmdargs{update}{\hgopt{update}{-C}} to override the patches you
%  have pushed.

\item \hgcmdargs{update}{\hgopt{update}{-C}}を用いて，pushしたパッチをオー
      バライドして新たなtipリビジョンへのアップデートを行う．

%\item Merge all patches using \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}
%    \hgxopt{mq}{qpush}{-a}}.  The \hgxopt{mq}{qpush}{-m} option to \hgxcmd{mq}{qpush}
%  tells MQ to perform a three-way merge if the patch fails to apply.

\item \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m} \hgxopt{mq}{qpush}{-a}}を
      用いてすべてのパッチのマージを行う．\hgxopt{mq}{qpush}{-m}オプショ
      ンを\hgxcmd{mq}{qpush}に付けると，MQはパッチの適用に失敗した場
      合，3ウェイマージを行う．

\end{enumerate}

%During the \hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}}, each patch in the
%\sfilename{series} file is applied normally.  If a patch applies with
%fuzz or rejects, MQ looks at the queue you \hgxcmd{mq}{qsave}d, and
%performs a three-way merge with the corresponding changeset.  This
%merge uses Mercurial's normal merge machinery, so it may pop up a GUI
%merge tool to help you to resolve problems.

\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-m}}コマンドの実行
中，\sfilename{series}内のパッチは通常通り適用される．もしパッチがfuzzや
rejectを出した場合，MQは\hgxcmd{mq}{qsave}したキューを参照し，対応するチェ
ンジセットとの間で3ウェイマージを行う．マージはMercurialの通常の機構を使っ
て行われるため，設定によって問題を解決するためのGUIマージツールなどが起動
する．

%When you finish resolving the effects of a patch, MQ refreshes your
%patch based on the result of the merge.

パッチの影響の解決を終えた時，MQはマージの結果を踏まえてパッチのリフレッ
シュを行う．

%At the end of this process, your repository will have one extra head
%from the old patch queue, and a copy of the old patch queue will be in
%\sdirname{.hg/patches.\emph{N}}. You can remove the extra head using

%\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a} \hgxopt{mq}{qpop}{-n} patches.\emph{N}}
%or \hgcmd{strip}.  You can delete \sdirname{.hg/patches.\emph{N}} once
%you are sure that you no longer need it as a backup.

このプロセスの最後にリポジトリには古いパッチキューに由来する一つ余分な
headができ，古いパッチキューが\sdirname{.hg/patches.\emph{N}}にコピーされ
る．このheadは\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}
\hgxopt{mq}{qpop}{-n} patches.\emph{N}}または\hgcmd{strip}によって消去で
きる．バックアップが不要なことが分かれば，\sdirname{.hg/patches.\emph{N}}を
消去しても構わない．

%\section{Identifying patches}
\section{パッチの識別}

%MQ commands that work with patches let you refer to a patch either by
%using its name or by a number.  By name is obvious enough; pass the
%name \filename{foo.patch} to \hgxcmd{mq}{qpush}, for example, and it will
%push patches until \filename{foo.patch} is applied.

パッチを扱うMQコマンドは，パッチをパッチ名または番号で参照する．名前の場
合は例えばファイル名\filename{foo.patch}を\hgxcmd{mq}{qpush}に渡す．この
場合，コマンドは\filename{foo.patch}までのファイルをプッシュする．

%As a shortcut, you can refer to a patch using both a name and a
%numeric offset; \texttt{foo.patch-2} means ``two patches before
%\texttt{foo.patch}'', while \texttt{bar.patch+4} means ``four patches
%after \texttt{bar.patch}''.

ショートカットとして，パッチに名前と数字によるオフセット両方を用いて参照
することができる．\texttt{foo.patch-2}は``\texttt{foo.patch}の2つ前のパッ
チ''と解釈される．また，\texttt{bar.patch+4}は``\texttt{bar.patch}の4つ
後のパッチ''と解釈される．

%Referring to a patch by index isn't much different.  The first patch
%printed in the output of \hgxcmd{mq}{qseries} is patch zero (yes, it's one
%of those start-at-zero counting systems); the second is patch one; and
%so on

インデックスがあまり違わないパッチの参照．\hgxcmd{mq}{qseries}で最初に表
示されるパッチはパッチ0(これも0から数え始める)で，2番目はパッチ1のように
続く．

%MQ also makes it easy to work with patches when you are using normal
%Mercurial commands.  Every command that accepts a changeset ID will
%also accept the name of an applied patch.  MQ augments the tags
%normally in the repository with an eponymous one for each applied
%patch.  In addition, the special tags \index{tags!special tag
%  names!\texttt{qbase}}\texttt{qbase} and \index{tags!special tag
%  names!\texttt{qtip}}\texttt{qtip} identify the ``bottom-most'' and
%topmost applied patches, respectively.

MQは，通常のMercurialコマンドを使う時のも簡単にしている．全てのコマンドは
チェンジセットIDと適用されたパッチの番号を受け付ける．MQは，リポジトリに
適用されたパッチの名前のついたタグを受け付ける．さらに，最下位の適用され
たパッチを表す特別なタグ\index{tags!special tag
names!\texttt{qbase}}\texttt{qbase}と，最上位を表す特別なタグ
\index{tags!special tag names!\texttt{qtip}}\texttt{qtip}も受け付ける．

%These additions to Mercurial's normal tagging capabilities make
%dealing with patches even more of a breeze.

Mercurialの通常のタグ機能へのこれらの追加は，パッチの取り扱いにおいて大き
な意味を持つ．

\begin{itemize}
%\item Want to patchbomb a mailing list with your latest series of
%  changes?
\item 一連の最新の変更をパッチ爆弾としてメーリングリストへに投げ込みたい
      だろうか？
  \begin{codesample4}
    hg email qbase:qtip
  \end{codesample4}
%  (Don't know what ``patchbombing'' is?  See
%  section~\ref{sec:hgext:patchbomb}.)
(``patchbombing''が何か分からなければsection~\ref{sec:hgext:patchbomb}を
      参照のこと．)
%\item Need to see all of the patches since \texttt{foo.patch} that
%  have touched files in a subdirectory of your tree?
 \item ツリー中のサブディレクトリに含まれるファイルに触れた
      \texttt{foo.patch}以降のパッチを全て見たいか？
  \begin{codesample4}
    hg log -r foo.patch:qtip \emph{subdir}
  \end{codesample4}
\end{itemize}

%Because MQ makes the names of patches available to the rest of
%Mercurial through its normal internal tag machinery, you don't need to
%type in the entire name of a patch when you want to identify it by
%name.

MQでのパッチの名称は，内部のタグ機構を用いているため，Mercurialの他の部分
でも利用可能である．名称を指定する時，名称全てを入力する必要はない．

\begin{figure}[ht]
  \interaction{mq.id.output}
%  \caption{Using MQ's tag features to work with patches}
  \caption{パッチを扱うためMQのタグ機能を利用する}
  \label{ex:mq:id}
\end{figure}

%Another nice consequence of representing patch names as tags is that
%when you run the \hgcmd{log} command, it will display a patch's name
%as a tag, simply as part of its normal output.  This makes it easy to
%visually distinguish applied patches from underlying ``normal''
%revisions.  Figure~\ref{ex:mq:id} shows a few normal Mercurial
%commands in use with applied patches.

パッチ名をタグとして取り扱うことのもう一つの利点は，\hgcmd{log}コマンド
を実行した時，通常出力の一部にパッチ名をタグとして表示する点である．この
ため，適用したパッチは下位の``通常の''リビジョンと視覚的に区別し易くなる．
図~\ref{ex:mq:id}にいくつかの通常のMercurialコマンドを適用済みパッチと共
に使用した場合を示す．

%\section{Useful things to know about}
\section{知っておくべきいくつかの点}

%There are a number of aspects of MQ usage that don't fit tidily into
%sections of their own, but that are good to know.  Here they are, in
%one place.

MQの使用法には個別に取り上げるほどではないが，知っておくと良いいくつかの
点がある．ここではそれらをまとめて取り上げる．

\begin{itemize}
%\item Normally, when you \hgxcmd{mq}{qpop} a patch and \hgxcmd{mq}{qpush} it
%  again, the changeset that represents the patch after the pop/push
%  will have a \emph{different identity} than the changeset that
%  represented the hash beforehand.  See
%  section~\ref{sec:mqref:cmd:qpush} for information as to why this is.
\item パッチを\hgxcmd{mq}{qpop}した後で再び\hgxcmd{mq}{qpush}する
      と，pop/pushした後のチェンジセットは，以前のチェンジセットと異なる
      アイデンティティを持ち，ハッシュ値が異なる．この理由についてはセク
      ション~\ref{sec:mqref:cmd:qpush}を参照されたい．
%\item It's not a good idea to \hgcmd{merge} changes from another
%  branch with a patch changeset, at least if you want to maintain the
%  ``patchiness'' of that changeset and changesets below it on the
%  patch stack.  If you try to do this, it will appear to succeed, but
%  MQ will become confused.
\item \hgcmd{merge}が他のブランチのパッチチェンジセットをマージすること
      は，そのチェンジセットとパッチスタックに積み込まれた他のチェンジセッ
      トとの間で一貫性を維持しようとするのであれば避けるべきである．これ
      を試みた場合，一見成功したように見えてもMQは混乱状態に陥ってしま
      う．
\end{itemize}

%\section{Managing patches in a repository}
\section{リポジトリ内でのパッチの管理}
\label{sec:mq:repo}

%Because MQ's \sdirname{.hg/patches} directory resides outside a
%Mercurial repository's working directory, the ``underlying'' Mercurial
%repository knows nothing about the management or presence of patches.

MQの\sdirname{.hg/patches}ディレクトリはMercurialリポジトリのワーキング
ディレクトリの外にあるので，``下位の''Mercurialリポジトリはパッチの管理
や，その存在自体について何も知らない．

%This presents the interesting possibility of managing the contents of
%the patch directory as a Mercurial repository in its own right.  This
%can be a useful way to work.  For example, you can work on a patch for
%a while, \hgxcmd{mq}{qrefresh} it, then \hgcmd{commit} the current state of
%the patch.  This lets you ``roll back'' to that version of the patch
%later on.

このことから，パッチディレクトリの管理を独立したMercurialリポジトリとして
行うことができるのではないかという興味が生まれる．実際この方法は有効な方
法となり得る．例えば，しばらくの間1つのパッチについて作業を行った後
で，\hgxcmd{mq}{qrefresh}を行い，パッチの現在の状態を\hgcmd{commit}する
ことができる．これによって，後でこのパッチを``ロールバック''することが可
能となる．

%You can then share different versions of the same patch stack among
%multiple underlying repositories.  I use this when I am developing a
%Linux kernel feature.  I have a pristine copy of my kernel sources for
%each of several CPU architectures, and a cloned repository under each
%that contains the patches I am working on.  When I want to test a
%change on a different architecture, I push my current patches to the
%patch repository associated with that kernel tree, pop and push all of
%my patches, and build and test that kernel.

複数の下位リポジトリの間で，同じパッチスタックの異なるバージョンを共有す
ることができる．筆者はこれをLinuxカーネルの機能を開発する時に利用してい
る．いくつかのCPUアーキテクチャの各々に対してまっさらなカーネルソースのリ
ポジトリを用意し，作業中のパッチを含むリポジトリをそれらの間でクローンし
ている．変更を異なるアーキテクチャでテストしたい時は，現在のパッチをその
アーキテクチャ用のカーネルツリーと結び付いたパッチのリポジトリへプッシュ
し，すべてのパッチをpop，pushしてカーネルのビルドとテストを行っている．

%Managing patches in a repository makes it possible for multiple
%developers to work on the same patch series without colliding with
%each other, all on top of an underlying source base that they may or
%may not control.

リポジトリ内でパッチを管理すると，複数の開発者が同じパッチシリーズの上で
コンフリクトすることなく作業できるようになる．これは彼らが下位のソースベー
スをコントロールできるか否かに関わりがない．

%\subsection{MQ support for patch repositories}
\subsection{MQによるパッチリポジトリサポート}

%MQ helps you to work with the \sdirname{.hg/patches} directory as a
%repository; when you prepare a repository for working with patches
%using \hgxcmd{mq}{qinit}, you can pass the \hgxopt{mq}{qinit}{-c} option to
%create the \sdirname{.hg/patches} directory as a Mercurial repository.

MQは\sdirname{.hg/patches}ディレクトリをリポジトリとして使いながら作業す
ることをサポートしている．パッチを扱う作業用のリポジトリを
\hgxcmd{mq}{qinit}で作成する時，\hgxopt{mq}{qinit}{-c}を渡して
\sdirname{.hg/patches}ディレクトリをMercurialリポジトリにすることができる．

\begin{note}
%  If you forget to use the \hgxopt{mq}{qinit}{-c} option, you can simply go
%  into the \sdirname{.hg/patches} directory at any time and run
%  \hgcmd{init}.  Don't forget to add an entry for the
%  \sfilename{status} file to the \sfilename{.hgignore} file, though
%  (\hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}} does this for you
%  automatically); you \emph{really} don't want to manage the
%  \sfilename{status} file.

 \hgxopt{mq}{qinit}{-c}オプションを忘れた場合はいつでも
 \sdirname{.hg/patches}に入って\hgcmd{init}を実行すればよ
 い．\sfilename{status}ファイルを\sfilename{.hgignore}ファイルに追加する
 のを忘れないこと．(\hgcmdargs{qinit}{\hgxopt{mq}{qinit}{-c}}はこれを自動
 的に行う．）\sfilename{status}をバージョン管理する必要は\emph{全くない}．
\end{note}

%As a convenience, if MQ notices that the \dirname{.hg/patches}
%directory is a repository, it will automatically \hgcmd{add} every
%patch that you create and import.

\dirname{.hg/patches}がリポジトリの時は，MQは便利のためにこれまで作成し，
インポートしたすべてのパッチを自動的に\hgcmd{add}する．

%MQ provides a shortcut command, \hgxcmd{mq}{qcommit}, that runs
%\hgcmd{commit} in the \sdirname{.hg/patches} directory.  This saves
%some bothersome typing.

MQはショートカットコマンド\hgxcmd{mq}{qcommit}を持つ．このコマンドは
\hgcmd{commit}コマンドを\sdirname{.hg/patches}ディレクトリの中で実行す
る．これによって繁雑な入力を省くことができる．

%Finally, as a convenience to manage the patch directory, you can
%define the alias \command{mq} on Unix systems. For example, on Linux
%systems using the \command{bash} shell, you can include the following
%snippet in your \tildefile{.bashrc}.

パッチディレクトリの管理のためにUNIX環境なら\command{mq}というエイリアス
を作っておくと便利だ．Linuxでは\command{bash}シェルの設定ファイル
\tildefile{.bashrc}にこれを定義しておく．

\begin{codesample2}
  alias mq=`hg -R \$(hg root)/.hg/patches'
\end{codesample2}

%You can then issue commands of the form \cmdargs{mq}{pull} from
%the main repository.

メインリポジトリから\cmdargs{mq}{pull}を実行することができる

%\subsection{A few things to watch out for}
\subsection{注意しておくべきいくつかの点}

%MQ's support for working with a repository full of patches is limited
%in a few small respects.

MQが大量のパッチのあるリポジトリを扱う際に，いくつかの小さな点から制限が
ある．

%MQ cannot automatically detect changes that you make to the patch
%directory.  If you \hgcmd{pull}, manually edit, or \hgcmd{update}
%changes to patches or the \sfilename{series} file, you will have to
%\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}} and then
%\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}} in the underlying repository to
%see those changes show up there.  If you forget to do this, you can
%confuse MQ's idea of which patches are applied.

MQは，パッチディレクトリに対して行われた変更を自動的に検出することはでき
ない．パッチファイルや\sfilename{series}に対して\hgcmd{pull}を行ったり，
手で編集したり，\hgcmd{update}を行った場合
は，下位のリポジトリに対して\hgcmdargs{qpop}{\hgxopt{mq}{qpop}{-a}}と
\hgcmdargs{qpush}{\hgxopt{mq}{qpush}{-a}}を行い，変更を知らせる必要があ
る．これを忘れるとMQはどのパッチが適用されたのか把握できなくなってしまう．


%\section{Third party tools for working with patches}
\section{パッチ向けサードパーティツール}
\label{sec:mq:tools}

%Once you've been working with patches for a while, you'll find
%yourself hungry for tools that will help you to understand and
%manipulate the patches you're dealing with.

しばらくパッチを使った作業をしていると，パッチを取り扱う助けとなるような
ツールが欲しくなるに違いない．

%The \command{diffstat} command~\cite{web:diffstat} generates a
%histogram of the modifications made to each file in a patch.  It
%provides a good way to ``get a sense of'' a patch---which files it
%affects, and how much change it introduces to each file and as a
%whole.  (I find that it's a good idea to use \command{diffstat}'s
%\cmdopt{diffstat}{-p} option as a matter of course, as otherwise it
%will try to do clever things with prefixes of file names that
%inevitably confuse at least me.)

\command{diffstat}コマンド~\cite{web:diffstat}はパッチ内のそれぞれのファ
イルへの変更のヒストグラムを生成する．これは，パッチが影響を及ぼすファイ
ルを把握したり，全体でそれぞれのファイルへどの程度変更を加えるのか把握す
るのに役立つ． （\command{diffstat}コマンドの\cmdopt{diffstat}{-p}オプショ
ンを用いるのは勿論良い考えである．さもなければコマンドはファイル名の
prefixに対して``賢い''ことをしでかすため，少なくとも筆者は混乱を避けられ
なかった．）


\begin{figure}[ht]
  \interaction{mq.tools.tools}
%  \caption{The \command{diffstat}, \command{filterdiff}, and
 %  \command{lsdiff} commands}
  \caption{\command{diffstat}, \command{filterdiff}, および
 \command{lsdiff} コマンド}
  \label{ex:mq:tools}
\end{figure}

%The \package{patchutils} package~\cite{web:patchutils} is invaluable.
%It provides a set of small utilities that follow the ``Unix
%philosophy;'' each does one useful thing with a patch.  The
%\package{patchutils} command I use most is \command{filterdiff}, which
%extracts subsets from a patch file.  For example, given a patch that

%modifies hundreds of files across dozens of directories, a single
%invocation of \command{filterdiff} can generate a smaller patch that
%only touches files whose names match a particular glob pattern.  See
%section~\ref{mq-collab:tips:interdiff} for another example.

\package{patchutils}パッケージ~\cite{web:patchutils}は非常に有用である．
このパッケージは``UNIX哲学''に従った小さなユーティリティからなり，各々の
ユーティリティはパッチに対して有用な単機能を提供す
る．\package{patchutils}の中で筆者が最も良く使うコマンドは
\command{filterdiff}で，これはパッチファイルからパッチの部分集合を取り出
す．例えば，10以上のディレクトリに跨って数百のファイルに変更を行うような
パッチがあるとして，ただ一回の\command{filterdiff}の実行で特定のパターン
にマッチしたファイルのみを変更するより小さなパッチを生成することができ
る．そのほかの例は\ref{mq-collab:tips:interdiff}を見よ．


%\section{Good ways to work with patches}
\section{好ましいパッチ取り扱い方法}

%Whether you are working on a patch series to submit to a free software
%or open source project, or a series that you intend to treat as a
%sequence of regular changesets when you're done, you can use some
%simple techniques to keep your work well organized.

フリーソフトやオープンソースプロジェクトに提出するためのパッチシリーズに
対して作業しているときや，パッチとしての作業が終った際に通常のチェンジセッ
トとして取り込む予定のパッチシリーズに対して作業しているときは，作業をう
まく行なうためのシンプルなテクニックがある．

%Give your patches descriptive names.  A good name for a patch might be
%\filename{rework-device-alloc.patch}, because it will immediately give
%you a hint what the purpose of the patch is.  Long names shouldn't be a
%problem; you won't be typing the names often, but you \emph{will} be
%running commands like \hgxcmd{mq}{qapplied} and \hgxcmd{mq}{qtop} over
%and over.  Good naming becomes especially important when you have a
%number of patches to work with, or if you are juggling a number of
%different tasks and your patches only get a fraction of your attention.

パッチに記述的な名前を与える．パッチに与えるべき良い名前は
\filename{rework-device-alloc.patch}のようなものである．理由は即座にパッ
チの目的のヒントを与えるからである．長い名前は問題にはならない．なぜなら
名前をタイプすることは滅多になく，代わりに\hgxcmd{mq}{qapplied}や
\hgxcmd{mq}{qtop}のようなコマンドを繰り返し実行することになるからである．
多数のパッチに対して作業をしているときは，良い名前を付けることは特に重要
となる．そうしないと，もしあなたがたくさんの別のタスクを抱えているなら
ば，パッチの区別はつかなくなってしまう．

%Be aware of what patch you're working on.  Use the \hgxcmd{mq}{qtop}
%command and skim over the text of your patches frequently---for
%example, using \hgcmdargs{tip}{\hgopt{tip}{-p}}---to be sure of where
%you stand.  I have several times worked on and \hgxcmd{mq}{qrefresh}ed a
%patch other than the one I intended, and it's often tricky to migrate
%changes into the right patch after making them in the wrong one.

どのパッチについて作業しているのか把握しておくべきであ
る．\hgxcmd{mq}{qtop}コマンドを使い，パッチを頻繁にチェックすべきである．
また，例えば\hgcmdargs{tip}{\hgopt{tip}{-p}}を使って，いまどこにいるのか
を調べることも必要である．意図しているパッチ以外のパッチについて
\hgxcmd{mq}{qrefresh}を行い，間違ったパッチに加えられた変更を正しいパッチ
に移動させた．

%For this reason, it is very much worth investing a little time to
%learn how to use some of the third-party tools I described in
%section~\ref{sec:mq:tools}, particularly \command{diffstat} and
%\command{filterdiff}.  The former will give you a quick idea of what
%changes your patch is making, while the latter makes it easy to splice
%hunks selectively out of one patch and into another.

このため，セクション~\ref{sec:mq:tools}で述べたサードパーティ製のいくつか
のツール，特に\command{diffstat}と\command{filterdiff}の使い方を学ぶのは
とても意味がある．前者は，あなたのパッチがどのような変更を加えるのか即座
に知ることができ，一方で後者はパッチの中のhunkを別のパッチへ挿入するのを
容易にする．


%\section{MQ cookbook}
\section{MQクックブック}

%\subsection{Manage ``trivial'' patches}
\subsection{``トリビアル''なパッチの管理}

%Because the overhead of dropping files into a new Mercurial repository
%is so low, it makes a lot of sense to manage patches this way even if
%you simply want to make a few changes to a source tarball that you
%downloaded.

ファイルをMercurialリポジトリに追加するオーバヘッドは小さい．このため，た
とえソースのtarアーカイブへ少数の変更を加えるだけだとしても，パッチをリポ
ジトリで管理するのは良い方法である．

%Begin by downloading and unpacking the source tarball,
%and turning it into a Mercurial repository.
%\interaction{mq.tarball.download}

ソースtarballをダウンロードして展開し，これをMercurialリポジトリに変換す
る．
\interaction{mq.tarball.download}

%Continue by creating a patch stack and making your changes.
%\interaction{mq.tarball.qinit}

新たなパッチスタックを作り，変更を行う．
\interaction{mq.tarball.qinit}

%Let's say a few weeks or months pass, and your package author releases
%a new version.  First, bring their changes into the repository.
%\interaction{mq.tarball.newsource}
%The pipeline starting with \hgcmd{locate} above deletes all files in
%the working directory, so that \hgcmd{commit}'s
%\hgopt{commit}{--addremove} option can actually tell which files have
%really been removed in the newer version of the source.

数週間から数カ月経った時，パッケージの作者が新しいバージョンをリリースし
たとしよう．その場合，まず新しいバージョンとの差分をリポジトリに取り込む．
\interaction{mq.tarball.newsource}
\hgcmd{locate}の出力をパイプで繋いでワーキングディレクトリのすべてのファ
イルを消去し，\hgcmd{commit}コマンドの\hgopt{commit}{--addremove}オプショ
ンを使って実際にどのファイルが新しいバージョンのソースで削除されたのか指
定する．

%Finally, you can apply your patches on top of the new tree.
%\interaction{mq.tarball.repush}

最後にパッチを新しいツリーに適用する．
\interaction{mq.tarball.repush}

%\subsection{Combining entire patches}
\subsection{パッチ同士を結合する}
\label{sec:mq:combine}

%MQ provides a command, \hgxcmd{mq}{qfold} that lets you combine entire
%patches.  This ``folds'' the patches you name, in the order you name
%them, into the topmost applied patch, and concatenates their
%descriptions onto the end of its description.  The patches that you
%fold must be unapplied before you fold them.

MQにはパッチ全体を結合する\hgxcmd{mq}{qfold}というコマンドがある．このコ
マンドは名前をつけたパッチを名付けた順番で再上位の適用済みパッチに畳み込
む．各々のパッチの説明は結合されてパッチの説明の末尾に追加される．畳み込
むパッチはすでに適用されていてはならない．

%The order in which you fold patches matters.  If your topmost applied
%patch is \texttt{foo}, and you \hgxcmd{mq}{qfold} \texttt{bar} and
%\texttt{quux} into it, you will end up with a patch that has the same
%effect as if you applied first \texttt{foo}, then \texttt{bar},
%followed by \texttt{quux}.

パッチを畳み込む順番は重要である．今，再上位の適用済みパッチが
\texttt{foo}だとして，\hgxcmd{mq}{qfold} \texttt{bar}と\texttt{quux}を行
うと，パッチは\texttt{foo}, then \texttt{bar}, \texttt{quux}の順番でパッ
チを適用したのと同じ効果を持つことになる．

%\subsection{Merging part of one patch into another}
\subsection{パッチの一部分を別のパッチへマージする}

%Merging \emph{part} of one patch into another is more difficult than
%combining entire patches.

パッチの\emph{一部}を別のパッチへマージすることは，パッチを結合するよりは
難しい．

%If you want to move changes to entire files, you can use
%\command{filterdiff}'s \cmdopt{filterdiff}{-i} and
%\cmdopt{filterdiff}{-x} options to choose the modifications to snip
%out of one patch, concatenating its output onto the end of the patch
%you want to merge into.You usually won't need to modify the patch
%you've merged the changes from.  Instead, MQ will report some rejected
%hunks when you \hgxcmd{mq}{qpush} it (from the hunks you moved into the
%other patch), and you can simply \hgxcmd{mq}{qrefresh} the patch to drop
%the duplicate hunks.

変更をファイルの集合全体に移動する場合，\command{filterdiff}に
\cmdopt{filterdiff}{-i}と\cmdopt{filterdiff}{-x}を付け，
一つのパッチから取る去る変更，パッチの末尾に結合する変更を選ぶ．
通常の場合，変更を取り出したパッチを変更する必要はない．その代わり，MQは
(他のパッチに移動したhunkから)\hgxcmd{mq}{qpush}した時にリジェクトされた
hunkを報告する．

%If you have a patch that has multiple hunks modifying a file, and you
%only want to move a few of those hunks, the job becomes more messy,
%but you can still partly automate it.  Use \cmdargs{lsdiff}{-nvv} to
%print some metadata about the patch.
%\interaction{mq.tools.lsdiff}

パッチに一つのファイルを変更する複数のhunkがあり，その中の一部を移動した
い場合は，作業はもっとややこしいものになるが，依然として一部は自動化する
ことができる．\cmdargs{lsdiff}{-nvv}コマンドでパッチのメタデータを表示す
る．\interaction{mq.tools.lsdiff}

%This command prints three different kinds of number:
このコマンドは3つの異なる番号を出力する:
\begin{itemize}
%\item (in the first column) a \emph{file number} to identify each file
%  modified in the patch;
\item (最初の列) このパッチで変更されるファイルを識別するための\emph{ファ
      イル番号}
%\item (on the next line, indented) the line number within a modified
%  file where a hunk starts; and
\item (次の行でインデントされている) 変更されたファイルの中でhunが始まる
      行番号
%\item (on the same line) a \emph{hunk number} to identify that hunk.
\item (それと同じ行) 当該hunkを識別する\emph{hunk番号}
\end{itemize}

%You'll have to use some visual inspection, and reading of the patch,
%to identify the file and hunk numbers you'll want, but you can then
%pass them to to \command{filterdiff}'s \cmdopt{filterdiff}{--files}
%and \cmdopt{filterdiff}{--hunks} options, to select exactly the file
%and hunk you want to extract.

必要なファイルとhunk番号を見つけるために，パッチを読むなどして目視で確認
する必要がある．その番号は，extractするファイルとhunkを選ぶために
\command{filterdiff}コマンドの\cmdopt{filterdiff}{--files}と
\cmdopt{filterdiff}{--hunks}オプションで使える．

%Once you have this hunk, you can concatenate it onto the end of your
%destination patch and continue with the remainder of
%section~\ref{sec:mq:combine}.

このhunkができたら，目的のパッチの末尾に結合し，セクションの残りの部分を
続けることができる~\ref{sec:mq:combine}．

%\section{Differences between quilt and MQ}
\section{quiltとMQの違い}

%If you are already familiar with quilt, MQ provides a similar command
%set.  There are a few differences in the way that it works.

すでにquiltに馴染んでいるユーザのために，MQは同様のコマンドセットを用意
している．コマンドの挙動には何点か違いがある．

%You will already have noticed that most quilt commands have MQ
%counterparts that simply begin with a ``\texttt{q}''.  The exceptions
%are quilt's \texttt{add} and \texttt{remove} commands, the
%counterparts for which are the normal Mercurial \hgcmd{add} and
%\hgcmd{remove} commands.  There is no MQ equivalent of the quilt
%\texttt{edit} command.

すでにほとんどのquiltコマンドには，対応する``\texttt{q}''で始まるMQコマン
ドがあることに気づいていることと思う．例外は，quiltの\texttt{add}コマンド
と\texttt{remove}コマンドで，これらにはそれぞれ通常のMercurialコマンドの
\hgcmd{add}と\hgcmd{remove}が対応する．また，quiltの\texttt{edit}コマンド
に対応するMQコマンドはない．

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