Name

git-submodule  - 初始化，更新或檢查子模塊

概要

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] summary [<options>] [--] [<path>…]git submodule [--quiet] foreach [--recursive] <command>git submodule [--quiet] sync [--recursive] [--] [<path>…]git submodule [--quiet] absorbgitdirs [--] [<path>…]

描述

檢查，更新和管理子模塊。

有關(guān)子模塊的更多信息，請參閱 gitsubmodules [7]。

命令

add -b <branch> --name <name> --depth <depth> <repository> <path>

將給定的存儲庫作為子模塊添加到要在當前項目旁提交的變更集的給定路徑：當前項目稱為“超級項目”。

<repository> 是新子模塊的源存儲庫的 URL 。這可能是一個絕對 URL ，或者（如果它以./或者../開始），相對于上層項目的默認遠程倉庫的位置（請注意，指定倉庫foo.git位于旁邊的一個上層項目bar.git，你”必須使用 - ../foo.git而不是./foo.git- 遵循相對 URL 的規(guī)則時所期望的 - 因為 Git 中的相對 URL 的評估與相對目錄的相同 URL 相同）。

默認遠程是當前分支的遠程追蹤分支的遠程。如果不存在這樣的遠程跟蹤分支或 HEAD 被分離，則“原點”被假定為默認遠程。如果超級項目沒有配置默認遠程，則超級項目是其自己的權(quán)威上游，而是使用當前工作目錄。

可選參數(shù) <path> 是克隆子模塊存在于超級項目中的相對位置。如果沒有給出 <path> ，則使用源存儲庫的規(guī)范部分（“repo”表示“/path/to/repo.git”，“foo”表示“host.xz：foo / .git”）。如果 <path> 存在并且已經(jīng)是有效的 Git 存儲庫，那么它將進行無克隆提交。除非--name用于指定邏輯名稱，否則 <path> 在其配置條目中也用作子模塊的邏輯名稱。

記錄給定的 URL .gitmodules以供后續(xù)用戶克隆超級項目使用。如果該 URL 是相對于超級項目的存儲庫給出的，則假定是超級項目，并且子模塊存儲庫將一起保存在相同的相對位置，并且只需要提供超級項目的 URL 。git-submodule 將使用中的 .gitmodules 的相對 URL 正確地定位子模塊。

status --cached --

顯示子模塊的狀態(tài)。這將為每個子模塊打印當前簽出的提交的 SHA-1 ，以及git describe用于 SHA-1 的子模塊路徑和輸出。-如果子模塊未初始化，+如果當前簽出的子模塊提交與包含存儲庫的索引中找到的 SHA-1 不匹配，并且U子模塊存在合并沖突，則每個 SHA-1 都將加上前綴。

如果--recursive指定，則此命令將遞歸嵌套子模塊，并顯示其狀態(tài)。

如果您只對目前初始化的子模塊相對于索引或 HEAD 中記錄的提交感興趣，git-status [1] 和 git-diff [1] 也會提供這些信息（也可以將更改報告給子模塊的工作樹）。

init --

通過submodule.$name.url在 .git / config 中設(shè)置來初始化索引中記錄的子模塊（已添加并在其他位置添加并提交）。它使用與.gitmodules模板相同的設(shè)置。如果 URL 是相對的，它將使用默認的遠程進行解析。如果沒有默認遠程，則當前的存儲庫將被假定為上游。

可選的 <path> 參數(shù)限制了哪些子模塊將被初始化。如果未指定路徑并且已配置 submodule.active ，則將初始化配置為活動的子模塊，否則會初始化所有子模塊。

當存在時，它也將復(fù)制值submodule.$name.update。該命令不會改變 .git / config 中的現(xiàn)有信息。然后，您可以在 .git / config 中為您的本地設(shè)置定制子模塊克隆 URL 并繼續(xù)git submodule update; 如果您不打算自定義任何子模塊位置，則也可以在git submodule update --init沒有明確init步驟的情況下使用。

有關(guān)默認遠程的定義，請參閱 add 子命令。

deinit -f|--force

取消注冊給定的子模塊，submodule.$name即將 .git / config 中的整個部分與其工作樹一起移除。進一步呼吁git submodule update，git submodule foreach并git submodule sync會跳過所有未注冊的子模塊，直到再次初始化，所以使用這個命令，如果你不想在你的工作樹子模塊的本地結(jié)賬了。

當命令在沒有 pathspec 的情況下運行時，它會出錯，而不是取消所有內(nèi)容，以防止出錯。

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

如果您確實想從存儲庫中移除子模塊并提交使用 git-rm [1]來代替。有關(guān)移除選項，請參閱 gitsubmodules [7]。

update --init -N | --no-fetch  -  no-recommend-shallow] -f | --force --reference <repository> --recursive  -

