问题现象
在执行 git status 时，发现某个文件夹（如 project/submodule_folder）显示正常，但在远端仓库查看时，该文件夹不包含任何文件，只显示一个 commit ID：
submodule_folder @ 6a7e81b7本地查看该文件夹，里面有完整的源代码文件，但 Git 就是不识别。
问题诊断
检查文件模式
bash
git ls-files -s path/to/folder输出示例：
160000 6a7e81b7dda75e2b71d762f4b6ac89ed97e118c7 0 path/to/folder关键识别点： 模式码 160000 表示这是一个 gitlink（子模块引用），而不是普通目录。
检查子模块配置
bash
cat .gitmodules
# 输出：No such file or directory（或没有该子模块的配置）
git submodule status
# 输出：fatal: no submodule mapping found in .gitmodules检查文件夹内的 .git
bash
ls -la path/to/folder/.git
# 输出：No such file or directory问题根源
什么是"孤儿子模块"
当满足以下条件时，就会形成孤儿子模块：
- 曾经添加过子模块 ：使用
git submodule add <url>添加了子模块 - 删除了配置文件 ：
.gitmodules文件被删除或移除了该子模块的配置 - 删除了 .git 目录 ：子模块文件夹内的
.git目录被删除 - 但未清理引用 ：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 缓存中删除子模块引用
bash
git rm --cached path/to/folder说明： --cached 参数只删除索引中的引用，不删除工作区文件。
步骤 2：重新添加为普通文件夹
bash
git add path/to/folder步骤 3：创建 .gitignore（可选）
如果文件夹包含编译产物，建议创建 .gitignore：
bash
echo "build/" > path/to/folder/.gitignore
git add path/to/folder/.gitignore步骤 4：提交更改
bash
git commit -m "将子模块转换为普通文件夹
之前 path/to/folder 是作为 gitlink 子模块引用，
现在将所有文件直接提交到主仓库中。"步骤 5：推送到远程
bash
git push origin <branch-name>验证结果
转换前（子模块模式）
bash
git ls-files -s path/to/folder
# 输出：160000 6a7e81b7... 0 path/to/folder远端显示：folder @ 6a7e81b7（仅显示 commit ID）
转换后（普通目录模式）
bash
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 的指针"
最佳实践
添加子模块的正确方式
bash
# 添加子模块
git submodule add <repository-url> path/to/folder
# 提交
git commit -m "添加子模块"移除子模块的正确方式
bash
# 使用 Git 命令移除（自动清理所有配置）
git submodule deinit -f path/to/folder
git rm -f path/to/folder
rm -rf .git/modules/path/to/folder
# 提交
git commit -m "移除子模块"检查子模块状态
bash
# 查看所有子模块
git submodule status
# 查看子模块配置
git config --file .gitmodules --list常见误区
| 误区 | 正确做法 |
|---|---|
直接删除 .gitmodules |
使用 git submodule deinit |
| 直接删除子模块文件夹 | 使用 git rm -f |
| 手动复制子模块文件夹 | 使用 git submodule add |
删除 .git 目录就能取消子模块 |
需要同时清理索引中的 gitlink |