🌳

Git Worktreeを快適に使うCLIツール「gw」を作った

に公開
Git
tech

はじめに

Git Worktreeを活用していますか？複数のブランチを並行して作業できる便利な機能ですが、コマンドが長くて覚えづらかったり、ディレクトリ名の管理が面倒だったりしませんか？

そこで、Git Worktreeをより快適に使えるCLIツール「gw」を作りました。

https://github.com/t98o84/gw

Git Worktreeとは？

そもそもGit Worktreeは、1つのリポジトリで複数のブランチを同時にチェックアウトできる機能です。

例えば、以下のようなシーンで便利です：

  • 新機能の開発中に、急なバグ修正が必要になった
  • レビュー中のPRがあるのに、別の作業を始めたい
  • 古いブランチの挙動を確認しながら、新しいコードを書きたい

従来はgit stashでコミットを一時退避したり、別のディレクトリにリポジトリをクローンしたりしていましたが、Worktreeを使えばスマートに解決できます。

課題：標準のgit worktreeコマンドは使いづらい

ただし、標準のgit worktreeコマンドは少々使いづらい面があります：

# Worktreeを作成（長い...）
git worktree add ../my-repo-feature-new-thing feature/new-thing

# 一覧表示
git worktree list

# 削除
git worktree remove ../my-repo-feature-new-thing

問題点：

  • コマンドが長く、パスを毎回指定するのが面倒
  • ディレクトリ名を自分で考えないといけない
  • 移動やコマンド実行が面倒
  • ブランチとWorktreeの紐付けが直感的ではない

解決策：gwで快適なWorktreeライフ

「gw」は、これらの課題を解決するラッパーツールです。

主な機能

📁 直感的なWorktree作成

ブランチ名を指定するだけで、自動的に良い感じのディレクトリ名を生成します。

# ブランチ名から自動的にディレクトリ名を生成
gw add feature/new-thing
# => ../my-repo-feature-new-thing/ に作成される

# 新規ブランチも簡単に
gw add -b feature/awesome-feature

# 引数なしでfzfによるインタラクティブな選択も可能
gw add

🐙 GitHub PRからWorktreeを作成

PR番号やURLを指定するだけで、そのPRのブランチでWorktreeを作成できます。

# PR番号から
gw add --pr 123
gw add -p 123

# PR URLから
gw add -p https://github.com/owner/repo/pull/123

レビューするときに超便利です！

🔍 fzfによるインタラクティブな操作

引数なしで実行すると、fzfで快適に選択できます。

# Worktreeをインタラクティブに選択して移動
gw sw

# Worktreeを選択して削除（Tabで複数選択可能）
gw rm

# Worktreeを選択してコマンド実行
gw exec git status

🚀 ディレクトリ移動のシェル統合

シェル統合を設定すれば、ディレクトリ移動が快適になります。

# 指定したWorktreeに移動
gw sw feature/new-thing

# fzfで選択して移動
gw sw

# 現在のWorktreeを閉じてメインに戻る
gw close

🎯 柔軟な名前指定

Worktreeを指定する際、複数の方法で名前を指定できます。

# すべて同じWorktreeを指す
gw rm feature/hoge
gw rm feature-hoge
gw rm my-repo-feature-hoge

🔧 プロジェクト固有の自動化（Hook機能）

プロジェクトルートにgw.yamlを配置すると、Worktree作成時に自動的に環境構築などを実行できます。

hooks:
  # Worktree作成前のバリデーション
  pre_add:
    - command: echo "新しいWorktreeを作成します $GW_BRANCH"

  # Worktree作成後のセットアップ
  post_add:
    - command: |
        echo "セットアップ完了"
        echo "- ブランチ: $GW_BRANCH"
        echo "- パス: $GW_WORKTREE_PATH"
        echo "- mainリポジトリルート: $GW_REPO_ROOT"

  # Worktree削除前のバックアップ
  pre_remove:
    - command: |
        echo "$GW_WORKTREE_PATH を削除します。"

  # Worktree削除後のクリーンアップ
  post_remove:
    - command: echo "$GW_BRANCH のクリーンアップが完了しました"

これにより、チーム全体で環境構築手順を統一でき、新しいWorktreeを作るたびに手動でコマンドを実行する必要がなくなります。

利用可能な環境変数：

  • GW_WORKTREE_PATH: 作成されたWorktreeの絶対パス
  • GW_BRANCH: ブランチ名
  • GW_REPO_ROOT: メインリポジトリのルートディレクトリの絶対パス

