svn cleanupとは？使い方と役割を徹底解説

はじめに：Subversion作業の「お掃除役」`svn cleanup` を知る

バージョン管理システムは、ソフトウェア開発やドキュメント作成において不可欠なツールです。その中でも、長く広く利用されているシステムの一つが Subversion (SVN) です。Subversion を使う上で、誰もが一度は遭遇するかもしれない問題があります。それは、「作業コピー (Working Copy) がロックされて操作できない」「特定の操作が途中で中断されてしまい、次に進めない」「何だか作業コピーの状態がおかしい」といった状況です。

このような、Subversion の作業コピーの状態が一時的に不正になったり、ロックされてしまったりした際に、その状態を健全に戻すために使用される非常に重要なコマンドがあります。それが svn cleanup です。

svn cleanup は直訳すれば「お掃除」です。まさにその名の通り、作業コピー内に残ってしまった不完全な状態、操作の中断痕跡、不要な一時ファイルなどをきれいにして、作業を再開できるようにしてくれるコマンドなのです。しかし、単に「お掃除」と言っても、具体的に何をしてくれるのか、どのような状況で必要なのか、どのように使うのが正しいのか、そして使う上でどんな注意点があるのかを正確に理解している人は少ないかもしれません。

この記事では、Subversion の svn cleanup コマンドについて、その役割から使い方、内部動作、必要な状況、そして利用上の注意点に至るまで、徹底的に解説します。この記事を読むことで、あなたは svn cleanup がなぜ必要なのか、どのように活用すればSubversionでの作業がよりスムーズになるのかを深く理解できるようになるでしょう。Subversion ユーザーであれば、作業効率と問題解決能力を大きく向上させるために、ぜひ最後までお読みください。

対象読者は、Subversion を日常的に利用している開発者、テスター、ドキュメント作成者など、すべての Subversion ユーザーです。基本的な Subversion コマンド（checkout, update, commit, status など）の使い方は理解している前提で解説を進めます。

第1章：Subversion (SVN) の基本と作業コピーの状態管理

svn cleanup の役割を理解するためには、まず Subversion がどのように動作し、作業コピーの状態をどのように管理しているのかを知る必要があります。

1.1 Subversion (SVN) とは

Subversion は集中型バージョン管理システム (Centralized Version Control System, CVCS) の一つです。中央にリポジトリと呼ばれるデータの保管場所があり、ユーザーはそのリポジトリからコードやドキュメントの最新版（または過去の特定のリビジョン）を自分のコンピューターに持ってきて作業を行います。この手元にある作業用の領域が「作業コピー (Working Copy)」です。

ユーザーは作業コピー内でファイルの追加、削除、編集などの変更を行い、その変更をリポジトリに「コミット (commit)」することで、他のユーザーと共有します。他のユーザーが行った変更は、リポジトリから自分の作業コピーに「アップデート (update)」することで取り込みます。

1.2 リポジトリと作業コピーの関係

リポジトリ (Repository): バージョン管理されるすべてのファイル、ディレクトリ、そしてそれらの変更履歴が集中して保存されている場所です。原則として、リポジトリは常に一貫性のある健全な状態を保つように設計されています。
作業コピー (Working Copy): リポジトリの特定のリビジョンをローカルにコピーしたものです。ユーザーは作業コピー内で自由に作業を行い、変更内容を確認したり、コミットしたり、リポジトリの最新状態に追従したりします。

作業コピーはリポジトリからチェックアウト (checkout) されるか、既存の作業コピーをアップデートすることで作成/更新されます。作業コピーは単にリポジトリのファイル群をコピーしただけではなく、それぞれのファイルやディレクトリがリポジトリのどのリビジョンに対応しているか、ローカルで行った変更は何か、といったバージョン管理に必要な情報（メタデータ）を保持しています。

1.3 作業コピーの状態管理の重要性

作業コピーが Subversion によるバージョン管理を正しく行うためには、その状態が正確に管理されている必要があります。この状態管理は、作業コピー内の各ディレクトリに存在する特殊な隠しディレクトリ (.svn ディレクトリ) によって行われます。

.svn ディレクトリ内には、そのディレクトリおよびサブディレクトリ下のファイルやディレクトリに関するさまざまな情報が格納されています。例えば：

各ファイル/ディレクトリがリポジトリのどのリビジョンに対応しているか
ローカルで行われた変更内容の追跡情報
予約されたプロパティ (svn:ignore, svn:keywords, svn:eol-style など)
保留中の操作に関する情報
作業コピーのロック情報

この .svn ディレクトリ内のメタデータは、Subversion コマンド（status, update, commit など）が正常に動作するために不可欠です。もしこのメタデータが破損したり、作業中に中断された操作によって不整合な状態になったりすると、Subversion コマンドは正しく機能できなくなります。

1.4 作業コピーが「汚れた」状態とは？

通常、Subversion のコマンドは、作業コピーの状態を常に整合性が取れた状態に保とうとします。しかし、予期せぬ事態が発生した場合、作業コピーの状態が一時的に「汚れた」状態、つまり不整合な状態になってしまうことがあります。このような状態は、主に以下のような状況で発生します。

Subversion 操作の強制終了: svn update や svn commit、svn switch、svn merge などの比較的時間がかかる操作の途中で、ユーザーが Ctrl+C でプロセスを中断したり、ネットワークが切断されたり、コンピューターがクラッシュしたりした場合です。これらの操作は、完了するまで作業コピーの状態を一時的に変更し、操作が完全に終わることで最終的な状態に落ち着きます。しかし、途中で中断されると、作業コピーは中途半端な状態のまま取り残されてしまいます。
作業コピーのロック: Subversion は、複数の操作が同時に作業コピーのメタデータにアクセスして不整合を起こすことを防ぐために、操作中に作業コピーの一部または全体をロックする機構を持っています。正常に操作が完了すればロックは自動的に解除されますが、操作が中断されると、ロックが解除されないまま残ってしまうことがあります。ロックされた作業コピーに対して、別の Subversion コマンドを実行しようとすると、「作業コピーはロックされています」といったエラーが表示され、操作が進められなくなります。
メタデータの破損: まれに、ファイルシステムの異常やその他の原因によって、.svn ディレクトリ内のファイル（特にメタデータファイル）が物理的に破損したり、内容が論理的に不整合を起こしたりすることがあります。
不完全な操作の痕跡: 中断された操作は、.svn ディレクトリ内にその操作に関する情報や一時ファイルとして痕跡を残すことがあります。これらの痕跡が残っていると、次に行うべきSubversion操作が正しく開始できない場合があります。

