ARCH チュートリアル (arch Meets hello-world)

このマニュアルを使うためには、基本的な unix コマンドラインツールに精通している べきです。(たとえばls, mv, findのようなコマンドです)。

さらに、diff、patch プログラム、さらに、 patchsetの概念に精通しているべきです。

それはとても役に立ちますが、CVSのような他のバージョン管理 システムを使っているか、少なくとも知っているのであれば、どうしても必要というわけでも ありません。

「リビジョン管理システム」は、複数ファイルからなるツリーや、 それに対する変更のためのライブラリ群と、設定のためのツールを言います。 たとえば、典型的なソフトウェア開発は、時間と共にどのようにプロジェクトの ソースコードが変化していくかを記録し、そのコードに対するそれぞれの変更を 記録し、(バグフィックスや、機能追加など)、そのような変更をプロジェクトに かかわっているすべてのプログラムで共有し、それらが正しく同期するようにし、 一つのソースツリーに対して異なる時間、異なるプログラマがほどこした修正 をまとめるために、リビジョン管理システムを利用します。

「ソース管理ツール」は、「手で」現実的に記録すること ができる以上のファイルがある場合でも、そのようなソースツリーを管理するのを 助けるようなソフトウェアのことを言います。たとえば、ソース管理ツールは ツリー中のソースファイルの目録を作成し、ソースファイルを 一時ファイルや、同じ場所に保存されているほかのファイルと区別し、 ソースファイルが追加や削除されたようなときに、そのことを伝えます。

「設定管理」は複数の分離して管理されているソースツリーを 一つのツリーにまとめるようなプロジェクトの要求を取り扱います。設定 管理ツールは統合されたプロジェクトを簡単に構築し、それぞれの部分での 開発がどのように同期されるかを記録するのを支援します。

archは競合するソフトと比較して、いくつもの利点を持って います。その中のいくつかは以下のようなものです:

ツリー全体の上での作業 archはツリー全体を記録します — 単に個別のファイルを管理するだけではありません。たとえば、 もしツリー中のたくさんのファイルを変更した場合、archはファイルごとの 変更ではなく、その変更すべてを一つのグループとして記録することができます。 もしファイル名を変更するか、ツリー中で移動した場合、archは そのようなツリーの形状の変化を、ファイルの内容に関する変更と共に記録することが できます。

チェンジセット指向 archは単にプロジェクトツリーの"スナップショット"をとる だけではありません。そのかわりに、archはそれぞれの リビジョンを特定のチェンジセットと関連づけます。チェンジセットとは、 変更内容にについての完全な記述のことです。archは、 チェンジセットの内容を見たり、チェンジセットを適用してツリーをマージしたり、 どのようなチェンジセットが適用されたかを問うことによってあるツリーの履歴を 調べたり、などなど、といったことを支援するようなチェンジセット指向のコマンドを 用意しています。

完全な分散システムであるということ archは"中心的なリポジトリ"に依存しません。 たとえば、すべての重要な貢献者に、プロジェクトアーカイブに対する 書き込み権限を与える必要がありません。そのかわり、それぞれの貢献者は 自分の作業のために、自分自身のアーカイブを持つことができます。 archはアーカイブ境界をまたいで、シームレスに 操作することができます。

上のコマンドの後では、自分のホームディレクトリに以下のような新しい ファイルができます:

        % ls ~/.arch-params
        =id

        % cat ~/.arch-params/=id
        Tom Lord <lord@emf.net>

注意: ~/.arch-params/の中のファイルを「手で」 編集しないでください。

アーカイブを保存する場所を決めなくてはなりません: アーカイブを 含むディレクトリをどこに作るか、ということです。

アーカイブの利用方法: 結局は一個以上の アーカイブが欲しいくなることが多いので、 複数のアーカイブを置くための専用のディレクトリを作るのは良い考えです。

以下の例では~/{archives}のサブディレクトリとしてアーカイブ を作ることにします。~/{archives}は、アーカイブ用の専用 ディレクトリです。

	# Create a directory in which to store archives:
	#
	% mkdir ~/{archives}

次に、アーカイブの名前を決める必要があります。アーカイブの名前はemailアドレスのあとに ダッシュを二つ続け(––)さらにその後に接頭辞をつけます。 便宜性を考えて、emailアドレスはアーカイブ所有者のものとすべきです。

例として、以下のような名前を使います:

	lord@emf.net--2003-example

アーカイブの利用方法: もし一つのアーカイブを非常に長い期間にわたって利用する場合、最終的には非常に大きな データが蓄積され、作業を続けるのに不便になることがあります。 arch は、アーカイブの境界をまたいで透過的な操作ができるので、 ただ一つのアーカイブにすべてを保存する必要はありません。時間 の経過とともに、アーカイブを分割する計画を立てるのは良い考えで、そのためアーカイブ名 には日付を含めることをお勧めします。今回の例では、アーカイブは2003と ラベルづけされています: 一年後、lord@emf.net––2004-example という名前の アーカイブを作り、その新しいアーカイブでプロジェクトを続けることができます。 2003 アーカイブも、そのまま存在します — 単に、もうそこには 新しいデータを追加しないというだけのことです。

アーカイブの利用方法: 複数のアーカイブを保管することを考えて、アーカイブの名前はそれぞれを区別するような ものにすべきです。上の例で-example の接頭辞はこのアーカイブが 単にチュートリアルの例として利用されるために作られたということを示しています。

新しいアーカイブを作るにはmake-archiveコマンドを使います。 アーカイブの名前と、場所を指定します:

        # Create the new archive
        #
        % larch make-archive lord@emf.net--2003-example \
                             ~/{archives}/2003-example

今後の操作で必要なコマンドのすべてにアーカイブ名を指定する手間を省くため、 新しいアーカイブをデフォルトであると宣言します:

        # Choose a default archive
        #
        % larch my-default-archive lord@emf.net--2003-example
        default archive set (lord@emf.net--2003-example)

現在のデフォルトアーカイブは以下のようにして表示できます:

        % larch my-default-archive
        lord@emf.net--2003-example

そして、デフォルト設定は以下のようにして取り消すことができます:

        % larch my-default-archive -d
        user default archive removed

(もしこの-dオプションを実際に試してみた場合は デフォルトアーカイブをもう一度設定し、以下の例を続けていけるようにして おいてください)

そのコマンドが何をするのか見てみましょう。

まず、larch は、新しいアーカイブについて知っています:

        # What archives does larch know about?
        #
        % larch archives
        lord@emf.net--2003-example
                /home/lord/{archives}/2003-example

        % larch whereis-archive lord@emf.net--2003-example
        /home/lord/{archives}/2003-example

        # Where is that data stored?
        # 
        % ls ~/.arch-params
        =default-archive   =id             =locations

        % cat ~/.arch-params/=default-archive
        lord@emf.net--2003-example

        % ls ~/.arch-params/=locations
        lord@emf.net--2003-example

        % cat ~/.arch-params/=locations/lord@emf.net--2003-example
        /home/lord/{archives}/2003-example

次に、アーカイブディレクトリは作成され、何行かが含まれています:

        % ls ~/{archives}
        2003-example

        % ls -a ~/{archives}/2003-example
        .                .archive-version
        ..               =meta-info

        % cat ~/{archives}/2003-example/.archive-version
        Hackerlab arch archive directory, format version 1.

        % ls -a ~/{archives}/2003-example/=meta-info/
        .       ..      name

        % cat ~/{archives}/2003-example/=meta-info/name
        lord@emf.net--2003-example

注意: ~/.arch-params/ の中のファイルや、アーカイブ中のファイルを 「手で」編集しないでください。

hello-world プロジェクトの最初のステップとして、アーカイブに 新しい"プロジェクトカテゴリ"を作ってみます。

        % larch make-category hello-world

アーカイブ中の全てのカテゴリの一覧を表示させることで、新しい カテゴリがうまく作成できたかどうか確認することができます:

        % larch categories
        hello-world

arch ではプロジェクトにブランチを作ることで、作業を分割する ことができます。

おおざっぱに言って、ブランチとはプロジェクトを二つ以上の部分に分けて、 お互いがほぼ独立しているような形にするしくみです。 例えば、hello-worldプロジェクトに二つのことをさせたいと します:

1) 伝統的なhello-worldの通常のリリースを作成し、単純なバグを修正し、 プログラムを移植し、重要ではない機能追加をすること

2) hello-worldにGUIインターフェースを追加する必要があり、 それには、だいたい一年くらいの開発期間がかると見込まれる

この二つの作業を並行してやりたいが、お互いに干渉させたくないとします。 例えば、うまく動作することが確認できるまでは、通常のリリースコード中に GUIのコードを混在させたくありません。

そのような場合、ブランチを使うことができます: 一つは通常のリリース用として(主系ブランチと言います)そして もう一つはGUI機能つきのものです(guiブランチと言います)。

ブランチには他にもいろいろな使い方があり、いくつかはこのマニュアルの後の ほうで説明します。いまの場合は、ひとつのブランチが必要になるだけです: hello-worldの公式な最新ソースのためのブランチです:

        % larch make-branch hello-world--mainline
                            ^^^^^^^^^^^  ^^^^^^^^
                                |            |
                                |       branch name
                          category name

カテゴリ名とブランチ名は二つのダッシュで区切られていることに注意して ください。一般的に言って、カテゴリ名とブランチ名は英文字とダッシュのみ を含み、英文字で始め、二つのダッシュを含んではならず、最後がダッシュ で終ってはなりません。

hello-worldカテゴリ中のブランチの一覧を取得するコマンド を確認することは簡単です。

        % larch branches hello-world
        hello-world--mainline

最後に、作業しようとしているhello-worldのバージョン番号を選択し、 そのバージョンをアーカイブに作る必要があります。

archのバージョン番号は、特定の「スナップショット」やプロジェクト のリリースの名前ではありません — そのような概念と関係しては いますが。正確には、バージョン番号は"開発ライン"の名前です: 開発ラインとは、特定のリリースを 作るときに加えた修正の並びです。

今回の例で、ブランチ中で新しい開発ラインを始めることができます:

        % larch make-version hello-world--mainline--0.1
                                                    ^^^
                                                     |
                                          version number

バージョン番号は常に二つの正の整数をピリオドで繋げたものです。 この二つの番号はよくメジャー番号とマイナー番号 と呼ばれます。

ブランチ中にどのようなバージョンがあるかを表示させて、新しいバージョンを確認することが できます:

        % larch versions hello-world--mainline
        hello-world--mainline--0.1

arch を使うのが初めての人はよく、アーカイブ構造の厳格な構成に 驚くようです。よくある二つの質問(と答え)は:

どうしてカテゴリ、ブランチ、バージョンなどという概念が あるのか? どうして好きな文字列でプロジェクトの名前をつけることができない のか? この質問は、リビジョン管理システムがライブラリ管理システム である、ということを思い出せば理解できると思います。 その仕事のひとつは、非常に大きなプロジェクトやソースコードの集まりを 閲覧したり検索したりするのを支援することです。そのような検索を現実的なものにするため、 arch はカテゴリシステムを定義しています: つまり、カテゴリ、ブランチ、バージョンがそれです。 (リビジョン管理とは何か?項参照)

これは、デューイの分類表のような、本のライブラリで使われるカテゴリシステム に何か似ているところもあります: ライブラリにあるすべては階層的に カテゴリ化されています。それは、あるアイテムがどこに保管されているかを 示すための統一的な方法で、さまざまなアイテム間の関係を示唆することによって 検索を支援します。たとえば、ブランチは同じカテゴリ中のほかのブランチとよく 似ているはずです。大きなメジャーバージョン番号を持ったディレクトリは、 同じブランチにある、より小さなメジャーバージョン番号を持ったものよりも あとで作られた作業を含んでいるはずです。

この類推は完全ではありません: デューイのような本のカタログシステムは、公式な カテゴリとサブカテゴリのリストに基づいていますが、archでは 自分でカテゴリ名を選ぶことができます。しかし、それでもなおarch は検索や閲覧を簡単にするために、関連するアイテムのグループ化のアイディアに 基づいています。そして、デューイが人々がどのようにして本を検索するかという 共通のパターンを把握することを意図していたのと同様、arch もソースアーカイブ中を人々がどのように検索するかという共通のパターンを捉える ことを意図しています。

なぜ、バージョン番号は二つの部分を持っているのか? 人によっては<major>.<minor> バージョン番号の 制約を好きになれないようです:0.1のかわりに、0.1.1 のような番号体系を好む、などです。

実際、この制約は、最終的にはarchから取り除かれることになるでしょう。 しかし現時点では、二つのバージョン番号体系の統一性は、unix の標準的なsort プログラムを使って、arch のバージョン番号の任意のリストをソートする ことをより簡単なものとしています。archは、sort のような標準的なツールと簡単に連携できることに非常に大きなプライオリティをおいています。

make-category, make-branch, そして make-version のようなコマンドは実際には何をするのでしょうか? それは概念的には非常に簡単なことです: アーカイブ中に新しいディレクトリを作ります。

        % larch whereis-archive lord@emf.net--2003-example
        /home/lord/{archives}/2003-example

        % cd `larch whereis-archive lord@emf.net--2003-example`

カテゴリは最上位のディレクトリです:

        % ls
        =meta-info      hello-world

ブランチは次の階層です:

        % ls hello-world
        =README         hello-world--mainline

Versions the third:

        % ls hello-world/hello-world--mainline
        =README         hello-world--mainline--0.1

バージョンもそれ自身、ディレクトリです:

        % ls hello-world/hello-world--mainline/hello-world--mainline--0.1/
        +revision-lock  +version-lock   =README

注意: =README ファイルには 誰がカテゴリ、ブランチ、リビジョンを作り、またそれがいつかという情報が含まれて います。これらのファイルはアーカイブ中のファイルを手で編集してはいけない、 という通常の規則の 唯一の例外になっています。 これらのファイルに含まれているヘッダーフィールド部分から空行で区切られた後 の部分に、新しい任意のテキストを追加することができます。

注意: ロックファイル(たとえば+revision-lock) は arch によって内部的に利用されます。新しいデータをアーカイブに追加するとき、arch は単にmkdirを呼び出すわけではありません。そのかわり、同時に実行されている ほかのコマンドや、あるコマンドが実行途中でkillされたかどうか、などにかかわらず常に一貫した状態 を保つために、アーカイブを注意深く変更します。

説明のため、初期状態としてすこしバグのあるhello-world の実装があるものとします:

        % cd ~/wd

        % ls
        hello-world

        % cd hello-world

        % ls
        hw.c    main.c

        % cat hw.c

        #include <stdio.h>

        void
        hello_world (void)
        {
          (void)printf ("hello warld");
        }
        
        
        % cat main.c
        
        extern void hello_world (void);
        
        int
        main (int argc, char * argv[])
        {
          hello_world ();
          return 0;
        }

ソースコードを用意する最初のステップは、普通のソースツリーを、"プロジェクトツリー" の形に変えることです:

        % cd ~/wd/hello-world

        % larch init-tree hello-world--mainline--0.1

        % ls
        hw.c    main.c  {arch}

これから作業するアーカイブ中のバージョン名を、init-treeコマンドに 渡していることに注意してください。init-treeは、新しいサブディレクトリ をツリーのルート({arch})に作ります。

{arch} サブディレクトリは、プロジェクトツリーのルートであることを 示しています:

        % larch tree-root
        /usr/lord/wd/hello-world

larch は、このツリーがどのアーカイブバージョンのためのもので あるかを知っています:

        % larch tree-version
        lord@emf.net--2003-example/hello-world--mainline--0.1

最後に、arch はinit-treeに渡す バージョンのために、patch logと呼ばれるものを 作ります:

        % larch logs
        lord@emf.net--2003-example/hello-world--mainline--0.1

あとの章で、patch log がなんのためにあるのかを説明します。

