执行 git submodule add 后本地无文件，因仅更新 .gitmodules 和索引，需运行 git submodule update --init（含嵌套加 --recursive）才能检出代码。
子模块添加后为什么本地没文件？
执行 git submodule add 只是把子模块信息写入 .gitmodules 和索引，不会自动检出代码。这是最常被忽略的一步。
- 必须手动运行
git submodule init（初始化配置） +git submodule update（拉取并检出） - 更常用的是合并为一条命令：
git submodule update --init - 如果子模块有嵌套，加
--recursive：git submodule update --init --recursive - 注意：如果子模块远程仓库权限不足或 URL 错误，
update会卡在 “Cloning into 'xxx'…” 并报Permission denied (publickey)或Repository not found
子模块更新时为什么总停留在旧 commit？
子模块在父仓库中记录的是一个**固定 commit hash**，不是分支名。即使子模块远程的 main 分支已更新，父仓库仍指向旧快照，除非你主动升级。
- 进入子模块目录，手动
git pull origin main（或对应分支），再回到父目录git add xxx-submodule提交——这是“升级子模块引用”的标准做法 - 想批量更新所有子模块到各自远程最新
HEAD：用git submodule update --remote（默认跟踪master；指定分支加--remote --branch develop） -
--remote本质是进每个子模块执行git fetch && git merge origin/xxx，所以可能产生冲突，不能全自动 - 别用
git pull --recurse-submodules代替——它只更新子模块的 commit 记录，不拉取子模块内部新代码
克隆含子模块的仓库时如何一步到位？
直接 git clone 主仓库后，子模块目录为空。常见但低效的做法是 clone 后再 init + update ——其实有更可靠的单步方案。
- 推荐：
git clone --recurse-submodules <url></url>（Git 2.19+ 默认行为，旧版本需显式加） - 如果已 clone 完毕，补救用：
git submodule sync && git submodule update --init --recursive（sync确保.git/config中子模块 URL 和.gitmodules一致，避免 fork 后 URL 滞后） - CI 场景下建议加
--jobs=4加速并发拉取：git submodule update --init --recursive --jobs=4
子模块提交后父仓库状态显示 modified，怎么回事？
子模块目录本身是个独立 Git 仓库，它的 HEAD 变动（比如你 cd 进去 git checkout dev）会让父仓库认为“子模块指针变了”，于是显示为 modified ——但这不是文件修改，而是 commit hash 不同了。
- 查看差异用：
git diff --submodule或git status中看到类似modified: xxx (new commits) - 若确认要提交这个新 hash，就
git add xxx（子模块路径），然后正常 commit - 若只是临时调试想退回，cd 进子模块
git reset --hard HEAD@{1}，再回父目录git restore --staged xxx即可撤销暂存 - 切记：子模块的 .git 不在自己目录下，而是在父仓库
.git/modules/xxx/里——误删子模块目录下的 .git 会导致损坏
