Git父子仓库子模块分支跟踪同步异常：切换分支后HEAD丢失

需求与问题 #

• 需求：创建父/子Git仓库，实现子模块分支自动跟踪父仓库对应分支
• 问题：使用Git 2.38.1.windows.1，按配置步骤操作后，切换父仓库分支（Main→UAT→Main）时，子模块仍停留在uat分支，提交变更后丢失HEAD；已配置submodule.recurse true等参数，但--recurse-submodules未自动生效，手动执行git submodule foreach git switch <branch>可切换，但疑惑为何自动同步配置未生效

操作步骤 #

# Setup main
# ------------
md Parent
cd Parent
git init
echo "Hello" > ReadMe.txt
git add .
git commit -m "Initialising Parent main"    
cd ..

md Child
cd Child
git init
echo "Hello" > ReadMe.txt
git add .
git commit -m "Initialising Child main"
cd ..

# Add Submodule
# ------------------
cd Parent
git config --global protocol.file.allow always
git config submodule.recurse true
git config submodule.update rebase
git config push.recurseSubmodules on-demand
git submodule add -b main ..\Child
git add .
git commit -m "Added submodule"
git log --oneline
# All good on main branch
cd Child
git log --oneline
# All good on main branch
cd ..\..

# Setup uat
# -----------
cd Parent
git switch -c uat --recurse-submodules
cd Child
#! -- recurse-submodules didn't work 
# Child still on main so switch manually
git switch -c uat
echo "Hello again" > Readme.txt
git add .
git commit -m "Initialising Child uat"
cd ..
git config -f .gitmodules submodule.Child.branch uat
git add .
git commit -m "Initialising Main at"
git log --oneline
# All good on uat branch
cd Child
git log --oneline
# All good on uat branch
cd ..\..

# Switch all to main
# ---------------------
# SPOILER Child Looses its HEAD
cd Parent
git switch main --recurse-submodules
cd Child
git log --oneline
#! Child lost its HEAD

更新 #

感谢@torek建议使用以下命令手动切换子模块分支：

git submodule foreach git switch <branch>

原本预期--recurse-submodules结合git config submodule.recurse true等配置可自动完成分支同步，理解submodule.recurse true会让支持的Git操作默认带上--recurse-submodules参数（clone操作除外），push.recurseSubmodules on-demand会在父仓库提交时对子模块变更发出警告，但实际配置未生效，对此存在疑惑。

问题解答 #

核心原因：git switch的--recurse-submodules逻辑并非切换分支 #

Git中git switch --recurse-submodules的作用是：切换父仓库分支后，将子模块更新到父仓库该分支所指向的子模块特定提交哈希，而不是切换子模块的分支。这是子模块的核心特性——父仓库默认只记录子模块的某个具体提交，而非分支关联。

自动同步分支的正确配置方式 #

要实现父仓库切换分支时，子模块自动切换到对应跟踪分支，需要结合以下配置和操作：

1. 确保子模块在.gitmodules中配置跟踪分支
   每个子模块需要在.gitmodules里明确branch字段，且该文件属于父仓库的版本控制内容，不同分支需单独配置并提交：

   # 在父仓库main分支执行
   git config -f .gitmodules submodule.Child.branch main
   git add .gitmodules && git commit -m "Set Child to track main branch"
   
   # 在父仓库uat分支执行
   git config -f .gitmodules submodule.Child.branch uat
   git add .gitmodules && git commit -m "Set Child to track uat branch"
   

2. 切换父分支后同步子模块分支
   切换父仓库分支后，执行以下命令让子模块同步到配置的跟踪分支：

   git submodule update --remote --recurse-submodules
   

   开启submodule.recurse true后可简化为：

   git submodule update --remote
   

3. 明确submodule.recurse true的生效范围
   submodule.recurse true仅会让git fetch、git pull、git push、git status等操作默认带上--recurse-submodules，git switch不在此列。即使开启该配置，git switch也不会自动添加--recurse-submodules参数，且该参数本身也不负责切换子模块分支。

4. 解决子模块丢失HEAD的问题
   子模块丢失HEAD是因为切换父分支后，子模块被切换到了**游离头指针（detached HEAD）**状态（父仓库记录的特定提交）。通过git submodule update --remote可让子模块回到配置的跟踪分支，避免游离状态。

优化后的工作流示例 #

1. 在父仓库main分支添加子模块并配置跟踪：

   git submodule add -b main ..\Child
   git config submodule.recurse true
   git add .gitmodules
   git commit -m "Add Child submodule tracking main branch"
   

2. 创建并配置uat分支：

   git switch -c uat
   git config -f .gitmodules submodule.Child.branch uat
   git add .gitmodules && git commit -m "Update Child to track uat branch"
   # 切换子模块到uat分支并提交变更
   cd Child
   git switch -c uat
   echo "uat change" >> Readme.txt
   git add . && git commit -m "uat changes"
   cd ..
   git add Child && git commit -m "Update Child submodule to uat commit"
   

3. 切换回main分支并同步子模块：

   git switch main
   git submodule update --remote
   

   此时子模块会自动切换回main分支，保持正常分支状态。

内容的提问来源于stack exchange，提问作者Ricardo da Silva