VSCode Git插件无法识别子模块是因为主仓库未初始化或状态脱节，需终端执行git submodule init && update，并配置git.autoRepositoryDetection为true或显式声明路径，再重启窗口。
Mac上VSCode内置Git插件无法识别子模块，本质是主仓库已声明子模块但工作区未完成初始化或状态脱节——VSCode Git扩展只认索引中记录的commit指针，不自动拉取子模块代码树，导致SCM面板空白、右键无Git菜单、状态栏不显示分支。
确认子模块是否真实存在且配置完整
打开终端，cd到项目根目录（即含.git的那层），执行：git submodule status。
若返回空行或报错“no submodule mapping found”，说明.gitmodules文件缺失或已被删；若返回带“-”开头的行（如 -e9a1b2c3 libs/utils），表示该子模块在索引中注册了但本地目录为空——这是Mac上最常见的情形。
检查是否存在 .gitmodules 文件：ls -a | grep gitmodules。没有则子模块从未被正确添加；有则继续下一步。
强制初始化并检出子模块内容
这一步必须在终端中执行，VSCode自身不会触发初始化逻辑。
运行：git submodule init → git submodule update。
如果子模块目录下仍为空（ls libs/utils 返回 nothing），说明远程仓库地址不可达或权限异常。此时需验证SSH密钥是否已加载：ssh -T git@github.com（或对应平台域名）；若提示“Permission denied”，需先配置好密钥再重试。
【注意】不要跳过 init 直接 run update —— Mac 上 git submodule update 单独执行时对未初始化的子模块静默失败，不会报错也不会拉代码。
修复VSCode Git扩展扫描行为
VSCode默认启用自动仓库发现，但若子模块路径被排除规则拦截，或工作区配置异常，仍会漏掉。
方法一：手动启用全量检测
按 Cmd+Shift+P → 输入 “Preferences: Open Settings (JSON)” → 在 settings.json 中添加："git.autoRepositoryDetection": true（确保不是 "submodules" 或 false）。
方法二：显式声明子模块路径
若上述无效，在 settings.json 中加入："git.scanRepositories": ["./", "./libs/utils"]（将 ./libs/utils 替换为你的子模块实际相对路径）。
方法三：重启VSCode并重载窗口
关闭所有VSCode窗口 → 用 Finder 定位到项目根目录（含 .git 的那一层）→ 右键 → “Open with Code” → 启动后按 Cmd+Shift+P → 执行 “Developer: Reload Window”。
清理残留状态避免指针错位
第一步：进入子模块目录，确认当前检出状态：cd libs/utils && git rev-parse HEAD。
第二步：回到项目根目录，比对是否与主仓库记录一致：git submodule status 输出的哈希值应与上一步完全相同。若不同，说明子模块本地被手动切过分支或提交过——这会导致VSCode持续标记“modified”且拒绝纳入SCM管理。
第三步：强制同步到主仓库指定版本：git submodule update --force --checkout libs/utils。
【关键前提】执行此命令前，确保子模块目录下已有完整代码树（即已成功跑过 init + update）；否则会报错“not a git repository”。
