Git
PR

git submoduleの使い方:追加・更新・削除とcloneで中身が空のときの対処

git submoduleの使い方:追加・更新・削除とcloneで中身が空のときの対処
hr
記事内に商品プロモーションを含む場合があります

チームで作った共通のライブラリを、いくつものアプリで使い回したい。そんなときに使える Git の仕組みが git submodule(ギット サブモジュール)です。別のリポジトリを、自分のリポジトリの中のフォルダーとして「特定のコミット」で取り込めます。

この記事では、追加・clone・更新・削除の手順と、「親でコミットし忘れて、ほかの人の手元が古いまま」などサブモジュールならではのつまずきを、実際の実行結果つきで説明します。

コマンドと実行結果は、Windows 11 の Git Bash(git --version の結果は git version 2.49.0.windows.1)で確かめたものです。練習用のリポジトリはすべて手元のフォルダーに作り、結果に出てくるフォルダーの場所は、前半を C:/work に置き換えて短くしています。コミット ID(1decaa2 のような英数字)は、実行するたびに違う値になります。

この記事で使うコマンド

やりたいことコマンド
サブモジュールを追加するgit submodule add URL フォルダー
サブモジュールごと clone するgit clone –recurse-submodules URL
clone したあと、空のサブモジュールに中身を入れるgit submodule update –init
記録されたコミットと今の状態を見るgit submodule status
子の変化をコミットの一覧で見るgit diff –submodule
子を取り込み元の最新にするgit submodule update –remote
すべての子で同じコマンドを実行するgit submodule foreach ‘コマンド’
サブモジュールを削除するgit rm フォルダー

git submodule とは?

サブモジュールは、あるリポジトリの中に、別のリポジトリを丸ごと入れる仕組みです。子は自分の履歴を持ったままです(公式ドキュメント gitsubmodules より)。取り込む側を親リポジトリ(公式の用語では superproject)、取り込まれる側を子(サブモジュール)と呼ぶことにします。

いちばん大事なのは、親が記録しているのは、子の「コミット ID」だけだという点です。子のファイル(下の例では util.py)の中身は、親の履歴には入りません。親は「libs/mylib のフォルダーには、mylib のコミット 1decaa2 を置く」とだけ覚えています。子のリポジトリに新しいコミットが増えても、親でコミットし直すまでは 1decaa2 のままです。

親リポジトリ my-app のコミットでは、main.py はファイルの中身を、libs/mylib は 160000 commit 1decaa2 というコミット ID だけを記録し、その ID が子リポジトリ mylib の 3 つのコミットのうち 1decaa2 を指している。
図 1:親は子のコミット ID だけを記録する

そのため「動作を確かめた版に固定して使いたい」場面に向いています。逆に、いつも最新を使いたいなら、更新のたびに親でコミットする手間がかかります。

準備:練習用のリポジトリ

手元のフォルダーに 2 つのリポジトリを作って使います(本当は GitHub などにある共有のリポジトリを使う場面です)。子にする mylib は util.py に greet 関数があるライブラリで、コミットは「81ff1b6 greet関数を追加」「1decaa2 READMEを追加」の 2 つです。親にする my-app は main.py で from libs.mylib.util import greet と読み込むアプリです。

サブモジュールを追加する(git submodule add)

書き方は git submodule add 取り込み元のURL 置くフォルダー です。GitHub なら clone 用の URL を書きます。ここでは my-app の中で、手元の mylib を libs/mylib に追加します。

git submodule add C:/work/mylib libs/mylib

手元のフォルダーから追加すると「transport ‘file’ not allowed」

手元のフォルダー(ローカルのパス)を取り込み元にすると、次のエラーで止まりました。

Cloning into 'C:/work/my-app/libs/mylib'...
fatal: transport 'file' not allowed
fatal: clone of 'C:/work/mylib' into submodule path 'C:/work/my-app/libs/mylib' failed