通過克隆缺失子模塊和更新子模塊的工作樹，更新已注冊的子模塊以匹配超級項目所期望的內(nèi)容。根據(jù)命令行選項和submodule.<name>.update配置變量的值，“更新”可以通過多種方式完成。命令行選項優(yōu)先于配置變量。如果兩者均未給出，則執(zhí)行結(jié)賬。更新過程支持從命令行以及設(shè)置submodule.<name>.update：

checkout

記錄在超級項目中的提交將在分離的 HEAD 上的子模塊中檢出。

如果--force指定，則git checkout --force即使包含存儲庫的索引中指定的提交與子模塊中簽出的提交匹配，也會檢出子模塊（如果適用）。

rebase

子模塊的當前分支將重新綁定到超級項目中記錄的提交上。

merge

記錄在超級項目中的提交將被合并到子模塊中的當前分支中。

以下過程僅通過submodule.<name>.update配置變量可用：

自定義命令

執(zhí)行采用單個參數(shù)（超級項目中記錄的提交的sha1）的任意 shell 命令。當submodule.<name>.update設(shè)置!command為時，感嘆號后的剩余部分是自定義命令。

none

子模塊沒有更新。

如果子模塊尚未初始化，并且只想使用存儲的設(shè)置.gitmodules，則可以使用該--init選項自動初始化子模塊。

如果--recursive指定，則此命令將遞歸到已注冊的子模塊中，并更新其中的任何嵌套子模塊。

summary --cached | --files commit <path> ...

在給定提交（默認為 HEAD ）和工作樹/索引之間顯示提交摘要。對于有問題的子模塊，顯示給定超級項目提交與索引或工作樹（切換--cached）之間的子模塊中的一系列提交。如果--files給出該選項，則在超級項目的索引和子模塊的工作樹之間顯示子模塊中的一系列提交（該選項不允許使用該--cached選項或提供顯式提交）。

使用--submodule=log git-diff [1] 的選項也會提供這些信息。

foreach --recursive <command>

在每個簽出的子模塊中評估一個任意的 shell 命令。該命令可以訪問變量 $ name，$ path，$ sha1 和 $ toplevel：$ name 是相關(guān)子模塊部分.gitmodules的名稱，$ path 是相對于超級項目的子模塊目錄的名稱，$ sha1 是提交記錄在超級項目中，而 $ toplevel 是超級項目頂級的絕對路徑。在超級項目中定義但未檢出的任何子模塊都將被此命令忽略。除非給出--quiet，否則 foreach 在評估命令之前打印每個子模塊的名稱。如果--recursive給出子模塊遞歸地遍歷（即，給定的 shell 命令也在嵌套子模塊中進行評估）。來自任何子模塊中的命令的非零返回會導(dǎo)致處理終止。這可以通過添加|| :到命令的末尾來覆蓋。

作為示例，下面的命令將顯示每個子模塊的路徑和當前簽出的提交：

git submodule foreach 'echo $path `git rev-parse HEAD`'

sync --recursive <path>…

將子模塊的遠程 URL 配置設(shè)置同步到中指定的值.gitmodules。它只會影響那些已經(jīng)在 .git / config 中有 URL 條目的子模塊（這是在初始化或新添加的情況下）。當子模塊 URL 更改為上游時，這很有用，因此您需要相應(yīng)地更新本地存儲庫。

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

如果--recursive指定，則此命令將遞歸到已注冊的子模塊中，并同步其中任何嵌套的子模塊。

absorbgitdirs

如果子模塊的 git 目錄位于子模塊內(nèi)部，請將子模塊的 git 目錄移動到其超級項目$GIT_DIR/modules路徑中，然后通過設(shè)置core.worktree和添加指向 git 目錄中的 .git 文件來連接 git 目錄及其工作目錄超級項目 git 目錄。

獨立克隆并隨后添加為子模塊或舊設(shè)置的存儲庫在子模塊內(nèi)部具有子模塊 git 目錄，而不是嵌入到 superprojects git 目錄中。

該命令默認是遞歸的。

選項

-q   --quiet

只打印錯誤消息。

--all

該選項僅對 deinit 命令有效。取消注冊工作樹中的所有子模塊。

-b   --branch

將存儲庫的分支添加為子模塊。分支的名稱記錄submodule.<name>.branch在.gitmodules了update --remote。特殊值.用于指示子模塊中分支的名稱應(yīng)與當前存儲庫中當前分支的名稱相同。

-f   --force

該選項僅適用于添加，刪除和更新命令。在運行 add 時，允許添加一個否則忽略的子模塊路徑。在運行 deinit 時，即使子模塊包含本地更改，也將刪除子模塊工作樹。在運行 update 時（只對 checkout 程序有效），在切換到其他提交時丟棄子模塊中的本地更改; 并且始終在子模塊中運行檢出操作，即使包含存儲庫的索引中列出的提交與在子模塊中檢出的提交匹配也是如此。

