簡體中文 ▾ 主題 ▾ 最新版本 ▾ git-submodule 最後更新於 2.47.0

名稱

git-submodule - 初始化、更新或檢查子模組

概要

git submodule [--quiet] [--cached]
git submodule [--quiet] add [<options>] [--] <repository> [<path>]
git submodule [--quiet] status [--cached] [--recursive] [--] [<path>…​]
git submodule [--quiet] init [--] [<path>…​]
git submodule [--quiet] deinit [-f|--force] (--all|[--] <path>…​)
git submodule [--quiet] update [<options>] [--] [<path>…​]
git submodule [--quiet] set-branch [<options>] [--] <path>
git submodule [--quiet] set-url [--] <path> <newurl>
git submodule [--quiet] summary [<options>] [--] [<path>…​]
git submodule [--quiet] foreach [--recursive] <command>
git submodule [--quiet] sync [--recursive] [--] [<path>…​]
git submodule [--quiet] absorbgitdirs [--] [<path>…​]

描述

檢查、更新和管理子模組。

有關子模組的更多資訊，請參閱 gitsubmodules[7]。

命令

不帶任何引數時，將顯示現有子模組的狀態。有多個子命令可用於對子模組執行操作。

add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--] <repository> [<path>]

將給定的倉庫作為子模組新增到給定路徑，並將其新增到當前專案（稱為“父專案”）的下一次提交更改集中。

<repository> 是新子模組源倉庫的 URL。這可以是一個絕對 URL，或者（如果以 ./ 或 ../ 開頭），則是相對於父專案預設遠端倉庫的位置。（請注意，要指定一個位於父專案 bar.git 旁邊的倉庫 foo.git，您必須使用 ../foo.git 而不是 ./foo.git——這與遵循相對 URL 規則時所期望的可能不同——因為 Git 中相對 URL 的評估與相對目錄的評估是相同的）。

預設遠端倉庫是當前分支的遠端跟蹤分支的遠端倉庫。如果不存在此類遠端跟蹤分支或 HEAD 已分離，則假定“origin”是預設遠端倉庫。如果父專案沒有配置預設遠端倉庫，則父專案是其自身的權威上游，並改用當前工作目錄。

可選引數 <path> 是克隆的子模組在父專案中存在的相對位置。如果未給出 <path>，則使用源倉庫的規範部分（“repo”表示“/path/to/repo.git”，“foo”表示“host.xz:foo/.git”）。如果 <path> 存在且已是有效的 Git 倉庫，則它將在不進行克隆的情況下暫存以供提交。<path> 也用作子模組在其配置條目中的邏輯名稱，除非使用 --name 指定邏輯名稱。

給定的 URL 將記錄在 .gitmodules 中，供後續克隆父專案的使用者使用。如果 URL 是相對於父專案的倉庫給出的，則假定父專案和子模組倉庫將保持在相同的相對位置，並且只需提供父專案的 URL。git-submodule 將使用 .gitmodules 中的相對 URL 正確地找到子模組。

如果指定了 --ref-format <format>，新克隆的子模組的引用儲存格式將相應設定。

status [--cached] [--recursive] [--] [<path>…​]

顯示子模組的狀態。這將列印每個子模組當前檢出提交的 SHA-1，以及子模組路徑和 git describe 對該 SHA-1 的輸出。如果子模組未初始化，每個 SHA-1 可能會以 - 為字首；如果當前檢出的子模組提交與包含倉庫索引中找到的 SHA-1 不匹配，則以 + 為字首；如果子模組存在合併衝突，則以 U 為字首。

如果指定了 --cached，此命令將轉而列印父專案中為每個子模組記錄的 SHA-1。

如果指定了 --recursive，此命令將遞迴進入巢狀子模組，並顯示它們的狀態。

如果您只對當前初始化子模組相對於索引或 HEAD 中記錄的提交的更改感興趣，git-status[1] 和 git-diff[1] 也將提供該資訊（並且還可以報告子模組工作樹的更改）。

init [--] [<path>…​]

透過在 .git/config 中設定 submodule.$name.url，初始化索引中記錄的子模組（這些子模組是在其他地方新增和提交的），使用 .gitmodules 中的相同設定作為模板。如果 URL 是相對的，它將使用預設遠端倉庫解析。如果沒有預設遠端倉庫，則當前倉庫將被假定為上游。

可選的 <path> 引數限制將初始化哪些子模組。如果未指定路徑且已配置 submodule.active，則將初始化配置為活動的子模組，否則將初始化所有子模組。