いままで、プロジェクトツリーを単にソースとしてだけ見てきました: アーカイブ中にまだ何も新しいものは保存していません。これからそうしようと 思いますが、その前に、最初に触れておかなくてはならな重要なトピックが あります: ソースの目録です。次の章でこれについて 触れます。

上の例で間違ってタイプしたとしましょう:

        % larch init-tree hello-world--mainlin--0.1

ひとつの「乱暴な」解決法は、単に{arch}サブディレクトリ を削除して、もう一度やり直すことです。しかし、後のことを考えると、この方法は望ましく ありません:{arch}サブディレクトリは削除したくないようなデータも 含んでいるからです。それで、あとでもっと高度なコマンドを導入します。

init-treeのあやふやな呼び出しの後で、ふたつの問題がおこります。 以下のコマンドの両方の出力は、望んでいるものではありません:

        % larch tree-version
        lord@emf.net--2003-example/hello-world--mainlin--0.1

        % larch logs
        lord@emf.net--2003-example/hello-world--mainlin--0.1

ツリーのtree-versionはいつでも変えることができます:

        % larch set-tree-version hello-world--mainline--0.1
        
        % larch tree-version
        lord@emf.net--2003-example/hello-world--mainline--0.1

パッチログは、少し技巧的です。不要なログを消さなくてはなりません。 そしてその後で、望んでいる内容のログを追加します。

        % larch add-log hello-world--mainline--0.1

        % larch logs
        lord@emf.net--2003-example/hello-world--mainlin--0.1
        lord@emf.net--2003-example/hello-world--mainline--0.1

        % larch remove-log hello-world--mainlin--0.1

        % larch logs
        lord@emf.net--2003-example/hello-world--mainline--0.1

警告: remove-log は危険なコマンドです: それは、指定したときには必要になるパッチログを削除してしまいます。remove-logは 上でやったように、削除されるログが本当に自分の望んだものではない時に限って利用すべきです。

init-tree は {arch} サブディレクトリを、ソースツリーの 最上位につくります。その中には何があるのでしょうか?

        % ls {arch}
        ++default-version       hello-world

        % cat {arch}/++default-version
        lord@emf.net--2003-example/hello-world--mainline--0.1

{arch}/hello-world は、かなり深いツリーのルートになっています。 パッチログは、そのツリー中に保存されます。

注意: 当り前ですが、 {arch}ディレクトリの中を手で 編集しないでください。

プロジェクトツリー中で、いくつかのファイルとディレクトリは「プロジェクト の一部」です — そのようなファイルはarchの興味 をひきます。他のファイルやディレクトリはゴミファイルであったり、編集時のバック アップファイルであったり、プログラムで生成された一時ファイルや中間ファイルで あったりします。そのようなファイルは、ほとんどのarch コマンドでは無視されるか特別の扱いを受けます。

この章ではarchがどのようにしてあるファイルに注目し、他のファイル を無視するかについて議論します。

コマンド larch inventory は、ソースファイルの一覧を表示する のに利用されます。それはたくさんのオプションをとりますが、その中には、他の種類 のファイルの一覧を表示するものもあります(たとえば、編集時バックアップファイルや ソースコード以外のファイルのすべての一覧をとるようなものです)。

何かの編集後、ソースツリーが以下のようになったとしましょう:

        % ls
        hw.c            hw.c.~1~        main.c          {arch}

ファイル hw.c.~1~ はエディタのバックアップファイルです。 larch はそれを理解し、ソース目録からそのファイルを除外します。

        % larch inventory --source
        ./hw.c
        ./main.c

larch はソースの一覧以外の一覧も表示することができます:

        % larch inventory --backups
        ./hw.c.~1~

この章は他の種類のファイルからソースファイルを選択するために archによって利用される名前規約について説明します。

名前規約はファイルのいくつかの分類に基づいています:

        . and ..                この二つは単に arch によって無視されます

        excluded                Excluded ファイルは普通ファイル一覧からは
                                省略されますが、––all
                                フラグがinventoryに渡される
                                と、以下のカテゴリのどれかの中に置かれ
                                一覧に含まれるようになります。

        source                  これはもちろんソースファイルのことです

        precious                自動的に削除されるべきではないような
                                ソース以外のファイルです

        junk                    自動的に削除されるかも知れないソース以外
                                のファイルです

        backups                 自動的に削除されるかも知れないソース以外
                                のファイルですが、削除しようとするプログラム
                                はそれをエディタのバックアップファイルと
                                して扱うべきです(たとえば、その中の一番古い
                                ものと最新のものを保存しておく、など)

        unrecognized            arch が分類の仕方を知らないようなファイルです
                                — そのような名前規約にも当てはまらないか
                                "疑わしい" 名前を持ったファイルです。

名前によってファイルを分類するアルゴリズムにはいくつかの規則があります。 ファイル名それぞれに、そのような規則が、上のリストの順番でひとつひとつ チェックされ、そのファイルに当てはまる最初の規則にたどり着くまで続け られます。

ドットファイルの除外 特別なファイル. と .. は常に目録一覧から 除外されます。

可搬ではない名前は認識されません 空白を含んだり、印字できない文字を含んでいたり、「グラブ文字」 を含んでいるファイルは常に認識不能として分類されます。 グラブ文字とは:

        ? [ ] * \

除外ファイルのテスト inventoryに、––all フラグが 与えられない場合、除外ファイルのパターンにマッチしたファイル名は 一覧から削除されます。もしディレクトリの名前が除外されると、そのディレクトリ の内容全体がスキップされます。デフォルトでは除外ファイルのパターンは、 arch自身が作った制御ファイルにマッチします:

        ^(.arch-ids|\{arch\})$

ゴミファイルのテスト このステップまで到達したすべてのファイルのうち、二つのコンマ (,,) で始まるものは、ゴミファイルとして 分類されます。arch 自身によって作られる一時ファイルは二つの コンマで始まります。さらにゴミのパターンと一致するようなファイルはすべて ゴミファイルとして分類されます。デフォルトでは、 そのパターンは(少なくとも)ひとつのコンマで始まるようなすべての名前にマッチ します。

        ^,.*$

このデフォルトパターンを使って、小技をきかせることができます。 もしソースツリー中にゴミのファイルを作りたい場合、その名前の先頭をコンマ から始まるものにしてください。

バックアップファイルのテスト デフォルトでは、バックアップファイルはこのテストまで到達したファイルのうち、 以下のどれかのパターンにマッチするもののことです:

        ^.*(~|\.~[0-9]+~)$
        ^.*\.bak|\.orig|\.rej|\.original|\.modified|\.reject)$

