如何通过Git Submodule-Update命令将子仓库同步至指定版本号？

本文共计890个文字，预计阅读时间需要4分钟。

在Git中，子模块（Submodule）默认不会自动随父仓库更新而同步到其记录的提交点；必须显式执行`git submodule update`才能将子模块检出为父仓库记录的精确commit。若需确保子模块处于特定版本（如某分支最新、某tag或某commit），先让父仓库记录该版本，再进行更新。

确认子模块当前记录的提交是否为目标版本

子模块的实际版本由父仓库中 .gitmodules 和 git 内部的 submodule commit 记录共同决定。仅修改 .gitmodules 不生效，必须提交更新后的 submodule commit hash。

• 运行 git submodule status 查看每个子模块当前状态：开头的 - 表示未初始化，+ 表示已检出但与父仓库记录不一致， （空格）表示匹配
• 进入子模块目录，用 git log -n 3 --oneline 或 git describe --tags 确认当前 HEAD 是否为你想要的版本点（如 v2.1.0 或 abc1234）
• 若不匹配，先在子模块内切换：git checkout v2.1.0（tag）、git checkout main && git pull（分支最新）、或 git checkout abc1234（commit）

将子模块新版本“固定”到父仓库

子模块版本变更后，父仓库并不自动感知——它仍指向旧 commit。必须手动“登记”新版本，否则 submodule update 不会改变它。

• 在父仓库根目录执行 git add path/to/submodule（注意：不加尾部斜杠，且路径是子模块在父仓库中的目录名）
• 执行 git commit -m "submodule: update path/to/submodule to v2.1.0"
• 此时 git ls-tree HEAD path/to/submodule 将显示新 commit hash，后续克隆或更新才会拉取该版本

同步更新子模块到父仓库记录的版本

当父仓库已提交了目标版本的 submodule commit，其他协作者或 CI 环境只需两步即可同步：

• 拉取父仓库更新：git pull origin main
• 更新子模块：git submodule update --init --recursive
• 注意：若只运行 git submodule update 而未加 --init，对首次克隆的环境会跳过初始化，导致子模块目录为空
• 如需强制覆盖本地修改并重置到记录版本，加 --force 和 --checkout（默认行为），例如：git submodule update --init --force --checkout path/to/submodule

进阶：直接更新到远程分支最新提交（非固定 commit）

如果希望子模块始终跟踪某个分支（如 origin/main）的最新状态，可启用 --remote 模式：

• 先在父仓库中设置子模块为远程跟踪：git config -f .gitmodules submodule.path/to/submodule.branch main
• 执行 git submodule update --remote --init --recursive
• 该命令会进入子模块、执行 git fetch origin、然后 git merge origin/main，并将新 commit 记录回父仓库（需手动 git add & commit 保存）
• ⚠️ 注意：这会改变父仓库的 submodule commit，属于主动变更，不是只读同步