簡體中文 ▾ 主題 ▾ 最新版本 ▾ gitmodules 最後更新於 2.42.0

名稱

gitmodules - 定義子模組屬性

概要

$GIT_WORK_TREE/.gitmodules

描述

位於 Git 工作樹頂層目錄中的 .gitmodules 檔案是一個文字檔案，其語法符合 git-config[1] 的要求。

該檔案包含每個子模組一個子部分，子部分的名稱是子模組的名稱。名稱設定為子模組新增到的路徑，除非使用 git submodule add 的 --name 選項進行了自定義。每個子模組部分還包含以下必需的鍵

submodule.<name>.path

定義了子模組在 Git 工作樹的頂層目錄中應簽出的路徑。路徑名稱不能以 / 結尾。所有子模組路徑在 .gitmodules 檔案中必須是唯一的。

submodule.<name>.url

定義了可以用來克隆子模組倉庫的 URL。這可以是直接傳遞給 git-clone[1] 的絕對 URL，或者（如果以 ./ 或 ../ 開頭）相對於父專案源倉庫的路徑。

此外，還有一些可選的鍵

submodule.<name>.update

定義了命名子模組的預設更新過程，即在父專案中，git submodule update 命令如何更新子模組。這僅用於 git submodule init 來初始化同名配置變數。此處允許的值為 checkout、rebase、merge 或 none，但出於安全原因不允許 !command。有關更多詳細資訊，請參見 git-submodule[1] 中 update 命令的描述。

submodule.<name>.branch

用於跟蹤上游子模組更新的遠端分支名稱。如果未指定該選項，則預設為遠端 HEAD。特殊值 . 用於指示子模組中的分支名稱應與當前倉庫中當前分支的名稱相同。有關詳細資訊，請參閱 git-submodule[1] 中 --remote 的文件。

submodule.<name>.fetchRecurseSubmodules

此選項可用於控制此子模組的遞迴獲取。如果此選項也存在於父專案的 .git/config 中該子模組的條目中，則該處的設定將覆蓋 .gitmodules 中的設定。這兩個設定都可以透過在 git fetch 和 git pull 命令中使用 --[no-]recurse-submodules 選項在命令列中進行覆蓋。

submodule.<name>.ignore

定義了 git status 和 diff 系列在何種情況下會將子模組顯示為已修改。支援以下值

all

子模組將永遠不會被視為已修改（但仍會在狀態和提交輸出中顯示，當它已被暫存時）。

dirty

將忽略對子模組工作樹的所有更改，只考慮子模組的 HEAD 與其在父專案中記錄的狀態之間的已提交差異。

untracked

將忽略子模組中未跟蹤的檔案。已跟蹤檔案的已提交差異和修改將顯示出來。

none

不忽略子模組的任何修改，將顯示所有已提交的差異以及已跟蹤和未跟蹤檔案的修改。這是預設選項。

如果此選項也存在於父專案的 .git/config 中該子模組的條目中，則該處的設定將覆蓋 .gitmodules 中的設定。

這兩個設定都可以透過使用 --ignore-submodules 選項在命令列中進行覆蓋。git submodule 命令不受此設定的影響。

submodule.<name>.shallow

設定為 true 時，將作為淺克隆（歷史深度為 1）執行此子模組的克隆，除非使用者明確要求非淺克隆。

注意事項

Git 不允許工作樹中的 .gitmodules 檔案是符號連結，並且會拒絕簽出此類樹條目。這使得在從索引或樹訪問檔案與從檔案系統訪問檔案時行為保持一致，並幫助 Git 可靠地強制執行檔案內容的安全性檢查。

示例

考慮以下 .gitmodules 檔案

[submodule "libfoo"]
	path = include/foo
	url = git://foo.com/git/lib.git

[submodule "libbar"]
	path = include/bar
	url = git://bar.com/git/lib.git

這定義了兩個子模組，libfoo 和 libbar。它們應在 include/foo 和 include/bar 路徑下籤出，並且為這兩個子模組都指定了一個可用於克隆子模組的 URL。

另請參閱

git-submodule[1], gitsubmodules[7], git-config[1]

GIT

Git[1] 套件的一部分