特殊ファイルのテスト デフォルトでは、特殊ファイルはこのテストまで到達したファイルのうち、 以下のどれかのパターンにマッチするもののことです:

     ^\+.*$
     ^(\.gdbinit|\.#ckpts-lock)$
     ^(=build\.*|=install\.*)$
     ^(CVS|CVS\.adm|RCS|RCSLOG|SCCS|TAGS)$

疑わしいファイルのテスト(認識しない) このテストまで到達したファイルのいくつかは、ソースツリー中におそらく 存在すべきではないだろうという推定のもとで、認識しない ものと して明示的に扱われます。デフォルトでは、以下の拡張子のどれかで終わるような名前は 認識しないものとして扱います:

        .o
        .a
        .so
        .core

さらに、ファイル名core は、(デフォルトでは) 認識しないものとされます。

ソースファイルテスト このテストまで到達したファイルはソースファイルとパターン比較されます。 デフォルトのパー単は以下のようなものです。このパターンは既に出てきた 除外 パターンと重なるかも知れないことに注意してください。 もし––all フラグが inventory に与えられた場合、 除外パターンは利用されず、マッチしたファイルは、 かわりにこのアルゴリズムの後のステップに「素通り」します。

        ^([_=a-zA-Z0-9].*|\.arch-ids|\{arch\}|\.arch-project-tree)$

言い換えると、デフォルトではarchの制御ファイル、制御 ディレクトリは、ソースである(もし除外しなければ)ということになります。 文字、数字、アンダースコア、あるいは等号記号で始まるファイルはソースです。

認識しないファイル このテストまで到達した残りのファイルはすべて、 認識しないものとされます。

例として、名前規約のいくつかの様子を見てみましょう。

私達のプロジェクトツリーが以下のような形であったことを思い出してください:

        % ls
        hw.c            hw.c.~1~        main.c          {arch}

それで、普通のソース一覧は:

        % larch inventory --source
        ./hw.c
        ./main.c

すべてのソースファイル(リストから何も除外しない形の場合)は:

        % larch inventory --source --all
        ./hw.c
        ./main.c
        ./{arch}/.arch-project-tree
        ./{arch}/=tagging-method

このリストのディレクトリを含めることもできます:

        % larch inventory --source --all --both
        ./hw.c
        ./main.c
        ./{arch}
        ./{arch}/.arch-project-tree
        ./{arch}/=tagging-method
        ./{arch}/hello-world
        ./{arch}/hello-world/hello-world--mainline
        [... output trimmed ...]

ソースコード以外の一覧を見ることもできます:

        % larch inventory --backups
        ./hw.c.~1~

inventoryコマンドは見たい内容に応じてたくさんのオプションをとります。

inventory によって利用される、ファイルを分類するための パターンを変更することができます。これについては後の章で説明します (付録B 参照)。

多くのシステムはソースファイルを認識するための名前規約はありますが、 arch を初めて利用する人はよく、なぜarch がこれほど たくさんのファイルの分類を持っているかを不思議に思うようです。arch が以下のような分類を持っていることを思い出してください:

        excluded
        source
        precious
        junk
        backups
        unrecognized

それぞれのグループの必要性は、以下のように説明できます:

excluded はarch の制御ファイルが特に興味を もたないような必要に一般的な場合に目録リストを簡潔な形に保つために用意されただけのものです。 これはlsコマンドの「ドットファイル」を扱う場合とよく似ていて、 inventory に対する––all フラグは、ls に対する-a フラグによく似ています。

source はarch がソースファイルを他のものと 確実に区別することができるように用意されたものです。たとえば、二つのソースツリーを比較するさい、 arch はsourceの分類中のファイルのみを比較します。

precious ファイルはarch が、そのままの形 でできる限り保持しようとするファイルです。たとえば、もし arch が あなたのためにプロジェクトツリーのコピーを必要としている場合、source ファイルと一緒にprecious ファイルもコピーします。たとえば、 ソースファイルで作業すると同時に、何かのメモをとっているとします。あなたはそのノート ファイルをソースコードの一部だとして間違って欲しくはありませんが、しかし、そのファイル を失いたくもありません。このような場合、ファイルにprecious に マッチする名前を選びます。(たとえば、+notesのような)

junk プロジェクトツリー上で作業しているときに 「使い捨て」ファイルを作りたいことがよくあります。ちょっとした テストプログラムをコンパイルしたい場合や、あるコマンドの出力結果を保存したい ような場合です。そのようなファイルがある程度たまってきたときに、どのファイルが 大事なもので、どれが消したいものかを注意深く区別せずに、後のほうのファイルだけ を一度に消してしまうことができると便利です。 junk 名はこのような目的にぴったりです。そのような使い捨てファイル を作る場合は、名前を,fooのようなものにしてください。後で 安全確実に以下のようなコマンドを実行することができます:

        % rm ,*

        % find . -name ',*' | xargs rm

        % larch inventory --junk | xargs rm

backups エディタが作るバックアップファイルや、 patch のようなプログラムによって作られるバックアップファイルは よく特殊な扱いが必要になります。たとえばエディタが「番号づけされたバックアップ 」を作る場合、それらはほとんど ゴミファイルに近いもの ですが、すべて消してしまって良いものでもく、その中のどれかだけを削除したいことが あります。

unrecognized ソースツリー中のファイルで、どのような知られたパターンにも (あるいは疑わしい名前にも)当てはまらないようなものは、 たいていの場合、何かがうまくいっていないことを示しています。 そのようなファイルを黙って無視したり precious や junkであるとして扱ったりする かわりに、arch はこのような例外に明示的なフラグを付けて、 ユーザに警告できるようにします。

全体的に、ファイル名前規約の採用は多くのプログラマにとってなじみのない規則かも 知れませんが、私が強く推奨するもののひとつです。このような規約に従うことは 簡単なことで、それによってinventory や後述の tree-lint のようなツールは、ソースコードを制御できない状態から正常に保つための助けになります。

arch の世界では、プロジェクトツリー中の全てのソースファイル(とディレクトリ)は、 ふたつの名前を持ちます: "ファイルパス"と、"目録タグ" です。

ファイルのファイルパスは、常に文字列 ./ で始まり、相対パス名称が続きます。それは、ソースツリー中でそのファイルがどこに あるかを記述するものです。

ファイルの目録タグは、ツリー中のファイルに対して一意になるように つけられた、(ほとんど)任意の文字列です。

普通、ファイルが移動すると、ファイルパスは変わりますが、 その目録タグは保存されます。

たとえば、以下のようなツリーとファイルがあるとします:

        file path               inventory tag
        ---------               -------------

        ./hw.c                  i_tag_hw
        ./main.c                i_tag_main

しかし、その後 hw.c を hello.cに名称変更しました。 その後では、以下のようになります:

        file path               inventory tag
        ---------               -------------

        ./hello.c               i_tag_hw
        ./main.c                i_tag_main

この章はどのようにしてタグがファイルに割り当てられるか、どのようにして タグが管理されるか、そしてどのようにしてそれらがarch で利用されるか、について説明します。

後の章で見るように、arch は、ソースツリーとその中にあるファイルの 変更を管理するのが得意で、そのようなツリーとファイルの 履歴に関する情報を伝えるのも得意です。

例として、アリスとボブがhello_worldプロジェクト上で一緒に作業していると しましょう。アリスは自分のツリーでhw.cに何か変更を加えます。 ボブは自分のツリーで、hw.cをhello.cに名称変更 します。

どこかの時点で、アリスとボブは、「同期をとる」必要があります。 ボブはアリスのやった変更を取り込まなくてはなりません。アリスはボブがやった 同じファイルの名称変更を取り込まなくてはなりません。

arch は同期をとるためのたくさんの仕組みを用意しています — それはarchがやることのできる最も重要なことの一つです — しかし、そのようなことのほとんどすべては、結局、changesets を計算することに帰着します。

アリスは arch に対して、彼女がやった変更を記述するチェンジセットを 作ることができ、そのチェンジセットは、彼女がhw.cにやった変更を 記述するものになるでしょう。ボブもチェンジセットを作ることができ、それは自分のした ファイル名称の変更を記述するようなものになるでしょう。

もしアリスが、ボブのチェンジセットを自分のツリーに適用すると、彼女のhw.c のコピーは、hello.cに名称変更されます。しかし、もう少し面倒なケースは 次のようなものです: もしボブが、アリスのチェンジセットを自分のツリーに適用すると、 何がおこるか? です。

アリスは ./hw.c という名前のファイルを変更しましたが、ボブのツリーの 中では、同じ変更は、./hello.cという名前のファイルに対して行われる べきです。幸運にも両方のファイルは同じ目録タグを持ちます:

        file path               inventory tag
        ---------               -------------

                 Alice's tree:
        ./hw.c                  i_tag_hw

                 Bob's tree:
        ./hello.c               i_tag_hw

アリスのチェンジセット中では、アリスのした変更は、タグがi_tag_hw であるようなファイルに対してなされた、という記述になります。

そのため、ボブのツリーに対してチェンジセットが適用されるとき、archは 同じタグを持つようなファイルにたいしてチェンジセットを適用することを知っています: それは、変更をボブの./hello.cに対して適用することを知っているわけです。

この例で、目録タグがなんのためにあるかが分かります: 目録タグは、arch が、ファイルの物理的な場所ではなく、論理的な同一性によってツリーに対してなされる変更を 記述することができるようにします。どのようにして目録タグが利用されるかについては もっと複雑なたくさんの例がありますが、ここでは少なくともこの基本的な点を見て来ました。

では、ファイルにたいしてどのような目録タグが与えられるのでしょうか? 一般的に、ファイルシステムは組み込みで、目録タグのような概念をサポート してはいません。オペレーティングシステムは組み込みの目録タグを持って いません。そのため、ユーザは、ファイルにタグを割り当て、その割り当て を管理するために、明示的な操作をする必要があります。

arch はその方法について選択させます。ファイルにタグを 割り当てるための三つの方法があります。最初にプロジェクトを作る時に、 この三つの方法のどれかを選びます。

それらの方法については簡単にここで導入し、詳細はその後に説明することに します。

タグづけの名前による方法 単にタグに関して無視することもできます — まったく利用 しないというものです。これは、タグづけの名前による方法、と呼ばれて います。この方法ではそれぞれのファイルの目録タグは、本質的にはそのファイルのパス名 と同じになります。結果として、ファイルを名称変更した場合、そのタグも変わります。

           The names Method of Tagging


        file path               inventory tag
        ---------               -------------

                Before a rename
        ./hw.c                  ?./hw.c

                 After a rename

        ./hello.c               ?./hello.c

ファイルが名称変更された場合に、ツリー間でその変更を同期させる必要がなければ、 名前によるタグづけは一番簡単な方法です。

タグづけの明示的な方法 明示的な 方法では、目録タグはファイルとは独立に .arch-idsという名前のサブディレクトリに保存されます。 この方法を使うのは、CVSのような古いリビジョン管理システムを使うのと よく似た方法です: もし新しいソースファイルを追加するなら、それにタグをつけるために、 larch addコマンドを使わなくてはなりません。 もしファイルを削除する なら、タグを削除するためにlarch deleteコマンドを使わなくてはなりません。 また、対応するタグファイルを移動するのに、larch moveコマンドを使わな くてはなりません。これは実績のある方法ですが、ユーザによっては、 add, delete, や move のような コマンドを使うのを不便に思う人もいます。

タグづけの暗黙的な方法 暗黙的な 方法は、明示的な方法と、 名前による方法のスーパーセットです。 特定のファイルに対して、タグを定義しないこともできます — その場合、名前による方法のように扱われます。 larch addを使ってタグを定義することもできます — この場合、 明示的な方法のように扱われます。しかし、 暗黙的な方法の本当の便利さは、次のような ものです: そのファイルの先頭または末尾付近に特殊な形式の文字列を埋め込むことに よってファイルにタグを定義することもできます (たとえば、ソースファイルのコメント部分などに)

新規ユーザにとっては一番馴染みのない方法であるとは思いますが、 暗黙的な 方法を使うことを強く進めます。 以下で見ていくように、それは、欠点を十分に補うだけの利点があります。

ツリーのタグづけ方法の設定や確認のためには tagging-method コマンドを使います:

        % cd ~/wd/hello-world

        # set the tagging method
        # 
        % larch tagging-method implicit


        # check the tagging method
        # 
        % larch tagging-method
        implicit

タグづけの方法の設定時に有効な値は、names, explicit, そして implicit のどれかです。

名前による タグづけを使いたいのなら、以下のようなコマンドを使います:

        % larch tagging-method names

このコマンドの後では、すべてのファイルはツリーのルートからの相対的な パスから作られるタグを持つようになります。

(繰り返しになりますが、名前による タグづけの方法は、 ファイルが名称変更された場合にチェンジセットがきれいに働かないという 欠点があることに注意してください)

明示的な タグづけの方法を使いたい場合は以下のようなコマンドを使います:

        % larch tagging-method explicit

明示的な 方法を使う場合、(普通は)すべてのファイルとディレクトリ に対してlarch addを使ってタグを付ける必要があります:

        % larch add FILE

もしFILE がディレクトリなら、それは FILE/.arch_ids/=id を作ります。もし通常のファイルであるか、シンボリックリンクである場合は、それは(同じディレクトリ 内に).arch_ids/FILE.idを作ります。どちらの場合でも、その作成されたファイルには ファイル対する自動的に生成されたタグを含んでいます。

通常のファイルやシンボリックリンクを削除する時には、以下のコマンドを利用しなくては なりません:

        % larch delete FILE

これは FILE 自身を削除することはありませんが、 FILE の目録タグを削除します。

ディレクトリを削除するには、.arch_idsサブディレクトリを自分で 削除しなくてはなりません。これはまた暗黙的に、そのディレクトリに保管されている archが押えていた全てのファイルの目録タグを削除します。 (たとえば、ディレクトリを削除するためのrm -rfの利用は、そのタグも 削除します。)

通常のファイルやシンボリックリンクを名称変更する場合に、以下のコマンドを使うと:

        % larch move OLD-NAME NEW-NAME

そのファイルの目録タグが移動します。

利用にあたっての注意: larch moveは、unix のmvのようには働きません。 特に NEW-NAME はファイル名でなくてはなりません — ファイルが移動する先のディレクトリの名前であってはなりません。

ディレクトリを名称変更する場合、その目録タグ(とそのディレクトリに 含まれるすべてのファイルとサブディレクトリのタグ)はそれと一緒に自動的に 移動します (理由は、.arch_ids サブディレクトリが移動されるからです)。

明示的なタグづけした作業ディレクトリ中で larch inventory を実行 すると、明示的に選ばれたソースファイルだけが一覧表示されます。 ソースファイルの名前規約に渡された全てのファイルの一覧を見たい場合には 以下のようなコマンドを使います:

        % larch inventory --source --names

tree-lint についても読んでください。( 物事を単純に保つこと項参照).

暗黙タグを利用する場合は、プロジェクトツリー中で以下のコマンドを 使ってください:

        % larch tagging-method implicit

この方法では: タグが割り当てられていないファイルはすべて、 その位置に基づいたタグが割り振られます — それは 名前による 方法の場合と一緒になります。larch addで割り当てられたタグをもつ ファイルは、そのタグを使います — それは明示的な方法の 場合と一緒になります。しかし、さらに、ファイルの先頭または末尾付近に特殊な形式の 文字列を追加することによってファイルにタグづけすることもできます。

ファイル中に埋め込む形のタグは、ファイルの先頭または末尾の1024バイト 以内に現れる一行で、以下の形をしています:

        <punct>tag:<spaces><tag>

例えば:

        /* tag: main for the hello world program
         */

注意: 目録タグの先頭または末尾の空白はタグの一部とは みなされません。タグ中で、表示できない文字は_で置き換えられます。 例えば、以下のようなタグを書いた場合:

        main for the hello    world program

実際の目録タグは以下のようになります:

        main_for_the_hello____world_program

以下のようなコマンド:

        % larch tree-lint

は、物事を単純に保つのに役にたちます。

明示的な タグづけの方法を使っているなら、 上記のコマンドは、どのファイルにも対応しないタグがどれであるかを 教えてくれます。それは、名前による規約を破りはしないが、明示的なタグは存在しない ようなファイルを教えてくれます。

もし暗黙的な タグを使う場合は、タグが見つからないすべてのファイル について教えてくれます — 明示的なタグ、暗黙的なタグの両方についてです。 また、明示的なタグでファイルに対応していないものについても教えてくれます。

どちらの場合でも、あるいは、名前による タグづけの方法を使った 場合でも、tree-lint は、名前による規約に合致しないすべてのファイル について教えてくれます。

最後に、もし、明示的なまたは暗黙的なタグを使っている場合、 tree-lint は複数のファイルで同じタグを使っているものをチェックします。もし二つのファイルが同じタグを 使っている場合、タグを編集するか(もしファイル自身の中にある場合)、重複している明示的な タグを置き換えるためにdelete と addコマンドを使って 修復しなくてはなりません。

以前までの章でやってきた例の続きです:hello-worldプロジェクトに 暗黙的なタグづけの方法を使ってみましょう:

        % cd ~/wd/hello-world

        % larch tagging-method implicit

さて、tree-lint は、何を報告するでしょうか?

        % larch tree-lint
        [...]
        ** WARNING: untagged files
        
           This directory uses the "implicit" inventory method, but
           these files do not have either implicit or explicit tags.
        
        *** file-list
        
                ./hw.c
                ./main.c

タグを追加するためにソースファイルを編集すると、:

        % tail -3 main.c
        
        /* tag: main module of the hello-world project
         */
        % tail -3 hw.c
        
        /* tag: hello_world module of the hello-world project
         */

それから、tree-lint を実行すると警告は出なくなります。

利用に関する注意 1: {arch}中のどのファイルにもタグをつけなかったことに注意して ください。arch はすべての制御ファイルに暗黙的なタグを用意 します。

利用に関する注意 2: 今回の小さなサンプルプロジェクトではarchコントロールディレクトリ 以外のサブディレクトリはありません。もしそのようなサブディレクトリがある場合は、 それに対してlarch addでタグを付けたいと思うかも知れません。

ある状況では、全てのファイルに明示的なタグをつけたり、暗黙的なタグをつけたりする のが不便なことがあります。

あるディレクトリ中のファイルに明示的なタグをつけないような場合に、 "デフォルトのタグ"を設定することができます。以下のようなコマンドを使います:

        % larch explicit-default TAG-PREFIX

この後では、そのディレクトリ中のファイルで明示的なタグがついていないものにも タグが割り当てられます:

        TAG-PREFIX__BASENAME

ここで BASENAME はファイルのベース名です。 この方法で作られたデフォルトタグは、ファイルに埋め込まれた暗黙的なタグに 優先します。あるディレクトリのデフォルトタグを確認するには:

        % larch explicit-default
        TAG-PREFIX

そしてそのデフォルトを削除るすには:

        % larch explicit-default --delete

また、暗黙的なタグよりも低い優先順位を持ったデフォルトタグを指定する こともできます:

        % larch explicit-default --weak TAG-PREFIX

そしてそのデフォルト値を表示するには:

        % larch explicit-default --weak

あるいは削除する場合は:

        % larch explicit-default --weak --delete

暗黙的なタグを使っているとき、タグづけされていない(明示的に、または暗黙的に)たくさんの ファイルがあるディレクトリがあるのだが、そのようなファイルをtree-lint によって生成されるタグづけされていないファイルとして報告して欲しくないことがあります。 そのようなファイルにたいしてtree-lintを黙らせるための二つの方法が あります。

ひとつは、デフォルトの明示的なタグあるいは、弱いデフォルトの明示的なタグを 前に説明したlarch explicit-defaultを使って用意することです。

もう一つの方法は、「無視」というラベルをそのディレクトリに付与することです — そのラベルは、tree-lint がタグづけされていないファイルについて不平を言わない という意味をもつものです。そうするには:

        % larch explicit-default --dont-care set

あるいは、「無視」フラグを削除するには:

        % larch explicit-default --delete --dont-care

あるディレクトリに「無視」フラグが設定されているかどうか を知るためには:

        % larch explicit-default --dont-care

アーカイブに、新しいhello-worldの"リビジョン"をいままさに作ろうとして いるところです: リビジョンとは、そのプロジェクトがある特定の時点でどのように見えるか という記録のことです。

新しいリビジョンを作るときは常に、そのリビジョンについてのログファイルを 作ります。

        % cd ~/wd/hello-world

        % larch make-log
        ++log.hello-world--mainline--0.1--lord@emf.net--2003-example

このコマンドからの出力は、いま編集しなくてはならないファイルの名前です。 初期状態では、それは以下のものを含んでいます:

        Summary: 
        Keywords: 

このファイルに、ちょうど emailメッセージのような内容を埋めてやる必要があります。 Summary:フィールドのリビジョンについての短い記述を追加し、 本体に詳細な記述を追加します。emailと同様、本体は空行でヘッダーと分ける必要が あります。これが終った時点で、ログは以下のような形になります:

        Summary: initial import
        Keywords: 

これはhello-worldの最初のインポートで、この驚異的なプログラムは 私たちの新しい .com カンパニーを飛躍させるものになるでしょう。

vi ユーザに対しての注意: ログメッセージのデフォルトのファイル名称は+ で始まります。viは、+で始まる 引数を、普通の引数と考えず、オプションとして扱うという意味で 非標準的なプログラムです。そのため、viにファイル 名称を渡すことを確実にするために、./で始めて ください。以下のような感じです:

    % vi ./++log.hello-world--mainline--0.1--lord@emf.net--2003-example

(今後、ログファイルのデフォルト名称を変更する予定があり、そうなれば ./ は不要になります。)

最後に arch に対してアーカイブにソースを追加するように 指示することができます:

        % larch import
        [....]

いくつかの方法で、このコマンドの副作用を見ることができます。

ます、今回のプロジェクトについて、アーカイブ中に どのようなリビジョンが存在しているかを arch に問い合わせることが できます:

        % larch revisions hello-world--mainline--0.1
        base-0

実際にはもっと詳細情報を得ることもできます:

        % larch revisions --summary --creator --date \
                          hello-world--mainline--0.1 
        base-0
            2003-01-28 00:45:50 GMT
            Tom (testing) Lord <lord@emf.net>
            initial import

プロジェクトツリー中で何が変更されたのでしょうか? "パッチログ"と呼ばれるものがあるのを思い出してください:

        % larch logs
        lord@emf.net--2003-example/hello-world--mainline--0.1

いまの場合それは、以下のエントリーを持ちます:

        % larch log-ls hello-world--mainline--0.1
        base-0

        % larch log-ls --summary --creator --date \
                       hello-world--mainline--0.1
        base-0
            2003-01-28 00:45:50 GMT
            Tom (testing) Lord <lord@emf.net>
            initial import

        % larch cat-log hello-world--mainline--0.1--base-0
        Revision: hello-world--mainline--0.1--base-0
        Archive: lord@emf.net--2003-example
        Creator: Tom (testing) Lord <lord@emf.net>
        Date: Mon Jan 27 16:45:50 PST 2003
        Standard-date: 2003-01-28 00:45:50 GMT
        Summary: initial import
        Keywords: 
        New-files: ./hw.c ./main.c
        New-patches: \
          lord@emf.net--2003-example/hello-world--mainline--0.1--base-0

        This is the initial import of hello-world, the killer app
        that will propel our new .com company to a successful IPO.

import はアーカイブ中に新しいリビジョンを作ります。 作成されたリビジョンはbase-0と呼ばれますが、カテゴリ、 ブランチ、そしてバージョン名を付けてそのリビジョンのもっと長い名前を 作ることもできます。

        hello-world--mainline--0.1--base-0
        ^^^^^^^^^^^  ^^^^^^^^  ^^^  ^^^^^^
             |          |       |     |
             |          |       |    patch level name
             |          |       |
             |          |     version number
             |          |
             |     branch name
             |
         category name

アーカイブ名を追加する場合、"完全に修飾されたリビジョン名"とでも言うべき 名前を手に入れることができますが、それは、そのリビジョンの大域的にユニーク な名前になります:

    lord@emf.net--2003-example/hello-world--mainline--0.1--base-0
    ^^^^^^^^^^^^^^^^^^^^^^^^^^
                |
          archive name

完全な修飾名は後の章で分散リポジトリに関して学ぶにつれて、 その重要性を増していきます。

import がアーカイブに与える効果について見てみましょう:

        # cd to the directory for the version we are working 
        # on:
        # 
        % cd ~/{archives}
        % cd 2003-example/
        % cd hello-world/
        % cd hello-world--mainline/
        % cd hello-world--mainline--0.1/
        % ls
        % ls
        +version-lock   =README         base-0

それは、リビジョンのために新しい base-0 ディレクトリを作ります。

        % cd base-0
        % ls
        +revision-lock
        hello-world--mainline--0.1--base-0.src.tar.gz
        log

+revision-lock ファイルは常にarchがどのような状況に おいても一貫した状態をとり続けるために内部的に利用されます。

log ファイルは、自分が付けたログメッセージのコピーに いくつかの追加ヘッダーをつけくわえたものです:

        % cat log
        Revision: hello-world--mainline--0.1--base-0
        Archive: lord@emf.net--2003-example
        Creator: Tom (testing) Lord <lord@emf.net>
        Date: Mon Jan 27 16:45:50 PST 2003
        Standard-date: 2003-01-28 00:45:50 GMT
        Summary: initial import
        Keywords: 
        New-files: ./hw.c ./main.c
        New-patches: \
          lord@emf.net--2003-example/hello-world--mainline--0.1--base-0

        This is the initial import of hello-world, the killer app
        that will propel our new .com company to a successful IPO.

最後に圧縮された tar ファイルは、プロジェクトツリーにあるソースファイルの コピーです:

        % tar ztf hello-world--mainline--0.1--base-0.src.tar.gz
        hello-world--mainline--0.1--base-0/
        hello-world--mainline--0.1--base-0/hw.c
        hello-world--mainline--0.1--base-0/main.c
        hello-world--mainline--0.1--base-0/{arch}/
        hello-world--mainline--0.1--base-0/{arch}/.arch-project-tree
        hello-world--mainline--0.1--base-0/{arch}/=tagging-method
        hello-world--mainline--0.1--base-0/{arch}/hello-world/
        [....]

tar ファイルはプロジェクトツリー中のすぺてのファイルを含んでいるわけで はないことに注意してください。それは、以下のコマンドで一覧表示されるファイルを含んでいます:

        % cd ~/wd/hello-world

        % larch inventory --source --both --all
        [....]

最後に、プロジェクトツリーの {arch} サブディレクトリをのぞいてみると、 二つの新しいアイテムができていることに気づくと思います:

        % ls
        ++default-version       =tagging-method
        ++pristine-trees        hello-world

ディレクトリ ++pristine-trees は、インポートされたツリーのコピー (ある深さの) を含んでいます。これは、他のarchコマンドによって利用される キャッシュコピーです。(archの今後のリリースでは、 ++pristine-trees サブディレクトリは別の仕組みによって置き換えられるかも 知れません。)

hello-world (パッチログ)ディレクトリの周辺をのぞいてみると、 今作ったばかりのリビジョンのログファイルのコピーを見つけることができます( 追加のヘッダーが付け加えられた形で見えます)。

hello-world のソースコードを見れば、スペルミスと、改行バグがあるのが わかるはずです:

        % cat hw.c

        #include <stdio.h>

        void
        hello_world (void)
        {
          (void)printf ("hello warld");
        }

        
        /*tag: hello_world module of the hello-world project
         */

明らかにhello warld ではなく、hello worldと出力したい わけですし、多分メッセージの最後では改行を出力するのが普通でしょう。それでこれらのバグを 修正しましょう。

これらのバグを修正するための計画があります: 私たちはソースを修正してこのバグを直します。 それからarch に、アーカイブ中のバグを修正するのに必要な変更を記録する ように言います。二番目のステップは新しいリビジョンをアーカイブに 作ります。

前に言ったように、新しいリビジョンを作るときはいつでもそのリビジョンのための ログメッセージ を用意する必要があります。 最初のログファイルの作成項

今回の簡単な例で直そうとしているバグは非常につまらないものです — しかし、現実の状況では、それはもっと複雑なものになりえます。あなたは 選ぶことができます: あなたの修正点を説明するログメッセージを書くために すべての変更が終了するまで待つこともできますし、ログメッセージだけを書いて おくこともできます。

アドバイス: ログメッセージだけを書きましょう。言い換えると、ハックしたつど、 記録をとりましょう。larch コマンドでは、それは、バグ修正 の処理を以下のコマンドで始めることを意味します:

        % cd ~/wd/hello-world

        % larch make-log
        ++log.hello-world--mainline--0.1--lord@emf.net--2003-example

それから新しいログファイルを編集するのに、以下を読み込みます:

        Summary: Fix bugs in the "hello world" string
        Keywords: 

Summary: はこれからやる変更に関連したものとしての説明になります。 作業をすすめるたびに、ログメッセージの変体に記録をとっていきます。

これらのバグは実際よりも複雑であるとします。この場合作業がどのように進むかを 説明します:

        Summary: Fix bugs in the "hello world" string
        Keywords: 

        Spell "world" correctly (not "warld").

        Summary: Fix bugs in the "hello world" string
        Keywords: 

        Spell "world" correctly (not "warld").

        Add a newline to the hello world message.

        % larch what-changed --diffs
        [....]
        *** patched regular files
 
        **** ./hw.c
        [....] 
             @@ -4,7 +4,7 @@
              void
              hello_world (void)
              {
             -  (void)printf ("hello warld");
             +  (void)printf ("hello world\n");
              }
        [....]

        % larch commit
        [....]

        % larch revisions hello-world--mainline--0.1
        base-0
        patch-1

        % larch revisions --summary hello-world--mainline--0.1
        base-0
            initial import
        patch-1
            Fix bugs in the "hello world" string

        % larch log-ls hello-world--mainline--0.1
        base-0
        patch-1

        % larch log-ls --summary hello-world--mainline--0.1
        base-0
            initial import
        patch-1
            Fix bugs in the "hello world" string

        # cd to the directory for the version we are working 
        # on:
        # 
        % cd ~/{archives}
        % cd 2003-example/
        % cd hello-world/
        % cd hello-world--mainline/
        % cd hello-world--mainline--0.1/
        % ls
        % ls
        +version-lock   =README         base-0          patch-1

        % cd patch-1

        % ls
        +revision-lock
        hello-world--mainline--0.1--patch-1.patches.tar.gz
        log

        % cat log
        Revision: hello-world--mainline--0.1--patch-1
        Archive: lord@emf.net--2003-example
        Creator: Tom (testing) Lord <lord@emf.net>
        Date: Mon Jan 27 22:26:13 PST 2003
        Standard-date: 2003-01-28 06:26:13 GMT
        Summary: Fix bugs in the "hello world" string
        Keywords: 
        New-files: \
          {arch}/hello-world/ [....] /patch-log/patch-1
        Modified-files: hw.c
        New-patches: \
          lord@emf.net--2003-example/hello-world--mainline--0.1--patch-1

        Spell "world" correctly (not "warld").

        Add a newline to the hello world message.

.patches.tar.gz ファイルは、何か チェンジセットと 呼ばれるようなものです。それはbase-0と、patch-1のリビジョン間 の差分として、あなたの変更点を記述したものです。後の章でチェンジセットの性質についてもっと詳しく 学ぶことになるでしょう。いまは、チェンジセットを、あなたが変更を加える前のbase-0 リビジョンと変更を加えたあとの、同じツリーとの間で実行したdiff -rの出力と 同様のものとしてとらえることができます。 (あるいは、arch ユーザの一人によれば: ステロイド上のパッチセット、となります)

        % cd ~/wd/hello-world

コミットコマンドは二つの効果を持ちます。一つは、 {arch}/hello-world配下に、ログファイルを追加します。第二に、base-0 リビジョンの代わりに、patch-1リビジョンのキャッシュコピーを含むように、 {arch}/++pristine-trees を書き換えます。

まだプロジェクトツリーが残っているかも知れません。その場合は、それを いったん削除してください:

        % cd ~/wd

        % ls
        hello-world

        % rm -rf hello-world

hello world プロジェクトの最後のソースを手にいれたいとしましょう。 それには、get コマンドを使います:

        % larch get hello-world--mainline--0.1 hello-world
        [...]


        % ls 
        hello-world

        % ls hello-world
        hw.c    main.c  {arch}

hello-world のもっと前のバージョンをチェックアウト したいとしましょう。

前の例では、プロジェクトの特定のバージョンを要求したことに注意してください:

        % larch get hello-world--mainline--0.1 hello-world
                    ^^^^^^^^^^^  ^^^^^^^^  ^^^ ^^^^^^^^^^^
                         |           |      |       |
                         |           |      |  target directory
                         |           |      |
                         |           |      |
                         |           |   version number
                         |           |
                         |      branch name
                         |
                   category name

patch level を明示的に指定することで、もっと以前のリビジョンを 手にいれることができます:

        % larch get hello-world--mainline--0.1--base-0 hello-world-0
                    ^^^^^^^^^^^  ^^^^^^^^  ^^^  ^^^^^^ ^^^^^^^^^^^^^
                         |           |      |      |        |
                         |           |      |      |  target directory
                         |           |      |      |
                         |           |      | patch level name
                         |           |      |
                         |           |   version number
                         |           |
                         |      branch name
                         |
                   category name




        % ls
        hello-world     hello-world-0

        % ls hello-world-0
        hw.c    main.c  {arch}

base-0 から patch-1 になされた変更点を見ることができます。 たとえば、diff -rを使えばできます:

        % diff -r hello-world-0 hello-world
        diff -r hello-world-0/hw.c hello-world/hw.c
        7c7
        <   (void)printf ("hello warld");
        ---
        >   (void)printf ("hello world\n");
        [...]

base-0 リビジョンを抽出するのは簡単です。思い出すことができるように、 base-0 リビジョンは、完全なソースツリーの圧縮された tar ファイルとして 保存されています( どのように働くか — インポートの効果項参照)。 base-0の抽出を指示すると、getコマンドは本質的には 単にその tar ファイルを展開するだけです。

patch-1 リビジョンの抽出は、二つのステップで実行されます。 patch-1 は base-0 と patch-1 の間の差分を記述したchangeset として保存されていることを思い出して ください。(どのように動作するか — 新しいリビジョンのコミット項参照)。 それで get は、最初にbase-0リビジョンを抽出し、 次にpatch-1を抽出し、そのチェンジセットをbase-0を 変形するのに利用することで、patch-1のツリーに変化します。 内部的には、get は、larchのコマンド、dopatch を チェンジセットを適用するのに使います。もし、diff/patchパッチセットに なじみがあるのなら、dopatch を、「ステロイドの上へのパッチ」 と考えることもできます。

ひとつの変更をコミットするかわりに、たくさんの変更をコミットしたとしましょう: patch-1 のリビジョンだけではなく、 patch-2, patch-3 などなど。本質的には getは、要求したリビジョンを 作るために、それぞれのチェンジセットを適用します。

注意: 実際には get は、上に説明したよりも、もう少し複雑なことをします。 たくさんのチェンジセットを適用しなくてはならないことを考慮して、get は最適化されています。一方、commitではなく、tagによって 作られたリビジョンもあるかも知れません。その場合は別の規則が適用されます。後の章でこの例外 について学ぶでしょう。

思いだすことができると思いますが、アーカイブは、論理名と物理位置を持って いるのでした:

        % larch archives
        lord@emf.net--2003-example
        ^^^^^^^^^^^^^^^^^^^^^^^^^^
          |     /usr/lord/{archives}/2003-example
          |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
          |                     |
          |              archive location        
          |
        archive name

(See xref:"Creating a New Archive".)

いくつかのアーカイブはネットワーク越しにアクセスすることができ、 現在のところ、以下のプロトコルが利用可能です:

        FTP
        SFTP
        WebDAV
        plain HTTP

この章の後のほうで、どうやってそのようなアーカイブを作るかについて 学びます。

いまは、そのようなアーカイブにアクセスするためには、そのアーカイブの名前と URLを使って表現された物理位置を登録する必要があるということを知っておいてください。

例えば、 HTTP か WebDAV を使ってアーカイブにアクセスするには:

    % larch register-archive lord@emf.net--2003 \
            http://regexps.srparish.net/{archives}/lord@emf.net--2003

FTPを使うなら:

    % larch register-archive lord@regexps.com--2002 \
            ftp://ftp.regexps.com/{archives}/lord@regexps.com--2002

このようなコマンドがうまくいったかどうかを確認することができます:

    % larch archives
    lord@emf.net--2003
            http://regexps.srparish.net/{archives}/lord@emf.net--2003
    lord@emf.net--2003-example
            /usr/lord/examples/{archives}/2003-example
    lord@regexps.com--2002
            ftp://ftp.regexps.com/{archives}/lord@regexps.com--2002

追加のアーカイブを登録した後、どのようにそれにアクセスすれば良いのでしょうか?

単純なやりかたとしては、そのアーカイブをデフォルトに設定してしまう というのがあります:

        % larch my-default-archive lord@emf.net--2003

        % larch categories
        [...categories in the remote archive...]

デフォルトアーカイブを変更するのは、もちろん不便です。 そこで、例で使っていたアーカイブをデフォルトに戻しておきます:

        % larch my-default-archive lord@emf.net--2003-example

リモートアーカイブにアクセスするには他に二つの方法があります:

アーカイブ上の操作をするすべてのコマンドは -A オプションを受け入れますが これはデフォルトアーカイブを上書きするために使うことができます:

        % larch my-default-archive
        lord@emf.net--2003-example

        % larch categories -A lord@emf.net--2003
        [... categories in lord@emf.net--2003 ...]

利用についての注意: -A 引数は、デフォルトアーカイブよりも優先順位が高いですが、 完全に修飾されたプロジェクト名称によってさらに上書きされてしまいます (以下を参照)。

プロジェクト名を受け入れるコマンドは、"完全に修飾されたプロジェクト名" を使うことができます。完全に修飾された名前は、アーカイブ名称を接頭辞とし、 スラッシュが続き、その後にプロジェクト名を続けたものです:

   category name:
   arch                     => lord@emf.net--2003/arch

   branch name:
   arch--devo               => lord@emf.net--2003/arch--devo

   version name:
   arch--devo--1.0          => lord@emf.net--2003/arch--devo--1.0

   revision name:
   arch--devo--1.0--patch-1 => lord@emf.net--2003/arch--devo--1.0--patch-1

この例では:

        % larch my-default-archive
        lord@emf.net--2003-example

        % larch branches lord@emf.net--2003/arch
        [... branches of arch in lord@emf.net--2003 ...]

利用にあたっての注意: 完全に修飾された名前は、-Aオプションと、 デフォルトアーカイブのどちらにも優先します。

オペレーティングシステムとサーバアクセス制御は読み込み専用アクセス に対して、数人またはすべてのユーザを制限するために利用することができます。 例えば、FTPは普通、匿名ユーザに読み込みを許しますが、アーカイブの修正は許しません。

互換性についての注意: この節で記述されるしくみは、今後のリリースでは変更されるかも知れません。ミラーは もっときれいな形でサポートされるでしょう。しかし、このしくみは、作業する上で 「十分うまく」動作しているので、現在のところ広く利用されています。

arch のよくある使い方は、ローカル(つまり、ネットワークアクセスできない )アーカイブで、普通の作業をし、"アーカイブミラー"を作ることによってネットワーク上に そのアーカイブを"公開"することです。

ミラーは以下のようにして作ります:

    % larch push-mirror lord@emf.net--2003 lord@emf.net--2003-mirror
    [....]

利用に関する注意: ユーザは push-mirror コマンドを手で実行してはいけません。 そのかわり、以前コピーしたアーカイブの部分についての記録をとることによってpush-mirror を最適化するnotifierと呼ばれるものを作ります。 notifier については、後の章でより詳しく学びます ( 第29章参照)。

利用についての注意: ネットワーク越しにアクセス可能なミラーについて他の人に公開する場合、 あなたのlocalなアーカイブの名前でそのミラー を登録するように言ってください。リモートユーザに関する限り、そのミラーは あなたのローカルアーカイブと同じものです。

複数のアクセス方法を経由することができるような一つのアーカイブを作る ことを防げることは何もありません。例えば、FTPのディレクトリを含むような マシン上のローカルファイルシステムの場所を使ってアクセスできるFTPアーカイブ を登録することもできますが、その同じアーカイブを、別の人には ftp: 形式のURLとして登録することもできます。

アーカイブは、FTPサーバが利用できるような場所の中にあるディレクトリの どこかに単に配置するだけで、FTPアクセス可能となります。

セキュリティーに関する注意: FTPアクセス可能なアーカイブを作る場合、二つの重要なセキュリティ上の考慮が必要になります: 平文でのパスワードと、 FTP サーバの設定です。

平文でのパスワード よく知られているように、FTPプロトコルはパスワードを、暗号化せずにネットワーク上を 流します。多くの場合、それは受け入れられないセキュリティリスクと考えられる ので、FTPアクセスは、公開データのみに利用し、読み込み専用アクセスとすべきかも 知れません。

FTP サーバの設定 一般的に言って、FTPサーバを十分セキュアに設定するには、オペレーティングシステムと 利用するFTPサーバの実装についての関連したドキュメントを注意深く、十分に理解する 必要があります。

[これはまだドキュメント化されていません]

[これはまだドキュメント化されていません]

アリスとボブの両者がhello-worldプロジェクト上で作業し、 一つのアーカイブを共有しているとしましょう。我々の例では、両方の役割を同時に こなすことにします。

最初に、両方のプログラマーはそれぞれ自分自身のプロジェクトツリーが必要に なります。

        % cd ~/wd

        % [ ... remove any directories left from earlier examples ...]


        % larch get hello-world--maineline--0.1  hello-world-Alice
        [....]

        % larch get hello-world--maineline--0.1  hello-world-Bob
        [....]

アリスのタスクは、それぞれのファイルに、いくつかの合理的な注釈を付け加える ことです。それが終った時点で(しかし、アーカイブにはまだ変更をcommit していないという前提では)ファイルは以下のようになっています:

        % cd ~/wd/hello-world-Alice

        % head -3 main.c
        /* Copywrong 1998 howdycorp inc.  All rights reversed.*/

        extern void hello_world (void);

        % head hw.c
        /* Copywrong 1998 howdycorp inc.  All rights reversed. */

        #include <stdio.h>

一方ボブは、mainに、もっと多くのコメントを追加していたとします:

        % cd ~/wd/hello-world-Bob

        % cat main.c
        extern void hello_world (void);

        int
        main (int argc, char * argv[])
        {
          hello_world ();

          /* Exit with status 0
           */
          return 0;
        }

        /* tag: main module of the hello-world project
         */

二人のプログラマーは修正されたバージョンのhello-worldを持って いて、両者とも、相手の修正を反映していないことに注意してください。

ボブが自分の変更を先にコミットしようとしたとします。 すでにみてきたように、これには二つのステップをとります。

最初にボブはログメッセージを用意します:

   % cd ~/wd/hello-world-Bob

   % larch make-log
   ++log.hello-world--mainline--0.1--lord@emf.net--2003-example

   [Bob edits the log message.]

   % cat ++log.hello-world--mainline--0.1--lord@emf.net--2003-example
   Summary: commented return from main
   Keywords: 

   Added a comment explaining how the return from main
   relates to the exit status of the program.

それからcommitを実行します:

   % larch commit
   [...]

今度はアリスの番です:

   % cd ~/wd/hello-world-Alice

   % larch make-log
   ++log.hello-world--mainline--0.1--lord@emf.net--2003-example

   [Alice edits the log message.]

   % cat ++log.hello-world--mainline--0.1--lord@emf.net--2003-example
   Summary: added copywrong statements
   Keywords: 

   Added copywrong statements to the source files so 
   that nobody can steal HowdyCorp's code.

それからコミットしようとします:

   % larch commit
   [....]
   commit: project tree out of date

     Working directory is missing these patches:

           patch-2

     Unable to complete "commit".

   Try "larch update --help" or "larch commit --out-of-date-ok"

ここでの問題は、ボブの変更はすでにアーカイブに保存されていますが、 アリスのツリーはその変更が反映されていない、というところです。

commit コマンドはアリスに、このツリーが「最新ではない」 ということを伝えます。それは、アリスのツリーがまだコミットする前に、アーカイブに対して 変更がすでにコミットされた、ということを意味します。

彼女はこの状況について、彼女のツリーに何が足りないのかを問い合わせることに よってもう少し深く調べることができます。

        % larch whats-missing
        patch-2

あるいは更に詳細に:

        % larch whats-missing --summary
        patch-2
            commented return from main

それは、ボブのログメッセージからのSummary:行として理解すべき です。

さらに深く調べるためには (以前導入した) revisions コマンドを使うこともできます( アーカイブ中への最初のリビジョンの保存項参照)。

彼女はボブのログメッセージ全体を参照することができます:

    % larch cat-archive-log hello-world--mainline--0.1--patch-2
    Revision: hello-world--mainline--0.1--patch-2
    Archive: lord@emf.net--2003-example
    Creator: Tom (testing) Lord <lord@emf.net>
    Date: Wed Jan 29 12:46:50 PST 2003
    Standard-date: 2003-01-29 20:46:50 GMT
    Summary: commented return from main
    Keywords: 
    New-files: {arch}/hello-world/[....]
    Modified-files: main.c
    New-patches: \
      lord@emf.net--2003-example/hello-world--mainline--0.1--patch-2

    Added a comment explaining how the return from main
    relates to the exit status of the program.

そのメッセージのヘッダを見ることによって、アリスは例えば、 ボブがファイルmain.cを修正したことを知ることが できます。

あとの章で、アリスがボブのした変更について知るために利用できる よりおおくのコマンドについて降れます。しかし今はアリスが どのようにして彼女のツリーにそのような変更を追加することができるか について見てみましょう。

アリスは自分の変更をcommitする前にボブの変更を自分の変更に部分と マージしなくてはなりません。 それをやる簡単な方法のひとつにupdateコマンドを使う方法が あります:

        % cd ~/wd

        % larch update --in-place hello-world-Alice
        [....]

これで彼女はボブの変更を自分のツリーに追加するできます:

        % cd hello-world-Alice

        % cat main.c
        /* Copywrong 1998 howdycorp inc.  All rights reversed. */

        extern void hello_world (void);

        int
        main (int argc, char * argv[])
        {
          hello_world ();

          /* Exit with status 0
           */
          return 0;
        }

        /* tag: main module of the hello-world project
         */

他には変更がない場合には:

        % larch whats-missing
        [no output]

        % larch commit
        [....]

習得にあたっての注意: 例にそって読み進めてきたのなら、ボブの修正は含んでいるが アリスのは含んでいないhello-world-Bobのツリーがあるはずです。 そのディレクトリにたいしていろいろなコマンドを実行してみてください (whats-missing, update, what-changed などなど)。

updateコマンドがどのように動作するかについての完全な 説明は、この章の範囲を少し越えています。 いくつかの後の章の後で、updateを詳しく理解することが できるようになるでしょう (チェンジセットとパッチログに関する章です)。

いまは、もし diff と patchになじみがあるのなら、 それをこのような感じで考えることができます:

update がアリスのツリーで実行されると、そのコマンドはpatch-2 リビジョンに向かっているところではあるが、彼女のツリーはpatch-1リビジョンの get としてチェックアウトされたことに気づきます。 update は三段階で動作します:

まず、それは mkpatch というコマンドを利用し、( それはdiffの拡張です) チェンジセットを計算します (パッチセットの拡張です) そのチェンジセットは、アリスが自分のツリーにした変更を記述するものです。

次に、それはpatch-2リビジョンのコピーをチェックアウトして、アリスのツリーを そのリビジョンで置き換えます。

最後に update は dopatch ( patchの拡張です) を使って、最初のステップで作ったパッチセットを 新しいツリーに適用します。

パッチの衝突をどのように扱うか不思議に思うかも知れません。 上の例は、衝突が起こらないように注意して選んだものです。心配する必要は ありません — その話題についてはすぐに触れます (不完全パッチ処理 — どのようにして衝突が扱われるか項 参照)。

mkpatch は二つのツリー間の差分を記述するようなチェンジセットを 計算します。この基本的なコマンドの構文は:

        % larch mkpatch ORIGINAL MODIFIED DESTINATION

これで、ORIGINAL と MODIFIEDのツリーが比較されます。

mkpatch は新しいディレクトリであるDESTINATIONを作り チェンジセットをそこに格納します。

mkpatch がツリーを比較するときには目録タグを使います。 たとえば、同じタグを持っている場合、その二つのディレクトリや二つのファイルは、 「同じディレクトリ(またはファイル)」 とみなされます — それぞれが、問題のツリーのどの場所にあるかにかかわらず、そうします (第10章 参照)。

mkpatch で作ったチェンジセットはどのファイルやディレクトリが 追加または削除され、どれが名称変更され、どれが修正されたか(そしてどのように修正 されたか)、そして、どのファイルのパーミッションが変更されたか(そしてどのように 変更されたか)を記述します。通常のテキストファイルが比較される場合には mkpatch はその差分を記述するようなコンテキスト diff を生成 します。mkpatch はバイナリファイルを比較したり(違っている 場合は、新旧両方のバージョンの完全なコピーを保存します)、シンボリックリンク を比較したり(両者が違っている場合は、新旧のリンク先を保存します)することも できます。

チェンジセットの形式の詳細な記述については補遺を見てください。 (付録A 参照)。

dopatch は、ツリーに対してチェンジセットを適用するのに 使います:

        % larch dopatch PATCH-SET TREE

ツリーが、mkpatchの実行時に現れた 「元の」ツリーそのものである場合、結果はひとつの例外を除いて (これについては以下で説明します)mkpatchの実行時に現れた 「修正された」 ツリーそのものになります。

「正確に同じ」 というのは、ディレクトリの構造が同じであり、 シンボリックリンク対象も同じで、通常のファイルの内容、そしてファイルの パーミッションも同じである、ということです。修正時刻、複数のリンクを持つ ファイル、そして、ファイルの所有者に関する情報については、確実に保存 されるとは限りません。

「完全に同じ」という規則の例外は、もしパッチがツリー からファイルやディレクトリを削除するようなものである場合、それらのファイルや ディレクトリは、区別できるようなパターンをもった名前で、ツリー のサブディレクトリに保存されるというものです:

        ++removed-by-dopatch-PATCH--DATE

ここで PATCH はパッチセットディレクトリの名前で、DATE はタイムスタンプになります。a

dopatchによってパッチされるツリーが mkpatchに現れる元のツリーと完全に同じものではない場合は どうなるのでしょう?

以下は、どうなるかについての概略です。dopatch 処理の完全な ドキュメントは、ソースコード中に含まれています。

dopatch はパッチされるツリーの目録を使います。それは、 チェンジセットによって期待されるどのファイルとディレクトリがツリー中に 存在し、また消えてしまっているかを決定し、それぞれのファイルやディレクトリ がツリー中のどこに位置しているかを明らかにするために目録タグを使います。

単純なパッチ もしチェンジセットが通常のパッチ か、リンク、ディレクトリまたはファイルに対するメタデータのパッチを含んでいて、 そのファイルがツリー中に存在している場合、dopatchはそのパッチ を普通の方法で適用します。もしパッチがきれいに適用されれば、修正されたファイル、 リンク、ディレクトリはその場所に残ります。

もし単純なパッチがきれいに適用できなかった場合は、dopatch は 常に.orig ファイル(変更されることのない、パッチされる 前のツリー中にあったもともとのファイル)と、.rej ファイル(適用 できなかったパッチの一部)を残します。

もしパッチがコンテキスト diff だった場合dopatch はファイルそれ自身 も残します — 一部だけパッチされたものです。

もし (成功しなかった) パッチがバイナリファイルに対するものであった場合、 部分的なパッチのファイルは残されません。その代わり、以下のようになります:

        .orig       -- パッチされるツリーにもともとあったファイルの修正される前の形のもの。

        .rej        -- 修正されたツリーのファイルの完全なコピーで、ファイルパーミッションは
                       .origと同一のもの。

        .patch-orig -- mkpatchに現れた元のツリーからのファイルの
                       完全なコピーで、ファイルパーミッションは元のものを保持した形のもの

                        -であるかまたは-

                       mkpatch に現れた元のツリーからのシンボリックリンク
                       で、パーミッションは元のツリーのもの。

もし (成功しなかった) パッチがシンボリックリンクである場合は、 部分的なパッチファイルは残りません。そのかわり:

        .orig       -- 元のツリーからのファイルで、まだ修正されていないもの。

        .rej        -- パッチの目的となるターゲットへのシンボリックリンクで、
                       パーミッションは .orig からのコピーであるもの。

        .patch-orig -- mkpatchに現れた元のツリーからのファイルの
                       完全なコピーで、パーミッションは元のファイルからのものを保持
                       しているもの

                        -であるかまたは-

                       mkpatchに現れた元のツリーからのシンボリックリンク
                       で、パーミッションは元のツリーのものと同じ。

失われたファイルに対するパッチ

失われたファイルやディレクトリに対するパッチはすべてパッチが 呼び出されたツリーの根元のサブディレクトリ中に保存されます。

        ==missing-file-patches-PATCH-DATE

ここで PATCH はチェンジセットディレクトリのベース名で、 DATE はタイムスタンプです。

ディレクトリの再配置と新しいディレクトリ

ディレクトリはあなたが思っているよりもずっと追加、削除、再配置される もので、実際にはあなたがそれを意識していない場合もあります。

mkpatch が呼び出されたとき、ORIGINAL ツリーが以下のよう だったとしましょう:

        ディレクトリまたはファイル:     タグ:

        a/x.c                           tag_1
        a/bar.c                         tag_2

しかし MODIFIED は以下の形だったします:

        a/x.c                           tag_1
        a/y.c                           tag_2

そして、この両方のファイルには変更が加えられているものとします。 パッチはtag_2 のタグを持ったファイルをy.c に名称変更し、タグtag_1 と tag_2をもった ファイルの内容を変更したいとします。

たとえば、以下のようなツリーがあり:

        a/foo.c                         tag_1
        a/zip.c                         tag_2

そのツリーにパッチを適用するとします。パッチの後では以下のようなファイル が残り:

        a/foo.c                         tag_1
        a/y.c (was zip.c)               tag_2

パッチは両方のファイルの内容に対して適用されます。

微妙な場合で、衝突をどのように扱うかの例をあげます:

mkpatch に現れる元のツリーが以下のようであるとします:

        ディレクトリまたはファイル:     タグ:

        ./a                             tag_a
        ./a/b                           tag_b
        ./a/b/c                         tag_c

そして修正後のディレクトリは:

        ./a                             tag_a
        ./a/c                           tag_c
        ./a/c/b                         tag_b

最後に、ツリーが以下のようであるとします:

        ./x                             tag_a
        ./x/b                           tag_b
        ./x/c                           tag_new_directory
        ./x/c/b                         tag_different_file_named_b
        ./x/c/q                         tag_c

ツリーにたいしてパッチが適用されると、以下のようになります:

        ./x                             tag_a
                そのパッチは tag_a のディレクトリには
                何も変更しないので。

        ./x/c.orig                      tag_new_directory
        ./x/c.rej                       tag_c
                Since the patch wants to make the 
                directory with tag_c a subdirectory named "c"
                of the directory with tag_a, but the tree
                already had a different directory there,
                with the tag tag_new_directory.

        ./x/c.rej/b                     tag_b
                Since the patch wants to rename the directory
                with tag_b to be a subdirectory named "b"
                of the directory with tag_c.

        ./x/c.orig/b                    tag_different_file_named_b
                Since the patch made new changes to this file,
                it stayed with its parent directory.

プロジェクトの最新バージョンをgetし、何かの変更を加え、 ログメッセージを書き、アーカイブにその変更をcommit したと します。これで何が起きるのでしょうか?

本質的に commitのすることは:

1 最新バージョンにどのよう変更をしたかを記述する チェンジセットを計算します。

2 アーカイブ中に新しいリビジョンのためのディレクトリを 作ります。

3 アーカイブ中にログメッセージとチェンジセットを保存します。

そのような観点から、戻って前の章を見たくなるかも知れません: どのように動作するか — 新しいリビジョンのコミット項

以前に、cat-archive-log コマンドはアーカイブから ログメッセージを取り出すということを学んだと思います (なぜアリスはコミットすることができないかということについての理解項参照)。

アーカイブからチェンジセットを取り出すこともできます:

        % cd ~/wd

        % larch get-patch hello-world--mainline--0.1--patch-1 patch-1
        [...]

get-patch はアーカイブからチェンジセットを取り出し、 この場合、patch-1という名前のディレクトリに保存して います。

(チェンジセットの形式については 付録A を参照してください)

チェンジセットの形式はプログラムによって利用するために最適化されて います。チェンジセットを「そのまま」見るのはとてもやっかい です。その代わりにpatch-report コマンドの利用を 考えたほうが良いでしょう:

        % larch patch-report --diffs patch-1
        [...]

例に沿って読み進めてきたのなら、以前に導入したwhat-changed コマンドからのpatch-report の出力形式を理解できるでしょう。 (ああ、なんてこと — いったい何をしてしまったんだ?項 参照)。

patch-report はまた–– html をとることができ、 その場合チェンジセットを記述する簡単な web ページを生成するのに利用することが できます。

変更の組をコミットすることが、一般的に言って、"きれいなチェンジセット"を作る ための「最良の練習」になります。

きれいなチェンジセットとは、すべてが関連していて、一つの目的のために 作られた変更のみを含んでいるようなもののことをいます。たとえば、 もしあなたがいくつかのバグを修正したか、いくつかの機能を追加する場合、 そのような変更をひとつのcommitにまとめてしまわない ようにすべきです。

きれいなチェンジセットにはいくつもの利点がありますが、その中でも もっとも大きな点は:

再検討のしやすさ 一つのことだけをやろうと しているチェンジセットを他の人が理解するのはやさしいことです。

マージしやすさ 後の章で学ぶように、 アーカイブ中のチェンジセットの集まりを見て、その中のいくつかを選択 して利用したいような状況があります。多分あなたは、「バグフィックスA 」は利用したいが、「新機能B」は利用したくない、 というケースです。もしチェンジセットのそれぞれが一つの目的を持って いれば、そのような"つまみ食い"は、ずっと現実的なものになります。

hello-worldの古いバージョンをチェックアウトしたとしましょう:

        % cd ~/wd
        % larch get hello-world--mainline--0.1--patch-1 hw-patch-1
        [...]

結果としてのツリーは最新ではないのは見やすいです:

        % cd hw-patch-1
        % larch whats-missing
        patch-2
        patch-3

ここで何かhw-patch-1にローカル修正を加えてから updateを実行するとします。何がおこるでしょうか?

ローカルな変更は、patch-1 に対して計算されます 言い替えると チェンジセットは、patch-1リビジョンの修正前コピーからプロジェクトツリーの 現在の状態(hw-patch-1)までの変更を表現するようなチェンジセットが作成され ます。

patch-3 のコピーはチェックアウトされます。 update は、patch-3リビジョンの編集前コピー で始まります。

チェンジセットは、patch-3 のツリーに対して適用されます。 最初のステップで計算された変更は、新しいツリーに適用されます。

しかし、別の方法もあります:

この時点でpatch-1のローカルコピーがあり、多分それはローカルな 変更がされているでしょう:

        % cd ~/wd/hw-patch-1
        % larch whats-missing
        patch-2
        patch-3

Recall that the patch-2 と patch-3 のリビジョンのそれぞれは、 特定のチェンジセットに対応していて、アーカイブ中に格納されていることを思い出してください( どのように動作するか — 新しいリビジョンのコミット項参照)。

ローカルツリーに対してそのような変更を追加するのに get-patch を使って それぞれのチェンジセットを抽出し、dopatchを使って適用することができた のでした(get-patch はアーカイブからチェンジセットを取り出します項 と dopatch項を参照してください)。 しかし、それにはたくさんの面倒な作業になるので、 archは、同じ効果をもつような自動的な方法を用意しています:

        % cd ~/wd/hw-patch-1
        % larch replay --in-place .
        [....]
        % larch whats-missing
        [no output]

replay ––in-place は、いま説明したことをやってくれます: アーカイブからパッチを取得し、それぞれをひとつひとつ適用していきます。 しかし、ひとつ注意があります:もしそのなかの一つが衝突を起こした場合、 replayはそこで止まり、衝突を直すようにユーザに求めます。 それから、replayが残した部分についてreplay ––in-place を実行することでもう一度選ぶことができます。

もし、いままでチュートリアルに沿ってやってきたのなら、 replay ––in-place の動作は自明です。 事実、それはまさに上に述べたことだからです。 replay は whats-missing を自分のツリーがやり忘れた変更を発見するのに使い、get-patch をそのような チェンジセットを抽出するのに使い、 dopatchで実際に適用するからです。 それをやるのに十分な量の 「記録」 があります。 — そしてその記録は replay が自動実行してくれることになります。

大きなプロジェクトツリーからあり、ある複雑な修正のまっただ中にいるとします。 あなたはたくさんのファイルを修正しましたが、まだやっていない他の修正が たくさんあるとします。

ここで不意にまだ触れていないファイルのどれかに つまらないバグがあることに気づいたとします。

あなたがやりそうなこととしては:

1) 作業を中断して、そのバグを修正し、

