（12282期）Unfuck My Git State – Git 仓库急救修复系统

Git 仓库急救修复系统 Git 仓库急救工具，通过诊断-快照-修复-验证的流程，安全恢复损坏的 HEAD 状态、工作树元数据和引用问题，避免数据丢失。 使用说明 核心用法 unfuck-my-git-state 是一套针对 Git 仓库严重损坏场景的系统性恢复方案。其核心流程遵循"诊断优先、快照保护、非破坏性修复、验证把关"的原则，处理包括游离 HEAD、幽灵工作树锁、孤立工作树条目、缺失引用、零值哈希等典型故障。 显著优点 结构化恢复流程：将混乱的 Git 故障场景归纳为四大剧本（Orphaned Worktree、Phantom Branch Lock、Detached HEAD、Broken Refs），每个剧本提供精确的命令序列和决策点，大幅降低修复难度。 防御性设计哲学：强制要求操作前执行状态快照（snapshotgitstate.sh），将 .git/ 目录视为生产数据；优先使用 git symbolic-ref 等官方 API，手动编辑 HEAD 作为最后手段；每个修复步骤后必须通过验证闸门。 自动化支撑工具：提供症状路由映射（symptom-map.md）、引导式修复计划生成器（guidedrepairplan.sh）、回归测试套件（regression_harness.sh），支持在隔离环境中预演修复逻辑。 可扩展的 hook 机制：为 CI/CD 和自定义工作树工具提供预检、后检、硬停止等自动化接入点，防止脚本化操作引入新的元数据损坏。 潜在缺点与局限性 依赖外部脚本：核心功能由多个 shell 脚本支撑（snapshotgitstate.sh、guidedrepairplan.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 内部状态与文件系统不一致。 建议配置 将 snapshotgitstate.sh 纳入任何自定义 Git 工作流的前置步骤 对关键仓库启用 regression_harness.sh 的 phantom-branch-lock 和 orphaned-worktree 场景定期演练 在团队 Wiki 中维护 symptom-map.md 的快速查询索引，缩短故障响应时间 原始说明 Diagnose and recover broken Git state and worktree metadata with a staged, low-risk recovery flow. Use when Git reports detached or contradictory HEAD state, phantom worktree locks, orphaned worktree entries, missing refs, 0000000000000000000000000000000000000000 hashes, or branch operations fail with errors like already checked out, unknown revision, not a valid object name, or cannot lock ref.