> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ellomas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with Graft in 5 minutes.

# 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

```bash theme={null}
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

```text theme={null}
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

```bash theme={null}
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:

```text theme={null}
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

```bash theme={null}
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:

```text theme={null}
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

```bash theme={null}
graft verify experiment
```

```text theme={null}
✓ Integrity OK (147 files, root f0e1d2)
```

## List Branches

```bash theme={null}
graft list
```

```text theme={null}
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

```bash theme={null}
graft checkout main
```

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