Git 模块配置文件（gitmodules） - 定义子模块属性

名称

gitmodules - 定义子模块属性

概要

$GIT_WORK_DIR/.gitmodules 文件，作用是定义子模块的属性

描述

.gitmodules 文件位于 Git 工作树的顶层目录中，是一个文本文件，其语法符合 git-config(1) 的要求。

该文件包含每个子模块的一个子节，子节值为子模块的名称。名称设置为添加子模块的路径，除非使用 git submodule add 命令的 --name 选项进行了自定义。每个子模块部分还包含以下必需键：

• submodule.<name>.path：定义子模块相对于 Git 工作树顶层目录的路径，在该路径下子模块预计将被检出。路径名不能以 / 结尾。.gitmodules 文件中所有子模块路径必须是唯一的。

• submodule.<name>.url：定义从中克隆子模块仓库的 URL。这可以是一个绝对 URL，可以直接传递给 git-clone(1)，或者（如果以 ./ 或 ../ 开头）是相对于父项目源仓库的位置。

此外，还有一些可选键：

• submodule.<name>.update：定义命名子模块的默认更新过程，即父项目中的 “git submodule update” 命令如何更新子模块。这仅由 git submodule init 使用，以初始化同名的配置变量。此处允许的值为 checkout、rebase、merge 或 none。有关它们的含义，请参见 git-submodule 中的 update 命令的描述。出于安全原因，此处不接受 !command 形式。

• submodule.<name>.branch：用于跟踪上游子模块更新的远程分支名称。如果未指定该选项，则默认为 master。特殊值 . 用于表示子模块中的分支名称应与当前仓库中的当前分支名称相同。有关详细信息，请参阅 git-submodule 中的 —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 的历史记录），除非用户明确要求进行非浅克隆。

示例

考虑以下 .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，gitsubmodules，git-config(1)