Git
PR

git worktreeの使い方:複数のブランチを同時に開く方法を実行結果つきで解説

git worktreeの使い方:複数のブランチを同時に開く方法を実行結果つきで解説
hr
記事内に商品プロモーションを含む場合があります

新しい機能を作っている途中で「本番で表示がおかしいので、すぐ直して」と頼まれた。作りかけの変更はまだコミットしたくないし、stash でしまうと元の状態に戻すのも少し面倒――そんなときに便利なのが git worktree(ギット ワークツリー)です。1 つのリポジトリから作業フォルダーをもう 1 つ作り、別のブランチを同時に開いておけるようになります。

この記事では、作業フォルダーの追加(新しいブランチ・既存のブランチ)、一覧、削除、手で消してしまったときの後片付け(prune)を、実際の実行結果つきで説明します。あわせて「同じブランチは 2 か所で開けない」「ブランチが消せない」など、つまずきやすいエラーの文言と直し方も紹介します。

コマンドと実行結果は、Windows 11 の Git Bash(git --version の結果は git version 2.49.0.windows.1)で実際に実行して確かめたものです。結果に出てくるフォルダーの場所は、前半を C:/work に置き換えて短くしています。コミット ID(8184dbc のような英数字)は、実行するたびに違う値になります。

この記事で使うコマンド

やりたいことコマンド
新しいブランチを作って、別のフォルダーで開くgit worktree add -b ブランチ名 フォルダー 元にするもの
今あるブランチを、別のフォルダーで開くgit worktree add フォルダー ブランチ名
作業フォルダーの一覧を見るgit worktree list
作業フォルダーを削除するgit worktree remove フォルダー
手で消したフォルダーの記録を片付けるgit worktree prune

git worktree とは?

ふつう、1 つのリポジトリには作業フォルダー(ファイルを編集する場所)が 1 つだけあり、同時に開けるブランチも 1 つです。別のブランチで作業したいときは git switch で切り替えますが、そのたびにフォルダーの中身が入れ替わります。

Git の公式ドキュメントでは、git worktree は「同じリポジトリに結びついた複数の作業フォルダーを管理する」コマンドで、「一度に 2 つ以上のブランチをチェックアウトできる」と説明されています。最初からある作業フォルダーをメインの worktree、git worktree add で足したものをリンクされた worktree(linked worktree)と呼びます。

ポイントは、リポジトリの本体(.git)は 1 つのままで、作業フォルダーだけが増えることです。コミットやブランチはすべてのフォルダーで共有され、フォルダーごとに別なのは「今どのブランチを開いているか(HEAD)」と「ステージした内容(index)」などです。

上にリポジトリ本体の my-app/.git が 1 つあり、その中にコミット・ブランチ・設定など共有するものと、worktrees/my-app-hotfix という hotfix 側の HEAD と index を置く場所がある。下に作業フォルダーが 2 つ並ぶ。左のメインの my-app は feature/login ブランチで作りかけの変更があり、中にある .git フォルダーを使う。右の追加した my-app-hotfix は hotfix ブランチで、.git ファイルに worktrees/my-app-hotfix の場所が書いてある。node_modules や .venv など Git が管理しないファイルはフォルダーごとに別。
図 1:1 つの .git を 2 つの作業フォルダーで使う

stash・clone との違い

「作業中の変更を残したまま、別のブランチで急ぎの修正をする」方法は、ほかにもあります。それぞれの違いは次のとおりです。

git stashgit clone でもう 1 つgit worktree
作りかけの変更いったんしまう(あとで戻す)元のフォルダーにそのまま残る元のフォルダーにそのまま残る
同時に開けるブランチ1 つ2 つ以上2 つ以上
リポジトリ本体(.git)1 つフォルダーごとにまるごとコピー1 つを共有
片方で作ったコミット―push や fetch をしないと、もう片方には見えないすぐにどちらからも見える
向いている場面数分で終わる切り替え完全に別の環境で試したいとき作業を止めずに、別のブランチも並行して触りたいとき

clone の行は、練習用リポジトリを手元でもう 1 つ clone してコミットし、元のリポジトリの git log --all にそのコミットが出てこないことで確かめました。stash の使い方は「git stashの使い方」で詳しく説明しています。

準備:練習用のリポジトリ

練習用のリポジトリ「my-app」を使います。hello.py に print("Hello") と print("Git") の 2 行があり、main ブランチにコミットが 2 つあります。

8184dbc Gitと表示する処理を追加
6d8dfa0 最初のコミット

