> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diversion.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# ワークツリー

> 同じリポジトリを複数のディレクトリで同時に作業する

ワークツリーは、同じコンピューター上の別のディレクトリにある、独自のワークスペースを持つリポジトリの追加のクローンです。ブランチを切り替えずに 2 つのタスクを同時に進めるために使用します。たとえば、メインのクローンで長いビルドを実行している間にバグを修正したり、各 AI エージェントに専用のディレクトリを与えたりできます。

## ダウンロードとディスク容量を節約する

Windows の Dev Drive または Mac 上の追加のワークツリーは、ディスク容量をほとんど追加で使用せず、ダウンロードもほとんど発生しません。クローンにすでにあるファイルは再ダウンロードされず、クローンのファイルとディスク容量を共有します。ファイルが独自のディスク容量を使用するのは、そのファイルを変更した後だけです。新しいコミット、ブランチの切り替え、マージでも、各ファイルはワークツリーごとではなくディスクごとに 1 回だけダウンロードされます。ファイルが共有されるのは、同じリポジトリのクローン間だけです。

> [!NOTE]
>
> **前提条件:** ディスク容量とダウンロードを節約するには、ワークツリーが Windows の Dev Drive または Mac (APFS) のディスク上にあり、クローンと同じディスク上にある必要があります。その他のディスクでもワークツリーは動作しますが、ワークツリーごとにすべてのファイルがダウンロードされます。

### Windows: Dev Drive を使用する

