介绍
# unfuck-my-git-state
在不扩大影响范围的情况下恢复代码仓库。
## 核心规则
1. 先做快照。不要“随便试试”。 2. 在执行强制操作之前，优先选择非破坏性修复。 3. 在备份之前，将 `.git/` 视为生产数据。 4. 在手动编辑 `.git/HEAD` 之前使用 `git symbolic-ref`。 5. 每次修复后，在继续操作前运行验证。
## 快速工作流
1. 捕获诊断信息： ```bash bash scripts/snapshot_git_state.sh . ``` 2. 使用 `references/symptom-map.md` 根据症状进行路由。 3. 生成非破坏性命令计划： ```bash bash scripts/guided_repair_plan.sh --repo . ``` 4. 应用匹配度最小的操作手册。 5. 运行 `references/recovery-checklist.md` 验证关卡。 6. 仅当验证失败时才进行升级处理。
用于显式路由： ```bash bash scripts/guided_repair_plan.sh --list bash scripts/guided_repair_plan.sh --symptom phantom-branch-lock ```
## 回归测试套件
在更改脚本逻辑之前，使用一次性模拟测试：
```bash bash scripts/regression_harness.sh ```
运行一个场景：
```bash bash scripts/regression_harness.sh --scenario orphaned-worktree ```
## 操作手册 A：孤立的工作区元数据
症状： - `git worktree list` 显示了一个不存在的路径。 - 工作区条目包含无效或哈希为零的内容。
步骤： ```bash git worktree list --porcelain git worktree prune -v git worktree list --porcelain ``` 如果仍有陈旧条目，请备份 `.git/` 并删除 `.git/worktrees/<name>` 下的特定陈旧文件夹，然后重新运行 prune 命令。
## 操作手册 B：幽灵分支锁定
症状： - `git branch -d` 或 `git branch -D` 失败，提示“已被 worktree 使用”。 - `git worktree list` 似乎与分支归属不一致。
步骤： ```bash git worktree list --porcelain ``` 找到使用该分支的工作区，将那个工作区切换到另一个分支或在此处分离 HEAD，然后在主仓库中重试分支操作。
## 操作手册 C：分离或矛盾的 HEAD
症状： - `git status` 意外地提示分离的 HEAD (detached HEAD)。 - `git branch --show-current` 和 `git symbolic-ref -q HEAD` 的结果不一致。
步骤： ```bash git symbolic-ref -q HEAD || true git reflog --date=iso -n 20 git switch <known-good-branch> ``` 如果分支上下文未知，请从当前提交创建一个救援分支： ```bash git switch -c rescue/$(date +%Y%m%d-%H%M%S) ``` 然后在调查后重新连接到预期的分支。
## 操作手册 D：丢失或损坏的引用 (Refs)
症状： - `unknown revision`（未知修订）、`not a valid object name`（不是有效的对象名）或 `cannot lock ref`（无法锁定引用）。
步骤： ```bash git fetch --all --prune git show-ref --verify refs/remotes/origin/<branch> git branch -f <branch> origin/<branch> git switch <branch> ``` 在强制移动分支指针之前，使用 `reflog` 恢复仅本地的提交。
## 最后手段：手动修复 HEAD
仅在备份 `.git/` 之后执行。
首选方式： ```bash git show-ref --verify refs/heads/<branch> git symbolic-ref HEAD refs/heads/<branch> ``` 当无法使用 `symbolic-ref` 时的后备方案： ```bash echo "ref: refs/heads/<branch>" > .git/HEAD ``` 立即运行验证关卡。
## 验证关卡（必须通过）
运行 `references/recovery-checklist.md` 中的检查。最低标准： - `git status` 干净退出，无致命错误。 - `git symbolic-ref -q HEAD` 与预期分支匹配。 - `git worktree list --porcelain` 没有缺失路径，也没有哈希为零的条目。 - `git fsck --no-reflogs --full` 没有新的关键错误。
## 升级路径
1. 归档 `.git`： ```bash tar -czf git-metadata-backup-$(date +%Y%m%d-%H%M%S).tar.gz .git ``` 2. 从远程重新克隆。 3. 使用 reflog 和从旧克隆中 cherry-pick 来恢复未推送的工作。 4. 记录失败模式并向自动化流程添加防护措施。
## 自动化钩子
在构建工作区工具（iMi、脚本、机器人）时，强制执行： - 预检快照和状态验证 - 操作后验证关卡 - 在 HEAD/引用不一致时强制停止 - 在执行破坏性命令前需要用户明确确认
## 资源
- 症状路由器：`references/symptom-map.md` - 验证检查清单：`references/recovery-checklist.md` - 诊断快照脚本：`scripts/snapshot_git_state.sh` - 引导式计划生成器：`scripts/guided_repair_plan.sh` - 一次性回归测试套件：`scripts/regression_harness.sh`