它還將 .gitmodules 檔案中存在的 submodule.$name.update 值複製到 .git/config，但 (1) 此命令不會更改 .git/config 中現有的資訊，並且 (2) 出於安全原因，設定為自定義命令的 submodule.$name.update 不會被複制。

然後，您可以為本地設定在 .git/config 中自定義子模組克隆 URL，然後執行 git submodule update；如果您不打算自定義任何子模組位置，也可以直接使用 git submodule update --init，而無需顯式 init 步驟。

有關預設遠端倉庫的定義，請參閱 add 子命令。

deinit [-f|--force] (--all|[--] <path>…​)

登出給定的子模組，即從 .git/config 中刪除整個 submodule.$name 部分及其工作樹。後續對 git submodule update、git submodule foreach 和 git submodule sync 的呼叫將跳過任何未註冊的子模組，直到它們再次初始化，因此，如果您不再希望在工作樹中擁有子模組的本地檢出，請使用此命令。

當不帶路徑規範執行此命令時，它會報錯，而不是登出所有內容，以防止誤操作。

如果指定了 --force，即使子模組的工作樹包含本地修改，它也將被刪除。

如果您真的想從倉庫中移除一個子模組並提交該更改，請改用 git-rm[1]。有關刪除選項，請參閱 gitsubmodules[7]。

update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>…​]

透過克隆缺失的子模組、獲取子模組中缺失的提交併更新子模組的工作樹，將已註冊的子模組更新為與父專案預期一致。“更新”可以透過多種方式進行，具體取決於命令列選項和 submodule.<name>.update 配置變數的值。命令列選項優先於配置變數。如果兩者都未給出，則執行 checkout。（注意：此時 .gitmodules 檔案中的內容無關緊要；請參閱上面的 git submodule init 以瞭解 .gitmodules 的使用方式）。命令列和透過 submodule.<name>.update 配置支援的 更新 過程有

checkout

父專案中記錄的提交將在子模組中以分離 HEAD 的方式檢出。

如果指定了 --force，即使包含倉庫索引中指定的提交已與子模組中檢出的提交匹配，子模組也將被檢出（使用 git checkout --force）。

rebase

子模組的當前分支將基於父專案中記錄的提交進行變基。

merge

父專案中記錄的提交將合併到子模組的當前分支中。

以下更新過程有額外的限制

自定義命令

一種機制，用於以提交 ID 作為引數執行任意命令。具體來說，如果 submodule.<name>.update 配置變數設定為 !custom command，則將父專案中為子模組記錄的提交的物件名稱附加到 custom command 字串並執行。請注意，此機制在 .gitmodules 檔案或命令列中不受支援。

無

子模組不會被更新。此更新過程不允許在命令列上使用。

如果子模組尚未初始化，並且您只想使用 .gitmodules 中儲存的設定，您可以使用 --init 選項自動初始化子模組。

如果指定了 --recursive，此命令將遞迴進入已註冊的子模組，並更新其中的任何巢狀子模組。

如果指定了 --ref-format <format>，新克隆的子模組的引用儲存格式將相應設定。

如果指定了 --filter <filter-spec>，給定的部分克隆過濾器將應用於子模組。有關過濾器規範的詳細資訊，請參閱 git-rev-list[1]。

set-branch (-b|--branch) <branch> [--] <path>
set-branch (-d|--default) [--] <path>

設定子模組的預設遠端跟蹤分支。--branch 選項允許指定遠端分支。--default 選項刪除 submodule.<name>.branch 配置鍵，這將導致跟蹤分支預設為遠端 HEAD。

set-url [--] <path> <newurl>

將指定子模組的 URL 設定為 <newurl>。然後，它將自動同步子模組的新遠端 URL 配置。

summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>…​]

顯示給定提交（預設為 HEAD）與工作樹/索引之間的提交摘要。對於所討論的子模組，將顯示子模組中給定父專案提交與索引或工作樹之間的一系列提交（由 --cached 切換）。如果給出 --files 選項，則顯示父專案的索引與子模組的工作樹之間的一系列子模組提交（此選項不允許使用 --cached 選項或提供顯式提交）。

使用帶 --submodule=log 選項的 git-diff[1] 也將提供該資訊。

foreach [--recursive] <command>

