Gitで複数のリポジトリをまたいで開発していると、次のような要件が出てくることがあります。
- 共通ライブラリを別リポジトリとして管理したい
- フロントとバックエンドで一部のコードを共有したい
- 外部のライブラリや社内共通モジュールを、特定バージョンで固定して使いたい
こうしたときに選択肢に上がるのが git submodule です。
ただ、git submodule は便利な反面、最初は少し理解しづらい仕組みでもあります。
- 普通のディレクトリと何が違うのか
- cloneしたのに中身がないのはなぜか
- submoduleを更新したのに他の人に反映されないのはなぜか
- 親リポジトリとサブモジュールのbranch名は揃える必要があるのか
この記事では、git submodule の基本から実務上の注意点まで、実例付きで整理します。
Git submoduleとは
git submodule は、別のGitリポジトリを、自分のリポジトリの中で参照する仕組みです。
たとえば次のような構成を考えます。
- 親リポジトリ:
myapp - サブモジュール:
shared-lib
myapp/
├── backend/
├── frontend/
└── packages/
└── shared-lib/
見た目は packages/shared-lib という普通のフォルダに見えますが、実体は別のGitリポジトリです。
ここで大事なのは、親リポジトリはサブモジュールの中身すべてを直接管理しているわけではなく、
「サブモジュールのどのコミットを使うか」 を記録している、という点です。
submoduleを使うと何がうれしいのか
git submodule が向いているのは、次のようなケースです。
- 共通機能を独立したリポジトリとして切り出したい
- 複数プロジェクトで同じモジュールを使い回したい
- 外部OSSや社内ライブラリを、特定コミットで固定したい
- リポジトリの責務を明確に分けたい
逆に、チーム全体でできるだけ単純な運用にしたい場合は、subtree やパッケージ管理のほうが向いていることもあります。
まずは最重要ポイントだけ先に
git submodule を理解するうえで、最初にこの1点だけ覚えると整理しやすくなります。
親リポジトリが管理しているのは、サブモジュールのbranch名ではなく、特定のcommit hashである
つまり親リポジトリは、サブモジュールに対して次のような情報を持っています。
packages/shared-libはabc1234のコミットを使う
この前提を押さえておくと、後で出てくる detached HEAD や branch 名の疑問も理解しやすくなります。
submoduleの追加方法
親リポジトリにサブモジュールを追加するには、次のコマンドを使います。
git submodule add https://github.com/example/shared-lib.git packages/shared-lib
git commit -m "Add shared-lib as submodule"
これで packages/shared-lib に別リポジトリが追加されます。
追加すると何が起きるか
submodule を追加すると、主に次の2つが作られます。
1. .gitmodules
[submodule "packages/shared-lib"]
path = packages/shared-lib
url = https://github.com/example/shared-lib.git
これは、submodule のパスやURLを管理する設定ファイルです。
2. 親リポジトリ内の特殊なエントリ
親リポジトリ上では packages/shared-lib は普通のフォルダではなく、
「どのコミットを指しているか」 を持つ特殊なエントリとして記録されます。
clone時の注意点
submodule入りのリポジトリを普通に clone すると、サブモジュールの中身が取得されないことがあります。
git clone https://github.com/example/myapp.git
cd myapp
この状態だと、packages/shared-lib が空、または未初期化の状態になっている場合があります。
そのため、clone後に次を実行します。
git submodule update --init --recursive
最初からまとめて取得するなら、こちらのほうが便利です。
git clone --recurse-submodules https://github.com/example/myapp.git
実務ではこちらを使うことが多いです。
submoduleの基本的な使い方
ここでは、親リポジトリ myapp とサブモジュール shared-lib を例に、典型的な流れを見ます。
1. submoduleを追加する
git submodule add git@github.com:example/shared-lib.git packages/shared-lib
git commit -m "Add shared-lib submodule"
2. 他のメンバーが取得する
git clone --recurse-submodules git@github.com:example/myapp.git
すでに clone 済みなら、次でOKです。
git submodule update --init --recursive
3. submodule内で修正する
submodule は別リポジトリなので、中に入って普通のGit操作をします。
cd packages/shared-lib
git checkout main
git pull
修正後は通常どおりコミット・プッシュします。
git add .
git commit -m "Fix helper logic"
git push origin main
4. 親リポジトリ側で参照先の更新をコミットする
ここが git submodule で最も大事なポイントです。
submodule 側で commit / push しただけでは、親リポジトリ側にはまだ反映されていません。
親から見ると、変わったのは「サブモジュールが指すコミット」です。
親リポジトリに戻って、submodule の参照更新をコミットします。
cd ../..
git status
たとえば次のように表示されます。
modified: packages/shared-lib (new commits)
そのうえで、親側でもコミットします。
git add packages/shared-lib
git commit -m "Update shared-lib to latest commit"
git push
つまり、更新時は次の2段階が必要です。
- submodule 側で commit / push
- 親側で submodule の参照更新を commit / push
この親側のコミットを忘れるのが、最も多いハマりどころです。
よくある運用シナリオ
たとえば Laravel アプリに共通ライブラリを submodule として組み込んでいるケースを考えます。
- 親:
myapp - サブモジュール:
packages/shared-lib
構成はこんなイメージです。
myapp/
├── app/
├── routes/
├── resources/
└── packages/
└── shared-lib/
shared-lib にバグが見つかり、それを直して親アプリへ反映する流れは次のようになります。
サブモジュール側
cd packages/shared-lib
git checkout main
# コード修正
git add .
git commit -m "Fix date formatter bug"
git push origin main
親リポジトリ側
cd ../..
git add packages/shared-lib
git commit -m "Bump shared-lib"
git push origin main
他メンバー側
git pull
git submodule update --init --recursive
これで親リポジトリが指している submodule のコミットに揃います。
親リポジトリとサブモジュールのbranch名は一致する必要があるのか
ここは非常によく聞かれるポイントです。
結論からいうと、一致する必要はありません。
たとえば次のような状態でも問題ありません。
- 親リポジトリ:
main - サブモジュール:
develop
あるいは
- 親リポジトリ:
feature/login - サブモジュール:
feature/api-change
なぜbranch名を揃えなくてもよいのか
理由は先ほどの原則どおりです。
親リポジトリが管理しているのは、サブモジュールの branch名ではなくcommit hash です。
つまり親は、次のような情報を持っています。
packages/shared-libはf0e1d2cを使う
そのコミットがサブモジュールの main 上にあるのか、develop 上にあるのかは、親から見ると本質ではありません。
具体例
たとえば、
- 親:
main - サブモジュール:
develop
という状態で、サブモジュール側の develop で修正を行ったとします。
cd packages/shared-lib
git checkout develop
git add .
git commit -m "Fix helper logic"
git push origin develop
その後、親で参照更新をコミットします。
cd ../..
git add packages/shared-lib
git commit -m "Update shared-lib"
git push origin main
このとき親の main が保持するのは、サブモジュールの develop というbranch名ではなく、
その時点の特定コミットです。
そのため、branch名が一致していなくても問題ありません。
技術的には不要、運用上は揃えることもある
branch名の一致はGitの仕様上は不要です。
ただし、チーム運用では揃えることがあります。
たとえば次のようなケースです。
- 親:
feature/order-api - サブモジュール:
feature/order-api
こうしておくと、親とサブモジュールの変更が対応関係として追いやすくなります。
レビューや障害調査でも把握しやすいです。
つまり整理すると、
- 技術的には一致不要
- 運用上わかりやすくするために揃えることはある
という考え方になります。
よくハマるポイント
git submodule では、branch名の一致よりも、次のポイントのほうが重要です。
1. submoduleの変更をpushしたのに他の人に反映されない
原因のほとんどはこれです。
- submodule 側では commit / push した
- でも親リポジトリ側で
git add submodule-path && git commitをしていない
submodule は親から見ると「フォルダ」ではなく、コミット参照です。
そのため、親側でも更新コミットが必要です。
2. cloneしたらsubmoduleの中身がない
普通に clone しただけだと中身が取れていないことがあります。
git clone ...
対策は次のどちらかです。
git clone --recurse-submodules ...
または
git submodule update --init --recursive
3. submoduleの中でdetached HEADになる
これはよくあります。
git submodule update をすると、親が指定した特定コミットに移動するため、
submodule 内で branch ではなく detached HEAD になることがあります。
確認するとこんな状態です。
HEAD detached at abc1234
この状態でも参照としては正しいです。
ただし、submodule の中で新たに開発したい場合は branch に切り替えます。
cd packages/shared-lib
git checkout main
git pull
4. 親でpullしたのにsubmoduleが古いまま
親を pull したあと、submodule 側も更新する必要があります。
git pull
git submodule update --init --recursive
これを忘れると、親の最新状態に見えても submodule が古いまま残ることがあります。
5. 未pushのsubmoduleコミットを親が参照してしまう
これはCIや他メンバー環境で事故りやすいポイントです。
たとえば submodule でローカルコミットしたあと、その commit を push する前に親側で参照更新をコミットすると、
他の人はその commit を取得できません。
正しい順序は必ずこちらです。
# submodule側
git push
# 親側
git add packages/shared-lib
git commit -m "Update submodule pointer"
git push
よく使うコマンドまとめ
submoduleを追加する
git submodule add <repo-url> <path>
clone時にsubmoduleもまとめて取得する
git clone --recurse-submodules <repo-url>
clone後にsubmoduleを初期化する
git submodule update --init --recursive
submoduleの状態を確認する
git submodule status
たとえば次のように表示されます。
a1b2c3d4e5f6g7h8i9j0 packages/shared-lib (heads/main)
submodule側を更新する
cd path/to/submodule
git checkout main
git pull
更新後、親側でも参照先のコミットを保存します。
cd ..
git add path/to/submodule
git commit -m "Update submodule"
branch追従用の設定を使う
.gitmodules に branch を書くこともできます。
[submodule "packages/shared-lib"]
path = packages/shared-lib
url = git@github.com:example/shared-lib.git
branch = main
この設定があると、次で追従更新しやすくなります。
git submodule update --remote
ただし、最終的に親リポジトリが保持するのはやはり branch 名ではなく、
更新後のコミット参照です。
submoduleとsubtreeの違い
混同しやすいので、ざっくり整理しておきます。
submodule
- 別リポジトリとして独立管理できる
- 親は「どのコミットを使うか」を保持する
- 履歴が完全に分かれる
- 運用はやや難しめ
subtree
- 親リポジトリに中身を取り込む形になる
- clone が楽
- submodule よりチーム運用しやすいことが多い
- 別プロジェクト感はやや弱い
使い分けの目安としては、
- 明確に別リポジトリとして独立管理したい → submodule
- チーム全体でなるべく簡単に扱いたい → subtree も検討
という形がわかりやすいです。
実務でのおすすめ運用
git submodule は仕組みを理解していれば便利ですが、チーム開発ではルールを決めておくとかなり安定します。
おすすめは次のような運用です。
- clone は
--recurse-submodulesを基本にする - README に submodule 初期化手順を書く
- submodule 更新時は、親側のコミットも必須にする
- submodule 内で作業するときは branch 状態を確認する
- CI でも submodule の初期化を忘れない
たとえば GitHub Actions では次のようにします。
- uses: actions/checkout@v4
with:
submodules: recursive
最小サンプルだけで覚えるならこれ
追加する人
git submodule add https://github.com/example/shared-lib.git lib/shared-lib
git commit -m "Add submodule"
使う人
git clone --recurse-submodules https://github.com/example/myapp.git
更新する人
cd lib/shared-lib
git checkout main
git pull
# 修正
git add .
git commit -m "Fix"
git push
cd ../..
git add lib/shared-lib
git commit -m "Update submodule pointer"
git push
追従する人
git pull
git submodule update --init --recursive
まとめ
git submodule は、親リポジトリの中で別リポジトリを特定コミットで参照する仕組みです。
理解のポイントは次の3つです。
- submodule は普通のフォルダではなく別リポジトリ
- 親が管理しているのは branch 名ではなく commit hash
- 更新したら submodule 側だけでなく、親側のコミットも必要
また、よくある疑問である
親リポジトリとサブモジュールのbranch名は揃える必要があるのか
については、結論として 不要 です。
ただし運用上わかりやすくするために、チームルールとして揃えるのは有効です。
おわりに
git submodule は便利ですが、通常の単一リポジトリ運用とは少し考え方が違います。
特に重要なのは、親はサブモジュールのbranchではなくコミットを指している、という理解です。
ここが腹落ちすると、clone時の挙動、更新時の手順、detached HEAD、branch名の疑問まで一気に整理しやすくなります。
submodule をこれから導入する方や、すでに使っていて運用に少しモヤモヤしていた方の参考になればうれしいです。