# git-submodule > 原文： [https://git-scm.com/docs/git-submodule](https://git-scm.com/docs/git-submodule) ## 名稱 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>…?] ``` ## 描述 檢查，更新和管理子模塊。 有關子模塊的更多信息，請參閱 [gitsubmodules [7]](https://git-scm.com/docs/gitsubmodules) 。 ## COMMANDS ``` add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>] ``` 將給定存儲庫添加為給定路徑下的子模塊，該路徑指向要在當前項目旁邊提交的變更集：當前項目稱為“超級項目”。 &lt;庫&gt;是新子模塊的原始存儲庫的URL。這可以是絕對URL，或者（如果它以./或../開頭），相對于超級項目的默認遠程存儲庫的位置（請注意，指定存儲庫 _foo.git_ ，這是位于超級項目 _bar.git_ 旁邊，您必須使用 _../foo.git_ 而不是 _./foo.git_ - 作為一個在遵循相對URL規則時可能會有所期望 - 因為Git中相對URL的評估與相對目錄的相同。 默認遠程是當前分支的遠程跟蹤分支的遠程。如果不存在這樣的遠程跟蹤分支或者HEAD被分離，則假定“origin”是默認遠程。如果超級項目沒有配置默認遠程，則超級項目是其自己的權威上游，而是使用當前工作目錄。 可選參數&lt; path&gt;是克隆子模塊在超級項目中存在的相對位置。如果&lt; path&gt;如果未給出，則使用源存儲庫的規范部分（“repo”表示“/path/to/repo.git”，“foo”表示“host.xz：foo / .git”）。如果&lt; path&gt;存在并且已經是一個有效的Git存儲庫，然后它將在沒有克隆的情況下進行提交。 &lt;路徑&gt;除非`--name`用于指定邏輯名稱，否則它也會在其配置條目中用作子模塊的邏輯名稱。 給定的URL記錄在`.gitmodules`中，供后續用戶克隆超級項目使用。如果URL是相對于超級項目的存儲庫給出的，則推測是超級項目，子模塊存儲庫將保存在同一相對位置，并且只需要提供超級項目的URL。 git-submodule將使用`.gitmodules`中的相對URL正確定位子模塊。 ``` status [--cached] [--recursive] [--] [<path>…?] ``` 顯示子模塊的狀態。這將打印每個子模塊當前檢出的提交的SHA-1，以及子模塊路徑和SHA-1的 _git describe_ 的輸出。如果子模塊未初始化，則每個SHA-1可能以`-`為前綴，如果當前檢出的子模塊提交與包含存儲庫的索引中找到的SHA-1不匹配，則`+`和`U`如果子模塊有合并沖突。 如果指定了`--recursive`，則此命令將遞歸到嵌套的子模塊中，并顯示其狀態。 如果您只對當前初始化的子模塊相對于索引或HEAD中記錄的提交的更改感興趣， [git-status [1]](https://git-scm.com/docs/git-status) 和 [git-diff [1]](https://git-scm.com/docs/git-diff) 也將提供該信息（并且還可以報告對子模塊工作樹的更改）。 ``` init [--] [<path>…?] ``` 通過在.git / config中設置`submodule.$name.url`來初始化索引中記錄的子模塊（已在其他地方添加并提交）。它使用`.gitmodules`中的相同設置作為模板。如果URL是相對的，則將使用默認遠程解析。如果沒有默認遠程，則假定當前存儲庫位于上游。 可選&lt;路徑&gt;參數限制將初始化哪些子模塊。如果未指定路徑且已配置submodule.active，則將初始化配置為活動的子模塊，否則將初始化所有子模塊。 如果存在，它還將復制`submodule.$name.update`的值。此命令不會更改.git / config中的現有信息。然后，您可以在.git / config中自定義子模塊克隆URL以進行本地設置，然后繼續`git submodule update`;如果您不打算自定義任何子模塊位置，也可以在沒有顯式 _init_ 步驟的情況下使用`git submodule update --init`。 有關默認遠程的定義，請參閱add子命令。 ``` deinit [-f|--force] (--all|[--] <path>…?) ``` 取消注冊給定的子模塊，即從.git / config中刪除整個`submodule.$name`部分及其工作樹。對`git submodule update`，`git submodule foreach`和`git submodule sync`的進一步調用將跳過任何未注冊的子模塊，直到它們再次初始化為止，因此如果您不想再在工作樹中本地檢出子模塊，請使用此命令。 當命令在沒有pathspec的情況下運行時，它會出錯，而不是去除所有內容，以防止出錯。 如果指定了`--force`，則即使子模塊包含本地修改，也將刪除該子模塊的工作樹。 如果你真的想要從存儲庫中刪除子模塊并提交使用 [git-rm [1]](https://git-scm.com/docs/git-rm) 。有關刪除選項，請參閱 [gitsubmodules [7]](https://git-scm.com/docs/gitsubmodules) 。 ``` update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>…?] ``` 通過克隆缺失的子模塊并更新子模塊的工作樹，更新已注冊的子模塊以匹配超級項目所期望的內容。 “更新”可以通過多種方式完成，具體取決于命令行選項和`submodule.&lt;name&gt;.update`配置變量的值。命令行選項優先于配置變量。如果兩者都沒有給出，則執行_檢出_。從命令行以及通過`submodule.&lt;name&gt;.update`配置支持的_更新_程序是： ``` checkout ``` 超級項目中記錄的提交將在分離的HEAD上的子模塊中檢出。 如果指定了`--force`，則子模塊將被檢出（使用`git checkout --force`），即使包含存儲庫的索引中指定的提交已經與子模塊中檢出的提交匹配。 ``` rebase ``` 子模塊的當前分支將重新定位到超級項目中記錄的提交。 ``` merge ``` 超級項目中記錄的提交將合并到子模塊中的當前分支中。 以下_更新_程序僅可通過`submodule.&lt;name&gt;.update`配置變量獲得： ``` custom command ``` 執行帶有單個參數的任意shell命令（超級項目中記錄的提交的sha1）。當`submodule.&lt;name&gt;.update`設置為_！命令_時，感嘆號后面的余數是自定義命令。 ``` none ``` 子模塊未更新。 如果子模塊尚未初始化，并且您只想使用`.gitmodules`中存儲的設置，則可以使用`--init`選項自動初始化子模塊。 如果指定了`--recursive`，則此命令將遞歸到已注冊的子模塊中，并更新其中的任何嵌套子模塊。 ``` summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>…?] ``` 顯示給定提交（默認為HEAD）和工作樹/索引之間的提交摘要。對于所討論的子模塊，顯示了給定超級項目提交與索引或工作樹（由`--cached`切換）之間的子模塊中的一系列提交。如果給出了選項`--files`，則顯示超級項目的索引與子模塊的工作樹之間的子模塊中的一系列提交（此選項不允許使用`--cached`選項或提供顯式承諾）。 在 [git-diff [1]](https://git-scm.com/docs/git-diff) 中使用`--submodule=log`選項也可以提供該信息。 ``` foreach [--recursive] <command> ``` 在每個簽出的子模塊中計算任意shell命令。該命令可以訪問變量$ name，$ sm_path，$ displaypath，$ sha1和$ toplevel：$ name是`.gitmodules`中相關子模塊部分的名稱，$ sm_path是直接記錄的子模塊的路徑superproject，$ displaypath包含從當前工作目錄到子模塊根目錄的相對路徑，$ sha1是直接超級項目中記錄的提交，$ toplevel是直接超級項目頂級的絕對路徑。請注意，為了避免與Windows上的 _$ PATH_ 沖突， _$ path_ 變量現在是 _$ sm_path_ 變量的棄用同義詞。此命令將忽略超級項目中定義但未檢出的任何子模塊。除非給出`--quiet`，否則foreach會在評估命令之前打印每個子模塊的名稱。如果給出了`--recursive`，則遞歸遍歷子模塊（即，給定的shell命令也在嵌套的子模塊中進行計算）。任何子模塊中命令的非零返回都會導致處理終止。這可以通過添加 _||來覆蓋：_到命令結束。 例如，下面的命令將顯示每個子模塊的路徑和當前檢出的提交： ``` git submodule foreach 'echo $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目錄移動到其superprojects `$GIT_DIR/modules`路徑，然后通過設置`core.worktree`并添加指向的.git文件來連接git目錄及其工作目錄。嵌入在superprojects git目錄中的git目錄。 獨立克隆并隨后作為子模塊或舊設置添加的存儲庫在子模塊內部具有子模塊git目錄，而不是嵌入到superprojects git目錄中。 默認情況下，此命令是遞歸的。 ## OPTIONS ``` -q ``` ``` --quiet ``` 僅打印錯誤消息。 ``` --progress ``` 此選項僅對添加和更新命令有效。除非指定了-q，否則在將標準錯誤流附加到終端時，默認情況下會報告進度狀態。即使標準錯誤流未定向到終端，此標志也會強制進度狀態。 ``` --all ``` 此選項僅對deinit命令有效。取消注冊工作樹中的所有子模塊。 ``` -b ``` ``` --branch ``` 存儲庫的分支添加為子模塊。分支名稱在`update --remote`中記錄為`update --remote`中的`submodule.&lt;name&gt;.branch`。 `.`的特殊值用于指示子模塊中分支的名稱應與當前存儲庫中的當前分支的名稱相同。 ``` -f ``` ``` --force ``` 此選項僅對add，deinit和update命令有效。運行add時，允許添加否則忽略的子模塊路徑。當運行deinit時，子模塊工作樹將被刪除，即使它們包含本地更改。運行更新時（僅對結帳過程有效），在切換到其他提交時，丟棄子模塊中的本地更改;并且始終在子模塊中運行checkout操作，即使包含存儲庫的索引中列出的提交與子模塊中簽出的提交匹配也是如此。 ``` --cached ``` 此選項僅對status和summary命令有效。這些命令通常使用子模塊HEAD中的提交，但使用此選項時，將使用存儲在索引中的提交。 ``` --files ``` 此選項僅對summary命令有效。當使用此選項時，此命令將索引中的提交與子模塊HEAD中的提交進行比較。 ``` -n ``` ``` --summary-limit ``` 此選項僅對summary命令有效。限制摘要大小（總計顯示的提交數）。給0將禁用摘要;負數表示無限制（默認值）。此限制僅適用于已修改的子模塊。對于添加/刪除/ typechanged子模塊，大小始終限制為1。 ``` --remote ``` 此選項僅對update命令有效。不使用超級項目記錄的SHA-1來更新子模塊，而是使用子模塊的遠程跟蹤分支的狀態。使用的遙控器是分支的遙控器（`branch.&lt;name&gt;.remote`），默認為`origin`。使用的遠程分支默認為`master`，但可以通過在`.gitmodules`或`.git/config`中設置`submodule.&lt;name&gt;.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.&lt;name&gt;.branch`，而`git pull`使用子模塊的`branch.&lt;name&gt;.merge`。如果您想在超級項目中分配默認上游分支，請選擇`submodule.&lt;name&gt;.branch`，如果您希望在子模塊本身工作時想要更原始的感覺，請選擇`branch.&lt;name&gt;.merge`。 ``` -N ``` ``` --no-fetch ``` 此選項僅對update命令有效。不要從遠程站點獲取新對象。 ``` --checkout ``` 此選項僅對update命令有效。在子模塊中的分離HEAD上簽出超級項目中記錄的提交。這是默認行為，此選項的主要用途是在設置為`checkout`以外的值時覆蓋`submodule.$name.update`。如果未將鍵`submodule.$name.update`顯式設置或設置為`checkout`，則此選項是隱式的。 ``` --merge ``` 此選項僅對update命令有效。將超級項目中記錄的提交合并到子模塊的當前分支中。如果給出此選項，則不會分離子模塊的HEAD。如果合并失敗阻止了此過程，則必須使用通常的沖突解決工具解決子模塊中產生的沖突。如果鍵`submodule.$name.update`設置為`merge`，則此選項是隱式的。 ``` --rebase ``` 此選項僅對update命令有效。將當前分支重新引導到超級項目中記錄的提交。如果給出此選項，則不會分離子模塊的HEAD。如果合并失敗阻止了此過程，則必須使用 [git-rebase [1]](https://git-scm.com/docs/git-rebase) 解決這些故障。如果鍵`submodule.$name.update`設置為`rebase`，則此選項是隱式的。 ``` --init ``` 此選項僅對update命令有效。初始化所有在更新之前尚未調用“git submodule init”的子模塊。 ``` --name ``` 此選項僅對add命令有效。它將子模塊的名稱設置為給定的字符串，而不是默認為其路徑。該名稱必須作為目錄名有效，并且不能以 _/_ 結尾。 ``` --reference <repository> ``` 此選項僅對添加和更新命令有效。這些命令有時需要克隆遠程存儲庫。在這種情況下，此選項將傳遞給 [git-clone [1]](https://git-scm.com/docs/git-clone) 命令。 **注**：**不是**使用此選項除非您已閱讀 [git-clone [1]](https://git-scm.com/docs/git-clone) 的`--reference`，`--shared`和`--dissociate`選項仔細。 ``` --dissociate ``` 此選項僅對添加和更新命令有效。這些命令有時需要克隆遠程存儲庫。在這種情況下，此選項將傳遞給 [git-clone [1]](https://git-scm.com/docs/git-clone) 命令。 **注**：參見`--reference`選項的注意事項。 ``` --recursive ``` 此選項僅對foreach，update，status和sync命令有效。遞歸遍歷子模塊。該操作不僅在當前倉庫的子模塊中執行，而且還在這些子模塊內的任何嵌套子模塊中執行（依此類推）。 ``` --depth ``` 此選項對添加和更新命令有效。創建一個_淺_克隆，其歷史記錄被截斷為指定的修訂數。見 [git-clone [1]](https://git-scm.com/docs/git-clone) ``` --[no-]recommend-shallow ``` 此選項僅對update命令有效。子模塊的初始克隆將使用默認情況下`.gitmodules`文件提供的推薦`submodule.&lt;name&gt;.shallow`。要忽略建議，請使用`--no-recommend-shallow`。 ``` -j <n> ``` ``` --jobs <n> ``` 此選項僅對update命令有效。與多個作業并行克隆新的子模塊。默認為`submodule.fetchJobs`選項。 ``` <path>…? ``` 子模塊的路徑。指定時，這將限制命令僅對指定路徑上找到的子模塊進行操作。 （添加時需要此參數）。 ## FILES 初始化子模塊時，使用包含存儲庫的頂級目錄中的`.gitmodules`文件來查找每個子模塊的URL。該文件的格式應與`$GIT_DIR/config`相同。每個子模塊url的關鍵是“submodule。$ name.url”。有關詳細信息，請參閱 [gitmodules [5]](https://git-scm.com/docs/gitmodules) 。 ## 也可以看看 [gitsubmodules [7]](https://git-scm.com/docs/gitsubmodules) ， [gitmodules [5]](https://git-scm.com/docs/gitmodules) 。 ## GIT 部分 [git [1]](https://git-scm.com/docs/git) 套件