子模块的 branch 配置仅影响 git submodule update --init 的初始检出，不自动同步、不跟踪、不随主分支切换；它只在首次初始化时拉取对应分支最新提交并锁定该 commit，后续 update 仍严格按父仓库记录的 commit hash 检出。
子模块的 branch 配置到底起什么作用？
它只影响 git submodule update --init 的初始检出行为，**不自动同步、不自动跟踪、不参与主仓库分支切换**。很多人误以为设了 branch = develop 就等于“子模块会随主项目分支自动切到对应分支”，这是最大误区。
实际效果是：首次克隆时，Git 会从该远程分支拉取最新提交，并将子模块目录锁定到那个 commit；后续执行 git submodule update，仍只会检出 .gitmodules 里记录的固定 commit，完全无视 branch 字段。
-
git submodule add -b develop <url> libs/utils</url>→ 记录 branch=develop，且当前检出 develop 最新 commit -
git submodule update --init→ 若子模块未初始化，会按 branch 字段 fetch 并 checkout 对应分支 tip -
git submodule update（无 --init）→ 只检出父仓库索引中存的 commit hash，哪怕远程 develop 已前进 20 个提交也毫无反应
怎么让子模块真正“跟主分支走”？
没有魔法命令，必须靠显式操作+约定。常见做法是：在主仓库每个分支上，手动把子模块更新到对应语义版本或分支 tip，并提交新 hash。
例如主仓库 feature/login 分支依赖子模块 shared-utils 的最新 develop 功能：
- 进子模块目录：
cd libs/shared-utils - 拉取远程最新：
git fetch origin develop - 检出并更新到最新：
git merge origin/develop或git reset --hard origin/develop - 回到主仓库根目录：
cd .. - 提交变更：
git add libs/shared-utils && git commit -m "submodule: update shared-utils to latest develop"
注意：如果子模块用了 force push，git reset --hard origin/develop 可能丢数据，此时应先 git status 确认工作区干净再执行。
为什么 git submodule foreach 容易出错？
它只是对每个子模块执行相同命令，**不区分当前主分支意图，也不校验子模块是否已配置 tracking 分支**。盲目运行 git submodule foreach 'git pull origin main' 可能把本该在 develop 上的子模块强行拉到 main，破坏功能一致性。
安全用法需加判断：
- 先查子模块配置：
git config -f .gitmodules submodule.libs/shared-utils.branch - 再动态执行：
git submodule foreach 'git checkout $(git config -f ../.gitmodules submodule.$name.branch || echo main) && git pull origin $(git config -f ../.gitmodules submodule.$name.branch || echo main)' - 更稳妥的做法是写成脚本，按主分支名映射子模块目标分支（如 main→main、feature/*→develop），避免硬编码
CI 构建时如何保证子模块状态可靠？
CI 环境不能依赖本地配置或人工干预，必须明确指定子模块状态。关键点只有两个：
-
git submodule update --init --recursive→ 确保所有子模块存在并检出父仓库 commit 记录的精确版本（这是唯一可信依据） - 禁止在 CI 中执行
git submodule update --remote或任何自动拉取最新代码的操作——这会让构建结果不可复现
如果真需要“最新版”，应在开发阶段由人完成子模块更新+父仓库提交，CI 只负责忠实还原那个 commit。否则，同一 commit ID 在不同时间构建出不同结果，调试成本会指数级上升。
最易被忽略的是：子模块的 .gitmodules 文件本身也是主仓库的一部分，修改它必须提交，否则别人 clone 后 git submodule update 会失败或指向错误 URL。
