HOWTO · Git

拉取最新的 Git 子模組

在本文中,我們將介紹 Git 子模組。

本頁內容

Git 子模組是在父倉庫中檢出的獨立倉庫。父倉庫會記錄子模組的一個特定提交,因此「更新」可能是還原到該記錄的提交,也可能是將子模組移至遠端較新的提交。在父倉庫中,使用 git submodule update --init --recursive 初始化尚未初始化的子模組,並檢出父倉庫記錄的提交。若要跟隨較新的遠端追蹤提交,請使用 git submodule update --remote --recursive;接著檢查並提交父倉庫中變更的子模組指標。

Git 子模組更新的運作方式

子模組有自己的提交歷史和遠端設定。父倉庫會儲存一個 gitlink,也就是指向該巢狀倉庫中某個提交的參照。因此,複製或檢出父倉庫,不代表子模組目錄已填入檔案,也不代表子模組會跟隨遠端分支的最新提交。

git submodule update 會檢出目前父提交所記錄的提交。若要使用專案宣告的相依版本,這是可重現的選擇。--init 選項會註冊並初始化 .gitmodules 中描述的子模組;--recursive 則會將操作套用至巢狀子模組。這些選項都不表示「取得最新提交」。

初始化子模組並更新至記錄的提交

若剛複製的倉庫尚未初始化子模組,或是檢出了含有子模組的父提交,請在父倉庫根目錄執行:

git submodule update --init --recursive

Git 會視需要初始化已設定的路徑,並檢出父倉庫記錄的各個提交。即使子模組已初始化,這個命令仍會將其工作目錄切換到記錄的提交。這可能會使子模組處於分離的 HEAD 狀態;對於由父倉庫固定在特定提交的子模組而言,這是正常情況。若要查看哪些子模組指標與父倉庫目前的提交不同,請在父倉庫中檢查 git status。

擷取子模組的較新遠端提交

若要從子模組所設定的遠端追蹤分支更新,請在父倉庫中執行 git submodule update --remote --recursive。Git 會擷取已設定的遠端,並檢出子模組所設定分支選定的提交。如果子模組沒有指定分支,Git 會使用其遠端的預設分支。這不保證取得每個分支或遠端上的最新提交;結果取決於已設定的分支及其已擷取的遠端追蹤狀態。

遠端更新會變更子模組目前檢出的提交,並使父倉庫顯示子模組指標已變更。提交前請先檢查這項變更。如果只想擷取遠端資料而不變更目前檢出的提交,請在子模組內執行擷取並檢視分支;不要把 --remote 當作只擷取而不檢出的操作。

複製包含子模組的倉庫

若要一次複製倉庫並遞迴初始化其中的子模組,請使用 git clone --recurse-submodules <repository-url>。請將佔位文字換成倉庫網址。一般的 git clone <repository-url> 只會複製父倉庫,不會初始化子模組的工作目錄;若已用一般方式複製,請在新父目錄中執行 git submodule update --init --recursive。

遞迴選項也會初始化巢狀於其他子模組中的子模組。檢出時會使用複製下來的父倉庫所記錄的提交;若要採用該專案選定的版本,這種方式就很合適。

提交並推送子模組變更

在子模組內修改內容時,請先從該子模組倉庫提交並推送變更。若子模組目前檢出的是父倉庫固定的提交,它可能處於分離的 HEAD 狀態,因此發布前要先選定目標遠端分支。如果變更應加入現有分支,請切換至該分支並在其中整合變更;否則請建立新分支。檢查子模組的遠端與分支設定,並確認協作者應使用這個分支。接著用 git add 和 git commit 提交變更,再推送分支,例如執行 git push <remote> <branch>。如果你刻意維持 HEAD 分離狀態,請使用 git push <remote> HEAD:<branch> 明確發布目前的提交,並將佔位文字換成選定的遠端和目標分支。請確認協作者日後擷取父倉庫時,也能取得已推送的提交。

只有在子模組提交已發布後,才返回父倉庫。父倉庫的狀態會顯示子模組指標已變更;請將該路徑加入暫存區並提交父倉庫,例如執行 git add path/to/submodule,接著執行 git commit -m "Update submodule pointer"。之後照常另外推送父提交。父提交記錄新的子模組提交 ID,而子模組提交本身屬於巢狀倉庫。只推送父倉庫,不會發布尚未推送的子模組提交;只推送子模組,也不會變更父倉庫記錄的提交。