これらの「汚れた」状態は、その後の Subversion 作業を妨げる原因となります。ここで登場するのが、これらの問題を解決し、作業コピーの状態を健全に戻すためのコマンド、svn cleanup なのです。

第2章：`svn cleanup` とは何か？その役割

svn cleanup コマンドは、Subversion の作業コピーに発生した不整合やロックを解消し、作業コピーの状態を健全な状態に戻すためのコマンドです。これは、Subversion での作業中に発生する多くの問題、特に「作業コピーがロックされています」というエラーに直面した際に、最初に試すべきコマンドとして広く認識されています。

2.1 `svn cleanup` の主な役割

svn cleanup が行う主要な処理は以下の通りです。

作業コピーのロック解除 (Unlock Working Copy):
- これは svn cleanup の最も一般的で重要な役割です。Subversion は、特定の操作（アップデート、コミット、スイッチ、マージなど）を実行する際に、作業コピー内のディレクトリに対してロックをかけ、他の Subversion プロセスが同時にその作業コピーを変更することを防ぎます。操作が正常に完了すればこのロックは自動的に解除されます。しかし、操作が途中で中断された場合、このロックが解除されずに残ってしまうことがあります。
- ロックが残った状態の作業コピーに対して別の svn コマンドを実行しようとすると、通常「作業コピーはロックされています」(Working copy is locked) という旨のエラーが表示され、そのコマンドは実行できません。
- svn cleanup は、作業コピー全体または指定されたパス以下に残っている不要なロック情報を検出し、それを強制的に解除します。これにより、ロックが原因でブロックされていた他の Subversion 操作を実行できるようになります。
不完全な操作の完了または巻き戻し (Complete or Rollback Incomplete Operations):
- svn update, svn commit, svn switch, svn merge などの操作は、完了するまでにいくつかの内部ステップを経ます。これらの操作が途中で中断された場合、作業コピーは中途半端な状態になり、次の操作に進むための内部的な準備ができていない状態になることがあります。
- svn cleanup は、.svn ディレクトリ内に記録されている、中断された操作に関する情報（保留中のログなど）を確認します。そして、可能な限りその中断された操作を安全に完了させるか、または操作を開始する前の状態に巻き戻すことで、作業コピーの状態を整合性が取れた状態に戻そうとします。
- 例えば、アップデート中に中断された場合、cleanup は途中まで適用された変更を元に戻したり、適用途中のファイルをクリーンアップしたりする可能性があります。
破損したメタデータの修復 (Limited Metadata Repair):
- .svn ディレクトリ内のメタデータファイルが軽度に破損したり、論理的な不整合を起こしたりした場合、svn cleanup がその検出を試み、可能な範囲で修復を行うことがあります。
- ただし、これは限定的な機能です。深刻なメタデータ破損（例えば、ファイルシステムレベルの障害による物理的な破損）に対して svn cleanup は無力であり、その場合は作業コピーを削除して再度チェックアウトするなどの別の手段が必要になります。
一時ファイルの削除 (Remove Temporary Files):
- Subversion の操作中に、一時的に使用されるファイルが .svn ディレクトリ内や作業コピー内の他の場所に作成されることがあります。操作が正常に完了すればこれらのファイルは自動的に削除されますが、中断された場合には残ってしまうことがあります。
- svn cleanup は、このような操作の痕跡として残った不要な一時ファイルを削除し、作業コピーをクリーンな状態にします。
競合状態の解消補助 (Limited Assistance with Conflicts):
- svn update や svn merge によって発生した競合 (conflict) が未解決のままである場合、その競合ファイル自体や、競合解消プロセスに関連するロックなどが残っていることがあります。
- svn cleanup は、競合そのものを自動的に解消したり、競合マーカー付きのファイルを変更したりすることは ありません。競合ファイルの解決はユーザーの手動作業または svn resolve コマンドで行う必要があります。
- しかし、競合解消プロセスを妨げている可能性のあるロックや一時ファイルを svn cleanup が除去することで、競合状態からの復旧作業を進めやすくする効果はあります。
外部定義 (svn:externals) の処理:
- svn:externals プロパティで定義された外部リポジトリの内容を作業コピー内にチェックアウト/アップデートする操作が中断された場合、それに関連するロックや不整合が残ることがあります。svn cleanup は、これらの外部定義に関連する不整合も解消しようと試みます。

2.2 `svn cleanup` が「しない」こと

svn cleanup は非常に便利なコマンドですが、何でも解決してくれるわけではありません。特に以下の点を理解しておくことが重要です。

ローカルでのファイル内容の変更を取り消さない: あなたがテキストエディタなどでファイルの内容を変更したローカルモディフィケーションは、svn cleanup を実行してもそのまま残ります。変更を取り消したい場合は、svn revert コマンドを使用する必要があります。
競合を自動的に解消しない: ファイルの内容が競合 (conflict) している場合、Subversion はファイル内に競合マーカー（<<<<<<<, =======, >>>>>>>）を挿入します。svn cleanup はこれらのマーカーを自動的に処理したり、ファイルの内容を自動的に解決したりしません。競合の解決は手動で行うか、svn resolve コマンドで解決済みとマークする必要があります。
リポジトリ側の問題を解決しない: svn cleanup はあくまで作業コピーに対して動作するコマンドです。リポジトリ側で発生した問題（例: リポジトリの破損、サーバーの停止）は svn cleanup では解決できません。
作業コピーを最新の状態に更新しない: svn cleanup は作業コピーの状態を「修復」しますが、リポジトリの最新のリビジョンを作業コピーに取り込むわけではありません。リポジトリの最新の状態にしたい場合は、別途 svn update コマンドを実行する必要があります。
バージョン管理外のファイルを自動的に無視しない（デフォルト設定の場合）: --remove-unversioned などのオプションを指定しない限り、ローカルで新規に作成したものの svn add していないファイルやディレクトリは svn cleanup の実行によって削除されることはありません。ただし、後述する削除系オプションを指定した場合はこの限りではありません。

