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

# Worktrees and Fresh Clones: Avoiding the Empty-Board Problem

> Why task state does not travel with git, the startup warning Substrate emits, and three options for avoiding an empty board in a worktree or clone.

Substrate is local-first: your workflow lives in the repo, but your task data does not. Understanding that split is essential before you use git worktrees or hand a fresh clone to an agent — if you don't, the agent operates on an empty board and silently invents its own work.

## The Failure Mode

`.substrate/boards/*.json` — your workflow — is committed to git and travels with every checkout.

`.substrate/data.sqlite` — your tasks, comments, and event log — is **gitignored** and does not.

A git worktree or fresh clone checks out the board files but not the database. libsql creates a fresh, empty database on open. An agent working in that checkout silently operates on its own empty board rather than the one in your main checkout.

<Warning>
  This is the sharpest footgun in Substrate today. Nothing errors — the agent simply sees no tasks and starts adding its own.
</Warning>

## The Warning Substrate Emits

Substrate detects this specific shape — a `.substrate/` directory that has board files but whose `data.sqlite` did not exist and was just created — and warns loudly on startup:

> This `.substrate/` has boards but no task database — a fresh EMPTY one was just created at … If this is a git worktree or fresh clone, its task state is NOT shared with your main checkout.

A genuine first `substrate init` has no committed boards yet, so it does not trip the check.

## What to Do

<Steps>
  <Step title="Stick to one checkout per project">
    The simplest answer, and the recommended approach for v0.7.0. Drive Substrate from the main checkout and let worktrees be for code only.
  </Step>

  <Step title="Or point the process at the main checkout">
    `substrate mcp` and `substrate serve` read the `.substrate/` directory in their **working directory**. Run them with the working directory set to the main checkout and every agent shares one board, regardless of which worktree the code edits happen in.
  </Step>

  <Step title="Or move state deliberately">
    If you need to migrate task state between checkouts, export from the source and import into the target:

    ```sh theme={null}
    substrate export /tmp/substrate.tar.gz   # from the source checkout
    substrate import /tmp/substrate.tar.gz   # into the target
    ```

    This is explicit, one-directional, and safe as long as you know which side is authoritative. See [Backup and Restore](/operations/backup-and-restore) for full details.
  </Step>
</Steps>

<Note>
  A shared-database pointer that lets several checkouts address one substrate is planned. It is not available in v0.7.0.
</Note>