git-worktree-runner で worktree 管理が劇的にラクになった話

git worktree、便利だけど運用が面倒だった

git worktree は強力な機能だが、実際の運用ではセットアップの手間がボトルネックになりがちだ。 git-worktree-runner（GTR）を使えば、その面倒を 1 コマンドに集約できる。

git worktree の基本（30秒でおさらい）

git worktree は Git 2.5 で追加された機能で、1 つのリポジトリから複数のブランチを同時にチェックアウトできる。git stash やブランチ切り替えなしに、別ディレクトリで別ブランチの作業が可能になる。

# 素の git worktree コマンド
git worktree add ../my-feature feature-branch
git worktree list
git worktree remove ../my-feature

素のコマンドで困ること

git worktree 自体はシンプルだが、実務で使うと以下の課題にぶつかる。

1. コマンドが長い: パス指定やブランチ名の指定が毎回必要
2. 環境ファイルのコピーが手動: .env や .env.local を新しい worktree にコピーし忘れて動かない
3. 依存パッケージのインストールが手動: npm install や pnpm install を忘れてエラー
4. クリーンアップが面倒: worktree 削除時に Docker コンテナの停止、ブランチ削除、git worktree prune を個別に実行

筆者もこれらの課題に対処するため、Taskfile.yaml（Go 製タスクランナー）で worktree 操作を定義して運用していた。しかし、プロジェクトごとに Taskfile を用意する必要があり、それ自体が負担になっていた。

---

git-worktree-runner（GTR）とは

GTR は CodeRabbit が開発した git worktree の CLI ラッパーだ。 worktree の作成・削除・環境セットアップを 1 コマンドに集約し、AI ツールとの連携もビルトインで提供する。

CodeRabbit が作った worktree CLI ラッパー

• リポジトリ: coderabbitai/git-worktree-runner
• 言語: Bash（3.2+ 対応、macOS / Linux / Git Bash）
• ライセンス: Apache 2.0

CodeRabbit は AI によるプルリクエストレビューサービスで知られる企業だ。GTR は同社が AI 開発ワークフローの一環としてオープンソースで公開したツールになる。

GTR でできること一覧

機能	説明
git gtr new	worktree 作成 + env コピー + 依存インストール + フック実行
git gtr list	worktree 一覧表示
git gtr rm	worktree 削除 + クリーンアップ
git gtr clean	マージ済み worktree の一括削除
git gtr ai	既存 worktree で AI ツールを起動
.gtrconfig	リポジトリ単位の共通設定
フック	postCreate, preRemove, postRemove, postCd
fzf 連携	インタラクティブな worktree 選択（v2.4.0〜）

---

インストールと初期設定

Homebrew でインストール

macOS / Linux（Linuxbrew）の場合、2 コマンドで完了する。

brew tap coderabbitai/tap
brew install git-gtr

スクリプトでインストールする場合:

git clone https://github.com/coderabbitai/git-worktree-runner.git
cd git-worktree-runner && ./install.sh

インストール後、バージョンを確認する。

git gtr --version
# git-gtr version 2.4.0

.gtrconfig を書く

リポジトリルートに .gtrconfig を配置すると、worktree 作成時の自動処理を定義できる。

[copy]
# worktree 作成時に自動コピーするファイル（glob パターン）
include = **/.env.example

[hooks]
# worktree 作成後に自動実行するコマンド
postCreate = pnpm install

[defaults]
# デフォルトのエディタと AI ツール
editor = cursor
ai = claude

この設定ファイルをリポジトリにコミットすれば、チームメンバー全員が同じ worktree 設定を共有できる。

---

基本的な使い方

worktree を作る（git gtr new）

# ブランチ名を指定して worktree 作成
git gtr new my-feature

# ベースブランチを指定
git gtr new my-feature --base develop

# 作成と同時にエディタを開く
git gtr new my-feature --editor

# 作成と同時に AI ツールを起動
git gtr new my-feature --ai

git gtr new を実行すると、以下が自動で行われる:

1. git worktree add でブランチと作業ディレクトリを作成
2. .gtrconfig の [copy] に基づきファイルをコピー
3. [hooks] postCreate を実行（例: pnpm install）
4. --editor 指定時はエディタを起動
5. --ai 指定時は AI ツールを起動

一覧と切り替え（git gtr list / cd）

# worktree 一覧
git gtr list

# fzf でインタラクティブに選択して移動
git gtr cd

worktree を消す（git gtr rm / clean）

# 指定した worktree を削除
git gtr rm my-feature

# マージ済み worktree を一括削除
git gtr clean --merged

git gtr rm は [hooks] preRemove → worktree 削除 → ブランチ削除 → git worktree prune → [hooks] postRemove を一括で処理する。

---

【体験談】Taskfile.yaml から GTR に移行してみた

Before — Taskfile.worktree.yml での運用

以前は Go 製タスクランナーの Task を使い、プロジェクトごとに Taskfile.worktree.yml を書いて worktree を管理していた。

# Taskfile.worktree.yml（実際に使っていた定義）
version: "3"

vars:
  MAIN_DIR: "{{.TASKFILE_DIR}}/.."
  WK_DIR: "{{.MAIN_DIR}}/../wk"
  SHARED_ENV: "{{.MAIN_DIR}}/../.env.shared"

tasks:
  add:
    desc: 新しいworktreeを作成（NAME=auth BASE=develop）
    dir: "{{.MAIN_DIR}}"
    requires:
      vars: [NAME]
    vars:
      BASE: '{{.BASE | default "develop"}}'
    cmds:
      - git fetch origin
      - git worktree add -b "{{.NAME}}" "{{.WK_DIR}}/{{.NAME}}" "{{.BASE}}"
      - ./scripts/worktree-env.sh "{{.WK_DIR}}/{{.NAME}}" "{{.SHARED_ENV}}"
      - task: wk:install-wk
        vars:
          NAME: "{{.NAME}}"
      - cmd: mise trust "{{.WK_PATH}}/mise.toml"

  remove:
    desc: worktreeを削除（NAME=auth）
    dir: "{{.MAIN_DIR}}"
    requires:
      vars: [NAME]
    cmds:
      - |
        if [ -d "{{.WK_DIR}}/{{.NAME}}" ]; then
          (cd "{{.WK_DIR}}/{{.NAME}}" && docker compose down --volumes --remove-orphans)
        fi
      - git worktree remove "{{.WK_DIR}}/{{.NAME}}"
      - git worktree prune
      - git branch -D "{{.NAME}}"

この運用で困っていたこと:

• プロジェクトごとに Taskfile を書く必要がある: 新しいリポジトリを始めるたびに、パス構成や依存インストール方法に合わせた定義が必要
• env コピーのスクリプトも別途管理: worktree-env.sh を各プロジェクトに配置
• 動作確認のコスト: Taskfile を書いた後、実際に worktree を作って正しく動くか毎回テスト
• チーム共有が難しい: Taskfile のテンプレート構文に慣れていないメンバーへの説明コスト

After — GTR での運用

GTR に移行後は .gtrconfig を 1 ファイル書くだけで完了する。

# .gtrconfig
[copy]
include = **/.env.example
include = **/.env.shared

[hooks]
postCreate = pnpm install && mise trust mise.toml
preRemove = docker compose down --volumes --remove-orphans

[defaults]
ai = claude

実行コマンド:

# Before（Taskfile）
task wk:add NAME=my-feature BASE=develop

# After（GTR）
git gtr new my-feature --base develop

比較まとめ

項目	Taskfile.yaml	GTR（.gtrconfig）
セットアップ	プロジェクトごとに YAML を作成	.gtrconfig 1 ファイル
env コピー	専用シェルスクリプトが必要	glob パターンで宣言的に指定
依存インストール	タスク定義内に記述	postCreate フックに記述
削除時クリーンアップ	条件分岐を含む複雑な定義	preRemove フックに 1 行
AI ツール連携	非対応（別途起動）	--ai フラグでビルトイン
学習コスト	Taskfile テンプレート構文	git config ライクな INI 形式
ポータビリティ	プロジェクトに Task のインストールが必要	Bash のみ（追加依存なし）

