docs/UNINSTALLING.md
This guide explains how to completely remove Beads from a repository.
Run these commands from your repository root:
# 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
If a Dolt server is running, stop it before cleanup:
bd dolt stop 2>/dev/null || true
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:
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:
ls .git/hooks/*.backup
Restore any backups if needed:
mv .git/hooks/pre-commit.backup .git/hooks/pre-commit
Beads adds these entries to your git config:
git config --unset beads.role
git config --unset merge.beads.driver
git config --unset merge.beads.name
Beads may have added a line to .gitattributes for merge handling. Check and remove if present:
# 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
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:
rm -rf .beads
Warning: This permanently deletes all issue data. Consider backing up first:
bd export -o ~/beads-backup-$(date +%Y%m%d).jsonl
If you used branch sync features, clean up the worktree:
rm -rf .git/beads-worktrees
If .beads/ was tracked in git, commit its removal:
git add -A
git commit -m "Remove beads issue tracking"
git push
bd BinaryThe bd command itself is a standalone binary. Remove it based on how you installed:
If installed via go install:
rm $(which bd)
# Or: rm ~/go/bin/bd
If installed manually:
# Remove from wherever you placed it
rm /usr/local/bin/bd
Run these checks to confirm Beads is fully removed:
# 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
To set up Beads again in the future:
bd init
This will recreate the .beads/ directory, install hooks, and configure the merge driver.