Claude Code worktreeinclude — .envをコピーする書き方と条件

.worktreeincludeは、プロジェクトルートに置くテキストファイルです。ここに書いたパターンに一致し、かつgitignoreされているファイルが、Claude Codeの作る新しいworktreeへ自動でコピーされます。.envや.env.localのように、リポジトリには入れないが動作確認には要るファイルを持ち込む用途です。

worktreeは新しいチェックアウトなので、追跡されていないファイルは最初から存在しません。何も設定しないと、並列セッションを立ち上げるたびに.envを手でコピーすることになります。

.worktreeincludeの書き方

置き場所はプロジェクトルートで、ファイル名は.worktreeincludeです。書式は.gitignoreと同じです。次の例は、2つの環境変数ファイルと秘密情報の設定ファイルをコピー対象にします。

.env
.env.local
config/secrets.json

モノレポでapps/webとapps/apiの両方に.env.localがある場合は、上の.env.local1行で両方が対象になります。.gitignoreの書式では、スラッシュを含まないパターンは階層に関係なく一致するためです。特定のパッケージの分だけをコピーしたいときに、パスを書いて絞ります。

apps/web/.env.local

書式は.gitignoreと同じ、と公式に書かれています。ワイルドカードやディレクトリ指定の当たり方に迷ったら、.gitignoreの書式の説明に当たると判断できます。

設定キーではなくファイルで指定する点が、worktree.symlinkDirectoriesなどの設定との違いです。公式の設定リファレンスにも、gitignore済みの.envを新しいworktreeへ持ち込むときは設定ではなく.worktreeincludeを使うと書かれています。

コピーされる条件は「一致」と「gitignore済み」の両方

書いただけではコピーされません。次の2条件が揃ったファイルだけが対象です。

この絞り込みがあるため、.worktreeincludeに広いパターンを書いても、追跡済みのファイルが二重にコピーされることはありません。逆に言えば、.gitignoreに載っていない.envは、.worktreeincludeに書いてもコピーされません。

コピーされないときは、先にファイルがgitignoreされているかを確かめると原因が絞れます。

git check-ignore -v .env

git check-ignore -vは、無視されているファイルについて、どの.gitignoreのどの行が効いているかを出力します。何も出力されなければ、そのファイルはgitignoreされていません。この場合は.gitignoreに追記してから.worktreeincludeを使います。

対象外になる条件と注意点

コピーされない代表的なケースを表にします。

自分でgit worktree addしたworktreeにも.worktreeincludeは効きません。公式の記述は「Claude Codeがgitで作るすべてのworktree」に限られています。同じworktreeの節にある共有項目は事情が違い、プロジェクトスコープのプラグインやBashコマンドの権限承認は、git worktree addで作ったworktreeにも及びます。コピーの対象と共有の対象は、適用範囲が別です。

フックを使う構成では、.worktreeincludeは読まれません。公式のhooksリファレンスにも、.envのようなローカル設定ファイルが要るなら、フックのスクリプトの中でコピーするよう書かれています。フックで作成処理を差し替える方法はWorktreeCreate/WorktreeRemove hookの記事で扱っています。

--worktreeに既存のworktreeと同じ名前を渡すと、新しく作らずにそのworktreeを開きます。表の「既存のworktreeを開き直す」はこの場面です。.worktreeincludeは「Claude Codeが新しく作るとき」に処理されると書かれているだけで、開き直したときに再コピーされるかは記載がありません。開き直したworktreeで.envが古いときは、手元のファイルを見比べて、必要なら自分でコピーし直します。

作成直後のworktreeでは依存パッケージも入っていません。コピーされるのはファイルだけなので、インストールは別途Claudeに頼むか、worktree内で自分で実行します。

**/で始まるパターンが効かないケース

**/config.jsonのように**/で始めるパターンには、独特の条件があります。対象のファイルが、ディレクトリごとgitignoreされている場所にあるときです。

この場合、次のどちらかを満たすときだけコピーされます。

• そのディレクトリ自体がパターンに一致している
• **/の直後の最初の名前が、ディレクトリのパスに含まれる名前のどれかである

