检查点功能

Gemini CLI 包含检查点(Checkpointing)功能，能够在 AI 工具对文件进行修改前自动保存项目状态的快照。这使您可以安全地尝试和应用代码变更，因为您知道随时可以回滚到工具运行前的状态。

工作原理

当您批准一个会修改文件系统的工具（如 write_file 或 replace）时，CLI 会自动创建一个"检查点"。该检查点包含：

1. Git 快照：在位于您主目录的特殊影子 Git 仓库（~/.gemini/history/<project_hash>）中创建一个提交。此快照捕获了项目文件在该时刻的完整状态。它不会干扰您自己项目的 Git 仓库。
2. 对话历史：保存您与代理(agent)的整个对话记录。
3. 工具调用：存储即将执行的特定工具调用。

如果您想撤销变更或简单地回退，可以使用 /restore 命令。恢复检查点将：

• 将项目中的所有文件还原到快照捕获的状态。
• 恢复 CLI 中的对话历史。
• 重新提出原始工具调用，允许您再次运行、修改或忽略它。

所有检查点数据，包括 Git 快照和对话历史，都存储在您的本地机器上。Git 快照存储在影子仓库中，而对话历史和工具调用则保存在项目临时目录的 JSON 文件中，通常位于 ~/.gemini/tmp/<project_hash>/checkpoints。

启用功能

检查点功能默认是禁用的。要启用它，您可以使用命令行标志或编辑 settings.json 文件。

使用命令行标志

您可以在启动 Gemini CLI 时使用 --checkpointing 标志为当前会话启用检查点功能：

gemini --checkpointing

使用 settings.json 文件

要为所有会话默认启用检查点功能，需要编辑您的 settings.json 文件。

在 settings.json 中添加以下键值：

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

使用 /restore 命令

启用后，检查点会自动创建。要管理这些检查点，您需要使用 /restore 命令。

列出可用检查点

要查看当前项目所有已保存的检查点列表，只需运行：

/restore

CLI 将显示可用检查点文件的列表。这些文件名通常由时间戳、被修改的文件名以及即将运行的工具名称组成（例如 2025-06-22T10-00-00_000Z-my-file.txt-write_file）。

恢复特定检查点

要将项目恢复到特定检查点状态，使用列表中的检查点文件：

/restore <checkpoint_file>

例如：

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

运行该命令后，您的文件和会话将立即恢复到创建检查点时的状态，原始工具提示将重新出现。