簡體中文 ▾ 主題 ▾ 最新版本 ▾ git-submodule 最後更新於 2.52.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 <分支>] [-f|--force] [--name <名稱>] [--reference <倉庫>] [--ref-format <格式>] [--depth <深度>] [--] <倉庫> [<路徑>]

將給定的倉庫新增為當前專案旁的更改集中的子模組，該更改集將用於下一個提交：當前專案稱為“超級專案”。

<倉庫> 是新子模組的源倉庫的 URL。它可以是絕對 URL，也可以（如果以 ./ 或 ../ 開頭）是相對於超級專案的預設遠端倉庫的位置（請注意，要指定一個與超級專案 foo.git 緊鄰的倉庫 bar.git，您必須使用 ../foo.git 而不是 ./foo.git - 正如遵循相對 URL 規則時可能期望的那樣 - 因為 Git 中相對 URL 的解析與相對目錄的解析相同）。

預設遠端是當前分支的遠端跟蹤分支的遠端。如果不存在這樣的遠端跟蹤分支或 HEAD 已分離，則假定“origin”是預設遠端。如果超級專案沒有配置預設遠端，則超級專案是其自身權威的上游，並使用當前工作目錄代替。

可選引數 <路徑> 是在超級專案中克隆的子模組存在的相對位置。如果未給出 <路徑>，則使用源倉庫的規範部分（“repo”用於“/path/to/repo.git”，而“foo”用於“host.xz:foo/.git”）。如果 <路徑> 存在且已經是有效的 Git 倉庫，則它將被暫存提交，而無需克隆。<路徑> 也用作子模組配置條目中的邏輯名稱，除非使用 --name 指定了邏輯名稱。

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

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

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>…​]

初始化索引中記錄的子模組（這些子模組已在其他地方新增和提交），方法是使用 .gitmodules 中的相同設定作為模板，在 .git/config 中設定 submodule.$name.url。如果 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 <倉庫>] [--ref-format <格式>] [--depth <深度>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>…​]

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

checkout

將在子模組中檢出超級專案記錄的提交，處於分離 HEAD 狀態。

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

rebase

將子模組的當前分支變基到超級專案中記錄的提交之上。

merge

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

以下更新過程有額外限制

custom command

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

none

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

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

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

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

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

set-branch (-b|--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 <分支>

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

-f
--force

此選項僅對 add、deinit 和 update 命令有效。執行時，允許新增一個通常被忽略的子模組路徑。此選項還用於繞過子模組名稱未被使用的檢查。預設情況下，如果擬議的名稱（從路徑派生）已在倉庫中為另一個子模組註冊，git submodule add 將失敗。使用 --force 允許命令繼續，自動生成唯一的名稱，方法是在衝突名稱後附加一個數字（例如，如果存在一個名為 child 的子模組，它將嘗試 child1，依此類推）。執行 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 <倉庫>

此選項僅對 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]。

--recommend-shallow
--no-recommend-shallow

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

-j <n>
--jobs <n>

此選項僅對 update 命令有效。使用指定數量的作業並行克隆新子模組。預設為 submodule.fetchJobs 選項。

--single-branch
--no-single-branch

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

<path>…​

子模組的路徑。指定時，此命令將僅限於對指定路徑下的子模組進行操作。（新增命令需要此引數）。

檔案

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

另請參閱

gitsubmodules[7], gitmodules[5]。

GIT

Git[1] 套件的一部分