HN 日本語サマリー

← 一覧へ戻る
プログラミング

Git worktreesはコーディングエージェントの隔離境界ではない

Git worktrees are not an isolation boundary for coding agents (fletch.sh)

27 pointsby alchaplinsky21 コメント

要約

この記事は、Gitのworktreeがコーディングエージェントの隔離境界として機能しない理由を解説しています。worktreeは単一の.gitディレクトリに紐づくため、エージェントがフックをインストールしたり、コミットのメールアドレスを変更したり、他のworktreeのstashを操作したりすることが可能です。worktreeは作業ディレクトリ、HEAD、インデックスのみを隔離しますが、それ以外のリポジトリの状態(オブジェクトストア、参照、フック、設定など)は共有されるため、エージェントが意図しない操作を行うリスクがあります。エージェントの実行には、worktreeではなくクローンを使用することが推奨されています。

全文翻訳

Git worktreeはコーディングエージェントの分離境界ではない

すべての投稿

git

AIコーディングエージェントを並列実行するほとんどのツールは、各エージェントにgit worktreeを提供します。worktreeは、参照、設定、スタッシュ、フックを実際のレポジトリと共有します。エージェントがメインリポジトリでコードを実行し、コミットIDを書き換えることができることを示すコピー&ペーストで実行可能な再現リポジトリと、適切に分離されたクローンが同等のコストで済むことを示すベンチマークを示します。

Alex Chaplinsky

2026年7月30日・12分読書

コーディングエージェントに独自のgit worktreeを与えると、ほとんどの並列実行ツールがそうするように、そのエージェントは、次にあなたが実際のレポジトリでコミットする際に実行されるフックをあなたのマシンにインストールできます。それは、あなたのコミットが帰属するメールアドレスを書き換えることができます。それは、別のエージェントのスタッシュを自分のツリーにポップすることができます。

それらのどれもバグやエキゾチックなコマンドを必要としません。worktreeは境界になったことはありません。それは1つの.gitにアタッチされた2番目のワーキングディレクトリであり、興味深いものはすべてその.gitの中にあります。

worktreeがここでデフォルトになったのは、それが明白な答えだったからです。1つのコマンド、履歴の重複なし、約1秒で2番目のチェックアウト。ピッチは「ほぼゼロコストでの分離」であり、その両方が間違っていることが判明しました。分離は「分離されたworktree」というフレーズが示唆するものよりもはるかに薄く、適切に行うコストは同じです。私はこの投稿の以前のバージョンでコストの部分を間違っていましたが、測定するまで気づきませんでした。

リンクされたworktree内では、.gitはディレクトリではありません。それはファイルです:

$ cat ../my-worktree/.gitgitdir: /path/to/repo/.git/worktrees/my-worktree

すべてはそのパスから導かれます。Gitはレポジトリの状態をworktreeごとの状態と共通の状態に分割し、どちらがどちらであるかを教えてくれます:

$ cd ../my-worktree$ git rev-parse --git-dir          # per-worktree/path/to/repo/.git/worktrees/my-worktree$ git rev-parse --git-common-dir   # shared with the parent and every sibling/path/to/repo/.git

worktreeごとの状態は短いリストです:HEAD、インデックス、ORIG_HEAD、およびいくつかのbisectとrebaseファイル。他のすべては--git-common-dirを通じて元のレポジトリに解決されます:

  • オブジェクトストア(.git/objects)、これはポイントであり、共有しても安全です。
  • 参照とブランチ(refs/heads、packed-refs)。すべてのworktreeに1つの名前空間があります。
  • 設定(.git/config)。
  • スタッシュ(refs/stash)。
  • フック(.git/hooks)、共有ディレクトリが任意のコード実行になる場所です。

したがって、分離は現実であり、狭いです:あなたのワーキングディレクトリ、HEAD、およびインデックス。それらは有用です。それらは境界ではありません。境界とは、worktreeに閉じ込められたプロセスがその外の状態に到達できないことを意味しますが、2番目のリストはそれができる方法のカタログです。「分離されたworktree」は、ツール説明やアドバイススレッドで、2つのリストのどちらが意図されているかを決して言わずに、常に使用されています。

