From 47cc84de3abe1240af218b217bbc5be7c8030e89 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Thu, 25 Dec 2025 16:21:33 -0800 Subject: [PATCH] fix(docs): standardize sync branch name and daemon syntax (GH#376) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace beads-metadata with beads-sync throughout docs (matches code default and internal examples) - Fix bd daemon start β†’ bd daemon --start (correct flag syntax) πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/CONFIG.md | 2 +- docs/DAEMON.md | 2 +- docs/GIT_INTEGRATION.md | 14 +++---- docs/PROTECTED_BRANCHES.md | 80 +++++++++++++++++++------------------- docs/QUICKSTART.md | 2 +- docs/WORKTREES.md | 12 +++--- 6 files changed, 56 insertions(+), 56 deletions(-) diff --git a/docs/CONFIG.md b/docs/CONFIG.md index 292143ee..f4204a39 100644 --- a/docs/CONFIG.md +++ b/docs/CONFIG.md @@ -365,7 +365,7 @@ Controls for the sync branch workflow (see docs/PROTECTED_BRANCHES.md): ```bash # Configure sync branch (required for protected branch workflow) -bd config set sync.branch beads-metadata +bd config set sync.branch beads-sync # Enable mass deletion protection (optional, default: false) # When enabled, if >50% of issues vanish during a merge AND more than 5 diff --git a/docs/DAEMON.md b/docs/DAEMON.md index d870056b..932f9142 100644 --- a/docs/DAEMON.md +++ b/docs/DAEMON.md @@ -36,7 +36,7 @@ bd runs a background daemon per workspace for auto-sync, RPC operations, and rea **Enable daemon in worktrees:** Configure sync-branch to safely use daemon across all worktrees: ```bash -bd config set sync-branch beads-metadata +bd config set sync-branch beads-sync ``` With sync-branch configured, daemon commits to a dedicated branch using an internal worktree, so your current branch is never affected. See [WORKTREES.md](WORKTREES.md) for details. diff --git a/docs/GIT_INTEGRATION.md b/docs/GIT_INTEGRATION.md index e23323c9..8224599a 100644 --- a/docs/GIT_INTEGRATION.md +++ b/docs/GIT_INTEGRATION.md @@ -236,18 +236,18 @@ jj resolve --tool=beads-merge ```bash # Initialize with separate sync branch -bd init --branch beads-metadata +bd init --branch beads-sync # Or configure existing setup -bd config set sync.branch beads-metadata +bd config set sync.branch beads-sync ``` ### How It Works -- Beads commits issue updates to `beads-metadata` instead of `main` +- Beads commits issue updates to `beads-sync` instead of `main` - Uses git worktrees (lightweight checkouts) in `.git/beads-worktrees/` - Your main working directory is never affected -- Periodically merge `beads-metadata` back to `main` via pull request +- Periodically merge `beads-sync` back to `main` via pull request ### Daily Workflow (Unchanged for Agents) @@ -258,7 +258,7 @@ bd update bd-a1b2 --status in_progress bd close bd-a1b2 "Fixed" ``` -All changes automatically commit to `beads-metadata` branch (if daemon is running with `--auto-commit`). +All changes automatically commit to `beads-sync` branch (if daemon is running with `--auto-commit`). ### Merging to Main (Humans) @@ -267,7 +267,7 @@ All changes automatically commit to `beads-metadata` branch (if daemon is runnin bd sync --status # Option 1: Create pull request -git push origin beads-metadata +git push origin beads-sync # Then create PR on GitHub/GitLab # Option 2: Direct merge (if allowed) @@ -449,7 +449,7 @@ See [MULTI_REPO_MIGRATION.md](MULTI_REPO_MIGRATION.md) for complete guide. β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Team Member │─▢│ Shared Repo β”‚ -β”‚ (main) β”‚ β”‚ (beads-metadata)β”‚ +β”‚ (main) β”‚ β”‚ (beads-sync)β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` diff --git a/docs/PROTECTED_BRANCHES.md b/docs/PROTECTED_BRANCHES.md index fe240d3b..c31fa9de 100644 --- a/docs/PROTECTED_BRANCHES.md +++ b/docs/PROTECTED_BRANCHES.md @@ -17,7 +17,7 @@ This guide explains how to use beads with protected branches on platforms like G **Problem:** GitHub and other platforms let you protect branches (like `main`) to require pull requests for all changes. This prevents beads from auto-committing issue updates directly to `main`. -**Solution:** Beads can commit to a separate branch (like `beads-metadata`) using git worktrees, while keeping your main working directory untouched. Periodically merge the metadata branch back to `main` via a pull request. +**Solution:** Beads can commit to a separate branch (like `beads-sync`) using git worktrees, while keeping your main working directory untouched. Periodically merge the metadata branch back to `main` via a pull request. **Benefits:** - βœ… Works with any git platform's branch protection @@ -33,10 +33,10 @@ This guide explains how to use beads with protected branches on platforms like G ```bash cd your-project -bd init --branch beads-metadata +bd init --branch beads-sync ``` -This creates a `.beads/` directory and configures beads to commit to `beads-metadata` instead of `main`. +This creates a `.beads/` directory and configures beads to commit to `beads-sync` instead of `main`. **Important:** After initialization, you'll see some untracked files that should be committed to your protected branch: @@ -61,7 +61,7 @@ Files that are automatically gitignored (do NOT commit): - `.beads/daemon.lock`, `daemon.log`, `daemon.pid` - Runtime files - `.beads/beads.left.jsonl`, `beads.right.jsonl` - Temporary merge artifacts -The sync branch (beads-metadata) will contain: +The sync branch (beads-sync) will contain: - `.beads/issues.jsonl` - Issue data in JSONL format (committed automatically by daemon) - `.beads/metadata.json` - Metadata about the beads installation - `.beads/config.yaml` - Configuration template (optional) @@ -72,7 +72,7 @@ The sync branch (beads-metadata) will contain: bd daemon --start --auto-commit ``` -The daemon will automatically commit issue changes to the `beads-metadata` branch. +The daemon will automatically commit issue changes to the `beads-sync` branch. **3. When ready, merge to main:** @@ -98,7 +98,7 @@ Beads uses [git worktrees](https://git-scm.com/docs/git-worktree) to maintain a your-project/ β”œβ”€β”€ .git/ # Main git directory β”‚ └── beads-worktrees/ -β”‚ └── beads-metadata/ # Worktree (only .beads/ checked out) +β”‚ └── beads-sync/ # Worktree (only .beads/ checked out) β”‚ └── .beads/ β”‚ └── issues.jsonl β”œβ”€β”€ .beads/ # Your main copy @@ -115,7 +115,7 @@ Main branch (protected): - `.beads/.gitignore` - Tells git what to ignore - `.gitattributes` - Merge driver configuration -Sync branch (beads-metadata): +Sync branch (beads-sync): - `.beads/issues.jsonl` - Issue data (committed by daemon) - `.beads/metadata.json` - Repository metadata - `.beads/config.yaml` - Configuration template @@ -137,8 +137,8 @@ When you update an issue: 1. Issue is updated in `.beads/beads.db` (SQLite database) 2. Daemon exports to `.beads/issues.jsonl` (JSONL file) -3. JSONL is copied to worktree (`.git/beads-worktrees/beads-metadata/.beads/`) -4. Daemon commits the change in the worktree to `beads-metadata` branch +3. JSONL is copied to worktree (`.git/beads-worktrees/beads-sync/.beads/`) +4. Daemon commits the change in the worktree to `beads-sync` branch 5. Main branch stays untouched (no commits on `main`) ## Setup @@ -147,12 +147,12 @@ When you update an issue: ```bash cd your-project -bd init --branch beads-metadata +bd init --branch beads-sync ``` This will: - Create `.beads/` directory with database -- Set `sync.branch` config to `beads-metadata` +- Set `sync.branch` config to `beads-sync` - Import any existing issues from git (if present) - Prompt to install git hooks (recommended: say yes) @@ -162,7 +162,7 @@ If you already have beads set up and want to switch to a separate branch: ```bash # Set the sync branch -bd config set sync.branch beads-metadata +bd config set sync.branch beads-sync # Start the daemon (it will create the worktree automatically) bd daemon --start --auto-commit @@ -192,7 +192,7 @@ bd daemon --start --auto-commit --auto-push You can also configure the sync branch via environment variable: ```bash -export BEADS_SYNC_BRANCH=beads-metadata +export BEADS_SYNC_BRANCH=beads-sync bd daemon --start --auto-commit ``` @@ -215,7 +215,7 @@ bd update bd-a1b2 --status in_progress bd close bd-a1b2 "Completed authentication" ``` -All changes are automatically committed to the `beads-metadata` branch by the daemon. No changes are needed to agent workflows! +All changes are automatically committed to the `beads-sync` branch by the daemon. No changes are needed to agent workflows! ### For Humans @@ -226,7 +226,7 @@ All changes are automatically committed to the `beads-metadata` branch by the da bd sync --status ``` -This shows the diff between `beads-metadata` and `main` (or your current branch). +This shows the diff between `beads-sync` and `main` (or your current branch). **Manual commit (if not using daemon):** @@ -251,11 +251,11 @@ For protected branches with required reviews: ```bash # 1. Push your sync branch -git push origin beads-metadata +git push origin beads-sync # 2. Create PR on GitHub/GitLab/etc. # - Base: main -# - Compare: beads-metadata +# - Compare: beads-sync # 3. After PR is merged, update your local main git checkout main @@ -276,7 +276,7 @@ bd sync --merge # This will: # - Switch to main branch -# - Merge beads-metadata with --no-ff (creates merge commit) +# - Merge beads-sync with --no-ff (creates merge commit) # - Push to remote # - Import merged changes to database ``` @@ -320,7 +320,7 @@ Example conflict resolution: {"id":"bd-a1b2","title":"Feature A","status":"closed","updated_at":"2025-11-02T10:00:00Z"} ======= {"id":"bd-a1b2","title":"Feature A","status":"in_progress","updated_at":"2025-11-02T09:00:00Z"} ->>>>>>> beads-metadata +>>>>>>> beads-sync ``` **Resolution:** Keep the line with the newer `updated_at`: @@ -344,7 +344,7 @@ bd import # Import to database (will use latest timestamp) This happens if you created the sync branch independently. Merge with `--allow-unrelated-histories`: ```bash -git merge beads-metadata --allow-unrelated-histories --no-ff +git merge beads-sync --allow-unrelated-histories --no-ff ``` Or use `bd sync --merge` which handles this automatically. @@ -355,7 +355,7 @@ If the worktree is corrupted or in a bad state: ```bash # Remove the worktree -rm -rf .git/beads-worktrees/beads-metadata +rm -rf .git/beads-worktrees/beads-sync # Prune stale worktree entries git worktree prune @@ -364,12 +364,12 @@ git worktree prune bd daemon --stop && bd daemon --start ``` -### "branch 'beads-metadata' not found" +### "branch 'beads-sync' not found" The sync branch doesn't exist yet. The daemon will create it on the first commit. If you want to create it manually: ```bash -git checkout -b beads-metadata +git checkout -b beads-sync git checkout main # Switch back ``` @@ -409,7 +409,7 @@ Ensure all clones are configured the same way: ```bash # On each clone, verify: -bd config get sync.branch # Should be the same (e.g., beads-metadata) +bd config get sync.branch # Should be the same (e.g., beads-sync) # Pull latest changes bd sync --no-push @@ -462,10 +462,10 @@ Yes! Each collaborator configures their own sync branch: ```bash # All collaborators use the same branch -bd config set sync.branch beads-metadata +bd config set sync.branch beads-sync ``` -Everyone's changes sync via the `beads-metadata` branch. Periodically merge to `main` via PR. +Everyone's changes sync via the `beads-sync` branch. Periodically merge to `main` via PR. ### How often should I merge to main? @@ -483,7 +483,7 @@ Yes! Use `bd sync --status` to see what's changed: ```bash bd sync --status -# Shows diff between beads-metadata and main +# Shows diff between beads-sync and main ``` Or create a pull request and review on GitHub/GitLab. @@ -504,7 +504,7 @@ Yes, but the daemon will recreate it. If you want to clean up permanently: bd daemon --stop # Remove worktree -git worktree remove .git/beads-worktrees/beads-metadata +git worktree remove .git/beads-worktrees/beads-sync # Unset sync branch bd config set sync.branch "" @@ -566,7 +566,7 @@ jobs: - name: Pull changes run: | - git fetch origin beads-metadata + git fetch origin beads-sync bd sync --no-push - name: Merge to main (if changes) @@ -591,8 +591,8 @@ Protected branch settings: Create sync branch PR: ```bash -git push origin beads-metadata -gh pr create --base main --head beads-metadata --title "Update beads metadata" +git push origin beads-sync +gh pr create --base main --head beads-sync --title "Update beads metadata" ``` ### GitLab @@ -605,8 +605,8 @@ Protected branch settings: Create sync branch MR: ```bash -git push origin beads-metadata -glab mr create --source-branch beads-metadata --target-branch main +git push origin beads-sync +glab mr create --source-branch beads-sync --target-branch main ``` ### Bitbucket @@ -618,7 +618,7 @@ Protected branch settings: Create sync branch PR: ```bash -git push origin beads-metadata +git push origin beads-sync # Create PR via Bitbucket web UI ``` @@ -649,9 +649,9 @@ git remote add upstream https://github.com/original/repo.git # Fetch upstream changes git fetch upstream -# Merge upstream beads-metadata to yours -git checkout beads-metadata -git merge upstream/beads-metadata +# Merge upstream beads-sync to yours +git checkout beads-sync +git merge upstream/beads-sync bd import # Import merged changes ``` @@ -667,7 +667,7 @@ If you have an existing beads setup committing to `main`: 1. **Set sync branch:** ```bash - bd config set sync.branch beads-metadata + bd config set sync.branch beads-sync ``` 2. **Restart daemon:** @@ -677,10 +677,10 @@ If you have an existing beads setup committing to `main`: 3. **Verify:** ```bash - bd config get sync.branch # Should show: beads-metadata + bd config get sync.branch # Should show: beads-sync ``` -Future commits will go to `beads-metadata`. Historical commits on `main` are preserved. +Future commits will go to `beads-sync`. Historical commits on `main` are preserved. ### From Sync Branch to Direct Commits diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 762ba76d..36651fac 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -25,7 +25,7 @@ bd init --contributor bd init --team # Protected main branch (GitHub/GitLab) -bd init --branch beads-metadata +bd init --branch beads-sync ``` The wizard will: diff --git a/docs/WORKTREES.md b/docs/WORKTREES.md index db5b4559..a3c388de 100644 --- a/docs/WORKTREES.md +++ b/docs/WORKTREES.md @@ -77,7 +77,7 @@ bd config set sync.branch "" # Stop and restart daemon bd daemon stop -bd daemon start +bd daemon --start # Clean up existing worktrees rm -rf .git/beads-worktrees @@ -138,7 +138,7 @@ bd automatically detects when you're in a git worktree and handles daemon mode s **With sync-branch configured:** - Daemon is **enabled** in worktrees -- Commits go to dedicated sync branch (e.g., `beads-metadata`) +- Commits go to dedicated sync branch (e.g., `beads-sync`) - Full daemon functionality available across all worktrees ## Usage Patterns @@ -147,13 +147,13 @@ bd automatically detects when you're in a git worktree and handles daemon mode s ```bash # Configure sync-branch once (in main repo or any worktree) -bd config set sync-branch beads-metadata +bd config set sync-branch beads-sync # Now daemon works safely in all worktrees cd feature-worktree bd create "Implement feature X" -t feature -p 1 bd update bd-a1b2 --status in_progress -bd ready # Daemon auto-syncs to beads-metadata branch +bd ready # Daemon auto-syncs to beads-sync branch ``` ### Alternative: Direct Mode (No Configuration Needed) @@ -295,7 +295,7 @@ bd config set sync.branch "" **Solution (if still occurring):** ```bash # Option 1: Configure sync-branch (recommended) -bd config set sync-branch beads-metadata +bd config set sync-branch beads-sync # Option 2: Explicitly disable daemon export BEADS_NO_DAEMON=1 @@ -357,7 +357,7 @@ export BEADS_DB=/path/to/specific/.beads/beads.db ```bash # Configure sync behavior -bd config set sync.branch beads-metadata # Use separate sync branch +bd config set sync.branch beads-sync # Use separate sync branch bd config set sync.auto_commit true # Auto-commit changes bd config set sync.auto_push true # Auto-push changes ```