beads/docs/UNINSTALLING.md
beads/crew/elinor 90da8f6028 docs: remove stale JSONL references from ~73 markdown files (bd-9ni.4)
Replace JSONL storage/sync references with Dolt-native equivalents across
documentation, plugin resources, website docs, agent instructions, and
example READMEs. Preserves legitimate JSONL references (bd import/export
commands, CHANGELOG history, routes.jsonl/interactions.jsonl concepts).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-22 22:18:02 -08:00

186 lines
4 KiB
Markdown

# Uninstalling Beads
This guide explains how to completely remove Beads from a repository.
## Quick Uninstall
Run these commands from your repository root:
```bash
# 1. Stop any running Dolt server (optional)
bd dolt stop 2>/dev/null || true
# 2. Remove git hooks installed by Beads
rm -f .git/hooks/pre-commit .git/hooks/prepare-commit-msg .git/hooks/post-merge .git/hooks/pre-push .git/hooks/post-checkout
# 3. Remove git config entries
git config --unset beads.role
git config --unset merge.beads.driver
git config --unset merge.beads.name
# 4. Remove .gitattributes entry (if only contains beads config)
# Or manually edit to remove the beads line
rm -f .gitattributes
# 5. Remove .beads directory
rm -rf .beads
# 6. Remove sync worktree (if exists)
rm -rf .git/beads-worktrees
```
## Detailed Steps
### 1. Stop the Dolt Server (Optional)
If a Dolt server is running, stop it before cleanup:
```bash
bd dolt stop 2>/dev/null || true
```
### 2. Remove Git Hooks
Beads installs these hooks in `.git/hooks/`:
| Hook | Purpose |
|------|---------|
| `pre-commit` | Runs beads pre-commit checks |
| `prepare-commit-msg` | Adds beads metadata to commit messages |
| `post-merge` | Imports changes after merges |
| `pre-push` | Syncs before pushing |
| `post-checkout` | Imports after branch switches |
To remove them:
```bash
rm -f .git/hooks/pre-commit
rm -f .git/hooks/prepare-commit-msg
rm -f .git/hooks/post-merge
rm -f .git/hooks/pre-push
rm -f .git/hooks/post-checkout
```
**Note:** If you had custom hooks before installing Beads, check for `.backup` files:
```bash
ls .git/hooks/*.backup
```
Restore any backups if needed:
```bash
mv .git/hooks/pre-commit.backup .git/hooks/pre-commit
```
### 3. Remove Git Config Entries
Beads adds these entries to your git config:
```bash
git config --unset beads.role
git config --unset merge.beads.driver
git config --unset merge.beads.name
```
### 4. Remove .gitattributes Entry
Beads may have added a line to `.gitattributes` for merge handling. Check and remove if present:
```bash
# Check if .gitattributes contains beads config
cat .gitattributes
# Remove the entire file if it only contains beads config
rm -f .gitattributes
# Or edit to remove just the beads line
```
### 5. Remove .beads Directory
The `.beads/` directory contains:
| File/Dir | Description |
|----------|-------------|
| `dolt/` | Dolt database directory |
| `dolt/sql-server.pid` | Running Dolt server PID (if server mode) |
| `dolt/sql-server.log` | Dolt server logs (if server mode) |
| `issues.jsonl` | Legacy issue data (if present) |
| `config.yaml` | Project configuration |
| `metadata.json` | Version tracking |
| `deletions.jsonl` | Soft-deleted issues (if present) |
| `README.md` | Human-readable overview |
Remove everything:
```bash
rm -rf .beads
```
**Warning:** This permanently deletes all issue data. Consider backing up first:
```bash
bd export -o ~/beads-backup-$(date +%Y%m%d).jsonl
```
### 6. Remove Sync Worktree
If you used branch sync features, clean up the worktree:
```bash
rm -rf .git/beads-worktrees
```
### 7. Commit the Removal (Optional)
If `.beads/` was tracked in git, commit its removal:
```bash
git add -A
git commit -m "Remove beads issue tracking"
git push
```
## Uninstalling the `bd` Binary
The `bd` command itself is a standalone binary. Remove it based on how you installed:
**If installed via go install:**
```bash
rm $(which bd)
# Or: rm ~/go/bin/bd
```
**If installed manually:**
```bash
# Remove from wherever you placed it
rm /usr/local/bin/bd
```
## Verify Complete Removal
Run these checks to confirm Beads is fully removed:
```bash
# Should show "command not found" or be a different bd
which bd
# Should not exist
ls .beads/
# Should not contain beads hooks
ls .git/hooks/
# Should not have merge driver
git config --get merge.beads.driver
# No .gitattributes or no beads line
cat .gitattributes
```
## Re-installing Later
To set up Beads again in the future:
```bash
bd init
```
This will recreate the `.beads/` directory, install hooks, and configure the merge driver.