ここから git switch -c feature/login でブランチ feature/login を作り、ログイン機能を作り始めたとします。hello.py の最後に print("Login") を足しましたが、まだコミットしていません。git status --short の結果は次のとおりです。

 M hello.py

「M」は変更あり(Modified)の印です。また、.gitignore で無視している .venv と node_modules のフォルダーもあります(Python や Node.js の開発でよく作られるフォルダーです)。この状態で「main の表示を急いで直して」と頼まれた、という場面で進めます。

新しいブランチで作業フォルダーを追加する(git worktree add -b)

my-app フォルダーの中で、次のコマンドを実行します。main を元に新しいブランチ hotfix を作り、my-app の隣に my-app-hotfix というフォルダーを作ってそこで開く、という意味です。

git worktree add -b hotfix ../my-app-hotfix main
Preparing worktree (new branch 'hotfix')
HEAD is now at 8184dbc Gitと表示する処理を追加

「新しいブランチ hotfix で worktree を準備した」「HEAD(今開いているコミット)は 8184dbc になった」という意味です。書き方の順番は次のとおりです。

  • -b hotfix:新しく作るブランチの名前
  • ../my-app-hotfix:作る作業フォルダーの場所(.. は 1 つ上のフォルダー。つまり my-app の隣)
  • main:どこから枝分かれするか。省略すると、今開いているコミット(HEAD)から作られる

my-app 側では何も変わっていません。git status --short はさっきと同じ M hello.py のままで、作りかけの print("Login") も残っています。

追加したフォルダーの中身:.git はファイル

my-app-hotfix の中を ls -A(隠しファイルも表示)で見ると、次のようになっていました。

.git
.gitignore
hello.py

hello.py は main の中身(print("Hello") と print("Git") の 2 行)です。.gitignore で無視している .venv と node_modules はありません。worktree で作られるのは Git が管理しているファイルだけです。

注目したいのは .git です。メインの my-app ではフォルダーですが、追加した側では中身が 1 行だけのファイルになっています。

cat ../my-app-hotfix/.git
gitdir: C:/work/my-app/.git/worktrees/my-app-hotfix

「この作業フォルダーの Git の情報は my-app/.git/worktrees/my-app-hotfix にある」というメモです。その場所には HEAD・index など、このフォルダー専用のファイルが置かれ、コミットやブランチは my-app/.git のものを共有します(公式ドキュメントの「DETAILS」の説明と同じ動きです)。このため、my-app フォルダーを消すと、my-app-hotfix も Git として使えなくなります。

修正してコミットする

my-app-hotfix に移動して git status を実行すると、ブランチ hotfix が開いていて、変更は何もありません。

cd ../my-app-hotfix
On branch hotfix
nothing to commit, working tree clean

hello.py の 1 行目を print("Hello!") に直してコミットします。

git commit -am "あいさつの表示を修正"
[hotfix 612aeb4] あいさつの表示を修正
 1 file changed, 1 insertion(+), 1 deletion(-)

このコミットは、my-app に戻って git log --oneline hotfix を実行してもすぐに見えます。リポジトリの本体が同じなので、push や fetch は要りません。

612aeb4 あいさつの表示を修正
8184dbc Gitと表示する処理を追加
6d8dfa0 最初のコミット

今あるブランチを開く(git worktree add フォルダー ブランチ名)

ブランチがすでにあるときは -b を付けず、フォルダーのあとにブランチ名を書きます。hotfix を main に取り込むために、main を my-app-main というフォルダーで開きます。

git worktree add ../my-app-main main
Preparing worktree (checking out 'main')
HEAD is now at 8184dbc Gitと表示する処理を追加

my-app-main に移動して git merge hotfix を実行すると、main に修正が入ります。

Updating 8184dbc..612aeb4
Fast-forward
 hello.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

このあいだも、my-app のログイン機能の作りかけは一度も触っていません。マージの基本は「Gitのブランチの使い方」で説明しています。

フォルダーだけ指定したとき・-d を付けたとき

ブランチを書かずに git worktree add ../review とすると、フォルダー名と同じ名前のブランチ review が新しく作られました(公式ドキュメントにも「パスの最後の部分の名前でブランチが作られる」とあります)。

Preparing worktree (new branch 'review')
HEAD is now at 8184dbc Gitと表示する処理を追加

ブランチを作らずに、ちょっと動かして確かめたいだけなら -d(--detach)を付けます。どのブランチにも属さない「detached HEAD」の状態で開くので、不要なブランチが増えません。

git worktree add -d ../my-app-test
Preparing worktree (detached HEAD 8184dbc)
HEAD is now at 8184dbc Gitと表示する処理を追加

作業フォルダーの一覧を見る(git worktree list)

git worktree list

