文章引用來源：https://blog.csdn.net/coco_1998_2/article/details/111537072

背景

面對比較復(fù)雜的項(xiàng)目，我們有可能會將代碼根據(jù)功能拆解成不同的子模塊。主項(xiàng)目對子模塊有依賴關(guān)系，卻又并不關(guān)心子模塊的內(nèi)部開發(fā)流程細(xì)節(jié)。

這種情況下，通常不會把所有源碼都放在同一個(gè) Git 倉庫中。

有一種比較簡單的方式，是在當(dāng)前工作目錄下，將子模塊文件夾加入到 .gitignore 文件內(nèi)容中，這樣主項(xiàng)目就能夠無視子項(xiàng)目的存在。這樣做有一個(gè)弊端就是，使用主項(xiàng)目的人需要有一個(gè)先驗(yàn)知識：需要在當(dāng)前目錄下放置一份某版本的子模塊代碼。

還有另外一種方式可供借鑒，可以使用 Git 的 submodule 功能，也是這篇文章的主題。

實(shí)際上 Git 工具的 submodule 功能就是建立了當(dāng)前項(xiàng)目與子模塊之間的依賴關(guān)系：子模塊路徑、子模塊的遠(yuǎn)程倉庫、子模塊的版本號。

使用流程

假定我們有兩個(gè)項(xiàng)目：project-main 和 project-sub-1，其中 project-main 表示主項(xiàng)目，而 project-sub-1 表示子模塊項(xiàng)目。

其中 project-main 的遠(yuǎn)程倉庫地址為 https://github.com/username/project-main.git，而 project-sub-1 的遠(yuǎn)程倉庫地址為 https://github.com/username/project-sub-1.git。

接下來，我們希望在 project-main 中添加 project-sub-1 ，而又保持 project-sub-1 自身獨(dú)立的版本控制。

1.創(chuàng)建 submodule

使用 git submodule add <submodule_url> 命令可以在項(xiàng)目中創(chuàng)建一個(gè)子模塊。

進(jìn)入項(xiàng)目 project-main ，輸入：

? project-main git:(master) git submodule add https://github.com/username/project-sub-1.git
正克隆到 '/path/to/project-main/project-sub-1'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
展開對象中: 100% (3/3), 完成.

此時(shí)項(xiàng)目倉庫中會多出兩個(gè)文件：.gitmodules 和 project-sub-1 。

前者的內(nèi)容是這樣的，事實(shí)上就是子模塊的相關(guān)信息；而后者那個(gè)文件，實(shí)際上保存的是子模塊當(dāng)前版本的版本號信息。

[submodule "project-sub-1"]
path = project-sub-1
url = https://github.com/username/project-sub-1.git

如果此前項(xiàng)目中已經(jīng)存在 .gitmodules 文件，則會在文件內(nèi)容中多出上述三行記錄。

事實(shí)上，此時(shí)在 .git/config 文件中也會多出一些信息，在 .git/modules 文件夾下也會多出一份內(nèi)容。

通常此時(shí)可以使用 git commit -m "add submodule xxx" 提交一次，表示引入了某個(gè)子模塊。提交后，在主項(xiàng)目倉庫中，會顯示出子模塊文件夾，并帶上其所在倉庫的版本號。

[圖片上傳失敗...(image-ac93fc-1649993033588)]

2.獲取 submodule

上述步驟在創(chuàng)建子模塊的過程中，會自動(dòng)將相關(guān)代碼克隆到對應(yīng)路徑，但對于后續(xù)使用者而言，對于主項(xiàng)目使用普通的 clone 操作并不會拉取到子模塊中的實(shí)際代碼。

使用以下命令進(jìn)行克隆，完成后 project-main/project-sub-1 文件夾是空的：

cd /path/to/temp
git clone <u style="box-sizing: border-box; outline: 0px; overflow-wrap: break-word;">https://github.com/username/project-main.git</u>

如果希望子模塊代碼也獲取到，一種方式是在克隆主項(xiàng)目的時(shí)候帶上參數(shù) --recurse-submodules，這樣會遞歸地將項(xiàng)目中所有子模塊的代碼拉取。

cd /path/to/temp2
git clone https://github.com/username/project-main.git --recurse-submodules

