unfuck-my-git-state

在不扩大故障影响范围的前提下恢复仓库状态。

核心原则

1. 先做快照，切勿“随便试试”。
2. 优先采用非破坏性修复方式，再考虑强制操作。
3. 在完成备份前，将 .git/ 视为生产数据对待。
4. 修改 .git/HEAD 前，应优先使用 git symbolic-ref。
5. 每次修复后，必须运行验证步骤，确认无误后再继续后续操作。

快速工作流

1. 采集诊断信息：

bash scripts/snapshot_git_state.sh .

2. 依据症状，参考 references/symptom-map.md 进行归类定位。
3. 生成非破坏性命令执行方案：

bash scripts/guided_repair_plan.sh --repo .

4. 应用最小且匹配的 playbook。
5. 执行 references/recovery-checklist.md 中定义的验证检查点。
6. 仅当验证检查点失败时，才进入升级处理流程。

如需显式指定路径：

bash scripts/guided_repair_plan.sh --list
bash scripts/guided_repair_plan.sh --symptom phantom-branch-lock

回归测试框架

在修改脚本逻辑前，使用可丢弃的模拟测试进行验证：

bash scripts/regression_harness.sh

运行单个测试场景：

bash scripts/regression_harness.sh --scenario orphaned-worktree

Playbook A：孤立的工作树元数据

症状：

• git worktree list 显示一个已不存在的路径。
• 工作树条目中包含无效哈希或全零哈希。

操作步骤：

git worktree list --porcelain
git worktree prune -v
git worktree list --porcelain

若仍有陈旧条目残留，请先备份 .git/，然后手动删除 .git/worktrees/ 下对应的具体陈旧目录，再重新运行 prune。

Playbook B：幽灵分支锁

症状：

• git branch -d 或 git branch -D 报错：“already used by worktree”（已被工作树占用）。
• git worktree list 显示的分支归属与实际不符。

操作步骤：

git worktree list --porcelain

定位正在使用该分支的工作树，在该工作树中切换至其他分支或分离 HEAD，随后回到主仓库重试分支操作。

Playbook C：分离或矛盾的 HEAD

症状：

• git status 意外提示 “detached HEAD”。
• git branch --show-current 与 git symbolic-ref -q HEAD 输出结果不一致。

操作步骤：

git symbolic-ref -q HEAD || true
git reflog --date=iso -n 20
git switch 

若无法确定当前分支上下文，可基于当前提交创建救援分支：

git switch -c rescue/$(date +%Y%m%d-%H%M%S)

待调查完成后，再重新关联至预期分支。

Playbook D：缺失或损坏的引用（refs）

症状：

• 报错 “unknown revision”、“not a valid object name” 或 “cannot lock ref”。

操作步骤：

git fetch --all --prune
git show-ref --verify refs/remotes/origin/
git branch -f  origin/
git switch 

在强制重置分支指针前，请务必利用 reflog 恢复本地未推送的提交。

最后手段：手动修复 HEAD

仅在已完成 .git/ 备份后执行。

推荐方式：

git show-ref --verify refs/heads/
git symbolic-ref HEAD refs/heads/

当 symbolic-ref 不可用时的备用方式：

echo "ref: refs/heads/" > .git/HEAD

立即运行验证检查点。

验证检查点（必须通过）

运行 references/recovery-checklist.md 中定义的全部检查项。最低要求包括：

• git status 干净退出，无任何致命错误。
• git symbolic-ref -q HEAD 输出与预期分支一致。
• git worktree list --porcelain 中无缺失路径，且无全零哈希值。
• git fsck --no-reflogs --full 不报告任何新增的关键性错误。

升级处理路径

1. 归档 .git 目录：

tar -czf git-metadata-backup-$(date +%Y%m%d-%H%M%S).tar.gz .git

2. 从远端仓库全新克隆。
3. 借助 reflog 和 cherry-pick，从旧克隆中恢复尚未推送的工作内容。
4. 记录故障模式，并为自动化流程添加防护机制。

自动化钩子规范

在构建工作树相关工具（iMi、脚本、机器人等）时，须强制落实以下约束：

• 预检快照与状态校验
• 操作后验证检查点
• 对 HEAD / ref 不一致情况实施硬性中断
• 所有破坏性命令执行前，必须获得用户显式确认

参考资料

• 症状路由表：references/symptom-map.md
• 验证检查清单：references/recovery-checklist.md
• 诊断快照脚本：scripts/snapshot_git_state.sh
• 引导式修复方案生成器：scripts/guided_repair_plan.sh
• 可丢弃回归测试框架：scripts/regression_harness.sh