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

Merge GH#409

Browse Source
This commit is contained in:
Steve Yegge
2025-12-16 01:19:07 -08:00
parent 22e63fb128 166d66205c
commit dedfc43d1f
17 changed files with 9685 additions and 366 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
.beads-hooks/pre-commit
View File

@@ -1,5 +1,5 @@
#!/bin/sh
# bd-hooks-version: 0.24.2
# bd-hooks-version: 0.29.0
#
# bd (beads) pre-commit hook
#
@@ -29,10 +29,12 @@ 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 warn but don't fail - this allows commits to proceed even if
# beads has issues (e.g., user removed .beads from their branch)
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
# Don't block the commit - user may have removed beads or have other issues
fi
# Stage all tracked JSONL files (issues.jsonl is canonical, beads.jsonl for backward compat, deletions.jsonl for deletion propagation)

9898
.beads/deletions.jsonl
View File

File diff suppressed because it is too large Load Diff

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

@@ -54,11 +54,20 @@ 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
<<<<<<< HEAD
# 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 "Warning: Failed to flush bd changes to JSONL" >&2
echo "Run 'bd sync --flush-only' manually to diagnose" >&2
# Continue with commit - don't block code changes due to beads issues
=======
# Note: We warn but don't fail - this allows commits to proceed even if
# beads has issues (e.g., user removed .beads from their branch)
if ! bd sync --flush-only >/dev/null 2>&1; then
echo "Warning: Failed to flush bd changes to JSONL" >&2
echo "Run 'bd sync --flush-only' manually to diagnose" >&2
# Don't block the commit - user may have removed beads or have other issues
>>>>>>> origin/bd-l0pg-slit
fi
# Stage all tracked JSONL files (issues.jsonl is canonical, beads.jsonl for backward compat, deletions.jsonl for deletion propagation)

8
docs/ADVANCED.md
View File

@@ -231,16 +231,16 @@ The conflicts you'll encounter are **git merge conflicts** in the JSONL file whe
**Resolution:**
```bash
# After git merge creates conflict
git checkout --theirs .beads/beads.jsonl # Accept remote version
git checkout --theirs .beads/issues.jsonl # Accept remote version
# OR
git checkout --ours .beads/beads.jsonl # Keep local version
git checkout --ours .beads/issues.jsonl # Keep local version
# OR manually resolve in editor (keep line with newer updated_at)
# Import the resolved JSONL
bd import -i .beads/beads.jsonl
bd import -i .beads/issues.jsonl
# Commit the merge
git add .beads/beads.jsonl
git add .beads/issues.jsonl
git commit
```

4
docs/ARCHITECTURE.md
View File

@@ -33,7 +33,7 @@ bd's core design enables a distributed, git-backed issue tracker that feels like
v
┌─────────────────────────────────────────────────────────────────┐
│ JSONL File │
│ (.beads/beads.jsonl) │
│ (.beads/issues.jsonl) │
│ │
│ - Git-tracked source of truth │
│ - One JSON line per entity (issue, dep, label, comment) │
@@ -246,7 +246,7 @@ open ──▶ in_progress ──▶ closed
```
.beads/
├── beads.db # SQLite database (gitignored)
├── beads.jsonl # JSONL source of truth (git-tracked)
├── issues.jsonl # JSONL source of truth (git-tracked)
├── bd.sock # Daemon socket (gitignored)
├── daemon.log # Daemon logs (gitignored)
├── config.yaml # Project config (optional)

2
docs/CLI_REFERENCE.md
View File

@@ -250,7 +250,7 @@ bd --allow-stale list --status open --json
```bash
# Force metadata update even when DB appears synced
bd import --force -i .beads/beads.jsonl
bd import --force -i .beads/issues.jsonl
```
**When to use:** `bd import` reports "0 created, 0 updated" but staleness errors persist.

2
docs/GIT_INTEGRATION.md
View File

@@ -595,7 +595,7 @@ git config merge.beads.driver
bd init --skip-db # Only reconfigure git, don't touch database
# Verify .gitattributes
grep "beads.jsonl" .gitattributes
grep "issues.jsonl" .gitattributes
# Expected: .beads/issues.jsonl merge=beads
```

