简体中文 ▾ 主题 ▾ 最新版本 ▾ 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,或者(如果以 ./../ 开头)相对于超项目(superproject)源仓库的位置。

此外,还有一些可选键:

submodule.<name>.update

定义指定子模块的默认更新过程,即超项目(superproject)中的 git submodule update 命令如何更新子模块。这仅由 git submodule init 用于初始化同名配置变量。允许的值为 checkoutrebasemergenone,但不允许 !command(出于安全原因)。有关详细信息,请参阅 git-submodule[1]update 命令的说明。

submodule.<name>.branch

用于跟踪上游子模块更新的远程分支名称。如果未指定此选项,则默认为远程 HEAD。特殊值 . 用于指示子模块中的分支名称应与当前仓库中的当前分支名称相同。有关详细信息,请参阅 git-submodule[1]--remote 的文档。

submodule.<name>.fetchRecurseSubmodules

此选项可用于控制此子模块的递归获取。如果此选项也存在于超项目(superproject)的 .git/config 中子模块的条目中,则该设置将覆盖 .gitmodules 中找到的设置。这两个设置都可以通过在命令行中使用 git fetchgit pull--[no-]recurse-submodules 选项来覆盖。

submodule.<name>.ignore

定义在何种情况下 git status 和 diff 系列命令会将子模块显示为已修改。支持以下值:

all

子模块永远不会被视为已修改(但当它被暂存时,仍然会显示在 status 和 commit 的输出中)。

dirty

子模块工作树的所有更改都将被忽略,只考虑子模块的 HEAD 与其在超项目(superproject)中记录的状态之间的已提交差异。

untracked

只忽略子模块中未跟踪的文件。已提交的差异和对已跟踪文件的修改将显示出来。

none

不忽略对子模块的任何修改,所有已提交的差异以及对已跟踪和未跟踪文件的修改都将显示。这是默认选项。

如果此选项也存在于超项目(superproject)的 .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