これは Git 2.38.1 のセキュリティ修正(CVE-2022-39253)で、設定 protocol.file.allow の既定値が user に変わったためです(リリースノートで確認)。user は「ユーザーが直接実行したときだけ使える」という意味で(git-config のドキュメントより)、サブモジュールの clone のように Git が内部で行う取得では手元のパスが使えません。https や ssh の URL は既定で使えるので、GitHub などから追加するときはこのエラーは出ません。

練習で手元のフォルダーを使うときは、設定を変えずに、そのコマンドのときだけ許可する -c を付けます。

git -c protocol.file.allow=always submodule add C:/work/mylib libs/mylib
Cloning into 'C:/work/my-app/libs/mylib'...
done.

注意:この許可を git config --global でずっと有効にするのはやめましょう。上の修正は、悪意のあるリポジトリから身を守るためのものです。

追加したあとの状態

git status を見ると、new file: .gitmodules と new file: libs/mylib の 2 つがステージ(コミットの準備)されています。

libs/mylib には mylib が clone されていて、util.py と README.md があります。git commit -m "mylibをサブモジュールとして追加" でコミットすると、結果の最後に create mode 160000 libs/mylib と表示されました。この 160000 が「ここはコミットを指す特別な項目」という印です(次で説明します)。

.gitmodules の中身

.gitmodules は、親リポジトリのいちばん上に作られるテキストファイルです。中身は次のとおりでした。

[submodule "libs/mylib"]
	path = libs/mylib
	url = C:/work/mylib

[submodule "libs/mylib"] はサブモジュールの名前(--name を付けなければ置いたフォルダーと同じ)、path は親のどこに置くか、url はどこから clone するかです。公式ドキュメント(gitmodules)では、path と url が必須の項目です。このファイルもコミットされるので、ほかの人が clone したときに「どこから何を取ってくるか」が分かります。書き方は git config の設定ファイルと同じ形式です。

親が記録するのはコミット ID だけ

親のコミットに何が入っているかを git ls-tree で確かめます。

git ls-tree HEAD libs/
160000 commit 1decaa263cb6fd9ddc8f2d9918fdeb2742379a76	libs/mylib

ふつうのファイルは blob、フォルダーは tree と表示されますが、libs/mylib は commit で、mylib のコミット 1decaa2 の ID が書かれているだけです。Pro Git では、モード 160000 を「サブフォルダーやファイルではなく、コミットをフォルダーの項目として記録する特別なモード」と説明しています。差分で見ても、libs/mylib の中身は +Subproject commit 1decaa26… の 1 行だけです。

今の状態は git submodule status でも確かめられます。

git submodule status
 1decaa263cb6fd9ddc8f2d9918fdeb2742379a76 libs/mylib (heads/main)

先頭の 1 文字は状態で、公式ドキュメントによると - は「まだ初期化されていない」、+ は「子で開いているコミットが、親の記録と違う」、U は「マージの衝突がある」、空白は親の記録どおりです。

clone したらフォルダーが空(git submodule update –init)

ほかの人が my-app をふつうに git clone すると、libs/mylib フォルダーはできますが、中身は空です。この状態で py main.py を実行すると、ModuleNotFoundError: No module named 'libs.mylib.util' で止まりました。git submodule status は先頭が「-」(未初期化)です。

-1decaa263cb6fd9ddc8f2d9918fdeb2742379a76 libs/mylib

中身を入れるには、clone したフォルダーの中で次のコマンドを実行します。--init は「未初期化のサブモジュールを初期化してから更新する」という意味です。

git submodule update --init
Submodule 'libs/mylib' (C:/work/mylib) registered for path 'libs/mylib'
Cloning into 'C:/work/colleague/libs/mylib'...
done.
Submodule path 'libs/mylib': checked out '1decaa263cb6fd9ddc8f2d9918fdeb2742379a76'