エージェントができること

最悪のケースから始めます。各ブロックは独自のレポジトリを作成するため、それらを空のディレクトリに貼り付けて任意の順序で実行できます。以下のすべての出力行は本物であり、git 2.50.1でキャプチャされました。

ホストでコードを実行する

.git/hooksは共通ディレクトリにあります。worktree内からインストールされたフックは、したがって親レポジトリにインストールされ、トリガーコマンドを実行するたびに、親であなたとして実行されます。

git init -q --initial-branch=main hook-democd hook-demogit commit -q --allow-empty -m initgit branch agent-workgit worktree add -q ../hook-agent agent-work# "isolated" worktreeが親の.gitにフックを書き込むcd ../hook-agentcat > "$(git rev-parse --git-common-dir)/hooks/pre-commit" <<'EOF'#!/bin/shecho "*** hook running as $(whoami) in $(pwd) ***"EOFchmod +x "$(git rev-parse --git-common-dir)/hooks/pre-commit"# ここで、あなたは自分のレポジトリで通常のコミットを行うcd ../hook-demogit commit -q --allow-empty -m "an ordinary commit"# -> *** hook running as you in /path/to/hook-demo ***

これも、worktreeがコンテナ化されたエージェントの分離レイヤーになれない理由です。コンテナにリンクされたworktreeを渡すということは、親の実際の.gitをマウントすることを意味します。なぜなら、それがworktree自身の状態が生きている場所だからです。ホスト側のマウントにある書き込み可能な.git/hooksはホストで実行され、コンテナは意味をなさなくなります。

コミットの差出人を書き換える

設定は共有されているため、worktree内のgit configは親の.git/configを書き込みます:

git init -q --initial-branch=main id-democd id-demogit commit -q --allow-empty -m initgit branch agent-workgit worktree add -q ../id-agent agent-workcd ../id-agentgit config user.email "agent@example.com"cd ../id-demogit config user.email# -> agent@example.comgit config --show-origin user.email# -> file:.git/config  agent@example.comgit commit -q --allow-empty -m "a commit you made yourself"git log -1 --format='%an <%ae>'# -> Your Name <agent@example.com>

最後の2行に注目してください。それはエージェントのコミットではありません。それはあなたのレポジトリでのあなたのコミットであり、他の誰かが選んだ作成者行を運んでいます。

他のworktreeのスタッシュを取る

レポジトリごとに1つのrefs/stashがあり、調整されていないライター間で共有される単一のスタックのように動作します:

git init -q --initial-branch=main stash-democd stash-demoecho original > file.txt && git add file.txt && git commit -q -m "add file"git branch branch-agit branch branch-bgit worktree add -q ../stash-a branch-agit worktree add -q ../stash-b branch-bcd ../stash-aecho "AGENT A PRECIOUS WORK" > file.txtgit stash -q                 # Aは作業を保存しますcd ../stash-bgit stash pop                # Bはそれを尋ねることなくポップしますcat file.txt# -> AGENT A PRECIOUS WORKcd ../stash-agit stash list               # -> emptycat file.txt                 # -> original. Aの作業は現在Bのツリーにあります。

1つの詳細は負荷がかかり、この再現リポジトリのいくつかのバージョンが機能しない理由です:file.txtはブランチが作成される前にコミットされているため、両方のworktreeで追跡されます。通常のgit stashは追跡されていないファイルを無視するため、「No local changes to save」と表示され、何もスタッシュせず、popは「No stash entries found」で失敗します。追跡されたファイルを使用するか、git stash -uを使用してください。

兄弟の下の参照を書き換える

すべてのworktreeは1つのrefs/headsと1つのオブジェクトストアに書き込みます。git gcを実行するエージェントは、リポジトリ全体(親を含む)に対して実行します。ブランチを強制的に更新したり、リベースしたり、git reset --hardに手を伸ばしたりするエージェントは、他のworktreeが解決する参照を変更しており、あるエージェントが孤立させたコミットは、別のエージェントの足元で参照されなくなる可能性があります。これらはエキゾチックなコマンドではありません。それらは、何かが混乱して整理しようと決めたときに手を伸ばすものです。