在每個已檢出的子模組中評估任意 shell 命令。該命令可以訪問變數 $name、$sm_path、$displaypath、$sha1 和 $toplevel：$name 是 .gitmodules 中相關子模組節的名稱，$sm_path 是在直接父專案中記錄的子模組路徑，$displaypath 包含從當前工作目錄到子模組根目錄的相對路徑，$sha1 是在直接父專案中記錄的提交，$toplevel 是直接父專案頂層的絕對路徑。請注意，為避免與 Windows 上的 $PATH 衝突，$path 變數現在是 $sm_path 變數的已棄用同義詞。此命令會忽略父專案中定義但未檢出的任何子模組。除非給出 --quiet，否則 foreach 會在評估命令之前列印每個子模組的名稱。如果給出 --recursive，子模組將遞迴遍歷（即，給定的 shell 命令也會在巢狀子模組中評估）。任何子模組中命令的非零返回都會導致處理終止。可以透過在命令末尾新增 || : 來覆蓋此行為。

例如，以下命令將顯示每個子模組的路徑和當前檢出的提交

git submodule foreach 'echo $sm_path `git rev-parse HEAD`'
sync [--recursive] [--] [<path>…​]

將子模組的遠端 URL 配置設定同步到 .gitmodules 中指定的值。它只會影響那些在 .git/config 中已經有 URL 條目的子模組（即它們已初始化或剛剛新增的情況）。當子模組 URL 在上游發生變化時，此功能很有用，您需要相應地更新本地倉庫。

git submodule sync 同步所有子模組，而 git submodule sync -- A 僅同步子模組“A”。

如果指定了 --recursive，此命令將遞迴進入已註冊的子模組，並同步其中的任何巢狀子模組。

absorbgitdirs

如果子模組的 git 目錄位於子模組內部，則將子模組的 git 目錄移動到其父專案的 $GIT_DIR/modules 路徑中，然後透過設定 core.worktree 並新增一個指向嵌入在父專案 git 目錄中的 git 目錄的 .git 檔案來連線 git 目錄及其工作目錄。

獨立克隆後新增為子模組的倉庫，或舊的設定，會將子模組的 git 目錄置於子模組內部，而不是嵌入到父專案的 git 目錄中。

此命令預設為遞迴。

選項

-q
--quiet

只打印錯誤訊息。

--progress

此選項僅對 add 和 update 命令有效。預設情況下，當連線到終端時，進度狀態會在標準錯誤流上報告，除非指定了 -q。此標誌即使標準錯誤流未重定向到終端，也會強制報告進度狀態。

--all

此選項僅對 deinit 命令有效。登出工作樹中的所有子模組。

-b <branch>
--branch <branch>

要新增為子模組的倉庫分支。分支名稱將記錄在 .gitmodules 中的 submodule.<name>.branch 中，用於 update --remote。特殊值 . 用於指示子模組中的分支名稱應與當前倉庫中的當前分支名稱相同。如果未指定此選項，則預設為遠端 HEAD。

-f
--force

此選項僅對 add、deinit 和 update 命令有效。執行 add 時，允許新增原本被忽略的子模組路徑。執行 deinit 時，即使子模組工作樹包含本地更改，也將被刪除。執行 update（僅在使用 checkout 過程時有效）時，在切換到不同提交時丟棄子模組中的本地更改；並且始終在子模組中執行 checkout 操作，即使包含倉庫索引中列出的提交與子模組中檢出的提交匹配。

--cached

此選項僅對 status 和 summary 命令有效。這些命令通常使用子模組 HEAD 中找到的提交，但使用此選項時，將使用索引中儲存的提交。

--files

此選項僅對 summary 命令有效。使用此選項時，此命令會將索引中的提交與子模組 HEAD 中的提交進行比較。

-n
--summary-limit

此選項僅對 summary 命令有效。限制摘要大小（總共顯示的提交數量）。給定 0 將停用摘要；負數表示無限制（預設）。此限制僅適用於已修改的子模組。對於已新增/已刪除/型別更改的子模組，大小始終限制為 1。

--remote

此選項僅對 update 命令有效。不是使用父專案記錄的 SHA-1 來更新子模組，而是使用子模組遠端跟蹤分支的狀態。使用的遠端倉庫是分支的遠端倉庫（branch.<name>.remote），預設為 origin。使用的遠端分支預設為遠端 HEAD，但可以透過在 .gitmodules 或 .git/config 中設定 submodule.<name>.branch 選項來覆蓋分支名稱（.git/config 優先）。

