beads/docs/UNINSTALLING.md

Uninstalling Beads

This guide explains how to completely remove Beads from a repository.

Quick Uninstall

Run these commands from your repository root:

# 1. Stop any running daemon
bd daemons killall

# 2. Remove git hooks installed by Beads
rm -f .git/hooks/pre-commit .git/hooks/post-merge .git/hooks/pre-push .git/hooks/post-checkout

# 3. Remove merge driver config
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 Daemon

If a Beads daemon is running for this repository, stop it first:

bd daemons list     # Check if daemon is running
bd daemons killall  # Stop all daemons

2. Remove Git Hooks

Beads installs these hooks in .git/hooks/:

Hook	Purpose
pre-commit	Syncs JSONL before commits
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/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

3. Remove Merge Driver Configuration

Beads configures a custom merge driver in your git config:

git config --unset merge.beads.driver
git config --unset merge.beads.name

4. Remove .gitattributes Entry

Beads adds a line to .gitattributes for JSONL merge handling:

.beads/issues.jsonl merge=beads

Either remove the entire file (if it only contains this line):

rm -f .gitattributes

Or edit it to remove just the beads line:

# Edit .gitattributes and remove the line containing "merge=beads"

5. Remove .beads Directory

The .beads/ directory contains:

File/Dir	Description
beads.db	SQLite database with issues
issues.jsonl	Git-tracked issue data
daemon.pid	Running daemon PID
daemon.log	Daemon logs
daemon.lock	Lock file for daemon
bd.sock	Unix socket for daemon IPC
config.yaml	Project configuration
metadata.json	Version tracking
deletions.jsonl	Soft-deleted issues
README.md	Human-readable overview

Remove everything:

rm -rf .beads

Warning: This permanently deletes all issue data. Consider backing up first:

cp .beads/issues.jsonl ~/beads-backup-$(date +%Y%m%d).jsonl

6. Remove Sync Worktree

If you used branch sync features, clean up the worktree:

rm -rf .git/beads-worktrees

7. Commit the Removal (Optional)

If .beads/ was tracked in git, commit its removal:

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:

rm $(which bd)
# Or: rm ~/go/bin/bd

If installed manually:

# Remove from wherever you placed it
rm /usr/local/bin/bd

Verify Complete Removal

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

Re-installing Later

To set up Beads again in the future:

bd init

This will recreate the .beads/ directory, install hooks, and configure the merge driver.