2) その修正をコミットし、

3) 再び複雑な修正作業に戻る、という方法です。

どうやってそれをやることができるでしょう?

この問題を解決するのに、簡単で「乱暴な」方法があります。

単に:

最後のリビジョンのきれいなコピーをチェックアウトします。 言い替えると、変更のまったくない第二のプロジェクトを作ります。

新しいツリーでそのつまらないバグを修正しコミットします。 これで、そのつまらないバグ修正を加えたきれいな変更をコミットします。

update か replay コマンドによって、元のツリーを最新に状態にします。 部分的に完了した変更と共に、自分のツリーに対してささいなバグ修正を追加します。

それは動くには動きますが、面倒です。 ちょっとしたバグを潰すためだけに、二つ目のプロジェクトを始めたいと本当に 思いますか?

しばしば、その面倒さは報われることもあります。 たとえば、プロジェクトは、コミット前には必ずなにかのテストを 実行しなくてはならないというような決まりがある場合です。そのような場合、本当に 二つ目のツリーが必要となるでしょう。

別の状況では、その面倒な処理は本当に避けたいことになります。たとえば もしそのささいなバグ修正が、すでに大きな変更を加えてしまったファイルの修正を ともなうような場合です。そのときでも乱暴な方法は一番単純なアプローチではあります (しかしまた、 larch undo ––help と larch redo ––helpを見てください)。

