DokuWiki の Darcs リポジトリについて

2010 年 1 月まで、DokuWiki のソースコードは Darcs¹⁾ によって管理されていました。現在は Git を使用していますので、DokuWiki への貢献方法については Git のページを参照する必要があります。なお、DokuWiki のプラグインのいくつかはまだ Darcs でメンテナンスされているため、このページは参照目的のためここに残しておきます。

Darcs は CVS の後継のひとつです。Darcs はシンプルで学びやすく使いやすく、かつ現代の分散したソフトウェアプロジェクトのニーズに合致した強力で新しいアプローチを採用しています。Darcs は量子力学をルーツとする「パッチ理論」に基づき、分散化されています。Darcs は GPL ライセンスの元で配布されるフリーソフトウェアです。

どこかで説明されていることをこのページで繰り返すことはしません。代わりに、情報源のリンクを示しておきます。

• Darcs のダウンロード
• Darcs のマニュアル (Getting started の章は非常に良いスタートアップガイドです)
• Darcs Wiki
• Darcs Cheet Sheet (PDF ファイル)

現在の開発版の DokuWiki を取得するには、以下のコマンドを実行します (このコマンドは dokuwiki というディレクトリを作成します)。

darcs get --partial http://dev.splitbrain.org/darcs/dokuwiki

darcs コマンドで取得した DokuWiki をアップデートするには、その DokuWiki ディレクトリの中で以下のコマンドを実行します。

darcs pull

あなたが新しいソースファイルを作成した場合は、以下のコマンドでそのファイルを Darcs リポジトリに加えてください。

darcs add somenewfile

あなたのソースファイル編集が完了した場合は、以下のコマンドを実行します。

darcs record

上記のコマンドはあなたのローカルの Darcs リポジトリをスキャンし、変更箇所を検索し、ローカルのリポジトリにコミットします。このコマンドでコミットしておくと、「darcs pull」コマンドで新規の変更箇所を取得してもローカルで行った変更箇所が上書きされなくなります。CVS とは異なり、この時点では変更したファイルは外部サーバには送信されません。あなた自身のリポジトリ専用の「ローカルタグ」のようなものです。

あなたが変更した箇所を公式リポジトリに反映したい場合は、まず以下のコマンドでパッチファイルを作成してください。

darcs send -o my_doku_patch_file

コマンド名は「darcs send」ですが、このコマンド自体がどこかにファイルを送るわけではありません。このコマンドは、メーリングリスト宛てに手動で送信できる形式のパッチファイルをローカルディスク上に出力します。

• 変更箇所の競合を避けるため、何か新しいパッチを作成する前にはいつでも「darcs pull」を実行してください。
• 「darcs send」で出力されたパッチを提出した後に「darcs amend-record」で既存パッチの修正を行うことは避けてください。十中八九、競合が発生してしまいます。代わりに、最初のパッチを修正するようなパッチを新規に作成してください。
• あなたのエディタが改行コードを変更 (Unix の LF から DOS の CRLF へ) してしまわないように気をつけてください。改行コードが変更された場合はファイル内のすべての行が更新されるため、実際にはわずかな変更でも、ファイル全体が変更されたことになってしまいます。
• ひとつの機能に対してひとつのパッチを作成してください。もし 2 つの機能 (例: 言語ファイル編集と機能の追加) に取り掛かっている場合は、それぞれにひとつずつ、計 2 つのパッチを作成してください。「darcs record」コマンドは実行時にどの変更箇所をパッチに含めるのか質問してきますので、簡単にパッチファイルを分けて出力することができます。
• パッチはメーリングリスト宛てに送信してください。そこで、そのパッチが何をするもので、なぜ作成されたのかを説明してください。
• パッチファイルの容量は気にしないでください。Darcs のパッチは、変更箇所がわずかでも大きくなるものです。しかし、メールサーバの容量などは安いものです。
• いくつかのメールソフトやメールサーバは、プレーンテキストの添付ファイルに変更を加えてしまうことがあります。この場合、Darcs パッチのハッシュ値が変更されてしまいます。安全のため、パッチはメールに添付する前に zip や tar、gzip などで圧縮しておいてください。
• 公式リポジトリの Web インタフェースは、http://dev.splitbrain.org/darcsweb/darcsweb.cgi?r=dokuwiki;a=summaryにあります。

Darcs ではチェックアウトしたものそれぞれがリポジトリでもあるので、独自に加えた変更箇所を自分だけのパッチセットとして保持することができます。この状態でも「マスターリポジトリ」からアップデートすることができます。