--cached

該選項僅對狀態(tài)和匯總命令有效。這些命令通常使用在子模塊 HEAD 中找到的提交，但使用此選項時，將使用存儲在索引中的提交。

--files

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

-n   --summary-limit

該選項僅對匯總命令有效。限制摘要大?。偣诧@示的提交數(shù)量）。給出0會禁用摘要; 負數(shù)表示無限制（默認）。此限制僅適用于修改的子模塊。添加/刪除/類型轉(zhuǎn)換子模塊的大小始終限制為1。

--remote

該選項僅對更新命令有效。使用子模塊的遠程跟蹤分支的狀態(tài)，而不是使用超級項目的已記錄的 SHA-1 來更新子模塊。使用的遠程是分支的遠程（branch.<name>.remote），默認為origin。遠程分支使用默認為master，但分支名稱可以通過設(shè)置覆蓋submodule.<name>.branch選項在任一.gitmodules或.git/config（與.git/config采取優(yōu)先次序）。

這適用于任何支持的更新程序（--checkout，--rebase，等）。唯一的變化是目標 SHA-1 的來源。例如，submodule update --remote --merge將上submodule update --merge游子模塊更改合并到子模塊中，同時將超級項目 gitlink 更改合并到子模塊中。

為了確保當前的跟蹤分支狀態(tài)，update --remote在計算 SHA-1 之前獲取子模塊的遠程存儲庫。如果你不想獲取，你應(yīng)該使用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

該選項僅對更新命令有效。不要從遠程站點獲取新的對象。

--checkout

該選項僅對更新命令有效。檢查子模塊中分離的 HEAD 上超級項目中記錄的提交。這是默認行為，此選項的主要用途是將其submodule.$name.update設(shè)置為除以外的值時覆蓋checkout。如果密鑰submodule.$name.update未明確設(shè)置或設(shè)置為checkout，則此選項是隱含的。

--merge

該選項僅對更新命令有效。將超級項目中記錄的提交合并到子模塊的當前分支中。如果給出該選項，子模塊的 HEAD 將不會被分離。如果合并失敗阻止了此過程，則必須使用通常的沖突解決工具來解決子模塊內(nèi)產(chǎn)生的沖突。如果該鍵submodule.$name.update設(shè)置為merge，則此選項是隱含的。

--rebase

該選項僅對更新命令有效。將當前分支重新映射到超級項目中記錄的提交。如果給出該選項，子模塊的 HEAD 將不會被分離。如果合并失敗阻止了這個過程，你將不得不用 git-rebase 來解決這些失敗[1]。如果該鍵submodule.$name.update設(shè)置為rebase，則此選項是隱含的。

--init

該選項僅對更新命令有效。在更新之前，初始化尚未調(diào)用“git子模塊init”的所有子模塊。

--name

該選項僅對 add 命令有效。它將子模塊的名稱設(shè)置為給定字符串，而不是默認其路徑。該名稱必須是有效的目錄名稱，可能不會以/。

--reference <repository>

該選項僅適用于添加和更新命令。這些命令有時需要克隆遠程存儲庫。在這種情況下，這個選項將被傳遞給 git-clone [1] 命令。

注意：不要不，除非你已經(jīng)閱讀說明了混帳克隆[1]的使用此選項--reference與--shared選項仔細。

--recursive

此選項僅適用于foreach，更新，狀態(tài)和同步命令。遞歸地遍歷子模塊。該操作不僅在當前回購的子模塊中執(zhí)行，而且在子模塊內(nèi)的任何嵌套子模塊中執(zhí)行（依此類推）。

--depth

該選項對添加和更新命令有效。創(chuàng)建一個shallow歷史截斷為指定修訂版本的克隆。參見 git-clone [1]

--no-recommend-shallow

該選項僅對更新命令有效。默認情況下，子模塊的初始克隆將使用submodule.<name>.shallow由.gitmodules文件提供的建議。忽略建議使用--no-recommend-shallow。

-j <n>   --jobs <n>

該選項僅對更新命令有效。與多個作業(yè)并行克隆新的子模塊。默認為submodule.fetchJobs選項。

<path>…

子模塊的路徑。指定時，將限制該命令僅對在指定路徑中找到的子模塊進行操作。（這個參數(shù)是需要添加的）。

文檔

初始化子模塊時，將.gitmodules使用包含存儲庫的頂級目錄中的文件來查找每個子模塊的 url 。這個文件的格式應(yīng)該和$GIT_DIR/config。每個子模塊網(wǎng)址的關(guān)鍵是“submodule。$ name.url”。有關(guān)詳細信息，請參閱 gitmodules [5]。