しかし、ときどき許容される、もっと簡単な方法もあります:

すでにおわかりのように、commit コマンドには ––files オプションがあり、いくつかのファイルにした変更だけをコミットすることができます。

もしちょっとした修正点を file-a.c と file-b.cにたいして やった場合、ログメッセージを用意した後で、そのようなファイルを以下のようにコミットすることが できます:

        % larch commit --files -- file-a.c file-b.c

commit ––files でコミットされるファイルは新しいファイルであっては ならず、そのファイルが名称変更されたとしても、commitはそのようなファイルの 内部的な変更だけを記録し、名称変更したものについては記録しません。

しばらくのあいだ hello-world プロジェクトはソースコードが公開 されていて、読み込み専用のミラーになっているとします( 第14章参照)。

まず、あなたは (hello-world プロジェクトに参加していない任意の人は) そのプログラムを利用したいが、自分自身のためのローカルな修正をする必要もあると します。

簡単な場合を考えて、あなたは自分の環境では、"hello world" と表示するのは 受け入れられないとします — きちんとカンマをつけて "hello, world" と 表示することが要求されているとします。

ここで問題がおこります: たしかにソースをダウンロードして変更を加えることは できます。しかし一方でプロジェクトは進行して行きます。彼らはひきつづき 修正を加えるでしょう。こうしてあなたは彼らの最新のソースをダウンロードしては その最新版に対して自分の変更をコピーする、という作業を繰り返ししなくては ならないという問題に直面します。

