简体中文 ▾ 主题 ▾ 最新版本 ▾ gitmodules 最后更新于 2.42.0

名称

gitmodules - 定义子模块属性

概要

$GIT_WORK_TREE/.gitmodules

描述

.gitmodules 文件位于 Git 工作树的顶级目录下，是一个文本文件，其语法符合 git-config[1] 的要求。

该文件为每个子模块包含一个子节（subsection），子节的值即为子模块的名称。除非在执行 git submodule add 时使用了 --name 选项进行了自定义，否则该名称通常被设置为子模块添加时的路径。每个子模块节还包含以下必需的键：

submodule.<name>.path

定义子模块预期检出的路径（相对于 Git 工作树的顶级目录）。路径名不得以 / 结尾。在 .gitmodules 文件中，所有子模块路径必须是唯一的。

submodule.<name>.url

定义克隆子模块仓库的 URL。这可以是一个准备传递给 git-clone[1] 的绝对 URL，或者（如果以 ./ 或 ../ 开头）一个相对于父项目源仓库（origin repository）的位置。

此外，还有许多可选键：

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

子模块永远不会被视为已修改（但在已暂存时，仍会显示在 status 和 commit 的输出中）。

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] 套件的一部分