Git School · FluxGit

Git worktreeとsubmodule：履歴の所属で選ぶ

FluxGit · 2026年10月9日

各ブロックは別のケースであり、一括実行するスクリプトではありません。自分のリポジトリに合うケースを選び、ブランチ名、パス、VERIFIED_COMMITを置き換えてください。中止コマンドは対応する進行中の操作だけに使い、両方の選択肢を実行しないでください。

要点

同じリポジトリで並行作業やブランチレビューのため別のチェックアウトが必要ならworktreeです。別リポジトリの特定コミットを依存関係として親に記録するならsubmoduleです。一方は共有履歴の別作業ディレクトリ、もう一方は独立したバージョン履歴と親による選択です。

判断	Worktree	Submodule
履歴	同じリポジトリのオブジェクトと参照を共有	別の子リポジトリ。親がコミットを記録
ファイル	専用のHEAD、インデックス、作業ディレクトリ	子のチェックアウトと親・インデックスのピンは異なり得る
バージョン	同じリポジトリのブランチまたはコミット	選択した子コミット。.gitmodulesだけでは決まらない
更新	選んだブランチを確認し統合	記録済みピンへチェックアウト。--remoteは別の選択
制限	通常は同じブランチの同時チェックアウト不可。権限隔離ではない	複数worktreeでの対応は不完全。子の作業は別

例と前提条件

最初に履歴を誰が管理するか確認します。同じアプリの修正を2つのエージェントで試すなら、通常は別ブランチと作業ツリーです。独自のリリースを持つライブラリなら固定依存関係が適します。どちらも権限sandboxではなく、ファイルとエージェントの権限管理は別に必要です。

変更前に状態を確認する

linked worktreeには固有のHEAD、インデックス、作業ファイルがあり、オブジェクトと多数の参照は共有します。現在の編集を保ちつつ別ブランチを確認できます。通常は同じブランチを2か所で同時チェックアウトできません。共有オブジェクトによって未ステージの編集が他のディレクトリへ自動転送されることもありません。

git status --short
git branch --show-current
git worktree list

参照または別のチェックアウトを保つ

状態を確認し、../topic-reviewにreview/worktreeを作ります。git -Cでそのチェックアウトを確認し、コミットを比較してから選んだ結果を統合します。別ディレクトリはタスクの混同を減らしますが、変更の互換性を保証しません。統合結果を検証し、同じチェックアウトを2つのツールが同時変更することは避けます。

git worktree add -b review/worktree ../topic-review HEAD
git -C ../topic-review status --short
git -C ../topic-review branch --show-current

最初の手順

submoduleは親のパス内にある独立したリポジトリです。親の確定済みツリーは通常mode 160000のgitlinkで子コミットを記録します。親のインデックスは別コミットを準備でき、子の現在のHEADも両者と異なり得ます。.gitmodulesはパスとURLを説明しますが、選択バージョンは記録されたコミットです。

別の結果を意図して選ぶ

deps/libraryではsubmodule status、親HEADのgitlink、インデックスのgitlink、子HEADを別々に確認します。親のpullで固定コミットが変わっても子は移動しない場合があります。通常のsubmodule updateは記録済み選択を使い、--remoteはリモート追跡先を選ぶ別のバージョン更新です。単に状態を消すためには使いません。

git submodule status -- deps/library
git ls-tree HEAD -- deps/library
git ls-files --stage -- deps/library
git -C deps/library rev-parse HEAD
git --no-optional-locks -C deps/library status --short

制限と例外

Gitは複数worktreeでのsubmodule対応が不完全と記載しています。--recursiveだけで任意の組み合わせが隔離された対応環境になるわけではありません。制限と実際のcheckout・更新を確認し、独立状態が必要なら別cloneも検討します。この比較は併用を自動化する万能手順ではありません。

競合と後片付け

worktreeを外す前に未コミットファイルとブランチを確認し、無闇にディレクトリを消さずworktree removeを使います。必要なブランチや確認済みmergeは残します。依存ピンの変更前に子の手順で変更をコミット・公開し、別cloneから取得できるようにした後、親で選択を記録します。

git -C ../topic-review status --short
git worktree remove ../topic-review
git worktree list

結果を確認する

worktreeではブランチ、状態、統合結果を確認します。submoduleでは3状態を比較し、必要な利用者が子オブジェクトを取得できるか確かめます。親がクリーンでも子の作業ツリーすべてがクリーンとは限りません。どちらも未コミットファイルを永久バックアップしません。

git worktree list
git submodule status -- deps/library

よくある質問

worktreeの用途は現在のcheckoutを替えず別ブランチで作業することです。submoduleは独立して版管理される依存関係を親で固定するときに使います。更新規則の調整が負担になる場合はpackage manager、vendoring、subtree、別cloneなどを検討します。版の所有と配布方法によって選び、万能な優勝者はありません。

FluxGitで操作を確認する

FluxGitの履歴と差分の表示で、操作と関連コミットを確認してください。この例のブランチ、共有履歴、ローカルファイルのチェックは維持します。現在利用できるビルドと対応プラットフォームはダウンロードページで確認できます。