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

Merge bd-2k5f-pumpjack: GH#483

Browse Source
This commit is contained in:
Steve Yegge
2025-12-16 01:18:02 -08:00
parent 3be20d64da 69ac8fdbc2
commit 8306b2b8f3
6 changed files with 1139 additions and 910 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1790
.beads/issues.jsonl
View File

File diff suppressed because one or more lines are too long

15
cmd/bd/templates/hooks/pre-commit
View File

@@ -23,12 +23,20 @@ if ! command -v bd >/dev/null 2>&1; then
exit 0
fi
# Check if we're in a bd workspace
# Check if we're in a bd workspace with an actual database
# Just having a .beads directory isn't enough - it must be properly initialized
if [ ! -d .beads ]; then
# Not a bd workspace, nothing to do
exit 0
fi
# Verify beads is actually initialized (has database or config)
# This handles the case where .beads was removed from git but directory lingers
if [ ! -f .beads/beads.db ] && [ ! -f .beads/config.yaml ] && [ ! -f .beads/issues.jsonl ]; then
# Directory exists but beads not initialized, nothing to do
exit 0
fi
# Check if sync-branch is configured in config.yaml or env var
# If so, .beads changes go to a separate branch via worktree, not the current branch
SYNC_BRANCH="${BEADS_SYNC_BRANCH:-}"
@@ -46,10 +54,11 @@ fi
# Flush pending changes to JSONL
# Use --flush-only to skip git operations (we're already in a git hook)
# Suppress output unless there's an error
# Note: We don't block commits on flush failure - beads issues shouldn't prevent code commits
if ! bd sync --flush-only >/dev/null 2>&1; then
echo "Error: Failed to flush bd changes to JSONL" >&2
echo "Warning: Failed to flush bd changes to JSONL" >&2
echo "Run 'bd sync --flush-only' manually to diagnose" >&2
exit 1
# Continue with commit - don't block code changes due to beads issues
fi
# Stage all tracked JSONL files (issues.jsonl is canonical, beads.jsonl for backward compat, deletions.jsonl for deletion propagation)

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
@@ -154,6 +250,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

29
examples/git-hooks/pre-commit
View File

@@ -1,5 +1,5 @@
#!/bin/sh
# bd-hooks-version: 0.22.2
# bd-hooks-version: 0.29.0
#
# bd (beads) pre-commit hook
#
@@ -23,12 +23,20 @@ if ! command -v bd >/dev/null 2>&1; then
exit 0
fi
# Check if we're in a bd workspace
# Check if we're in a bd workspace with an actual database
# Just having a .beads directory isn't enough - it must be properly initialized
if [ ! -d .beads ]; then
# Not a bd workspace, nothing to do
exit 0
fi
# Verify beads is actually initialized (has database or config)
# This handles the case where .beads was removed from git but directory lingers
if [ ! -f .beads/beads.db ] && [ ! -f .beads/config.yaml ] && [ ! -f .beads/issues.jsonl ]; then
# Directory exists but beads not initialized, nothing to do
exit 0
fi
# Check if sync-branch is configured in config.yaml or env var
# If so, .beads changes go to a separate branch via worktree, not the current branch
SYNC_BRANCH="${BEADS_SYNC_BRANCH:-}"
@@ -46,16 +54,27 @@ fi
# Flush pending changes to JSONL
# Use --flush-only to skip git operations (we're already in a git hook)
# Suppress output unless there's an error
# Note: We don't block commits on flush failure - beads issues shouldn't prevent code commits
if ! bd sync --flush-only >/dev/null 2>&1; then
echo "Error: Failed to flush bd changes to JSONL" >&2
echo "Warning: Failed to flush bd changes to JSONL" >&2
echo "Run 'bd sync --flush-only' manually to diagnose" >&2
exit 1
# Continue with commit - don't block code changes due to beads issues
fi
# Stage all tracked JSONL files (beads.jsonl, issues.jsonl for backward compat, deletions.jsonl for deletion propagation)
# Stage all tracked JSONL files (issues.jsonl is canonical, beads.jsonl for backward compat, deletions.jsonl for deletion propagation)
# For worktrees, .beads is in the main repo's working tree, not the worktree,
# so we can't use git add. Skip staging for worktrees.
if [ "$(git rev-parse --git-dir)" = "$(git rev-parse --git-common-dir)" ]; then
# Regular repo: files are in the working tree, safe to add
# git add is harmless if file doesn't exist
for f in .beads/beads.jsonl .beads/issues.jsonl .beads/deletions.jsonl; do
[ -f "$f" ] && git add "$f" 2>/dev/null || true
done
else
# Worktree: .beads is in the main repo's working tree, not this worktree
# Git rejects adding files outside the worktree, so we skip it.
# The main repo will see the changes on the next pull/sync.
: # do nothing
fi
exit 0