Git状态修复

技能简介

本技能提供系统化的Git仓库状态诊断与修复流程，针对分离HEAD、幽灵工作树锁、孤立工作树条目、缺失引用、零哈希值等异常场景，采用分阶段低风险恢复策略。

业务背景

开发团队常因Git仓库异常陷入停滞：分离HEAD导致代码提交丢失、工作树锁冲突阻断协作、分支操作失败影响发版节奏。本技能提供标准化诊断流程，快速定位根因并生成安全修复方案，避免工程师盲目操作造成数据损坏，缩短故障恢复时间，保障研发流水线持续运转。

落地案例：某项目组反馈无法切换分支，提示"已检出"错误。经诊断发现存在幽灵工作树锁占用目标分支。按技能指引，先定位占用该分支的工作树环境，完成上下文切换后释放分支锁定，再执行分支删除与重建。全程通过快照备份与非破坏性验证，确保代码历史完整无损，团队恢复正常协作。

能做什么

• 诊断Git仓库的异常状态（分离HEAD、矛盾引用、工作树锁冲突）
• 生成非破坏性修复命令计划
• 清理孤立或损坏的工作树元数据
• 修复分支操作失败（已检出、未知版本、无效对象名）
• 通过回归测试验证修复脚本

使用说明

安装准备

克隆技能仓库到本地：

git clone https://github.com/openclaw/skills.git
cd skills/delorenj/unfuck-my-git-state

快速修复流程

1. 捕获诊断快照：

   bash scripts/snapshot_git_state.sh .

2. 根据症状路由：参考 references/symptom-map.md
3. 生成修复计划：

   bash scripts/guided_repair_plan.sh --repo .

4. 应用最小匹配剧本
5. 运行验证检查清单
6. 仅当验证失败时升级处理

按症状选择剧本

• 孤立工作树元数据：执行 git worktree prune -v，必要时手动清理 .git/worktrees/
• 幽灵分支锁：切换占用分支的工作树后再删除分支
• 分离HEAD：使用 git switch 或创建救援分支
• 缺失引用：先 git fetch --all --prune 再强制重置分支

回归测试

bash scripts/regression_harness.sh
bash scripts/regression_harness.sh --scenario orphaned-worktree

输入与输出

见下方输入与输出表格。

风险提示

• 任何修复前必须执行快照备份，禁止直接尝试修复
• 将 .git/ 视为生产数据，备份后方可操作
• 优先使用 git symbolic-ref 而非直接编辑 .git/HEAD
• 每次修复后必须通过验证门控才能继续
• 手动HEAD修复为最后手段，需完整归档 .git 目录

来源信息

原始链接：https://github.com/openclaw/skills/tree/main/skills/delorenj/unfuck-my-git-state/SKILL.md
来源类型：GitHub仓库