$Git Simulator
壊しても大丈夫。全部ブラウザの中だけで動いています

worktree と submodule

少し発展的な 2 つの機能を紹介します。名前は似た雰囲気ですが、目的はまったく違います。

機能ひとことで使う場面
worktree1 つのリポジトリで、複数のブランチを 同時に別フォルダで 開く作業中に急ぎのバグ修正が入った、レビュー用に別ブランチを動かしたい
submoduleリポジトリの中に、別のリポジトリ を組み込む共通ライブラリやテーマを複数のプロジェクトで使い回したい

どちらもこのシミュレーターには無い、本物の Git の機能です。

worktree ― ブランチごとに作業フォルダを分ける

どんなときに便利?

feature ブランチで作業している途中に「本番のバグを今すぐ直して」と頼まれたとします。普通は次のどちらかです。

  • 作業中の変更を git stash して main に switch する
  • 中途半端な状態で一度コミットする

worktree を使うと、今のフォルダはそのままに、別のフォルダで main を開けます。ビルドや依存のインストールをやり直す必要もなく、両方を同時に動かせます。

基本の使い方

# ../hotfix フォルダに、新しいブランチ hotfix/login を作って開く
git worktree add -b hotfix/login ../hotfix main

cd ../hotfix
# …修正・コミット・push…

cd ../my-app
git worktree list                 # worktree の一覧
git worktree remove ../hotfix     # 用が済んだら片付ける

既存のブランチを開くなら git worktree add ../review feature/search のように書きます。

仕組みと注意点

  • すべての worktree は 同じ .git の中身(コミットやブランチ)を共有 しています。clone し直すのと違い、ディスクも節約でき、片方でしたコミットはもう片方からもすぐ見えます
  • 同じブランチを 2 つの worktree で同時に開くことはできません(混乱を防ぐため)
  • worktree のフォルダを手で削除した場合は git worktree prune で記録を掃除します
  • node_modules などの未追跡ファイルは共有されないので、必要なら各フォルダでインストールします

submodule ― リポジトリの中に別のリポジトリを入れる

どんなときに使う?

  • 複数のプロジェクトで共通のライブラリやデザインテーマを使っている
  • 外部のリポジトリを、特定のバージョンに固定して 取り込みたい

submodule は、親リポジトリに「この場所には、あのリポジトリの、このコミットを置く」という参照を記録します。中身のファイルそのものを親にコピーするわけではありません。

追加する

git submodule add <リポジトリの URL> libs/common
git commit -m "共通ライブラリを submodule として追加"

すると次の 2 つが記録されます。

  • .gitmodules — submodule のパスと URL の対応表
  • libs/common — 中身ではなく「どのコミットを使うか」という参照

submodule を含むリポジトリを clone する

普通に clone すると、submodule のフォルダは 空のまま です。

git clone --recurse-submodules <URL>       # clone と同時に中身も取得

# すでに clone してしまったなら
git submodule update --init --recursive

「clone したのにフォルダが空」というのは submodule でよくあるつまずきです。

更新する

submodule は 特定のコミットに固定 されています。新しいバージョンを使うには、明示的に更新して親でコミットします。

git submodule update --remote libs/common  # submodule を追跡先ブランチの最新にする
git status                                 # libs/common が modified になる
git add libs/common
git commit -m "共通ライブラリを更新"

チームメイトがこの更新を pull したら、git submodule update で手元の submodule も合わせます。

git pull
git submodule update --init --recursive

注意点

  • submodule の中は 独立したリポジトリ です。中でコミットしたら、その submodule のリモートに push してから、親で参照を更新してコミットする、という 2 段階になります
  • submodule の中は detached HEAD になっていることが多く、そのままコミットすると迷子になりやすいです。中で作業するときは先にブランチに switch します
  • 親の push を忘れても、submodule の push を忘れても、チームメイトの手元で取得に失敗します

代わりの選択肢

submodule は便利ですが、扱いに慣れが必要です。目的によっては別の方法の方が楽なこともあります。

方法向いている場面
パッケージマネージャ(npm、pip など)ライブラリを配布・利用するなら第一候補
モノレポ関連するプロジェクトを 1 つのリポジトリにまとめて管理する
git subtree別リポジトリの内容を親の履歴に取り込む。clone 時の追加操作が不要

まとめ

  • worktree は「同じリポジトリを、ブランチごとに別のフォルダで同時に開く」機能。stash や作業の中断を減らせる
  • submodule は「別のリポジトリを、特定のコミットに固定して組み込む」機能。clone と更新に独特の手順がある