Git 仓库急救修复系统

Git 仓库急救工具，通过诊断-快照-修复-验证的流程，安全恢复损坏的 HEAD 状态、工作树元数据和引用问题，避免数据丢失。

基本信息

• 技能名称?Unfuck My Git State
• 中文名称?Git 仓库急救修复系统
• 作者?delorenj
• 分类?专业技能
• 版本?0.2.1
• 标签?git, devops, version-control, recovery, worktree, troubleshooting, shell-scripting, repository-maintenance

使用方法

使用说明
核心用法
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/ 目录后若未正确执行 git worktree prune ，可能导致 Git 内部状态与文件系统不一致。
   建议配置
   将 snapshot_git_state.sh 纳入任何自定义 Git 工作流的前置步骤
   对关键仓库启用 regression_harness.sh 的 phantom-branch-lock 和 orphaned-worktree 场景定期演练
   在团队 Wiki 中维护 symptom-map.md 的快速查询索引，缩短故障响应时间