將編輯歷史匯出到 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 只會繼續它自己在這台電腦上匯出的分支。
• 匯出期間請勿簽出匯出分支。在最後一次工作樹檢查之後簽出，可能導致該工作樹的索引和檔案與已移動的分支不一致。