Skip to main content

​
graft checkout

Create a new data branch or switch to an existing one. The container is recreated with a bind mount pointing at the branch directory.

​
Usage

graft checkout <branch> [flags]

​
Behavior

​
New Branch

  1. Resolve parent branch’s tip commit
  2. Load tree entries from the DAG
  3. Materialize files from the object pool into the new branch directory
  4. Set new branch ref to parent’s tip
  5. Recreate container with bind mount

​
Existing Branch

  1. Resolve branch’s tip commit
  2. Load tree entries
  3. Diff current branch against target tree
  4. Only touch files that differ (start with unchanged files skipped)
  5. Prune empty directories
  6. Recreate container with bind mount

​
Flags

FlagAliasDefaultDescription
--bindfalseFlip container to bind mount mode on checkout

​
Examples

​
Create a New Branch

graft checkout experiment

Seeding experiment from a1b2c3d (147 file(s))...
Switching to branch: experiment
Container recreated with bind mount (--bind mode).

​
Switch to Existing Branch

graft checkout main

Materializing 147 file(s) from a1b2c3d into ~/.graft/postgres/branches/main...
Switching to branch: main
Container recreated with bind mount (--bind mode).

​
Materialization

Checkout uses diff-based materialization. Graft walks the current branch directory, hashes every file, and compares the result against the target tree. Only files that are:
  • Added — Copied from the object pool
  • Removed — Deleted from the branch directory
  • Changed — Replaced with the correct blob from the object pool
  • Unchanged — Left in place
This makes checkout fast even for large databases where only a few files differ between branches.

​
Exit Codes

CodeMeaning
0Checkout successful
1Error (branch not found, no commits, container issue)