Git Subtree と Submodule の違いをできるだけシンプルに整理する

外部リポジトリをプロジェクトに組み込みたいとき、
git submodule と git subtree のどちらを使うべきか迷うことが多いので、
両者の違いを用途ごとにざっくり整理します。

---

結論

機能	Submodule	Subtree
管理方法	別リポジトリを参照する（ポインタ方式）	別リポジトリの内容を直接取り込む（コピー方式）
メリット	軽量・純粋に外部依存を切り出せる	親リポジトリだけ見れば完結する
デメリット	運用が面倒（clone 後の init/update など）	履歴が混ざるためリポジトリが重くなる
向いてる用途	ライブラリ・SDK を外部依存として切り出したい	共同開発でリポジトリを部分的に共有したい

「外部コードへの依存を軽く扱いたいなら Submodule」
「外部を取り込んで自前コードのように扱いたいなら Subtree」

---

Submodule の特徴

特徴

• 外部リポジトリを 参照として保持 するだけ
• 中身は .gitmodules に記録される URL・パスと、親リポジトリに記録されるコミット ID へのポインタ
• 実体は clone 時に別途 git submodule update が必要

メリット

• 外部コードを完全に独立した依存として扱える
• 親リポジトリが軽い
• 外部リポジトリの履歴を汚さない

デメリット

• 運用が面倒
  • clone後に git submodule init && git submodule update
  • submodule の状態管理を意識する必要がある
• CI/CD でも追加設定が必要

向いているケース

• OSS ライブラリや SDK を固定バージョンで参照したい
• 外部リポジトリを明確に依存として扱いたい

---

Subtree の特徴

特徴

• 外部リポジトリのコードを 親リポジトリに直接取り込む
• clone しただけで内容が揃う
• 一部ディレクトリだけ切り出して使える

メリット

• 運用が簡単（clone するだけで OK）
• 親リポジトリだけで完結
• チーム間でリポジトリを部分共有するとき便利
• Submoduleより扱いやすい

デメリット

• 親リポジトリが重くなる
• 履歴が合流してやや複雑になる（--squash で軽減可能）
• 外部への変更を戻す場合は subtree コマンドが必要

向いているケース

• チーム間で一部ディレクトリを共有したい
• モノレポっぽく扱いたい
• Submodule より運用ストレスを減らしたい

---

実際の使いどころをまとめてみる

状況	おすすめ
外部ライブラリを依存として扱いたい	Submodule
外部リポジトリの一部をプロジェクトに取り込みたい	Subtree
clone 後に何も考えず動いてほしい	Subtree
リポジトリの重さよりも運用簡単さを優先	Subtree
履歴をきれいに保ちたい	Submodule

---

まとめ

• Submodule → 参照方式。外部依存として切り出したいとき向け
• Subtree → 取り込み方式。運用しやすく、チームで使いやすい

---