Documentation

Fossil Quick Start

これは読者が苦労無く fossil を利用し始めるためのガイドである。

インストール

Fossil は単一の C プログラムである。 読者はコンパイル済みバイナリを ここから入手するか、 自分でソースからビルドすることを選べる。 fossil のインストールは、そのバイナリファイルを PATH 環境変数の通っている 場所に設置することだけである。

存在するリポジトリのクローン

ほとんどの fossil における操作は、リモートではなくローカルに置いた リポジトリに対して行われる。このため、リモートのリポジトリを利用する場合、 まずそれをローカルにコピーする必要がある。リモートのリポジトリを ローカルにコピーする作業のことを「クローン」と呼ぶ。

リモートリポジトリのクローン方法:

fossil clone URL repository-filename

ここでURLはクローンしたい fossil リポジトリの http URL である。 これには "user:password" 句を含んでいてもよい。例えば http://drh:secret@www.fossil-scm.org/fossilである。 リポジトリファイル名には、好きなように名前を付けられる。 例として、fossil リポジトリを次のようにクローンすることができる:

fossil clone http://www.fossil-scm.org/ myclone.fossil

上の例では「myclone.fossil」と名付けられたように、リポジトリの ローカルコピーは単一のファイルに格納される。 読者は各自のリポジトリに好きな名前を付けられる。「.fossil」拡張子も 付ける必要は無い。

付記: もし読者が制限の厳しいファイアウォールの中に居る場合、 利用のために HTTP プロキシ を設定する必要がある。

新規プロジェクトの開始

fossil によって新プロジェクトを開始したい場合、次のように 空のリポジトリを作成すればよい:

fossil new repository-filename

ローカルリポジトリの設定

クローンなり新規作成なりでローカルのリポジトリを準備した後、 いくつかの設定をローカルリポジトリに対して行いたくなるだろう。 これを行うには、fossil に組み込みの Webサーバを利用すると簡単だ。 fossil の Webサーバを起動するには次のようにする:

fossil ui repository-filename

この操作により、Web サーバは 8080番ポートにて動作を開始する。 別のポートを利用したい場合には、コマンドラインから-portオプション を使うことで指定できる。サーバが立ち上がると fossil はWebブラウザを 起動し、サーバの動いている URL を指すようにする。 読者のシステムの設定によっては fossil がうまくブラウザを操作できない かもしれない。そのような場合には読者自身でブラウザを起動し、 http://localhost:8080/ を指すようにアドレスを設定してほしい。 その後、メニューにある「Admin」リンクをクリックすることで ローカルリポジトリの設定画面に移動することができる。

デフォルト設定では fossil はループバックアドレスである 127.0.0.1 からの 接続に対してログインを求めない。この動作は、いくつかのユーザアカウントを 追加した後に変更することができ、またそうすべきである。

設定を終えたら、(訳注:fossil コマンドラインの動作しているウィンドウに 戻って)コントロール + C キー、または kill コマンドによってミニサーバを 終了させることができる。

ローカルツリーのチェックアウト

fossil でプロジェクトの作業をする場合には、ソースツリーのローカルな 版をチェックアウトする必要がある。ツリーのルートとなるフォルダを作成し、 そこへ cd コマンドで移動した後、次のようにする:

fossil open repository-filename

この操作により、ツリーの最新版をチェックアウトする。 ローカルツリー以下の任意のフォルダにおいて、以下のコマンド群を利用して ローカルツリーの状態を確認することができる:

fossil info
fossil status
fossil changes
fossil timeline
fossil leaves
fossil ls
fossil branches

変更するには

プロジェクトへ新規ファイルを追加、あるいは既存ファイルを削除するには 次のように行う:

fossil add file...
fossil rm file...

また、読者はファイルを自由に操作することができる。変更が一段落して コミットの準備ができたら次のように打ち込む:

fossil commit

すると、チェックイン用のコメントを求めるプロンプトが VISUAL あるいは EDITOR 環境変数に基いてエディタによって表示される。 また、GPG がインストールされていれば、それを使ってチェックインに 署名するためにパスフレーズの入力を求められるだろう。 これらが終わると、変更のチェックインが終了する。

変更を共有するには

読者の行った変更のcommitは、ローカルリポジトリのみに影響する。 この変更点を他のリポジトリにも共有するにはこうする:

fossil push URL

