如何正确批量切换Git仓库中子模块的分支？

我来帮你梳理清楚两种场景下的解决方案，都是日常维护多子模块仓库时常用的操作：

场景1：先修改.gitmodules，再同步所有子模块到新分支 #

如果还没动手切换子模块分支，推荐用这个流程，能保证配置和子模块状态完全对齐：

1. 编辑根目录的.gitmodules文件
   找到每个子模块的配置块，把branch字段从branch_rev_1改成branch_rev_2，比如：

   [submodule "components/auth"]
       path = components/auth
       url = git@example.com:team/auth.git
       branch = branch_rev_2  # 把原来的branch_rev_1替换成这个
   

2. 同步配置到子模块本地
   执行以下命令，把.gitmodules里的分支配置同步到每个子模块的本地.git/config文件中：

   git submodule sync --recursive
   

   --recursive是为了处理嵌套子模块，如果你的子模块没有嵌套可以省略。

3. 拉取新分支的最新代码并更新子模块
   用下面的命令让所有子模块切换到目标分支的最新提交：

   git submodule update --remote --merge --recursive
   

   • --remote：告诉Git拉取子模块远程仓库对应分支的最新代码
   • --merge：如果子模块本地有未提交的修改，会尝试合并（如果不需要合并可以换成--rebase，或者直接--checkout覆盖本地修改）

4. 提交.gitmodules的修改
   别忘了把.gitmodules的变更提交到主仓库，这样其他克隆仓库的同事也能拿到正确的子模块分支配置：

   git add .gitmodules
   git commit -m "Update all submodules to branch_rev_2"
   

场景2：已经在子模块切换了分支，同步.gitmodules和配置 #

如果已经手动在每个子模块里执行了git checkout branch_rev_2，现在要把配置对齐，按下面的步骤来：

1. 确保子模块跟踪远程分支
   先确认每个子模块的本地分支已经关联了远程分支，避免后续update --remote失效：

   git submodule foreach 'git branch -u origin/branch_rev_2'
   

2. 批量更新.gitmodules的分支配置
   手动编辑.gitmodules容易出错，推荐用Git命令批量修改：

   git submodule foreach --quiet 'echo $name' | while read submod; do
     git config --file .gitmodules submodule."$submod".branch branch_rev_2
   done
   

   这个命令会遍历所有子模块，自动把它们的branch字段更新为branch_rev_2。

3. 同步配置并提交
   重复场景1的第2、4步：执行git submodule sync --recursive同步配置，然后提交.gitmodules的修改。

关键提醒 #

• .gitmodules里的分支配置是克隆仓库时的默认分支，而子模块本地的当前分支是独立状态，必须通过sync和update命令才能对齐两者。
• 如果子模块处于「游离HEAD状态」（比如之前checkout了某个具体commit而不是分支），要先执行git checkout branch_rev_2切换到分支上，再进行后续操作。

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