08 · Submodule
状态：✅ 已实现 · 范围：v1 · 工程参考：
../spec.md
Submodule 如何展示
- 含
.gitmodules的仓库在任一 submodule 需要处理（未初始化或有漂移）时带◇徽标。 - Submodule 仓库嵌套显示在其父仓库下。已初始化的与普通仓库完全一致（第 03–11 页全部适用——它们本就是被父仓库钉住提交的普通仓库）。
- 未初始化的 submodule（文件夹为空或不存在）以灰色显示，附"未初始化"提示与一键初始化操作。
每个 submodule 的状态
| 状态 | 含义 | 展示 |
|---|---|---|
| 同步 | 检出的提交与父仓库记录的一致 | 普通行 |
| 漂移 | 检出的提交与记录不符（有人移动了 pin，或本地更新过 ） | 警告提示 + "检出记录的提交"操作 |
| 脏 | submodule 内有未提交改动 | ● 徽标（漂移单独汇报——脏不等于漂移） |
| 未初始化 | 从未克隆 | 灰色 + 初始化操作 |
操作
- Update all（仓库右键菜单，招牌操作）——执行
git submodule update --init --recursive，进度按 submodule 与嵌套层级流式展示。单个失败单独汇报，不中断其余部分。 - 更新此 submodule——单个版本的更新。
- 检出记录的提交——把漂移的 submodule 拉回父仓库 pin 的提交。
- Sync URLs——
.gitmodules里的远端地址变更后执行git submodule sync。 - 作为仓库打开——把该 submodule 聚焦为一个完整仓库节点（提交图、变更、自己的远端）。
- 添加子模块…（仓库右键菜单）——把一个仓库克隆到指定文件夹，钉住它检出的提交，并写进
.gitmodules。文件夹留空则按仓库名命名；可选的分支用于指定后续更新要跟踪的目标。 - 注销此子模块（submodule 行菜单）——清空它的检出目录并让父仓库不再跟踪它。
.gitmodules条目保留，之后仍可再次初始化。若 submodule 有自己的改动——未提交的文件，或父仓库尚未记录的检出——会再确认一次才丢弃。
说明
Update all的并发度遵循git.concurrency设置（第 12 页）；默认值调低以温和对待网络。- submodule 的 fetch/push 使用它自己的远端与凭据；认证失败只对该 submodule 报类型化错误（排查见第 13 页）。
- 支持 submodule 套 submodule（
--recursive）——嵌套深度在进度输出中展示。 - 用本地文件夹路径添加需要放行 git 的 file 协议（
protocol.file.allow）；远端地址不受影响。