git-worktree

gwt は git worktree を簡単に扱うための CLI。新しい worktree を作るとき、 .gitignore で無視される .env や node_modules/ などのローカルファイルも自動でコピーする。 swt は Superset 向けの worktree CLI で、GitHub Issue / PR から worktree とタスクファイルを作り、 必要に応じて Superset workspace 登録や AI エージェント起動まで行う。

概要

基本のデータフロー

flowchart TD
        repo["元リポジトリ"]
        gwt["gwt add"]
        wt["新しい worktree
+ .gitignore 対象のコピー"]
        gh["GitHub Issue / PR"]
        swt["swt issue / swt pr"]
        task[".superset/task-{slug}.md"]
        agent["AI エージェント起動
claude / codex / gemini ..."]
        superset["Superset / Codex
workspace 連携"]

        repo --> gwt --> wt
        gh --> swt --> wt
        swt --> task --> agent
        wt --> superset
      

インストール

Windows を含む汎用の git worktree 用途では gwt だけをインストールする。 swt は Superset sh / Mac 前提の workflow 用 CLI なので、gwt だけを使う場合はインストール対象外。

# 汎用用途は gwt だけ
go install github.com/TomoakiMizuno/git-worktree/cmd/gwt@latest

# Superset workflow も使う場合は swt も
go install github.com/TomoakiMizuno/git-worktree/cmd/swt@latest

make install-gwt   # gwt だけ
make install       # gwt / swt の両方

gwt — worktree を追加する

# デフォルトの作成先に worktree を追加
gwt add feature-branch

# 作成先パスを明示
gwt add feature-branch /path/to/worktree

# 新規 branch の起点を指定
gwt add feature-branch --base develop

path を省略すると、作成先は現在のリポジトリルート名に branch 名を連結した隣接パスになる。 例えば /repo/myapp で gwt add feature-branch を実行すると、通常は /repo/myapp-feature-branch が作成先。 worktree 作成後、元リポジトリで .gitignore により無視されているファイルやディレクトリを新しい worktree へコピーする。

作成先と base branch

gwt add は第 1 引数の branch が既に存在するかを確認し、状況に応じて git worktree add の呼び出しを切り替える。

--base のデフォルトは main。新規 branch を作る場合だけ、指定したローカル branch または origin/<base> が起点になる。 どちらも見つからない場合は 起点ブランチ "<base>" が見つかりません というエラーで停止する。

gwt — 作業開始前に main を更新する

gwt refresh-main は、現在の worktree を作業開始前に origin/main へ fast-forward する保守的な更新コマンド。 Codex App、Orca、Claude Code などの agent worktree で、tool や hook に依存しない preflight として明示的に呼べる。

# origin/main を fetch し、HEAD がその祖先なら fast-forward
gwt refresh-main

# remote や branch を明示
gwt refresh-main --remote upstream --branch develop

# dirty worktree での実行を明示的に許可
gwt refresh-main --allow-dirty

既定では dirty worktree、diverged HEAD、fetch 失敗、remote branch 不在、fast-forward 失敗で停止する。 --allow-dirty を指定しても stash、自動 rebase、通常 merge、自動 conflict 解決は行わない。

gwt — .worktreeinclude でコピー対象を絞る

gwt add がコピーする対象は、元リポジトリ側で .gitignore に一致したファイルとディレクトリ （.env、node_modules/、.vscode/ など）。リポジトリルートに .worktreeinclude を置くと、 .gitignore で無視された候補をさらにホワイトリストで絞り込める。

# 環境変数ファイルだけコピーする
*.env
.env.*

# 特定の設定ディレクトリをコピーする
config/

# Claude 設定をコピーする
**/.claude/*

• .worktreeinclude が存在しない場合は、従来どおり .gitignore 対象をすべてコピーする。
• 空、またはコメント行と空行だけの場合は何もコピーされない。
• パターン形式は .gitignore と同じ。# で始まるコメント行と空行は無視される。
• ディレクトリがパターンに一致した場合、その配下もコピー対象になる。

gwt — 一覧・削除・コマンド実行

# worktree 一覧（path / branch / commit を表示）
gwt list

# fzf で選択して削除
gwt remove
# path を直接指定して削除
gwt remove /path/to/worktree
# branch 名を指定してデフォルト作成先を削除
gwt remove feature-branch

# 選択した worktree path を最後の引数として渡す
gwt exec code
# 選択した worktree をカレントとしてコマンド実行
gwt exec-in make build

gwt remove / gwt exec / gwt exec-in は fzf を使う。 シェル補完は gwt completion <shell> で出力でき、対応 shell は bash / zsh / fish / powershell。 gwt remove <Tab> で worktree path が補完される。

swt — GitHub Issue / PR から worktree を作る

# GitHub Issue から worktree とタスクファイルを作成
swt issue 123
swt issue '#123'
swt issue https://github.com/org/repo/issues/123
swt issue 123 --base develop

# GitHub PR から worktree とタスクファイルを作成
swt pr 456
swt pr 456 --base develop

# worktree 作成後にエージェントを起動し、Draft PR 作成方針を task に埋め込む
swt issue 123 --agent --pr draft

Issue / PR の入力形式は番号、# 付き番号、GitHub URL。現在の repository と違う owner/repo の URL は拒否する。 日本語など ASCII 以外を含む Issue title からは、codex / copilot / claude の順に英訳を試して branch 名 slug を作る。

swt pr の --base は git worktree add の起点ではなく、task ファイルに書き込む Base Branch の値。 PR の head ref は fetch され、ローカル branch が無ければ作成される。すでにある場合は未 push コミットが無ければ PR の開始点に同期し、未 push コミットがあるとローカル作業を守るためエラーになる。

swt — タスクファイルとエージェント起動

worktree 作成後、swt は .superset/task-{slug}.md を生成する。テンプレートは次の順で探索する。

1. 新しい worktree の template

   <worktree>/.superset/task-prompt-template.md

2. 実行元 repository の template

   未 commit の project local template でも反映できる

3. ホームの template

   ~/.superset/task-prompt-template.md

4. 組み込みデフォルト

   swt task template > .superset/task-prompt-template.md で出力できる

テンプレートでは {{id}}、{{slug}}、{{title}}、{{description}}、{{priority}}、 {{statusName}}、{{labels}}、{{prStrategy}}、{{baseBranch}} の placeholder を使える。 作成済み task からの再開は swt task run（slug 省略時は .superset/task-*.md を探索）。

swt task run                 # 複数 task があれば fzf で選ぶ
swt task run 123-fix-login   # slug を直接指定
swt task run --agent claude

swt は claude、codex、gemini、opencode、pi、copilot、cursor-agent を agent 名として扱える。 swt issue / swt pr で --agent を値なし指定した場合の既定は claude、swt task run で --agent 省略時は codex。 --danger または SWT_DANGER_MODE=1 で agent 定義の権限バイパス系 flag を付ける。

PR 作成戦略

--pr は task ファイルへ書き込む PR 作成戦略。swt 自体がその場で PR を作るのではなく、task を読んだ agent が作業完了後の方針として使う。

swt — 孤立 worktree をクリーンアップする

swt clean は Superset から削除されたが disk に残っている worktree を検出し、必要に応じて削除する。 Superset 管理の worktree directory 配下だけを対象にし、Superset DB の worktree record に存在しない git worktree を孤立とみなす。 まず --list で削除候補を確認する。

swt clean --list          # 削除せず候補だけ表示
swt clean                 # 孤立 worktree を削除
swt clean --delete-branch # local branch も削除
swt clean --force         # 未コミット変更があっても強制削除

Codex App 管理 worktree の record cleanup や stale alias cleanup は swt clean ではなく swt codex unlink-workspace / swt codex prune-links を使う。

Superset / Codex 連携

# Codex hook から現在の Codex worktree を Superset に同期
swt codex sync-current-workspace --quiet

# 同期予定を dry-run で確認
swt codex sync-workspaces --dry-run

# record だけを外す（実体 worktree は残す）
swt codex unlink-workspace --dry-run

# Superset record 起点で古い workspace を監査
swt codex stale-workspaces

# archived thread だけの worktree を cleanup（dry-run -> --apply）
swt codex cleanup-archived-workspaces

所有権は分離されており、Codex App が作成した実体 worktree の所有者は Codex App。実体 worktree を削除するのは stale-workspaces --apply または cleanup-archived-workspaces --apply を明示した場合だけ。 Codex の SessionStart hook（~/.codex/hooks.json）に swt codex sync-current-workspace --quiet を追加すると、セッション開始時に現在の workspace だけを同期できる。

詳細ドキュメント

参照元

• TomoakiMizuno/git-worktree
• README.md
• docs-site docs index