diff --git a/docs/FAQ.md b/docs/FAQ.md index ec851360..ae48974e 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -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 ` +- Set `bd config set sync.branch ` + +The worktrees allow beads to commit issue updates to a separate branch without switching your working directory. + +**Location:** `.git/beads-worktrees//` + +**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? diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index a810814f..4b081922 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -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 diff --git a/docs/WORKTREES.md b/docs/WORKTREES.md index 96da22c2..803619af 100644 --- a/docs/WORKTREES.md +++ b/docs/WORKTREES.md @@ -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 ` or `bd config set sync.branch `), 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//` +- 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