问题发现&解决

什么是子模块（子文档）

  • 定义：Git 子模块（submodule）是一个嵌套在父仓库中的独立 Git 仓库。
  • 作用：允许你在一个 Git 仓库中引用另一个仓库，并保持独立版本控制。
  • 特点：
    • 有自己的 .git 目录或由父仓库 .gitmodules 管理。
    • GitHub 上显示为 箭头文件夹，点击会跳转到子模块的远程仓库。
    • 本地未初始化或更新时，会出现 in unpopulated submodule 报错。

如何发现文件夹被上传成子模块

image.png

  • GitHub 文件浏览器：

    • 文件夹前有 箭头标记。
    • 点击会跳到子模块对应的远程仓库，而不是显示普通文件列表。

  • 本地操作：

    • 执行 git status 或 git submodule status 可能显示子模块信息。

    • 对未初始化的子模块操作文件会报错，例如：

      1
      in unpopulated submodule

为什么文件夹会被识别为子模块

  1. 误操作添加子模块：

    1
    git submodule add <repo_url> 子文件夹名
    • Git 会记录子模块信息在 .gitmodules 和 .git/config。

  2. 克隆含子模块的仓库：

    • 克隆时未初始化子模块：

      1
      2
      git clone <repo>
      git submodule update --init

    • Git 会把文件夹当作子模块，但未下载内容。

  3. 上传一个已有 Git 仓库的文件夹：

    • 如果文件夹里原本有 .git 目录：

      1
      2
      3
      cp -r other-repo myRepo/my-folder
      git add my-folder
      git commit -m "Add folder"

    • Git 会自动识别为子模块，GitHub 上显示箭头。

如何将子模块转换为普通文件夹

假设本地文件夹名为 my-folder，步骤如下：

步骤 1：检查子模块

1
git submodule status
  • 查看当前仓库是否有子模块。

步骤 2：取消子模块关联

1
2
3
git submodule deinit -f my-folder
git rm -f my-folder
Remove-Item -Recurse -Force .git\modules\my-folder
  • deinit：取消初始化信息
  • git rm -f：从索引中移除子模块
  • 删除 .git/modules 中的子模块记录

步骤 3：保留文件夹内容

  • 确认本地文件夹和文件仍然存在，如果被删除可手动恢复。

步骤 4：将文件夹加入 Git 并提交

1
2
3
git add my-folder
git commit -m "Convert submodule to normal folder"
git push origin main
  • 文件夹变成普通文件夹，GitHub 上箭头消失。

额外注意事项

  • rebase 冲突处理：

    • 子模块转换过程中可能会遇到 ~HEAD 冲突目录。
    • 可以删除冲突临时目录，git add 本地文件夹，然后继续 git rebase --continue。

  • 网络问题：

    • 如果 push/pull 超时，可能需要 VPN 或切换 SSH 方式。

  • 强制覆盖远端：

    • 如果想用本地状态覆盖远端：

      1
      2
      3
      git rebase --abort
      git reset --hard HEAD
      git push origin main --force

总结：

  • 子模块本质是嵌套 Git 仓库，GitHub 显示为箭头。
  • 上传成子模块常见原因：误用 git submodule add、克隆含子模块仓库、上传已有 Git 仓库文件夹。
  • 转换为普通文件夹主要步骤：取消子模块信息 → 保留文件夹 → 添加提交 → 推送。