using-gwq

gwq で Git worktree を扱う

worktree の操作は常に gwq を使い、git worktree は使わない。gwq は worktree を 固定のベースディレクトリ配下（~/worktrees/{{.Host}}/{{.Owner}}/{{.Repository}}/{{.Branch}}） に必ず配置するので、パスが予測可能になる。引数の体系が git worktree とは違うため、 推測せず以下のルールに従うこと。

git worktree との重要な違い

• パスは渡さない。 worktree の配置場所は gwq に任せる。ブランチだけを渡す。
• 引数はブランチが先: gwq add [branch] [path] で、git worktree add [path] [branch] とは逆の順序。
• remove はパスではなくパターンを取る: ブランチ名やパスの一部にマッチさせて削除する。
• 対話モードを絶対に起動しない。 パターンやブランチを省略すると fuzzy finder (fzf) が起動し、非対話のエージェントはハングする。常に明示的にブランチ／パターンを渡し、 -i/--interactive は使わない。

worktree を作る

# 新しいブランチ＋worktree
gwq add -b feature/new-thing

# 既存ブランチから worktree
gwq add feature/existing

パス引数は渡さないこと。-s/--stay（シェルを起動する）も使わないこと。

worktree 作成後のセットアップ（mise を使うリポジトリ）

リポジトリが mise を使っている（.mise.toml / mise.toml / .config/mise/config.toml などがある）場合、worktree を作るたびに mise trust が必要になる。~/.config/gwq/config.toml の repository_settings に setup_commands を足しておくと、gwq add のたびに自動実行される：

[[repository_settings]]
repository = "~/workspace/github.com/<owner>/<repo>"
setup_commands = ["mise trust"]

repository はリポジトリのルートパス、setup_commands は worktree 作成後に走らせる コマンドの配列。mise を使うリポジトリで未設定なら、この設定を足すことを提案・実施すること。

worktree のパスを調べて移動する

gwq cd は新しい対話シェルを立ち上げる。人間には便利だが、エージェントにとっては 不便（立ち上がったシェルの中で操作できない）。代わりに、まずパスを解決してから 自分で cd する：

# 正確なパスを取得する（曖昧なときに fuzzy finder を避けるため --json を使う）
gwq list --json
# 該当する .path を選び、別ステップでディレクトリを移動する

gwq get <pattern> もパスを表示するが、パターンが複数の worktree にマッチすると fuzzy finder が起動する。gwq list --json で正確なエントリを自分で選び、その .path へ cd する方を優先すること。

ディレクトリを移動せずに worktree の中でコマンドを実行したいときは exec を使う：

gwq exec feature/existing -- npm test

一覧と状態確認

gwq list            # 今のリポジトリの worktree
gwq list --json     # 機械可読。パス抽出にはこれを使う
gwq list -g         # 全リポジトリの worktree（どこからでも）
gwq status --json   # 全 worktree の git status

worktree を削除する

# worktree を削除（ブランチは残す）。パターンはブランチ名かパスにマッチ
gwq remove feature/old

# worktree とブランチを両方削除
gwq remove -b feature/done

# 削除せずに対象だけ確認
gwq remove --dry-run feature/old

引数なしの gwq remove は実行しない（fuzzy finder が起動する）。常にパターンを渡すこと。

クイックリファレンス

やりたいこと	コマンド
新ブランチ＋worktree	gwq add -b <branch>
既存ブランチから worktree	gwq add <branch>
一覧（パス付き）	gwq list --json
worktree 内でコマンド実行	gwq exec <pattern> -- <cmd>
cd するためのパス取得	gwq list --json → .path を選ぶ → 別ステップで cd
worktree を削除	gwq remove <pattern>
worktree＋ブランチを削除	gwq remove -b <pattern>

避けること（対話的／シェルを起動するためエージェントがハングする）: 引数なしの gwq add/gwq remove/gwq get、-i/--interactive、-s/--stay、gwq cd。