Git子模块更新命令差异、参数解析及CI场景疑问

一、三个命令的核心区别（通俗版） #

1. git submodule update --remote --recursive #

这个命令的核心是**“跟着子模块自己的远程仓库走”**：

• 直接拉取每个子模块关联的远程仓库的最新代码（比如子模块绑定的GitHub仓库的最新提交）
• 自动处理嵌套子模块（子模块里还有子模块的话，也会一起更新）
• 不管主仓库里记录的子模块版本是什么，直接把子模块更到它自己的最新版

2. git pull --recurse-submodules #

这个命令是**“跟着主仓库的要求走”**：

• 先拉取主仓库的最新代码
• 然后根据主仓库最新commit里记录的子模块版本号，把每个子模块切换到对应的版本（比如主仓库要求子模块用v1.2，就更到v1.2，哪怕子模块远程有更新也不管）

3. git submodule foreach git pull origin main #

这个是**“手动强制拉取指定分支”**：

• 给每个子模块单独执行git pull origin main，强制拉取子模块远程仓库的main分支最新代码
• 只处理当前层级的子模块，嵌套子模块不会自动更新
• 如果子模块用的不是main分支（比如master），这个命令会直接报错

二、哪个命令适合你？ #

• 如果你想让所有子模块都跟上它们自己的最新代码（不管主仓库记录的版本）：用git submodule update --remote --recursive
• 如果你想让子模块和主仓库保持严格同步（主仓库指定哪个版本就用哪个）：用git pull --recurse-submodules
• 第三个命令仅适合你需要手动指定子模块拉取分支的特殊场景，日常不推荐，容易因为分支名不匹配出错

三、关键参数解释 #

--remote（仅针对git submodule update） #

默认情况下，git submodule update是按照主仓库里记录的子模块版本号来切换的。加上--remote后，它会忽略主仓库的记录，直接去拉取子模块远程仓库的默认分支（一般是main或master）的最新代码。

--recursive #

和你猜测的一样，这个参数是用来处理嵌套子模块的。比如子模块A里面还有子模块B，加了这个参数后，更新A的同时会自动更新B，不用你手动进入A的目录再跑更新命令。

四、常见疑问解答 #

1. 子模块仓库已存在时，git submodule update会更新到最新提交吗？ #

• 不带--remote：不会，它会把子模块切换到主仓库当前记录的那个版本（可能不是子模块远程的最新版）
• 带--remote：会，直接把子模块更新到它自己远程仓库的最新提交

2. GitHub Actions中，仅靠.gitmodules文件，git submodule update会更新到最新提交吗？ #

不会。CI/CD环境每次都是全新的，默认的git submodule update只会按照主仓库当前commit记录的子模块版本，克隆子模块并切换到对应版本，不会主动拉取子模块的最新远程代码。如果想要拉子模块的最新版，需要加上--remote参数，比如执行git submodule update --init --remote --recursive（--init是确保初次克隆子模块）

内容的提问来源于stack exchange，提问作者Zo-Bro-23