これらの点を踏まえると、svn cleanup は主に作業コピーの「基盤となるメタデータや状態の整合性」に関わる問題を解決するコマンドであり、ユーザーのローカル変更内容やリポジトリとの同期状態そのものを操作するものではない、ということが理解できます。

第3章：`svn cleanup` の使い方

svn cleanup コマンドの基本的な使い方と、よく利用されるオプションについて解説します。

3.1 基本的な構文

svn cleanup コマンドの最も基本的な構文は以下の通りです。

bash svn cleanup [PATH...]

PATH: クリーンアップを実行したい対象のファイルまたはディレクトリを指定します。複数のパスを指定することも可能です。

3.2 PATH の指定

特定のパスを指定する場合: svn cleanup の後に、クリーンアップしたいファイルやディレクトリのパスを指定します。例えば、my_project/src/ ディレクトリとその配下だけをクリーンアップしたい場合は svn cleanup my_project/src と実行します。
bash svn cleanup path/to/specific/directory svn cleanup path/to/specific/file
パスを指定しない場合: svn cleanup コマンドを引数なしで実行した場合、コマンドを実行した現在のディレクトリ（カレントディレクトリ）に対して、再帰的にクリーンアップが実行されます。
bash svn cleanup
これは最も一般的な使い方であり、多くの場合はこの引数なしでの実行で作業コピー全体または大部分のロックや不整合を解消できます。なぜなら、Subversion のロックはディレクトリ階層全体に影響を及ぼす可能性があるため、問題が発生している場所だけでなく、その親ディレクトリも含めてクリーンアップを行うのが効果的だからです。通常、問題が発生した作業コピーのルートディレクトリ（チェックアウトした一番上のディレクトリ）で svn cleanup を実行することが推奨されます。

3.3 実行時の出力例

svn cleanup を実行すると、通常は以下のような出力が表示されます。

bash $ svn cleanup

（問題がなければ、何も出力されないか、完了を示すメッセージが表示される）

bash $ svn cleanup path/to/directory

svn: warning: W150001: 'path/to/directory' is not a working copy root
（ワーキングコピーのルート以外で実行した場合の警告。クリーンアップ自体は実行される。）

$ svn cleanup

Cleaning up '.'
（カレントディレクトリに対してクリーンアップを実行していることを示すメッセージ）

$ svn cleanup path/to/directory

Cleaning up 'path/to/directory'
（指定したディレクトリに対してクリーンアップを実行していることを示すメッセージ）

問題が検出され、クリーンアップ処理が行われた場合は、その内容を示すメッセージが表示されることがあります。例えば、ロックを解除した場合などです。エラーが発生した場合は、その旨のエラーメッセージが表示されます。

3.4 よく使うオプション

svn cleanup は比較的単純なコマンドですが、いくつかの便利なオプションを持っています。特に Subversion 1.9 以降で追加された削除系のオプションは強力ですが、使用には注意が必要です。

一般的なオプション

-h または --help:
- svn cleanup コマンドの使い方、構文、利用可能なオプションを表示します。
  bash svn cleanup --help
--verbose (-v):
- クリーンアップ処理中に実行された詳細な情報を出力します。どのディレクトリで何を行っているかなどを詳しく知りたい場合に有用です。
  bash svn cleanup --verbose
--quiet (-q):
- 通常の出力を抑制し、エラーメッセージのみを表示します。スクリプトなどから実行する場合に便利です。
  bash svn cleanup --quiet

Subversion 1.9 以降で追加された削除系オプション（使用注意！）

これらのオプションは、バージョン管理されていないファイルや、無視されているファイルなどを作業コピーから削除します。クリーンアップと同時に不要ファイルを整理できるため便利な場合がありますが、意図しないファイルを削除してしまうリスクもあるため、使用には細心の注意が必要です。

--remove-unversioned:
- Subversion によってバージョン管理されていないファイルやディレクトリを作業コピーから削除します。これらは svn status の出力で ? で示されるアイテムです。ローカルで一時的に作成したファイルや、svn add を忘れていた重要なファイルまで削除してしまう可能性があるため、非常に危険なオプションです。
  bash svn cleanup --remove-unversioned
--remove-ignored:
- svn:ignore プロパティやグローバル設定で無視されているファイルやディレクトリを作業コピーから削除します。これらは svn status の出力で I で示されるアイテム（svn status --no-ignore の場合は ?）です。ビルド生成物やログファイルなど、通常は削除しても問題ないものが多いですが、念のため注意が必要です。
  bash svn cleanup --remove-ignored
--remove-external-items:
- svn:externals プロパティで定義された外部リポジトリからチェックアウト/アップデートされたアイテムを作業コピーから削除します。
  bash svn cleanup --remove-external-items
--remove-degenerate:
- --remove-unversioned, --remove-ignored, --remove-external-items の3つをまとめて指定したのと同じ効果があります。最も危険なオプションの組み合わせと言えます。
  bash svn cleanup --remove-degenerate

【重要】削除系オプションの注意点:

これらの削除系オプションを使用する前には、必ず svn status または svn status --no-ignore コマンドを実行して、削除される可能性のあるファイルを確認してください。特に --remove-unversioned オプションは、意図せず大切なファイルを失う可能性があるため、本当に必要な場合以外は使用しないことを強く推奨します。これらのオプションを使わずにクリーンアップだけを行いたい場合は、何も指定しないか、標準的なオプションのみを使用します。

--depth ARG:
- 再帰的な操作の深さを指定します。empty, files, immediates, infinity (デフォルト) などがあります。通常、cleanup は再帰的に実行される (infinity がデフォルト) ため、このオプションを使うことは稀です。特定のサブディレクトリ以下のクリーンアップだけを行いたい場合は、そのサブディレクトリを PATH 引数として指定する方が一般的です。

3.5 複数のパスを指定する場合

複数の特定のディレクトリやファイルに対してクリーンアップを実行したい場合は、それぞれのパスをスペース区切りで指定します。

bash svn cleanup /path/to/dir1 /path/to/file2 /path/to/another/dir3

この場合、指定されたそれぞれのパスに対して再帰的にクリーンアップが試みられます。ただし、多くの場合は作業コピーのルートディレクトリで引数なしの svn cleanup を実行する方が、問題の根本的な解決につながりやすいです。

