gastownhall__beads/docs/getting-started/sync-setup.md

title, description

title	description
Sync Setup Guide	Set up Dolt sync so issue data follows you across machines: remotes, bootstrapping a clone, and day-to-day push and pull

Set up beads with Dolt sync so your issues follow you across computers.

Prerequisites

You need two tools installed on every machine:

Tool	Version	Install
bd (beads CLI)	0.59.0+	See Installation
Dolt	A specific pinned version, not "latest"	See Which Dolt version to install

Verify both are installed:

bd version     # must be 0.59.0+
dolt version   # must match the pinned version

Install a specific Dolt version rather than releases/latest. On Dolt 2.3.x a few percent of freshly created databases come up with CALL DOLT_RESET('--hard') broken for the life of the server process, which breaks bd flatten, bd admin compact and the rollback behind bd dolt pull; separately, the upstream latest URL can resolve to a lower version than one released days earlier. Which Dolt version to install has the measurements, the install command, and how to check a database you already have.

Initial Setup (First Computer)

1. Initialize beads

cd your-project
bd init

This creates the .beads/ directory with a Dolt database. If the git repo has an origin remote, bd init also configures a Dolt remote named origin pointing at that same git URL. Dolt stores issue data under refs/dolt/data, separate from normal source branches.

2. Create some issues

bd create "Set up CI pipeline" -p 1 -t task
bd create "Add authentication" -p 2 -t feature
bd list

3. Verify or add a Dolt remote

In a normal git repo with origin, this should already be configured:

bd dolt remote list
# Expected: origin  <your git origin URL>

If the repo had no origin during init, point beads at your Git remote for sync:

# GitHub (SSH — recommended)
bd dolt remote add origin git+ssh://git@github.com/org/repo.git

# GitHub (HTTPS)
bd dolt remote add origin git+https://github.com/org/repo.git

# Other options: DoltHub, S3, GCS, local path
# See DOLT.md for all remote types

4. Push your issues

bd dolt push

Verify the push worked:

git ls-remote origin | grep dolt
# Expected: <hash>  refs/dolt/data

Existing Projects Without a Dolt Remote

Projects initialized by older versions of bd init may have a local embedded Dolt database and a committed .beads/issues.jsonl, but no Dolt remote. Fix that from the machine whose local database is authoritative:

bd dolt remote list
bd export -o .beads/issues.pre-remote.jsonl   # optional issue audit export
bd dolt remote add origin git+ssh://git@github.com/org/repo.git
bd dolt push

bd dolt remote add origin ... writes sync.remote to .beads/config.yaml. Commit and push that config file with your normal git workflow. Other clones can then run bd bootstrap if their database is missing/stale, or bd dolt pull when they already have the right database.

Cloning to a New Computer

When you clone a repo that already has beads data on the remote, a standard git clone does not fetch refs/dolt/data. You need to bootstrap the Dolt database.

Quick path: bd bootstrap

On recent versions of bd, bd bootstrap handles everything automatically:

git clone git@github.com:org/repo.git
cd repo

bd bootstrap

bd bootstrap auto-detects refs/dolt/data on origin, clones the Dolt database, and configures the remote. Verify with:

bd list       # should show your issues
bd history    # should show recent issue history

If bd bootstrap succeeds, you're done — skip to Day-to-day Sync.

Manual path (if bootstrap fails)

If bd bootstrap doesn't work (older bd versions, unusual remote configs), follow these steps:

Step 1: Confirm the remote has beads data

git ls-remote origin | grep dolt
# Expected: <hash>  refs/dolt/data
# If missing, the remote has no beads data — use bd init normally.

Step 2: Initialize beads

bd init

This creates .beads/ with an empty database. Ignore any warnings about bd bootstrap — we'll replace the empty database manually.

Step 3: Stop the Dolt server

bd dolt stop

Step 4: Find your database name and remove the empty database

# Check your database name
cat .beads/metadata.json    # look for "dolt_database"

The dolt_database field is your <dbname> (typically the repo name).

# Remove the empty database
rm -rf .beads/dolt/<dbname>/

Step 5: Clone the Dolt data from the remote

cd .beads/dolt
dolt clone git@github.com:org/repo.git <dbname>
cd ../..

Step 6: Start the server and migrate

bd dolt start
bd migrate --yes

Step 7: Ensure the remote is registered

bd dolt remote add origin git+ssh://git@github.com/org/repo.git

If you see "remote already exists", that's fine — dolt clone already set it up.

Step 8: Verify

bd dolt remote list   # should show origin
bd list               # should show your issues

Day-to-day Sync

Once set up on both machines, sync is two commands:

# Push your changes to the remote
bd dolt push

# Pull changes from the remote
bd dolt pull

Typical workflow

Machine A                          Machine B
─────────                          ─────────
bd create "New task" -p 1
bd dolt push
                                   bd dolt pull
                                   bd update bd-a1b2 --claim
                                   bd close bd-a1b2 --reason "Done"
                                   bd dolt push
bd dolt pull
bd list                            # sees the closed task

Important rules

• Always use bd dolt ... commands — never run raw dolt CLI commands while the Dolt server is running. It causes journal corruption.
• Commit before pulling — if you have uncommitted working set changes, bd dolt pull will fail with "cannot merge with uncommitted changes". Run bd dolt commit first.
• Push before switching machines — unpushed changes only exist locally.
• Do not use JSONL as sync — .beads/issues.jsonl is an export for viewers and interchange. It is not the source of truth, not a full database backup, and cannot safely reconcile deletes or pruning.

Troubleshooting

"no common ancestor" on push

A stale refs/dolt/data from a previous database is conflicting. Clear it and retry:

git update-ref -d refs/dolt/data
bd dolt push

"cannot merge with uncommitted changes" on pull

Commit your working set first:

bd dolt commit
bd dolt pull

"no store available" on push or commit

This was a bug in bd < 0.59.0. Upgrade bd:

brew upgrade beads
# or re-run the install script

bd list shows nothing after clone

The Dolt database wasn't bootstrapped. Either run bd bootstrap or follow the manual path above.

Stale lock files after crash

bd doctor --fix --yes

WARNING: Do NOT manually remove files inside .dolt/ directories (including noms/LOCK). These are Dolt-internal files and removing them will cause unrecoverable data corruption. Dolt manages these files itself.

"fatal: Unable to read current working directory"

The Dolt server's working directory no longer exists (common after branch switches). Restart it:

bd dolt stop
bd dolt start

See Also

• Sync Concepts — The conceptual model behind this setup (why Dolt is the source of truth, what JSONL is for)
• Quick Start — Getting started with beads
• Dolt Backend for Beads — Dolt backend details, server modes, federation, remote types, and sync modes
• Installation — Installation for all platforms

Attribution

This guide was inspired by @leonletto's community setup guide at leonletto.github.io/thrum, which documented the end-to-end setup and sync process including the manual bootstrap workflow. Thanks for contributing to the beads community!