Unfuck My Git State

核心用法

unfuck-my-git-state 是一套针对 Git 仓库严重损坏场景的系统性恢复方案。其核心流程遵循"诊断优先、快照保护、非破坏性修复、验证把关"的原则，处理包括游离 HEAD、幽灵工作树锁、孤立工作树条目、缺失引用、零值哈希等典型故障。

显著优点

1. 结构化恢复流程：将混乱的 Git 故障场景归纳为四大剧本（Orphaned Worktree、Phantom Branch Lock、Detached HEAD、Broken Refs），每个剧本提供精确的命令序列和决策点，大幅降低修复难度。

2. 防御性设计哲学：强制要求操作前执行状态快照（snapshot_git_state.sh），将 .git/ 目录视为生产数据；优先使用 git symbolic-ref 等官方 API，手动编辑 HEAD 作为最后手段；每个修复步骤后必须通过验证闸门。

3. 自动化支撑工具：提供症状路由映射（symptom-map.md）、引导式修复计划生成器（guided_repair_plan.sh）、回归测试套件（regression_harness.sh），支持在隔离环境中预演修复逻辑。

4. 可扩展的 hook 机制：为 CI/CD 和自定义工作树工具提供预检、后检、硬停止等自动化接入点，防止脚本化操作引入新的元数据损坏。

潜在缺点与局限性

• 依赖外部脚本：核心功能由多个 shell 脚本支撑（snapshot_git_state.sh、guided_repair_plan.sh 等），这些脚本未在技能文档中内嵌，实际可用性取决于仓库完整性和脚本可访问性。
• 场景覆盖边界：主要针对工作树元数据和引用层损坏，对于底层对象数据库损坏（corrupt packfile、blob hash mismatch）仅能通过 git fsck 检测，未提供修复方案。
• 需要人工判断：尽管有症状路由，部分场景（如"无法确定正确分支"）仍需用户基于 reflog 和时间戳做出决策，无法完全自动化。
• 学习曲线：术语体系（phantom lock、orphaned entry）和多层验证机制对普通用户有一定认知门槛。

适合人群

• 使用 Git 工作树功能（git worktree）的开发者，尤其是遇到多工作树元数据不一致问题
• DevOps/SRE 负责维护 CI/CD 中 Git 仓库健康状态
• 高级 Git 用户在复杂 rebase、cherry-pick 失败后需要系统性恢复
• 工具开发者需要为 Git 操作添加故障恢复和回归测试能力

常规风险

• 数据丢失风险：git branch -f 和 git symbolic-ref 操作会移动分支指针，若未事先检查 reflog 确认本地未推送提交，可能导致孤立提交。
• 并发操作冲突：修复过程中若有其他进程访问同一 .git/ 目录（如 IDE、监控脚本），可能触发竞态条件。
• 验证闸门绕过：若用户跳过 recovery-checklist.md 中的 git fsck 检查，可能遗留深层对象损坏，在后续操作中爆发。
• 工作树路径残留：手动删除 .git/worktrees/<name> 目录后若未正确执行 git worktree prune，可能导致 Git 内部状态与文件系统不一致。

建议配置

• 将 snapshot_git_state.sh 纳入任何自定义 Git 工作流的前置步骤
• 对关键仓库启用 regression_harness.sh 的 phantom-branch-lock 和 orphaned-worktree 场景定期演练
• 在团队 Wiki 中维护 symptom-map.md 的快速查询索引，缩短故障响应时间

核心功能

unfuck-my-git-state 是一款专注于 Git 仓库状态修复的运维工具，针对 detached HEAD、幽灵工作树锁、孤儿工作树条目、损坏的引用、全零哈希等典型 Git 异常场景提供结构化恢复方案。

显著优点

安全优先的设计理念 是该工具最突出的特点。强制要求"先快照、后修复、再验证"的三段式流程，所有破坏性操作前必须完成 .git/ 目录备份。Playbook 化的症状路由机制（A-D 四个剧本覆盖 90% 常见故障）配合 symbolic-ref 优先的手动修复策略，最大限度降低二次损坏风险。

零依赖架构 带来极高的可移植性。纯 Bash 脚本实现，无第三方包依赖，无网络通信，可在隔离环境或 CI/CD 容器中直接运行。860 行代码中 64.5% 为 Shell 脚本，34.4% 为 Markdown 文档，结构清晰易于审计。

完善的回归测试体系 包含可丢弃的场景模拟测试（regression_harness.sh），支持 orphaned-worktree、phantom-branch-lock 等特定故障模式演练，适合在自动化流程中集成。

潜在局限性

• 学习曲线陡峭：需要用户理解 Git 内部机制（symbolic-ref、worktrees 目录结构、fsck 输出）
• 故障覆盖有限：仅处理工作树元数据和引用层问题，不涉及对象数据库损坏（如 pack 文件损坏需 git gc --prune=now 等额外操作）
• 交互式依赖：部分修复步骤需要人工判断分支归属，暂未实现全自动修复

适合人群

• 频繁使用 Git 工作树（worktree）的多分支开发者
• DevOps 工程师维护 CI/CD 中的 Git 仓库状态
• 需要修复仓库但无法承受 rm -rf .git && git clone 数据丢失风险的场景

风险提醒

即使安全等级为 S，仍需注意：
1. git branch -f 和手动 echo 写入 .git/HEAD 属于强制操作，前置检查依赖用户执行
2. 多工作树场景下，修复一个工作树可能影响其他链接工作树的状态一致性
3. 建议在使用前完整阅读 references/recovery-checklist.md 验证清单