arch そのような作業の自動化を助けることができます。 この章ではそのやり方について説明します。

以下の例では、あなたの役割を変えます。hello-worldプロジェクト上の プログラマ、アリスとボブを「演じる」代わりに、第三者である キャンディスを演じます。

キャンディスに彼女自身のアーカイブを与えるところから始めましょう。 そのアーカイブを彼女のデフォルトアーカイブとします:

        % larch make-archive lord@emf.net--2003-candice \
                             ~/{archives}/2003-candice

        % larch my-default-archive lord@emf.net--2003-candice
        default archive set (lord@emf.net--2003-candice)

(このコマンドが何をするかについては、 第6章を復習してください)。

キャンディスは自分のアーカイブ中に hello-world プロジェクトを 作る必要があります。 以下のコマンドを使うことができます:

        % larch make-category hello-world
        % larch make-branch hello-world--candice
        % larch make-version hello-world--candice--0.1

彼女はアリスとボブの使っている同じ名前をプロジェクト名に 選ぶ ことは できません。実際この場合彼女は別のブランチ名前を選びました (これらのコマンドについては 第7章参照のこと)

アリスとボブがアーカイブを作ったとき、最初のリビジョンを作るためにimport を使いました。私達は ブランチを作るので、別のコマンドを使います。

例として、キャンディスはアリスとボブのアーカイブの patch-1 リビジョンから始めるものとします:

    % larch tag \
        lord@emf.net--2003-example/hello-world--mainline--0.1--patch-1 \
        hello-world--candice--0.1
    [....]

このコマンドについていくつか注意しておくべきことがあります。

まず、私達は 完全に修飾されたリビジョン名 を使って アリスとボブの patch-1 リビジョンを参照しました。 それはそのリビジョンは、現在のデフォルトアーカイブ以外のアーカイブ中にある リビジョンであるからです。 (一度に複数のアーカイブを使った作業項参照)

次に私達は patch-1 のリビジョンを明示的に指定しなくてはなりません。 もし ––patch-1 サフィックスを省略すれば、 tag コマンド はアリスとボブのアーカイブの最新のリビジョンを指定したものと考えます (それは patch-3 ということになるでしょう)。

tagを使った後キャンディスは自分のアーカイブ中に新しいリビジョンを 持つことになります:

   % larch revisions --summary hello-world--candice--0.1
   base-0
       tag of lord@emf.net--2003-example/hello-world--mainline--0.1--patch-1

彼女は普通の方法でそのリビジョンを抽出することができます:

   % larch get hello-world--candice--0.1 hw-candice
   [...]

   % ls hw-candice
   hw.c         main.c          {arch}

arch のNiftyな機能: もし注意深く読み進めてきたのなら、キャンディスは他のアーカイブ中に保存された arch のリビジョンから自分のアーカイブ中にブランチを作ったことに気づくでしょう。 今の例だと、これら両方のアーカイブはローカルファイルシステム上に ありますが、それは必要なことではありません: キャンディスはネットワーク越しに アリスとボブのアーカイブにアクセスできる場合でも、ブランチを作ることが できます。

利用についての注意: キャンディスの作業はまだ済んで いません。次の章では、彼女が多分やりたいと思う別のステップについて 説明します。

キャンディスは tag を使って、アリスとボブのアーカイブからブランチを 作りました。そのリビジョンをチェックアウトするためにgetコマンドを実行 すると、何がおこるのでしょうか? 大雑把にいって、archはそのリビジョンがブランチであることに気づき、 アリスとボブのアーカイブから実際にソースを取得しようとします。

すると疑問が湧きます: もしアリスとボブがアーカイブを「捨てて」しまったら? いままでの説明を考えるとわかるように、もしそうなった場合、キャンディスは もはや彼女自身のブランチを取得することはできません。

しかし彼女は自分のアーカイブ中にそのリビジョンを構築するのに必要な すべての情報をキャッシュすることで問題を回避することができます:

   % larch archive-cache-revision hello-world--candice--0.1--base-0
   [...]

そして、この処理結果は以下のコマンドで確認できます:

   % larch archive-cached-revisions hello-world--candice--0.1
   hello-world--candice--0.1--base-0

その後 arch は、キャンディスのbase-0リビジョンを 抽出するのに、アリスとボブのアーカイブに依存する必要はなくなります。

以前にキャンディスは自分のブランチを作って get でチェックアウト しました。そのツリーの中を見てみましょう:

        % cd ~/wd/hw-candice

        % larch logs
        lord@emf.net--2003-candice/hello-world--candice--0.1
        lord@emf.net--2003-example/hello-world--mainline--0.1

キャンディスのツリーはアリスとボブの両方のバージョンのパッチログを 持っています。そして彼女自身のブランチのものも持っています:

    % larch log-ls --summary \
            lord@emf.net--2003-example/hello-world--mainline--0.1
    base-0
        initial import
    patch-1
        Fix bugs in the "hello world" string


    % larch log-ls hello-world--candice--0.1
    base-0
        tag of \
        lord@emf.net--2003-example/hello-world--mainline--0.1--patch-1

キャンディスのブランチ上ではその後の変更はありません:

        % larch whats-missing hello-world--candice--0.1
        [no output]

しかし、アリスとボブは patch-3の用意ができています:

        % larch whats-missing -A lord@emf.net--2003-example \
                hello-world--mainline--0.1
        patch-2
        patch-3

最初の tagの後で, キャンディスは普通の方法で自分のブランチに 変更をコミットすることができます。

彼女は hw.c を編集したとします。すると ( 一部だけ抜粋すると):

        % cat hw.c
        [...]
        void
        hello_world (void)
        {
          (void)printf ("hello, world\n");
        }
        [...]

そして、彼女はログメッセージを用意します:

    % cat ++log.hello-world--candice--0.1--lord@emf.net--2003-candice
    Summary: Punctuated the output correctly
    Keywords: 

このプログラムは "hello word"の代わりに "hello, world" と表示するでしょう。

これで彼女は普通の方法でコミットすることができ、自分自身のpatch-1リビジョン を作ることができます:

   % larch commit
   [....]

   % larch revisions --summary hello-world--candice--0.1
   base-0
       tag of \
       lord@emf.net--2003-example/hello-world--mainline--0.1--patch-1
   patch-1
       Punctuated the output correctly

一方アリスとボブは自分たちのリビジョン、 patch-2 と patch-3を作ったとします。 アリスはどうやって彼女のブランチにその変更を追加することができるのでしょうか?

arch はこういうことのためにたくさんの方法を用意しています。 すでに導入されたコマンドを使うとすると、彼女は update か replay を使うことができます。今回はreplayを使ってみましょう。

        % cd ~/wd/hw-candice

        % larch replay --in-place \
                -A lord@emf.net--2003-example \
                . \
                hello-world--mainline--0.1
        [...]

Note that we used a -A オプションを使って、どのアーカイブ からの変更をリプレイするか、そして、バージョン名で、どの変更が欲しいかを 指定したことに注意してください。今回の場合 replay は、キャンディスのツリーに対して、 patch-2 と patch-3 のチェンジセットを適用しました。

このreplay の使いかたは、"マージ"の形になっています: キャンディスのローカルな変更はアリスとボブの主系での変更を マージしました。

注意: 例に沿って読んできたのなら、 hw.c を調べてキャンディスの printf 文字列への変更と、アリスの「copywrong」の注意書きの両方が含まれている ことに注意してください。

注意: また、キャンディスのpatch-1リビジョン の二つめのコピーをチェックアウトして、同じマージ処理を、replayの代わりに updateを使ってやってみることもできます。'larch update -help' を使って どのオプションと引数が用意されているかを調べるこができます。

また、以下のことにも注意してください。いままでこのような変更を キャンディスのツリーに対してだけやってきました — キャンディスのアーカイブにはチェックインしませんでした。実際に彼女のアーカイブ にマージを記録するには、ログメッセージを作って、通常のやり方でコミット しなくてはなりません( 第12章参照).

