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:

Inspect the container and capture its image, environment variables, port mappings, and network settings
Prompt you to select which Docker volume contains your database data
Stop the container
Bridge the data from the Docker volume to ~/.graft/my-postgres/branches/main/
Recreate the container with a bind mount pointing at the branch directory
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.

Overview

CLI Reference

Configuration

Guides

Quickstart

Quickstart

Prerequisites

Initialize Graft

Capture a Save Point

Create a Branch

Verify Integrity

List Branches

Switch Back

​Quickstart

​Prerequisites

​Initialize Graft

​Capture a Save Point

​Create a Branch

​Verify Integrity

​List Branches

​Switch Back

Quickstart

Prerequisites

Initialize Graft

Capture a Save Point

Create a Branch

Verify Integrity

List Branches

Switch Back