> ## 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.

# graft checkout

> Create or switch to a data branch.

# `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

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

| Flag     | Alias | Default | Description                                   |
| -------- | ----- | ------- | --------------------------------------------- |
| `--bind` |       | `false` | Flip container to bind mount mode on checkout |

## Examples

### Create a New Branch

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

```text theme={null}
Seeding experiment from a1b2c3d (147 file(s))...
Switching to branch: experiment
Container recreated with bind mount (--bind mode).
```

### Switch to Existing Branch

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

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

| Code | Meaning                                               |
| ---- | ----------------------------------------------------- |
| `0`  | Checkout successful                                   |
| `1`  | Error (branch not found, no commits, container issue) |