git worktreeコマンドを使ってみる

はじめに

git worktree を使うと、1つのリポジトリから複数ブランチを同時に別ディレクトリで扱える。
「mainでレビューしながら、別ブランチで実装する」のような作業がかなりやりやすくなる。

また、巷ではAI エージェントにタスクを並列で任せることもあるときには、worktreeをよく使うとのことで、この機会に仕組みとか運用について学んでみることにした。

環境

Ubuntu 24.04.3 LTS (dev container)
git version 2.50.1

git worktreeの仕組み

通常の git checkout, git switch は、1つの作業ディレクトリを1つのブランチに切り替えて使う。
一方 git worktree は、同じリポジトリのオブジェクトを共有しつつ、ブランチごとに作業ディレクトリを追加できる。

つまり、以下のような運用ができる。

master（または main）は元ディレクトリで維持
機能Aは worktrees/feature-a
機能Bは worktrees/feature-b

git clone を複数作るより軽く、ブランチ切り替えの待ち時間やミスも減らせる。

`git worktree`のイメージ

1つのリポジトリオブジェクトを共有したまま、作業ディレクトリとブランチを分離して同時進行できるイメージである。

PR前後の状態遷移

追加した worktree は、マージ後に削除していくと運用がシンプルになる。

git worktreeを使ってみる

現在のworktree一覧を確認

git worktree list

/workspaces/blog-hugo  7ce3c0d [master]

既存ブランチを別ディレクトリに追加

今回は worktree-demo ブランチを、worktrees/worktree-demo に追加する。

mkdir -p worktrees
git worktree add worktrees/worktree-demo worktree-demo
git worktree list

Preparing worktree (checking out 'worktree-demo')
Updating files: 100% (2416/2416), done.
HEAD is now at 7ce3c0d create
/workspaces/blog-hugo                          7ce3c0d [master]
/workspaces/blog-hugo/worktrees/worktree-demo  7ce3c0d [worktree-demo]

追加先ディレクトリに移動して git status を見ると、確かに worktree-demo ブランチで作業できる。

cd worktrees/worktree-demo
git status -sb

## worktree-demo

不要になったworktreeを削除

cd /workspaces/blog-hugo
git worktree remove worktrees/worktree-demo
git worktree list

/workspaces/blog-hugo  7ce3c0d [master]

AIエージェントで並列開発するときに便利な理由

1. 作業コンテキストを物理的に分離できる

タスクごとにディレクトリを分けられるので、エージェントごとに「どのブランチで何を触るか」が明確になる。
checkout の切り替え事故や、別タスクの変更混入を減らせる。

2. レビューと実装を同時進行しやすい

片方の worktree でレビュー・検証しながら、別の worktree で次の実装を進められる。
人間側もエージェント側も待ち時間が減る。

3. 失敗時の切り戻しが簡単

問題が起きた worktree だけ破棄すればよい。
メインの作業ディレクトリを汚さずに試行錯誤できる。

運用時のメモ

1つのブランチは同時に複数 worktree へチェックアウトできない。
使い終わった worktree は git worktree remove でこまめに片付ける。
削除済みディレクトリの管理情報が残った場合は git worktree prune を実行する。

参考

git-worktree Documentation
https://git-scm.com/docs/git-worktree
Pro Git (Git Branching)
https://git-scm.com/book/ja/v2/Git-%E3%83%96%E3%83%A9%E3%83%B3%E3%83%81-Git-%E3%81%AE%E3%83%96%E3%83%A9%E3%83%B3%E3%83%81%E3%83%B3%E3%82%B0

おわりに

git worktree は「複数ブランチを同時に進める」ための実用的な仕組みであった。
特に AI エージェントを使った並列開発では、作業コンテキスト分離の効果が大きい。

今後は、タスク単位で worktree を切って実装・検証・レビューを流す運用を標準にしていきたい。