gwt の使い方

gwt は汎用の Git worktree wrapper です。このページでは gwt add/refresh-main/list/remove/exec/exec-in/completion の基本操作と、.gitignore で無視されるファイルのコピー仕様、.worktreeinclude によるコピー対象制御を扱います。

このページの範囲

  • GitHub や Superset に依存しない gwt の操作を説明します。
  • swt issue / swt pr などの GitHub 連携 workflow は swt workflow を参照してください。
  • Superset workspace / Codex App worktree 連携は Superset/Codex runbook を参照してください。

インストール

Windows を含む汎用の git worktree 用途では、swt ではなく gwt だけをインストールします。

go install github.com/TomoakiMizuno/git-worktree/cmd/gwt@latest

ソース checkout から gwt だけをインストールする場合:

go install ./cmd/gwt

make が使える環境では、make install-gwt でも gwt だけをインストールできます。make install は gwt と swt の両方をインストールします。

README 代表導線

README に残す候補 リンク先 理由
gwt add feature-branch #worktree-を追加する gwt の中心操作を一目で示すため。
gwt add feature-branch --base develop #作成先と-base-branch 新規 branch の起点を変えられることを README の短い例で示すため。
gwt refresh-main #作業開始前に-main-を更新する agent preflight や hook から呼ぶ安全な更新手段を示すため。
gwt remove /path/to/worktree #worktree-の一覧と削除 作成と対になる基本操作として示すため。
.worktreeinclude #worktreeinclude コピー対象を絞れる重要な設定なので詳細 docs への導線を残すため。

worktree を追加する

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

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

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

gwt add <branch> [path] は、新しい worktree を作成したあと、元リポジトリで .gitignore により無視されているファイルやディレクトリを新しい worktree へコピーします。

path を省略した場合、作成先は現在のリポジトリルート名に branch 名を連結した隣接パスになります。例えば /repo/myapp で gwt add feature-branch を実行すると、通常は /repo/myapp-feature-branch が作成先です。branch 名に path separator として使えない文字が含まれる場合は、安全な path component に変換されます。

作成先と base branch

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

状況 実行される Git 操作 --base の扱い
ローカル branch が存在する git worktree add <path> <branch> 使われません。
ローカル branch はなく、origin/<branch> が存在する git worktree add -b <branch> <path> origin/<branch> 使われません。
ローカル / remote tracking branch がどちらもない git worktree add -b <branch> <path> <base> 新規 branch の起点として使われます。

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

既存ローカル branch が別の worktree で checkout 済みの場合は、通常の Git worktree の制約により git worktree add が失敗します。その場合は別 branch 名を使うか、既存 worktree を削除してから再実行してください。

作業開始前に 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 では停止します。--allow-dirty を指定しても stash、自動 rebase、通常 merge、自動 conflict 解決は行いません。fast-forward できない場合は停止します。

停止条件は次のとおりです。

  • worktree に未コミットの変更がある（--allow-dirty 未指定時）
  • HEAD が対象 remote branch の祖先ではない
  • git fetch <remote> <branch> が失敗する
  • 対象の remote branch が存在しない
  • git merge --ff-only <remote>/<branch> が失敗する

コピー対象の決まり方

gwt add が worktree 作成後にコピーする対象は、元リポジトリ側で .gitignore に一致したファイルとディレクトリです。代表例は次のとおりです。

  • .env、.env.local などの環境変数ファイル
  • node_modules/ などの依存関係ディレクトリ
  • .vscode/、.idea/ などの IDE 設定
  • その他、リポジトリの .gitignore で無視されるファイルやディレクトリ

検索時は階層ごとの .gitignore を読み込みます。別 worktree のディレクトリは検索対象から除外されるため、既存 worktree の無視ファイルを誤って新しい worktree へコピーしません。

.worktreeinclude が存在する場合は、.gitignore に一致した候補をさらにホワイトリストで絞り込みます。詳細は .worktreeinclude を参照してください。

.worktreeinclude

リポジトリルートに .worktreeinclude を置くと、.gitignore で無視されたファイルのうち、.worktreeinclude のパターンに一致するものだけをコピーします。

# .worktreeinclude

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

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

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

