johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(docs): standardize sync branch name and daemon syntax (GH#376)

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-12-25 16:21:33 -08:00
parent 3034fc392e
commit 47cc84de3a
6 changed files with 56 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/CONFIG.md
View File

@@ -365,7 +365,7 @@ Controls for the sync branch workflow (see docs/PROTECTED_BRANCHES.md):
```bash ```bash
# Configure sync branch (required for protected branch workflow) # 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) # Enable mass deletion protection (optional, default: false)
# When enabled, if >50% of issues vanish during a merge AND more than 5 # When enabled, if >50% of issues vanish during a merge AND more than 5

2
docs/DAEMON.md
View File

@@ -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: **Enable daemon in worktrees:** Configure sync-branch to safely use daemon across all worktrees:
```bash ```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. 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.

14
docs/GIT_INTEGRATION.md
View File

@@ -236,18 +236,18 @@ jj resolve --tool=beads-merge
```bash ```bash
# Initialize with separate sync branch # Initialize with separate sync branch
bd init --branch beads-metadata bd init --branch beads-sync
# Or configure existing setup # Or configure existing setup
bd config set sync.branch beads-metadata bd config set sync.branch beads-sync
``` ```
### How It Works ### 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/` - Uses git worktrees (lightweight checkouts) in `.git/beads-worktrees/`
- Your main working directory is never affected - 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) ### Daily Workflow (Unchanged for Agents)
@@ -258,7 +258,7 @@ bd update bd-a1b2 --status in_progress
bd close bd-a1b2 "Fixed" 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) ### Merging to Main (Humans)
@@ -267,7 +267,7 @@ All changes automatically commit to `beads-metadata` branch (if daemon is runnin
bd sync --status bd sync --status
# Option 1: Create pull request # Option 1: Create pull request
git push origin beads-metadata git push origin beads-sync
# Then create PR on GitHub/GitLab # Then create PR on GitHub/GitLab
# Option 2: Direct merge (if allowed) # 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 │ │ Team Member │─▶│ Shared Repo │
│ (main) │ │ (beads-metadata)│ │ (main) │ │ (beads-sync)│
└──────────────┘ └─────────────────┘ └──────────────┘ └─────────────────┘
``` ```

80
docs/PROTECTED_BRANCHES.md
View File

@@ -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`. **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:** **Benefits:**
- ✅ Works with any git platform's branch protection - ✅ 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 ```bash
cd your-project 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: **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/daemon.lock`, `daemon.log`, `daemon.pid` - Runtime files
- `.beads/beads.left.jsonl`, `beads.right.jsonl` - Temporary merge artifacts - `.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/issues.jsonl` - Issue data in JSONL format (committed automatically by daemon)
- `.beads/metadata.json` - Metadata about the beads installation - `.beads/metadata.json` - Metadata about the beads installation
- `.beads/config.yaml` - Configuration template (optional) - `.beads/config.yaml` - Configuration template (optional)
@@ -72,7 +72,7 @@ The sync branch (beads-metadata) will contain:
bd daemon --start --auto-commit 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:** **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/ your-project/
├── .git/ # Main git directory ├── .git/ # Main git directory
│ └── beads-worktrees/ │ └── beads-worktrees/
│ └── beads-metadata/ # Worktree (only .beads/ checked out) │ └── beads-sync/ # Worktree (only .beads/ checked out)
│ └── .beads/ │ └── .beads/
│ └── issues.jsonl │ └── issues.jsonl
├── .beads/ # Your main copy ├── .beads/ # Your main copy
@@ -115,7 +115,7 @@ Main branch (protected):
- `.beads/.gitignore` - Tells git what to ignore - `.beads/.gitignore` - Tells git what to ignore
- `.gitattributes` - Merge driver configuration - `.gitattributes` - Merge driver configuration
Sync branch (beads-metadata): Sync branch (beads-sync):
- `.beads/issues.jsonl` - Issue data (committed by daemon) - `.beads/issues.jsonl` - Issue data (committed by daemon)
- `.beads/metadata.json` - Repository metadata - `.beads/metadata.json` - Repository metadata
- `.beads/config.yaml` - Configuration template - `.beads/config.yaml` - Configuration template
@@ -137,8 +137,8 @@ When you update an issue:
1. Issue is updated in `.beads/beads.db` (SQLite database) 1. Issue is updated in `.beads/beads.db` (SQLite database)
2. Daemon exports to `.beads/issues.jsonl` (JSONL file) 2. Daemon exports to `.beads/issues.jsonl` (JSONL file)
3. JSONL is copied to worktree (`.git/beads-worktrees/beads-metadata/.beads/`) 3. JSONL is copied to worktree (`.git/beads-worktrees/beads-sync/.beads/`)
4. Daemon commits the change in the worktree to `beads-metadata` branch 4. Daemon commits the change in the worktree to `beads-sync` branch
5. Main branch stays untouched (no commits on `main`) 5. Main branch stays untouched (no commits on `main`)
## Setup ## Setup
@@ -147,12 +147,12 @@ When you update an issue:
```bash ```bash
cd your-project cd your-project
bd init --branch beads-metadata bd init --branch beads-sync
``` ```
This will: This will:
- Create `.beads/` directory with database - 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) - Import any existing issues from git (if present)
- Prompt to install git hooks (recommended: say yes) - 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 ```bash
# Set the sync branch # 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) # Start the daemon (it will create the worktree automatically)
bd daemon --start --auto-commit 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: You can also configure the sync branch via environment variable:
```bash ```bash
export BEADS_SYNC_BRANCH=beads-metadata export BEADS_SYNC_BRANCH=beads-sync
bd daemon --start --auto-commit bd daemon --start --auto-commit
``` ```
@@ -215,7 +215,7 @@ bd update bd-a1b2 --status in_progress
bd close bd-a1b2 "Completed authentication" 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 ### For Humans
@@ -226,7 +226,7 @@ All changes are automatically committed to the `beads-metadata` branch by the da
bd sync --status 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):** **Manual commit (if not using daemon):**
@@ -251,11 +251,11 @@ For protected branches with required reviews:
```bash ```bash
# 1. Push your sync branch # 1. Push your sync branch
git push origin beads-metadata git push origin beads-sync
# 2. Create PR on GitHub/GitLab/etc. # 2. Create PR on GitHub/GitLab/etc.
# - Base: main # - Base: main
# - Compare: beads-metadata # - Compare: beads-sync
# 3. After PR is merged, update your local main # 3. After PR is merged, update your local main
git checkout main git checkout main
@@ -276,7 +276,7 @@ bd sync --merge
# This will: # This will:
# - Switch to main branch # - 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 # - Push to remote
# - Import merged changes to database # - 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":"closed","updated_at":"2025-11-02T10:00:00Z"}
======= =======
{"id":"bd-a1b2","title":"Feature A","status":"in_progress","updated_at":"2025-11-02T09: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`: **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`: This happens if you created the sync branch independently. Merge with `--allow-unrelated-histories`:
```bash ```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. Or use `bd sync --merge` which handles this automatically.
@@ -355,7 +355,7 @@ If the worktree is corrupted or in a bad state:
```bash ```bash
# Remove the worktree # Remove the worktree
rm -rf .git/beads-worktrees/beads-metadata rm -rf .git/beads-worktrees/beads-sync
# Prune stale worktree entries # Prune stale worktree entries
git worktree prune git worktree prune
@@ -364,12 +364,12 @@ git worktree prune
bd daemon --stop && bd daemon --start 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: The sync branch doesn't exist yet. The daemon will create it on the first commit. If you want to create it manually:
```bash ```bash
git checkout -b beads-metadata git checkout -b beads-sync
git checkout main # Switch back git checkout main # Switch back
``` ```
@@ -409,7 +409,7 @@ Ensure all clones are configured the same way:
```bash ```bash
# On each clone, verify: # 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 # Pull latest changes
bd sync --no-push bd sync --no-push
@@ -462,10 +462,10 @@ Yes! Each collaborator configures their own sync branch:
```bash ```bash
# All collaborators use the same branch # 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? ### How often should I merge to main?
@@ -483,7 +483,7 @@ Yes! Use `bd sync --status` to see what's changed:
```bash ```bash
bd sync --status 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. 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 bd daemon --stop
# Remove worktree # Remove worktree
git worktree remove .git/beads-worktrees/beads-metadata git worktree remove .git/beads-worktrees/beads-sync
# Unset sync branch # Unset sync branch
bd config set sync.branch "" bd config set sync.branch ""
@@ -566,7 +566,7 @@ jobs:
- name: Pull changes - name: Pull changes
run: | run: |
git fetch origin beads-metadata git fetch origin beads-sync
bd sync --no-push bd sync --no-push
- name: Merge to main (if changes) - name: Merge to main (if changes)
@@ -591,8 +591,8 @@ Protected branch settings:
Create sync branch PR: Create sync branch PR:
```bash ```bash
git push origin beads-metadata git push origin beads-sync
gh pr create --base main --head beads-metadata --title "Update beads metadata" gh pr create --base main --head beads-sync --title "Update beads metadata"
``` ```
### GitLab ### GitLab
@@ -605,8 +605,8 @@ Protected branch settings:
Create sync branch MR: Create sync branch MR:
```bash ```bash
git push origin beads-metadata git push origin beads-sync
glab mr create --source-branch beads-metadata --target-branch main glab mr create --source-branch beads-sync --target-branch main
``` ```
### Bitbucket ### Bitbucket
@@ -618,7 +618,7 @@ Protected branch settings:
Create sync branch PR: Create sync branch PR:
```bash ```bash
git push origin beads-metadata git push origin beads-sync
# Create PR via Bitbucket web UI # Create PR via Bitbucket web UI
``` ```
@@ -649,9 +649,9 @@ git remote add upstream https://github.com/original/repo.git
# Fetch upstream changes # Fetch upstream changes
git fetch upstream git fetch upstream
# Merge upstream beads-metadata to yours # Merge upstream beads-sync to yours
git checkout beads-metadata git checkout beads-sync
git merge upstream/beads-metadata git merge upstream/beads-sync
bd import # Import merged changes bd import # Import merged changes
``` ```
@@ -667,7 +667,7 @@ If you have an existing beads setup committing to `main`:
1. **Set sync branch:** 1. **Set sync branch:**
```bash ```bash
bd config set sync.branch beads-metadata bd config set sync.branch beads-sync
``` ```
2. **Restart daemon:** 2. **Restart daemon:**
@@ -677,10 +677,10 @@ If you have an existing beads setup committing to `main`:
3. **Verify:** 3. **Verify:**
```bash ```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 ### From Sync Branch to Direct Commits

2
docs/QUICKSTART.md
View File

@@ -25,7 +25,7 @@ bd init --contributor
bd init --team bd init --team
# Protected main branch (GitHub/GitLab) # Protected main branch (GitHub/GitLab)
bd init --branch beads-metadata bd init --branch beads-sync
``` ```
The wizard will: The wizard will:

12
docs/WORKTREES.md
View File

@@ -77,7 +77,7 @@ bd config set sync.branch ""
# Stop and restart daemon # Stop and restart daemon
bd daemon stop bd daemon stop
bd daemon start bd daemon --start
# Clean up existing worktrees # Clean up existing worktrees
rm -rf .git/beads-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:** **With sync-branch configured:**
- Daemon is **enabled** in worktrees - 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 - Full daemon functionality available across all worktrees
## Usage Patterns ## Usage Patterns
@@ -147,13 +147,13 @@ bd automatically detects when you're in a git worktree and handles daemon mode s
```bash ```bash
# Configure sync-branch once (in main repo or any worktree) # 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 # Now daemon works safely in all worktrees
cd feature-worktree cd feature-worktree
bd create "Implement feature X" -t feature -p 1 bd create "Implement feature X" -t feature -p 1
bd update bd-a1b2 --status in_progress 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) ### Alternative: Direct Mode (No Configuration Needed)
@@ -295,7 +295,7 @@ bd config set sync.branch ""
**Solution (if still occurring):** **Solution (if still occurring):**
```bash ```bash
# Option 1: Configure sync-branch (recommended) # 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 # Option 2: Explicitly disable daemon
export BEADS_NO_DAEMON=1 export BEADS_NO_DAEMON=1
@@ -357,7 +357,7 @@ export BEADS_DB=/path/to/specific/.beads/beads.db
```bash ```bash
# Configure sync behavior # 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_commit true # Auto-commit changes
bd config set sync.auto_push true # Auto-push changes bd config set sync.auto_push true # Auto-push changes
``` ```