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

docs: explain sync-branch worktree behavior (GH#510)

Browse Source 
Add comprehensive documentation about beads-created worktrees:
- New section in WORKTREES.md explaining why and where beads creates worktrees
- Common confusion: 'beads took over main!' with solution
- Troubleshooting entries for 'branch already checked out' errors
- FAQ entry: 'Why did beads create worktrees in my .git directory?'

This addresses user confusion when beads' sync-branch feature creates
internal worktrees that can lock branches users want to checkout.

Closes #510

🤖 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-14 17:20:12 -08:00
parent ee8fe2bbb7
commit 344fc1b95d
3 changed files with 205 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/FAQ.md
View File

@@ -426,7 +426,33 @@ bd ready
bd create "Fix bug" -p 1
```
See [ADVANCED.md#git-worktrees](ADVANCED.md#git-worktrees) for details.
See [WORKTREES.md](WORKTREES.md) for details.
### Why did beads create worktrees in my .git directory?
Beads automatically creates git worktrees when using the **sync-branch** feature. This happens when you:
- Run `bd init --branch <name>`
- Set `bd config set sync.branch <name>`
The worktrees allow beads to commit issue updates to a separate branch without switching your working directory.
**Location:** `.git/beads-worktrees/<sync-branch>/`
**Common issue:** If you see "branch already checked out" errors when switching branches, remove the beads worktrees:
```bash
rm -rf .git/beads-worktrees
rm -rf .git/worktrees/beads-*
git worktree prune
```
**To disable sync-branch (stop worktree creation):**
```bash
bd config set sync.branch ""
```
See [WORKTREES.md#beads-created-worktrees-sync-branch](WORKTREES.md#beads-created-worktrees-sync-branch) for full details.
### What's the difference between SQLite corruption and ID collisions?

47
docs/TROUBLESHOOTING.md
View File

@@ -342,7 +342,52 @@ chmod +x .git/hooks/post-merge
chmod +x .git/hooks/post-checkout
```
Or use the installer: `cd examples/git-hooks && ./install.sh`
### "Branch already checked out" when switching branches
**Symptom:**
```bash
$ git checkout main
fatal: 'main' is already checked out at '/path/to/.git/beads-worktrees/beads-sync'
```
**Cause:** Beads creates git worktrees internally when using the sync-branch feature (configured via `bd init --branch` or `bd config set sync.branch`). These worktrees lock the branches they're checked out to.
**Solution:**
```bash
# Remove beads-created worktrees
rm -rf .git/beads-worktrees
rm -rf .git/worktrees/beads-*
git worktree prune
# Now you can checkout the branch
git checkout main
```
**Permanent fix (disable sync-branch):**
```bash
bd config set sync.branch ""
```
See [WORKTREES.md#beads-created-worktrees-sync-branch](WORKTREES.md#beads-created-worktrees-sync-branch) for details.
### Unexpected worktree directories in .git/
**Symptom:** You notice `.git/beads-worktrees/` or `.git/worktrees/beads-*` directories you didn't create.
**Explanation:** Beads automatically creates these worktrees when using the sync-branch feature to commit issue updates to a separate branch without switching your working directory.
**If you don't want these:**
```bash
# Disable sync-branch feature
bd config set sync.branch ""
# Clean up existing worktrees
rm -rf .git/beads-worktrees
rm -rf .git/worktrees/beads-*
git worktree prune
```
See [WORKTREES.md](WORKTREES.md) for details on how beads uses worktrees.
### Auto-sync not working

132
docs/WORKTREES.md
View File

@@ -8,6 +8,102 @@ Beads now provides **enhanced Git worktree support** with a shared database arch
**Note:** While comprehensively implemented and tested internally, this feature may benefit from real-world usage feedback to identify any remaining edge cases.
---
## Beads-Created Worktrees (Sync Branch)
**Important:** Beads automatically creates git worktrees internally for its sync-branch feature. This is different from user-created worktrees for parallel development.
### Why Beads Creates Worktrees
When you configure a **sync branch** (via `bd init --branch <name>` or `bd config set sync.branch <name>`), beads needs to commit issue updates to that branch without switching your working directory away from your current branch.
**Solution:** Beads creates a lightweight worktree that:
- Contains only the `.beads/` directory (sparse checkout)
- Lives in `.git/beads-worktrees/<sync-branch>/`
- Commits issue changes to the sync branch automatically
- Leaves your main working directory untouched
### Where to Find These Worktrees
```
your-project/
├── .git/
│ ├── beads-worktrees/ # Beads-created worktrees live here
│ │ └── beads-sync/ # Default sync branch worktree
│ │ └── .beads/
│ │ └── issues.jsonl # Issue data committed here
│ └── worktrees/ # Standard git worktrees directory
├── .beads/ # Your working copy
│ ├── beads.db # Local SQLite database
│ └── issues.jsonl # Local JSONL (may differ from sync branch)
└── src/ # Your code (untouched by sync)
```
### Common Confusion: "Beads took over main!"
If you see worktrees pointing to `main` and can't switch branches normally, this is likely because:
1. Your sync branch was created from `main`
2. Beads created a worktree for that branch
3. Git worktrees lock branches they're checked out to
**Symptoms:**
```bash
$ git checkout main
fatal: 'main' is already checked out at '/path/to/.git/beads-worktrees/beads-sync'
```
**Quick Fix:**
```bash
# Remove the beads worktree
rm -rf .git/beads-worktrees
# Prune stale worktree references
git worktree prune
# Also remove any stray worktrees in .git/worktrees (older versions)
rm -rf .git/worktrees/beads-*
git worktree prune
```
### Disabling Sync Branch (Remove Worktrees)
If you don't want beads to use a separate sync branch:
```bash
# Unset the sync branch configuration
bd config set sync.branch ""
# Stop and restart daemon
bd daemon stop
bd daemon start
# Clean up existing worktrees
rm -rf .git/beads-worktrees
git worktree prune
```
### Checking Your Sync Branch Configuration
```bash
# See current sync branch setting
bd config get sync.branch
# Check if worktrees exist
ls -la .git/beads-worktrees/ 2>/dev/null || echo "No beads worktrees"
ls -la .git/worktrees/ 2>/dev/null || echo "No standard worktrees"
# List all git worktrees
git worktree list
```
### See Also
For complete sync-branch documentation, see [PROTECTED_BRANCHES.md](PROTECTED_BRANCHES.md).
---
## How It Works
### Shared Database Architecture
@@ -156,6 +252,42 @@ bd create "Fix password validation" -t bug -p 0
## Troubleshooting
### Issue: "Branch already checked out" error
**Symptoms:**
```bash
$ git checkout main
fatal: 'main' is already checked out at '/path/to/.git/beads-worktrees/beads-sync'
```
**Cause:** Beads created a worktree for its sync branch feature, and that worktree has your target branch checked out. Git doesn't allow the same branch to be checked out in multiple worktrees.
**Solution:**
```bash
# Remove beads worktrees
rm -rf .git/beads-worktrees
rm -rf .git/worktrees/beads-*
# Clean up git's worktree registry
git worktree prune
# Now you can checkout the branch
git checkout main
```
**Prevention:** If you use trunk-based development and don't need a separate sync branch, disable it:
```bash
bd config set sync.branch ""
```
### Issue: Unexpected worktree directories appeared
**Symptoms:** You notice `.git/beads-worktrees/` or entries in `.git/worktrees/` that you didn't create.
**Cause:** Beads automatically creates worktrees when using the sync-branch feature (configured via `bd init --branch` or `bd config set sync.branch`).
**Solution:** See [Beads-Created Worktrees](#beads-created-worktrees-sync-branch) section above for details on what these are and how to remove them if unwanted.
### Issue: Daemon commits to wrong branch
**Symptoms:** Changes appear on unexpected branch in git history