Git子模塊（Submodule）使用指南：管理項目中的依賴代碼

想象你正在開發一個大項目，這個項目裏需要用到一些獨立的代碼庫，比如一個團隊共同維護的工具類庫，或者一個第三方提供的組件。如果每次更新這些代碼都要手動複製粘貼，不僅麻煩，還容易出錯。這時候，Git子模塊（Submodule）就能幫上大忙了！

什麼是Git子模塊？¶

簡單來說，Git子模塊就是在一個Git倉庫（我們叫它“主項目”）裏，包含另一個Git倉庫（叫它“子模塊”）作爲子目錄。主項目只需要記錄子模塊的位置和版本，而子模塊本身是獨立的倉庫，可以單獨更新和維護。就像你買了一座房子，同時擁有房子裏的一個獨立儲藏室，儲藏室可以自己裝修、更新，主房子只需要記得儲藏室的位置就行。

爲什麼要用子模塊？¶

獨立維護：子模塊可以單獨開發、測試、更新，不影響主項目的其他部分。
版本控制：主項目能精確指定子模塊的版本（比如某個特定的提交或分支），避免依賴代碼混亂。
複用性：多個主項目可以共享同一個子模塊，子模塊更新後，主項目只需同步版本即可。

如何使用Git子模塊？¶

1. 添加子模塊到主項目¶

假設你有一個主項目my_project，現在要把一個第三方工具庫tool-lib作爲子模塊加入，工具庫的倉庫地址是https://github.com/example/tool-lib.git，希望放在主項目的libs/tool-lib目錄下。

執行命令：

# 在主項目目錄下執行
git submodule add https://github.com/example/tool-lib.git libs/tool-lib

add參數會創建子模塊，https://github.com/example/tool-lib.git是子模塊倉庫的地址，libs/tool-lib是子模塊在主項目中的存放路徑。
執行後，主項目會自動生成兩個文件：
.gitmodules：記錄子模塊的元數據（倉庫地址、路徑等）。
.git/config：新增子模塊的配置信息。

把這些文件提交到主項目倉庫：

git add .gitmodules libs/tool-lib/.git
git commit -m "添加工具庫子模塊 tool-lib"

2. 克隆包含子模塊的主項目¶

如果別人要克隆你的主項目，並且希望同時獲取子模塊的內容，需要用--recursive參數（遞歸克隆子模塊）：

git clone --recursive https://github.com/yourname/my_project.git

如果忘記加--recursive，克隆後子模塊目錄是空的，需要手動初始化並拉取子模塊內容：

git clone https://github.com/yourname/my_project.git
cd my_project
git submodule update  # 拉取子模塊內容

3. 更新子模塊¶

當子模塊倉庫有新的代碼提交時，主項目需要更新子模塊到最新版本：

方法1：手動更新子模塊
進入子模塊目錄，直接拉取更新：

cd libs/tool-lib  # 進入子模塊目錄
git pull  # 拉取子模塊倉庫的最新代碼

回到主項目，更新子模塊的版本記錄：

cd ..  # 返回主項目目錄
git add libs/tool-lib  # 提交子模塊版本的變化
git commit -m "更新子模塊 tool-lib 到最新版本"

方法2：用Git命令自動更新
在主項目目錄直接執行：

git submodule update

這條命令會自動進入子模塊目錄拉取更新，並更新主項目中記錄的子模塊版本號。

4. 刪除子模塊¶

如果不再需要某個子模塊，需要從主項目中徹底移除：

   rm -rf libs/tool-lib

清理主項目配置：
- 打開.gitmodules文件，刪除對應子模塊的配置（比如[submodule "libs/tool-lib"]部分）。
- 從Git配置中刪除子模塊：

     git config --remove-section submodule.libs/tool-lib

從主項目Git索引中移除：

   git rm --cached libs/tool-lib

提交主項目的變更：

   git commit -m "移除子模塊 tool-lib"

清理殘留文件：

   rm -rf .git/modules/libs/tool-lib  # 刪除子模塊的緩存文件

常見問題 & 注意事項¶

子模塊更新後主項目沒變化？
子模塊目錄的內容變化後，主項目需要重新提交子模塊的版本號。確保執行git add <子模塊路徑>和git commit。
子模塊顯示“detached HEAD”（遊離頭）？
這是因爲子模塊默認處於某個提交的“遊離頭”狀態。進入子模塊目錄執行git checkout master（或目標分支）即可切換到正常分支。
多人協作時如何避免衝突？
子模塊的版本由主項目的提交哈希控制，只要大家遵循“更新子模塊→提交主項目→合併”的流程，就能避免衝突。

總結¶

Git子模塊是管理項目依賴的強大工具，尤其適合獨立維護的代碼庫。核心步驟可以概括爲：添加子模塊→克隆主項目（帶遞歸參數）→更新子模塊→提交主項目版本。掌握這些基礎操作，就能輕鬆複用和管理項目中的依賴代碼，避免重複勞動和版本混亂。