docs/dev-notes/MANUAL_GITHUB_GIT_REMOTE_TEST.md
Validates that a standalone Beads Dolt database can push/pull/clone to a real
GitHub repository using Dolt v1.81.8+ native git remote support. Dolt stores
its data under refs/dolt/data in the git repo, invisible to normal git clone.
Dolt version required: 1.81.8+ Estimated time: 15-20 minutes
dolt version shows >= 1.81.8ssh -T [email protected] succeeds)beads-dolt-test)bd CLI built and available on PATHgit CLI availableSet these before starting. All commands below reference them:
GITHUB_REPO="[email protected]:<you>/beads-dolt-test.git"
WORKDIR=$(mktemp -d -t beads-git-remote-test)
echo "Working in: $WORKDIR"
mkdir -p "$WORKDIR/town-a" && cd "$WORKDIR/town-a"
git init && git commit --allow-empty -m "init"
bd init --backend dolt
Expected: .beads/dolt/ directory created, bd list returns empty.
bd init --backend dolt succeeds.beads/dolt/ directory existsbd list runs without errorbd create "Test issue alpha" -p 1
bd create "Test issue beta" -p 2 -t bug
bd create "Test issue gamma" -p 3
Expected: Three issues created.
bd list shows 3 issues with correct priorities/typescd .beads/dolt
dolt remote add origin "$GITHUB_REPO"
dolt remote -v
Expected: Remote origin listed pointing to the GitHub repo URL.
dolt remote -v shows origin with correct URLcd "$WORKDIR/town-a/.beads/dolt"
dolt push -u origin main
Expected: Push succeeds. Dolt data is stored under refs/dolt/data in the
GitHub repo.
dolt push exits 0 with no errorsgit ls-remote "$GITHUB_REPO" 'refs/dolt/*'
Expected: At least one ref matching refs/dolt/data (or similar Dolt refs).
git ls-remote shows refs/dolt/* referencesmkdir -p "$WORKDIR/town-b" && cd "$WORKDIR/town-b"
dolt clone "$GITHUB_REPO" beads-clone
cd beads-clone
Expected: Dolt database cloned successfully.
dolt clone exits 0dolt log shows commit historydolt sql -q "SHOW TABLES;"
dolt sql -q "SELECT id, title, priority, type FROM issues ORDER BY priority;"
Expected: issues table present. All three test issues visible with
correct field values.
SHOW TABLES includes issuesdolt sql -q "SHOW TABLES;"
Check that ALL tables from the original database are present (issues, labels, dependencies, comments, events, metadata, etc.).
cd "$WORKDIR/town-a"
bd create "Incremental issue delta" -p 1
cd .beads/dolt
dolt add .
dolt commit -m "Add delta issue"
dolt push origin main
Expected: Incremental push succeeds (not a full re-upload).
dolt push exits 0cd "$WORKDIR/town-b/beads-clone"
dolt pull origin main
Expected: Pull succeeds, new issue appears.
dolt pull exits 0dolt sql -q "SELECT title FROM issues WHERE title LIKE '%delta%';" returns the new issuecd "$WORKDIR"
git clone "$GITHUB_REPO" git-only-clone
cd git-only-clone
Expected: Normal git clone succeeds but does NOT contain Dolt database
data. The refs/dolt/data refs are not fetched by default git clone.
git log --oneline # Should show git commits (if any), not Dolt data
git show-ref | grep dolt # Should return nothing or empty
ls # Should NOT contain Dolt database files
git clone succeedsrefs/dolt/* in local refs (git show-ref | grep dolt is empty)cd "$WORKDIR"
git clone "$GITHUB_REPO" cleanup-clone
cd cleanup-clone
git push origin :refs/dolt/data
Or delete all dolt refs:
git ls-remote origin 'refs/dolt/*' | awk '{print $2}' | while read ref; do
git push origin ":$ref"
done
Expected: Dolt refs removed from GitHub.
git ls-remote "$GITHUB_REPO" 'refs/dolt/*' returns emptyDelete the GitHub repo via the web UI or:
gh repo delete <you>/beads-dolt-test --yes
rm -rf "$WORKDIR"
Create a GitHub repo with a README, then try the push flow. Verify Dolt data coexists with normal git content.
git clone still gets only the git content (README)Repeat Phase 1.3-1.4 with HTTPS URL and a GitHub token:
GITHUB_REPO_HTTPS="https://github.com/<you>/beads-dolt-test.git"
dolt remote add origin-https "$GITHUB_REPO_HTTPS"
DOLT_REMOTE_PASSWORD="<github-pat>" dolt push --user "<you>" origin-https main
Create 100+ issues, push, clone, and verify all data arrives intact:
for i in $(seq 1 100); do bd create "Bulk issue $i" -p $((i % 4 + 1)); done
bd create 'Issue with "quotes" and <brackets> & ampersands'
bd create "Issue with unicode: emoji 🐛 and CJK 你好"
Push, clone, verify data integrity.
| # | Test | Result |
|---|---|---|
| 1.1 | Init Dolt backend | |
| 1.2 | Create test data | |
| 1.3 | Add GitHub remote | |
| 1.4 | Push to GitHub | |
| 1.5 | Verify refs on GitHub | |
| 2.1 | Dolt clone from GitHub | |
| 2.2 | Data integrity check | |
| 2.3 | All tables round-trip | |
| 3.1 | Incremental push | |
| 3.2 | Pull new data | |
| 4.1 | Git clone isolation | |
| 5.1 | Cleanup Dolt refs | |
| 6.1 | Non-empty repo (optional) | |
| 6.2 | HTTPS auth (optional) | |
| 6.3 | Large dataset (optional) | |
| 6.4 | Special characters (optional) |
Minimum passing criteria: All Phase 1-5 tests pass.
dolt push fails with authentication errorssh -T [email protected]DOLT_REMOTE_PASSWORD env var with a GitHub PATdolt push fails with "object not found" or similardolt gc before pushingdolt status for uncommitted changesdolt clone failsgit ls-remote "$GITHUB_REPO" 'refs/dolt/*'--ref flag: dolt clone --ref refs/dolt/data "$GITHUB_REPO" destgit push :refs/dolt/data failsgit push origin --delete refs/dolt/data