问题现象

在执行 git status 时，发现某个文件夹（如 project/submodule_folder）显示正常，但在远端仓库查看时，该文件夹不包含任何文件，只显示一个 commit ID：

submodule_folder @ 6a7e81b7

本地查看该文件夹，里面有完整的源代码文件，但 Git 就是不识别。

问题诊断

检查文件模式

git ls-files -s path/to/folder

输出示例：

160000 6a7e81b7dda75e2b71d762f4b6ac89ed97e118c7 0	path/to/folder

关键识别点： 模式码 160000 表示这是一个 gitlink（子模块引用），而不是普通目录。

检查子模块配置

cat .gitmodules
# 输出：No such file or directory（或没有该子模块的配置）

git submodule status
# 输出：fatal: no submodule mapping found in .gitmodules

检查文件夹内的 .git

ls -la path/to/folder/.git
# 输出：No such file or directory

问题根源

什么是"孤儿子模块"

当满足以下条件时，就会形成孤儿子模块：

1. 曾经添加过子模块：使用 git submodule add <url> 添加了子模块
2. 删除了配置文件：.gitmodules 文件被删除或移除了该子模块的配置
3. 删除了 .git 目录：子模块文件夹内的 .git 目录被删除
4. 但未清理引用：Git 索引中仍保留着 160000 模式的 gitlink 引用

典型产生场景

场景	说明
手动删除 .gitmodules	为了"简化"配置而删除
复制粘贴代码	从其他项目复制了子模块文件夹，但没有子模块配置
错误的子模块移除方式	直接删除文件夹而非使用 git submodule deinit
子模块转普通目录未完成	想取消子模块，但只删除了 .git 目录

为什么会出现这个问题

Git 的子模块机制依赖于三个部分：

┌─────────────────────────────────────────────────────────┐
│  1. .gitmodules          - 子模块配置文件（仓库级）      │
│  2. .git/config          - 子模块配置信息（本地级）      │
│  3. .git/modules/        - 子模块 git 数据存储           │
│  4. submodule/.git       - 子模块工作树链接              │
│  5. 索引中的 160000 条目   - gitlink 引用                 │
└─────────────────────────────────────────────────────────┘

当 1、3、4 被删除，但 5 仍存在 时，Git 仍然认为这是一个子模块，但无法正常工作。

解决方案

转换为普通文件夹（推荐）

如果你想保留文件夹内的所有文件，并将其变为普通目录：

步骤 1：从 Git 缓存中删除子模块引用

git rm --cached path/to/folder

说明： --cached 参数只删除索引中的引用，不删除工作区文件。

步骤 2：重新添加为普通文件夹

git add path/to/folder

步骤 3：创建 .gitignore（可选）

如果文件夹包含编译产物，建议创建 .gitignore：

echo "build/" > path/to/folder/.gitignore
git add path/to/folder/.gitignore

步骤 4：提交更改

git commit -m "将子模块转换为普通文件夹

之前 path/to/folder 是作为 gitlink 子模块引用，
现在将所有文件直接提交到主仓库中。"

步骤 5：推送到远程

git push origin <branch-name>

验证结果

转换前（子模块模式）

git ls-files -s path/to/folder
# 输出：160000 6a7e81b7...  0  path/to/folder

远端显示：folder @ 6a7e81b7（仅显示 commit ID）

转换后（普通目录模式）

git ls-files -s path/to/folder
# 输出：
# 100644 abc123...  0  path/to/folder/file1.txt
# 100644 def456...  0  path/to/folder/file2.txt
# ...

远端显示：完整的文件夹结构和所有文件

关键概念解释

Git 文件模式码

模式码	含义	说明
100644	普通文件	最常见的文件类型
100755	可执行文件	有执行权限的文件
160000	gitlink（子模块）	指向另一个 git 仓库的引用
120000	符号链接	软链接

为什么是 160000

160000 是 Git 内部用于表示 gitlink 的特殊模式码，它告诉 Git：

“这个路径不是普通文件，而是指向另一个 Git 仓库特定 commit 的指针”

最佳实践

添加子模块的正确方式

# 添加子模块
git submodule add <repository-url> path/to/folder

# 提交
git commit -m "添加子模块"

移除子模块的正确方式

# 使用 Git 命令移除（自动清理所有配置）
git submodule deinit -f path/to/folder
git rm -f path/to/folder
rm -rf .git/modules/path/to/folder

# 提交
git commit -m "移除子模块"

检查子模块状态

# 查看所有子模块
git submodule status

# 查看子模块配置
git config --file .gitmodules --list

常见误区

误区	正确做法
直接删除 .gitmodules	使用 git submodule deinit
直接删除子模块文件夹	使用 git rm -f
手动复制子模块文件夹	使用 git submodule add
删除 .git 目录就能取消子模块	需要同时清理索引中的 gitlink

参考资料

• Git Submodules
• Removing a submodule
• Git 文件模式码详解