git submodule update 失败:找不到仓库
快速摘要
你运行了 git submodule update,但 git 无法找到或获取某个子模块仓库 —— 远程 URL 错误或提交缺失。
为什么发生
.gitmodules 中的子模块远程 URL 指向私有仓库(你无权访问)或已删除的服务器
超级项目引用的子模块提交被强制推送覆盖,在远程已不存在
仓库迁移或重命名后 .gitmodules 文件的路径或 URL 条目不正确
最小示例
✗ 错误代码
git submodule update --init # fatal: repository 'https://example.com/old/repo.git' not found✓ 修复代码
git submodule set-url sub/old https://example.com/new/repo.git
git submodule sync
git submodule update --init # succeeds更新子模块 URL 到新位置并同步后,git 会从正确的远程获取再检出引用的提交。
如何诊断
运行 cat .gitmodules 检查配置的子模块 URL 和路径是否正确
尝试 git ls-remote <submodule-url> 验证远程仓库是否可访问
运行 git submodule status 查看哪些子模块的提交不匹配或缺失
如何修复
用 git submodule set-url <path> <new-url> 更新 .gitmodules 中的 URL,然后 git submodule sync
如果远程可访问但引用过期,手动 git clone <url> <path> 重新克隆子模块
请子模块维护者恢复引用的提交,或更新超级项目指向已存在的提交
如何预防
保持 .gitmodules 中的 URL 指向稳定可访问的仓库,迁移后及时更新
避免强制推送超级项目引用的子模块分支
相关资源
相关课程
- git submodule
学习如何管理子模块。