Hook実行のエラーハンドリング：

  • pre_add / pre_remove: 失敗すると操作全体が中止される
  • post_add / post_remove: 失敗しても警告のみで操作は成功扱い

⚙️ 設定ファイルによるカスタマイズ

~/.config/gw/config.yamlで動作をカスタマイズできます。

add:
  open: true  # Worktree作成後に自動でエディタを開く
  sync: false  # メインWorktreeからファイルを同期
  sync_ignored: false  # gitignoreされたファイルも同期
rm:
  branch: false  # Worktree削除時にブランチも削除
  force: false  # 確認プロンプトをスキップ
close:
  force: false  # 確認プロンプトをスキップ
editor: code  # 使用するエディタコマンド

また、--no-*フラグで設定を一時的に無効化することもできます。

# config.yaml で add.open=true でも開かない
gw add --no-open feature/hoge

# config.yaml で rm.branch=true でもブランチを残す
gw rm --no-branch feature/hoge

インストール

Homebrew（推奨）

brew install t98o84/tap/gw

Go

go install github.com/t98o84/gw@latest

バイナリ

Releasesから各OS用のバイナリをダウンロードできます。

セットアップ

1. シェル統合の設定

gw swでディレクトリ移動するために、シェルの設定ファイルに以下を追加します。

Bash:

# ~/.bashrc に追加
eval "$(gw init bash)"

Zsh:

# ~/.zshrc に追加
eval "$(gw init zsh)"

Fish:

# ~/.config/fish/config.fish に追加
gw init fish | source

2. 必要なツールのインストール

  • git - 必須
  • fzf - インタラクティブな選択に必要
  • gh - PR連携に必要（オプション）
# macOS
brew install fzf gh

# Ubuntu/Debian
sudo apt install fzf gh

使用例

基本的なワークフロー

# 1. 新機能用のWorktreeを作成
gw add -b feature/awesome-feature

# 2. 作業する
cd ../my-repo-feature-awesome-feature
# ... コーディング ...

# 3. 急なバグ修正が必要になった
gw add -b fix/critical-bug
# 自動的に ../my-repo-fix-critical-bug に移動

# 4. バグ修正完了、元の作業に戻る
gw sw feature/awesome-feature

# 5. 不要になったWorktreeを削除
gw rm fix/critical-bug

# またはWorktree上から閉じる
gw close

PRレビュー時のワークフロー

# 1. PRからWorktreeを作成
gw add -p 123

# 2. レビュー後、削除
gw close -b  # Worktreeとブランチを同時に削除

複数Worktreeの一括削除

# fzfで選択（Tabで複数選択）
gw rm

# またはブランチ名で指定
gw rm feature/old-1 feature/old-2 fix/completed

コマンド一覧

コマンド エイリアス 説明
gw add <branch> gw a Worktreeを作成
gw add -b <branch> gw a -b 新規ブランチ+Worktree作成
gw add --pr <url|number> gw a -p PRのブランチでWorktree作成
gw add --open gw a --open Worktree作成後にエディタで開く
gw add --sync gw a --sync メインWorktreeからファイルを同期
gw ls gw l Worktree一覧を表示
gw ls -p gw l -p フルパスのみを出力
gw rm [name...] gw r Worktreeを削除（複数指定可）
gw rm -b <name> gw r -b Worktreeとブランチを削除
gw exec [name] <cmd...> gw e 対象Worktreeでコマンド実行
gw sw [name] gw s 対象Worktreeに移動
gw close gw c 現在のWorktreeを閉じてメインに戻る
gw close -b gw c -b Worktreeとブランチを削除して閉じる
gw fd gw f fzfでWorktreeを検索（ブランチ名出力）
gw fd -p gw f -p fzfでWorktreeを検索（フルパス出力）
gw init <shell> gw i シェル初期化スクリプトを出力

まとめ

「gw」を使えば、Git Worktreeの操作がシンプルかつ直感的になります。

  • ✅ ディレクトリ名を考えなくていい
  • ✅ コマンドが短くて覚えやすい
  • ✅ fzfでインタラクティブに選択できる
  • ✅ PRからすぐにWorktreeを作れる
  • ✅ Hookで環境構築を自動化できる
  • ✅ 設定ファイルで動作をカスタマイズできる

複数ブランチでの並行作業が多い方、PRレビューを効率化したい方にぜひ使ってほしいツールです。

気に入っていただけたら、GitHubでスターをいただけると嬉しいです！

https://github.com/t98o84/gw

参考リンク

Discussion