git worktree とは？
stash と switch で行き来する代わりに、ブランチごとに作業フォルダを並べる。仕組み（.git の中身）と注意点を、動く図で整理した勉強の記録。
git worktree は、1 つのリポジトリから作業フォルダをいくつも取り出す機能です。ブランチを切り替える代わりに、ブランチごとにフォルダを並べて、同時に開いておけます。コマンドの使い方より先に「何が起きているのか」を、図で整理しました。
1なぜ調べたか
AI のコーディングエージェントを複数並べて動かす話になると、決まって worktree が出てきます。名前は知っていても、git stash で行き来するのと何が違うのか、フォルダを増やしてディスクは大丈夫なのか、説明できませんでした。
2リポジトリと作業ツリーは別のもの
まず、git には 2 つの層があります。リポジトリ（.git）は、全部のコミットとブランチを持つ「倉庫」。作業ツリーは、そこから 1 本のブランチを取り出してファイルとして並べた「作業台」です。どのブランチを取り出しているかは HEAD が指しています。
- index.ts
- app.ts
- README.md
リポジトリ（.git）は全部のブランチの履歴を持っている。作業フォルダに出ているのは、そのうち HEAD が指す 1 本（main）の中身だけ。
ふつうは倉庫 1 つに作業台 1 つ。だから別のブランチを触るには、作業台の上を片付けて並べ直す（switch）しかありません。worktree は、倉庫はそのままに作業台だけを増やす仕組みです。
3入れ替えるか、増やすか
この違いは、作業の途中に別のブランチを触りたくなったときにはっきり出ます。feature の途中で、急ぎの修正が入った場面です。
- 退避する→
- 切り替える→
- 直す→
- 戻す→
- 復元する
- 5 手
feature で作業中。変更はまだコミットしていない。そこに急ぎの修正依頼が来る。
5同じブランチは 1 か所だけ
worktree には 1 つ制約があります。同じブランチを 2 つのフォルダで同時に開くことはできません。HEAD はフォルダごとにあっても、ブランチ自体は共有なので、 片方で進めるともう片方の作業台が置いていかれるからです。
もし同じ main を 2 つのフォルダで開けたとする（実際には git が止める）。どちらも HEAD は main、ファイルは c3 の状態。
同じ内容を別のフォルダで見たいだけなら、ブランチではなくコミットを直接取り出します（git worktree add --detach ../app-peek main）。
6つまずきやすいところ
7どんなときに使うか
逆に、ブランチを 1 日に 1〜2 回切り替えるくらいなら switch で十分です。「行き来が多い」「止めたくない処理がある」ときに効きます。
8コマンド早見表
git worktree add <path> <branch>既にあるブランチを <path> に取り出すgit worktree add -b <new> <path> <start><start> から新しいブランチを作って取り出すgit worktree add --detach <path> <commit>ブランチなしで取り出す（見るだけのとき）git worktree listフォルダとブランチの一覧git worktree remove <path>フォルダと管理情報を消す。変更があると止まる（--force で強制）git worktree prune手で消したフォルダの管理情報を片付けるgit worktree move <path> <new-path>フォルダを移す（mv だと繋がりが切れる）git worktree lock <path>外付けディスクなど、一時的に見えなくても prune させない- git には、全部を持つリポジトリ（倉庫）と、1 本を取り出した作業ツリー（作業台）がある。
- switch は作業台の中身を入れ替える。worktree は作業台を増やす。
- 増やした作業台ごとに別なのは HEAD・index・ファイルだけ。コミットとブランチは共有。
- だから同じブランチは 1 か所でしか開けない。