結論として、GTR に移行したことで「プロジェクトごとに定義ファイルを書く」という作業自体がなくなった。新しいリポジトリでも .gtrconfig を数行書けば、すぐに worktree 運用を開始できる。

---

AI 並列開発への活用

Claude Code × GTR で並列セッション

GTR の最大の特徴の一つが、AI ツールとのビルトイン連携だ。.gtrconfig で ai = claude を設定すれば、worktree 作成時に Claude Code セッションを同時起動できる。

# worktree を作ると同時に Claude Code を起動
git gtr new auth-feature --ai

# 既存の worktree で Claude Code を起動
git gtr ai auth-feature

これにより、以下のような並列開発ワークフローが実現する:

1. git gtr new auth --ai → 認証機能を Claude Code に任せる
2. git gtr new ui-fix --ai → UI 修正を別の Claude Code セッションに任せる
3. メインの worktree では自分がコアロジックを実装
4. 各セッションが完了したら PR を作成してマージ

ワークフロー例

# 1. 3 つの worktree を作成し、それぞれ AI セッションを起動
git gtr new feature-auth --ai
git gtr new fix-pagination --ai
git gtr new refactor-api --ai

# 2. 一覧で状況確認
git gtr list

# 3. 作業完了後、マージ済み worktree を一括クリーンアップ
git gtr clean --merged

Claude Code の worktree 対応（--worktree フラグや Agent ツールの isolation: "worktree" オプション）と組み合わせることで、AI エージェントが安全に隔離された環境で作業できる。GTR はその「環境を用意する」部分の手間を省いてくれるツールだ。

---

まとめ — worktree 運用の「面倒」を消す

git-worktree-runner（GTR）は、git worktree の「便利だけど面倒」を解消するツールだ。

• 1 コマンドで完結: git gtr new だけで worktree 作成 + env コピー + 依存インストール
• 設定は .gtrconfig に集約: プロジェクトごとのスクリプト管理が不要に
• AI 連携がビルトイン: --ai フラグで Claude Code 等を即起動

以前は Taskfile.yaml でプロジェクトごとに定義を書いていたが、GTR への移行で worktree 運用のハードルが大幅に下がった。AI による並列開発がますます一般的になる中、worktree をストレスなく使えるようにしておくことは、開発効率に直結する。

GTR 導入チェックリスト

• [ ] brew tap coderabbitai/tap && brew install git-gtr でインストール
• [ ] git gtr --version でバージョン確認
• [ ] リポジトリに .gtrconfig を作成（copy / hooks / defaults）
• [ ] git gtr new test-branch で動作確認
• [ ] git gtr rm test-branch で削除確認
• [ ] （任意）git gtr config set gtr.ai.default claude で AI ツール設定

---

FAQ

Q: git-worktree-runner は git worktree の代替ですか？
A: 代替ではなく、git worktree コマンドのラッパーです。内部で git worktree add / git worktree remove を呼んでおり、追加の環境設定やフック実行を自動化します。

Q: Windows でも使えますか？
A: Git Bash または WSL 環境で動作します。Bash 3.2 以上が必要なため、PowerShell ネイティブでは使用できません。WSL での利用を推奨します。

Q: .gtrconfig はリポジトリにコミットすべきですか？
A: チーム開発であればコミット推奨です。メンバー全員が同じ worktree 設定（env コピー、フック）を共有できます。個人設定は git config --local で上書き可能です。

Q: 既存の worktree がある状態で GTR を導入できますか？
A: はい。GTR は git worktree list の出力をベースにしているため、既存の worktree もそのまま管理対象になります。.gtrconfig を追加するだけで運用を開始できます。

Q: Claude Code 以外の AI ツールにも対応していますか？
A: Cursor, VS Code, Aider, Codex, Gemini, Copilot 等のアダプターがビルトインで用意されています。git gtr config set gtr.ai.default <ツール名> で切り替え可能です。