もう一点だけ指摘しておきたいもっと便利な方法があります。 キャンディスが自分のログメッセージを書くとき、マージが行われたことと、 それに含まれていることについて書きたいと思うかも知れません。 arch は、そのようなログメッセージ中に含まれるものと同じ になるような出力をもつコマンドがあります。

  % cd ~/wd/hw-candice

  % larch log-for-merge
  Patches applied:

    * lord@emf.net--2003-example/hello-world--mainline--0.1--patch-3
       added copywrong statements

    * lord@emf.net--2003-example/hello-world--mainline--0.1--patch-2
       commented return from main

tag がしたことは何でしょうか? キャンディスのアーカイブを 見てみましょう:

        % cd ~/{archives}
        % cd 2003-candice
        % cd hello-world
        % cd hello-world--candice
        % cd hello-world--candice--0.1

        % ls
        +version-lock   =README         base-0          patch-1
        patch-2

あるいは、特に興味を引くのはbase-0 リビジョンです — それは、tagで作られたものです:

        % cd base-0

        % ls
        CONTINUATION
        hello-world--candice--0.1--base-0.patches.tar.gz
        hello-world--candice--0.1--base-0.tar.gz
        log

        % cat CONTINUATION
        lord@emf.net--2003-example/hello-world--mainline--0.1--patch-1

ファイルCONTINUATION はこのリビジョンをタグリビジョンとして 判別します。それはどのリビジョンからブランチを作ったのかを教えてくれます。

このリビジョンのチェンジセットもまた (....patches.tar.gz) tagから作られました。もしチェンジセットを調べれば、(get-patch と patch-reportを思い出してください) それがやったことは、ツリーのパッチログに ログのエントリを追加したことだけだということがわかるでしょう。

ソースファイル (...base-0.tar.gz) は archive-cache-revisionによって作られました。 それはキャンディスのbase-0リビジョンの完全なコピーを含んでいます。 そのファイルはあるので、getはこのリビジョンを構築するためにアリス とボブのアーカイブを見る必要はありません。

リモートアーカイブは少なくとも二つの欠点があります:

まず、それは消えてしまうことがあります。 もしネットワークがダウンしたり、リモートアーカイブの管理者がそれを 保持しなければ、アーカイブはなくなってしまいます。

次に、そのようなアクセスは遅い場合があります。 リモートアーカイブは、まさに、リモートな場所にあります。その内容にアクセスすることは、 リモートデータにへのネットワークアクセスの通常の遅延の問題が起こります。

もしリモートアーカイブが重要なデータを含んでいる場合、この欠点は 深刻なものになります。そのようなリスクを減らすにはどうしたら 良いのでしょうか?

互換性についての注意: この章で説明する方法は 今後のリリースでは変更になるかも知れません。ミラーはもっとすっきりとサポートする かも知れません。それでもこの方法は作業をうまくやるのに"十分良い"方法です。

少しディスクは食いますが、本質的に以下の二つのステップによって、リモートアーカイブに関する 問題を最小限にすることができます。

リモートアーカイブを第二の名前で登録します。 register-archiveを使うときに、リモートアーカイブをもともとの名前とは 別の名前にします。

ローカルコピーを作るために、push-mirror を使います。 リモートアーカイブのミラーである、ローカルアーカイブを作ります。そのミラーを、アーカイブの 名前で登録します。 push-mirror を使って、リモートアーカイブを自分のプライベートなミラーに コピーするのに使います。(読み込み専用のアーカイブのミラー項参照)。

アーカイブ中の全ての最初のインポート、タグリビジョン、そしてチェンジセットリビジョン はそれに関連したログメッセージを持つことを思い出してください。そのメッセージは importやcommitのようなコマンドに明示的に渡す ヘッダとボディー、そしてarchによって自動的に生成されるヘッダからなります。

プロジェクトツリーが最初にアーカイブにインポートされるとき、新しいリビジョンの ためのパッチログエントリがツリーに追加されます。 コミット処理全体の一部として、commitが起こると、新しいリビジョン のログエントリがツリーに追加されます。tagコマンドによって 作成されたリビジョンをgetする場合、そのタグリビジョンのための パッチログエントリを含んでいることがわかるでしょう。

パッチログエントリは蓄積されます。それで例えばそれぞれのコミット は新しいログエントリを追加し、以前のすべてのログエントリは保存されたままです。 それぞれのタグリビジョンはそのタグのためのエントリのみを含むのではなく、 タグづけされたリビジョンから受け付いたすべてのログエントリを含んでいます。

前の例に戻って、アリスとボブのpatch-2リビジョンを見てみましょう:

        % cd ~/wd

        [... remove directories from earlier examples ...]

        % larch get -A lord@emf.net--2003-example \
                    hello-world--mainline--0.1--patch-2 \
                    hw-AnB-2

        [...]

        % cd ~/hw-AnB-2

最初にパッチログは arch のバージョン名でソートされることに注意 してください。このツリーは一つのバージョンのみからのログを持っています:

        % larch logs
        lord@emf.net--2003-example/hello-world--mainline--0.1

そのログ中で、最初のインポートのログと、ふたつのチェンジセットがあります:

        % larch log-ls -A lord@emf.net--2003-example \
                       --summary \
                       hello-world--mainline--0.1
        base-0
            initial import
        patch-1
            Fix bugs in the "hello world" string
        patch-2
            commented return from main

特にこのようなログエントリの一つについて調べてみます:

        % larch cat-log -A lord@emf.net--2003-example \
                        hello-world--mainline--0.1--patch-2
        Revision: hello-world--mainline--0.1--patch-2
        Archive: lord@emf.net--2003-example
        Creator: Tom (testing) Lord <lord@emf.net>
        Date: Wed Jan 29 12:46:50 PST 2003
        Standard-date: 2003-01-29 20:46:50 GMT
        Summary: commented return from main
        Keywords: 
        New-files: \
          {arch}/[...]/hello-world--mainline--0.1/[...]/patch-log/patch-2
        Modified-files: main.c
        New-patches: \
          lord@emf.net--2003-example/hello-world--mainline--0.1--patch-2

        Added a comment explaining how the return from main
        relates to the exit status of the program.

例えば、patch-2チェンジセットはmain.cを修正し、 新しいファイルとログエントリ自身を追加しました。(上の出力中ではその名前は省略して あります)。

別の例はキャンディスのツリーからのものを考えると良いです。 彼女はpatch-1リビジョンでアリスとボブのツリーから分岐する ためにタグを使ったことを思い出してください。それで:

        % cd ~/wd

        % larch get -A lord@emf.net--2003-candice \
                    hello-world--candice--0.1--patch-2 \
                    hw-C-0

        [...]

        % cd ~/hw-C-0

        % larch logs
        lord@emf.net--2003-candice/hello-world--candice--0.1
        lord@emf.net--2003-example/hello-world--mainline--0.1

        % larch log-ls  -A lord@emf.net--2003-example \
                        --summary \
                        hello-world--mainline--0.1
        base-0
            initial import
        patch-1
            Fix bugs in the "hello world" string


        % larch log-ls  -A lord@emf.net--2003-candice \
                        --summary \
                        hello-world--candice--0.1
        base-0
            tag of \
              lord@emf.net--2003-example/hello-world--mainline--0.1--patch-1

以前、どのように whats-missing コマンドがアーカイブに対する コミットされた修正について伝えるかについて学びましたが、与えられたプロジェクト ツリーではまだ現れてはいません。 (なぜアリスはコミットすることができないかということについての理解項と 新しいブランチの調査項を参照のこと)

そのようなコマンドがどのように動作するかを理解するのはやさしいことです。 archは、revisionsコマンドを使って 与えられたバージョン中のすべてのリビジョンの一覧を表示することができます:

        % larch revisions -A lord@emf.net--2003-example \
                          hello-world--mainline--0.1
        base-0
        patch-1
        patch-2
        patch-3

それはアーカイブ中のログです。 arch は、log-lsでログエントリを持つプロジェクト ツリーのためのリビジョンの一覧を表示することができます:

        % larch log-ls -A lord@emf.net--2003-example \
                       hello-world--mainline--0.1
        base-0
        patch-1
        patch-2

二つの一覧の間の違いが whats-missingの出力になります:

        % larch whats-missing -A lord@emf.net--2003-example \
                              hello-world--mainline--0.1
        patch-3

パッチログはツリーの履歴に重要な情報を与えます。 注意しておく価値のある二つの見方があります: "変更履歴"の見方と、 "ツリーancestry"の見方です。

非公式には、アーカイブされたリビジョンは、もし与えられたツリーがアーカイブされたリビジョンの バージョン中にある全てのリビジョンのログエントリを持っているなら、そのプロジェクトツリーの "ツリーancestor"である、と言います。

それで例えば、キャンディスのタグリビジョンはアリスとボブのpatch-1リビジョンを ancestor として持ちますが、それはアリスとボブのリビジョンを持っているためです:

        base-0
        patch-1

さらにキャンディスの patch-2 リビジョンはアリスとボブの patch-2 と patch-3の変更をマージした ものですが、このふたつのリビジョンを追加の ancestor として持ちます (ブランチからのバージョンを更新すること項参照。)

larch changelog コマンドは、GNU-スタイルの ChangeLog ファイルを パッチログから生成します:

  % cd ~/wd

  % larch get -A lord@emf.net--2003-candice \
              hello-world--candice--0.1 \
              hw-C-latest
  [....]

  % cd ~/wd/hw-C-latest

  % larch changelog
  # do not edit -- automatically generated by arch changelog
  # tag: automatic-ChangeLog-- [...]
  #

  2003-01-30 GMT  Tom (testing) Lord <lord@emf.net>       patch-2

      Summary:
        merge from mainline sources
      Revision:
        hello-world--candice--0.1--patch-2
  
      Patches applied:
      
        * lord@emf.net--2003-example/hello-world--mainline--0.1--patch-3
           added copywrong statements
      
        * lord@emf.net--2003-example/hello-world--mainline--0.1--patch-2
           commented return from main
      
  
      new files:
       {arch}/ [...] /hello-world--mainline--0.1 [...] /patch-2
       {arch}/ [...] /hello-world--mainline--0.1 [...] /patch-3
  
      modified files:
       hw.c main.c
  
      new patches:
       lord@emf.net--2003-example/hello-world--mainline--0.1--patch-2
       lord@emf.net--2003-example/hello-world--mainline--0.1--patch-3
  
  
  2003-01-30 GMT  Tom (testing) Lord <lord@emf.net>       patch-1
  
      Summary:
        Punctuated the output correctly
      Revision:
        hello-world--candice--0.1--patch-1
  
      
      This program should say "hello, world" not "hello world".
      
  
      modified files:
       hw.c
  
  
  2003-01-30 GMT  Tom (testing) Lord <lord@emf.net>       base-0
  
      Summary:
        tag of lord@emf.net--2003-example/hello-world--mainline--0.1--patch-1
      Revision:
        hello-world--candice--0.1--base-0
  
      (automatically generated log message)
      
  
      new patches:
       lord@emf.net--2003-example/hello-world--mainline--0.1--base-0
       lord@emf.net--2003-example/hello-world--mainline--0.1--patch-1
  

生成されたChangeLog は tag の行を含んでいることに 注意してください。プロジェクトツリー中の changelog コマンドの出力を 省略したい場合は、暗黙的なタグを使うか、tagにマッチする明示的なタグを 与えることで、commit のようなコマンドは自動的に ChangeLog を最新の状態に保ちます。

いままで、例にそって読み進めてきたのなら、キャンディスは基本的なブランチを 持っているはずです。彼女は主系からブランチを作り、ローカルな修正を加え、 アリスとボブの主系の最新の内容を自分のブランチに反映しました。

この時点で、アリスとボブはキャンディスの変更を主系にマージしたいと 思っているとします。

実際にはそのようなマージ作業はすでに済んでいます。キャンディスの 最後のリビジョンはまさにアリスとボブがほしいと思っているもの だからです。キャンディスの最後のリビジョンを彼ら自身の主系に コミットすることによって、アリスとボブは非常に簡単に そのようなマージすることができます。

        % larch get -A lord@emf.net--2003-candice \
                    hello-world--candice--0.1 \
                    hw-C
        [...]


        % cd hw-C

        % larch set-tree-version -A lord@emf.net--2003-example \
                    hello-world--mainline--0.1

        % larch make-log
        ++log.hello-world--mainline--0.1--lord@emf.net--2003-example

        [... edit log file (consider larch log-for-merge) ... ]

        % cat ++log.hello-world--mainline--0.1--lord@emf.net--2003-example
        Summary: merge from Candice's Branch
        Keywords: 

        Patches applied:

          * lord@emf.net--2003-candice/hello-world--candice--0.1--patch-2
             merge from mainline sources

          * lord@emf.net--2003-candice/hello-world--candice--0.1--patch-1
             Punctuated the output correctly

          * lord@emf.net--2003-candice/hello-world--candice--0.1--base-0
             tag of 
              lord@emf.net--2003-example/hello-world--mainline--0.1--patch-1

        % larch commit
        [....]

注意。よく読んでください: いま使った"トリック"に注意してください。キャンディスの最後のリビジョンはアリスとボブが まさに欲しいと思っているものでした — 彼らはgetをset-tree-version と組み合わせて、キャンディスのツリーを彼らの主系に簡単にコミットでるようなものに変えました。

両方のブランチで開発が進んだところを考えてみましょう。 この目的のため、新しいものを導入します: 複数のブランチとそれらの間のマージを図式化する 方法です。

いまの例では、以下のような状況になっています。

      mainline-0.1                    candice-0.1
      ------------                    -----------
        base-0             -----------> base-0 (a tag)
        patch-1  ---------'             patch-1
        patch-2             ----------> patch-2
        patch-3  ----------'  --------'
        patch-4  <-----------'

これは、candice のブランチは主系からのpatch-1のタグである ことを示しています。: そして、キャンディスのブランチのpatch-2で 主系のpatch-3までのすべてのマージがあり、最後に、 主系のpatch-4は、キャンディスのブランチの patch-2までのすべての変更をマージした状態になっています。

マージを示す線が一つもないような図のことを、常に、"単純な開発ブランチ" と言います。

単純な開発ブランチの重要性は、どのようにして二つの開発が一つのプロジェクト 上で非同期的に進めることができるかというモデルだからです。 それぞれの開発ライン上で — それはそれぞれのブランチ上でおこりますが — プログラマは「update/commit」スタイルの共同作業を使います。 (第15章参照)。しかし、 片方の変更は、二つのブランチがマージされるまではもう一方に影響を与えることは ありません。

主系 とキャンディス のブランチでもっと いろいろな作業が起こったとしましょう。以下のようになりました:

      mainline-0.1                    candice-0.1
      ------------                    -----------
        base-0             -----------> base-0 (a tag)
        patch-1  ---------'             patch-1
        patch-2             ----------> patch-2
        patch-3  ----------'  --------' patch-3
        patch-4  <-----------'          patch-4
        patch-5
        patch-6


        % larch revisions --summary -A lord@emf.net--2003-candice \
                          hello-world--candice--0.1
        base-0
            tag of 
            lord@emf.net--2003-example/hello-world--mainline--0.1--patch-1
        patch-1
            Punctuated the output correctly
        patch-2
            merge from mainline sources
        patch-3
            added a period to output string
        patch-4
            capitalized the output string



        % larch revisions --summary -A lord@emf.net--2003-example \
                          hello-world--mainline--0.1
        base-0
            initial import
        patch-1
            Fix bugs in the "hello world" string
        patch-2
            commented return from main
        patch-3
            added copywrong statements
        patch-4
            merge from Candice's Branch
        patch-5
            fixed the copyrwrong for hw.c
        patch-6
            fixed the copyrwrong for main.c

