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

docs: clarify bd reset command and document workarounds (GH#922)

Browse Source 
- Add Reset section to CLI_REFERENCE.md documenting bd admin reset
- Add troubleshooting section for "old data returns after reset"
- Clarify that --hard and --skip-init flags were never implemented
- Document workarounds for complete clean slate including remote data

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
beads/crew/wolf
2026-01-11 20:45:27 -08:00
committed by Steve Yegge
parent 0248895298
commit b9207b513c
2 changed files with 79 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/CLI_REFERENCE.md
View File

@@ -373,6 +373,33 @@ bd rename-prefix kw- --dry-run # Preview changes
bd rename-prefix kw- --json # Apply rename
```
### Reset
Remove all local beads data and return to uninitialized state.
```bash
# Preview what would be removed (dry-run)
bd admin reset
# Actually perform the reset
bd admin reset --force
```
**What gets removed:**
- `.beads/` directory (database, JSONL, config)
- Git hooks installed by bd
- Merge driver configuration
- Sync branch worktrees (`.git/beads-worktrees/`)
**What does NOT get removed:**
- Remote sync branch (if configured)
- JSONL history in git commits
- Remote repository data
**Important:** If you want a complete clean slate (including remote data), see [Troubleshooting: Old data returns after reset](TROUBLESHOOTING.md#old-data-returns-after-reset).
**Note:** The `--hard` and `--skip-init` flags mentioned in some discussions were never implemented. Use `--force` to perform the reset.
## Molecular Chemistry
Beads uses a chemistry metaphor for template-based workflows. See [MOLECULES.md](MOLECULES.md) for full documentation.

52
docs/TROUBLESHOOTING.md
View File

@@ -211,6 +211,58 @@ bd config set import.orphan_handling "strict"
See [CONFIG.md](CONFIG.md#example-import-orphan-handling) for complete configuration documentation.
### Old data returns after reset
**Symptom:** After running `bd admin reset --force` and `bd init`, old issues reappear.
**Cause:** `bd admin reset --force` only removes **local** beads data. Old data can return from:
1. **Remote sync branch** - If you configured a sync branch (via `bd init --branch` or `bd config set sync.branch`), old JSONL data may exist on the remote
2. **Git history** - JSONL files committed to git are preserved in history
3. **Other machines** - Other clones may push old data after you reset
**Solution for complete clean slate:**
```bash
# 1. Reset local beads
bd admin reset --force
# 2. Delete remote sync branch (if configured)
# Check your sync branch name first:
bd config get sync.branch
# Then delete it from remote:
git push origin --delete <sync-branch-name>
# Common names: beads-sync, beads-metadata
# 3. Remove JSONL from git history (optional, destructive)
# Only do this if you want to completely erase beads history
git filter-branch --force --index-filter \
'git rm --cached --ignore-unmatch .beads/issues.jsonl' \
--prune-empty -- --all
git push origin --force --all
# 4. Re-initialize
bd init
```
**Less destructive alternatives:**
```bash
# Option A: Just delete the sync branch and reinit
bd admin reset --force
git push origin --delete beads-sync # or your sync branch name
bd init
# Option B: Start fresh without sync branch
bd admin reset --force
bd init
bd config set sync.branch "" # Disable sync branch feature
```
**Note:** The `--hard` and `--skip-init` flags mentioned in [GH#479](https://github.com/steveyegge/beads/issues/479) were never implemented. Use the workarounds above for a complete reset.
**Related:** [GH#922](https://github.com/steveyegge/beads/issues/922)
### Database corruption
**Important**: Distinguish between **logical consistency issues** (ID collisions, wrong prefixes) and **physical SQLite corruption**.