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

名称

gitmodules - 定义子模块属性

概要

$GIT_WORK_TREE/.gitmodules

描述

.gitmodules 文件位于 Git 工作树的顶层目录中,是一个文本文件,其语法符合 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 fetchgit 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

这定义了两个子模块,libfoolibbar。 它们预计在路径 include/fooinclude/bar 中检出,并且为两个子模块指定了可用于克隆子模块的 URL。

GIT

属于 git[1] 套件的一部分

scroll-to-top