Git submodule のファイルが空のまま更新できない
Git submodule が空のままなら、git submodule update --init --recursive で中身を取得すれば直る。
clone だけでは取得されないので、clone 時に --recurse-submodules を付けてもよい。
公開: 更新:
git clone parent parent-clone Cloning into 'parent-clone'... done.
git submodule update --init --recursive Submodule 'vendor/sub' (/tmp/tmp.fECKOJ/sub) registered for path 'vendor/sub' Cloning into '/tmp/tmp.fECKOJ/parent-clone/vendor/sub'... done. Submodule path 'vendor/sub': checked out '382c7f242cf2e25e9d5c6b83a6002b79f9869a17'
2026-08-02 に alpine/git で実際に打って取った出力。検証環境の詳細
要約
Git submodule のディレクトリは、clone しただけでは中身が空のままになる。git clone --recurse-submodules を付けるか、後から git submodule update --init --recursive を実行すれば取得できる。
親リポジトリと submodule は別の HEAD を持つので、親を pull した後の同期も忘れやすい。
実行例
alpine/git(Git 2.54.0)環境で上記の手順を走らせると、--recurse-submodules を付けずに clone した直後は vendor/sub が空のままだった。git submodule update --init --recursive を実行した時点で vendor/sub への登録・clone・チェックアウトが完了し、終了コード 0 で lib.txt が取得できた。
$ git clone parent parent-clone
Cloning into 'parent-clone'...
done.$ ls -A parent-clone/vendor/sub$ git submodule update --init --recursive
Submodule 'vendor/sub' (/tmp/tmp.fECKOJ/sub) registered for path 'vendor/sub'
Cloning into '/tmp/tmp.fECKOJ/parent-clone/vendor/sub'...
done.
Submodule path 'vendor/sub': checked out '382c7f242cf2e25e9d5c6b83a6002b79f9869a17'
$ echo $?
0$ ls -A vendor/sub
.git
lib.txt$ cat vendor/sub/lib.txt
hello from submodule— 2026-08-02 時点の出力
検証環境2026-08-02 検証
- 検証日
- 実行環境
alpine/git
この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。
解決策
1. 初回 clone でまとめて取得
git clone --recurse-submodules https://example.com/parent.git--recurse-submodules を付けると、親 clone 完了後に自動で submodule init + submodule update が走る。
2. 既存 clone を初期化する
git submodule update --init --recursive--init は .gitmodules を読み、.git/config に submodule を登録する。--recursive を付けると、ネストした submodule にも適用される。
詳しくは git-submodule 公式ドキュメント(新しいタブで開く) に書かれている。
3. 親の pull とセットで実行
git pull
git submodule update --init --recursive親の commit が submodule の新しい SHA を指していると、git status で modified content と表示されることがある。update で submodule の HEAD を親が指す SHA に揃える。
4. URL が変わったとき
git submodule sync --recursive
git submodule update --init --recursivesync は、.gitmodules の url 行を .git/config 側に反映する。
リポジトリ移行後にこの 2 行を流しておけば、古い URL のまま fetch することがなくなる。
さらに踏み込んだ運用は Pro Git の Submodules 章(新しいタブで開く) が詳しい。
よくある原因
- clone 時にオプションを指定していない。
git clone <url>だけ実行すると.gitmodulesに書かれた submodule の中身は取得されず、ディレクトリだけが空の状態で作られる。 - submodule の初期化を忘れている。
後から submodule が追加されたリポジトリでgit pullしても submodule ディレクトリは空のままなので、git submodule update --initが必要になる。 - 親リポジトリを更新したあと、submodule を追従させていない。
親が submodule の新しいコミットを指していても、ローカルの submodule HEAD は古いコミットのままなので、git submodule updateで追従させる必要がある。 - URL の変更が反映されていない。
.gitmodulesで submodule の URL が変わっても、ローカルの.git/config側は古い URL を保持しているため、fetch 先が間違っている。