ここで URL は変更を共有したいサーバリポジトリの http: URL である。 もし URL の入力を省略した場合、fossil は一番最近にアクセスしたサーバへ 接続を試みる。

push コマンドは自分の変更点を送るだけである。 他での変更点を受け取るには pull コマンドを使う。 両方を同時に行うには sync を使う:

fossil pull URL
fossil sync URL

pull コマンドによって変更点を取得した場合、それらはリポジトリに格納され、 チェックアウト済みのローカルツリーには影響しない。 これらの変更点をローカルツリーに反映させるには update を使う:

fossil update AID

ここで AID はチェックインごとに付与される40桁の一意な識別子である。 もし AID の指定を省略した場合、fossil は現在のブランチの葉にあたる バージョンを適用する。ブランチが複数の葉を持っていた場合はエラーになる。 その時には AID を指定する必要がある。

ブランチとマージ

同じベースバージョンに対して複数のコミットを行うことでブランチを作ることができる。 これらのブランチを一つにマージし直すには、どれかのブランチで update を行い、他のブランチに対して merge を行っていく:

fossil merge AID

このマージによってソースコードが汚れていないことを確認してから、 commitと、場合によっては push を行う。 読者が commit するまで、あるいは別のリポジトリに push するまで 他の誰も変更を知ることができないことを覚えておいてほしい。

サーバのセットアップ

一番簡単なサーバのセットアップは:

fossil server repository-filename

もしくは

fossil ui repository-filename

これら二つのコマンドの違いは、ui がWebブラウザを立ち上げて アドレスを設定して閲覧できるようにするのに比べ、serverは サーバを起動するのみでブラウザ起動を行わないことである。 チェックアウトしたローカルツリー上に居る場合にはrepository-filenameを 省略することができる。これらのサーバはデフォルトで 8080 番ポートを利用するが -portオプションを指定することで変更できる。

このようなコマンドラインのサーバは、必要に応じて二人の間で リポジトリを共有したい場合に便利である。 恒久的に設置したい場合には CGI サーバか、inetd を利用することができる。 CGI サーバを使うには、次のようなスクリプトを用意する:

#!/usr/local/bin/fossil
repository: /home/proj1/repos1.fossil

コマンドのパスとリポジトリのパスについては、環境に合わせて 適宜変更してもらいたい。このファイルを CGI のパスに置き、 リポジトリファイルを CGI ユーザから読み書きできるように設定する。 それからクライアントで CGI スクリプトを実行させる。これで全てだ。

また、inetd や xinetd によって fossil を動かすこともできる。 例えば inetd で動かす場合、次のような項目を /etc/inetd.conf に追加する:

80 stream tcp nowait.1000 root /usr/bin/fossil \
/usr/bin/fossil http /home/proj1/repos1.fossil

fossil のパスはインストール環境に合わせて変更してほしい。 ここで fossil は root として起動されている。これは必要ではない。 fossil は非特権ユーザから実行できる。しかしながら fossil を root で 実行させた方が安全である。fossil は root として起動されると 自動的に自身をリポジトリと同じフォルダの chroot 環境に置く。 その後、root 特権を外す。

HTTP プロキシ

もし読者がインターネット接続にプロキシを必要とするような 厳しいファイアウォールの中に居るならば、プロキシ設定を行うのに 三つの異なる方法がある。まずはネットワークを利用するコマンド syncclonepushpullについて、 コマンドライン中にプロキシオプションを設定する方法である:

fossil clone URL --proxy Proxy-URL

しかし、これではプロジェクトの内容を同期するたびにプロキシURLを 打ち込まなくてはならない。その代わりにプロキシ設定を setting コマンドで永続化することができる:

fossil setting proxy Proxy-URL

もしくは、環境変数 "http_proxy" を設定する:

export http_proxy=Proxy-URL

プロキシの利用を停止するにはこうする:

fossil setting proxy off

または環境変数の設定を外す。fossil のプロキシ設定は環境変数に優先するが、 コマンドラインオプションはこのどちらも上書きする。 もし永続的なプロキシ設定をしており、一時的に変更したい場合には コマンドラインから簡単に行うことができる。 例えば、同僚のリポジトリに LAN から接続するには:

fossil sync http://192.168.1.36:8080/ --proxy off

更なるヒント

以下のコマンドを試してほしい:

fossil help
fossil test-commands

Explore and have fun!