Unfuck My Git State

核心定位

unfuck-my-git-state 是一套面向 Git 仓库灾难恢复的专业级诊断修复工具，针对 detached HEAD、phantom worktree locks、orphaned entries、无效哈希、引用锁定失败等复杂故障场景提供结构化救援流程。

核心用法

工具采用"快照优先、分阶段验证"的安全哲学：

1. 诊断阶段：运行 snapshot_git_state.sh 捕获完整元数据，建立可回溯基线
2. 路由阶段：依据 symptom-map.md 匹配症状到具体剧本（Playbook A-D）
3. 修复阶段：执行 guided_repair_plan.sh 生成的最小化非破坏性命令序列
4. 验证阶段：通过 recovery-checklist.md 门禁检查，失败则触发升级路径

显著优点

• 风险可控：强制快照备份、禁止"试试看"式盲目操作，将 .git/ 视为生产数据
• 结构化决策：症状→剧本→命令的显式路由，消除猜测和 Stack Overflow 驱动编程
• 防御性验证：每步操作后强制检查点，确保状态可观测
• 回归测试：regression_harness.sh 支持 disposable simulation，脚本逻辑变更前可安全验证
• 自动化友好：内置 preflight/post-operation hooks，适合集成到 CI/CD 和机器人工作流

潜在局限

• 依赖本地脚本生态：需配套 scripts/ 和 references/ 目录结构，非单文件可移植方案
• 学习曲线：术语体系（phantom lock、orphaned worktree）对初级用户有一定门槛
• 远程场景有限：主要覆盖本地仓库元数据修复，大规模团队协作冲突需配合流程规范
• 非万能：明确划定"Last Resort"边界，极端损坏场景建议归档后重新克隆

适合人群

• 频繁使用 Git worktree 的高级开发者
• 维护复杂多分支 CI/CD 流水线的 DevOps 工程师
• 需要为团队建立 Git 灾难响应 SOP 的技术负责人
• 编写 Git 自动化工具（bots、CLI wrappers）的开发者

常规风险

| 风险点 | 说明 |

|--------|------|

| 数据丢失 | 未执行快照即强制修复可能加剧损坏 |

| 验证跳过 | 绕过 `recovery-checklist.md` 门禁可能遗留潜伏故障 |

| 并发冲突 | 多 worktree 环境下分支所有权竞争需人工协调 |

| 自动化误用 | 脚本钩子若未配置用户确认，可能意外执行 destructive 命令 |

安全等级 S+ 的来源依据：强制备份策略、非破坏性优先原则、完整的验证门禁和升级路径设计。

核心用法

unfuck-my-git-state 是一套 Git 状态诊断与恢复工具集，采用「快照优先、分级修复」的保守策略，解决日常开发中遭遇的棘手 Git 故障：

• 分离 HEAD / 矛盾 HEAD 状态 —— 通过 git symbolic-ref 与 reflog 安全重连分支
• 幽灵分支锁 —— 识别多工作树占用冲突，优雅释放分支引用
• 孤立工作树元数据 —— 清理已删除路径的残留工作树条目
• 损坏或缺失的 refs —— 利用远程引用与 reflog 重建分支指针
• 零哈希异常 —— 定位并修复 0000000000000000000000000000000000000000 等无效对象引用

标准工作流程：
1. 运行 snapshot_git_state.sh 创建诊断快照（只读，零风险）
2. 根据症状路由至对应 Playbook（A-D）
3. 使用 guided_repair_plan.sh 生成非破坏性修复命令
4. 每步执行后通过 recovery-checklist.md 验证门控
5. 失败则归档 .git/ 并走升级路径（克隆新仓库 + cherry-pick 恢复）

---

显著优点

| 维度 | 表现 |

|------|------|

| **安全设计** | 强制「备份 → 诊断 → 修复 → 验证」四段式流程，拒绝「先试试」的赌徒心态 |

| **非破坏性优先** | 所有 Playbook 优先使用 `git symbolic-ref`、`git worktree prune` 等原生命令，手动编辑 `.git/` 被列为「最后手段」 |

| **零依赖** | 纯 Bash 实现，无 npm/pip/gem 依赖，规避供应链攻击面 |

| **回归测试** | 内置 `regression_harness.sh`，支持隔离场景（`--scenario orphaned-worktree`）预演修复逻辑 |

| **可审计** | 每步操作可回放，`.git` 归档包支持事后取证与自动化 Guardrail 迭代 |

---

潜在缺点与局限性

1. 人工介入门槛：症状路由需要用户理解 Git 内部机制（refs、worktrees、symbolic-ref），纯新手可能误操作
2. 大型仓库性能：snapshot_git_state.sh 在十万级提交仓库中可能耗时较长，无进度提示
3. T3 来源风险：作者 delorenj 为个人开发者，无组织背书，需关注后续更新签名
4. 无 GUI/IDE 集成：纯命令行工具链，需手动在终端执行
5. 极端损坏场景：若 .git/objects 损坏或远程仓库不可达，工具只能归档止损，无法魔术恢复

---

适合人群

• 资深开发者：有 5 年以上 Git 使用经验，理解 reflog、detached HEAD、worktree 概念
• DevOps/SRE：负责 CI/CD 仓库维护，需快速修复构建节点的异常 Git 状态
• 开源维护者：管理多工作树或复杂分支策略的仓库，遭遇「already checked out by worktree」类错误
• Git 讲师/布道者：作为教学案例演示 Git 内部数据模型与恢复技术

不适合：Git 初学者（建议先学习 git reflog 基础）、追求一键修复的「懒人」、无备份习惯的冒险者。

---

常规风险与应对

| 风险场景 | 触发条件 | 缓解措施 |

|----------|----------|----------|

| **数据丢失** | 跳过备份直接运行破坏性命令 | 工具内置强制检查：`git status` 异常时拒绝继续 |

| **分支覆盖** | 强制重置指针到 origin 导致本地未推送提交丢失 | Playbook D 明确要求先检查 reflog 再执行 `branch -f` |

| **工作树误删** | 手动删除 `.git/worktrees/` 文件夹时选错路径 | 仅删除确认「路径不存在且哈希无效」的条目，保留其他 |

| **权限问题** | 脚本在只读文件系统或 root 权限下运行 | `set -euo pipefail` 确保失败即停，不静默忽略 |

| **社会工程学** | 攻击者伪装更新植入恶意代码 | T3 来源建议手动校验 SHA256，勿自动信任 `curl | bash` |

---

认证与合规

• CLS 六维扫描：静态代码 90 分、动态行为 85 分、零依赖 100 分、网络隔离 100 分
• 合规通过：GDPR 数据最小化、无硬编码凭证、无动态代码加载、无权限升级诱导
• 建议行动：关注作者 GitHub 动态，重大更新时人工校验 sha256:9da802a737d44b0c4ef9b4fbbf3a34be40aae1f3fa6775edfd9d9cb1b4174cae