ブランチ名で衝突する

共有参照は、gitが2つのworktreeで同じブランチを拒否することも意味します:

$ git worktree add ../probe mainPreparing worktree (checking out 'main')fatal: 'main' is already used by worktree at '/path/to/repo'

残りのものに比べて無害ですが、人々が最初にぶつかる壁であり、worktreeごとに一時的なブランチを生成してgitを満たすように促すものです。

修正されない修正策

この問題が議論されるたびに、2つの緩和策が出てきます。どちらも効果がありません。

worktreeごとの設定。 extensions.worktreeConfigはデフォルトでオフになっており、それをオンにしても、書き手がgit config --worktreeをオプトインした場合にのみ役立ちます。通常のgit config(注意していないものが実行するものです)は、共有ファイルを書き込み続けます:

git config extensions.worktreeConfig true    # あなたが親でオプトインしますcd ../my-worktreegit config --worktree user.email scoped@example.comgit -C ../repo config user.email    # -> you@example.com, 影響なしgit config user.email leaked@example.comgit -C ../repo config user.email    # -> leaked@example.com

フックを.gitから移動する。これは循環的です。core.hooksPathは設定であり、設定は共有されているため、worktreeはそれを好きな場所にポイントします:

cd repo && git config core.hooksPath ../safe-hooks    # あなたの緩和策cd ../my-worktreemkdir -p evil-hooks && printf '#!/bin/sh
echo pwned
' > evil-hooks/pre-commitchmod +x evil-hooks/pre-commitgit config core.hooksPath "$(pwd)/evil-hooks"         # 設定は共有されていますcd ../repo && git commit --allow-empty -m "an ordinary commit"# -> pwned

--separate-git-dirも同様に失敗します。それは.gitを移動しますが、すべてのworktreeはそれが移動されたものを共有し続けます。

これら3つすべては、行動しようとしている書き手を制約します。どれもworktreeが書き込むことができるものを減らすことはありません。

それならクローンを使おう。コストは同じです。

標準的な反論は、ワーカーごとのクローンは履歴をコピーすることを意味するというものですが、ローカルソースにとっては単にそうではありません。これは私が以前間違っていた部分なので、数値を示します。

git/gitのフルクローンを基準に測定:81,772コミット、4,828ファイル追跡、318MBの.git、58MBのワーキングツリー。各行は、そのローカルソースから新しいチェックアウトを1つ作成します。

方法についての注意、それは答えを変えるので。ディスクはツリー全体に対する累積デルタとして測定されます。duは呼び出しごとに1つのinodeをカウントするため、ハードリンクされたクローンをそれ自体で測定すると、実際に追加したバイト数をクレジットしません。

チェックアウトを1つ作成経過時間追加ディスク.gitの表示サイズコピーされたパックファイル
git clone --no-hardlinks1791 ms373 MB315 MB1
git clone (ローカル)982 ms58.9 MB318 MB1 (ハードリンク)
git clone --shared870 ms58.9 MB660 KB0
git worktree add826 ms58.7 MB4 KB0

下3行を見てください。58.7〜58.9 MB、826〜982 ms。ディスクに関してはそれらは同じ操作であり、その数値はワーキングツリーのチェックアウトであり、ソースの58 MBツリーにほぼ一致します。どちらのメカニズムを選択しても、ファイルの1つのコピーと、それ以外に重要なものは何も支払っていません。

ローカルのgit cloneはオブジェクトをコピーせず、ハードリンクするため、.gitは318 MBと報告されますが、実際には59 MBのディスクが追加されます:

