git submodule add 后无 .gitmodules 文件，大概率因未在 git 仓库根目录执行命令或未手动 git add .gitmodules；该文件需显式暂存提交，否则不生效。
git submodule add 为什么没生成 .gitmodules 文件？
执行 git submodule add 后看不到 .gitmodules，大概率是因为当前目录不是 Git 仓库根目录，或者你漏掉了 git add .gitmodules 这一步。Git 不会自动提交该文件，它只是记录子模块路径和 URL 的配置项，必须手动暂存。
- 确认你在项目根目录下运行命令：
git submodule add https://github.com/user/repo.git path/to/submodule - 执行后检查是否生成了
.gitmodules和path/to/submodule目录（内容为空） - 立刻运行
git add .gitmodules和git add path/to/submodule—— 注意后者是空目录，Git 只跟踪其“存在”，不跟踪内部文件 - 如果已提交过但没生效，检查
.gitmodules是否被.gitignore错误匹配（比如写了.git*）
克隆主项目后子模块目录为空怎么办？
这是最常被忽略的环节：克隆主项目时，子模块目录默认是空的，Git 不会自动拉取。必须显式初始化并更新。
- 先运行
git submodule init—— 把.gitmodules中的配置读进.git/config - 再运行
git submodule update—— 拉取子模块代码并检出对应 commit - 更常用的一键写法：
git submodule update --init --recursive（含嵌套子模块） - 如果遇到
fatal: no submodule mapping found，说明.gitmodules缺失或路径不一致，先核对git config --file .gitmodules --get-regexp submodule
子模块 commit ID 被改了但主项目没提交，会发生什么？
子模块本身是个独立仓库，它的 HEAD 可以随意切换；但主项目只记录某个固定 commit ID。如果你在子模块里做了修改、切了分支、甚至 git pull 更新了代码，主项目仍指向旧 commit —— 这会导致协作时其他人 git submodule update 后看到的是旧状态，你的改动不会同步过去。
- 修改子模块后，先进入子模块目录：
cd path/to/submodule - 提交你的变更：
git add . && git commit -m "fix" - 推送到子模块远程：
git push - 回到主项目根目录，用
git add path/to/submodule把新的 commit ID 暂存（注意不是git add .，否则可能漏掉） - 然后
git commit -m "update submodule to latest"
想让子模块始终跟踪远程分支（比如 main），怎么配？
Git 默认不跟踪分支，只锁死 commit ID。若需动态跟随，得手动配置分支并定期同步，且主项目要记录新 commit —— 这不是“自动更新”，而是“可重复拉取最新”的工作流。
- 进入子模块：
cd path/to/submodule - 设置跟踪分支：
git config -f .gitmodules submodule.path/to/submodule.branch main（先写配置） - 拉取并切换：
git checkout main && git pull - 回到主项目，
git add path/to/submodule提交新 commit ID - 后续更新只需在主项目运行：
git submodule update --remote --merge（等价于进子模块执行git pull并自动提交新 ID 到主项目） - ⚠️ 注意：
--remote会忽略子模块当前分支，直接 fetch + merge 对应 branch 的最新 commit，容易引发冲突
git add 子模块路径本身，或者把 .gitmodules 当成自动生成文件而没纳入版本控制。