(手元のフォルダーが取り込み元なので、実際には -c protocol.file.allow=always を付けて実行しました。)最後の行のとおり、親が記録しているコミット 1decaa2 が取り出され、py main.py も Hello, my-app と表示されました。サブモジュールの中にさらにサブモジュールがあるときは --recursive も付けます。

最初から一緒に取ってくる(git clone –recurse-submodules)

サブモジュールがあると分かっているなら、clone のときに --recurse-submodules を付ければ 1 回で済みます。

git clone --recurse-submodules C:/work/my-app colleague2
Cloning into 'colleague2'...
done.
Submodule 'libs/mylib' (C:/work/mylib) registered for path 'libs/mylib'
Cloning into 'C:/work/colleague2/libs/mylib'...
done.
Submodule path 'libs/mylib': checked out '1decaa263cb6fd9ddc8f2d9918fdeb2742379a76'

(ここでも -c protocol.file.allow=always を付けて実行しました。)

子を新しいコミットに更新する

mylib の作者が、あいさつの最後に「!」を付けるコミット 79a7325 を追加しました。my-app でもこの版を使うまでの流れは、次の 3 段階です。

1 子の中で git pull、2 親で git add と git commit、3 ほかの人が git pull と git submodule update、の 3 段階が矢印でつながっている。2 を忘れるとほかの人は古いコミットのまま。
図 2:子を更新して、親でコミットし直す流れ

1. 子のフォルダーの中で更新する

サブモジュールのフォルダーは、それ自体がふつうのリポジトリです。中に移動して git pull すれば、取り込み元の新しいコミットが入ります(pull の意味は「Gitのリモートの基本」で説明しています)。

cd libs/mylib
git pull
From C:/work/mylib
   1decaa2..79a7325  main       -> origin/main
Updating 1decaa2..79a7325
Fast-forward
 util.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

2. 親で変化を確かめてコミットする

cd ../.. で my-app に戻り、git status を見ます。

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   libs/mylib (new commits)

「libs/mylib に新しいコミットがある」という意味です。ふつうの git diff ではコミット ID が変わることしか分からないので、--submodule を付けて子のコミットの一覧で表示します。

git diff --submodule
Submodule libs/mylib 1decaa2..79a7325:
  > あいさつに!を付ける

「>」は増えるコミットです。設定 diff.submodule を log にすると、git diff だけでこの形になります(既定は short)。

内容を確かめたら、親でコミットします。ふつうのファイルと同じく git add してから commit します。

git add libs/mylib
git commit -m "mylibを更新(あいさつに!を付ける)"

結果は [main 440f993] mylibを更新(あいさつに!を付ける) と 1 file changed で、変わったのは libs/mylib に記録したコミット ID だけです。

3. ほかの人は pull のあと git submodule update

ほかの人(colleague)が my-app を git pull すると、親は 440f993 になります。ところが、子のフォルダーの中身は古い 1decaa2 のままです。git status には modified: libs/mylib (new commits) と出て、git diff --submodule は次のように「巻き戻し(rewind)」と表示しました。

Submodule libs/mylib 79a7325..1decaa2 (rewind):
  < あいさつに!を付ける

「親の記録は 79a7325 なのに、子は 1decaa2 に戻っている」という意味です。ここで git commit -a などで libs/mylib をコミットしてしまうと、せっかくの更新を古い版に戻すコミットになってしまいます。子を親の記録に合わせるには、次のコマンドを実行します。

git submodule update
Submodule path 'libs/mylib': checked out '79a73258358c53ca3730c5f03d5432620bb40080'

git pull --recurse-submodules と書けば、pull のあとに子の取り出しまで 1 回で行われました(結果の最後に上と同じ checked out '79a7325…' の行が出ます)。

取り込み元の最新にまとめて更新する(–remote)

子のフォルダーに入らずに、取り込み元の最新のコミットにしたいときは --remote を付けます。mylib に「e3bcc83 bye関数を追加」が増えた状態で、my-app で実行しました。

