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

一、什麼是Git子模塊？爲什麼要用它？¶

想象你正在開發一個大項目，比如一款手機遊戲。你需要一個通用的角色動畫庫（比如專門處理角色走路、跳躍的代碼），這個庫可以在多個項目中複用，而且需要獨立更新（比如修復動畫bug、添加新動作）。如果直接把這個動畫庫的代碼複製到遊戲項目裏，每次動畫庫更新，你都要手動把代碼複製過去，既麻煩又容易出錯。

這時候，Git子模塊（Submodule） 就能派上用場了！它就像給大項目“搭積木”：主項目是“房子”，子模塊是“樂高零件”。主項目依賴這些“零件”，但“零件”本身是獨立的項目，可以單獨維護和更新，修好了零件直接用新的，不用重新拼整個房子。

二、子模塊的核心優勢¶

代碼複用：避免重複複製依賴代碼，節省存儲空間。
獨立維護：子模塊本身是獨立的Git倉庫，別人可以直接修改、提交、合併子模塊的代碼，主項目只需跟蹤子模塊的版本。
版本可控：主項目可以指定子模塊的具體版本（比如某個提交ID或分支），確保所有人使用的依賴版本一致。

三、子模塊的基本原理¶

子模塊本質是一個獨立的Git倉庫，但被嵌套在另一個主倉庫中。主倉庫通過記錄子模塊的“引用”（比如子模塊倉庫的URL和特定版本），實現對依賴代碼的關聯。舉個例子：

主項目（my_game）需要一個角色動畫庫（character_animations）作爲子模塊。
character_animations 是獨立的倉庫，有自己的提交歷史和分支。
主項目通過 .gitmodules 文件記錄子模塊的配置，通過 .git/config 記錄子模塊的當前版本引用。

四、開始使用子模塊的步驟¶

假設你已經安裝了Git，並且需要在主項目中添加一個子模塊，以下是核心操作：

1. 添加子模塊（在主項目中）¶

如果你有一個空的主項目，或者想給現有項目添加子模塊，使用 git submodule add 命令：

# 進入主項目目錄
cd my_game

# 添加子模塊（URL是子模塊倉庫地址，路徑是子模塊在主項目中的存放位置）
git submodule add https://github.com/yourname/character_animations.git character_animations

執行後會發生什麼？
主項目的 .gitmodules 文件會新增一行，記錄子模塊的名稱和倉庫地址。
主項目的 .git/config 會新增子模塊的配置信息。
主項目根目錄會多出一個 character_animations 文件夾（但此時是空的，需要後續拉取）。

2. 克隆包含子模塊的倉庫¶

如果別人已經創建了包含子模塊的項目，或者你想克隆一個完整的項目（包括子模塊），可以用 --recursive 參數一次性拉取所有子模塊：

# 直接克隆主項目和所有子模塊
git clone --recursive https://github.com/yourname/my_game.git

如果忘記加 --recursive，克隆後子模塊目錄是空的，需要手動初始化和更新：

# 克隆主項目
git clone https://github.com/yourname/my_game.git
cd my_game

# 初始化子模塊（讀取.gitmodules配置）
git submodule init

# 更新子模塊（拉取子模塊的代碼）
git submodule update

3. 進入子模塊修改代碼¶

如果需要修改子模塊的內容（比如給動畫庫新增一個走路動作），直接進入子模塊目錄：

# 進入子模塊目錄
cd character_animations

# （假設當前在子模塊的master分支）
git checkout master

# 修改代碼（比如新增一個walk_forward函數）
# ... 編輯文件 ...

# 提交子模塊的修改
git add .
git commit -m "Add walk_forward animation"
git push  # 推送到子模塊倉庫（如果需要遠程同步）

修改完成後，回到主項目並提交子模塊的版本更新：

# 回到主項目目錄
cd ..

# 查看子模塊狀態（會顯示子模塊的引用是否有更新）
git status

# 提交子模塊的版本更新（記錄子模塊的最新commit ID）
git add character_animations
git commit -m "Update character_animations to version 1.2.3"
git push

4. 更新子模塊到最新版本¶

如果子模塊倉庫被別人更新了（比如你同事修好了動畫庫的bug），主項目需要拉取最新的子模塊代碼：

# 方法1：直接拉取主項目的子模塊更新
cd my_game
git pull

# （或者如果已經在主項目中，執行更新）
git submodule update

注意：如果主項目的子模塊配置中指定了特定分支（比如dev分支），可以進入子模塊手動切換分支：

cd character_animations
git checkout dev
git pull
cd ..
git add character_animations
git commit -m "Update to dev branch"

5. 刪除子模塊¶

如果需要移除某個子模塊（比如角色動畫庫不再需要），不能直接刪除文件夾！需要手動清理配置：

# 1. 刪除子模塊文件夾
rm -rf character_animations

# 2. 刪除.gitmodules中的配置
git rm --cached character_animations
# （或手動編輯.gitmodules，刪除對應子模塊的section）

# 3. 刪除.git/config中的子模塊引用
git config --remove-section submodule."character_animations"

# 4. 提交清理結果
git commit -m "Remove character_animations submodule"
git push

五、常見問題與解決方法¶

子模塊克隆後是空的？
原因：克隆時沒加 --recursive，或忘記執行 git submodule update。
解決：git clone --recursive 或 git submodule update。
修改子模塊後主項目沒看到更新？
原因：修改子模塊後未提交到主項目的子模塊引用。
解決：進入子模塊提交修改，再回到主項目 git add 子模塊目錄並提交。
多人協作時子模塊版本衝突？
解決：約定子模塊分支（如main或dev），避免直接修改主項目的子模塊提交ID。

六、總結¶

Git子模塊適合管理獨立開發、需要複用的依賴代碼（如工具庫、第三方框架）。核心流程是：
1. 添加子模塊 → 2. 克隆/更新子模塊 → 3. 進入子模塊修改並提交 → 4. 主項目更新子模塊引用。

記住：子模塊是“獨立倉庫的嵌套”，主項目只跟蹤子模塊的版本，而不是複製代碼。合理使用子模塊能大幅提升項目複用性和維護效率！