如何在递归克隆Git子模块时重写其URL？

针对GitLab CI环境下需要将递归子模块的SSH格式URL替换为带CI_JOB_TOKEN的HTTP格式URL的需求，最简洁高效的方案是利用Git内置的URL替换配置，无需手动修改每一层子模块的.gitmodules文件。

核心方案：使用Git的url.insteadOf全局配置 #

Git的url.<base>.insteadOf配置可以自动将所有匹配指定前缀的URL替换为目标格式，递归子模块的拉取操作也会自动应用这个替换规则，完美解决多层子模块的URL转换问题。

具体操作步骤 #

在CI作业脚本中先执行以下配置命令，再进行克隆或子模块更新操作：

# 配置Git自动替换SSH URL为带CI_JOB_TOKEN的HTTP URL
git config --global url."https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.company.com/".insteadOf "git@gitlab.company.com:"

# 递归克隆顶层项目（所有子模块会自动使用转换后的HTTP URL）
git clone --recursive git@gitlab.company.com:your/main-project.git

# 若已克隆项目，更新递归子模块
# git submodule update --init --recursive

配置说明 #

• 该配置会把所有以git@gitlab.company.com:开头的SSH格式URL，替换为https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.company.com/开头的HTTP格式URL，自动适配SSH到HTTP的路径格式差异（冒号转斜杠）。
• CI_JOB_TOKEN是GitLab CI自动注入的环境变量，无需手动定义。
• 此配置为CI作业环境的全局配置，仅作用于当前作业的Git操作，不会影响其他环境。

备选方案：批量修改子模块配置（适合复杂场景） #

如果需要更精细地控制子模块URL，可通过git submodule foreach命令递归修改所有层级子模块的.gitmodules文件，但操作相对繁琐：

# 克隆顶层项目（不递归）
git clone git@gitlab.company.com:your/main-project.git
cd main-project

# 修改顶层项目的.gitmodules文件
sed -i 's/git@gitlab.company.com:/https:\/\/gitlab-ci-token:'"${CI_JOB_TOKEN}"'@gitlab.company.com\//' .gitmodules
git submodule sync

# 初始化并更新递归子模块，同时修改每一层子模块的.gitmodules
git submodule update --init --recursive
git submodule foreach --recursive '
  sed -i "s/git@gitlab.company.com:/https:\/\/gitlab-ci-token:'"${CI_JOB_TOKEN}"'@gitlab.company.com\//" .gitmodules
  git submodule sync
'

总结 #

优先推荐使用url.insteadOf全局配置方案，操作简洁且能自动覆盖所有递归子模块，无需手动处理多层嵌套的子模块配置。

内容的提问来源于stack exchange，提问作者Timmmm