submodule sync 是什么
.gitmodules 里的 URL 修改后，各克隆的本地配置仍指向旧地址；git submodule sync 把新 URL 同步到 .git/config 与 .git/modules 下的子模块配置，让后续 update 走新地址。仓库迁移、切换镜像源、内外网双地址场景都靠它，忘记同步会导致子模块拉取仍然访问旧域名。
基本信息
| 语法 | git submodule sync [--recursive] |
|---|---|
| 前提 | 先更新 .gitmodules（或直接改配置） |
| 配套 | git submodule update --init --recursive 重新拉取 |
| 作用点 | 本地配置与子模块仓库缓存中的 URL 一起更新 |
| 核对 | git submodule foreach 'git remote -v' 查看子模块远端 |
| 注意 | 不带 --recursive 时嵌套子模块不更新 |
典型使用场景
- 仓库迁移：主仓库换域名后子模块 URL 一并同步
- 镜像切换：内网镜像与公网地址切换，本地配置要跟上
- CI 环境：缓存的工作区沿用旧 URL 时，同步后再拉取
- 排错：子模块拉取报错域名不可达时先看同步状态
- 审计脚本：批量检查各克隆的 URL 是否与新规范一致
- 迁移演练：先在测试克隆完整跑通同步与重拉流程，确认无误再批量通知所有克隆者执行
常用示例
常用示例
# 修改 .gitmodules 后同步并重新拉取
git submodule sync --recursive
git submodule update --init --recursive
git submodule foreach 'git remote -v | head -1' # 逐个核对子模块远端不同步会怎样
| 现象 | 原因 | 处理 |
|---|---|---|
| 拉取仍走旧域名 | 只改了 .gitmodules 没 sync | sync 后用 update 重拉 |
| 新克隆一切正常 | 新克隆直接读新配置 | 老克隆逐个 sync |
| 子模块内有本地改动 | 子模块自己改过 remote | 单独核对，以父仓库配置为准 |
sync 以父仓库 .gitmodules 为准：子模块内部另行改过的 remote 会被覆盖，操作前先看清楚。
仓库迁移建议配套清单：同步 URL、清理旧账号凭据、通知所有克隆者执行 sync 与 update。
多层嵌套仓库要逐层确认：主仓库、子模块、子模块的子模块各有一份配置，同步时自顶向下逐层检查，任何一层漏掉都会在该层拉取时失败。