$ stat -f '%i links=%l' reference/.git/objects/pack/*.pack154102172 links=2$ stat -f '%i links=%l' plain-clone/.git/objects/pack/*.pack154102172 links=2     # 同じinode

--no-hardlinksのみがコピーの代金を支払いますが、誰もそれを誤って実行しません。ローカルクローンを履歴の重複を想定して避けていた場合、それらは重複しません。

--sharedはさらに進んで何もコピーしません。それは1つのファイルを書き込みます:

$ cat shared-clone/.git/objects/info/alternates/path/to/reference/.git/objects$ find shared-clone/.git/objects -type f | grep -v /info/ | wc -l0

したがって、プレーンクローンのハードリンクされた318 MBに対して660 KBの.gitとなります。あなたが得る実際のプロパティは、履歴サイズからの独立性です。--sharedは、ソースが持つ履歴の量に対してO(1)であり、チェックアウトするファイルの数に対してO(n)です。チェックアウトが支配的であり、テーブルが示しているのはそれです。

私は以前、この投稿で、これを「キロバイトとミリ秒」と表現しました。それはメタデータについては真実ですが、操作については偽です。それは.gitのキロバイトと1つのワーキングツリーを、1秒未満でコストとしています。

同じ59 MBに対して、あなたはこれを得ます:

$ cd plain-clone   && git config user.zzTest x && git -C ../reference config user.zzTest# -> (not set)$ cd shared-clone  && git config user.zzTest x && git -C ../reference config user.zzTest# -> (not set)$ cd worktree      && git config user.zzTest x && git -C ../reference config user.zzTest# -> set-from-worktree
状態worktree--shared clone
オブジェクトストア共有共有、alternates経由
参照 / ブランチ共有分離
設定共有分離
スタッシュ共有分離
フック共有分離
インデックス分離分離
HEAD分離分離

どちらも、コピーするのが高価で共有しても安全な唯一のものを共有します。クローンはまた、フットガンになる5つのものを分離します。それらが複数ライターになるとすぐに。

オブジェクトを借用するため、ソースオブジェクトストアがその場所にとどまることに依存します。ソースの下にあるものを削除しないでください。クローンがまだ参照しているオブジェクトを刈り取ることができるため、クローンがアクティブな間にソースで積極的なgit gcを実行しないでください。git clone --dissociateは、借用したオブジェクトをコピーし、後で終了したい場合は依存関係を切断します。

プレーンなハードリンククローンは2つのうちでより堅牢であり、その理由は知っておく価値があります。ハードリンクはinodeをそれ自体で生かしておきます。ソースがそのパックファイルを削除または再パックしても、クローンのリンクはデータを開いたままにします。--sharedにはそのような保護はありません。なぜなら、それは参照ではなくパスを保持するからです。あなたが失うのは、O(1)プロパティ、永続的な重複排除、およびファイルシステムを横断する能力であり、ワークスペースが別のボリュームに存在したり、コンテナにバインドマウントされたりするとすぐに重要になります。

どちらも厳密には良くありません。それらは異なる方法で失敗し、どちらも参照、設定、スタッシュ、およびフックを分離します。

worktreeが適切な場合

worktreeは意図的に.gitを共有しており、それらが構築されたジョブにとっては、その共有がすべてです:

  • 1人が2〜3のブランチ間を移動する。あなたはすべてのブランチ、スタッシュ、設定がどこでも表示されることを望みます。
  • インデックスを邪魔せずに別のブランチをすばやくビルドまたはテストする。
  • あなたが唯一のライターであり、実行する前に各コマンドが何をするかを知っているもの。

エージェントであっても、1人または2人のエージェントを、各差分を読んでいる人が監視している場合、worktreeとシェルエイリアスで問題ありません。生き残らないのは、調整されていないライターです。「.gitを共有する」と「要求なしに行動する複数のプロセスを実行する」は直接的な緊張関係にあり、ドライビングプログラムでのどんな注意も共有ディレクトリが許可することを変えません。

したがって:人が運転しているときはworktree、それ以外の場合はクローンを使用します。コストはどちらの場合も同じなので、実際に選択しているのは、混乱したプロセスがどれだけの損害を与えられるかだけです。


開示:私はFletchを構築しています。これはコーディングエージェントを実行するmacOSアプリです。そのため、これらのいずれかを選択する必要がありました。上記の測定結果に基づき、各エージェントにgit clone --sharedを提供しています。そのworktreeモードは開発者フラグの後ろにありますが、コンテナ下では実際の.gitをマウントすることを意味し、最初の再現リポジトリのフックはホストで実行されることになります。