Tutorial/demonstration
Note: この説明は作成中のもので、変化している ソースコードに関係した説明もあります。設計や説明書についての意見がある 人は リストに投げてみて ください。
導入
Bazaar-NG はバージョン管理ツールです。ファイルとサブディレクトリからなる ツリーを管理します。特にツリーのリビジョン を管理しますが、それは ある時点ごとのツリーの状態、それらのリビジョンについての情報、そしておたがいの 関係を表現したものです。ツリーのリビジョンを記録したり抽出することは、 ソフトウェアやドキュメント、その他の同様の創作をしているのであれぱいろいろな 意味で有用です。
- 以前のリビジョンを保存すれば、間違いや、既存の作業内容をチェックする場合に 過去のものに戻ることができます。これは非常に高レベルの無制限の undo 機能の ようにとらえることができます。
- リビジョンごとのコメントを記録すればプロジェクトの注釈履歴を生成することが できます。これは何が、誰によって、なぜ、そしていつ行われたかの説明になります。
- バージョン管理ツールを使えばプロジェクトについて考えるのを助けることも できます: 定期的な機関での安定なした状態版を取得し、それから何をしたかの説明を つければ簡単にプロジェクトを組織化し、追跡することができるようになります。
Bazaar-NG はリビジョンの 祖先 を記憶しています: つまりあるリビジョンの 元になった以前のリビジョンですに。単一のリビジョンは一つ以上の子のりビジョンを 持つ可能性がありますが、それらに対して異なる変更をすればツリーの進化・発展を表現 することができます。ブランチを作ることで Bazaar-NG は進化するプロジェクト上で 複数の人たちが協調して作業することを助けます。このさい、すべての作業には厳格な 排他制御は不要です。単独の開発者にとってもブランチ化は役に立つことがあります。
Bazaar-NG 単一の新しいコマンド bzr をインストールします。他のすべての機能はこのコマンドのサブ コマンドになります。 bzr help でこの一部を表示することができます。 今後、表示できるコマンドの数は増えていくでしょう。
ブランチの作成
履歴はデフォルトではブランチの.bzrディレクトリに保存されます。 これを分離されたリポジトリに保存する機能もあり、その場合、保存先は リモートマシン上でもありえます。既存のディレクトリでbzr init を実行して新しいブランチを作ることができます。
% mkdir tutorial % cd tutorial % ls -a ls -a ./ ../ % pwd /home/mbp/work/bzr.test/tutorial % % bzr init % ls -aF ./ ../ .bzr/ .bzr.log %
.bzr.log はデバッグ時の問題に関する有用な情報を記録したもの です。必要に応じてこのファイルの内部を見たり削除したりすることが できます。バグを見つけた場合にはメーリング リスト に報告してください。このさい .bzr.log の内容も報告 してください。
CVS ではファイルの種別には三つありました: 不明(unkonwn)、無視(ignored)、 そしてバージョン管理下にあるもの(versioned)。addコマンドはファイル をバージョン管理下に置きます: つまり、変更点はシステムによって記録され ます。
% echo 'hello world' > hello.txt % bzr status ? hello.txt % bzr unknowns hello.txt % bzr add -v hello.txt A hello.txt % bzr unknowns
間違ったファイルを追加した場合には bzr removeを使って 取り消してください。これは作業コピーを削除したりはしません。
変更点の確認
何かの作業が完了したら、バージョンの履歴としてそれを コミットしたくなるかも知れません。頻繁にコミットするのは 良い習慣です: 新たらしい機能を追加したり、バグを修正したり、 コードやドキュメントの一部を改良したりした場合です。またコミット する前にコードがコンパイル可能でテストをクリアしたことを確認する のも良い習慣です。こうすればすべてのリビジョンは良い状態に保たれる でしょう。変更点を確認して、本当にやりたいことをコミットしようとして いるかどうかを確かめることもできます。これで永遠に記録されてしまう 前にやったことを再考する機会が与えられることになります。
ここでは二つの bzr コマンドが特にやくにたちます: status と diffです。statusコマンド はファイルごとに一行づつ状態表示します。つまり現在のリビジョンからの 追加(Added)、削除(Deleted)、修正(Modified)、そして名称変更(Renamed) の 状態です。不明なファイル(Unknown)は '?' で示します。--all オプションを使うと status コマンドは修正されていないバージョン管理下 にあるファイルを '.' で、また無視されたファイルも 'I' で表示します。
% bzr status A hello.txt
diff コマンドは標準の unidiff 形式によってすべてのファイル の変更点を表示します。これはpatch, diffstat, filterdiff, colordiff のようなさまざまな プログラムにパイプすることもできます。
% bzr diff *** added file 'hello.txt' --- /dev/null +++ hello.txt @@ -1,0 +1,1 @@ +hello world
-rオプションをつけるとツリーは以前のリビジョンと 比較されます。
[TODO: options to run external diff; to get context diff or other formats; to diff only selected files; to compare two historical revisions.]
修正点のコミット
作業ツリーの状態が満足のいくものになったり、そのブランチを コミットして、この状態のスナップショットを含んだ新しいリビジョン を作ることができます。
commit コマンドはリビジョン中の変更点を記述するメッセージ を引数にとります。それはまた userid, 現在の時刻、タイムゾーン、そして ツリーのインベントリとその内容を記録します。コミットメッセージは -mまたは--messageオプションで指定します。 複数行のコミットメッセージを入力することもできます; ほとんどのシェル では行末で引用符を開いたままにして改行することでこれが可能になります。
% bzr commit -m "added my first file"
[TODO: commit message interactively, through an editor or from a file.]
[TODO: commit only selected files, including renamed/added/deleted files.]
無視するファイル
多くのソースツリーでは、バージョン管理する必要のないファイルが あるものです。たとえばエディタのバックアップファイル、オブジェクトファイル やバイトコードファイル、そしてビルド結果のプログラムです。これらを単に 追加しないようにすることもできますが、これだと常に不明ファイルとして コマンド出力に現れてしまいます。ツリーの最上位ディレクトリに .bzrignoreというファイルを追加することでこれらのファイルを 無視するように bzr に指示することもできます。
このファイルはファイルのワイルドカード(あるいは グロブ
)を
一行にひとつずつ含んでいます。典型的な内容は以下のようなものです:
*.o *~ *.tmp *.py[co]
グロブがスラッシュを含んでいる場合、ツリーの最上位ディレクトリ からのパス全体として一致します; そうでなければそれは単にファイル名 として一致します。このため以前の例 *.o はすべてのサブディレクトリ で無視されますが、以下の例では最上位にあるconfig.h とdoc/ にある HTML ファイルだけが無視されます:
./config.h doc/*.html
どのファイルが無視され、どのパターンと一致するかのリストを得るには bzr ignored コマンドを使います:
% bzr ignored .bzr.log .bzr.log config.h ./config.h configure.in~ *~
無視するパターンがバージョン管理下にあるファイルに一致することも 無視されているファイルを追加することも問題ありません。無視されるパターン はバージョン管理下にあるファイルにはなんの影響も与えません; それは 単にバージョン化されていないファイルが不明(unkown)であるか無視(ignored)されて いるかを示すだけだからです。
.bzrignore ファイルは通常はバージョン管理下に置かれるので ブランチの新しいコピーは同じパターンに出会うことになります:
% bzr add .bzrignore % bzr commit -m "Add ignore patterns"
履歴の確認
さまざまな方法で履歴の調査をすることができます(annotate(注釈) コマンドは後に追加されるでしょう。)
ブランチの統計情報
bzr info コマンドは作業ツリーとブランチ履歴に関する概要情報 を表示します。これはあなたにとって重要な情報を与えるかも知れませんし、 そうでもないかも知れません:
% bzr log
----------------------------------------
revno: 1
committer: mbp@sourcefrog.net
timestamp: Mon 2005-03-14 11:37:47 +1100
message:
added my first file
% bzr info
branch format: Bazaar-NG branch, format 0.0.4
in the working tree:
1 unchanged
0 modified
0 added
0 removed
0 renamed
0 unknown
1 ignored
0 versioned subdirectories
branch history:
1 revision
1 committer
0 days old
first revision: Mon 2005-03-14 11:37:47 +1100
latest revision: Mon 2005-03-14 11:37:47 +1100
bzr はファイルやディレクトリを、名称変更を考慮した形で 追跡し、それらを後でうまくマージすることができるような形でバージョン 管理します。(mv コマンドはまだ動作しません)。
% mkdir src
% echo 'int main() {}' > src/simple.c
% bzr add src
% bzr status
A src/
? src/simple.c
% bzr add src/simple.c
% bzr status
A src/
A src/simple.c
ファイルの削除(deleting) と非バージョン化(removing)
ファイルやディレクトリを削除したい場合には、作業ディレクトリから単に 削除するだけです。これは CVS とは少し違っているところで、CVS では cvs removeも実行する必要があります。
bzr remove は非バージョン化しますが、作業コピーから 削除することはしません。間違ったファイルを追加してしまったり実際には バージョン化されるべきでないファイルをそうしてしまった場合などに やくにたちます。
% rm -r src % bzr remove -v hello.txt ? hello.txt % bzr status ? hello.txt D src/ D src/simple.c
今後の開発
Note: ここから先のコマンドはまだ実装されていませんが今後 bzr がどのようなものに なっていくかを示すことには意味があります。
あるプロジェクトを新規に始めるよりも、すでに存在しているプロジェクトに 変更点を送りたいという場合がよくあります。この場合、そのディレクトリを コピーすることでブランチをもってくるか、tarball を展開するか、 あるいは rsync のようなプログラムでリモートコピーするかします。コピーを 作るのに bzr を利用することもできます。この新しいコピーは潜在的には 新しいブランチなのでこのコマンドは branch と呼ばれます:
% bzr branch http://bazaar-ng.org/bzr/main ./bzr-main % cd bzr-main
このコマンドはブランチの完全な履歴をコピーするので すべての操作をコピーしたローカルマシン上で実行できます: ブランチの ログ表示、注釈表示、ブランチの作成、マージ、などです。望むなら 履歴の一部分だけを取得するようなオプションも実装されるでしょう。
上位アーカイブの変更点の追従
親ブランチの変更点を 引っ張ってくる(pulling) ことで 上位アーカイブの最新の状態についていくことができます:
% bzr pull
これはローカルなブランチが親のブランチの変更点だけを含んでいる 場合にだけうまく動作します。そうでなければブランチは拡散した 状態にある(diverged)と言われ、(pullの)かわりにマージされなくては なりません。
変更点の送信
自分のローカルブランチに変更を加えた後、その変更を上位アーカイブの 管理者に送って、吟味してもらったり、そのブランチに取り込んでもらったり したいと思うかも知れません。
% bzr send --message 'Fix typo in README' Submit patch by mail to mbp@sourcefrog.net [y/n] y
send コマンドはブランチにある変更点のうち、送信先には 加わっていないものを送ります。これにはさまざまな送信方法を利用することが でき、それには email を利用したり、バグ追跡システムへのサブミットなど も含まれます。