git submoduleで、別のリポジトリを中に入れて使う方法
複数のプロジェクトで使う共通の 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 は何も表示しません。
$ 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> <置く場所> で追加します。検証環境では、最初に打ったとき、次のように止められました。
$ 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 を入れてから、もう一度追加しました。
$ 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つがステージされました。
$ 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だけです。
$ 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 はその場所を指すファイルになっていました。

この2つをコミットして、blog のリモート(remote/blog.git)に push しました。
$ 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 を表します。
$ 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 し、記録されたコミットを取り出します。
$ 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回で済みました。
$ 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)でした。公式リファレンスにあるとおり、記録されたコミットそのものを取り出すためです。
$ 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 を実行すると、共有元から取ってきて、最新のコミットに切り替わりました。
$ 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 を使うと、どのコミットが入ってくるかが分かります。
$ 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 に変わります。
$ 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 には角を丸くする行がありません。
$ 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 で元に戻しました。
$ 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 に記録されたコミットに合わせます。
$ 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 を毎回付けたのと同じになります。
$ git pull -q --recurse-submodules
$ git submodule status
6f735c5c9767493b5ceef96f2f2f1869b9235b46 vendor/neko-ui (remotes/origin/HEAD)
$ git status --short
submodule を外す
使わなくなった submodule は git rm で外します。
$ 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 がこのフォルダーを残します。完全に消したいときは、このフォルダーを自分で消します。





