Skip to content

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 指向稳定可访问的仓库,迁移后及时更新

  • 避免强制推送超级项目引用的子模块分支

相关资源

相关术语

相关课程

← 返回语言