Unfuck My Git State

概述

Git State Recovery Specialist 是一套系统性的Git仓库状态修复技术，专门解决因操作中断、手动删除目录或工具冲突导致的仓库元数据损坏问题。

核心用法

该技能采用"诊断-分类-修复-预防"四阶段工作流：

诊断阶段：通过检查 .git/HEAD 内容、git worktree list 输出一致性、git symbolic-ref HEAD 与 git branch --show-current 交叉验证，快速定位损坏类型。

损坏分类：

• Type A（损坏的HEAD引用）：HEAD指向不存在分支，需强制重置
• Type B（孤立工作树元数据）：目录已删除但Git仍记录引用，需prune清理
• Type C（分支锁冲突）：工作树声明占用与实际HEAD不符，需对齐或强制删除

修复操作：提供从温和（git worktree prune）到激进（直接写入.git/HEAD、重建分支引用）的多级恢复手段，并包含"核选项"——完全从远程重建。

显著优点

1. 系统性：覆盖诊断、修复、预防完整生命周期，非临时救火方案
2. 工程化：提供Rust代码示例，可直接集成到iMi等工作树管理工具
3. 场景完整：包含PR分支误切主干、跨仓库工作树命名冲突等真实边缘案例
4. 渐进式：从标准命令到直接操作.git目录，风险可控地升级修复手段

潜在缺点/局限性

1. 需要人工判断损坏类型：自动诊断逻辑仅提供示例代码，未封装为一键工具
2. 直接操作.git目录风险：echo "ref: ..." > .git/HEAD 等方式绕过Git保护机制，误操作可能加剧损坏
3. 假设远程可用：核选项依赖完整远程历史，若远程也被污染则无法恢复
4. 未覆盖索引损坏：专注HEAD/分支/工作树，未涉及index文件损坏场景

适合人群

• 开发内部Git工具或CI/CD系统的工程师
• 高频使用git worktree的高级开发者
• 维护大型monorepo或复杂分支策略的团队

常规风险

• 强制重置HEAD可能导致未提交工作丢失（需先git stash或备份）
• git branch -D 强制删除会丢失仅存在于本地的提交
• 直接修改.git目录前务必执行建议的tar备份步骤
• 修复后应验证git fsck通过，确保对象数据库完整性

技能概述

recovering-from-bad-git-state 是一份专注于 Git 仓库状态恢复的纯文档型技能，提供系统化的诊断流程和修复方案，帮助开发者应对 Git 仓库的多种损坏场景。

核心用法

技能采用症状分类→诊断→修复的三层结构：

1. 状态验证：通过检查 .git/HEAD 内容、git worktree list 输出、以及 git symbolic-ref HEAD 的交叉比对，快速定位异常

2. 损坏类型识别：

• Type A (损坏的 HEAD 引用)：HEAD 指向不存在的分支，修复方式为强制重置 HEAD 到已知正常分支
• Type B (孤立 worktree)：手动删除目录未清理 Git 元数据，使用 git worktree prune 或手动清理 .git/worktrees/
• Type C (分支锁定冲突)：worktree 检出分支后 HEAD 被强制修改，需对齐 HEAD 或强制删除幽灵分支

3. 核选项重建：当引用完全损坏时，通过 git fetch --all --prune 配合分支重建恢复

显著优点

• 场景覆盖全面：涵盖 HEAD 损坏、worktree 孤立、分支锁冲突、多仓库命名冲突等边缘案例
• 预防导向设计：提供 Rust 代码示例展示如何在自动化工具中集成状态验证钩子
• iMi 生态集成：专门针对 iMi worktree 管理工具设计验证模式
• 风险分级处理：从标准修复到"核选项"再到备份-重建的升级路径

潜在局限性

• 纯文档无自动化：所有命令需手动执行，无一键修复脚本
• 假设用户熟练度：要求用户理解 Git 内部机制（如 .git/HEAD 文件格式、symbolic-ref 等）
• 特定生态绑定：iMi 集成章节对非 iMi 用户价值有限
• 无回滚机制：部分操作（如直接写入 .git/HEAD）具有破坏性，虽有备份建议但无自动回滚

适合人群

• 高级 Git 用户：理解 Git 对象模型和引用机制
• DevOps/平台工程师：维护多 worktree 开发环境或 CI/CD 中的 Git 操作
• iMi 工具用户：使用 iMi 进行多分支并行开发
• 开源项目维护者：处理贡献者因操作失误导致的仓库损坏

常规风险

| 操作 | 风险等级 | 注意事项 |

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

| `echo "ref: ..." > .git/HEAD` | **高** | 直接绕过 Git 安全检查，需确认目标分支存在 |

| `rm -rf .git/worktrees/` | 中 | 可能导致活跃 worktree 元数据丢失 |

| `git branch -D` + `git push --delete` | 高 | 强制删除会丢失未合并的远程分支 |

| `git reset --hard` | 高 | 丢弃本地未提交更改 |

关键建议：技能文档明确推荐在执行"核选项"前创建备份（tar -czf repo-backup.tar.gz .git/），用户应严格遵守此步骤。

与其他工具对比

相比 git reflog 或 git fsck 等底层工具，本技能提供场景化的问题-解决方案映射，而非要求用户自行推断损坏原因。但与 git-undo 等插件相比，缺乏交互式引导和自动检测能力。