Skip to content
Graft

App-State Walkthrough

This walkthrough tracks a small app data directory: one SQLite database, one JSON config file, and one attachment. It shows the everyday shape Graft is designed for. You can rehearse the same concepts in the browser Playground before running the local commands below.

Create App State

Section titled “Create App State”
Terminal window
mkdir graft-walkthrough
cd graft-walkthrough
graft init


graft sql --db data.sqlite "CREATE TABLE docs(id TEXT PRIMARY KEY, title TEXT, attachment TEXT);"
graft sql --db data.sqlite "INSERT INTO docs VALUES ('doc-1', 'Proposal', 'attachments/proposal.txt');"


mkdir -p attachments
printf 'proposal draft\n' > attachments/proposal.txt
printf '{ "theme": "light" }\n' > settings.json

Stage and commit everything:

Terminal window
graft status --json
graft add --all
graft commit -m "seed app state"

That commit records one coherent state:

data.sqlite
settings.json
attachments/proposal.txt

Make A Branch

Section titled “Make A Branch”
Terminal window
graft switch -c rewrite-title
graft sql --db data.sqlite "UPDATE docs SET title = 'Updated Proposal' WHERE id = 'doc-1';"
printf 'proposal draft v2\n' > attachments/proposal.txt
graft diff --rows HEAD data.sqlite
graft add --all
graft commit -m "rewrite proposal"

Switch back:

Terminal window
graft switch main
graft sql --db data.sqlite "SELECT id, title, attachment FROM docs;"
cat attachments/proposal.txt

Graft materializes the branch’s committed SQLite snapshots and files into the worktree as you switch.

Merge The Branch

Section titled “Merge The Branch”
Terminal window
graft merge rewrite-title
graft status

If the changes are compatible, Graft can stage the merge result. If not, inspect conflicts:

Terminal window
graft conflicts --json
graft resolve --theirs data.sqlite
graft merge --continue -m "merge rewrite"

SQLite conflicts can include row-level analysis. File artifacts use conservative file-level resolution.

Sync Through A Local Remote

Section titled “Sync Through A Local Remote”

Use a filesystem remote for a local smoke test:

Terminal window
mkdir -p /tmp/graft-remote
graft remote add origin fs:///tmp/graft-remote
graft push origin main

Clone elsewhere:

Terminal window
mkdir ../graft-clone
cd ../graft-clone
graft clone fs:///tmp/graft-remote main
graft sql --db data.sqlite "SELECT id, title FROM docs;"

You now have the same app-state history in another worktree.

Next

Section titled “Next”