第4章：`svn cleanup` が必要な具体的なシナリオ

ここでは、実際にどのような状況で svn cleanup コマンドが必要になるのか、具体的なシナリオをいくつか紹介します。

4.1 シナリオ1：「作業コピーはロックされています」エラーが発生した場合

これは svn cleanup が最もよく利用される状況です。svn update, svn commit, svn switch, svn merge などの Subversion コマンドを実行しようとした際に、以下のようなエラーメッセージが表示されて操作が拒否されることがあります。

svn: E155004: Working copy 'path/to/working/copy' is locked. svn: E155004: Run 'svn cleanup' to remove locks (type 'svn help cleanup' for details)

または、古い Subversion バージョンでは以下のようなメッセージの場合もあります。

svn: Working copy locked; try 'svn cleanup'

原因:
これは、前回の Subversion 操作（アップデート、コミットなど）が正常に完了せず、作業コピーにロックが残ってしまっている状態です。操作中に Ctrl+C で中断したり、ネットワークエラー、システムクラッシュなどによって発生します。

対処法:
エラーメッセージにも示されている通り、svn cleanup コマンドを実行することで、残ったロックを解除します。通常は、問題が発生している作業コピーのルートディレクトリに移動し、引数なしで実行します。

bash cd /path/to/working/copy_root svn cleanup

svn cleanup が正常に完了すれば、ロックが解除され、中断されていた操作や次に実行したかった操作（例: svn update, svn commit）が実行できるようになります。

4.2 シナリオ2：アップデートやコミットが途中で止まる、エラーになる

svn update や svn commit を実行した際に、処理が途中でフリーズしたり、予期しないエラーが発生して完了しなかったりする場合があります。エラーメッセージが具体的でなく、「処理できませんでした」「内部エラー」のような曖昧なものであることもあります。

原因:
操作の中断による不完全な状態や、.svn ディレクトリ内のメタデータの軽微な不整合が原因である可能性があります。ロックがかかっている場合もこのような挙動を示すことがあります。

対処法:
まずは svn cleanup を試してみてください。作業コピーのルートディレクトリで実行するのが一般的です。

bash svn cleanup

cleanup が不完全な操作の痕跡をクリーンアップしたり、メタデータの整合性を回復させたりすることで、その後の svn update や svn commit が正常に完了するようになる可能性があります。

4.3 シナリオ3：競合 (Conflict) が発生し、その後の操作がうまくいかない

svn update や svn merge を実行した際にファイルが競合し、C ステータスとして表示されたとします。この競合を解消する作業を進める前に、例えば別のファイルをコミットしようとしたり、さらにアップデートしようとしたりすると、ロックなどが原因でエラーになることがあります。

原因:
競合解消プロセスに関連するロックや、不完全な状態が残っている可能性があります。

対処法:
この場合も svn cleanup が有効な場合があります。

bash svn cleanup

svn cleanup は競合ファイルの内容自体（競合マーカー）を変更したり、競合を自動解消したりはしません。しかし、競合解消のステップ（例: 競合を解決した後に svn resolved を実行する）を進める上で妨げになっているロックや不完全な状態を取り除くことができます。cleanup の後、競合ファイルを編集して手動で解決し、svn resolved を実行して Subversion に解決済みであることを伝え、その後の作業（コミットなど）を進めることになります。

4.4 シナリオ4：特定のファイルやディレクトリに対する操作がエラーになる

特定のファイルやディレクトリに対して svn status, svn info, svn diff などのコマンドを実行しようとした際に、「指定されたパスは作業コピーではありません」「メタデータが見つかりません」といったエラーや、不可解な挙動を示すことがあります。

原因:
その特定のファイルやディレクトリ、あるいはその親ディレクトリの .svn ディレクトリ内のメタデータに問題がある可能性があります。あるいは、過去の中断された操作がそのパスに関連する不完全な状態を残しているのかもしれません。

対処法:
エラーが発生したパス、またはその一つか二つ上の親ディレクトリを指定して svn cleanup を実行してみてください。

bash svn cleanup /path/to/problematic/directory

指定されたパス以下に絞ってクリーンアップが試みられ、問題が解決する場合があります。ただし、問題が作業コピー全体のメタデータ構造に関わる場合は、作業コピーのルートで svn cleanup を実行する必要があります。

4.5 シナリオ5：`svn status` の出力が異常な場合

svn status を実行した際に、本来表示されるべきでないファイルが表示されたり、ファイルのステータスが何度も実行するたびに変わったり、あるいは全く表示されなかったりするなど、作業コピーの状態表示がおかしいと感じる場合があります。

原因:
作業コピーの内部状態管理が不整合を起こしている可能性があります。.svn ディレクトリ内のメタデータが破損している、あるいは不完全な操作が残っていることが考えられます。

対処法:
まずは svn cleanup を実行して、作業コピーの内部状態をリセットする試みを行います。

bash svn cleanup

cleanup がメタデータの軽微な修復や不完全な操作の解消を行うことで、svn status の出力が正常に戻る場合があります。それでも改善しない場合は、メタデータの破損が深刻である可能性が高く、その場合は作業コピーの再チェックアウトを検討する必要があります。

まとめ：`svn cleanup` は「何かおかしいな」と思ったときの最初の選択肢

上記のように、svn cleanup は様々な状況で役立ちます。特に、Subversion の操作が予期せず中断された後や、作業コピーの挙動がおかしいと感じたときには、まず svn cleanup を試してみるのが良い習慣です。ほとんどの場合、問題の原因となっているロックや一時的な不整合は svn cleanup によって解消されます。

第5章：`svn cleanup` の内部動作 (より深く理解するために)

svn cleanup がどのように問題を解決するのかを理解するために、その内部動作、特に関連する作業コピーの構造とロック機構について詳しく見ていきましょう。

5.1 `.svn` ディレクトリの役割と構造の進化

Subversion の作業コピーには、各ディレクトリに隠しディレクトリ .svn が存在し（Subversion 1.7 以降は作業コピーのルートディレクトリに集約されました）、そこでそのディレクトリおよび配下のバージョン管理情報が管理されています。

Subversion 1.6 以前の構造

Subversion 1.6 以前では、バージョン管理されているディレクトリのそれぞれに .svn ディレクトリが存在しました。この .svn ディレクトリ内には、以下のような情報が格納されていました。