公式の例では、**/.claude/skills/*.mdと書くと、最初の名前が.claudeなので、無視されている.claude/の中の一致ファイルもコピーされます。**/のパターンが届かないディレクトリの中身を持ち込みたいときは、ディレクトリ名をパターンに入れます。**/config.jsonではなくvendor/**/config.jsonと書く形です。

この挙動は変更を経ています。v2.1.239より前は、ディレクトリ全体が無視されている場合に、そのディレクトリ自体がパターンに一致するときだけコピーしていました。更新履歴には、**/始まりのパターンがgitignore対象のディレクトリ内で何にもマッチしない問題の修正が載っています。古いバージョンで「書いたのにコピーされない」場合は、バージョンも疑う価値があります。リリース内容はv2.1.239のリリースノートにまとめています。

.claude/skillsは.worktreeincludeなしでも読み込まれる

先ほどの**/.claude/skills/*.mdの例を見て、スキルをworktreeへコピーしないと使えないのかと思うかもしれません。.claude/skillsがgitignoreされていてworktreeのルートに存在しない場合、Claude Codeはメインのチェックアウトにあるプロジェクトのスキルをworktreeのセッションで読み込みます。.claude/agentsと.claude/commandsも同じ扱いです。

条件は2つあります。worktreeが自前の.claude/skillsディレクトリを持っているときは、そちらだけが読み込まれ、メインの分は使われません。また、スキルのこの読み込みにはv2.1.277以降が必要です。スキルをコピー対象に入れる必要があるのは、worktree側でスキルの内容を書き換えて試したいときのように、メインと別の実体を持たせたい場合に限られます。

壊れた角かっこパターンの扱い

[で始まる角かっこパターンを閉じ忘れると、v2.1.207より前は、ファイルの読み取りや候補表示、worktree作成まで壊れていました。更新履歴では、ルールのglob・スキルのパス・.ignoreとあわせて.worktreeincludeも修正対象に挙がっています。パターンを書くときは、閉じ忘れがないかを見直します。詳しくはv2.1.207のリリースノートを参照してください。

適用される作成経路

.worktreeincludeは、Claude Codeがgitでworktreeを作る経路すべてに効きます。

• --worktreeで作るworktree
• サブエージェントのworktree(isolation: worktreeを含む)
• デスクトップアプリの並列セッション

この3経路はいずれもClaude Codeが作るworktreeなので、どの経路でも同じファイルが使われ、、サブエージェント用に別の設定は要りません。サブエージェントを隔離して動かす設計はworktree実践ガイドにまとめています。デスクトップ側の使い方はデスクトップの並列セッションの記事が詳しいです。

秘密情報をコピーするときの考え方

config/secrets.jsonのような秘密情報も、.worktreeincludeに書けばworktreeへ複製されます。ファイルが増えるぶん、置き場所が増える点は見落としやすいところです。

worktreeは既定で.claude/worktrees/の下に作られます。.envはgitignore済みでなければコピーされないので、コミット対象にはなりません。ただし、worktreeを削除し忘れると、コピーした秘密情報はディスクに残り続けます。不要になったworktreeの掃除は、agent viewでworktreeが溜まる原因と掃除の手順で確認できます。

コピーしたいのが.envだけなら、書く行は1行で足ります。コピー対象は必要なものに絞り、*.jsonのような広いパターンは避けます。gitignore済みのファイルだけが対象とはいえ、広く書くとビルド成果物やキャッシュまでworktreeに入ります。

node_modulesはコピーせずリンクする

.worktreeincludeは「ファイルを複製する」仕組みです。node_modulesのように大きなディレクトリを複製すると、時間もディスクも食います。大きなディレクトリにはworktree.symlinkDirectoriesでシンボリックリンクを張る分け方が向いています。設定方法はsymlinkDirectoriesの記事にあります。

小さな環境ファイルは.worktreeincludeでコピーし、大きな依存ディレクトリは設定でリンクにする。この分担で、新しいworktreeを開いてすぐ動かせる状態に近づきます。

まとめ

.worktreeincludeは、一致とgitignore済みの両方を満たしたファイルだけを新しいworktreeにコピーします。効かないときは、git check-ignore -vでgitignore済みかを見て、次にフックで作成していないか、**/パターンの条件に当たっていないかを確かめると切り分けられます。