大規模なリポジトリで外部ライブラリや共通コンポーネントを別リポジトリとして再利用したいとき、Gitのsubmodule（サブモジュール）は有力な選択肢です。サブモジュールは親リポジトリから独立した履歴を保ちつつ、特定コミットを参照して一貫した状態を再現できます。本記事では基本概念から導入手順、日々の運用コマンド、つまずきやすいポイントとベストプラクティスまでをまとめます。
サブモジュールの基本概念
サブモジュールは親リポジトリに「別リポジトリの特定コミットを指すポインタ」を固定する仕組みです。実体はサブディレクトリとして展開されますが、親の履歴には「どのコミットを参照するか」だけが記録されます。これにより、親をチェックアウトした時点で必ず同じ依存バージョンが再現できるのが利点です。
追加と初期化の手順
はじめにサブモジュールを追加します。パスは展開先ディレクトリ、URLはサブモジュールのリポジトリを指定します。
# サブモジュールの追加
git submodule add https://github.com/example/lib.git libs/lib
git commit -m "Add submodule: lib"
# 既存プロジェクトをクローンする場合は再帰オプションで一括取得
git clone --recurse-submodules https://github.com/example/app.git
# すでにclone済みなら初期化と取得を明示
git submodule init
git submodule update
# ネストがある場合や最新の状態に合わせるなら再帰で
git submodule update --init --recursive
この操作で親リポジトリ直下に.gitmodulesという設定ファイルが生成され、URLとパスの対応が記録されます。
サブモジュール側の更新と親への固定
サブモジュールは独立したリポジトリとして扱います。サブモジュールのディレクトリに入り、通常どおりcommitやpullを行います。参照コミットが進んだら親側で「新しいコミットを指すように」変更が発生するため、それをコミットして固定します。
# サブモジュールへ移動して更新
cd libs/lib
git checkout main
git pull origin main
cd ../..
# 親側にはポインタの更新差分が出るのでコミットで固定
git add libs/lib
git commit -m "Bump submodule(lib) to latest on main"
チームメンバーがこの変更をpullすると、親の参照コミットは更新されます。作業開始前にサブモジュール実体を追従させるにはupdateを実行します。
git submodule update --init --recursive
ブランチ切り替え時の注意点
親リポジトリでブランチを切り替えると、サブモジュールの参照コミットもブランチごとに異なる可能性があります。意図した状態に合わせるため、切り替え後にupdateを忘れない運用が安全です。
git checkout feature/new-ui
git submodule update --init --recursive
サブモジュールを特定ブランチに常時追随させたい場合は、.gitmodulesにbranch設定を加え、update時にそのブランチの最新を取得できます。
# .gitmodules の例
[submodule "libs/lib"]
path = libs/lib
url = https://github.com/example/lib.git
branch = main
# 追随更新
git submodule update --remote --recursive
変更の取り込みとコンフリクト対処
サブモジュール内での開発は通常のGit操作と同じですが、親に反映し忘れると参照ポインタが古いままになり、他メンバーの環境で不一致が起きます。サブモジュールでcommit/pushしたら必ず親でパスの差分をaddし、固定コミットを更新する、という二段階を徹底します。コンフリクトが発生した場合は、どのコミットを指すべきかを決めて親のインデックスを書き換えます。
# 例：どちらの参照を採用するか決めたあとに add して解決
git add libs/lib
git commit
CI/CDとクローンの最適化
CIでのチェックアウトは、再帰取得と浅いクローンの使い分けが効果的です。履歴を最小限に抑えたい場合は–depthを併用します。CI環境の実行ユーザーやSSH鍵の取り扱いにも注意し、プライベートサブモジュールはデプロイ鍵やアクセストークンで認証します。
# 例：再帰かつ浅いクローン
git clone --recurse-submodules --depth 1 https://github.com/example/app.git
git -C app submodule update --init --recursive --depth 1
よくあるつまずきと回避策
サブモジュールの「変更が親に反映されない」問題は、ポインタ更新のコミット漏れが大半です。常に「サブモジュールの更新 → 親でadd/commit」の二段階を意識します。「サブモジュールの中で未コミットの変更がある」状態で親を切り替えると不整合を招きます。作業前にサブモジュールでstashやcommitを済ませましょう。「URL変更や移設」による取得失敗は.gitmodulesと.git/configの両方でURLが一致しているか確認し、必要に応じてgit submodule syncを実行します。
# URL変更時の同期
git submodule sync --recursive
git submodule update --init --recursive
ベストプラクティス
サブモジュールを採用するなら、参照はタグや特定コミットで厳密に固定する方針が安全です。リリース単位でタグを切り、親はそのタグを指すように更新すると再現性が高まります。開発中に常に最新を追い続けたい場合でも、ブランチ追随はCIでのみ行い、手元は明示的なupdateに限定すると事故が減ります。チーム規約として「サブモジュールを更新したら親で必ずポインタをコミット」「親のブランチ切り替え後はupdateを実行」「クローンは–recurse-submodulesを基本」といった手順を明文化しておくと、新規参加者の学習コストを下げられます。依存の入れ子構造が深くなるほど運用は複雑化します。深いネストは避け、複数の小モジュールが必要な場合はリポジトリの境界を再検討します。履歴を統合したい、サブプロジェクト側でGitを意識させたくないといった要件が強い場合は、subtreeやパッケージマネージャーでの配布も比較検討するとよいでしょう。
運用例のひな形
サブモジュールを更新して親に固定する一連の流れをスクリプト化しておくと、手順ミスを防げます。
# 例: scripts/update-lib.sh
#!/usr/bin/env bash
set -euo pipefail
pushd libs/lib >/dev/null
git fetch --tags origin
git checkout v1.4.2 # 参照したいタグやコミットSHA
popd >/dev/null
git add libs/lib
git commit -m "Update submodule(lib) to v1.4.2"
まとめ
サブモジュールは「外部リポジトリの特定コミットを参照して再現性を担保する」ための仕組みです。追加はgit submodule add、取得は–recurse-submodulesやupdate –init、更新はサブモジュール内で変更したのち親でポインタをコミット、ブランチ切り替え時はupdateの徹底、という運用が基本線です。タグ固定やCIでの再帰クローン、URL同期、ポインタのコミット漏れ防止といったポイントを押さえれば、ライブラリの再利用やモノレポ外の分割管理を安全に進められます。
