pikasTech-unidesk/docs/reference/worktree-submodule-cleanup.md

含子模块的任务 Worktree 清理

职责边界

• 通用 worktree 同步、并行改动保护、语义合并和清理前判定继续以 DevOps hygiene 为唯一权威。
• 本文只补充任务 worktree 含 Git submodule 时的清理动作：
  • 不改变通用语义合并门槛；
  • 不授权丢弃 superproject 或 submodule 的修改；
  • 不授权删除未进入目标分支的提交。

清理前置

• 固定主 worktree 已同步目标 remote/base。
• 任务 worktree 的 superproject 必须 clean。
• 每个已初始化 submodule 必须同时满足：
  • worktree clean；
  • 当前提交存在于固定 source authority；
  • superproject 的目标 gitlink 已进入目标分支。
• 任务分支提交必须已经是目标分支祖先，或经语义核查确认没有未吸收 patch。
• 待删除路径必须是 Git 已登记的明确任务 worktree 绝对路径。

最短路径

• 完成前置核查后，直接从固定主 worktree 执行：

git -C <fixed-root> worktree remove --force <absolute-task-worktree>
git -C <fixed-root> branch -d <merged-task-branch>
git -C <fixed-root> fetch --prune <remote>

• 这里的 --force 只用于越过 Git 对“worktree 含 submodule”的结构性拒绝：
  • 必须先证明 superproject 和全部 submodule clean；
  • 必须先证明任务语义已经进入目标分支；
  • 任一前置不成立时禁止执行。
• 清理后必须复核：
  • 任务路径不再出现在 git worktree list --porcelain；
  • 固定主 worktree 与目标 remote/base 对齐且 clean；
  • 固定主 worktree 的 submodule 仍指向目标 gitlink。

禁止绕行

• 禁止用 rm -rf、覆盖式 checkout 或 reset 代替 Git worktree 清理。
• 不要把 git submodule deinit 作为移除任务 worktree 的前置：
  • 多 worktree 可能共享 submodule 注册配置；
  • 在任务 worktree 执行 deinit 可能让固定主 worktree 显示为未初始化。
• 如果历史操作已经执行 deinit，必须在固定主 worktree 恢复并复核：

git -C <fixed-root> submodule update --init -- <submodule-path>
git -C <fixed-root> submodule status <submodule-path>
git -C <fixed-root> status --short --branch

• submodule status 的目标行必须以空格开头：
  • - 表示未初始化；
  • + 表示检出提交与目标 gitlink 不一致；
  • 两者都不能作为清理完成状态。