FAQ.md

常见问题与注意事项

⚠️ 可以在游戏运行时使用 gitsave 保存或回滚吗？

不建议，且存在损坏存档的风险。

除非你已经对目标游戏的文件读写规律有非常充分的了解，否则请务必在游戏完全退出后，再使用本工具进行任何文件读写操作（保存、回滚、导出等）。

风险说明：
游戏在运行时会持续向存档文件写入数据，例如生成新地形、自动保存区块、更新玩家状态等。如果你的工具恰好在游戏写入的毫秒级瞬间复制该文件，将产生"撕裂写"（Torn Write）现象——即被复制的文件头部是新数据、中间或尾部还是旧数据，或者文件校验和不匹配，导致文件结构损坏。

直接回滚这种损坏快照，通常会导致游戏加载时报错：

• "损坏的区块"（Corrupted chunk）
• "Failed to load world"

这类损坏往往难以修复，且无法通过 gitsave 自动识别或绕过。

推荐做法：先完全退出游戏，再执行 gitsave save 或任何回滚操作。

为什么提示不是 gitsave 仓库？

请先在目标存档目录执行 gitsave init。

可以在已有 .git 的目录里使用 gitsave 吗？

不建议。gitsave 依赖 Git 行为，如果在已有 .git 的项目目录中使用，可能污染项目提交历史或造成误操作。建议在独立的存档目录使用 gitsave。

误在错误路径执行了 gitsave init 怎么办？

如果在系统目录、游戏安装目录或其他不该初始化的路径执行了 gitsave init，请直接删除该目录下的 .git 文件夹即可撤销初始化。

为什么会出现“初始化后历史丢失”？

通常是因为在已有 gitsave 仓库的子目录或已存在 .git 的目录中执行了 gitsave init，生成了新的 .git，TUI 会绑定到最近的仓库而看不到原历史。解决方式：删除误创建的 .git，并回到正确的存档根目录使用 gitsave。

Windows 上命令找不到？

确认 PATH 已包含安装目录，并重新打开终端窗口。具体步骤见 docs/INSTALL.md。

为什么切换路线或回滚会提示未保存更改？

切换路线/回滚会覆盖当前工作区。如果存在未保存更改，需要确认是否丢弃。建议先执行 gitsave save。

回滚后为什么看不到原路线的后续提交？

回滚会在目标提交上创建并切换到新路线，原路线的提交仍然存在，不会被删除。你需要切回原路线才能看到它们。

游戏失败导致存档变坏，想直接丢弃当前更改怎么做？

在 TUI 的 History 中选择上一条正常存档，按 Enter 回滚并输入新路线名，确认提示会说明“未保存更改将被丢弃”。这是针对坏结局/误操作后的推荐恢复方式。

TUI 在 Windows 上卡顿

Windows 终端渲染性能有限，建议使用 Windows Terminal。TUI 已降低重绘频率以减轻卡顿，但大型存档操作仍可能短暂停顿。

自动保存为什么没有生效？

自动保存功能暂不实现，当前仅保留配置入口与状态展示。

gitsave.toml 为什么在 .git 内？

为了配合回滚设计，配置文件存储在 .git 内部，避免回滚时被误删或被忽略。