get-shit-done 更新后本地改动被覆盖怎么办：gsd-local-patches 备份与 --reapply-平芜编程栈

get-shit-done 更新后本地改动被覆盖怎么办：gsd-local-patches 备份与 --reapply

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done

如果你直接修改过 get-shit-done（GSD）安装的 workflow、command 或 agent 文件，再运行更新时，这些改动会被安装器的 clean install 覆盖——GSD 的更新机制是对 GSD 托管目录做 wipe-and-replace。从 v1.17 开始，安装器会在覆盖前把检测到的本地修改文件备份到gsd-local-patches/目录，之后通过/gsd-update --reapply命令可以把改动合并回新版本。本文说明如何确认备份存在、如何执行恢复、如何读懂恢复结果，以及遇到冲突或验证失败时怎么处理。

更新为什么会覆盖本地改动

/gsd:update更新时执行的安装程序会清除并替换 GSD 托管的目录，包括commands/gsd/、get-shit-done/、agents/gsd-*文件（全局安装时位于~/.claude/等运行时目录，本地安装时位于项目下的./.claude/等目录）。以下文件不受影响，会被保留：

commands/gsd/之外的自定义 command
不以gsd-开头的自定义 agent
自定义 hooks
你的CLAUDE.md文件

对于你直接修改过的 GSD 文件，安装器通过 SHA-256 哈希比较检测出它们是"被修改过的"，在覆盖前自动备份到配置目录下的gsd-local-patches/，并写入清单文件backup-meta.json；同时保存更新前的原始副本到gsd-pristine/目录，用于恢复时的三方比较。更新流程结束后会自动检查该备份目录，若发现备份会提示：

Local patches were backed up before the update. Run `/gsd:update --reapply` to merge your modifications into the new version.

也就是说，"改动被覆盖"这件事本身在 v1.17 及以上版本不会造成永久丢失，前提是备份确实生成了——下面先确认这一点。

第一步：确认 gsd-local-patches 备份是否存在

备份目录位于运行时配置目录下，位置取决于安装作用域和运行时：

全局安装（Claude Code）：~/.claude/gsd-local-patches/
全局安装（其他运行时）：~/.config/opencode/、~/.opencode/、~/.gemini/、~/.config/kilo/或~/.codex/下的gsd-local-patches/
本地安装：项目下./.claude/、./.opencode/、./.gemini/等对应目录下的gsd-local-patches/

如果安装时用过环境变量指定配置目录（如CLAUDE_CONFIG_DIR、OPENCODE_CONFIG_DIR、GEMINI_CONFIG_DIR、CODEX_HOME、KILO_CONFIG_DIR），备份目录在环境变量指向的目录下，而不是默认路径。

以 Claude Code 全局安装为例，可以这样检查：

# 检查更新是否产生了本地补丁备份 ls ~/.claude/gsd-local-patches/backup-meta.json

backup-meta.json里记录了被备份的文件列表，以及每个文件的原始内容哈希（pristine_hashes字段），reapply时用它来定位三方比较的基线。

两个需要区分的边界情况：

如果更新提示中没有备份、目录也不存在，/gsd-update --reapply会输出 "No local patches found. Nothing to reapply."——说明你没有改动过 GSD 托管文件，无需恢复。
更新流程对"用户自己新增的、不在安装清单里的文件"另有处理：它会把它们备份到gsd-user-files-backup/而不是gsd-local-patches/。这类文件不在--reapply的恢复范围内，需要更新后自行从备份目录恢复。

第二步：运行 /gsd-update --reapply 合并改动

确认备份存在后，在运行时里执行/gsd-update --reapply。该命令路由到 reapply-patches 工作流（见 reapply-patches 工作流、update 命令定义），整个过程由工作流自动完成，你主要参与的是冲突裁决：

