worktree.baseRefとsparsePathsでworktreeの起点と範囲を決める

2つの設定は「どこから分岐するか」と「何を書き出すか」を決める

worktree.baseRef は、Claude Codeが新しいworktreeをどのrefから分岐させるかを選ぶ設定です。worktree.sparsePaths は、worktreeに実ファイルとして書き出すディレクトリを絞る設定です。どちらも settings.json の worktree オブジェクトに入り、スコープは「Any file」。プロジェクトの .claude/settings.json にもユーザー設定にも書けます。

分岐元の選択と書き出し範囲は独立した設定です。片方だけ書いても動きます。worktree全体の仕組みはClaude Code Worktree実践ガイドにあり、ここでは2つのキーの値と挙動に絞ります。

baseRefはfreshとheadの2択

値は2つだけです。

{
  "worktree": {
    "baseRef": "head"
  }
}

既定が "fresh" なので、何も書かなければ --worktree で作るworktreeはリモートの既定ブランチ(通常は main)から始まります。手元で積んだ作業の上でサブエージェントを動かしたいときは、"head" に切り替えます。サブエージェント用の一時worktreeも、--worktree と同じ分岐元の判断に従います。

サブエージェントを専用のworktreeで動かすには、カスタムサブエージェントのfrontmatterに isolation: worktree を書きます。

---
name: refactorer
description: 大きな変更を隔離して試す
isolation: worktree
---

このサブエージェントは起動のたびに一時worktreeを持ち、変更なしで終わればClaude Codeが自動で削除します。変更が残ったworktreeは、定期的な掃除で失われる作業がないと確認できるまでディスクに残ります。baseRef が "fresh" のままだと、手元の未pushコミットはこの一時worktreeに入りません。進行中の作業をサブエージェントに触らせたいときに "head" が要ります。

headは「いま立っている場所」から分岐する

"head" が指すのは、コマンドを実行した時点の手元のHEADです。worktreeの中でさらにworktreeを作る場合、"head" は元のチェックアウトではなく、いま居るworktreeのHEADに解決されます。メインのチェックアウトに戻って分岐させたい場面で、思わぬコミットを引き継ぐ原因になります。

freshはいつfetchするか

"fresh" のとき、Claude Codeは origin/HEAD を新しく保とうとします。仕様は次のとおりです。

• 直近24時間にfetchしていなければ、既定ブランチだけをfetchする
• fetchの待ち時間は最大5秒。失敗したら手元にキャッシュされたrefを使う
• パスワード・鍵のパスフレーズ・新しいSSHホストの確認が必要なfetchは、入力を待たずに失敗として扱う
• リモートが未設定、または origin/HEAD がキャッシュされておらず取得もできないときは、手元のHEADにフォールバックする

v2.1.208より前は、手元にキャッシュ済みの origin/HEAD をそのまま使っていました。古いバージョンでは、しばらくfetchしていないリポジトリで古いコミットから始まることがあります。

ブランチ名は指定できない

baseRef に書けるのは "fresh" と "head" だけです。release/2026-q4 のような既存ブランチ名は書けません。特定のブランチから始めたいときは、git worktree add ../project-bugfix fix-issue-456 のようにgitで直接worktreeを作り、そこでClaude Codeを起動します。

PR番号やMRのURLからも分岐できる

--worktree には名前のほかに、# を付けたPR番号、GitHubのプルリクエストURL、GitLabのマージリクエストURLを渡せます。Claude Codeは、その変更の先頭コミットを origin から取得し、.claude/worktrees/pr-<番号> にworktreeを作ります。この場合の分岐元はPRの先頭コミットで、baseRef の "fresh" と "head" のどちらとも別の起点です。# はシェルがコメントの開始と解釈するので、引用符で囲みます。

claude --worktree "#1234"

URLから読むのは番号だけで、取得先は常にリポジトリの origin です。ホストごとに取得するrefが変わります。

取得中にパスワードやパスフレーズ、新しいSSHホストの確認が必要になると、入力を待たずに Error creating worktree: Failed to fetch PR/MR #<番号> で終了します。ssh-agent に載せた鍵は使えるので、鍵を載せたうえで、新しいホストは一度手元で git fetch して登録しておきます。v2.1.233より前は、#<番号> とGitHub形式のURLだけが使え、取得先も常に pull/<番号>/head でした。

同じ名前を再利用したときの挙動も変わる

claude --worktree feature-auth を、すでにディレクトリがある名前で再実行すると、既存のworktreeが開きます。ここで baseRef が効きます。

"fresh" のときは、次の3つがすべて成り立つと、開き直したworktreeが既定ブランチへリセットされます。

1. コミットされていない変更も未追跡ファイルもない
2. Claude Codeが作ったブランチにまだ居る
3. 自分のコミットがない、またはプルリクエスト(マージリクエスト)がマージされてリモートブランチが削除済み