上の 4 つのフォルダーがある状態では、次のように表示されました。

C:/work/my-app         8184dbc [feature/login]
C:/work/my-app-hotfix  612aeb4 [hotfix]
C:/work/my-app-main    612aeb4 [main]
C:/work/my-app-test    8184dbc (detached HEAD)
C:/work/review         8184dbc [review]

左から「フォルダーの場所」「開いているコミット」「開いているブランチ」です。最初の行がメインの worktree です。どのフォルダーの中で実行しても同じ一覧が出ます。

また、メインの my-app で git branch を実行すると、ほかのフォルダーで開いているブランチには「+」が付きます(公式ドキュメントでは「リンクされた worktree でチェックアウトされているブランチは、シアン色で + 付きで表示される」とあります)。

* feature/login
+ hotfix
  main

これは my-app-main を作る前の結果です。「*」は今のフォルダーで開いているブランチ、「+」は別のフォルダーで開いているブランチです。

作業フォルダーを削除する(git worktree remove)

修正が終わったら、作業フォルダーは git worktree remove で削除します。エクスプローラーや rm で消すのではなく、このコマンドを使うのが基本です。ここでは、my-app-hotfix の hello.py にメモの 1 行を書き足して保存したまま、削除してみます。

git worktree remove ../my-app-hotfix
fatal: '../my-app-hotfix' contains modified or untracked files, use --force to delete it

「変更されたファイルか、追跡していないファイルがあるので削除しない。消すなら –force を付けて」という意味です。公式ドキュメントにも「削除できるのは、追跡していないファイルも、追跡中のファイルの変更もない、きれいな worktree だけ」とあります。変更を元に戻して、新しく作ったメモ用のファイル notes.txt だけを残した場合も、同じエラーで止まりました。

残っている変更が不要だと確かめたうえで消すときは、--force を付けます。

git worktree remove --force ../my-app-hotfix

何も表示されずに終わり、my-app-hotfix フォルダーはなくなりました。注意:--force を付けると、まだコミットしていない変更や新しいファイルもフォルダーごと消え、元に戻せません。必要な変更は、先にコミットするか別の場所にコピーしてから実行してください。

なお、メインの worktree は削除できません。my-app の中で git worktree remove . を実行すると fatal: '.' is a main working tree と表示されました。

worktree を消してもブランチは残る

remove で消えるのは作業フォルダーだけで、ブランチ hotfix とそのコミットは残ります。いらなくなったブランチは、ふつうのブランチと同じく git branch -d で消します。ここでつまずきやすい点は、次の「よくある間違い・トラブル」で説明します。

フォルダーを手で消してしまったら(git worktree prune)

作業フォルダーを git worktree remove を使わずに消すと、.git/worktrees の中に記録だけが残ります。試しに、git worktree add -b experiment ../my-app-exp で作ったフォルダーを rm で消してから一覧を見ました。

C:/work/my-app       8184dbc [feature/login]
C:/work/my-app-exp   8184dbc [experiment] prunable
C:/work/my-app-main  612aeb4 [main]

「prunable」は「片付けてよい(フォルダーが見つからない)」という印です。この記録が残っていると、同じ場所に作り直そうとしても次のように止められます。

fatal: '../my-app-exp' is a missing but already registered worktree;
use 'add -f' to override, or 'prune' or 'remove' to clear

まず --dry-run(実際には消さない)と --verbose(何をするか表示)で、何が片付けられるかを確かめます。

git worktree prune --dry-run --verbose
Removing worktrees/my-app-exp: gitdir file points to non-existent location

「my-app-exp の記録が指している場所が存在しない」という意味です。問題なければ、オプションなしで実行します。

git worktree prune

何も表示されませんが、git worktree list から my-app-exp の行が消えました。prune が片付けるのは記録だけで、ブランチ experiment は残っています(git branch で確かめました)。また公式ドキュメントによると、prune しなくても記録はいずれ自動で片付けられます(期限は設定 gc.worktreePruneExpire で決まります)。

よくある間違い・トラブル

同じブランチを 2 か所で開こうとして止められる

1 つのブランチは、1 つの作業フォルダーでしか開けません。my-app で開いている feature/login を、別のフォルダーでも開こうとすると次のエラーになります。

Preparing worktree (checking out 'feature/login')
fatal: 'feature/login' is already used by worktree at 'C:/work/my-app'

同じことは git switch でも起こります。my-app で、my-app-hotfix が開いている hotfix に切り替えようとすると、次のように止められました。

fatal: 'hotfix' is already used by worktree at 'C:/work/my-app-hotfix'

