スマホからパソコン上の Git worktree を管理する
Git worktree をリモートで追加、切り替え、片付けるための実践ガイド。レビュー、小さな編集、安全なコミットのためのスマホでのワークフロー付きです。
- CLI
- 0.2.17
- プレビュー ref
- a2c45c8
Git worktree は、「本格的な」Git ユーザー向けの高度な機能に見えるかもしれません。
でも、同じ状況が何度も起きます。
- ある変更の途中にいる
- 小さなホットフィックスが割り込んでくる
- または、別のブランチをさっとレビューしたい
- そして stash/unstash を繰り返したくない
worktree は、これにすっきり答えてくれます。
もう1つの気づきは、もっと実用的なものでした。
スマホから worktree を管理できれば、「デスクに戻ってから後でやろう」で止まらなくなる。
このガイドは、スマホを操作の中心にした、落ち着いて繰り返せる worktree のワークフローです。
かんたんな定義: worktree とは（わかりやすく）
Git のリポジトリには、通常1つの作業ディレクトリ（チェックアウトしたファイル）があります。
worktree を使うと、1つのリポジトリに複数の作業ディレクトリを持てるので、同時に複数のブランチをチェックアウトできます。
Git の公式ドキュメントでは、「同じリポジトリに紐づく複数の作業ツリー」を管理し、同時に複数のブランチをチェックアウトできるものと説明されています。（出典: https://git-scm.com/docs/git-worktree）
実際には:
- リポジトリのオブジェクトデータベースは共有される
- 各 worktree は、それぞれ自分のチェックアウトされたファイルと index/HEAD の状態を持つ
だから worktree は「リポジトリを2回クローンする」よりずっと軽く感じられます。
よくある方法とトレードオフ
ホットフィックスが大きな変更に割り込んできたとき、よくある選択肢は:
- stash: 使えますが、何をなぜ stash したか忘れがちです
- WIP をコミットする: 使えますが、履歴が汚れてミスを招きます
- もう一度クローンする: 使えますが、遅く、多くを重複させます
worktree なら、メインのブランチをきれいに保ち、しかも勢いを保てます。
動くワークフロー
このワークフローでは、日々の Git 操作のために、リポジトリを持つパソコンに対してリモート UI を使います。
Happier は、この方法に対応する選択肢の1つです。
Happier のセッションはどれもパソコン上のフォルダに紐づいていて、スマホではセッションがそのフォルダ専用の ファイル（Files）タブと Git タブを持ちます。つまり、worktree のフォルダと、その中のセッションがあれば十分です。
Git の書き込み操作（コミット、プル、プッシュ、ブランチの切り替え）は実験的で、既定ではオフです。設定（Settings）→ 機能（Features）→ バージョン管理操作（Source control operations） でオンにします（Git のドキュメント（英語）を参照）。状態や差分の確認は、これがなくても使えます。
トレードオフ: パソコンはオンラインである必要があります。
Happier を初めて使う場合（概要と入手方法）
Happier を初めて見る方へ。Happier はオープンソースのコンパニオンアプリ（モバイル/Web/デスクトップ）で、ワークフローは信頼できるパソコンに置いたまま、スマホから管理できます。
セットアップ:
- スマホから Happier を使う方法
- GitHub: https://github.com/happier-dev/happier
- インストール/ダウンロード: https://github.com/happier-dev/happier#how-it-works
- Discord（コミュニティとサポート）: https://discord.gg/W6Pb8KuHfg
ミスを防ぐ考え方
スマホから worktree に触る前に、2つのルールを決めておきます。
-
1つの worktree = 1つの目的。 ホットフィックスが無関係なら、専用の worktree を用意しましょう。
-
スマホでは小さな編集、大がかりな作業はキーボードで。 スマホは、レビュー、軽い変更、範囲の狭い修正のプッシュに向いています。
手順: スマホから worktree を管理する
1) リポジトリのフォルダでセッションを開く
リポジトリで動いているセッションを開くか、新しいセッションを始めて、作業ディレクトリとしてパソコン上のリポジトリのフォルダを選びます。
2) Git タブを「安全確認の画面」として使う
セッションの中で:
- Git タブを開く
- 変更されたファイルから始める
これで、次のことをすっきり行えます。
- 何が変更されているか確認する
- 意図してコミットする
- 同期する（プル/プッシュ）
次のように表示されたら:
- Operation requires a clean working tree.（作業ツリーがクリーンである必要があります）
ガードレールとして受け止めましょう。
3) 新しい worktree を作る（ホットフィックス）
worktree の作り方には、2つの考え方があります。
- 「新しいブランチ用の新しいディレクトリが欲しい」
- 「既存のブランチ用の新しいディレクトリが欲しい」
素の Git では、おおむね次のとおりです。
git worktree add <path>（新しいブランチを手軽に）- または
git worktree add <path> <branch>（既存のブランチ）
（出典: https://git-scm.com/docs/git-worktree）
Happier で大事なのは、結果です。
- 専用のセッションを始められる2つ目の作業ディレクトリ
- すでにチェックアウトされているものを乱さない
4) スマホでの編集は狭く保つ
worktree ができたら、スマホでのループは次のとおりです。
- その worktree で動いているセッションを開く
- ファイル で目的のファイルを検索する
- 最小限の編集をする
- 保存（Save）
- Git タブに切り替えて差分を確認する
- 修正に含めるファイルだけを正確に選び（0.2.12 以降で対応）、小さな変更としてコミットする
5) ホットフィックスをプッシュする（そして止める）
ホットフィックスをプッシュしたら、止めます。
worktree の価値は、ホットフィックスが2つ目のプロジェクトに膨らまないことです。
狭いままに保ちます。
6) worktree を片付ける（散らからないように）
worktree は強力ですが、溜まっていきます。
良いルール:
- ブランチがマージされたら、worktree を削除する
- 長く続くものなら残すが、わかりやすい名前を付ける
素の Git では、worktree が正しくない方法で削除された場合、git worktree prune で古い管理ファイルを片付けられます。（出典: https://git-scm.com/docs/git-worktree）
UI 中心のワークフローでは、目標はもっとシンプルです。放置された作業ディレクトリの山を残さないことです。
worktree と複数のエージェント（これが重要になった理由）
worktree は以前からありますが、複数のエージェントやセッションを並列で動かすようになると、ずっと便利になります。
Claude Code、Codex、OpenCode を使っているなら、基本的なマルチエージェントのパターンは次のとおりです。
- タスクごとに1つの worktree
- worktree ごとに1つのセッション
これで分離できます。
- エージェントどうしがファイルを踏み合わない
- 差分がレビューしやすいまま
- コミットが狭いまま
Happier なら、スマホをターミナルにしなくてもこれができます。
- worktree を作る
- その worktree のフォルダで新しいセッションを起動する（Claude/Codex/OpenCode）
- 差分、コミット、履歴を確認するのと同じアプリでセッションを監視する
これは意図的に「エージェントを 10 個同時に動かす」話ではありません。
2〜3 個を並列で動かし、レビューが手に負えるよう分離しておく、という話です。
ターミナル（任意）
埋め込みターミナルが使える場合、セッションに ターミナル（Terminal）タブが表示されます。機能一覧（英語）によると実験的な機能で、接続済みのデーモンと到達可能なマシンが必要です。
ターミナルは、次のための非常口として扱いましょう。
- UI にない1つのコマンド
- 念のための確認
- 何かがおかしな状態のときの worktree の片付け
何でもターミナルでやっていると気づいたら、それは次のどちらかのサインです。
- ワークフローを単純にする
- キーボードを待つ
よくある質問（worktree の実際の疑問）
ブランチと worktree の違いは？
ブランチはポインター（コミットの流れに付けた名前）です。
worktree は、ブランチをチェックアウトできる別の作業ディレクトリです。
ふつうは両方を組み合わせて使います。worktree ごとに1つのブランチです。
stash ではなく worktree を使う理由は？
stash は、ちょっとしたコンテキストの切り替えに向いています。
worktree は、割り込みが本物の作業（ホットフィックス、レビュー、テストの実行）で、今の変更を踏む可能性をゼロにしたいときに向いています。
同じブランチを2つの worktree でチェックアウトできますか？
既定では、Git は同じブランチを2つの worktree で同時にチェックアウトすることを防ぎます。
これは安全のための機能です。
（ブランチなしで「テストを実行するだけ」のような作業には、detached HEAD の worktree を使えます。）
将来の自分にわかるよう、worktree にどう名前を付けますか？
目的がわかる名前を使います。
hotfix-<ticket>review-<pr>release-<version>
worktree でよくある大きな失敗は？
Git の部分ではありません。
人間の部分です。
- どの worktree が「プッシュしていない変更があるもの」か忘れる
- 作りかけのホットフィックスの worktree を放置する
対処はシンプルです。worktree を狭く保ち、片付けることです。
スマホから worktree を使うべきでないのはいつですか？
次のことをしようとしているときです。
- コンフリクトの解決
- インタラクティブな rebase
- 大規模なリファクタリング
これらは、やはりキーボードでやるのが向いています。
「worktree is locked」とはどういう意味ですか？
Git では worktree をロックして、自動で prune/片付けされないようにできます。
worktree が、常にマウントされているとは限らないディスクや場所にある場合に便利です。
「prune」は何をするもので、いつ必要ですか？
worktree のフォルダが正しくない方法で（git worktree remove を使わずに）削除されると、Git に古いメタデータが残ることがあります。
git worktree prune は、その古い管理ファイルを片付けます。
worktree のフォルダを手作業で削除しないなら、これが必要になることはまれです。
長く続くブランチを分けておくのにも worktree を使えますか（ホットフィックス以外にも）？
はい。良い使い方です。
例:
- メインの worktree で
mainをきれいに保つ release/<version>を専用の worktree に置く- 長く続くリファクタリングを専用の worktree に置く
コンテキストの切り替えが減り、さっとレビューしやすくなります。
worktree どうしで node_modules やビルド成果物は共有されますか？
自動では共有されません。
各 worktree は別のディレクトリなので、ほとんどのツールは別のプロジェクトフォルダとして扱います。
キャッシュを共有したいなら、それはふつう Git ではなく、言語やツールの層（pnpm store、Gradle のキャッシュなど）が扱います。
worktree のフォルダはどこに置くべきですか？
メインのリポジトリのフォルダの隣に、わかりやすい名前で置きます。
例:
repo/（メインの worktree）repo--hotfix-123/repo--release-1.2/
良い命名規則は、スマホの画面で何を見ているのかがすぐわかるものです。
スマホから worktree を安全に削除できますか？
はい。ただ、先に安全のためのルールを1つ守りましょう。
- コミットしていない変更がないことを確認する
- まだ必要な、プッシュしていないコミットがないことも確認する
削除の前に「変更されたファイル」（Changed files）をさっと確認するのは、安い保険です。
git worktree は git switch / git checkout と同じものですか？
いいえ。
switch/checkoutは、1つの作業ディレクトリが指すブランチを変えます。worktree addは、切り替えなくて済むよう2つ目の作業ディレクトリを作ります。
ブランチの代わりに worktree を使うべきですか？
いいえ。worktree はブランチを補うものです。
良い既定は変わりません。
- worktree ごとに1つのブランチ
サブモジュールと一緒に worktree を使えますか？
はい。ただし注意が必要です。各 worktree はそれぞれのチェックアウト状態を持ちます。
サブモジュールがワークフローの一部なら、スマホでの変更は狭く保ち、大がかりな「サブモジュールの手術」はキーボードでやりましょう。