entries: そのディレクトリ内のファイルやサブディレクトリに関するメタデータ（名前、リビジョン、URLなど）
text-base: ファイルのベースリビジョン（チェックアウト/アップデートした時点のリビジョン）のコピー
prop-base: ファイルやディレクトリのプロパティのベースリビジョンコピー
tmp: 一時ファイルやロックファイル
lock: ディレクトリ単位のロックファイル

この構造では、各ディレクトリが自身の情報を管理していましたが、作業コピー全体の状態を一元的に管理するのが難しく、操作が中断された際のロックファイルなどが複数の .svn ディレクトリに散在するという問題がありました。svn cleanup も、問題を解消するために作業コピー全体を再帰的に探索して、各ディレクトリの .svn ディレクトリに対して処理を行う必要がありました。

Subversion 1.7 以降の構造 (WC-NG)

Subversion 1.7 で導入された WC-NG (Working Copy Next Generation) と呼ばれる新しい作業コピー形式では、すべてのバージョン管理情報が作業コピーのルートディレクトリにある単一の .svn ディレクトリに集約されました。

このルートの .svn ディレクトリ内には、主に以下のものが格納されています。

wc.db: SQLite データベースファイル。作業コピー全体に関するすべてのメタデータ（ファイル/ディレクトリの状態、リビジョン、プロパティ、ローカル変更の追跡、外部定義、ロック情報など）が一元的に管理されています。
pristine: ファイルのベースリビジョン（編集していないクリーンな状態）のコピーを格納する場所。コンテンツはハッシュ値で管理され、重複を排除して効率的に格納されます。
tmp: 一時ファイルなどが格納される場所。

WC-NG では、作業コピーの状態管理がデータベース (wc.db) によって一元化されたため、Subversion の多くの操作（status, update, commit など）のパフォーマンスが向上し、作業コピーの状態管理もより堅牢になりました。svn cleanup も、主にこの wc.db ファイルに対して処理を行うことで、ロックの解除や不完全な操作の解消を実現しています。

5.2 ロック機構の詳細

Subversion の作業コピーロックは、複数の svn プロセスが同時に同じ作業コピーのメタデータを変更して、不整合を起こすことを防ぐための機構です。これはリポジトリ側の排他ロック (svn lock) とは全く異なるもので、あくまでローカルの作業コピー内での並行処理を制御するためのものです。

Subversion 1.6 以前では、各ディレクトリの .svn/lock ファイルが存在することで、そのディレクトリがロックされていることを示していました。

Subversion 1.7 以降 (WC-NG) では、ロック情報は .svn/wc.db データベース内で管理されています。特定の操作が実行されると、wc.db 内のロック関連テーブルに情報が書き込まれ、作業コピーの一部または全体がロック状態であることを示します。

5.3 中断された操作の痕跡

svn update や svn commit などの操作が中断されると、その操作が途中まで書き込んだ情報や、次に何をすべきかを示す「操作ログ」のようなものが .svn ディレクトリ内に残ることがあります。

Subversion 1.6 以前では、これはファイルベースのログファイルとして .svn/tmp/log のような場所に書き込まれていました。svn cleanup はこれらのログファイルを確認し、記述されている手順を完了させるか、または安全に中止する処理を実行していました。

Subversion 1.7 以降 (WC-NG) では、操作ログや保留中の操作に関する情報は wc.db データベース内に記録されます。例えば、特定のファイルに対してリビジョンXへの更新がスケジュールされているがまだ完了していない、といった情報がデータベースのフラグやテーブルエントリとして保持されます。

5.4 `svn cleanup` が行うステップ (WC-NG の場合)

Subversion 1.7 以降の WC-NG 作業コピー形式において、svn cleanup は主に以下のステップを実行します（詳細な内部処理は複雑ですが、概念的には）。

データベース (wc.db) のロック取得: svn cleanup 自身が wc.db データベースへのアクセス権を確保します。
保留中の操作ログの確認と処理: wc.db 内に記録されている、中断された操作に関する情報（保留中の操作ログ）を確認します。これらのログに基づいて、以下のいずれかを試みます。
- 中断された操作を安全に完了させることが可能であれば、それを試みます。
- 完了が困難または不可能な場合は、操作を開始する前の状態に巻き戻す処理（ロールバック）を行います。例えば、中途半端に適用された変更を取り消したりします。
作業コピーのロック解除: wc.db データベース内に残っている、他の Subversion プロセスがかけたロック情報をクリアします。これにより、作業コピー全体または指定されたパス以下のロックが解除されます。
一時ファイルや不要なデータのクリーンアップ: 操作中に生成された一時ファイルや、不整合の原因となりうるキャッシュデータなどを削除します。これらは .svn/tmp ディレクトリなどに存在する可能性があります。
データベースの整合性チェックと修復: wc.db データベース自体の論理的な整合性をチェックし、軽微な破損があれば修復を試みます。
（オプション指定の場合）バージョン管理外アイテムの削除: --remove-unversioned, --remove-ignored, --remove-external-items などのオプションが指定されている場合、wc.db の情報を参照して、削除対象となるファイルやディレクトリを作業コピーから物理的に削除します。
データベースの解放: 処理が完了したら、wc.db データベースのロックを解除し、他の Subversion プロセスがアクセスできるようにします。

このように、Subversion 1.7 以降の svn cleanup は、作業コピーの状態管理の中心である wc.db データベースに対する一連の処理として実行されます。これにより、以前のバージョンよりも効率的かつ確実に作業コピーの状態を健全に戻すことができるようになっています。

ただし、前述の通り、メタデータ（wc.db ファイルそのもの）が物理的に深刻な破損を負っている場合など、svn cleanup では修復しきれない問題も存在します。

第6章：`svn cleanup` の注意点とリスク

svn cleanup は便利なコマンドですが、特に特定のオプションを使用する際には注意が必要です。安全に svn cleanup を使用するためのポイントを解説します。

6.1 必ず作業コピーの状態を確認してから実行する

svn cleanup を実行する前に、現在の作業コピーの状態を svn status コマンドで確認することを強く推奨します。

bash svn status

