将编辑历史导出到 Git

VMark 为每个文档保存编辑历史：每次保存，以及 AI 客户端通过 MCP 做出的每次编辑，都会连同编辑者一起记录下来。文件 → 文档历史 → 将编辑历史导出到 Git… 会把这份历史复制到一个 Git 仓库中，你可以用 git log 浏览、比较差异，或与项目一起保存。

如何导出

1. 打开要导出历史的文档。
2. 选择 文件 → 文档历史 → 将编辑历史导出到 Git…（也可以在命令面板中运行 将编辑历史导出到 Git）。
3. 选择 Git 仓库中的一个文件夹。选择器会在文档所在的文件夹中打开。

VMark 会告诉你新增了多少个提交，或者分支已是最新。

分支里有什么

历史会写入专用分支 vmark-journal/<document-uuid>。VMark 不会触碰你的工作区、索引、HEAD 或任何其他分支，也不会切换分支。该分支只包含一个文件，以文档命名。

• 每个修订一个提交。 作者是做出编辑的一方（你或 AI 客户端），日期是编辑发生的时间。
• 每段被清理的历史一个汇总提交。 VMark 会清理旧修订，让历史保持精简。一段连续被清理的修订会合并为一个名为 Collected history 的提交，并列出这段时间内的所有编辑者。

每条提交信息的末尾都带有把它与 VMark 关联起来的尾注（trailer）：

尾注	含义
VMark-Document	文档的标识，在每个提交中都相同
VMark-Revision	此提交记录的修订
VMark-Parent	前一个修订
VMark-Actor	做出编辑的一方
VMark-Kind	记录方式：controlled（通过 VMark 的 AI 编辑）、observed（一次保存）、gap（在 VMark 之外的更改）等
VMark-Tool	AI 编辑所用的 MCP 工具
VMark-Session、VMark-Client	AI 客户端提供的会话标签和名称
VMark-Collected	汇总提交中：它涵盖的被清理修订范围
VMark-Actors	汇总提交中：该范围内的所有编辑者，已排序

再次导出

可以随时反复导出。再次导出只会追加上次之后的修订；没有新内容时不做任何改变。同样的历史总是生成同样的提交。

如果分支已不是 VMark 留下的样子，VMark 会拒绝导出，而不是覆盖：

• 自上次导出以来分支被更改过（有人在上面提交、回退或改写了它）。请移动或删除该分支，然后重新导出。
• 已存在同名分支，但它不是 VMark 对此文档的导出。
• 该分支已被检出（在某个工作树中）。

要求与限制

• 必须安装 Git。VMark 会在登录 shell 的 PATH 中查找 Git；找不到时，导出会明确提示。
• 只导出已保存的历史。尚未保存的编辑不包括在内。
• VMark 使用 Git 的底层命令创建提交，因此不会运行提交钩子。监视分支更新的钩子会运行。
• 历史很大时需要一些时间：每个提交都要运行几个 Git 进程。
• 在浅克隆（shallow clone）中，VMark 只会继续它自己在这台电脑上导出的分支。
• 导出期间不要检出导出分支。在最后一次工作树检查之后检出，可能导致该工作树的索引和文件与已移动的分支不一致。