在 Git 仓库中，子模块（submodule）是一种将另一个 Git 仓库嵌入到当前仓库中的机制。本教程介绍如何检查一个 Git 仓库是否存在子模块，以及如何解决子模块配置损坏的问题。
1️⃣ 检查 Git 仓库是否存在子模块
✅ 方法 1：查看 .gitmodules 文件
子模块信息记录在仓库根目录下的 .gitmodules 文件中。
ls -a | grep .gitmodules
或直接查看文件内容：
cat .gitmodules
如果存在该文件且有内容，说明仓库配置了子模块。
✅ 方法 2：使用 git submodule 命令查看
git submodule
- 如果有子模块，会输出子模块的 commit 和路径。
- 如果没有子模块，输出为空。
✅ 方法 3：查看 .git/config 中是否配置了 submodule
git config --file .git/config --get-regexp submodule
如果有输出，说明有子模块配置。
✅ 方法 4：通过 git ls-tree 检查
查看当前 HEAD 下的文件类型：
git ls-tree HEAD
如果输出中存在 160000 commit 类型，表示该路径是子模块。
示例输出：
160000 commit a1b2c3d4e5f6 submodules/my-submodule
2️⃣ 问题场景：git submodule 报错
如果执行 git submodule 时出现以下错误：
fatal: no submodule mapping found in .gitmodules for path 'themes/hugo-theme-stack'
表示：
- Git 索引中存在子模块目录（
themes/hugo-theme-stack） - 但
.gitmodules文件中没有对应配置
这是子模块引用 损坏 或 不完整 的典型现象。
3️⃣ 解决方案
根据实际需求选择对应方案：
🟢 情况 1：不需要子模块
如果该子模块不需要，可以完全清理：
git rm --cached themes/hugo-theme-stack
rm -rf themes/hugo-theme-stack
--cached表示仅从 Git 索引中移除，不会删除工作目录外文件。
🟢 情况 2：需要子模块，但 .gitmodules 丢失
重新添加子模块：
git submodule add https://github.com/<user>/hugo-theme-stack.git themes/hugo-theme-stack
如果目录已存在，可以先删除目录后添加，或者用 --force：
rm -rf themes/hugo-theme-stack
git submodule add https://github.com/<user>/hugo-theme-stack.git themes/hugo-theme-stack
然后初始化并更新：
git submodule init
git submodule update
🟢 情况 3：仓库中曾有 .gitmodules 文件，但被误删
查看历史是否存在 .gitmodules：
git log -- .gitmodules
如果找到了历史版本，恢复文件：
git checkout <commit-id> -- .gitmodules
再运行：
git submodule init
git submodule update
4️⃣ 验证结果
重新检查子模块是否正常：
git submodule
git ls-tree HEAD
确保 .gitmodules 文件和 Git 索引中的子模块引用一致。
🎉 结语
通过以上步骤，成功：
- ✅ 清理了错误添加的子模块
- ✅ 重新添加并正确配置
.gitmodules - ✅ 确保主仓库和子模块状态一致