私達の目標が、主系での新しい作業内容を、キャンディス のブランチにマージすることである、という状況を考えてみます。言い替えると 以下のようにしたいとします:

      mainline-0.1                    candice-0.1
      ------------                    -----------
        base-0             -----------> base-0 (a tag)
        patch-1  ---------'             patch-1
        patch-2             ----------> patch-2
        patch-3  ----------'  --------' patch-3
        patch-4  <-----------'          patch-4
        patch-5               --------> patch-5
        patch-6  ------------'

そのようなマージはどうやったらいいのでしょうか? 最後のマージ前のキャンディスのリビジョンから始めましょう (patch-4):

        % larch get -A lord@emf.net--2003-candice \
                       hello-world--candice--0.1--patch-4 \
                       hw-C-4
        [....]

        % cd hw-C-4

ここで、実際にはうまく動作しないふたつのやり方があります:

        % larch whats-missing --summary \
                              -A lord@emf.net--2003-example \
                              hello-world--mainline--0.1
        patch-4
            merge from Candice's Branch
        patch-5
            fixed the copyrwrong for hw.c
        patch-6
            fixed the copyrwrong for main.c

        delta(X, Y)

        delta(mainline--0.1--patch-3, hw-C-4) 

        delta(X, Y) [ Z ]

        delta(mainline--0.1--patch-3, hw-C-4) [mainline--0.1--patch-6]

        delta(mainline--0.1--patch-3, hw-C-4)

delta の記法を使って、このマージ問題をはっきりさせましょう。

ひとつの可能性は、主系にたいして一番高い優先順位を 与えて、キャンディスからの変更をマージし、それから プロジェクトツリー中にのみ現れるローカルな変更をマージすることに 一番低い優先順位をつけることです。この解決策は、冗長な変更からの 不要な衝突をすることなしに、以下のように書き下すことができます:

   tmp = delta(X, Y)[Z]
     where X = lord@emf.net--2003-candice/hello-world--candice--0.1--base-0
           Y = lord@emf.net--2003-candice/hello-world--candice--0.1--patch-2
           Z = lord@emf.net--2003-example/hello-world--mainline--0.1--patch-4
   

   answer = delta(L,M)[tmp]

     where L = lord@emf.net--2003-example/hello-world--mainline--0.1--patch-4
           M = /usr/lord/examples/wd/hw-AnB

利用に関する注意: マージにおける「優先順位」の概念は、どのようにして (必要な)衝突を扱うかということを処理しなくてはなりません。 主系に対して高い優先順位を与えることで、 他のふたつのツリーが含む衝突のある変更は、.rejファイルに 現れることを保証します。それは以下のような場合には重要なことになりえます。 たとえば、衝突が解消した主系に相対的な変更を最小化したい 場合です(不完全パッチ処理 — どのようにして衝突が扱われるか項 参照)。

似たように見えるが別の解決策が必要になるのは、主系よりも キャンディスのブランチに高い優先順位を与えたい場合です。

   tmp = delta(X, Y)[Z]
     where X = lord@emf.net--2003-candice/hello-world--candice--0.1--patch-2
           Y = lord@emf.net--2003-example/hello-world--mainline--0.1--patch-6
           Z = lord@emf.net--2003-candice/hello-world--candice--0.1--patch-4
   

   answer = delta(L,M)[tmp]

     where L = lord@emf.net--2003-candice/hello-world--candice--0.1--patch-4
           M = /usr/lord/examples/wd/hw-C-4

私達は実際、「手あたり次第の」方法で解決策を実装することもできます。 二つのブランチのマージ履歴を調べ、どのように解決したかを調べ、 必要なツリーをチェックアウトし、チェンジセットを計算するのにmkpatch を使い、dopatchでそれを適用する、という方法です。 しかしこのあとすぐに見るように、archはこの手のマージのために 組み込みのサポートがあります。

開発ブランチマージ問題の一般的にな完全な解決策を説明するのは このチュートリアルの範囲を少し越えています。上で見せた二つの解決策は 二つの場合について示していますが、時にはもう少し違った解決方法が 必要な場合もあります。

知っておくべきことは、単純な開発ブランチがある場合には (簡単な開発ブランチ項参照)、 star-merge コマンドは、不要なマージ衝突を起こすことなく それらの間でどのようにマージすれば良いかを知っているということです。

star-merge (ここで示すように––in-place オプションつきの ばあい)は三つの引数をとります: ふたつの arch バージョンとプロジェクトツリー です(名前は ./で始まる必要があります)。これらの引数の順序は それぞれのソースからの変更の順序を決めます。

たとえば、前の節の二つの解決策は以下のようにしても達成することができます:

        # giving the mainline branch precedence over the candice
        # branch:
        # 

        % larch star-merge --in-place \
                  lord@emf.net--2003-example/hello-world--mainline--0.1 \
                  lord@emf.net--2003-candice/hello-world--candice--0.1 \
                  ./hw-C-4


        # giving the candice branch precedence over the mainline
        # branch:
        # 

        % larch star-merge --in-place \
                  lord@emf.net--2003-candice/hello-world--candice--0.1 \
                  lord@emf.net--2003-example/hello-world--mainline--0.1 \
                  ./hw-C-4

利用に関する注意: 以前に説明したマージの解決策は両方とも二つのチェンジセットの適用を含んでいた ことに注意してください。一般的に、そのようなものの片方、または両方は パッチの衝突を起こすかも知れません。もし最初のマージの後衝突が起こった場合は star-merge は中断し、その衝突を解決するチャンスが与えられます。 star-mergeに対する––finish オプション を使って、二番目のチェンジセットを適用します。 (see larch star-merge ––help参照)。

利用に関する注意: star-mergeを使う前に、get/set-tree-version/commit の トリックを使ってキャンディスから主系への 最初のマージ戻しをしました。 (基本的なブランチから、より複雑なブランチへ項参照)。 一般的に、基本的なブランチから、親ブランチへ戻す形の最初のマージは常にこのような方法で 行われるべきです。 (時々、ユーザから star-merge は そのような「組み込みの」トリックを持つべきだという要求があります。 多分、いつかそのようになるでしょう。)

新しいリビジョンライブラリを始めるのに、まず新しいディレクトリを作り(DIR) それからその場所を登録します:

        % larch my-revision-library DIR

ライブラリの位置は以下のようにして確認できます:

        % larch my-revision-library

登録を解除するには:

        % larch my-revision-library -d

リビジョンライブラリは以下のような形のサブディレクトリを持っています:

ARCHIVE-NAME/CATEGORY/BRANCH/VERSION/REVISION/

それぞれの REVISION ディレクトリは特定のリビジョンの 完全なソースを含んでいます。さらに補助的なサブディレクトリとファイルも 含んでいます。

REVISION/,,patch-set/

その祖先からこのリビジョンを作ったパッチセット (リビジョンが完全なソースを持ったベースリビジョンではないかぎり)。

リビジョンライブラリ中のファイル上のパーミッションはパッチセットによって 決定されますが、リビジョンライブラリ中のファイルを変更 することはできません。そのようなことをしようとすると、 奇妙なエラーがおこり、いろいろなarchのコマンドで 失敗するようになります。

ある特定したリビジョンをあなたのリビジョンライブラリに追加する ことができます。以下のようにします:

        % larch library-add REVISION

それは REVISIONをライブラリに追加するだけではなく、 同じアーカイブ、または同じライブラリにある別のアーカイブからの 直接の引き続くリビジョンも(再帰的に)追加します。 (この場合の「直接の引き続く」は、普通のリビジョンまたはタグづけされたリビジョン のための前のパッチレベルを意味します。)

library-findコマンドでライブラリ中の特定のリビジョンを検索 できます:

        % larch library-find REVISION
        PATH-TO-REVSION

出力はそのリビジョンを含むライブラリディレクトリの絶対パス名称です。 (繰り返しになりますが、そのディレクトリのファイルを編集してはなりません。)

ライブラリからの特定のリビジョンを削除するには:

        % larch library-remove REVISION

現在のリリースでは以下の制約があります: 三つの引き続くリビジョンを追加しようとしているとします、A, B, そして Cです。 それからBを削除し再び Bを追加します。 その場合、BとCの間のファイルの共有は あまり最適化されないかも知れず、不要に大きな領域を必要とするかも知れません (これは、Cを削除し、もう一度追加すれば解決できます)

コマンド library-archives は、ライブラリ中の全てのアーカイブをその記録と一緒に 一覧表示します:

        % larch library-archive
        ARCHIVE-NAME
        ARCHIVE-NAME
        ...

同様に、カテゴリ、ブランチ、バージョン、リビジョンも表示できます:

        % larch library-categories [ARCHIVE]
        % larch library-branches [ARCHIVE/CATEGORY]
        % larch library-versions [ARCHIVE/BRANCH]
        % larch library-revisions [ARCHIVE/VERSION]

リビジョンライブラリ中の個々のファイルの場所を以下のようにして知ることが できます:

        % archive library-file FILE [REVISION]
        PATH

あるいはその内容は:

        % archive cat-library-file FILE [REVISION]
        ...file contents...

両方のコマンドはオプション ––tag と ––thisをとる ことができます。––tagを使うと引数 FILE は 目録タグと解釈され、そのタグが見つけたファイルを指します。

––thisを使うと FILE は現在のディレクトリに相対的な ファイルとして解釈されます。このディレクトリはプロジェクトツリーの一部であるべきです。 ファイルの目録タグは計算され、REVISION中に見付かった対応するファイル になります。

          % larch touched-files-prereqs REVISION

このコマンドは REVISION のためのパッチセットを見て、 同じバージョンのすべての以前のパッチセットを見ます(それはこの目的のために リポジトリではなくライブラリを検索します)。それは、ファイルとディレクトリ の重なったものに関係するようなパッチの一覧を報告します — 言い替えると、それは他と独立に適用できるパッチについての情報を与えます。 このコマンドには特定のパターン(e.g. "=README" や "ChangeLog") にマッチするファイル名称 を排除するようなオプションがあります。 また、既に与えられたプロジェクトツリーに適用されているパッチのリストを除外する ようなオプションもあります。また、重なりあっている特定のファイルについての 報告を要求するオプションがあります。

notify は四つの設定ファイルによって制御されます。 設定ファイルはNOTIFICATION-DIRにあります。それは以下の ものです:

        =rules.archives
                Specifies actions to take whenever new categories
                are added to specific archives.

        =rules.categories
                Specifies actions to take whenever new branches
                are added to specific categories.

        =rules.branches
                Specifies actions to take whenever new versions
                are added to specific branches.

        =rules.versions
                Specifies actions to take whenever new revisions
                are added to specific versions.

これらのファイルの中では空白行があってもよく、コメントは '#'で始まり、行末まで 続きます。

ファイル =rules.versions は、以下のような形式の行を含んでいます:

VERSION ACTION

ここで VERSION は完全に修飾されたバージョン名で、動作は以下の形式 の文字列です(空白があってはなりません):

COMMAND:THUNK

新たらしいリビジョンが VERSION中に検出された場合は常に notify が実行されます:

larch COMMAND THUNK RVN ...

ここで COMMAND と THUNK は設定ファイルからのもので、 最後の RVN 引数は新しく検出されたリビジョンの完全に修飾された リビジョン名のリストです。

ファイル =rules.branches も同様です。それは以下の形式の行を含んでいます:

BRANCH COMMAND:THUNK VERSION-ACTION

新しいバージョンが BRANCHに作られると常に notify は 二つの動作をとります。まず以下を起動します:

larch COMMAND THUNK VSN ...

次に、以下のような形式の新しいルール =rules.versions を追加します:

VSN VERSION-ACTION

=rules.categories と =rules.archives はよく似ています。 前者は以下の形式の行を含んでいます:

CATEGORY COMMAND:THUNK BRANCH-ACTION VERSION-ACTION

後者は以下のような形式の行を含みます:

ARCHIVE COMMAND:THUNK CATEGORY-ACT BRANCH-ACT VERSION-ACT

設定ファイルに加えて、notify はプライペートな状態を NOTIFY-DIRに管理します。解くに、それはどのような通知が既に 送信されたかを記録し、同じ通知を何度も送信するのを防ぎます。

あるアーカイブ中のすべてのカテゴリ、ブランチ、バージョンにたいして通知を設定するのは とても簡単です: 単に =rules.archivesファイルを書くだけです — 他の設定ファイルはそれから自動的に生成されます。

最初の=rules.archivesファイルは以下のような行を含んでいるべきです:

ARCHIVE COMMAND:THUNK CATEGORY-ACT BRANCH-ACT VERSION-ACT

トリガーしたい動作ごとに記述します。 設定ファイルを作成後、そのディレクトリで notify を実行してください。最初の実行で リポジトリ中のすべてのカテゴリを検出し、それにたいして COMMAND を実行し、以下のような行を持つ rules.categories ファイルを作ります:

CATEGORY CATEGORY-ACT BRANCH-ACT VERSION-ACT

それからnotifyその設定ファイルを読んで、リポジトリ中のすべてのブランチを 検出し、CATEGORY-ACTを実行して =rules.branchesを作ります。

最後に =rules.versions が同様にして自動生成されます。

新しいカテゴリ、ブランチ、バージョンがアーカイブに追加されるたびに 定義ファイルはその追加を反映する形で自動的に更新されます(当り前 ですがnotify が実行されたときにです。)

以下のコマンドはアーカイブに新しい追加があったことを知らせる email 送信のためのnotifier のルール中で使うことができます:

mail-new-categories mail-new-branches mail-new-versions mail-new-revisions

以下のコマンドは、新しいリビジョンのために起動された場合、my-revision-library で登録されるリビジョンライブラリにそれらのリビジョンを追加するために使うことが できます:

notify-library

最後に noop コマンドは何の動作も必要ない場合の通知イベントの 置き場所として使うことができます。

これらのコマンドを組み合わせて、=rules.archivesファイルを作り 通知を送り、アーカイブのリビジョンライブラリをアップデートするこが できます(長い行は複数行にしてあります):

        lord@emf.net--2003              mail-new-categories:lord \
                                        mail-new-branches:lord \
                                        mail-new-versions:lord \
                                        mail-new-revisions:lord

        lord@emf.net--2003              noop:notify-library:lord \
                                        noop:notify-library:lord \
                                        noop:notify-library:lord \
                                        notify-library:lord

不幸にもこの世界が持っているいくつかの基本的な性質のために、 make it impossible for notify が、それぞれの新しいカテゴリ、 ブランチ、バージョン、あるいはリビジョンに対して、一度だけ起動されることを 経章できない場合があります。 (非常にまれな場合ですが) あるタイミングの割り込みや、システムの異常はnotify に、アーカイブに対する変更に対して、一度異常の動作を起こしてしまうことがあります。

結果として、動作はそのような場兄に対して堅牢な設計となっていなくてはなりません。

notify は並行した起動に対して安全になるよう設計されています: もし二つのプロセスが同時にnotifyを起動した場合、すべてのことが 問題なく動作し、冗長な動作や、 NOTIFY-DIR領域の破壊といった ことはおこりません。

notify を使う戦略のひとつは、cron からの起動です。

以下のコマンドは (そして以下のコマンドだけが) notifyに対して重要であるような形でarchのリポジトリを 修正します:

        make-category
        make-branch
        make-version
        import
        commit
        tag

もしmy-notifierコマンドで通知ディレクトリを登録した場合:

        % larch my-notifier NOTIFIER-DIR

上にリストしたコマンドは動作完了後、端末から切り離されたデーモンを起動し、 そのディレクトリ中で、larch notifyを起動します。 それらのデーモンの開始時刻、終了ステータスは ~/.arch-params/log-file に記録され、デバッグ上の問題が ある場合には役に立ちます。ときどきのそのファイルをクリアすると良いでしょう。