2 か所で同じブランチを書き換えると、片方の変更がもう片方の知らないうちに進んでしまうため、Git が守ってくれています。エラーに出ているフォルダーでそのまま作業するか、そのフォルダーを remove してから開き直しましょう。--force を付けると無理に開けますが、初心者のうちは使わないほうが安全です。

ブランチが消せない(used by worktree / not fully merged)

作業フォルダーで開いたままのブランチは削除できません。my-app-hotfix を remove する前に git branch -d hotfix を実行すると、次のエラーになりました。

error: cannot delete branch 'hotfix' used by worktree at 'C:/work/my-app-hotfix'

先に git worktree remove で作業フォルダーを消してから、ブランチを消します。ただし、my-app(feature/login を開いている)で実行すると、今度は別のエラーが出ました。

error: the branch 'hotfix' is not fully merged
hint: If you are sure you want to delete it, run 'git branch -D hotfix'
hint: Disable this message with "git config set advice.forceDeleteBranch false"

hotfix は main にマージ済みなのに「マージされていない」と言われるのは、git branch -d が「今のフォルダーで開いているブランチ(HEAD)」に取り込まれているかで判断するからです(追跡するリモートのブランチを設定していない場合。公式ドキュメントの -d の説明より)。feature/login には hotfix の修正が入っていないので止められました。main を開いている my-app-main で実行すると、問題なく消えました。

Deleted branch hotfix (was 612aeb4).

ヒントにある git branch -D(大文字)は、マージされていなくても強制的に消すコマンドです。どこにも取り込んでいないコミットは見えなくなるので、本当に不要か確かめてから使ってください。

node_modules や venv がなくて動かない

先ほど見たとおり、追加した作業フォルダーには、Git が管理していないファイル(.gitignore で無視しているもの、まだ add していないもの)は入りません。Node.js の node_modules、Python の仮想環境(.venv など)、ビルドの結果、.env のような設定ファイルは、フォルダーごとに用意し直す必要があります。たとえば Node.js なら新しいフォルダーで npm install、Python なら仮想環境を作り直してライブラリを入れます。その分ディスクも使うので、使い終わったフォルダーは remove しておきましょう。

作業フォルダーをリポジトリの中に作ってしまう

git worktree add -b inner inner-wt のように ../ を付け忘れると、my-app の中に作業フォルダーができます。すると my-app の git status --short に、追跡していないフォルダーとして表示されてしまいました。

 M hello.py
?? inner-wt/

うっかり git add . すると混乱のもとになります。作業フォルダーはリポジトリの外(隣など)に作りましょう。

消したい作業フォルダーの中で remove すると空のフォルダーが残る(Windows)

Windows の Git Bash で、消したい作業フォルダー(ここでは tmpx)の中に cd したまま git worktree remove . を実行すると、次のエラーが出ました。

error: failed to delete 'C:/work/tmpx': Permission denied

このとき、中のファイルと Git の記録は消えましたが、使用中のフォルダーそのものは空のまま残りました。cd .. で外に出てから空のフォルダーを消せば片付きます。最初から、メインの my-app などほかのフォルダーに移動してから remove するのが確実です。

よくある質問

stash と worktree はどう使い分ければいいですか?

数分で終わる切り替えなら stash で十分です。修正に時間がかかりそう、テストを流しながら別の作業もしたい、レビューのために別のブランチを並べて見たい、といったときは worktree が向いています。作りかけの変更に触らないので、戻し忘れや pop でのコンフリクトの心配もありません。

作業フォルダーを消すと、ブランチやコミットも消えますか?

消えません。remove でも prune でも、消えるのは作業フォルダーと記録だけで、ブランチは残ります(この記事の実験で確かめました)。ブランチを消すときは git branch -d を別に実行します。ただし、コミットしていない変更は remove --force でフォルダーと一緒に消えます。

作業フォルダーで push はできますか?

リモートの設定はリポジトリ本体で共有されるので、どのフォルダーからでも、そのフォルダーで開いているブランチを push できます。この記事ではリモートを使った確認はしていません。push と pull の基本は「Gitのリモートの基本」を見てください。

まとめ

  • git worktree add -b 新しいブランチ ../フォルダー main で、作業を止めずに別のブランチを開ける
  • リポジトリ本体は 1 つを共有。コミットはすぐにどのフォルダーからも見える。node_modules や venv は共有されない
  • 同じブランチは 2 か所で開けない。開いたままのブランチは消せない
  • 片付けは git worktree remove。手で消したら git worktree prune。--force は未コミットの変更も消える

worktree 以外のコマンドも、やりたいことから探せる「Gitコマンド検索」で調べられます。

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました