Gemini CLI 的 Checkpointing 功能在每次 AI 工具修改文件前自动创建快照：把项目文件状态存入 shadow Git 仓库、保存对话历史和工具调用记录。一旦出现问题，用 /restore 命令立即回到"改动前"的状态，可选择性恢复文件、对话或两者。本页介绍启用方法和使用流程。

Checkpointing 检查点

Checkpointing 是 Gemini CLI 的安全网功能：在 AI 修改任何文件之前，自动保存一个完整的项目快照，让你可以随时无损地回滚。

工作原理

当你批准一个会修改文件系统的工具调用（如 write_file、replace）时，CLI 自动创建检查点，包含三部分：

1. Git 快照：在 ~/.gemini/history/<项目哈希> 的 shadow Git 仓库中创建提交，记录此刻项目文件的完整状态。这个仓库与你自己的 Git 仓库完全独立，不会影响你的提交历史。
2. 对话历史：截至此刻你与 AI 的完整对话记录。
3. 工具调用记录：即将执行的那次工具调用的详细信息。

所有检查点数据存储在本地，路径通常为 ~/.gemini/tmp/<项目哈希>/checkpoints。

启用检查点功能

Checkpointing 默认关闭，在 settings.json 中启用：

{
  "general": {
    "checkpointing": {
      "enabled": true
    }
  }
}

注意：从 0.11.0 版本起，--checkpointing 命令行标志已移除，只能通过 settings.json 配置。

设置生效后，下次启动 Gemini CLI 即开始自动创建检查点。

使用 /restore 命令

查看可用检查点

/restore

显示当前项目所有已保存的检查点列表。文件名格式通常是：时间戳-文件名-工具名，例如 2025-06-22T10-00-00_000Z-my-file.txt-write_file。

恢复到特定检查点

/restore 2025-06-22T10-00-00_000Z-my-file.txt-write_file

执行后：

• 项目文件立即恢复到快照时的状态
• 对话历史回滚到对应时间点
• 原始工具调用提案重新出现，你可以选择重新执行、修改或忽略

典型使用场景

场景	操作
AI 重构后发现方向不对	/restore → 选择重构前的检查点
想对比不同实现方案	恢复检查点 → 用不同 Prompt 重新实现
意外确认了错误的改动	立即 /restore → 精确恢复
调试 AI 工具链问题	查看检查点中的工具调用记录

与 Rewind 的区别

功能	Rewind	Checkpointing
触发方式	手动 /rewind 或双击 Esc	自动（每次文件修改前）
存储位置	会话内存	磁盘（持久化）
跨会话恢复	不支持	支持
精度	按对话轮次	按工具调用（精确到每次文件操作）

下一步

• 了解 Rewind 即时回滚功能：会话管理教程
• 配置检查点目录等参数：settings.json 参考

常见问题

Q: Checkpointing 会占用多少磁盘空间？

A: Shadow Git 仓库只存储增量 diff，不是文件全量副本，通常比你想象的小得多。但对于大型代码库的频繁操作，~/.gemini/history/ 可能会增长。可以手动删除 shadow 仓库目录清理空间，下次操作时会重新初始化。

Q: Shadow Git 仓库会包含我的代码内容吗？

A: 会，快照中包含你项目文件的完整内容，存储在你本地的 ~/.gemini/history/ 目录下。这些数据不会被发送到任何外部服务。

Q: Checkpointing 和 .gitignore 有关系吗？

A: Checkpointing 的 shadow 仓库独立于你的项目 Git 仓库，它会备份 Gemini CLI 能访问的所有文件（包括被 .gitignore 忽略的文件）。如果你不想让某些文件被备份，可以用 .geminiignore 将其排除。