## 背景
ローカルで同じリポジトリに対し、複数の開発を同時に行うには[[git worktree]]が不可欠となる。特に複数の[[AIエージェント]]で並行開発するケースでは。
一方で、[[git worktree]]はいくつか難点がある。
- コマンドが(個人的に)直感的でない
- ディレクトリ構成や後始末が面倒なことがある
- [[Lazygit]]を使っても上記の問題は解消していない
正直、どれも言語化できるほどハッキリ分析できていない。ただ、直感的にはこのように感じており、過去3回ほど[[git worktree]]の並行開発にチャレンジしてきては挫折してきたという事実がある。
## [[gtr]]
そんなときに[[gtr]]という[[CLI]]ツールを見かけた。
<div class="link-card-v2">
<div class="link-card-v2-site">
<img class="link-card-v2-site-icon" src="https://github.githubassets.com/favicons/favicon.svg" />
<span class="link-card-v2-site-name">GitHub</span>
</div>
<div class="link-card-v2-title">
GitHub - coderabbitai/git-worktree-runner: Bash-based Git worktree manager with editor and AI tool integration. Automates per-branch worktree creation, configuration copying, dependency installation, and workspace setup for efficient parallel development.
</div>
<div class="link-card-v2-content">
Bash-based Git worktree manager with editor and AI tool integration. Automates per-branch worktree creation, con ...
</div>
<img class="link-card-v2-image" src="https://opengraph.githubassets.com/23463d367554ac7f922f1f1dc36c06ec20bc8ac814ed4d48314e982611df3393/coderabbitai/git-worktree-runner" />
<a href="https://github.com/coderabbitai/git-worktree-runner"></a>
</div>
開発元は[[CodeRabbit]]なので品質は信頼できそうだ。
## インストール
```console
brew tap coderabbitai/tap
brew install git-gtr
```
### 環境
| 対象 | バージョン |
| --------- | ------ |
| [[macOS]] | 15.7.4 |
| [[gtr]] | 2.6.0 |
| [[Git]] | 2.53.0 |
### 設定
[[Neovim]]と[[GitHub Copilot CLI]]を設定する。
```
git gtr config set gtr.editor.default nvim --global
```
`~/.gitconfig` に追加される。
```ini
[gtr "editor"]
default = nvim
```
## [[ワークツリー]]をつくってみる
```console
$ git gtr new feature/issue-376
==> Creating worktree: feature-issue-376
Location: /Users/tadashi-aikawa/git/github.com/tadashi-aikawa/obsidian-various-complements-plugin-worktrees/feature-issue-376
Branch: feature/issue-376
==> Fetching remote branches...
==> Creating new branch feature/issue-376 from origin/main
Preparing worktree (new branch 'feature/issue-376')
HEAD is now at 8946302 chore(release): 11.1.0 [skip ci]
[OK] Worktree created with new branch feature/issue-376
[OK] Worktree created: /Users/tadashi-aikawa/git/github.com/tadashi-aikawa/obsidian-various-complements-plugin-worktrees/feature-issue-376
Next steps:
git gtr editor feature/issue-376 # Open in editor
git gtr ai feature/issue-376 # Start AI tool
cd "$(git gtr go feature/issue-376)" # Navigate to worktree
```
fetchでブランチを最新にしたうえで `origin/main` (カレントブランチのorigin?) からブランチと[[ワークツリー]]を生成した。
- [[ワークツリー]]の生成パスは `../<リポジトリ名>-worktrees/<ブランチ名>`
- `<ブランチ名>` の `/` は `-` に置換される
- 別途必要なこと
- `mise trust`
- `node_modules` のインストール
## 設定でセットアップを楽にする
`git gtr config` コマンドで追加することもできるが、リポジトリで管理しても問題ないと思うので `.gtrconfig` に設定する。
`.gtrconfig`
```ini
[hooks]
postCreate = mise trust
postCreate = pnpm install --frozen-lockfile
```
先ほどの[[ワークツリー]]は一度削除する。
```console
git gtr rm feature/issue-376
```
もう一度作成する。
```console
git gtr new feature/issue-376
```
[[ワークツリー]]に移動する。
```console
cd "$(git gtr go feature/issue-376)"
```
## シェルの補完を有効にする
対象のブランチ/[[ワークツリー]]名を指定したり、`cd` コマンドで移動するのも面倒なので設定する。
```bash
# ~/.zshrc
autoload -Uz compinit
compinit
# compinitより後
_gtr_init="${XDG_CACHE_HOME:-$HOME/.cache}/gtr/init-gtr.zsh"
[[ -f "$_gtr_init" ]] || eval "$(git gtr init zsh)" || true
source "$_gtr_init" 2>/dev/null || true; unset _gtr_init
```
> [!left-bubble] ![[chappy.webp]]
> `gtr` を「コマンドとして実行できる」こと自体は、Homebrew が `/opt/homebrew/bin/gtr` を入れて `PATH` に載っているからです。
> つまり、これは `compinit` 前でも後でもなく、brew インストールだけで成立します。
>
> そのうえで設定の役割はこうです。
>
> - `compinit` より前の `eval "$(git gtr completion zsh)"`
> - これは `git gtr` の補完のためです
> - Zsh に「`gtr` は `git` のサブコマンドだ」と事前登録します
> - ついでに completion 用の `fpath` を足します
> - ただし `gtr` 関数は作りません
>
> - `compinit` の後の `git gtr init zsh` を source する設定
> - これは `gtr` シェル関数を定義します
> - その結果、`gtr cd` や `gtr new --cd` が使えるようになります
> - `gtr` 単体のラッパー補完もここで `compdef _gtr_completion gtr` により入ります
>
> 要するにこうです。
>
> - `git gtr` の補完を有効にするのは `compinit` 前の設定
> - `gtr cd` を使えるようにするのは `compinit` 後の `init` 設定
> - `gtr` という実行ファイルそのものは brew が入れている
## [[fzf]]と連携する
[[ファジー検索]]で[[ワークツリー]]を切り替えられるのでとても便利。`gtr cd` コマンドで起動するが、より簡単に起動できるように `iw` コマンドでエイリアスを張った。
```console
alias iw='gtr cd'
```
## ワークツリーを削除する
開発を終えてマージし終えたブランチ/[[ワークツリー]]を削除する。
`gtr rm` コマンドでも可能だが、先ほどの `iw` コマンドで選択したあとに `<C-d>` を押すことで削除できる。ただ、確認メッセージは出ないので誤爆に注意。
ブランチも同時に消したいときは `gtr rm` コマンドを `--delete-branch` オプションで指定したほうが速い。
```console
gtr rm <branch> --delete-branch
```
## まとめ
### インストールと初期設定
```console
brew tap coderabbitai/tap
brew install git-gtr
git gtr config set gtr.editor.default nvim --global
```
`~/.zshrc`
```bash
autoload -Uz compinit
compinit
# compinitより後
_gtr_init="${XDG_CACHE_HOME:-$HOME/.cache}/gtr/init-gtr.zsh"
[[ -f "$_gtr_init" ]] || eval "$(git gtr init zsh)" || true
source "$_gtr_init" 2>/dev/null || true; unset _gtr_init
alias iw='gtr cd'
```
### リポジトリの設定
[[🦉Various Complements]]の場合。
`.gtrconfig`
```ini
[hooks]
postCreate = mise trust
postCreate = pnpm install --frozen-lockfile
```
一部の非追跡ファイルもコピーしたいとき。
`.gtfconfig`
```ini
[copy]
include = carnelianrc.json
```
### 主な操作
```bash
# ワークツリーの作成
gtr new <ブランチ名>
# ワークツリーの切り替え
iw
# ワークツリーの削除
iw # <C-d>で削除
# ワークツリー&ブランチの削除
gtr rm <branch> --delete-branch
```