マージ済みの検出は、gitの状態だけで行われます。pushしたリモートブランチが消えていて、worktree内の全コミットが既定ブランチに含まれていれば、マージ済みとみなされます。

条件を1つでも外れる場合、"head" の場合、名前がPRやMRの参照の場合は、古い先端のまま開き直します。"head" では毎回古い先端から再開するので、前回の続きとして使う運用に向きます。再利用まわりの不具合はworktreeが再利用されるバグにまとめています。v2.1.208より前は、名前を再利用すると常に古い先端で開いていました。

sparsePathsは巨大リポジトリの作成を速くする

worktree.sparsePaths は、gitのsparse-checkoutを使って、リストしたディレクトリとルート直下のファイルだけをディスクに書き出します。モノレポのように全体が大きいリポジトリで、worktreeの作成が速くなり、使う容量も減ります。

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ]
  }
}

この設定では、Claudeがworktreeを作るとき、.claude/、packages/api/、packages/shared/ だけがチェックアウトされます。パスはリポジトリルートからの相対で、どのサブディレクトリからClaudeを起動しても同じ解釈です。パッケージの根でなくても、任意のディレクトリを指定できます。

型は文字列の配列、既定値は未設定で、未設定なら各worktreeは全体を書き出します。

書くのはディレクトリで、ファイルではない

ここが誤解されやすい点です。

• package.json、tsconfig.base.json、ロックファイルなどルート直下のファイルは、リストに書かなくても常に書き出される
• ルート直下のディレクトリは書き出されない。.claude も同様
• リポジトリルートの .claude/settings.json や .claude/rules/ をworktreeの中で読ませたいなら、.claude を明示的にリストへ入れる

個別のファイルを列挙する使い方は想定されていません。リストに入れなかったディレクトリはworktreeに書き出されないので、そこにあるファイルは作業ディレクトリ上に存在しません。必要になりそうな範囲は、最初から sparsePaths に含めておきます。

全worktreeが同じsparsePathsを共有する

1つのセッション内のworktreeは、すべて同じ sparsePaths を使います。あるサブエージェントが packages/api/ を、別のサブエージェントが packages/web/ を必要とするなら、両方を並べておきます。

チームで共有する分とローカルで足す分

全員が同じパスを必要とするなら、.claude/settings.json に書いてコミットします。自分だけが追加したいパスは .claude/settings.local.json に書きます。配列は各スコープで結合されるため、ローカルファイルは、コミット済みのリストにパスを足せますが、取り除けません。

読み込むタイミングに注意

sparsePaths と symlinkDirectories は、worktreeを作る前に、起動したディレクトリから読まれます。作成後のセッションの作業ディレクトリはworktreeのルートです。そこで読まれるプロジェクト設定は、チェックアウトされたリポジトリルートの .claude/settings.json です。worktreeの中で効かせたい権限ルールやhookは、リポジトリルートの .claude/settings.json に置いておきます。

組み合わせると「速く作って、依存は共有する」になる

sparsePaths は書き出しを絞るだけなので、node_modules のような巨大ディレクトリの複製までは防げません。そこで symlinkDirectories を並べます。

{
  "worktree": {
    "baseRef": "head",
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": ["node_modules"]
  }
}

各worktreeの node_modules/ は、メインリポジトリの実体へのシンボリックリンクになります。書き方と注意点はworktree.symlinkDirectoriesの解説を参照してください。

作成後は、worktreeの中で次のように状態を確かめられます。

git sparse-checkout list
git log --oneline -3

1行目で書き出し対象のパスが、2行目で先頭のコミットが分かります。baseRef を "head" にしたつもりで、直近の自分のコミットが並んでいなければ、設定が読まれていません。

sparse worktreeがgitの設定に残すもの

sparse-checkoutを使うworktreeが存在する間、gitはリポジトリ共有の .git/config で extensions.worktreeConfig を有効にします。Claude Codeは、最後のworktreeを削除するときにこの項目を外します。ただし、Claude Code自身が追加した場合に限ります。利用者が自分で設定した値は消しません。

v2.1.207より前は、最後のworktreeを削除してもこの項目が残りました。tea のようなgo-gitベースのツールがリポジトリを開けなくなることがあり、git config --unset extensions.worktreeConfig で解消していました。

状況別の設定早見表

worktree オブジェクトには bgIsolation もあり、バックグラウンドセッションの編集先を決めます。こちらはworktree.bgIsolationの解説にあります。

よくある質問

作成済みのworktreeにも設定変更は反映されますか

設定は、worktreeを作成するときに読まれます。ドキュメントには、作成済みのworktreeへ遡って適用するという記載がありません。確実にしたいときは、設定を変えてから新しいworktreeを作ります。