AIエージェント並列実行に便利なgtr（git-worktree-runner）が.gtrconfig対応でチーム利用しやすくなった

Claude CodeやCodex CLIなどのAIエージェントを並列実行する上でgit worktree（以下worktree）が注目されています。
ただworktreeはコマンドがややこしいので、補助ツールが欲しくなります😭

そこでおすすめしたいのがCodeRabbitが開発しているgit-worktree-runnerというcliツールです!（公式の略称がgtrなので、今後はgtrと表記します。）
gtrの提供するコマンドは便利だったのですが、これまで設定周りが少し使いづらかったのですが、最近のアプデで.gtrconfigという設定ファイルに対応しチームでの活用などもやりやすくなりました🥳

この記事ではgtrの簡単な使い方と、最近追加された.gtrconfigについて紹介します。

gtrの使い方

.gtrconfigの紹介がメインの記事なので重要なところだけ紹介します。詳細は公式リポジトリや別の紹介記事をご覧ください。

インストール

いくつか用意されていますがQuick Startのものを紹介します。

リポジトリをクローンして、シンボリックリンクを貼る方式です。
これでgit gtrというコマンドが使えるようになります。

git clone https://github.com/coderabbitai/git-worktree-runner.git
cd git-worktree-runner
sudo ln -s "$(pwd)/bin/git-gtr" /usr/local/bin/git-gtr

ちょっと長いのでaliasを設定するのが良いかと思います。
元々はgtrというコマンド名だったのですが、brewのコマンドと被ることが多く変わりました。

# ~/.zshrc などに追加
alias gwr='git gtr'

アップデート

シンボリックリンクの場合は
git pullしたらOKです

cd git-worktree-runner
git pull

日常的に使うコマンド

だいたい以下のコマンドで使うことになります。
new、editor、aiでworktreeを作ってAIツールで開く。
listとrmで作成済みのworktreeを管理、といった感じですね。

# my-featureという名前でブランチとworktreeを作る。すでにブランチがあればworktreeだけ作る
git gtr new my-feature
# 現在のcheckoutしてるブランチからnewしたい場合
git gtr new my-feature --from-current
# 設定したエディタ（Cursorなど）でworktreeを開く
git gtr editor my-feature
# 設定したCLIツール（Claude Codeなど）でworktreeを開く
git gtr ai my-feature

# worktreeの一覧を確認
git gtr list
# worktreeを削除
git gtr rm my-feature

gwrエイリアスある場合

# my-featureという名前でブランチとworktreeを作る。すでにブランチがあればworktreeだけ作る
gwr new my-feature
# 現在のcheckoutしてるブランチからnewしたい場合
gwr new my-feature --from-current
# 設定したエディタ（Cursorなど）でworktreeを開く
gwr editor my-feature
# 設定したCLIツール（Claude Codeなど）でworktreeを開く
gwr ai my-feature

# worktreeの一覧を確認
gwr list
# worktreeを削除
gwr rm my-feature

list表示すると分かりますが、いい感じにworktree用のディレクトリに纏まります。

❯ gwr list
Git Worktrees

BRANCH                         PATH
------                         ----
main [main repo]               /Users/you/your-project
(detached)                     /Users/you/your-project-worktrees
my-feature                     /Users/you/your-project-worktrees/my-feature
test                           /Users/you/your-project-worktrees/test


Tip: Use 'git gtr list --porcelain' for machine-readable output

.gtrconfigで設定を宣言的に管理

本編です。
worktreeを作る際には普段gitignoreしてるファイルをコピーしたり、作成後に特定の依存解決コマンドを実行したいです。

これまでの課題

gtrはcopyやhooksの設定機能でこれらを実現するのですが、これまでは毎回設定コマンドを叩く必要がありました。

# コピー系
git gtr config add gtr.copy.include "**/.env.example"
git gtr config add gtr.copy.include "**/CLAUDE.md"
git gtr config add gtr.copy.include "*.config.js"

# hook
git gtr config add gtr.hook.postCreate "npm install"

コピーしたいファイルごとに何度もコマンドを叩くのは面倒で、チームで設定を共有するのも難しい状況でした。

.gtrconfig

アプデでgtr用の設定を宣言的に書けるようになりました。
リポジトリにこのファイルを追加すれば、チームメンバーも簡単にgtrを使い始められますね！
何が設定されてるかも分かりやすいです。
defaultsの部分は使用するエディタやAIツールが人によって異なるため、.gtrconfigには書かない、もしくは.gtrconfig.exampleのようなファイルをgit管理するのが良いかと思います。

.gtrconfig

# .gtrconfig - commit this file to share settings with your team

[copy]
    include = **/.env.example
    include = *.md
    exclude = **/.env

[copy]
    includeDirs = node_modules
    excludeDirs = node_modules/.cache

[hooks]
    postCreate = npm install
    postCreate = cp .env.example .env

[defaults]
    editor = cursor
    ai = claude

.gtrconfig作成のTips

おそらくみなさんAIツールで.gtrconfigを作成されると思います。
copy部分は以下の方法が楽だったので紹介です。

1. gtrで2つworktreeを作る
2. 片方だけビルドを済ませる（依存インストールやビルドコマンドを実行）
3. /add-dirなどで両方のworktreeディレクトリをエージェントに伝える
4. ビルド済みとビルド前のworktreeを比較させ、生成されたファイル（node_modulesやビルドキャッシュなど）を特定してコピー対象に追加する

まとめ

.gtrconfigの登場でチーム全体でworktreeを活用しやすくなると思います

ちなみに.gtrconfigや--from-currentオプションは自分がIssueで提案したのですが、かなり早く対応してもらえたので要望あったらFBすると良さそうです！

https://github.com/coderabbitai/git-worktree-runner/issues?q=is%3Aissue state%3Aclosed author%3AK9i-0