跟踪数据库和文件

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

忽略 Worktree 路径

Graft 默认读取 repository 根目录及各级子目录中的 .gitignore。规则遵循 Git 的匹配语法和优先级，包括 ! 否定、/ 锚定、仅目录规则、**、?、字符类、 注释和转义。与 Git 一致，如果父目录已被排除，就不能重新包含其中的文件。

Graft 继续支持 .graftignore，其语法与 .gitignore 相同。同一目录中同时存在 两个文件时，.graftignore 的规则优先；更深目录中的规则优先于父目录规则。

忽略规则只影响 untracked path 的发现和普通 add；已经由 Graft 跟踪的路径仍会 报告并可 stage 其变更。若要显式添加被忽略的 untracked path，请使用 graft add --force path。

查看文件清单

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。