如何移除 Git 子模块（submodule）

先确认子模块内没有未提交或未推送的工作，并备份必要内容。 以下步骤移除当前版本中的子模块；清理内部 Git 存储是可选的，保留它有利于检出历史版本。

git submodule deinit -f -- vendor/lib     # 1. 反初始化（清 .git/config 注册）
git rm -f vendor/lib                       # 2. 从索引和工作区删除（含 .gitmodules 条目）
# 可选：确认不需要子模块中的本地历史后，再清理其内部存储
git commit -m "移除 vendor/lib 子模块"      # 4. 提交

验证清理干净

cat .gitmodules                 # 应不再有该子模块条目；空文件可自行决定是否删除
git config --list | grep submodule   # 无该子模块配置
git status                        # 干净

只删目录会留下什么

• .gitmodules 里的条目 → 别人 clone 时报错；
• .git/config 里的注册信息；
• .git/modules/<路径> 下的完整仓库数据（占磁盘）。

移除后想恢复

git submodule add <仓库地址> vendor/lib    # 重新添加

历史里也有记录：git log -- .gitmodules 能翻到曾经的子模块配置。

常见问题（FAQ）

Q：git rm 报 "not removing recursively"？

子模块目录内有改动或未提交内容时 Git 会拒绝，确认无用后加 -f。

Q：能把子模块"转正"为普通目录吗？

可以：按上面移除后，把子模块仓库的代码复制进来 git add 提交（历史不带过来；要历史用 git subtree 合并）。

Q：.gitmodules 空了要提交删除吗？

git rm 会自动处理 .gitmodules 条目的移除并暂存；如果文件已空且不再需要，可显式删除并提交。

参考资料

• Git submodule 官方文档
• Git rm 官方文档
• Git commit 官方文档
• Git config 官方文档