git submodule update --remote
From C:/work/mylib
   79a7325..e3bcc83  main       -> origin/main
Submodule path 'libs/mylib': checked out 'e3bcc834420ae1662cdfe840552463135acc1a1b'

(手元のフォルダーなので -c protocol.file.allow=always を付けて実行しました。)このあとも、親で add と commit をするのは同じです。

子が detached HEAD になる理由と注意

上の --remote のあと、libs/mylib の中で git status を実行すると、1 行目は HEAD detached at e3bcc83 でした。detached HEAD は「どのブランチにもいない状態」です。

理由は、git submodule update がブランチではなく、親が記録したコミットそのものを取り出すからです。公式ドキュメントにも、既定の checkout の方法では「親に記録されたコミットが、子で detached HEAD として取り出される」とあります。update --init した colleague 側でも HEAD detached at 1decaa2 でした(git submodule add した直後は main ブランチにいました)。

読むだけなら問題ありませんが、この状態で子を編集してコミットすると、コミットが行方不明になりやすいです。試しに、detached HEAD のまま README.md を直してコミット e55306f を作り、親で git submodule update を実行しました。

Submodule path 'libs/mylib': checked out 'e3bcc834420ae1662cdfe840552463135acc1a1b'

警告は何も出ずに、子は e3bcc83 に戻りました。e55306f はどのブランチにも属していないので git log にも出ませんが、子の中の git reflog(HEAD が動いた記録)には e55306f HEAD@{1}: commit: READMEに説明を追加 と残っていました。

子のフォルダーで作業するときは、先にブランチに切り替えるのが安全です。

git switch main

今回は main が古かったので git merge --ff-only origin/main で進め、行方不明だった e55306f を git cherry-pick e55306f で main に取り込みました(新しいコミット a8f2f77 になりました)。ブランチの操作は「Gitのブランチの使い方」を参照してください。

すべての子で同じコマンドを実行する(git submodule foreach)

サブモジュールが複数あるときは、foreach で 1 つずつ同じコマンドを実行できます。2 つ目の子 libs/mylog を追加した状態で実行しました。

git submodule foreach 'git log --oneline -1'
Entering 'libs/mylib'
a8f2f77 READMEに説明を追加
Entering 'libs/mylog'
51a15b7 log関数を追加

コマンドは「’」で囲みます。中では $sm_path(置いたフォルダー)や $sha1(親が記録したコミット)などの変数も使えます。Pro Git では git submodule foreach 'git stash' の例が紹介されています。

サブモジュールを削除する

公式ドキュメント(gitsubmodules)では、サブモジュールの削除は git rm してコミットする、と説明されています。libs/mylog を削除します。

git rm libs/mylog
rm 'libs/mylog'

.gitmodules から mylog の 3 行が消え、その変更と libs/mylog の削除がステージされました。あとは git commit -m "mylogを削除" でコミットします。

ただし、子のリポジトリの本体は残ります。サブモジュールの Git の情報は、親の .git/modules/ の下に置かれていて(子のフォルダーにある .git は、そこを指す 1 行のファイルです)、git rm のあとも .git/modules/libs/mylog は残っていました。公式ドキュメントによると、これは過去のコミットを取り出したときに、もう一度取ってこなくても済むようにするためで、「完全に消したいときは $GIT_DIR/modules/<name>/ を手で削除する」とあります。また、.git/config にも submodule.libs/mylog.url などの設定が残っていました。

この残りがあると、同じ場所に追加し直すときに止められます(後述)。.git/modules の下を消すときは、消すフォルダーの名前をよく確かめてください。.git の中を間違えて消すと、リポジトリが壊れます。

なお、git submodule deinit libs/mylib は削除ではなく「この PC では使わない」操作です。子のフォルダーが空になるだけで、親の履歴や .gitmodules は変わらず、git submodule update --init で元に戻せます。

