因未跟踪工作区文件无法切换Git分支，子模块问题求助

问题背景 #

创建引用外部Git仓库的子模块后，切换分支时触发如下错误：

git -c diff.mnemonicprefix=false -c core.quotepath=false --no-optional-locks checkout Feature/7-SOE_Update --progress
error: The following untracked working tree files would be overwritten by checkout:
Application_Layer/Appl_SOC/SOC_Algorithm/SOC_Basic.c
Application_Layer/Appl_SOC/SOC_Algorithm/SOC_Basic.h
Please move or remove them before you switch branches.
Aborting

已尝试的无效操作：

• 执行git status显示仓库状态正常
• 在.gitmodule中添加ignore = dirty无法解决分支切换问题
• 强制切换会丢失未跟踪文件

当前临时解决方法（需重复执行，效率极低）：

git submodule deinit --all
git pull
rm -rf build
rm -rf $RETDEC_INSTALL_DIR

核心异常：仅子模块中的3个文件显示未跟踪状态，其余文件正常，分支切换问题重复出现。

根本原因 #

这3个文件大概率是子模块仓库中未被追踪（或被.gitignore忽略），但主仓库的目标分支中存在同名文件，导致Git判定切换分支时会覆盖未跟踪文件，从而阻止操作。

分步解决方法 #

1. 确认子模块内的文件状态 #

进入子模块目录，检查这3个文件的具体状态：

cd Application_Layer/Appl_SOC/SOC_Algorithm
git status

根据输出判断：

• 若显示untracked：子模块仓库未追踪这些文件
• 若显示modified：子模块内有未提交的修改

2. 处理子模块内的文件 #

情况A：子模块需要长期追踪这些文件

如果这3个文件是子模块的必要业务文件，在子模块内提交并推送：

# 子模块目录下执行
git add SOC_Basic.c SOC_Basic.h
git commit -m "Add and track SOC_Basic core files"
git push

回到主仓库，更新子模块引用并提交：

cd ../../../../
git add Application_Layer/Appl_SOC/SOC_Algorithm
git commit -m "Update submodule reference to include SOC_Basic files"

情况B：子模块不需要追踪这些文件

如果这些是本地生成的临时文件或编译产物，在子模块中添加忽略规则：

# 子模块目录下执行
echo "SOC_Basic.c" >> .gitignore
echo "SOC_Basic.h" >> .gitignore
git add .gitignore
git commit -m "Add SOC_Basic files to ignore list"
git push

回到主仓库，更新子模块引用并提交：

cd ../../../../
git add Application_Layer/Appl_SOC/SOC_Algorithm
git commit -m "Update submodule ignore configuration"

3. 清理主仓库的冗余文件 #

如果主仓库的某个分支直接在子模块路径下添加了这3个文件（而非通过子模块引用），需要从主仓库中移除这些冗余文件：

# 切换到存在问题的分支
git checkout 你的问题分支名称
# 从主仓库索引中移除文件（不删除本地文件）
git rm --cached Application_Layer/Appl_SOC/SOC_Algorithm/SOC_Basic.c
git rm --cached Application_Layer/Appl_SOC/SOC_Algorithm/SOC_Basic.h
# 提交修改
git commit -m "Remove redundant SOC_Basic files from main repository"

4. 配置子模块忽略规则 #

修改主仓库的.gitmodules文件，针对该子模块设置ignore = untracked（而非dirty）：

[submodule "Application_Layer/Appl_SOC/SOC_Algorithm"]
    path = Application_Layer/Appl_SOC/SOC_Algorithm
    url = 你的子模块仓库URL
    ignore = untracked

执行同步和更新命令生效：

git submodule sync
git submodule update --init --recursive

5. 验证分支切换 #

完成上述操作后，尝试切换分支验证：

git checkout Feature/7-SOE_Update

如果仍有残留未跟踪文件，可清理子模块目录的未跟踪内容（确保已备份重要文件）：

git clean -fd Application_Layer/Appl_SOC/SOC_Algorithm/

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