在大型專案中，我們常常需要重複使用其他專案的程式碼。直接Copy會造成維護困難，這時候Git Submodule就是最經典的解決方案。
在軟體開發中，當你的專案需要引用其他獨立的專案（例如公共類別庫、通用 UI 組件或第三方套件），且你希望這些組件能夠獨立維護、同時又能被多個專案共享時，Git Submodule（子模組）就是最佳的解決方案。Git Submodule是 Git 提供的一個功能，允許你將一個 Git 倉庫（Repository）作為另一個 Git 倉庫的子目錄。與直接「複製貼上」程式碼不同，Git Submodule 採用的是指針（Pointer）機制。主專案只會紀錄子模組的遠端倉庫 URL以及一個特定的Commit ID (SHA-1 哈希值)。當團隊其他成員複製（Clone）主專案時，Git 會根據這個指針，去對應的子模組倉庫把該特定版本的程式碼拉取下來。
為什麼要使用它？（核心優勢）
- 程式碼去中心化與共享：同一個公共庫（如 utils）可以被多個專案同時引用，避免重複造輪子。
- 保持專案邊界：主專案的開發人員不需要看到子模組裡密密麻麻的修改歷史，主專案的 Commit 紀錄會保持乾淨。
- 精準控制版本：主專案可以自由決定什麼時候要「升級」子模組的版本，不會因為子模組那邊有人更新了程式碼，就無預警地破壞主專案的運作。
git submodule add 範例
1. 到C Disk目錄
2. 接著建立Module資料夾，並進入Module資料夾目錄
3. 建立1.txt
4. 初始化GIT，加入1.txt和Commit
5. 建立submodule資料夾並進入
6. 在submodule 資料夾裡建立2.txt檔案。
7. 接著再回到Module資料夾目錄。如果要將剛才建立的submodule資料夾和submodule資料夾裡的檔案為Module 倉庫的submodule。則執行以下指令git submodule add ./submodule
8. 打git status，則顯示 submodule 資料夾已加入到Module倉庫裡。記得submodule資料夾要先建成repository(git init, git add . 和加上git commit -m)
注意 Git 2.38+ 之後常見的安全性限制。Git 預設不允許使用 file:// 或本機路徑來建立 submodule，以避免惡意 repository 利用本機檔案。如下範例
Git 會把它視為本機 (file) transport，因此被拒絕。
加入 git submodules to GitHub
我的Github有兩個倉庫。Module和Submodule。我們嘗試把Submodule倉庫成為Module的子倉庫。
注意這兩個遠端倉儲裡的檔案是完全新建的，與前面在本地建立的範例檔案沒有關聯。
1. 想Submodule倉庫當成Module倉庫的子倉庫。則執行
git submodule add https://github.com/Joseph225Gang/Submodule.git
2. 接著git add, git commit 和 git push。把submodule加入module的遠端倉庫。
3. 如上已將submodule倉庫加入Module的子倉庫。打開.gitmodules會看到子repository的路徑和URL。
4. 接著我們嘗試更新submodule倉庫。我們加入test.txt在submodule端。
5. 注意如果我們在module倉庫要取得子模組最新版本。要輸入以下指令
git submodule update –remote或是
git submodule update –remote submodule 指定的 submodule
所以Submodule 的更新需要兩個步驟：
- 先更新submodule本身（git pull 或 git submodule update –remote）。
- 再回到父倉庫提交新的 submodule commit 指標（git add submodule → git commit → git push）。
也就是說，即使 submodule 已經 git push，父倉庫仍然需要再commit 一次，才能讓其他人取得新的submodule版本。
最後我們回到github看，Module裡的Submodule已更新。
總結來說，Git Submodule 適合用在多個專案需要共享穩定基礎庫、UI 元件或工具函式，且希望精準控制版本、保持主專案乾淨的場景。它能有效避免重複造輪子，同時讓子模組獨立維護。然而，當兩個專案高度耦合、子模組更新非常頻繁，或團隊成員對 Submodule 尚不熟悉時，就不建議使用此方式，此時可考慮 Monorepo 架構、Git Subtree 或直接透過套件管理工具發佈。掌握 Submodule 的正確使用時機與更新流程，將能大幅提升專案管理效率。建議大家多練習實際操作，遇到問題再持續優化，就能讓它成為團隊開發的得力助手！