実際問題、これはどのような仕組みなのでしょうか? Darcs は魔法を使っているわけではありません。もしあなたがローカルのリポジトリに変更を加え、マスターリポジトリのまさに同じ箇所に変更が加えられた場合は、競合が発生します。これはどのようなバージョン管理システムでも回避できません。

しかし、あなたの変更が、マスターリポジトリで変更されていない箇所に加えた些細なものであれば、全く問題無くマスターリポジトリからアップデートすることができるでしょう。これは、Darcs がパッチを単純に適用しているだけだからです。変更箇所の前後の様子など、パッチを適用するのに十分な情報がある場合は、正常にパッチを当てることができます。

例えばあなたが「html.php」ファイル内の関数のひとつに HTML を少し書き加えるだけであれば、あなたは「darcs pull」コマンドを実行するだけで、簡単に公式のパッチを「html.php」ファイルに適用することができるでしょう。

Darcs は DokuWiki の開発者だけでなく、利用者にとっても有益です。Darcs は、安定版のインストールや次の安定版がリリースされたときのアップデートといった用途にも利用できます。

特定のバージョンの DokuWiki を取得するには、以下のコマンドを実行します。コマンド内の「yyyy-mm-dd」は、バージョン番号に含まれる日付に置き換えてください (例: 2006-11-06)。

darcs get --partial --tag="release yyyy-mm-dd" http://dev.splitbrain.org/darcs/dokuwiki

しかし残念なことに、Darcs には「--partial」と「--tag」オプションを同時に指定した場合に問題が発生するというバグがあります。このバグが修正されるまでは、「--partial」オプションを指定しない以下のようなコマンドを実行した方が良いでしょう。

darcs get --tag="release yyyy-mm-dd" http://dev.splitbrain.org/darcs/dokuwiki

特定のリリース版やリリース候補版、最新の安定版 (stable) にアップデートするには、以下のコマンドを実行します。

darcs pull --tags "release yyyy-mm-dd" --all --quiet
darcs pull --tags "release candidate yyyy-mm-dd" --all --quiet
darcs pull --tags "release stable" --all --quiet

上記の「--all --quiet」オプションは、すべてのパッチが適用されることを保証するとともに、パッチ適用に関する膨大なメッセージを表示させないようにするためのものです。

もしあなたが DokuWiki のコア部分に独自の変更を加えている場合は、以下のように「--all --quiet」オプションを除いたコマンドを実行し、パッチをひとつひとつ確認しながら適用を許可したほうが良いでしょう。

darcs pull --tags "release yyyy-mm-dd"
darcs pull --tags "release candidate yyyy-mm-dd"
darcs pull --tags "release stable"

パッチ適用作業の終わりに、Darcs は、特定のバージョンにアップデートするためのパッチとあなた独自の変更箇所との間に競合が発生しなかったかどうかを知らせてきます。あなたは問題となったファイルを検査し、必要な変更を加えることができます。

独自に変更した箇所は、以下のコマンドで追跡することができます。

darcs whatsnew

なお、以下のコマンドを実行すると、独自の変更箇所について、ひとつひとつ破棄するかどうかを決めることができます。独自の変更箇所が不要となった場合であれば、上記の「darcs whatsnew」で変更箇所を探しつつエディタで削除するのと同様のことができます。

darcs revert --interactive

では、私が CVS や Subversion、arch などではなく、Darcs を選んだのはなぜでしょうか。

私の考えでは、Darcs には有利な点がいくつかあります。

• 閲覧のみのアクセスのために特別なサーバが不要なこと – HTTP サーバであればどんなものでも十分です
• ディレクトリを取り扱えること (SVN や arch も取り扱えます)
• 完全に分散化されており、チェックアウトしたものそれぞれがリポジトリでもあること (arch も同様です)
• 複雑な命名体系が無いこと (arch にはあります)
• 独立したパッチセットを持つこと
• パッチの提供と提供されたパッチの適用が簡単なこと (「darcs send」コマンド)

しかし、不利な点もいくつかあります。

• 時々動作が怪しいこと (深刻ではありません)
• まだあまり知られていないこと

私が一番気に入っているのは、パッチセットです。チェックアウトしたものそれぞれがリポジトリでもあるため、みんなが自分だけの変更箇所をパッチセットとして保持しておくことができ、その状態でも私の「マスターリポジトリ」からアップデートできるのです。このあたりの説明については、前のセクションをご覧ください。