動作は次の順です。

  1. .gitignore で無視されるファイルとディレクトリを検出する。
  2. .worktreeinclude が存在しない場合は、検出した対象をそのままコピーする。
  3. .worktreeinclude が存在する場合は、そのパターンに一致した対象だけをコピーする。

.worktreeinclude の注意点:

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

worktree の一覧と削除

worktree の一覧は gwt list で確認します。

gwt list

出力には worktree path、branch、commit が表示されます。

worktree を削除する場合は gwt remove を使います。

# fzf で選択して削除する
gwt remove

# path を直接指定して削除する
gwt remove /path/to/worktree

# branch 名を指定して、デフォルト作成先の worktree を削除する
gwt remove feature-branch

# shell completion で worktree path を補完して削除する
gwt remove <Tab>

引数なしで実行すると、fzf で branch<Tab>path 形式の候補から削除対象を選択します。detached HEAD の worktree は branch の代わりに commit hash の先頭 7 文字が括弧付きで表示されます（例: (abc1234)）。

gwt remove [path|branch] に引数を渡した場合、次の順で削除対象を解決します。

  1. 絶対 path として存在するか確認する。
  2. 現在のディレクトリからの相対 path として存在するか確認する。
  3. branch 名として扱い、gwt add <branch> と同じデフォルト作成先が存在するか確認する。

削除時のオプション:

# Git の worktree lock や dirty 状態を含めて強制削除する
gwt remove --force /path/to/worktree
gwt remove -f /path/to/worktree

# worktree 削除後に対応するローカル branch も削除する
gwt remove --delete-branch /path/to/worktree
gwt remove -d /path/to/worktree

# 強制削除し、対応するローカル branch も削除する
gwt remove -f -d /path/to/worktree

--force は git worktree remove --force --force を実行します。未保存の変更や worktree lock を無視して削除するため、必要な変更が残っていないか確認してから使ってください。

--delete-branch は worktree 削除後に対応するローカル branch を git branch -D で削除します。未マージ branch や squash merge 済みの branch も削除されます。main と master は保護対象なので、このオプションを指定した場合は worktree 削除前にコマンド全体が失敗します。detached HEAD の worktree では branch 削除をスキップします。

worktree でコマンドを実行する

gwt exec と gwt exec-in は、fzf で選択した worktree に対してコマンドを実行します。どちらも fzf が必要です。

gwt exec は、選択した worktree path をコマンドの最後の引数として渡します。

gwt exec code
# => code /path/to/selected-worktree

gwt exec open
# => open /path/to/selected-worktree

gwt exec-in は、選択した worktree をカレントディレクトリとしてコマンドを実行します。

gwt exec-in make build
# => cd /path/to/selected-worktree && make build

gwt exec-in git status
# => cd /path/to/selected-worktree && git status

シェル補完

gwt completion <shell> は shell completion script を出力します。対応 shell は Cobra の completion と同じく bash、zsh、fish、powershell です。

zsh の例:

mkdir -p ~/.zsh/completions
gwt completion zsh > ~/.zsh/completions/_gwt
echo 'fpath+=(~/.zsh/completions)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
source ~/.zshrc

bash の例:

mkdir -p ~/.bash_completion.d
gwt completion bash > ~/.bash_completion.d/gwt
source ~/.bash_completion.d/gwt

gwt remove <Tab> では worktree path が補完されます。

動作例

元リポジトリに .env と node_modules/ があり、どちらも .gitignore で無視されている例です。

$ ls -a
.git .env node_modules/ src/ .gitignore

$ cat .gitignore
.env
node_modules/

$ gwt add feature-new-ui
Preparing worktree (new branch 'feature-new-ui')
Worktree created: /path/to/repo-feature-new-ui

$ ls -a ../repo-feature-new-ui
.git .env node_modules/ src/ .gitignore

.worktreeinclude で .env だけを許可すると、node_modules/ はコピーされません。

$ cat .worktreeinclude
.env

$ gwt add feature-api
Preparing worktree (new branch 'feature-api')
Worktree created: /path/to/repo-feature-api

$ ls -a ../repo-feature-api
.git .env src/ .gitignore
このページは生成物です。原本は元リポジトリ側にあります。