これにより、どのようなファイルが変更されているか、競合しているか、バージョン管理外であるかなどを把握できます。cleanup はローカルでのファイル内容の変更を消しませんが、状態が不整合になっている中で cleanup を実行すると、予期せぬ結果になる可能性もゼロではありません。特に、誤って削除系オプションを使ってしまうリスクを避けるためにも、現状を把握しておくことは重要です。

6.2 削除系オプション (`--remove-unversioned` など) の危険性

第3章で解説した Subversion 1.9 以降の削除系オプション（--remove-unversioned, --remove-ignored, --remove-external-items, --remove-degenerate）は、非常に強力であると同時に危険なオプションです。

--remove-unversioned のリスク: 最も注意が必要です。ローカルで新規に作成したものの、まだ svn add していないファイル（例: 新しいコードファイル、重要なメモ、設定ファイルなど）が、cleanup を実行したディレクトリ以下に含まれている場合、このオプションによって警告なしに物理的に削除されてしまいます。Subversion はそれがバージョン管理下にないため、その重要性を判断できません。必要なファイルが削除されないよう、このオプションは本当にその効果を理解し、削除対象を確認した上で、細心の注意を払って使用してください。
--remove-ignored のリスク: svn:ignore やグローバル設定で無視されているファイルは、通常はビルド生成物やログなど、削除しても問題ない一時的なファイルであることが多いです。しかし、中には開発環境の設定ファイルや、意図的にバージョン管理から外しているがローカルに保持しておきたいファイルなどが無視対象になっている可能性もあります。念のため、これらのファイルが削除されても問題ないか確認する意識は持つべきです。
--remove-external-items のリスク: svn:externals で管理されているコンテンツは、通常はリポジトリから再度チェックアウトできるものですが、ローカルでカスタマイズを加えている場合など、削除されると困るケースも考えられます。

これらの削除系オプションを使う場合は、事前に svn status --no-ignore を実行して、? や I と表示される項目を全て確認し、削除されても問題ないか慎重に判断してください。

安全策としては、特別な理由がない限り、svn cleanup を実行する際にこれらの削除系オプションを使用しないことです。ほとんどの場合、svn cleanup を引数なしで実行するだけで、ロックの解除や不完全な操作の解消という本来の目的は達成できます。不要ファイルの削除は、svn status で確認しながら手動で行うか、より安全なスクリプトなどを使用することを検討してください。

6.3 `svn cleanup` は万能ではない

繰り返しになりますが、svn cleanup は作業コピーの特定の問題を解決するためのツールであり、万能ではありません。

深刻なメタデータ破損: .svn/wc.db ファイル自体が物理的に破損している、または論理的な不整合が深刻で cleanup の内部修復処理では対応できない場合、svn cleanup は正常に完了しないか、実行しても問題が解決しないことがあります。このような場合は、最終手段として、問題のある作業コピーを削除し、リポジトリから改めて新しい作業コピーをチェックアウトする必要があります。
リポジトリ側の問題: svn cleanup は作業コピーにのみ作用します。リポジトリサーバーが停止している、リポジトリ自体が破損しているといったリポジトリ側の問題は svn cleanup では解決できません。
ローカル変更内容: 編集中のファイル内容や、競合マーカーなどはそのまま残ります。これらを元に戻したい場合は svn revert を使用する必要があります。

6.4 実行中の他のSubversion操作を避ける

svn cleanup を実行している間は、同じ作業コピーに対して他の svn コマンドを実行するべきではありません。cleanup 自身が作業コピーのメタデータを操作しているため、同時に別のコマンドを実行すると、競合したり、さらなる不整合を引き起こしたりする可能性があります。

6.5 実行時間の考慮

非常に大きな作業コピーや、メタデータが複雑に絡み合った状態、あるいはファイルシステムやネットワークの速度によっては、svn cleanup の実行に時間がかかることがあります。特に再帰的に実行する場合や、大量のファイルが存在する作業コピーでは注意が必要です。実行中はプロンプトが帰ってこないため、フリーズしたのではないかと心配になるかもしれませんが、しばらく待ってみてください。verbose オプション (-v) を付けて実行すると、ある程度進捗を確認できる場合があります。

第7章：`svn cleanup` と他の関連コマンド

Subversion のコマンドはそれぞれ異なる役割を持っていますが、svn cleanup は他のコマンドと連携して使用されることが多いです。ここでは、svn cleanup と関連性の高いコマンドについて、その役割と cleanup との違いを説明します。

7.1 `svn status`

役割: 作業コピーの現在の状態を表示します。どのファイルが変更されているか (M), 追加されているか (A), 削除されているか (D), 競合しているか (C), ロックされているか (L), バージョン管理外か (?), 無視されているか (I) などを一覧で確認できます。
cleanup との関係: svn cleanup を実行する前後の状態確認に必須のコマンドです。cleanup を実行することでロック (L) やその他の不整合な状態表示が解消されることを確認します。また、削除系オプションを使う場合は、svn status --no-ignore で削除対象を確認します。
違い: svn status は状態を表示するだけであり、作業コピーの状態を変更することはありません。一方、svn cleanup は作業コピーの状態を修復します。

7.2 `svn revert`

役割: 作業コピー内でのローカル変更（ファイルの編集、追加、削除、プロパティ変更など）を取り消し、そのファイルやディレクトリをリポジトリから取得したベースリビジョンの状態に戻します。競合マーカー (<<<<<<< など) が付いたファイルを、競合発生前の状態に戻す際にも使われます。
cleanup との関係: svn cleanup はローカル変更や競合マーカーを消しません。競合を解消せずにベースリビジョンに戻したい場合や、単にローカルでの編集内容を取り消したい場合は、cleanup ではなく svn revert を使用します。競合によってロックがかかり revert できない場合に、先に cleanup でロックを解除してから revert を実行する、という連携も考えられます。
違い: svn cleanup は作業コピーのメタデータや操作の中断によって生じた不整合を解消するのが主目的です。svn revert はユーザーが行った具体的な変更内容を破棄するのが主目的です。

7.3 `svn update`

役割: リポジトリから最新の変更を作業コピーに取り込み、作業コピーをリポジトリの特定の（通常は最新の）リビジョンに同期させます。他のユーザーのコミット内容を作業コピーに反映させる際に使用します。
cleanup との関係: svn update が途中で中断され、ロックや不完全な状態になった場合に、svn cleanup が必要になります。cleanup で作業コピーの状態を健全に戻してから、改めて svn update を実行することで、更新を正常に完了させることができます。
違い: svn update はリポジトリと作業コピーの同期を行うコマンドです。svn cleanup は作業コピー内部の不整合を解消するコマンドであり、リポジトリとの同期機能はありません。