此時(shí) project-main/project-sub-1 文件夾是有內(nèi)容的，并且固定在某個(gè) Git 提交的版本上。

另外一種可行的方式是，在當(dāng)前主項(xiàng)目中執(zhí)行：

git submodule init
git submodule update

則會根據(jù)主項(xiàng)目的配置信息，拉取更新子模塊中的代碼。

3.子模塊內(nèi)容的更新

對于子模塊而言，并不需要知道引用自己的主項(xiàng)目的存在。對于自身來講，子模塊就是一個(gè)完整的 Git 倉庫，按照正常的 Git 代碼管理規(guī)范操作即可。

對于主項(xiàng)目而言，子模塊的內(nèi)容發(fā)生變動(dòng)時(shí)，通常有三種情況：

1）當(dāng)前項(xiàng)目下子模塊文件夾內(nèi)的內(nèi)容發(fā)生了未跟蹤的內(nèi)容變動(dòng)；

2）當(dāng)前項(xiàng)目下子模塊文件夾內(nèi)的內(nèi)容發(fā)生了版本變化；

3）當(dāng)前項(xiàng)目下子模塊文件夾內(nèi)的內(nèi)容沒變，遠(yuǎn)程有更新；

情況1：子模塊有未跟蹤的內(nèi)容變動(dòng)

對于第1種情況，通常是在開發(fā)環(huán)境中，直接修改子模塊文件夾中的代碼導(dǎo)致的。

此時(shí)在主項(xiàng)目中使用 git status 能夠看到關(guān)于子模塊尚未暫存以備提交的變更，但是于主項(xiàng)目而言是無能為力的，使用 git add/commit 對其也不會產(chǎn)生影響。

? project-main git:(master) git status
位于分支 master
您的分支與上游分支 'origin/master' 一致。
尚未暫存以備提交的變更：
（使用 "git add <文件>..." 更新要提交的內(nèi)容）
（使用 "git checkout -- <文件>..." 丟棄工作區(qū)的改動(dòng)）
（提交或丟棄子模組中未跟蹤或修改的內(nèi)容）
修改： project-sub-1 (未跟蹤的內(nèi)容)
修改尚未加入提交（使用 "git add" 和/或 "git commit -a"）

在此情景下，通常需要進(jìn)入子模塊文件夾，按照子模塊內(nèi)部的版本控制體系提交代碼。

當(dāng)提交完成后，主項(xiàng)目的狀態(tài)則進(jìn)入了情況2，即當(dāng)前項(xiàng)目下子模塊文件夾內(nèi)的內(nèi)容發(fā)生了版本變化。

情況2：子模塊有版本變化

當(dāng)子模塊版本變化時(shí)，在主項(xiàng)目中使用 git status 查看倉庫狀態(tài)時(shí)，會顯示子模塊有新的提交：

? project-main git:(master) ? git status
位于分支 master
您的分支與上游分支 'origin/master' 一致。
尚未暫存以備提交的變更：
（使用 "git add <文件>..." 更新要提交的內(nèi)容）
（使用 "git checkout -- <文件>..." 丟棄工作區(qū)的改動(dòng)）
修改： project-sub-1 (新提交)
修改尚未加入提交（使用 "git add" 和/或 "git commit -a"）

在這種情況下，可以使用 git add/commit 將其添加到主項(xiàng)目的代碼提交中，實(shí)際的改動(dòng)就是那個(gè)子模塊 文件 所表示的版本信息：

git diff HEAD HEAD^
diff --git a/project-sub-1 b/project-sub-1
index ace9770..7097c48 160000
--- a/project-sub-1
+++ b/project-sub-1
@@ -1 +1 @@
-Subproject commit ace977071f94f4f88935f9bb9a33ac0f8b4ba935
+Subproject commit 7097c4887798b71cee360e99815f7dbd1aa17eb4

通常當(dāng)子項(xiàng)目更新后，主項(xiàng)目修改其所依賴的版本時(shí)，會產(chǎn)生類似這種情景的 commit 提交信息。

情況3：子模塊遠(yuǎn)程有更新

通常來講，主項(xiàng)目與子模塊的開發(fā)不會恰好是同時(shí)進(jìn)行的。通常是子模塊負(fù)責(zé)維護(hù)自己的版本升級后，推送到遠(yuǎn)程倉庫，并告知主項(xiàng)目可以更新對子模塊的版本依賴。

