Git 子模块管理工具，作为 qtcloud-devops CLI 的 code 子命令集提供。
code 命令不做 git 已有的事（添加、初始化、更新、切换分支等直接用 git 命令），只做 git 做不到的事：三路 commit 比对 + 7 种状态分类 和 子模块 → 父仓库指针同步。
安装¶
通过 pip install qtcloud-devops-cli 或 cargo install qtcloud-devops-cli 安装。详见 安装文档。
CLI 快速参考¶
qtcloud-devops code <COMMAND> [选项] [参数]命令详解¶
status — 查看仓库及子模块状态¶
qtcloud-devops code status
qtcloud-devops code status /path/to/repo输出 JSON 格式：
| 字段 | 含义 |
|---|---|
parent_dirty | 主仓库是否有未提交的变更 |
submodules | 子模块列表（无子模块时为 []） |
total | 子模块总数 |
clean_count | Clean 状态的子模块数 |
needs_attention | 需要关注的子模块名称列表 |
无子模块时退化到普通 git 仓库状态检测，仅报告 parent_dirty。
子模块 7 种状态¶
通过三路 commit 比对（父仓库指针 / 本地 HEAD / 远程 HEAD）判定：
| 状态 | 含义 | 建议 |
|---|---|---|
| Clean / 干净 | 三方 commit 一致 | 无需操作 |
| AheadOfParent / 领先 | 本地有父仓库未记录的新提交 | code sync <name> |
| BehindRemote / 落后 | 远程有更新，本地落后 | git submodule update --remote <name> |
| Detached / 游离 | 游离 HEAD | git checkout <name> <branch> |
| Dirty / 脏 | 有未提交的修改 | 手动 commit 或 stash |
| Orphaned / 孤儿 | 父仓库记录的 commit 在远程已不存在 | 手动干预 |
| Uninitialized / 未初始化 | 尚未初始化 | git submodule update --init <name> |
远程不可达时跳过 Orphaned/BehindRemote 判定。
Orphaned 状态详解¶
Orphaned（孤儿）表示父仓库记录的 commit 在远程仓库中已经不存在了。这是唯一无法自动收敛的状态，需要人工干预。
常见原因：
| 场景 | 说明 |
|---|---|
| 子模块 rebase + force push | 开发者 rebase 后 git push --force，旧 commit 被丢弃。最常见的情况 |
| squash merge PR | GitHub squash merge 把多个 commit 合并为一个，原 commit 消失 |
| 子模块仓库被替换 | 子模块 URL 指向了新的仓库，旧 commit 历史不存在 |
| 远程 gc 清理 | 远程仓库 git gc 清掉了未被引用的孤立 commit（极少见） |
如何处理：找到子模块远程存在的一个接近的 commit，手动更新父仓库指针后重新同步。
sync — 端到端子模块同步¶
三步完成子模块同步：
推送子模块 — 将子模块本地 commit 推送到子模块的 remote
更新父指针 — 更新父仓库中的子模块指针并本地提交
推送父仓库 — 将父仓库的指针更新推送到 remote
省略名称时同步全部。
qtcloud-devops code sync lib-a
qtcloud-devops code sync # 同步全部retire — 退役子模块¶
完整自动化反注册：deinit + .gitmodules + index 清理。
qtcloud-devops code retire lib-old常见场景¶
# 查看状态（含主仓库自身）
qtcloud-devops code status
# 同步子模块并推送到 remote
qtcloud-devops code sync lib-a
# 退役
qtcloud-devops code retire lib-old故障排除¶
qtcloud-devops code --help
qtcloud-devops code <COMMAND> --help