這適用於任何受支援的更新過程（--checkout、--rebase 等）。唯一的區別是目標 SHA-1 的來源。例如，submodule update --remote --merge 會將上游子模組的更改合併到子模組中，而 submodule update --merge 則會將父專案的 gitlink 更改合併到子模組中。

為了確保當前的跟蹤分支狀態，update --remote 會在計算 SHA-1 之前拉取子模組的遠端倉庫。如果您不想拉取，則應使用 submodule update --remote --no-fetch。

使用此選項可將上游子專案的更改與您子模組的當前 HEAD 整合。或者，您可以在子模組中執行 git pull，這除了遠端分支名稱外是等效的：update --remote 使用預設上游倉庫和 submodule.<name>.branch，而 git pull 使用子模組的 branch.<name>.merge。如果您想將預設上游分支與父專案一起分發，則優先使用 submodule.<name>.branch；如果您想在子模組本身中工作時獲得更原生的感覺，則優先使用 branch.<name>.merge。

-N
--no-fetch

此選項僅對 update 命令有效。不要從遠端站點拉取新物件。

--checkout

此選項僅對 update 命令有效。在子模組中，以分離 HEAD 的方式檢出父專案中記錄的提交。這是預設行為，此選項的主要用途是在 submodule.$name.update 設定為 checkout 以外的值時覆蓋它。如果鍵 submodule.$name.update 未明確設定或設定為 checkout，則此選項是隱式的。

--merge

此選項僅對 update 命令有效。將父專案中記錄的提交合併到子模組的當前分支中。如果給出此選項，子模組的 HEAD 將不會分離。如果合併失敗阻止此過程，您將必須使用常規衝突解決工具解決子模組中的衝突。如果鍵 submodule.$name.update 設定為 merge，則此選項是隱式的。

--rebase

此選項僅對 update 命令有效。將當前分支變基到父專案中記錄的提交。如果給出此選項，子模組的 HEAD 將不會分離。如果合併失敗阻止此過程，您將必須使用 git-rebase[1] 解決這些失敗。如果鍵 submodule.$name.update 設定為 rebase，則此選項是隱式的。

--init

此選項僅對 update 命令有效。在更新之前，初始化所有尚未呼叫“git submodule init”的子模組。

--name

此選項僅對 add 命令有效。它將子模組的名稱設定為給定的字串，而不是預設為其路徑。該名稱必須是有效的目錄名，並且不能以 / 結尾。

--reference <repository>

此選項僅對 add 和 update 命令有效。這些命令有時需要克隆遠端倉庫。在這種情況下，此選項將傳遞給 git-clone[1] 命令。

注意：除非您已仔細閱讀 git-clone[1] 的 --reference、--shared 和 --dissociate 選項的注意事項，否則請不要使用此選項。

--dissociate

此選項僅對 add 和 update 命令有效。這些命令有時需要克隆遠端倉庫。在這種情況下，此選項將傳遞給 git-clone[1] 命令。

注意：請參閱 --reference 選項的注意事項。

--recursive

此選項僅對 foreach、update、status 和 sync 命令有效。遞迴遍歷子模組。此操作不僅在當前倉庫的子模組中執行，還會在這些子模組內部的任何巢狀子模組中執行（依此類推）。

--depth

此選項對 add 和 update 命令有效。建立一個歷史記錄截斷為指定修訂數的淺克隆。請參閱 git-clone[1]

--[no-]recommend-shallow

此選項僅對 update 命令有效。子模組的初始克隆將預設使用 .gitmodules 檔案中提供的推薦 submodule.<name>.shallow。要忽略這些建議，請使用 --no-recommend-shallow。

-j <n>
--jobs <n>

此選項僅對 update 命令有效。並行克隆新子模組，最多可執行多個任務。預設為 submodule.fetchJobs 選項。

--[no-]single-branch

此選項僅對 update 命令有效。更新時只克隆一個分支：HEAD 或由 --branch 指定的分支。

<path>…​

子模組路徑。指定時，這將限制命令僅對指定路徑下的子模組進行操作。（此引數在 add 命令中是必需的）。

檔案

初始化子模組時，包含倉庫頂層目錄中的 .gitmodules 檔案用於查詢每個子模組的 URL。此檔案的格式應與 $GIT_DIR/config 相同。每個子模組 URL 的鍵是“submodule.$name.url”。有關詳細資訊，請參閱 gitmodules[5]。

另請參閱

gitsubmodules[7], gitmodules[5]。

GIT

Git[1] 套件的一部分

scroll-to-top