beads/docs/SYNC_SETUP.md

6.4 KiB

Sync Setup Guide

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

Prerequisites

You need two tools installed on every machine:

Tool Minimum Version Install
bd (beads CLI) 0.59.0+ See INSTALLING.md
Dolt 1.81.8+ brew install dolt or dolt install script

Verify both are installed:

bd version     # must be 0.59.0+
dolt version   # must be 1.81.8+

Initial Setup (First Computer)

1. Initialize beads

cd your-project
bd init

This creates the .beads/ directory with a Dolt database and starts a background dolt sql-server.

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. Add a Dolt remote

Point beads at your Git remote for sync. Dolt stores data under refs/dolt/data, separate from your normal Git refs — so you can use the same remote as your source code.

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

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

# Other options: DoltHub, S3, GCS, local path
# See DOLT-BACKEND.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

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 vc log     # should show commit 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.

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

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!