Checkpointing 功能

Gemini CLI 提供 Checkpointing 功能，会在 AI 工具修改文件前自动保存项目快照。这样你可以放心尝试代码变更，因为随时都能恢复到工具运行前的状态。

工作原理

当你批准某个会修改文件系统的工具（如 write_file、replace）时，CLI 会自动创建一个 “checkpoint”，其中包含：

1. Git 快照： 在用户主目录的影子 Git 仓库中（~/.gemini/history/<project_hash>）存储一次提交，记录当时项目文件的完整状态，不会影响你自己的项目仓库。
2. 会话历史： 保存截至当前的整段对话记录。
3. 工具调用： 记录即将执行的工具调用详情。

如果想撤销改动或回到之前的状态，可以使用 /restore 命令。恢复 checkpoint 会：

• 将项目文件回滚到快照时刻；
• 恢复 CLI 中的会话历史；
• 重新提出原始工具调用，方便你再次执行、修改或忽略。

所有 checkpoint 数据均保存在本地，包括 Git 快照和会话历史。Git 快照位于影子仓库，会话与工具调用保存在项目临时目录（通常是 ~/.gemini/tmp/<project_hash>/checkpoints）下的 JSON 文件中。

启用方式

Checkpointing 默认关闭，可通过命令行参数或 settings.json 开启。

通过命令行参数

在启动 Gemini CLI 时添加 --checkpointing，即可在当前会话启用：

gemini --checkpointing

通过 settings.json

若希望所有会话默认启用，在 settings.json 中加入：

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

使用 /restore 命令

启用后，checkpoint 会自动创建。可通过 /restore 管理。

列出可用 Checkpoint

查看当前项目所有 checkpoint：

/restore

CLI 会展示 checkpoint 列表。文件名通常包含时间戳、被修改的文件名以及工具名，例如： 2025-06-22T10-00-00_000Z-my-file.txt-write_file。

恢复指定 Checkpoint

使用列表中的文件名称恢复：

/restore <checkpoint_file>

示例：

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

执行后，文件与会话会恢复到创建 checkpoint 时的状态，同时原始工具提示会重新出现，方便进一步操作。