独りのプロジェクトで arch を使う.
(英語版 (オリジナル)) (ロシア語版) (ドイツ語版) (ブラジル系ポルトガル語版)
このミニガイドでは arch の基本的な機能を簡単に見渡します. これは arch tutorial (日本語訳) を補うものです. はじめにこれを読むことで, 他のミニガイドへ進んだり, arch tutorial へ進んだりする助けになるでしょう.
arch を使い始める前に, アーカイブ (archive)を 準備する必要があります. これはファイルシステム上のディレクトリで, そこにプロジェクトのリビジョン (revision) を格納します. これはローカルなファイルシステム上に無くても構いません. よそにアーカイブを作成して, HTTP, FTP, SFTP 等でアクセスすることができます. ここでは話を簡単にするため, ローカルなアーカイブを使います.
CVSに慣れてる人なら, アーカイブは CVSROOTに似たようなものと考えてよいです.
アーカイブを準備するのは簡単です:
john@shell% tla make-archive john@doe.com--myarchive ~/myarchive john@shell% tla my-default-archive john@doe.com--myarchive
この意味を説明します:
まず,
アーカイブ名 john@doe.com--myarchive に対応する
アーカイブディレクトリ ~/myarchive を作成します.
つぎに, これをデフォルトのアーカイブにします.
うまく行ったかどうかを確かめるため, arch に利用可能なアーカイブの一覧を 尋ねてみます:
john@shell% tla archives
lord@emf.net--2003b
http://arch.quackerhead.com/~lord/archives/lord@emf.net--2003b
john@doe.com--myarchive
/home/john/myarchive
アーカイブは john@doe--myarchive の他にもありますね.
これは archの最新版が置いてあるとこです. こっちはこのガイドでは使いません.
アーカイブ名は次の形式です:
email@address--archive-name
電子メールアドレスは本物である必要はありません. 単にアーカイブを一意にするためのものです. アーカイブ名はこの規約に従わなければなりません.
あなたの初めてのプロジェクトをインポート (import)
できるようになる前の, 最後の段階です.
ここで IDを設定する必要があります.
このために my-id コマンドを使います:
john@shell% tla my-id "John Doe <john@doe.com>"
arch はこれを記憶します (デフォルトアーカイブを記憶してるのと同じです). IDは changelog等で使われます.
アーカイブを準備したので, あなたの初めてのプロジェクトをインポートする準備ができました. このために, ソースが置いてあるディレクトリで作業します. このディレクトリを作業ディレクトリ (working directory)とかプロジェクトツリー (project tree)と呼びます. ほんとに単純な, "hello world"プロジェクトが例題です:
john@shell% cd $wd/hello john@shell% ls hello.py world.py
プロジェクトをインポートする第一歩は, それに名前を付けることです. このプロジェクトを次のように呼ぶことにします:
hello--dev--1.0
これは三つの部分からできていて, それらを二つのハイフン(--)で繋げたものです.
hello
はカテゴリ名 (category name)と呼ばれます.
これはバージョン情報の無いプロジェクト名です.
dev はブランチ名 (branch name)です.
ここで, dev は開発中を意味します. あとで安定版のブランチを加えることはできます.
1.0 はバージョン番号 (version number)です.
以前は, 二つの数字をドット(.)で区切る必要がありました.
しかし, いまでは何個の数字を使っても良いことになってます.
arch ではこの命名フォーマットが強制されます. これは始めはちょっとなじめないかもしれません. しかし, あなたの下で成長することになる, ソフトウェアの特定のリビジョン (revision)を参照するのに便利な方法になるでしょう.
プロジェクトに名前を付けるために, ディレクトリを, arch の作業ディレクトリとして初期化します.
コマンドは init-tree を使います:
john@shell% tla init-tree hello--dev--1.0
john@shell% ls
hello.py world.py {arch}
{arch} ディレクトリが加わったことに注目してください. ここにプロジェクトの名前や, アーカイブについての情報等が格納されます.
デフォルトでは, arch は 明示的なタグ付け法 (explicit tagging method) を使います. つまり, どのファイルをアーカイブに追加するかを arch に明示的に伝える必要があります. このためにファイルにタグを付け(tagging)ます. この例では, 全てのファイルを含めたいとします.
john@shell% tla add *.py
この操作が成功したかどうか確かめるには, ファイルの在庫目録 (inventory) を調べます:
john@shell% tla inventory S ./hello.py S ./world.py
ファイルがタグ付けされていると, S と印が付き (source の略), そうでなければ, U と印が付きます (unrecognised, つまり, 未認識の略) :
john@shell% tla inventory U ./hello.py U ./world.py
作業ディレクトリをアーカイブにインポートする準備ができました. これから二つの段階を踏む必要があります. まず, 関係する カテゴリ(category), ブランチ(branch), リビジョン(revisions) を, アーカイブに作成します. そして, import を実行します. ここでは, tla 1.1 の新機能を使って, 両者を同時に行います:
john@shell% tla import --setup * creating category john@doe.com--myarchive/hello * creating branch john@doe.com--myarchive/hello--dev * creating version john@doe.com--myarchive/hello--dev--1.0 * imported john@doe.com--myarchive/hello--dev--1.0
おめでとう! 例題をなぞってきたならば, 難しいところは片づきました. 以下では, arch でどれだけ楽できるかがわかります.
プロジェクトをインポートしたので, プロジェクトを変更し始めることができます. John Doe が hello.py に新しい機能 - 文字列 hello を, 1回ではなく5回印字する - を加えたとしましょう. アーカイブに変更をコミット (commit)する前に, 辺りを見回して, これが正しいか, そして, テスト用のコードを残してないかを確認したいとします.
このために, arch が提供するコマンドは what-changed です:
john@shell% tla what-changed M ./hello.py
これでわかることは, hello.py が変更 (M は modify の頭文字) されたことです. 変更点を正確に見渡すために, John はアーカイブにあるバージョンと変更後のものとの 差分を必要とします. このために, what-changed に引数を加えることができます:
john@shell% tla what-changed --diffs M ./hello.py * modified files --- orig/hello.py +++ mod/hello.py @@ -1,3 +1,4 @@ #!/usr/bin/env python -print "hello" +for i in range(5): + print "hello"
この意味は, 一行が除去され, 二行が加えられた. ということです.
注意点は, これらのコマンドが最近のアーカイブ版の, キャッシュされたコピー - プリスティンツリー (pristine tree) と呼ばれます - を使ったことです (pristine (純粋な) というのは, 最近のバージョンで変更が加わってないからです). これはネットワークから切り離された環境での作業で特に有用です. 変更点を知るのに, アーカイブに接続する必要はありません.
John は変更点が予想通りなので満足です. そこで変更点をアーカイブへコミットしたいとします.
このために, arch が提供するコマンドは commit です:
john@shell% tla commit -L "print hello 5 times instead of 1"
M ./hello.py
* update pristine tree (john@doe.com--myarchive/hello--dev--1.0--base-0
=> hello--dev--1.0--patch-1)
* commited john@doe.com--myarchive/hello--dev--1.0--patch-1
注目点は, 引数 -L です. これを使うと, コマンドラインでログメッセージ (log message) を指定できます.
これは急ぎの変更で便利です. しかし, 時には詳細なログメッセージが必要です.
このため, コミットする前に ログメッセージを書く方法があります.
沢山の変更があって, 変更点を入念に記録する必要がある場合,
コミットする前にログメッセージを作れると便利です.
このために, arch の make-log コマンドがあります:
john@shell% tla make-log /home/john/wd/hello/++log.hello--dev--1.0--john@doe.com--myarchive john@shell% cat ++log.hello--dev--1.0--john@doe.com--myarchive Summary: Keywords:
これは空のログメッセージを作成し, そのファイル名を印字します. よくやるのは, ファイル作成と同時に編集することで, こんな具合にします:
john@shell% $EDITOR $(tla make-log) Warning: not overwriting existing log file <エディタが立ちあがる>
ファイルの冒頭にある summary の行に変更点を簡潔に記述します - 普通は 60字程度より短かくです. keywords の欄はあまり使われません. keywords 以降の部分は ログメッセージ本体として扱われます. いくら長くても構いません.
John がログメッセージを以下のように書いたとしましょう:
Summary: print hello 5 times instead of 1 Keywords: Upon a request from a user, I have made hello print 5 times instead of 1. You can still obtain the old functionality by running hello | tail -1. Comments on this change are welcome.
変更を commit する場合, 引数 -L は省けます:
john@shell% tla commit
M ./hello.py
* update pristine tree (john@doe.com--myarchive/hello--dev--1.0--base-0
=> hello--dev--1.0--patch-1)
* commited john@doe.com--myarchive/hello--dev--1.0--patch-1
アーカイブの変更点一覧を手に入れるために,
revisions コマンドが使えます.
arch は log-ls コマンドも提供しています.
これは作業ディレクトリの変更点一覧を示します.
複数の人が同じブランチで作業してる場合,
作業ディレクトリ中の変更点がアーカイブでの変更点より少ないこともありえます.
しかし, ここではその場合は考えません.
これらの変更点の記述は パッチログ (patch log) に含まれてます. パッチログは電子メールの文に似ていて, 内容は, 変更点の記述や日付等です. パッチログはアーカイブと作業ディレクトリ の両方に格納されてるので, もしラップトップ上で作業してて, アーカイブにアクセスできないときでも, ツリーに適用された変更点一覧の全てを入手できます.
revisions コマンドはこんな感じで使います:
john@shell% tla revisions --summary
base-0
initial import
patch-1
print hello 5 times instead of 1
独り開発者のブランチでは, log-ls は常に同じものを印字します.
ここで, いろいろ引数を試してみます:
john@shell% tla log-ls --summary --creator
base-0
John Doe <john@doe.com>
initial import
patch-1
John Doe <john@doe.com>
print hello 5 times instead of 1
作者名を見てください.
これは以前に my-id コマンドで与えたものです.
上で説明した patch log は log-ls や
revisions コマンド の出力よりも多くの情報を記述します.
これらを取得するために, arch は changelog コマンド を
提供します:
john@shell% tla changelog
# do not edit -- automatically generated by arch changelog
# arch-tag: automatic-ChangeLog--john@doe.com--myarchive/hello--dev--1.0
#
2003-07-13 09:36:33 GMT John Doe <john@doe.com> patch-1
Summary:
print hello 5 times instead of 1
Revision:
hello--dev--1.0--patch-1
Upon a request from a user, I have made hello print 5 times instead of 1.
You can still obtain the old functionality by running hello | tail -1.
Comments on this change are welcome.
modified files:
./hello.py
2003-07-13 08:58:18 GMT John Doe <john@doe.com> base-0
Summary:
initial import
Revision:
hello--dev--1.0--base-0
(automatically generated log message)
new files:
./hello.py ./world.py
changelog コマンドはリポジトリから変更点一覧を入手します.
まだ全然作業をしてない場合でも, 完全な変更点一覧を表示します.
John による新しいバージョンの hello が, それを使ってた別のプログラムで壊れたと, John は報告を受けました. その問題を John の update したもので調べるため, 昔のリリースにアクセスしたいとします.
(すでに忘れてしまっている)変更点を確認することから始めます:
john@shell% cd
john@shell% tla revisions --summary hello--dev--1.0
base-0
initial import
patch-1
print hello 5 times instead of 1
revisions コマンドへのプロジェクト名の与え方に注意してください.
これは, 作業ディレクトリを離れていて, 関係するプロジェクトが無いためです.
John は一覧を見て, base バージョンが必要だと気付きました (もし, もっと沢山のパッチを選ぶ余地があれば, より以前のパッチを選ぶかもしれません). base-0 リビジョンを取得するため, 以下のコマンドを使うことができます:
john@shell% tla get hello--dev--1.0--base-0 * from import revision: john@doe.com--myarchive/hello--dev--1.0--base-0 * making pristine copy * tree version set john@doe.com--myarchive/hello--dev--1.0
これは hello--dev--1.0--base-0 という名前のディレクトリを作ります.
別の名前を指定することもできます:
john@shell% tla get hello--dev--1.0--base-0 mydir
最新のリビジョンが必要なら, てっとりばやい方法があります. バージョン指定子 (version specifier) (base-0, patch-1, 等)は次のように省けます:
john@shell% tla get hello--dev--1.0