6
docs/MULTI_REPO_AGENTS.md
View File

@@ -303,7 +303,7 @@ bd daemons killall # Restart all daemons
- ❌ Don't manually override routing without good reason
### Teams
- ✅ Commit `.beads/beads.jsonl` to shared repo
- ✅ Commit `.beads/issues.jsonl` to shared repo
- ✅ Use `bd sync` to ensure changes are committed/pushed
- ✅ Link related issues across repos with dependencies
- ❌ Don't gitignore `.beads/` - you lose the git ledger
@@ -328,14 +328,14 @@ Multi-repo mode is fully backward compatible:
**Without multi-repo config:**
```bash
bd create "Issue" -p 1
# → Creates in .beads/beads.jsonl (single-repo mode)
# → Creates in .beads/issues.jsonl (single-repo mode)
```
**With multi-repo config:**
```bash
bd create "Issue" -p 1
# → Auto-routed based on config
# → Old issues in .beads/beads.jsonl still work
# → Old issues in .beads/issues.jsonl still work
```
**Disabling multi-repo:**

19
docs/MULTI_REPO_MIGRATION.md
View File

@@ -14,7 +14,7 @@ This guide helps you adopt beads' multi-repo workflow for OSS contributions, tea
## What is Multi-Repo Mode?
By default, beads stores issues in `.beads/beads.jsonl` in your current repository. Multi-repo mode lets you:
By default, beads stores issues in `.beads/issues.jsonl` in your current repository. Multi-repo mode lets you:
- **Route issues to different repositories** based on your role (maintainer vs. contributor)
- **Aggregate issues from multiple repos** into a unified view
@@ -223,7 +223,7 @@ bd ready
bd list --json
# Complete team work
git add .beads/beads.jsonl
git add .beads/issues.jsonl
git commit -m "Updated issue tracker"
git push origin main
```
@@ -394,7 +394,7 @@ bd sync
bd list --json
```
### Git merge conflicts in .beads/beads.jsonl
### Git merge conflicts in .beads/issues.jsonl
**Problem:** Multiple repos modifying same JSONL file.
@@ -432,12 +432,12 @@ No migration needed! Multi-repo mode is opt-in:
```bash
# Before (single repo)
bd create "Issue" -p 1
# → Creates in .beads/beads.jsonl
# → Creates in .beads/issues.jsonl
# After (multi-repo configured)
bd create "Issue" -p 1
# → Auto-routed based on role
# → Old issues in .beads/beads.jsonl still work
# → Old issues in .beads/issues.jsonl still work
```
### Disabling Multi-Repo
@@ -461,7 +461,7 @@ bd create "Issue" -p 1
- ❌ Don't mix planning and implementation in the same repo
### Teams
- ✅ Commit `.beads/beads.jsonl` to shared repository
- ✅ Commit `.beads/issues.jsonl` to shared repository
- ✅ Use protected branch workflow for main/master
- ✅ Review issue changes in PRs like code changes
- ❌ Don't gitignore `.beads/` - you lose the git ledger
@@ -481,7 +481,14 @@ bd create "Issue" -p 1
## Related Issues
<<<<<<< HEAD
- `bd-8rd` - Migration and onboarding epic
- `bd-mlcz` - `bd migrate` command (planned)
- `bd-kla1` - `bd init --contributor` wizard ✅ implemented
- `bd-twlr` - `bd init --team` wizard ✅ implemented
=======
- [bd-8rd](/.beads/issues.jsonl#bd-8rd) - Migration and onboarding epic
- [bd-mlcz](/.beads/issues.jsonl#bd-mlcz) - `bd migrate` command (planned)
- [bd-kla1](/.beads/issues.jsonl#bd-kla1) - `bd init --contributor` wizard ✅ implemented
- [bd-twlr](/.beads/issues.jsonl#bd-twlr) - `bd init --team` wizard ✅ implemented
>>>>>>> origin/bd-l0pg-slit

22
docs/PROTECTED_BRANCHES.md
View File

@@ -62,7 +62,7 @@ Files that are automatically gitignored (do NOT commit):
- `.beads/beads.left.jsonl`, `beads.right.jsonl` - Temporary merge artifacts
The sync branch (beads-metadata) will contain:
- `.beads/beads.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/config.yaml` - Configuration template (optional)
@@ -100,10 +100,10 @@ your-project/
│ └── beads-worktrees/
│ └── beads-metadata/ # Worktree (only .beads/ checked out)
│ └── .beads/
│ └── beads.jsonl
│ └── issues.jsonl
├── .beads/ # Your main copy
│ ├── beads.db
│ ├── beads.jsonl
│ ├── issues.jsonl
│ └── .gitignore
├── .gitattributes # Merge driver config (in main branch)
└── src/ # Your code (untouched)
@@ -116,7 +116,7 @@ Main branch (protected):
- `.gitattributes` - Merge driver configuration
Sync branch (beads-metadata):
- `.beads/beads.jsonl` - Issue data (committed by daemon)
- `.beads/issues.jsonl` - Issue data (committed by daemon)
- `.beads/metadata.json` - Repository metadata
- `.beads/config.yaml` - Configuration template
@@ -136,7 +136,7 @@ Not tracked (gitignored):
When you update an issue:
1. Issue is updated in `.beads/beads.db` (SQLite database)
2. Daemon exports to `.beads/beads.jsonl` (JSONL file)
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
5. Main branch stays untouched (no commits on `main`)
@@ -295,11 +295,11 @@ If you encounter conflicts during merge:
# bd sync --merge will detect conflicts and show:
Error: Merge conflicts detected
Conflicting files:
.beads/beads.jsonl
.beads/issues.jsonl
To resolve:
1. Fix conflicts in .beads/beads.jsonl
2. git add .beads/beads.jsonl
1. Fix conflicts in .beads/issues.jsonl
2. git add .beads/issues.jsonl
3. git commit
4. bd import # Reimport to sync database
```
@@ -308,7 +308,7 @@ To resolve:
JSONL files are append-only and line-based, so conflicts are rare. When they occur:
1. Open `.beads/beads.jsonl` and look for conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)
1. Open `.beads/issues.jsonl` and look for conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)
2. Both versions are usually valid - keep both lines
3. Remove the conflict markers
4. Save and commit
@@ -332,8 +332,8 @@ Example conflict resolution:
Then:
```bash
git add .beads/beads.jsonl
git commit -m "Resolve beads.jsonl merge conflict"
git add .beads/issues.jsonl
git commit -m "Resolve issues.jsonl merge conflict"
bd import # Import to database (will use latest timestamp)
```

4
docs/TROUBLESHOOTING.md
View File

@@ -656,7 +656,7 @@ bd --allow-stale list --status open
```bash
# Most reliable for sandboxed environments
bd --sandbox ready
bd --sandbox import -i .beads/beads.jsonl
bd --sandbox import -i .beads/issues.jsonl
```
---
@@ -670,7 +670,7 @@ If stuck in a sandboxed environment:
bd --sandbox ready
# Step 2: If you get staleness errors, force import
bd import --force -i .beads/beads.jsonl
bd import --force -i .beads/issues.jsonl
# Step 3: If still blocked, use allow-stale (emergency only)
bd --allow-stale ready

2
examples/contributor-workflow/README.md
View File

@@ -58,7 +58,7 @@ When you create issues as a contributor:
bd create "Fix authentication bug" -p 1
```
Beads automatically routes this to your planning repo (`~/.beads-planning/.beads/beads.jsonl`), not the current repo.
Beads automatically routes this to your planning repo (`~/.beads-planning/.beads/issues.jsonl`), not the current repo.
### Viewing Issues

4
examples/git-hooks/README.md
View File

@@ -129,11 +129,11 @@ This solves bd-my64: changes made between commit and push (or pending debounced
After a git pull or merge, the hook runs:
```bash
bd import -i .beads/beads.jsonl
bd import -i .beads/issues.jsonl
```
This ensures your local database reflects the merged state. The hook:
- Only runs if `.beads/beads.jsonl` exists (also checks `issues.jsonl` for backward compat)
- Only runs if `.beads/issues.jsonl` exists (also checks `issues.jsonl` for backward compat)
- Imports any new issues or updates from the merge
- Warns on failure but doesn't block the merge

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

@@ -23,20 +23,12 @@ if ! command -v bd >/dev/null 2>&1; then
exit 0
fi
# 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
# Check if we're in a bd workspace
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:-}"
@@ -54,27 +46,18 @@ 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
# Note: We warn but don't fail - this allows commits to proceed even if
# beads has issues (e.g., user removed .beads from their branch)
if ! bd sync --flush-only >/dev/null 2>&1; then
echo "Warning: Failed to flush bd changes to JSONL" >&2
echo "Run 'bd sync --flush-only' manually to diagnose" >&2
# Continue with commit - don't block code changes due to beads issues
# Don't block the commit - user may have removed beads or have other issues
fi
# 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
# Stage all tracked JSONL files (beads.jsonl, issues.jsonl for backward compat, deletions.jsonl for deletion propagation)
# 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
exit 0

6
examples/protected-branch/README.md
View File

@@ -176,11 +176,11 @@ my-project/
│ ├── beads-worktrees/ # Hidden worktree directory
│ │ └── beads-metadata/ # Lightweight checkout of sync branch
│ │ └── .beads/
│ │ └── beads.jsonl
│ │ └── issues.jsonl
│ └── ...
├── .beads/ # Main beads directory (in your workspace)
│ ├── beads.db # SQLite database
│ ├── beads.jsonl # JSONL export
│ ├── issues.jsonl # JSONL export
│ └── bd.sock # Daemon socket (if running)
├── src/ # Your application code
│ └── ...
@@ -209,7 +209,7 @@ my-project/
### Troubleshooting
**"Merge conflicts in beads.jsonl"**
**"Merge conflicts in issues.jsonl"**
JSONL is append-only and line-based, so conflicts are rare. If they occur:
1. Both versions are usually valid - keep both lines

20
examples/team-workflow/README.md
View File

@@ -244,20 +244,20 @@ Hash-based IDs prevent most conflicts. If conflicts occur:
```bash
# During git pull/merge
git pull origin beads-metadata
# CONFLICT in .beads/beads.jsonl
# CONFLICT in .beads/issues.jsonl
# Option 1: Accept remote
git checkout --theirs .beads/beads.jsonl
bd import -i .beads/beads.jsonl
git checkout --theirs .beads/issues.jsonl
bd import -i .beads/issues.jsonl
# Option 2: Accept local
git checkout --ours .beads/beads.jsonl
bd import -i .beads/beads.jsonl
git checkout --ours .beads/issues.jsonl
bd import -i .beads/issues.jsonl
# Option 3: Use beads-merge tool (recommended)
# See docs/GIT_INTEGRATION.md for merge conflict resolution
git add .beads/beads.jsonl
git add .beads/issues.jsonl
git commit
```
@@ -299,7 +299,7 @@ git commit
### Q: How do team members see each other's issues?
A: Issues are stored in `.beads/beads.jsonl` which is version-controlled. Pull from git to sync.
A: Issues are stored in `.beads/issues.jsonl` which is version-controlled. Pull from git to sync.
```bash
git pull
@@ -372,9 +372,9 @@ bd daemon --start --auto-commit --auto-push
Use beads-merge or resolve manually (see [GIT_INTEGRATION.md](../../docs/GIT_INTEGRATION.md)):
```bash
git checkout --theirs .beads/beads.jsonl
bd import -i .beads/beads.jsonl
git add .beads/beads.jsonl
git checkout --theirs .beads/issues.jsonl
bd import -i .beads/issues.jsonl
git add .beads/issues.jsonl
git commit
```

2
skills/beads/references/CLI_REFERENCE.md
View File

@@ -249,7 +249,7 @@ bd --allow-stale list --status open --json
```bash
# Force metadata update even when DB appears synced
bd import --force -i .beads/beads.jsonl
bd import --force -i .beads/issues.jsonl
```
**When to use:** `bd import` reports "0 created, 0 updated" but staleness errors persist.