检测备份：定位gsd-local-patches/，读取backup-meta.json。
确定三方比较基线：按优先级使用 git 历史（配置目录是 git 仓库时，用pristine_hashes匹配对应提交）、gsd-pristine/快照目录；两者都没有则退化为增强的双向比较。三方比较用"更新前原始版本、你的备份版本、新安装版本"来区分哪些是你改的、哪些是上游版本迭代。
显示补丁摘要：列出来源版本、当前版本、修改文件数和采用的合并策略（three-way (git)、three-way (pristine)或two-way (enhanced)），每个文件初始状态为 Pending。
逐文件合并，合并规则是：
- 只有你改过的部分 → 保留你的版本
- 只有上游改过的部分 → 接受上游版本
- 双方都改过的部分 → 标记为 CONFLICT，展示两个版本由你选择
- 双方都没改 → 用新版本
合并后验证：对工作流输出的每个用户改动块做行存在性检查，产出 Hunk Verification Table（每行一个改动块，verified列标明是否在新文件中确认存在），并运行确定性验证脚本 verify-reapply-patches.cjs 做结构化校验。
清理选项：验证全部通过后询问你是否保留gsd-local-patches/作为参考，或将其删除。
输出最终报告：

## Patches Reapplied | # | File | Result | User Changes Preserved | |---|------|--------|----------------------| | 1 | {file_path} | Merged | Added step X, modified section Y | | 2 | {file_path} | Incorporated | Already in upstream v{version} | | 3 | {file_path} | Conflict resolved | User chose: keep custom section |

上面的表格是文档给出的报告格式示例，实际内容以你的文件为准。

第三步：判断恢复是否成功

按文件核对最终报告，成功条件是工作流列出的成功标准：所有备份文件都被处理（零遗漏）、没有任何文件被归类为"无自定义内容"、每个文件都有状态说明并附保留内容摘要。单个文件的正常结果是Merged（你的修改已干净合并）、Conflict resolved（你裁决过冲突）或Incorporated（上游已收录了你的修改，仅当有原始基线确认时才会出现此状态）。

Hunk Verification Table 中verified列的含义：yes表示该改动块的首行在合并后的新文件中找到了；no表示改动块可能丢失，需要处理（见下节）。

验证失败或流程被暂停时怎么办

reapply 有两道验证门：确定性脚本校验（强制门）和 Hunk Verification Table 复查（建议门），任一未通过都不会进入清理步骤。文档给出了对应的处理路径：

脚本校验失败（退出码非零）：报告会列出哪些用户新增行在新文件中缺失，并给出两个解决选项——手工把缺失内容重新合并进已安装文件，或直接从备份恢复该文件：cp {patches_dir}/{file} {installed_path}（{patches_dir}为你的gsd-local-patches/目录，{installed_path}为文件在配置目录下的对应路径）。处理完后重新运行/gsd:update --reapply再次验证。
pristine 快照漂移（Bug #3657）：即使脚本退出码为 0，报告也可能标记部分文件因gsd-pristine/快照哈希与backup-meta.json记录不一致而被跳过，此时流程会暂停。文档给出的三个解决选项：(a) 把 pristine 快照重新锚定到backup-meta.json记录的版本；(b) 从备份恢复受影响文件后手工重新合并；(c) 若上游改动可以接受，把backup-meta.json中对应文件的pristine_hashes更新为当前磁盘哈希，再重新运行/gsd:update --reapply。
Hunk Verification Table 缺失或存在verified: no行：暂停并提示备份位置，按同样方式手工重合并或从备份恢复后再重跑。

限制与注意事项

备份机制自 v1.17.0 引入（见 CHANGELOG）。更早版本安装的 GSD 没有gsd-local-patches/备份，更新前请先自行保留对 GSD 文件的修改。
备份覆盖的是"被修改的 GSD 托管文件"；你新加在 GSD 目录下的自定义文件走的是gsd-user-files-backup/通道，--reapply不负责恢复它们。
即使某个文件的差异看起来全是路径替换、变量注入这类"机械漂移"，工作流也不会静默跳过，而是标记为 CONFLICT 让你确认——因为安装器的哈希比较已经证明该文件被改过，"没有自定义内容"不是合法的结论。
更新完成、恢复完成之后，仍需要按更新流程的提示重启运行时，才能加载新的命令和 agent。