将目录替换为同名子模块后，如何修复Git仓库？

当Git仓库中的某个子目录被替换为同名子模块时，会导致git fetch完全失效。本次场景中该子目录原本包含另一个子模块（不确定是否为复现必要条件，但这是GitLab CI中遇到的实际场景——GitLab CI会复用Git目录用于无关构建）。

问题复现脚本 #

#!/bin/bash -e

# 创建三个仓库。Leaf_repo是普通仓库
mkdir leaf_repo
cd leaf_repo
git init --initial-branch=master
echo "Leaf repo" > README.md
git add .
git commit -m "Initial commit"
cd ..

# Subdir_repo包含leaf_repo作为子模块
mkdir subdir_repo
cd subdir_repo
git init --initial-branch=master
echo "Subdir repo" > README.md
git -c protocol.file.allow=always submodule add ../leaf_repo
git add .
git commit -m "Initial commit"
cd ..

# Root_repo最初将`subdir_repo`作为普通目录而非子模块，
# 并且在该目录下直接包含leaf_repo作为子模块
mkdir root_repo
cd root_repo
git init --initial-branch=master
echo "Test" > README.md
git add .
git commit -m "Initial commit"
mkdir subdir_repo
git -c protocol.file.allow=always submodule add ../leaf_repo subdir_repo/leaf_repo
git add .
git commit -m "Add leaf repo"

# 模拟有人创建MR分支，将`subdir_repo`从普通目录切换为子模块
git switch -c an_mr
git rm subdir_repo/leaf_repo
git commit -m "Remove leaf_repo submodule"
rmdir subdir_repo
rm -rf .git/modules # 否则会报错："fatal: not a git repository: '.git/modules/subdir_repo'; fatal: A git directory for 'subdir_repo' is found locally with remote(s):"
git -c protocol.file.allow=always submodule add ../subdir_repo
git commit -m "Convert subdir_repo to submodule"

# 模拟其他人复用该仓库（使用FETCH策略），切回master分支
echo "--- Fetch attempt 1 ---"

(
    git checkout -f -q master
    git submodule init
    git submodule sync --recursive
    git submodule foreach git clean -ffdx
    git submodule foreach git reset --hard
    git submodule update --init --recursive
) || true

# 上述拉取会失败，尝试清理工作区
echo "--- Clean worktree ---"

git rm -rf --ignore-unmatch .
git clean -ffdx

# 但仍然会失败
echo "--- Fetch attempt 2 ---"

git checkout -f -q master
    git submodule init
    git submodule sync --recursive
    git submodule foreach git clean -ffdx
    git submodule foreach git reset --hard
    git submodule update --init --recursive

echo "SUCCESS" # 不会被打印

执行脚本后出现的错误 #

Synchronizing submodule url for 'subdir_repo/leaf_repo'
error: submodule git dir '/path/to/root_repo/.git/modules/subdir_repo/leaf_repo' is inside git dir '/path/to/root_repo/.git/modules/subdir_repo'
fatal: refusing to create/use '/path/to/root_repo/.git/modules/subdir_repo/leaf_repo' in another submodule's git dir

背景说明 #

之前为GitLab CI添加了“清理工作区”步骤来避免此类问题，原本想在git fetch失败时直接rm -rf整个仓库重新拉取，但GitLab工作人员担心这会清除.git中的大缓存文件。当时git rm -rf ... && git clean -ffdx足以修复其他导致git fetch失效的问题，但没有覆盖当前这种场景。

核心问题 #

一旦Git仓库出现此类损坏，能否找到无需全量重新拉取即可修复的命令？
更具体地说，需要一个可在gitlab-runner中实现的通用命令。

解决方案 #

要修复这个问题，核心是清理.git/modules中残留的旧子模块数据，同时重置子模块配置，执行以下命令即可：

# 切回目标分支并重置到最新提交
git checkout -f -q master
git reset --hard HEAD

# 清理工作区所有未跟踪内容
git clean -ffdx

# 取消所有子模块的本地关联，清理残留的子模块Git数据
git submodule deinit --all -f
rm -rf .git/modules

# 重新初始化并拉取正确的子模块
git submodule init
git submodule sync --recursive
git submodule update --init --recursive

命令解释 #

• git submodule deinit --all -f：取消所有子模块的本地关联，移除.git/config中的子模块配置，但不会删除工作区文件。
• rm -rf .git/modules：删除残留的旧子模块Git目录——这是导致错误的根源，Git不允许在一个子模块的Git目录下创建另一个子模块的Git目录。
• 后续的init/sync/update命令会重新从远程拉取正确的子模块配置和数据，恢复仓库的正常状态。

这个方案仅清理残留的子模块垃圾数据，保留了.git中的对象缓存，既解决了问题，又符合GitLab团队对缓存保留的要求。

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