Overview

Graft turns a directory of SQLite databases into a repository:

project/
  app.db
  analytics.db
  .graft/
    config.toml
    HEAD
    refs/
    objects/
    store/
    index/

The .graft/ directory is the project boundary. It stores repository metadata, immutable objects, refs, remote configuration, and the repo-local Graft storage used by SQLite database snapshots.

Choose An Entry Point

CLI Best for local experiments, demos, and manual verification.

SQLite Extension Best for embedding Graft in applications and language runtimes.

Local Testing Build release artifacts, put `graft` on PATH, and verify diff behavior.

Mental Model

Initialize or clone a repository.
Terminal window
```
graft init
```

Modify SQLite data through the Graft VFS.

graft sql "CREATE TABLE users(id INTEGER PRIMARY KEY, name TEXT);"
graft sql "INSERT INTO users(name) VALUES ('Alice');"

Stage the current database snapshot.
Terminal window
```
graft add app.db
```
Commit the staged snapshot.
Terminal window
```
graft commit -m "seed users"
```
Branch, switch, fetch, pull, push, diff, and restore using repository revisions.
Terminal window
```
graft branch feature/search
graft switch feature/search
graft diff main HEAD app.db
```

SQLite transactions and Graft commits are intentionally separate. A SQLite transaction makes database writes atomic. A Graft commit records a project version.