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

docs: update beads.jsonl references to issues.jsonl

Browse Source 
Fixes GH#409 - Documentation inconsistently referred to beads.jsonl
as the canonical filename when issues.jsonl has been the default
since v0.25.1 (bd-6xd).

Updated files:
- docs/ARCHITECTURE.md
- docs/CLI_REFERENCE.md
- docs/PROTECTED_BRANCHES.md
- docs/ADVANCED.md
- docs/GIT_INTEGRATION.md
- docs/MULTI_REPO_AGENTS.md
- docs/MULTI_REPO_MIGRATION.md
- docs/TROUBLESHOOTING.md
- examples/*/README.md
- skills/beads/references/CLI_REFERENCE.md

Note: beads.jsonl is still supported for backward compatibility.

🤖 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-16 01:08:46 -08:00
parent 214b5f9d07
commit 166d66205c
15 changed files with 918 additions and 785 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.beads/.gitignore vendored
View File

@@ -30,3 +30,5 @@ beads.right.meta.json
!issues.jsonl !issues.jsonl
!metadata.json !metadata.json
!config.json !config.json
deletions.jsonl
deletions.jsonl.migrated

1599
.beads/issues.jsonl
View File

File diff suppressed because one or more lines are too long

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:** **Resolution:**
```bash ```bash
# After git merge creates conflict # After git merge creates conflict
git checkout --theirs .beads/beads.jsonl # Accept remote version git checkout --theirs .beads/issues.jsonl # Accept remote version
# OR # 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) # OR manually resolve in editor (keep line with newer updated_at)
# Import the resolved JSONL # Import the resolved JSONL
bd import -i .beads/beads.jsonl bd import -i .beads/issues.jsonl
# Commit the merge # Commit the merge
git add .beads/beads.jsonl git add .beads/issues.jsonl
git commit 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 v
┌─────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────┐
│ JSONL File │ │ JSONL File │
│ (.beads/beads.jsonl) │ │ (.beads/issues.jsonl) │
│ │ │ │
│ - Git-tracked source of truth │ │ - Git-tracked source of truth │
│ - One JSON line per entity (issue, dep, label, comment) │ │ - One JSON line per entity (issue, dep, label, comment) │
@@ -246,7 +246,7 @@ open ──▶ in_progress ──▶ closed
``` ```
.beads/ .beads/
├── beads.db # SQLite database (gitignored) ├── 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) ├── bd.sock # Daemon socket (gitignored)
├── daemon.log # Daemon logs (gitignored) ├── daemon.log # Daemon logs (gitignored)
├── config.yaml # Project config (optional) ├── config.yaml # Project config (optional)

2
docs/CLI_REFERENCE.md
View File

@@ -249,7 +249,7 @@ bd --allow-stale list --status open --json
```bash ```bash
# Force metadata update even when DB appears synced # 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. **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 bd init --skip-db # Only reconfigure git, don't touch database
# Verify .gitattributes # Verify .gitattributes
grep "beads.jsonl" .gitattributes grep "issues.jsonl" .gitattributes
# Expected: .beads/issues.jsonl merge=beads # 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 - ❌ Don't manually override routing without good reason
### Teams ### Teams
- ✅ Commit `.beads/beads.jsonl` to shared repo - ✅ Commit `.beads/issues.jsonl` to shared repo
- ✅ Use `bd sync` to ensure changes are committed/pushed - ✅ Use `bd sync` to ensure changes are committed/pushed
- ✅ Link related issues across repos with dependencies - ✅ Link related issues across repos with dependencies
- ❌ Don't gitignore `.beads/` - you lose the git ledger - ❌ Don't gitignore `.beads/` - you lose the git ledger
@@ -328,14 +328,14 @@ Multi-repo mode is fully backward compatible:
**Without multi-repo config:** **Without multi-repo config:**
```bash ```bash
bd create "Issue" -p 1 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:** **With multi-repo config:**
```bash ```bash
bd create "Issue" -p 1 bd create "Issue" -p 1
# → Auto-routed based on config # → Auto-routed based on config
# → Old issues in .beads/beads.jsonl still work # → Old issues in .beads/issues.jsonl still work
``` ```
**Disabling multi-repo:** **Disabling multi-repo:**

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

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 - `.beads/beads.left.jsonl`, `beads.right.jsonl` - Temporary merge artifacts
The sync branch (beads-metadata) will contain: 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/metadata.json` - Metadata about the beads installation
- `.beads/config.yaml` - Configuration template (optional) - `.beads/config.yaml` - Configuration template (optional)
@@ -100,10 +100,10 @@ your-project/
│ └── beads-worktrees/ │ └── beads-worktrees/
│ └── beads-metadata/ # Worktree (only .beads/ checked out) │ └── beads-metadata/ # Worktree (only .beads/ checked out)
│ └── .beads/ │ └── .beads/
│ └── beads.jsonl │ └── issues.jsonl
├── .beads/ # Your main copy ├── .beads/ # Your main copy
│ ├── beads.db │ ├── beads.db
│ ├── beads.jsonl │ ├── issues.jsonl
│ └── .gitignore │ └── .gitignore
├── .gitattributes # Merge driver config (in main branch) ├── .gitattributes # Merge driver config (in main branch)
└── src/ # Your code (untouched) └── src/ # Your code (untouched)
@@ -116,7 +116,7 @@ Main branch (protected):
- `.gitattributes` - Merge driver configuration - `.gitattributes` - Merge driver configuration
Sync branch (beads-metadata): 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/metadata.json` - Repository metadata
- `.beads/config.yaml` - Configuration template - `.beads/config.yaml` - Configuration template
@@ -136,7 +136,7 @@ Not tracked (gitignored):
When you update an issue: 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/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/`) 3. JSONL is copied to worktree (`.git/beads-worktrees/beads-metadata/.beads/`)
4. Daemon commits the change in the worktree to `beads-metadata` branch 4. Daemon commits the change in the worktree to `beads-metadata` branch
5. Main branch stays untouched (no commits on `main`) 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: # bd sync --merge will detect conflicts and show:
Error: Merge conflicts detected Error: Merge conflicts detected
Conflicting files: Conflicting files:
.beads/beads.jsonl .beads/issues.jsonl
To resolve: To resolve:
1. Fix conflicts in .beads/beads.jsonl 1. Fix conflicts in .beads/issues.jsonl
2. git add .beads/beads.jsonl 2. git add .beads/issues.jsonl
3. git commit 3. git commit
4. bd import # Reimport to sync database 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: 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 2. Both versions are usually valid - keep both lines
3. Remove the conflict markers 3. Remove the conflict markers
4. Save and commit 4. Save and commit
@@ -332,8 +332,8 @@ Example conflict resolution:
Then: Then:
```bash ```bash
git add .beads/beads.jsonl git add .beads/issues.jsonl
git commit -m "Resolve beads.jsonl merge conflict" git commit -m "Resolve issues.jsonl merge conflict"
bd import # Import to database (will use latest timestamp) bd import # Import to database (will use latest timestamp)
``` ```

4
docs/TROUBLESHOOTING.md
View File

@@ -611,7 +611,7 @@ bd --allow-stale list --status open
```bash ```bash
# Most reliable for sandboxed environments # Most reliable for sandboxed environments
bd --sandbox ready bd --sandbox ready
bd --sandbox import -i .beads/beads.jsonl bd --sandbox import -i .beads/issues.jsonl
``` ```
--- ---
@@ -625,7 +625,7 @@ If stuck in a sandboxed environment:
bd --sandbox ready bd --sandbox ready
# Step 2: If you get staleness errors, force import # 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) # Step 3: If still blocked, use allow-stale (emergency only)
bd --allow-stale ready 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 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 ### 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: After a git pull or merge, the hook runs:
```bash ```bash
bd import -i .beads/beads.jsonl bd import -i .beads/issues.jsonl
``` ```
This ensures your local database reflects the merged state. The hook: 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 - Imports any new issues or updates from the merge
- Warns on failure but doesn't block the merge - Warns on failure but doesn't block the merge

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

@@ -176,11 +176,11 @@ my-project/
│ ├── beads-worktrees/ # Hidden worktree directory │ ├── beads-worktrees/ # Hidden worktree directory
│ │ └── beads-metadata/ # Lightweight checkout of sync branch │ │ └── beads-metadata/ # Lightweight checkout of sync branch
│ │ └── .beads/ │ │ └── .beads/
│ │ └── beads.jsonl │ │ └── issues.jsonl
│ └── ... │ └── ...
├── .beads/ # Main beads directory (in your workspace) ├── .beads/ # Main beads directory (in your workspace)
│ ├── beads.db # SQLite database │ ├── beads.db # SQLite database
│ ├── beads.jsonl # JSONL export │ ├── issues.jsonl # JSONL export
│ └── bd.sock # Daemon socket (if running) │ └── bd.sock # Daemon socket (if running)
├── src/ # Your application code ├── src/ # Your application code
│ └── ... │ └── ...
@@ -209,7 +209,7 @@ my-project/
### Troubleshooting ### 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: JSONL is append-only and line-based, so conflicts are rare. If they occur:
1. Both versions are usually valid - keep both lines 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 ```bash
# During git pull/merge # During git pull/merge
git pull origin beads-metadata git pull origin beads-metadata
# CONFLICT in .beads/beads.jsonl # CONFLICT in .beads/issues.jsonl
# Option 1: Accept remote # Option 1: Accept remote
git checkout --theirs .beads/beads.jsonl git checkout --theirs .beads/issues.jsonl
bd import -i .beads/beads.jsonl bd import -i .beads/issues.jsonl
# Option 2: Accept local # Option 2: Accept local
git checkout --ours .beads/beads.jsonl git checkout --ours .beads/issues.jsonl
bd import -i .beads/beads.jsonl bd import -i .beads/issues.jsonl
# Option 3: Use beads-merge tool (recommended) # Option 3: Use beads-merge tool (recommended)
# See docs/GIT_INTEGRATION.md for merge conflict resolution # See docs/GIT_INTEGRATION.md for merge conflict resolution
git add .beads/beads.jsonl git add .beads/issues.jsonl
git commit git commit
``` ```
@@ -299,7 +299,7 @@ git commit
### Q: How do team members see each other's issues? ### 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 ```bash
git pull 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)): Use beads-merge or resolve manually (see [GIT_INTEGRATION.md](../../docs/GIT_INTEGRATION.md)):
```bash ```bash
git checkout --theirs .beads/beads.jsonl git checkout --theirs .beads/issues.jsonl
bd import -i .beads/beads.jsonl bd import -i .beads/issues.jsonl
git add .beads/beads.jsonl git add .beads/issues.jsonl
git commit git commit
``` ```

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

@@ -249,7 +249,7 @@ bd --allow-stale list --status open --json
```bash ```bash
# Force metadata update even when DB appears synced # 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. **When to use:** `bd import` reports "0 created, 0 updated" but staleness errors persist.