よくある間違い・トラブル

親でコミットし忘れて、ほかの人の手元が古いまま

my-app で git submodule update --remote して子を e3bcc83 にしたあと、親でコミットせずに colleague 側で git pull すると、結果は Already up to date. で、子は 79a7325 のままでした。子を更新しただけでは、親の記録は変わりません。git status に modified: libs/mylib (new commits) が残っていないか、作業の最後に確かめましょう。

子のコミットを push し忘れて「not our ref」

子のフォルダーで自分がコミットした a8f2f77 を、取り込み元の mylib に届けないまま、親でコミットしました。colleague 側で pull すると、次のように止まりました。

Fetching submodule libs/mylib
fatal: git upload-pack: not our ref a8f2f77c2d58fd6ff06d02af1d810c58e80efd02
fatal: remote error: upload-pack: not our ref a8f2f77c2d58fd6ff06d02af1d810c58e80efd02
Errors during submodule fetch:
	libs/mylib

git submodule update も did not contain a8f2f77… というエラーで失敗します。親が指すコミットが、取り込み元のどこにもないからです。直し方は、コミットした人が子のリポジトリを先に push することです(今回は mylib に a8f2f77 を取り込んだあと、update が通りました)。Pro Git では、親を push するときに git push --recurse-submodules=check を使うと、子に push していないコミットがあれば止めてくれると紹介されています。

「modified content」「untracked content」と表示される

親の git status の括弧の中は、子の状態を表しています。

表示status –short意味
new commitsM子のコミットが親の記録と違う
modified contentm子の中に、コミットしていない変更がある
untracked content?子の中に、追跡していないファイルがある

今回、py main.py のあとに (new commits, untracked content) と出ました。Python が子のフォルダーに __pycache__/ を作ったためです。modified content と untracked content は、親で git add libs/mylib しても記録されません(公式ドキュメント(git-status)にも書かれていて、実際に add しても m libs/mylib のままでした)。子の中でコミットするか、元に戻します。キャッシュのようなファイルは、子のリポジトリの .gitignore に書くのが根本的な対策です。

「A git directory for ‘…’ is found locally」で追加し直せない

git rm で消した libs/mylog を、同じ場所にもう一度追加しようとすると、次のように止められました。

fatal: A git directory for 'libs/mylog' is found locally with remote(s):
  origin	C:/work/mylog
If you want to reuse this local git directory instead of cloning again from
  C:/work/mylog
use the '--force' option. If the local git directory is not the correct repo
or you are unsure what this means choose another name with the '--name' option.

削除で残った .git/modules/libs/mylog が原因です。同じ取り込み元なら --force を付けると、Reactivating local git directory for submodule 'libs/mylog' と表示され、残っている情報を使い直して追加されました。別のリポジトリを同じ場所に置きたいときは --name で別の名前を付けるか、.git/modules/libs/mylog を消してから追加します(消してから追加し直すと、ふつうに clone されました)。

subtree・パッケージ管理との違い

別のリポジトリのコードを使う方法は、サブモジュールだけではありません。git subtree は子のファイルそのものを親に取り込む方法で、公式ドキュメントには「サブモジュールと違って .gitmodules のような特別な仕組みが要らず、使う人に特別なことをさせない」とあります。代わりに、親の履歴に子のファイルが入ります。

パッケージとして配布できるライブラリなら、pip や npm などのパッケージ管理で版の番号を指定して使うほうが手軽です(「pipの使い方」を参照)。

まとめ

親が記録するのは子のコミット ID だけです。clone のあとは git submodule update --init、子を更新したら親で add と commit(子でコミットしたら子の push が先)、子で作業するときは先にブランチへ切り替える、の 3 つを覚えておけば、たいていのつまずきは避けられます。

submodule 以外の Git のコマンドも、やりたいことから探せる「Gitコマンド検索」で調べられます。

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました