git submoduleで、別のリポジトリを中に入れて使う方法

​​Git​コマンドライン

複数のプロジェクトで使う共通の CSS やライブラリを、コピーせずに別のリポジトリのまま取り込みたいときは、git submodule(サブモジュール)を使います。取り込んだリポジトリは自分の履歴を持ったまま、使う側のリポジトリの中の1つのフォルダーとして置かれます。追加、clone 後の取り出し、共有元の更新の取り込み、取り外しの4つを、操作の前と後の出力で示します。

補足

検証環境は Ubuntu 24.04、Git 2.43.0 です。作者の名前とメールアドレスには例示用の値(Neko <neko@example.com>)を設定し、コミットの日時を環境変数で決めました。作業用のフォルダーは /path/to という名前で作ったので、出力に出るパスもこの値です。共有元のリポジトリは、GitHub などのサーバーではなく、同じマシンの中に作った bare リポジトリ(/path/to/remote/neko-ui.git)です。HTTPS や SSH の URL での追加、submodule の中にさらに submodule がある場合、submodule の中での作業とコミット、Windows・macOS は試していません。

試したリポジトリの組み合わせ

共有する側は、ボタンの CSS(button.css)だけが入った neko-ui リポジトリです。使う側は、トップページ(index.html)だけがある blog リポジトリです。index.html は vendor/neko-ui/button.css を読み込むように書いてあり、ここに neko-ui を submodule として入れます。

操作の前の blog の状態です。git submodule status は何も表示しません。

console
$ git status
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

$ ls -a
.
..
.git
index.html

$ git submodule status

git submodule add で追加する

git submodule add <リポジトリのURL> <置く場所> で追加します。検証環境では、最初に打ったとき、次のように止められました。

console
$ git submodule add /path/to/remote/neko-ui.git vendor/neko-ui
Cloning into '/path/to/blog/vendor/neko-ui'...
fatal: transport 'file' not allowed
fatal: clone of '/path/to/remote/neko-ui.git' into submodule path '/path/to/blog/vendor/neko-ui' failed

git config の公式リファレンスにある protocol.allow と protocol.<name>.allow の説明によると、https や ssh は初めから使えますが、ローカルのパス(file)は、submodule の取り込みのように Git が自動で clone するときには使えない設定になっています。https や ssh の URL で追加するときには、次の設定は要りません。ここでは、使い捨ての検証環境のユーザー設定(--global)に protocol.file.allow を入れてから、もう一度追加しました。

console
$ git config --global protocol.file.allow always

$ git submodule add /path/to/remote/neko-ui.git vendor/neko-ui
Cloning into '/path/to/blog/vendor/neko-ui'...
done.

追加した後の状態です。.gitmodules という設定ファイルと、vendor/neko-ui の2つがステージされました。

console
$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	new file:   .gitmodules
	new file:   vendor/neko-ui


$ cat .gitmodules
[submodule "vendor/neko-ui"]
	path = vendor/neko-ui
	url = /path/to/remote/neko-ui.git

$ ls -a vendor/neko-ui
.
..
.git
button.css

.gitmodules には、置く場所(path)と、取ってくる元(url)が書かれています。公式リファレンスによると、この URL は、あとで blog を clone した人が submodule を取ってくるときに使われます。

vendor/neko-ui の中身のファイルは、blog のコミットには入りません。blog に記録されるのは、neko-ui のどのコミットを使うかを示すコミットIDだけです。

console
$ cat vendor/neko-ui/.git
gitdir: ../../.git/modules/vendor/neko-ui

$ git ls-files -s vendor/neko-ui
160000 e2869d7cb647bc3b3aa8374e5d0f02881e80b9d9 0	vendor/neko-ui

$ git diff --cached vendor/neko-ui
diff --git a/vendor/neko-ui b/vendor/neko-ui
new file mode 160000
index 0000000..e2869d7
--- /dev/null
+++ b/vendor/neko-ui
@@ -0,0 +1 @@
+Subproject commit e2869d7cb647bc3b3aa8374e5d0f02881e80b9d9

モードが 160000 のこの記録を、gitsubmodules の公式の説明では gitlink と呼んでいます。neko-ui の履歴そのものは、blog の .git/modules/ の下に置かれ、vendor/neko-ui/.git はその場所を指すファイルになっていました。

使う側のリポジトリ blog は、.gitmodules に置く場所と取ってくる元を、vendor/neko-ui にコミット e2869d7 のコミットIDだけを記録する。共有するリポジトリ neko-ui は独自の履歴を持ち、新しいコミット 6f735c5 は自動では入らない
使う側のリポジトリが submodule について記録するもの

この2つをコミットして、blog のリモート(remote/blog.git)に push しました。

console
$ git commit -q -m 'neko-ui を submodule として追加'

$ git push -q origin main

$ git log --oneline
dd709f3 neko-ui を submodule として追加
fa09f72 トップページを追加

clone した後に submodule の中身を取り出す

blog を別のフォルダー(blog2)に、ふつうに clone しました。vendor/neko-ui のフォルダーはできますが、中身は空です。git submodule status の先頭の - は、まだ初期化していない submodule を表します。

console
$ git clone -q remote/blog.git blog2

$ ls -a blog2/vendor/neko-ui
.
..

$ git -C blog2 submodule status
-e2869d7cb647bc3b3aa8374e5d0f02881e80b9d9 vendor/neko-ui

git submodule update --init で、.gitmodules の URL から clone し、記録されたコミットを取り出します。

console
$ git -C blog2 submodule update --init
Submodule 'vendor/neko-ui' (/path/to/remote/neko-ui.git) registered for path 'vendor/neko-ui'
Cloning into '/path/to/blog2/vendor/neko-ui'...
done.
Submodule path 'vendor/neko-ui': checked out 'e2869d7cb647bc3b3aa8374e5d0f02881e80b9d9'

$ git -C blog2 submodule status
 e2869d7cb647bc3b3aa8374e5d0f02881e80b9d9 vendor/neko-ui (heads/main)

$ ls blog2/vendor/neko-ui
button.css

clone するときに --recurse-submodules を付けると、この2つの手順が1回で済みました。

console
$ git clone -q --recurse-submodules remote/blog.git blog3

$ git -C blog3 submodule status
 e2869d7cb647bc3b3aa8374e5d0f02881e80b9d9 vendor/neko-ui (heads/main)

git submodule update で取り出した submodule の中は、どのブランチにもいない状態(detached HEAD)でした。公式リファレンスにあるとおり、記録されたコミットそのものを取り出すためです。

console
$ git -C blog2/vendor/neko-ui status
HEAD detached at e2869d7
nothing to commit, working tree clean

共有元の新しいコミットを取り込む

neko-ui に、ボタンの角を丸くするコミット(6f735c5)を足して push しました。この時点では、blog の submodule は前のコミット e2869d7 のままです。submodule は記録したコミットに固定されるので、共有元が進んでも勝手には変わりません。

git submodule update --remote を実行すると、共有元から取ってきて、最新のコミットに切り替わりました。

console
$ git submodule status
 e2869d7cb647bc3b3aa8374e5d0f02881e80b9d9 vendor/neko-ui (heads/main)

$ git submodule update --remote
From /path/to/remote/neko-ui
   e2869d7..6f735c5  main       -> origin/main
Submodule path 'vendor/neko-ui': checked out '6f735c5c9767493b5ceef96f2f2f1869b9235b46'

$ git submodule status
+6f735c5c9767493b5ceef96f2f2f1869b9235b46 vendor/neko-ui (remotes/origin/HEAD)

先頭の + は、取り出しているコミットが、blog に記録したコミットと違うことを表します。git status では、vendor/neko-ui が変更ありとして出ました。git diff --submodule=log を使うと、どのコミットが入ってくるかが分かります。

console
$ git status
On branch main
Your branch is up to date with 'origin/main'.

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:   vendor/neko-ui (new commits)

no changes added to commit (use "git add" and/or "git commit -a")

$ git diff --submodule=log
Submodule vendor/neko-ui e2869d7..6f735c5:
  > ボタンの角を丸くする

新しいコミットを使うと決めたら、ふつうのファイルと同じように git add してコミットします。これで、blog に記録されるコミットIDが 6f735c5 に変わります。

console
$ git add vendor/neko-ui

$ git commit -q -m 'neko-ui を更新'

$ git push -q origin main

$ git submodule status
 6f735c5c9767493b5ceef96f2f2f1869b9235b46 vendor/neko-ui (remotes/origin/HEAD)

ほかの clone では pull の後に update が要る

先に clone しておいた blog2 で git pull すると、記録されるコミットIDは新しくなりますが、submodule の中のファイルは古いままでした。git submodule status の先頭に + が付き、button.css には角を丸くする行がありません。

console
$ git pull -q

$ git status
On branch main
Your branch is up to date with 'origin/main'.

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:   vendor/neko-ui (new commits)

no changes added to commit (use "git add" and/or "git commit -a")

$ git submodule status
+e2869d7cb647bc3b3aa8374e5d0f02881e80b9d9 vendor/neko-ui (heads/main)

$ git diff
diff --git a/vendor/neko-ui b/vendor/neko-ui
index 6f735c5..e2869d7 160000
--- a/vendor/neko-ui
+++ b/vendor/neko-ui
@@ -1 +1 @@
-Subproject commit 6f735c5c9767493b5ceef96f2f2f1869b9235b46
+Subproject commit e2869d7cb647bc3b3aa8374e5d0f02881e80b9d9

$ cat vendor/neko-ui/button.css
.button {
  color: #fff;
}

git diff は、記録された 6f735c5 から古い e2869d7 へ戻す向きの差分になっています。試しにこの状態で git add すると、古いコミットに戻す変更がステージされました。確かめた後、git restore --staged で元に戻しました。

console
$ git add vendor/neko-ui

$ git diff --cached
diff --git a/vendor/neko-ui b/vendor/neko-ui
index 6f735c5..e2869d7 160000
--- a/vendor/neko-ui
+++ b/vendor/neko-ui
@@ -1 +1 @@
-Subproject commit 6f735c5c9767493b5ceef96f2f2f1869b9235b46
+Subproject commit e2869d7cb647bc3b3aa8374e5d0f02881e80b9d9

$ git restore --staged vendor/neko-ui

$ git status --short
 M vendor/neko-ui

ここでは git add せずに、git submodule update(--remote なし)で、blog に記録されたコミットに合わせます。

console
$ git submodule update
Submodule path 'vendor/neko-ui': checked out '6f735c5c9767493b5ceef96f2f2f1869b9235b46'

$ git submodule status
 6f735c5c9767493b5ceef96f2f2f1869b9235b46 vendor/neko-ui (remotes/origin/HEAD)

$ cat vendor/neko-ui/button.css
.button {
  color: #fff;
  border-radius: 8px;
}

--remote を付けると共有元の最新に、付けないと blog に記録されたコミットに合わせる、という違いです。

blog3 では git pull --recurse-submodules を使いました。pull と同時に submodule も記録どおりのコミットになり、git status --short には何も出ませんでした。git config の公式リファレンスにある submodule.recurse の説明によると、この設定を true にすると、pull などで --recurse-submodules を毎回付けたのと同じになります。

console
$ git pull -q --recurse-submodules

$ git submodule status
 6f735c5c9767493b5ceef96f2f2f1869b9235b46 vendor/neko-ui (remotes/origin/HEAD)

$ git status --short

submodule を外す

使わなくなった submodule は git rm で外します。

console
$ git rm vendor/neko-ui
rm 'vendor/neko-ui'

$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   .gitmodules
	deleted:    vendor/neko-ui


$ ls -a vendor
.
..

$ ls .git/modules/vendor
neko-ui

vendor/neko-ui のフォルダーが消え、.gitmodules からはこの submodule の節が消えました(検証では、ほかに submodule がないので .gitmodules は0バイトになりました)。どちらの変更もステージされるので、あとはコミットすれば外れます。

一方で、.git/modules/vendor/neko-ui は残りました。gitsubmodules の公式の説明によると、過去のコミットを取り出したときに、もう一度取ってこなくても submodule を戻せるように、Git がこのフォルダーを残します。完全に消したいときは、このフォルダーを自分で消します。

​Posted by 86