1. [Dev Drive を作成します](https://learn.microsoft.com/windows/dev-drive/)。Dev Drive はこの機能に対応した ReFS ファイルシステムを使用します。
2. リポジトリを Dev Drive にクローンします。
3. そのクローンからワークツリーを作成します。デフォルトではワークツリーはクローンの隣に作成されるため、同じドライブ上に置かれます。

### macOS と Linux

* **macOS**: デフォルトのディスクフォーマットである APFS がこの機能に対応しています。設定は不要です。
* **Linux**: ワークツリーごとにすべてのファイルがダウンロードされます。コピーオンライトへの対応は近日提供予定です。

## ワークツリーはワークスペースである

コンピューター上のすべてのクローンは [ワークスペース](https://docs.diversion.dev/ja/concepts/repo-branch-workspace.md) です。ワークスペースは、コミットされていない変更を置くプライベートな場所で、保存するたびにクラウドに同期されます。ワークツリーは、別のディレクトリにクローンされた、同じリポジトリのもう 1 つのワークスペースです。

* ワークツリーはワークスペースの一覧に表示され、他のクローンと同様に同期されます。
* 各ワークツリーは独自のコミットされていない変更を持ち、通常どおりそこからコミットします。
* デフォルトでは、各ワークツリーに専用のブランチが割り当てられます。`--ref` を使用すると、複数のワークツリーを同じブランチ上に置けます。その場合、1 つのワークツリーからのコミットは他のワークツリーに自動的に反映されます。

## ワークツリーを作成する

クローン内から `dv worktree add` を実行します:

```bash theme={null}
dv worktree add my-task            # on branch my-task; creates it if it does not exist
dv worktree add -b my-task         # on a new branch my-task; fails if the branch exists
dv worktree add --ref fix-login    # on an existing branch, a commit, or a tag
```

* 新しいブランチは、クローンの現在のコミットから作成されます。`-b` と `--ref` を一緒に指定した場合は、代わりに `--ref` のコミットから作成されます。
* `dv worktree add` には、名前、`-b`、`--ref` のいずれかが必要です。どれも指定しない場合は処理を中止し、名前を求めます。

ワークツリーは、クローンの隣の `diversion-worktrees/<repo>/<name>` に作成されます。名前を指定しない場合、ディレクトリ名はブランチ名またはコミットに基づいて付けられます。たとえば、`~/projects/game` から実行した場合:

```
~/projects/
  game/                          your clone
  diversion-worktrees/
    game/
      fix-login/                 dv worktree add --ref fix-login
      my-task/                   dv worktree add my-task
```

* ワークツリーをクローンの内部に置くことはできません。別の場所を使用するには、`../my-task` のようにクローンの外部のパスを指定します。
* ワークツリーはクローンと同じディスク上に置いてください。そうすることで、クローンとファイルの内容を共有できます。[ダウンロードとディスク容量を節約する](#save-downloads-and-disk-space) を参照してください。

AI エージェントに専用のブランチを与えるには `-b` を使用します。これにより、エージェントが既存のブランチを乗っ取ることはありません:

```bash theme={null}
dv worktree add -b agent-1
```

## ワークツリーを一覧表示・削除する

```bash theme={null}
dv worktree list
dv worktree remove <path> [-f]
```

`dv worktree list` は、このコンピューター上にあるこのリポジトリのワークツリーを、パス、ブランチ、ワークスペース ID とともに表示します。

`dv worktree remove` は、ワークツリーのワークスペースを削除し、そのディレクトリの同期を停止してから、ディレクトリを削除します。確認は求めませんが、作業が残っている可能性のあるワークツリーの削除は拒否します:

* コミットされていない変更または競合。最初にワークツリーを再スキャンして同期を待つため、直前に保存したファイルも対象になります。
* 競合バックアップ (アップロードされることはありません)
* ワークツリー内のサブモジュール
* 一時停止中のワークツリー (変更が同期されていない可能性があります)。`dv workspace resume` で再開してください。

その作業をコミットまたはクリアするか、`-f` を追加して作業ごとワークツリーを削除します。ワークスペースの削除に失敗した場合は、コマンドを再度実行します。ディレクトリの削除だけが失敗した場合は、手動で削除します。

`dv worktree remove` はメインのクローンを削除しません。クローンの同期を停止するには [`dv unregister`](https://docs.diversion.dev/ja/cmd-ref/unregister) を使用します。

## コーディングエージェントにワークツリーを作成させる

新しいリポジトリの [`AGENTS.md`](https://docs.diversion.dev/ja/basic/start-using-diversion#agents-md-and-claude-md) には、コーディングエージェントにワークツリーの使い方を伝える内容がすでに含まれています。`AGENTS.md` に "Parallel agents" セクションがない場合は、次のセクションを追加します:

````markdown theme={null}
## Parallel agents

Give each agent that works in parallel its own worktree: a second checkout of
this repository with its own workspace. Agents then cannot see or overwrite
each other's uncommitted changes.

```sh
dv worktree add -b task-name          # Create a worktree on a new branch task-name; it prints the worktree path
dv worktree list                      # List this repository's worktrees
dv worktree remove <path>             # Delete a worktree and its workspace; refuses if it has uncommitted changes
```

- Work only in the worktree path. The shell can return to the original
  directory after each command, so start every command with
  `cd <worktree path> &&`, and use absolute paths for file edits.
- The worktree is outside this directory, so file edits there may need the
  user's approval. In Claude Code, after the first worktree exists, the user
  can run `/add-dir` once on the `diversion-worktrees` directory next to this
  one.
- Commit in the worktree, on its own branch. Merge into the target branch only
  when asked.
- Claude Code's `isolation: worktree` option works only with git or a
  WorktreeCreate hook. Without one, use the commands above.
````

Claude Code が `AGENTS.md` を読むのは、`CLAUDE.md` がそれをインポートしている場合だけです。リポジトリのルートにある `CLAUDE.md` に `@AGENTS.md` という行があることを確認し、ファイルが存在しない場合は作成してください。

## 新しいワークツリーを自動的にセットアップする

新しいワークツリーにはリポジトリのファイルが含まれますが、依存関係やビルドキャッシュなど、ローカルでビルドまたはインストールしたものは含まれません。ワークツリーを準備するには、リポジトリのルートに `.dvworktree.yml` ファイルをコミットします:

```yaml theme={null}
# Dirs to symlink from the clone you run the command in, instead of building them again
link:
  - node_modules
  - .cache/build
# Shell command to run in the new worktree
setup: ./scripts/bootstrap.sh
```

どちらもオプトインです:

* `--link` は、`link:` の下にある各ディレクトリを、コマンドを実行したクローンからシンボリックリンクします。
* `--setup` は、新しいワークツリーで `setup:` のコマンドを実行します。コマンドは、実行元のクローンのパスを環境変数 `DV_WORKTREE_ORIGIN` で受け取ります。

```bash theme={null}
dv worktree add --ref fix-login --link --setup
```

> [!WARNING]
>
> このファイルは、チェックアウトするブランチまたはコミットから取得されます。`--setup` はそのリファレンスにあるコマンドをコンピューター上で実行するため、信頼できるリファレンスでのみ使用してください。

## git worktree との比較

| | `git worktree` | `dv worktree` |
| - | - | - |
| コミットされていない変更 | ディスク上にのみ存在 | 保存するたびにクラウドのワークスペースにバックアップ |
| ブランチ上の新しいコミット | 各ワークツリーでプルまたはマージ | すべてのワークツリーに自動的に反映 |
| 2 つのワークツリーで同じブランチ | `--force` を使用しない限り拒否 | `--ref` で可能。一方のコミットがもう一方に反映 |
| ディスク上のファイル | ワークツリーごとにすべてのファイルを完全コピー | Dev Drive または Mac ではクローンと共有 (変更するまで) |
| 削除 | ディレクトリを削除 | ワークスペースも削除 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.