Skip to main content

​
Quickstart

This guide walks through initializing Graft on a running Postgres container, creating a save point, branching, and verifying integrity.

​
Prerequisites

  • Docker installed and running (Docker Desktop or OrbStack on macOS)
  • rsync available on your PATH
  • A running database container (e.g., Postgres, MySQL)

​
Initialize Graft

graft init my-postgres --bind
Graft will:
  1. Inspect the container and capture its image, environment variables, port mappings, and network settings
  2. Prompt you to select which Docker volume contains your database data
  3. Stop the container
  4. Bridge the data from the Docker volume to ~/.graft/my-postgres/branches/main/
  5. Recreate the container with a bind mount pointing at the branch directory
  6. Start the container
Initialising my-postgres...
Bridging volume graft_postgres_data -> ~/.graft/my-postgres/branches/main...
Recreating my-postgres with bind mount to ~/.graft/my-postgres/branches/main...
Graft initialized. Project root: ~/.graft/my-postgres
Container is now bound to the host directory via a Docker bind mount (--bind mode).
Run 'graft commit -m "initial state"' to capture this as your first save point.

​
Capture a Save Point

graft commit -m "initial data setup"
Graft stops the container, hashes every file in the branch directory with BLAKE3, stores the blobs in the object pool, builds a Merkle tree, and inserts the commit into the SQLite DAG: 
Stopping my-postgres to snapshot data...
Hashing ~/.graft/my-postgres/branches/main...
Storing 147 blob(s) in object pool...
Save point a1b2c3d created on main (tree f0e1d2).

​
Create a Branch

graft checkout experiment
This seeds a new branch experiment from the current branch’s tree. The container is recreated with a bind mount pointing at the new branch directory: 
Seeding experiment from a1b2c3d (147 file(s))...
Switching to branch: experiment
Container recreated with bind mount (--bind mode).
Make changes in your database (create tables, insert data, run migrations).

​
Verify Integrity

graft verify experiment

✓ Integrity OK (147 files, root f0e1d2)

​
List Branches

graft list

Container: my-postgres
Project root: ~/.graft/my-postgres

BRANCH      ACTIVE  SIZE    COMMITS  INTEG   UPDATED
experiment  *       289.2M  0        ⟳      2026-06-04T12:00:00Z
main                289.2M  1        ✓      2026-06-04T11:59:00Z

​
Switch Back

graft checkout main
Your database is back to the state captured in the initial commit, with all experiment changes isolated.