子模块需显式初始化才能拉取代码；克隆时应加--recurse-submodules参数，否则目录为空；更新用git submodule update --remote --merge；删除须同步清理.gitmodules、.git/config和缓存。
子模块不是自动加载的，克隆主仓库后目录为空是正常现象；必须显式执行 git submodule update --init --recursive 才能拉取代码。
添加子模块时路径已存在报错
常见错误：'path/to/submodule' already exists and is not empty。这是因为目标路径下已有文件或目录，Git 拒绝覆盖。
- 清空目标路径（确保无重要数据）后再执行
git submodule add - 改用新路径，比如从
libs/ui改为libs/ui-v2 - 若想保留现有内容并转为子模块，需先
rm -rf该目录，再git submodule add，最后把必要文件手动复制回去（注意别带 .git）
克隆含子模块的项目后子模块目录为空
这是最常被忽略的问题：普通 git clone 只下载主仓库，不碰子模块。子模块目录会创建，但里面没文件、没 .git、也没工作区。
- 推荐做法：首次克隆就加
--recurse-submodules参数，一步到位 - 已克隆完？进主目录后运行
git submodule update --init --recursive - 如果子模块还嵌套了子模块（多层），
--recursive不可省略；漏掉会导致内层仍为空
更新子模块到远程最新提交
默认情况下，子模块停留在主仓库记录的那个 commit 上，不会随远程分支自动前进。要更新，有两种常用方式：
- 进入子模块目录，手动
git fetch && git checkout origin/main（或指定分支），再回到主项目git add path/to/submodule && git commit - 在主项目根目录执行
git submodule update --remote --merge，它会自动进入每个子模块、fetch 并 merge 远程跟踪分支（默认是origin/HEAD） - 注意：
--remote默认跟踪的是子模块的master或main分支，如果子模块用了其他分支（如stable/v2），得先在.gitmodules里用branch = stable/v2显式声明，否则会出错或切错
删除子模块的正确顺序
直接 rm -rf 子模块目录只会让主仓库状态变脏，下次 git status 会一直提示“deleted: path/to/submodule”。必须同步清理三处：
- 删
.gitmodules中对应段落（如[submodule "libs/ui"]及其下几行） - 删
.git/config中对应 section（搜索submodule "libs/ui"） - 执行
git rm --cached path/to/submodule（注意有--cached，不加会连带删磁盘文件） - 最后
rm -rf path/to/submodule和git commit
子模块的引用本质是 Git 内部的一个“commit hash 指针”，它不包含任何实际代码；所以所有操作都围绕“指针是否准确”和“本地是否加载了对应 commit 的工作树”展开——这两点一旦脱节，就会出现看似克隆成功却无法构建的情况。