在這種情況下，主項(xiàng)目是比較茫然的。

之前曾經(jīng)提到，主項(xiàng)目可以使用 git submodule update 更新子模塊的代碼，但那是指 當(dāng)前主項(xiàng)目文件夾下的子模塊目錄內(nèi)容 與 當(dāng)前主項(xiàng)目記錄的子模塊版本 不一致時(shí)，會參考后者進(jìn)行更新。

但如今這種情況下，后者 當(dāng)前主項(xiàng)目記錄的子模塊版本 還沒有變化，在主項(xiàng)目看來當(dāng)前情況一切正常。

此時(shí)，需要讓主項(xiàng)目主動(dòng)進(jìn)入子模塊拉取新版代碼，進(jìn)行升級操作。

通常流程是：

cd project-sub-1
git pull origin master

子模塊目錄下的代碼版本會發(fā)生變化，轉(zhuǎn)到情況2的流程進(jìn)行主項(xiàng)目的提交。

當(dāng)主項(xiàng)目的子項(xiàng)目特別多時(shí)，可能會不太方便，此時(shí)可以使用 git submodule 的一個(gè)命令 foreach 執(zhí)行：

git submodule foreach 'git pull origin master'

情況匯總

終上所述，可知在不同場景下子模塊的更新方式如下：

• 對于子模塊，只需要管理好自己的版本，并推送到遠(yuǎn)程分支即可；
• 對于父模塊，若子模塊版本信息未提交，需要更新子模塊目錄下的代碼，并執(zhí)行 commit 操作提交子模塊版本信息；
• 對于父模塊，若子模塊版本信息已提交，需要使用 git submodule update ，Git 會自動(dòng)根據(jù)子模塊版本信息更新所有子模塊目錄的相關(guān)代碼。

4.刪除子模塊

網(wǎng)上流傳了一些偏法，主要步驟是直接移除模塊，并手動(dòng)修改 .gitmodules、.git/config 和 .git/modules 內(nèi)容。包含了一大堆類似git rm --cached <sub-module>、rm -rf <sub-moduel>、rm .gitmodules 和 git rm --cached 之類的代碼。

實(shí)際上這是一種比較野的做法，不建議使用。

根據(jù)官方文檔的說明，應(yīng)該使用 git submodule deinit 命令卸載一個(gè)子模塊。這個(gè)命令如果添加上參數(shù) --force，則子模塊工作區(qū)內(nèi)即使有本地的修改，也會被移除。

git submodule deinit project-sub-1
git rm project-sub-1

執(zhí)行 git submodule deinit project-sub-1 命令的實(shí)際效果，是自動(dòng)在 .git/config 中刪除了以下內(nèi)容：

[submodule "project-sub-1"]
url = https://github.com/username/project-sub-1.git

執(zhí)行 git rm project-sub-1 的效果，是移除了 project-sub-1 文件夾，并自動(dòng)在 .gitmodules 中刪除了以下內(nèi)容：

[submodule "project-sub-1"]
path = project-sub-1
url = https://github.com/username/project-sub-1.git

此時(shí)，主項(xiàng)目中關(guān)于子模塊的信息基本已經(jīng)刪除（雖然貌似 .git/modules 目錄下還有殘余）：

? project-main git:(master) ? gs
位于分支 master
您的分支與上游分支 'origin/master' 一致。
要提交的變更：
（使用 "git reset HEAD <文件>..." 以取消暫存）
修改： .gitmodules
刪除： project-sub-1

可以提交代碼：

git commit -m "delete submodule project-sub-1"

至此完成對子模塊的刪除。

總結(jié)

當(dāng)項(xiàng)目比較復(fù)雜，部分代碼希望獨(dú)立為子模塊進(jìn)行版本控制時(shí)，可以使用 git submodule 功能。

使用 git submodule 功能時(shí)，主項(xiàng)目倉庫并不會包含子模塊的文件，只會保留一份子模塊的配置信息及版本信息，作為主項(xiàng)目版本管理的一部分。

本篇文章簡單介紹了 git submodule 的添加和刪除，以及項(xiàng)目開發(fā)過程中主項(xiàng)目與子模塊不同狀態(tài)時(shí)刻的操作方式。