7.4 `svn commit`

役割: 作業コピーで行った変更（ファイルの追加、削除、編集など）をリポジトリに送信し、新しいリビジョンを作成します。
cleanup との関係: svn commit が途中で中断された場合に、ロックなどが残ることがあります。この際に svn cleanup を実行して状態をリセットし、改めて svn commit を実行することで、コミットを再開またはやり直すことができます。
違い: svn commit はローカル変更をリポジトリに反映するコマンドです。svn cleanup は作業コピー内部の状態を修復するコマンドです。

7.5 `svn resolved`

役割: 競合しているファイルをユーザーが手動で編集して解決した後、そのファイルがもはや競合状態ではないことを Subversion に伝えます。これにより、ファイルステータスが C から M に戻り、コミットできるようになります。
cleanup との関係: 競合が発生している状況で、その後の作業（resolved や commit）を進めるために cleanup でロックなどを解除することがあります。cleanup は競合内容自体は触りませんが、競合ファイルに対する操作を可能にするための下準備として役立つことがあります。
違い: svn resolved はユーザーが競合を解決したことをSubversionに伝えるためのコマンドです。svn cleanup は作業コピー内部の状態を修復するコマンドです。

7.6 `svn lock` / `svn unlock`

役割: これはリポジトリ側のファイルに対する排他ロックを設定/解除するコマンドです。他のユーザーがそのファイルをコミットできないようにするために使用します。
cleanup との関係: svn cleanup が扱う作業コピーのロックとは全く異なる種類のロックです。svn cleanup はリポジトリ側の svn lock によるロックには影響しません。
違い: svn lock / svn unlock はリポジトリ上のファイルに対するロックです。svn cleanup は作業コピー内のメタデータに対するロックを扱います。

第8章：トラブルシューティング例

svn cleanup を実行しても問題が解決しない場合など、より深刻な問題に直面した際のトラブルシューティングのヒントをいくつか紹介します。

8.1 「作業コピーはロックされています」エラーが cleanup しても解消しない場合

svn cleanup を実行しても、「作業コピーはロックされています」というエラーが繰り返し表示される、または cleanup 自身がエラーで完了しない場合があります。

考えられる原因:
- 複数の Subversion プロセスが同時に実行されている: バックグラウンドで別の svn コマンドが動いているか、他のユーザー（同じコンピューターを使っている場合）が同じ作業コピーにアクセスしている可能性があります。
- Cleanup 自身が中断された、またはエラーになっている: 以前の cleanup コマンドが正常に完了せず、それ自体が不完全な状態を残している可能性があります。
- 深刻なメタデータ破損: .svn/wc.db ファイルが深刻に破損している、あるいはファイルシステムレベルの問題が発生している可能性があります。
- 権限の問題: .svn ディレクトリやその中のファイルに対する読み書き権限がない可能性があります。
対処法:
1. 他の Subversion プロセスを終了する: 他に実行中の svn コマンドがないか確認し、あれば終了させます。GUIツール（TortoiseSVNなど）を使用している場合は、それらも終了してみてください。
2. コンピューターを再起動する: システム再起動は、OS レベルのファイルロックやプロセスが解放される可能性があるため、試す価値があります。
3. もう一度 svn cleanup を実行する: 一度目の cleanup が不完全だった場合、もう一度実行することで状態が改善する可能性があります。
4. .svn ディレクトリの権限を確認する: 作業コピーのディレクトリや .svn ディレクトリ、特に Subversion 1.7 以降の場合は .svn/wc.db ファイルに対して、現在のユーザーが適切な読み書き権限を持っているか確認してください。
5. 作業コピーを再チェックアウトする (最終手段): 上記の方法で解決しない場合、メタデータの破損が深刻である可能性が高いです。問題のある作業コピー全体を削除し、リポジトリから新しい作業コピーを再度チェックアウト（またはエクスポート）するのが最も確実な解決策です。この際、ローカルでの未コミットの変更がある場合は、事前にどこかにバックアップしておいてください。

8.2 `svn cleanup` 自身がエラーで完了しない場合

svn cleanup を実行すると、エラーメッセージが表示されて処理が中断されることがあります。

考えられる原因:
- メタデータの破損: cleanup コマンド自身が .svn ディレクトリや wc.db ファイルを読み書きする際に、破損箇所に遭遇している可能性があります。
- ファイルシステムの障害: 作業コピーが存在するファイルシステムに物理的な問題が発生している可能性があります。
- 権限の問題: cleanup がアクセスしようとしているファイルやディレクトリに対して、ユーザーが適切な権限を持っていない可能性があります。
- Subversion のバグ: まれに、使用している Subversion クライアントのバージョンに既知のバグが存在する可能性も否定できません。
対処法:
1. エラーメッセージをよく読む: 表示されたエラーメッセージに、問題の原因や関連ファイルに関する具体的な情報が含まれていることがあります。
2. ファイルシステムのチェック: 作業コピーが存在するドライブ/パーティションに対して、ファイルシステムのエラーチェックを実行してみてください。
3. 権限の確認: .svn ディレクトリや関連ファイルに対する権限を確認・修正してください。
4. Subversion クライアントのアップデート: 使用している Subversion クライアントのバージョンが古い場合は、最新版にアップデートすることで問題が解決する可能性があります。
5. 作業コピーを再チェックアウトする: 他の方法で解決できない場合、メタデータ破損が深刻である可能性が高いため、作業コピーを削除して再チェックアウトすることを検討してください。

8.3 cleanup 後も `svn status` が異常な場合

svn cleanup を実行し、特にエラーも表示されなかったにもかかわらず、svn status の出力がいまだに異常な状態（例: 消えないロック表示、不可解なステータス、一部のファイルが表示されないなど）である場合があります。

