.gitmodules 文件是 Git 子模块（submodule）功能的核心配置文件。它位于 Git 仓库的根目录下，用于声明和管理项目所依赖的所有子模块。
这个文件记录了每个子模块的名称、本地路径和远程仓库地址 等元数据。它的格式与 git-config 语法一致，本质上是一个 INI 格式的文本文件。
📄 文件格式与配置项
一个典型的 .gitmodules 文件内容如下：
ini
[submodule "libfoo"]
path = include/foo
url = git://foo.com/git/lib.git每个子模块的配置都包含在一个 [submodule "<name>"] 的节（section）中。其中包含以下核心配置项：
| 配置项 | 是否必需 | 说明 |
|---|---|---|
submodule.<name>.path |
是 | 子模块克隆到主项目后的相对路径 。路径必须以 / 结尾，且所有子模块的路径必须唯一。 |
submodule.<name>.url |
是 | 子模块远程仓库的 URL。可以是绝对路径，也可以是相对于主项目源仓库的相对路径（以 ./ 或 ../ 开头）。 |
submodule.<name>.update |
否 | 定义 git submodule update 的默认更新策略。可选值有 checkout、rebase、merge 或 none。 |
submodule.<name>.branch |
否 | 指定用于跟踪上游更新的远程分支名 。如果未指定，则默认跟踪远程仓库的 HEAD。特殊值 . 表示使用与当前仓库同名的分支。 |
submodule.<name>.ignore |
否 | 控制 git status 等命令何时将子模块视为已修改。可选值包括 all、dirty、untracked 和 none。 |
🛠️ 常用操作
.gitmodules 文件通常不直接手动编辑，而是通过 Git 命令来管理。
-
添加子模块 ：使用
git submodule add <repository> [<path>]命令。Git 会自动克隆子模块仓库，并在仓库根目录创建或更新.gitmodules文件。 -
克隆包含子模块的项目 ：克隆主项目后，子模块目录是空的。需要运行以下命令来初始化和更新子模块：
bashgit submodule init git submodule update或者在克隆时一步到位：
git clone --recurse-submodules <repository>。 -
更新子模块 ：进入主项目目录，运行
git submodule update --remote可将所有子模块更新到其跟踪分支的最新提交。 -
同步子模块 URL ：如果子模块的远程仓库地址发生了变化，需要手动修改
.gitmodules文件中的 URL，然后运行git submodule sync来同步配置。 -
删除子模块 ：需要多步操作，较为繁琐：
git submodule deinit -f -- <path>：从.git/config中移除子模块配置。rm -rf .git/modules/<path>：删除该子模块在.git/modules目录下的缓存。git rm -f <path>：从主项目的暂存区和工作区中移除子模块目录，并同时删除.gitmodules文件中的对应条目。
⚠️ 注意事项
- 文件需纳入版本控制 ：
.gitmodules文件必须被提交到主项目的版本库中，这样其他协作者才能获取子模块的信息。 - 配置优先级 ：关于子模块的配置可能存在于多个地方，其优先级从高到低为：命令行选项 > 主项目
.git/config文件 >.gitmodules文件 。这意味着本地可以覆盖.gitmodules中的默认设置。 - 子模块是静态的 ：子模块指向的是特定的提交，而不是一个分支。主项目记录的是子模块仓库的某个具体提交哈希值。因此，即使子模块的原仓库有更新，主项目中的引用也不会自动改变，需要手动更新。
- 谨慎手动编辑 ：虽然可以直接编辑
.gitmodules文件，但更推荐使用git submodule命令来进行管理，以避免配置错误。
💎 总结
.gitmodules 是 Git 实现模块化与依赖管理的关键。通过它，你可以清晰地声明项目所需的外部仓库，实现对依赖版本的精确控制。
建议你在日常使用中，多通过 git submodule 系列命令来与 .gitmodules 交互，而非直接编辑文件，这样更安全、也更规范。