Git分支切换时同名目录与子模块的冲突解决及分支维护方案

这个问题我之前也碰到过——当一个分支把目录改成子模块后，切回保留原目录的旧分支时，Git会因为工作区里子模块目录的未追踪文件而报错。结合你说的不能重命名/移动目录的限制，给你几个可行的方案：

方案一：安全清理子模块工作区后切换（推荐） #

这个方法能最大程度保留你的改动，同时避免冲突：

1. 先进入子模块目录，把未提交的改动临时存起来（如果已经提交过可以跳过这步）：

   cd NAME
   git stash push -m "临时存储子模块改动，用于分支切换"
   cd ..
   

2. 让子模块回到当前分支指定的版本，确保NAME目录里没有Git识别的未追踪文件：

   git submodule update --init --recursive
   

3. 现在再切换分支就不会报错了：

   git checkout OldBranchWithDir
   

等你切回新分支时，别忘了回到NAME目录执行git stash pop恢复之前的子模块改动。

方案二：强制切换（适合确定子模块改动已备份/无需保留时） #

如果你确定当前NAME目录下的子模块改动已经提交到子模块仓库，或者不需要保留，可以直接用强制切换命令：

git checkout --force OldBranchWithDir

⚠️ 注意：这个命令会直接覆盖工作区中NAME目录下的未追踪文件，执行前一定要确认这些内容不需要保留。

方案三：使用稀疏检出（适合频繁在两个分支间切换的场景） #

如果需要经常在这两个分支来回切换，可以用Git的稀疏检出功能临时隐藏NAME目录：

1. 在当前新分支上启用稀疏检出：

   git sparse-checkout init --cone
   

2. 配置Git不检出NAME目录：

   git sparse-checkout set '/*' '!NAME'
   

   执行后工作区的NAME目录会被自动移除
3. 现在可以顺利切换到旧分支：

   git checkout OldBranchWithDir
   

4. 切换完成后，可以关闭稀疏检出恢复正常状态：

   git sparse-checkout disable
   

下次切回新分支时，重复上述步骤先排除NAME目录再切换即可。

长期维护建议 #

如果需要长期维护旧分支且频繁切换，可以把方案一的步骤写成一个简单的脚本，自动处理子模块的存储和更新，避免每次手动操作：

#!/bin/bash
TARGET_BRANCH=$1

# 检查当前分支是否包含NAME子模块
if git submodule status | grep -q "NAME"; then
    echo "处理NAME子模块..."
    cd NAME
    git stash push -m "自动存储：切换到${TARGET_BRANCH}"
    cd ..
    git submodule update --init --recursive
fi

echo "切换到分支${TARGET_BRANCH}..."
git checkout $TARGET_BRANCH

把脚本保存为switch-branch.sh，赋予执行权限后，用./switch-branch.sh OldBranchWithDir就能一键切换了。

内容的提问来源于stack exchange，提问作者MR. D