考えられる原因:
- Metadata の軽微な不整合が残っている: cleanup ですべての不整合が完全に解消されなかった。
- 深刻な Metadata 破損: cleanup の修復能力を超える破損が発生している。
- ローカルでのファイル操作: cleanup 実行後に、Subversion を介さずにファイルシステム上でファイルやディレクトリを直接操作（移動、コピー、削除など）した。
- Subversion クライアントのキャッシュ問題: ごくまれに、クライアント側の内部キャッシュが古い情報を保持している。
対処法:
1. もう一度 svn cleanup を実行する: 一度で不十分だった場合、再度実行すると効果があることがあります。
2. 作業コピーのルートで実行したか確認する: 特定のサブディレクトリではなく、作業コピー全体の不整合が疑われる場合は、必ず作業コピーのルートディレクトリで svn cleanup を実行してください。
3. svn status に --no-ignore を付けてみる: もし I ステータスが異常に表示される場合、無視設定の問題かもしれません。
4. 作業コピーを再チェックアウトする: 解決しない場合、メタデータ破損の可能性が高いと判断し、作業コピーを再作成するのが最も確実です。

8.4 非常に時間がかかる場合の対処法

svn cleanup を実行したが、プロンプトが帰ってこず、非常に時間がかかっているように見える場合があります。

考えられる原因:
- 非常に大きな作業コピー: 管理しているファイル数が多い場合、メタデータの処理に時間がかかります。
- 深刻な不整合: 大量のロックや複雑な操作ログが残っており、それらを処理するのに時間がかかっています。
- ファイルシステムの速度: ストレージのアクセス速度が遅い場合、メタデータへのアクセスに時間がかかります。
- ネットワークの問題: 外部定義などが含まれる場合、ネットワークアクセスが遅いと時間がかかることがあります。
対処法:
1. しばらく待ってみる: 特に問題が深刻な場合や作業コピーが大きい場合は、完了までに数分、場合によっては数十分かかることもあります。焦らずしばらく待ってみてください。
2. verbose オプション (-v) を付けて実行する: 何も出力されない場合でも、-v オプションを付けることで、現在どのディレクトリを処理しているかなどの進捗状況が表示される場合があります。
3. Subversion のプロセスを確認する: タスクマネージャー（Windows）や ps aux | grep svn（Linux/macOS）などで、svn プロセスがCPUを使用しているか、ディスクアクセスが続いているかなどを確認し、実際に動作しているかを判断します。完全にフリーズしている場合はプロセスを終了するしかないかもしれません。
4. ファイルシステムの速度を確認する: ディスクアクセスがボトルネックになっている可能性があれば、ファイルシステムの健康状態や速度を確認します。
5. 問題の範囲を絞って実行する: 作業コピー全体ではなく、特定のディレクトリに対して svn cleanup /path/to/directory を実行し、問題の範囲を絞り込むことができるか試みます。
6. 作業コピーの再チェックアウト: どうしても完了しない場合や、毎回長時間かかる場合は、作業コピーの状態が慢性的に不整合を起こしている可能性があり、新しい作業コピーを作成する方が早い場合があります。

これらのトラブルシューティングのヒントは、問題解決の一般的なアプローチを示すものです。実際の状況に合わせて、適切な手順を試してください。

第9章：まとめ

svn cleanup コマンドは、Subversion を日常的に使用する上で避けて通れない、作業コピーの健全性を維持するための重要なツールです。その主な役割は、操作の中断によって発生したロックや不完全な状態を解消し、作業コピーを次の操作に進めることができるクリーンな状態に戻すことにあります。

この記事で解説した svn cleanup のポイントをまとめます。

svn cleanup は、Subversion 作業コピーの内部的な不整合やロックを解消するためのコマンドです。
最も一般的な用途は、「作業コピーはロックされています」というエラーの解消です。
中断されたアップデート、コミット、スイッチなどの操作を完了させるか巻き戻すことで、作業コピーの状態を健全に戻します。
通常は、引数なしで作業コピーのルートディレクトリで実行することで、作業コピー全体を再帰的にクリーンアップするのが効果的です。
Subversion 1.7 以降では、.svn/wc.db データベースに対して処理が行われます。
Subversion 1.9 以降で追加された --remove-unversioned などの削除系オプションは強力ですが、意図せず重要なファイルを削除してしまうリスクがあるため、使用には細心の注意が必要です。特別な理由がなければ使わないことを推奨します。
svn cleanup は、ローカルでのファイル内容の変更や競合マーカーを削除することはありません。これらを元に戻すには svn revert を使用します。
深刻なメタデータ破損やリポジトリ側の問題は svn cleanup では解決できません。
svn cleanup を実行する前後には、必ず svn status で作業コピーの状態を確認しましょう。
cleanup がうまくいかない場合は、他の Subversion プロセスを終了したり、コンピューターを再起動したり、最終手段として作業コピーを再チェックアウトしたりすることを検討します。

svn cleanup は、Subversion のバージョン管理を円滑に進める上で、いわば作業の「お掃除役」として不可欠な存在です。このコマンドの役割と正しい使い方、そして注意点を理解しておくことで、Subversion 利用時に発生する多くの問題を自身で解決できるようになり、より快適にバージョン管理を行うことができるでしょう。

もし Subversion の作業中に「何かおかしいな」「コマンドが通らない」と感じたら、まずは落ち着いて svn status で状態を確認し、その上で svn cleanup を試してみてください。多くの場合は、それだけで問題が解決し、作業を再開できるはずです。

この記事が、あなたの Subversion 作業効率の向上と、問題発生時の迅速な解決に役立つことを願っています。

付録：Subversion クライアントのバージョン確認

使用している Subversion クライアントのバージョンによって、.svn ディレクトリの構造や cleanup で利用可能なオプションが異なります。特に削除系オプションは Subversion 1.9 以降でなければ利用できません。

使用している Subversion クライアントのバージョンは、以下のコマンドで確認できます。

bash svn --version

出力例：
“`
svn, version 1.14.1 (r1886195)
compiled Dec 11 2023, 12:37:08 on x86_64-apple-darwin22.6.0

Copyright (C) 2020 Apache Software Foundation.
This is licensed under the Apache License, Version 2.0. See http://www.apache.org/licenses/LICENSE-2.0 for more information.
“`

version 1.14.1 のように表示されます。1.7 以上であれば WC-NG 形式の作業コピーを使用しており、1.9 以上であれば削除系オプションが利用可能です。

以上で、「svn cleanupとは？使い方と役割を徹底解説」の詳細な記事となります。約5000語の要件を満たすように、各項目を詳細に記述しました。