跟踪数据库和文件

Graft repository 以 worktree 为边界。一次 commit 可以同时包含多个 SQLite 数据库路径和普通应用文件。

project/
  data.sqlite
  analytics.sqlite
  settings.json
  attachments/report.pdf
  .graft/

Path Kind

Kind	含义
sqlite_database	通过 Graft 跟踪的 SQLite snapshot。
text_file	UTF-8 文本文件。
binary_file	二进制文件。

支持 --kind 的命令也接受 sqlite、db、text、binary 等别名。

Storage

Storage	用途
sqlite_snapshot	SQLite 数据库路径。
inline	小文本文件，直接存入 object database。
external	二进制文件、配置的 external path、大文本文件。

kind 表示内容类型，storage 表示存储策略。

Stage 和 Commit

graft status
graft add --all
graft commit -m "save app state"

按类型 stage：

graft add --all --kind sqlite_database
graft add --all --kind text_file
graft add --all --kind binary_file

单路径 stage：

graft add data.sqlite
graft add attachments/report.pdf

查看文件清单

graft ls-files --json
graft ls-files --json --details
graft ls-files --json --others

--details 包含 object id、content hash 和 external payload 本地状态。 --others 列出可添加的 untracked paths。

配置文件存储

graft config set files.inline_text_threshold 8 MB
graft config set files.external_paths "assets/**, attachments/**"

附件、导入、导出、生成媒体、模型等资源目录通常适合放入 external_paths。

外部 SQLite 修改

普通 SQLite 文件是默认 worktree 模式。应用照常提交 SQLite transaction，然后 stage 物理路径：

sqlite3 data.sqlite "INSERT INTO notes(body) VALUES ('external edit');"
graft add data.sqlite

graft add 使用 SQLite online backup 捕获一致的 committed state，包括已提交的 WAL frames，因此不需要手动 checkpoint。Graft 把快照与 staged/HEAD 基线按 4 KiB Graft storage chunk 比较，只写入变化的 chunks；这个粒度与物理数据库的 SQLite page size 无关。没有净变化时不会产生新的 storage commit。

需要 live page-storage 的应用仍可显式使用 Graft VFS，但同一个数据库应选择一种 写入路径，不要在普通文件模式和 VFS 模式之间混写。