サブモジュールとは？
Git サブモジュールは、ある Git リポジトリを別の Git リポジトリの一部として組み込む機能です。例えば、フロントエンドプロジェクトに API 仕様書のリポジトリを組み込む場合などに使用されます。
VS Code での表示
VS Code でサブモジュールフォルダを確認すると、フォルダ名の右側に 「S」 の文字が表示されます。これは Submodule（サブモジュール） であることを示すマーカーです。
- S: サブモジュール
- M: 変更あり
- U: 未追跡ファイル
- +: 新規ファイル
.gitmodules ファイルの役割
.gitmodules ファイルは、サブモジュールの設定を管理するファイルです。プロジェクトルートに自動生成されます。
[submodule "api"]
path = api
url = git@github.com:example/example-api.git
設定項目の説明
-
[submodule "api"]: サブモジュール名 -
path: サブモジュールを配置するローカルパス -
url: サブモジュールのリモートリポジトリ URL
サブモジュール追加の手順
1. サブモジュールを追加
# サブモジュールを追加
git submodule add git@github.com:example/example-api.git api
# 変更をコミット
git add .gitmodules api
git commit -m "Add API submodule"
2. サブモジュールの状態確認
# サブモジュールの状態確認
git submodule status
# 出力例：
# -38175b29caaadfe7d89d5d57bd68ec52c2651a2a api # 未初期化
# 38175b29caaadfe7d89d5d57bd68ec52c2651a2a api # 正常
既存プロジェクトでサブモジュールを利用する手順
サブモジュール設定されているプロジェクトをクローンしてきたら、まずはサブモジュールの初期化・更新が必要になる。
# サブモジュールを初期化・更新
git submodule update --init --recursive
この際、.gitmodules ファイルに書かれている url の接続方式を取る。SSH 接続の場合、鍵がないとエラーが起きる。
エラーが起きたら以下の手順で解決すること。
パターン 1: SSH 鍵が存在しない場合
# SSH鍵の存在確認
ls -la ~/.ssh/
# SSH鍵が存在しない場合は新規作成
ssh-keygen -t ed25519 -C "luck@imai.am" -f ~/.ssh/id_ed25519
# 公開鍵を確認・コピーしてGitHubに登録
cat ~/.ssh/id_ed25519.pub
# GitHub接続テスト
ssh -T git@github.com
その後、Settings > SSH and GPG keys > New SSH key から SSH 鍵を GitHub に登録する。
パターン 2: SSH 鍵は存在するが agent に追加されていない場合
# SSH鍵の存在確認
ls -la ~/.ssh/
# GitHub接続テスト（失敗する場合）
ssh -T git@github.com
# SSH鍵をagentに追加
ssh-add ~/.ssh/id_ed25519
# 再度接続テスト
ssh -T git@github.com
サブモジュールの日常的な管理
サブモジュールの更新
# サブモジュールを最新に更新
git submodule update --remote
# 特定のサブモジュールのみ更新
git submodule update --remote api
サブモジュール内での作業
# サブモジュールディレクトリに移動
cd api
# ブランチ作成・切り替え
git checkout -b feature/new-api
# 変更後、サブモジュール内でコミット
git add .
git commit -m "Update API spec"
git push origin feature/new-api
メインプロジェクトでサブモジュールの変更を反映
# メインプロジェクトに戻る
cd ..
# サブモジュールの変更をメインプロジェクトに反映
git add api
git commit -m "Update API submodule"
git push origin main
実用例: API 仕様書の管理
フロントエンドプロジェクトで API 仕様書を管理する場合：
# API仕様書リポジトリをサブモジュールとして追加
git submodule add https://github.com/example/api-specs.git api
# Orvalなどのコード生成ツールでAPI型定義を生成
yarn api:generate
これにより、API 仕様書の変更を自動的にフロントエンドプロジェクトに反映できます。
以上です。
Discussion