git worktree は AI コーディングエージェントを並列に走らせる文脈で広く使われています。エージェントごとに別の worktree を割り当てれば、同じリポジトリを共有しながら並列にブランチを進められるためです。
並列開発のために導入したコマンドだったのですが、実際に使い始めると、単発のローカル作業でも「現在の作業ツリーには触れずに別ブランチでだけ何かをしたい」というケースが思った以上に多く、結局は両方の用途で日常的に使うようになりました。本記事では後者の文脈、つまり並列開発以外で worktree が役立った局面を紹介します。
検証環境は git 2.53.0、macOS で確認しました。
worktree の基本
git worktree add <path> <ref> で任意のパスに別チェックアウトを作れます。各 worktree は独立した HEAD と作業ツリーを持ち、.git だけを共有します。
同じブランチを複数 worktree でチェックアウトすることは、通常はできません (デフォルトでは拒否されます)。別ブランチや detached HEAD なら自由に並列展開できます。
使い道 1: 作業中のブランチに触れずに別ブランチで小さな別作業を済ませる
リファクタの途中でファイルが多数 dirty な状態のまま、別件で 1 PR を独立に切り出したくなることがあります。実際に遭遇したのは、進行中の作業がまだコミットできる粒度でないのに、別の小さなタスクだけ先に解決できる状態でした。
最初は git checkout で別ブランチに切り替えてみたのですが、次のように弾かれます。
error: Your local changes to the following files would be overwritten by checkout
git stash も試したのですが、新規追加ファイルと削除ファイルが混じっており、pop 後の整合を毎回確認するのが煩わしくなったので worktree に切り替えました。「別ディレクトリで別ブランチを開く」だけで済むぶん、書き手の頭の中も軽くなります。
git worktree add /tmp/wt-fix origin/main
cd /tmp/wt-fix
git checkout -b fix/typo
# 修正してコミット
git push -u origin fix/typo
メインのチェックアウトは最初から最後まで dirty のまま据え置けます。完了後はこうします。
cd ~/repos/proj
git worktree remove /tmp/wt-fix
公開済みブランチへの修正コミットの追加
PR 作成直後に CI が落ちて、ログを見たら Prettier が改行位置の好み違いで warn を出しているだけ、という状況がありました。直すのは 1 ファイル 2 行だけなのに、メイン作業 (こちらは依然として dirty) を中断するのは大袈裟すぎるというパターンです。
git worktree add /tmp/wt-lint origin/feat/X
cd /tmp/wt-lint
git checkout -b fix/lint
# 修正してコミット
git push origin fix/lint:feat/X
最後の local:remote 形式の refspec が要点です。ローカルでは fix/lint という名前を使いつつ、リモートの feat/X へ直接 push できます。これで PR ブランチへ 1 コミットが追加された状態になります。
pnpm install のようなビルドツールを実行する必要があれば、worktree 内で実行します。node_modules がそのディレクトリに作られるだけで、メインの node_modules は関係がありません。
AI 並列開発の文脈との違い
AI 並列開発で worktree を使う場合は、エージェントごとに別 worktree を渡して長時間並走させる構成が多いです。本記事のケースは反対で、短時間の単発作業を一時 worktree で完結させ、終わったら捨てるという使い方になります。
どちらも .git を共有してチェックアウトを分ける点は同じで、技術的な仕組みは変わりません。違うのは「どれくらい使い倒すか」だけです。
後始末
不要になったら git worktree remove で削除します。中身を残したい場合は手動でコピーしてから削除してください。
git worktree remove /tmp/wt-fix
git worktree remove /tmp/wt-lint --force
--force は worktree 内に未コミット変更が残っている場合の上書き削除用です。git worktree list で残存 worktree を確認できます。
git worktree list
# /Users/me/repos/proj abc123 [main]
メインチェックアウトだけが残っていれば完了です。
まとめ
AI 並列開発の文脈でよく語られる git worktree には、次の使い道もあります。
- dirty な作業ツリーを抱えたまま別ブランチで小作業を済ませる
- 公開済み PR ブランチに修正コミットを 1 つ追加する
といった使い方が日常的に役立ちます。git stash で済む場面もありますが、新規ファイルや削除ファイル、ビルドツールの副作用が混じる場合は worktree のほうが状態を把握しやすくなります。