Beads 完全卸载指南从bd admin reset到手工清理与数据备份【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads本指南围绕 Beadsbd在仓库中的卸载全流程展开无论你是想从单个仓库中移除 Beads 数据与 Git hooks还是想彻底从机器上删除bd二进制都能在这里找到可复现的操作步骤。文章以 docs/recovery/uninstalling.md 为主体结合 cmd/bd/reset.go 与 cmd/bd/hooks.go 的源码实现说明每条命令背后的删除判定逻辑与安全边界。读完你既能安全卸载也能理解为什么有些文件 Beads 会故意不删。卸载前必读数据是删了就拿不回来的Beads 把本地数据放在仓库的.beads/目录中其中核心是本地 Dolt 数据库。bd admin reset会永久删除.beads/这一步没有回收站。用 Dolt 原生备份保命如果 issue 历史对你重要先用 Dolt 原生备份bd backup init /path/to/beads-backup bd backup syncbd backup init在指定路径初始化备份存储bd backup sync把当前数据库同步过去相关命令定义见 cmd/bd/backup.go。这是唯一能完整保留数据库状态的备份方式。导出 issue 表格仅用于查看与迁移bd export -o ~/beads-issues-$(date %Y%m%d).jsonlbd export把 issue 以 JSONL 格式写出命令定义见 cmd/bd/export.go便于人工审阅、迁移或与其他系统互操作。但要明确bd export不是可完整恢复的数据库备份。它不保留 Dolt 分支、提交历史、工作集状态working-set state以及其他非 issue 表。首选路径bd admin reset仓库重置在仓库根目录执行bd admin reset默认进入预览dry-run模式只列出将要删除的内容bd admin reset确认预览无误后再真正执行bd admin reset --force从源码看reset命令挂在admin组下cmd/bd/admin.go 中的adminCmd.AddCommand(resetCmd)其--force标志在 cmd/bd/reset.go 中注册注释明确写着Actually perform the reset (required)——也就是说不加--force时绝不执行删除这是刻意的安全设计。--force会移除以下几类 Beads 管理的仓库数据对应 cmd/bd/reset.go 中collectResetItems的收集逻辑.beads/目录数据库、JSONL、配置Beads整文件安装的 Git hooks源码只检查pre-commit、post-merge、pre-push、post-checkout四个名称旧版本遗留的同步分支 worktree位于.git/beads-worktrees/Reset 只删整文件不删你的文件里的 Beads 段落这是bd admin reset与bd hooks uninstall分工的关键reset 按整文件判定归属按整文件删除。如果某个 hook 文件全部内容都是 Beads 生成的reset 直接删掉它如果某个 hook 是你的文件、只是被 Beads 注入了一段受标记管理的代码reset不会删这个文件而是把它的路径列在Left in place保留不动清单里并提示你用bd hooks uninstall移除段落。这个判定逻辑在源码里叫classifyResetHookcmd/bd/reset.go它把 hook 分成三类hookNotOurs没有任何 Beads 溯源标记Beads 从未写过它绝不删除hookBdOwnedBeads 写了整个文件删除正好还原到 Beads 介入前的状态hookUserOwnedWithBdSection用户自己的 hook被注入了 Beads 段落v0.49 的段落标记模型文件属于用户删除会连用户内容一起带走而 reset 没有任何备份可以恢复它只在 Beads 自己顶替过的 hook 上留有.backup。需要注意判定依据是文件内容里的 Beads 标记而不是文件里出现了 beads 这个词。classifyResetHook的注释里记录了曾经的教训旧实现检查前 10 行是否包含子串 beads结果把用户手写、git 跟踪、只是调用bd hooks run的自定义pre-commit也当成了 Beads 安装的 hook 删掉且无法恢复。所以现在判定只看三类标记段落标记# --- BEGIN BEADS INTEGRATIONhookSectionBeginPrefix内联标记# bd (beads)inlineHookMarker版本标记# bd-hooks-version:与# bd-shimhookVersionPrefix/shimVersionPrefix见 cmd/bd/hooks.go而且段落文件的归属判定比安装侧更严格剥离 Beads 段落后如果只剩 shebang 和空行说明 Beads 事实上写了全部内容判为可删但注释也算内容——一个头部注释 Beads 段落的 hook 是你的文件reset 会保留并如实报告isOnlyShebangOrBlankcmd/bd/reset.go。一个值得知道的保护拒绝误删全局目录bd admin reset还有一个内置护栏refuseGlobalBeadsDircmd/bd/reset.go当仓库自身没有.beads/、Beads 向上查找落到用户全局~/.beads时reset 会直接拒绝执行并报错避免本来只想重置一个临时仓库、结果把用户全局 Beads 状态连 hook 一起删了的灾难源码注释记录了 2026-07-21 的真实事故。只有仓库根目录本身是主目录时~/.beads才被当作该仓库自己的目录允许删除。只移除 Hooksbd hooks uninstall想保留 issue 数据、只去掉 Git hooks 时用bd hooks uninstall源码实现cmd/bd/hooks.go的删除逻辑是段落优先、整文件兜底对每个受管 hookpre-commit、post-merge、pre-push、post-checkout、prepare-commit-msg先尝试removeHookSection只剥离BEGIN BEADS INTEGRATION与END BEADS INTEGRATION之间的内容剥离后如果只剩下空内容或孤零零的 shebang#!/usr/bin/env sh/#!/bin/sh才删除整个文件如果没有段落标记但命中版本标记旧版 shim/内联 hook删除文件并在存在hook.backup时把它改回原位恢复完全没有 Beads 标记的 hook 一律不动。这正是文档强调的优先用命令而不是手删因为bd hooks uninstall会保留标记之外你写的所有内容。另外卸载 hook 文件之后命令还会清理 Beads 管理的 git 配置——resetHooksPathIfBeadsManagedcmd/bd/hooks.go 起会取消core.hooksPath仅当它指向.beads/hooks或.beads-hooks时并无条件清除beads.role。这是刻意设计hook 文件都删了就不能让 Beads 管理的配置残留。手工清理bd admin reset不可用时的兜底方案只有当bd admin reset不可用或无法在仓库中运行时才使用手工清理。先停掉本地 Dolt server如果有的话bd dolt stop 2/dev/null || trueHooks删除之前先看清楚这一步刻意没有批处理命令。pre-commit、prepare-commit-msg、post-merge、pre-push、post-checkout都是 git 的标准 hook 名称不是 Beads 保留的名称——任何一个都可能是你自己写的。既然你已经走到手工清理这一步说明bd hooks uninstall无法帮你区分归属了。先列出哪些 hook 存在、Beads 在它们里面留了什么grep -l -e bd-hooks-version: -e bd-shim -e bd (beads) -e BEGIN BEADS INTEGRATION \ .git/hooks/pre-commit .git/hooks/prepare-commit-msg .git/hooks/post-merge \ .git/hooks/pre-push .git/hooks/post-checkout 2/dev/null逐个打开命中的文件依据内容决定整个文件都是 Beads 生成的文件带有# bd-hooks-version:、# bd-shim或# bd (beads)行且除了 shebang 没有别的内容。删除它rm -f .git/hooks/name。你的文件里嵌着 Beads 段落文件中有# --- BEGIN BEADS INTEGRATION ... ---块。这是你的文件。编辑它删掉从BEGIN标记到END标记的所有行保留其余内容文件留在原位。注意标记周围的注释也算你的内容——头部注释 Beads 段落的 hook 依然归你编辑而不是删除。命令没列出来的 hook 无论里面提到什么都归你所有。在注释里提到 beads或者在你的 hook 里调用bd都不改变文件的归属。其余残留# 移除本地 beads 数据库与配置 rm -rf .beads # 移除旧版本遗留的同步分支 worktree rm -rf .git/beads-worktrees git worktree prune.gitattributes如果只包含 Beads 的 merge-driver 配置整个移除如果还有其他项目条目只删掉 Beads 那一行。如果仍有 Beads 相关的 git 配置残留逐个清除git config --unset beads.role 2/dev/null || true git config --unset core.hooksPath 2/dev/null || true git config --unset merge.beads.driver 2/dev/null || true git config --unset merge.beads.name 2/dev/null || true不要跳过core.hooksPath如果它残留着git 会一直去找一个已经不存在的 hooks 目录而 Beads 的 post-checkout 导入可能因此按旧前缀重新创建出.beads/工作区。但先要检查它的值——core.hooksPath不是 Beads 独享的git config --get core.hooksPath如果它指向的是其他 hook 管理器比如 husky 的.husky/_而不是.beads/hooks或.beads-hooks就别动它取消它会把那个工具的 hooks 一起禁用。bd doctor遵守同样的规则不是它设置的 hooks 路径它不会碰。移除bd二进制CLI 是独立二进制按安装方式对应删除# Homebrew brew uninstall beads # Go install rm -f $(which bd) # 手动安装位置 rm -f /usr/local/bin/bd如果单独安装过 MCP 包用当初安装它的工具一并移除MCP 集成相关内容可参考 integrations/beads-mcp。卸载后验证which bd test ! -e .beads bd hooks list 2/dev/null || true git config --get merge.beads.driverwhich bd确认命令已不可见预期无输出test ! -e .beads确认.beads/已不存在bd hooks list确认 hooks 状态如果二进制已删该命令会失败所以加了|| truegit config --get merge.beads.driver预期无输出说明 merge-driver 配置已清除。bd hooks list的实现见 cmd/bd/hooks.go会逐项报告各 hook 的 installed / outdated / missing 状态。以后想重新初始化在仓库里重新初始化 Beadsbd init它会重新创建.beads/工作区并重新安装受管 hooks。Beads 的 hook 采用段落标记模型# --- BEGIN/END BEADS INTEGRATION与你自己的 hook 内容可以共存——这正是卸载与重装都能做到只动 Beads 的部分、不动你的部分的根本原因。小结场景推荐命令行为删除整个仓库的 Beads 数据bd admin reset先预览→bd admin reset --force删.beads/、Beads 整文件安装的 hooks、.git/beads-worktrees/你的文件保留并报告保留数据、只去 hooksbd hooks uninstall只剥离 Beads 段落保留标记外的用户内容并清理 Beads 管理的 git 配置reset 不可用手工清理按 grep 结果逐文件判断归属后处理注意core.hooksPath是否属于其他工具卸载二进制brew uninstall beads/rm -f $(which bd)按安装方式对应再次使用bd init重新初始化无论走哪条路径记住两条底线删除.beads/等于永久删除本地 Dolt 数据库先做bd backup initbd backup sync而这个 hook 是不是 Beads 的只看文件里的受管标记不看文件里有没有提到 beads 这个词。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Beads 完全卸载指南：从 `bd admin reset` 到手工清理与数据备份
Beads 完全卸载指南从bd admin reset到手工清理与数据备份【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads本指南围绕 Beadsbd在仓库中的卸载全流程展开无论你是想从单个仓库中移除 Beads 数据与 Git hooks还是想彻底从机器上删除bd二进制都能在这里找到可复现的操作步骤。文章以 docs/recovery/uninstalling.md 为主体结合 cmd/bd/reset.go 与 cmd/bd/hooks.go 的源码实现说明每条命令背后的删除判定逻辑与安全边界。读完你既能安全卸载也能理解为什么有些文件 Beads 会故意不删。卸载前必读数据是删了就拿不回来的Beads 把本地数据放在仓库的.beads/目录中其中核心是本地 Dolt 数据库。bd admin reset会永久删除.beads/这一步没有回收站。用 Dolt 原生备份保命如果 issue 历史对你重要先用 Dolt 原生备份bd backup init /path/to/beads-backup bd backup syncbd backup init在指定路径初始化备份存储bd backup sync把当前数据库同步过去相关命令定义见 cmd/bd/backup.go。这是唯一能完整保留数据库状态的备份方式。导出 issue 表格仅用于查看与迁移bd export -o ~/beads-issues-$(date %Y%m%d).jsonlbd export把 issue 以 JSONL 格式写出命令定义见 cmd/bd/export.go便于人工审阅、迁移或与其他系统互操作。但要明确bd export不是可完整恢复的数据库备份。它不保留 Dolt 分支、提交历史、工作集状态working-set state以及其他非 issue 表。首选路径bd admin reset仓库重置在仓库根目录执行bd admin reset默认进入预览dry-run模式只列出将要删除的内容bd admin reset确认预览无误后再真正执行bd admin reset --force从源码看reset命令挂在admin组下cmd/bd/admin.go 中的adminCmd.AddCommand(resetCmd)其--force标志在 cmd/bd/reset.go 中注册注释明确写着Actually perform the reset (required)——也就是说不加--force时绝不执行删除这是刻意的安全设计。--force会移除以下几类 Beads 管理的仓库数据对应 cmd/bd/reset.go 中collectResetItems的收集逻辑.beads/目录数据库、JSONL、配置Beads整文件安装的 Git hooks源码只检查pre-commit、post-merge、pre-push、post-checkout四个名称旧版本遗留的同步分支 worktree位于.git/beads-worktrees/Reset 只删整文件不删你的文件里的 Beads 段落这是bd admin reset与bd hooks uninstall分工的关键reset 按整文件判定归属按整文件删除。如果某个 hook 文件全部内容都是 Beads 生成的reset 直接删掉它如果某个 hook 是你的文件、只是被 Beads 注入了一段受标记管理的代码reset不会删这个文件而是把它的路径列在Left in place保留不动清单里并提示你用bd hooks uninstall移除段落。这个判定逻辑在源码里叫classifyResetHookcmd/bd/reset.go它把 hook 分成三类hookNotOurs没有任何 Beads 溯源标记Beads 从未写过它绝不删除hookBdOwnedBeads 写了整个文件删除正好还原到 Beads 介入前的状态hookUserOwnedWithBdSection用户自己的 hook被注入了 Beads 段落v0.49 的段落标记模型文件属于用户删除会连用户内容一起带走而 reset 没有任何备份可以恢复它只在 Beads 自己顶替过的 hook 上留有.backup。需要注意判定依据是文件内容里的 Beads 标记而不是文件里出现了 beads 这个词。classifyResetHook的注释里记录了曾经的教训旧实现检查前 10 行是否包含子串 beads结果把用户手写、git 跟踪、只是调用bd hooks run的自定义pre-commit也当成了 Beads 安装的 hook 删掉且无法恢复。所以现在判定只看三类标记段落标记# --- BEGIN BEADS INTEGRATIONhookSectionBeginPrefix内联标记# bd (beads)inlineHookMarker版本标记# bd-hooks-version:与# bd-shimhookVersionPrefix/shimVersionPrefix见 cmd/bd/hooks.go而且段落文件的归属判定比安装侧更严格剥离 Beads 段落后如果只剩 shebang 和空行说明 Beads 事实上写了全部内容判为可删但注释也算内容——一个头部注释 Beads 段落的 hook 是你的文件reset 会保留并如实报告isOnlyShebangOrBlankcmd/bd/reset.go。一个值得知道的保护拒绝误删全局目录bd admin reset还有一个内置护栏refuseGlobalBeadsDircmd/bd/reset.go当仓库自身没有.beads/、Beads 向上查找落到用户全局~/.beads时reset 会直接拒绝执行并报错避免本来只想重置一个临时仓库、结果把用户全局 Beads 状态连 hook 一起删了的灾难源码注释记录了 2026-07-21 的真实事故。只有仓库根目录本身是主目录时~/.beads才被当作该仓库自己的目录允许删除。只移除 Hooksbd hooks uninstall想保留 issue 数据、只去掉 Git hooks 时用bd hooks uninstall源码实现cmd/bd/hooks.go的删除逻辑是段落优先、整文件兜底对每个受管 hookpre-commit、post-merge、pre-push、post-checkout、prepare-commit-msg先尝试removeHookSection只剥离BEGIN BEADS INTEGRATION与END BEADS INTEGRATION之间的内容剥离后如果只剩下空内容或孤零零的 shebang#!/usr/bin/env sh/#!/bin/sh才删除整个文件如果没有段落标记但命中版本标记旧版 shim/内联 hook删除文件并在存在hook.backup时把它改回原位恢复完全没有 Beads 标记的 hook 一律不动。这正是文档强调的优先用命令而不是手删因为bd hooks uninstall会保留标记之外你写的所有内容。另外卸载 hook 文件之后命令还会清理 Beads 管理的 git 配置——resetHooksPathIfBeadsManagedcmd/bd/hooks.go 起会取消core.hooksPath仅当它指向.beads/hooks或.beads-hooks时并无条件清除beads.role。这是刻意设计hook 文件都删了就不能让 Beads 管理的配置残留。手工清理bd admin reset不可用时的兜底方案只有当bd admin reset不可用或无法在仓库中运行时才使用手工清理。先停掉本地 Dolt server如果有的话bd dolt stop 2/dev/null || trueHooks删除之前先看清楚这一步刻意没有批处理命令。pre-commit、prepare-commit-msg、post-merge、pre-push、post-checkout都是 git 的标准 hook 名称不是 Beads 保留的名称——任何一个都可能是你自己写的。既然你已经走到手工清理这一步说明bd hooks uninstall无法帮你区分归属了。先列出哪些 hook 存在、Beads 在它们里面留了什么grep -l -e bd-hooks-version: -e bd-shim -e bd (beads) -e BEGIN BEADS INTEGRATION \ .git/hooks/pre-commit .git/hooks/prepare-commit-msg .git/hooks/post-merge \ .git/hooks/pre-push .git/hooks/post-checkout 2/dev/null逐个打开命中的文件依据内容决定整个文件都是 Beads 生成的文件带有# bd-hooks-version:、# bd-shim或# bd (beads)行且除了 shebang 没有别的内容。删除它rm -f .git/hooks/name。你的文件里嵌着 Beads 段落文件中有# --- BEGIN BEADS INTEGRATION ... ---块。这是你的文件。编辑它删掉从BEGIN标记到END标记的所有行保留其余内容文件留在原位。注意标记周围的注释也算你的内容——头部注释 Beads 段落的 hook 依然归你编辑而不是删除。命令没列出来的 hook 无论里面提到什么都归你所有。在注释里提到 beads或者在你的 hook 里调用bd都不改变文件的归属。其余残留# 移除本地 beads 数据库与配置 rm -rf .beads # 移除旧版本遗留的同步分支 worktree rm -rf .git/beads-worktrees git worktree prune.gitattributes如果只包含 Beads 的 merge-driver 配置整个移除如果还有其他项目条目只删掉 Beads 那一行。如果仍有 Beads 相关的 git 配置残留逐个清除git config --unset beads.role 2/dev/null || true git config --unset core.hooksPath 2/dev/null || true git config --unset merge.beads.driver 2/dev/null || true git config --unset merge.beads.name 2/dev/null || true不要跳过core.hooksPath如果它残留着git 会一直去找一个已经不存在的 hooks 目录而 Beads 的 post-checkout 导入可能因此按旧前缀重新创建出.beads/工作区。但先要检查它的值——core.hooksPath不是 Beads 独享的git config --get core.hooksPath如果它指向的是其他 hook 管理器比如 husky 的.husky/_而不是.beads/hooks或.beads-hooks就别动它取消它会把那个工具的 hooks 一起禁用。bd doctor遵守同样的规则不是它设置的 hooks 路径它不会碰。移除bd二进制CLI 是独立二进制按安装方式对应删除# Homebrew brew uninstall beads # Go install rm -f $(which bd) # 手动安装位置 rm -f /usr/local/bin/bd如果单独安装过 MCP 包用当初安装它的工具一并移除MCP 集成相关内容可参考 integrations/beads-mcp。卸载后验证which bd test ! -e .beads bd hooks list 2/dev/null || true git config --get merge.beads.driverwhich bd确认命令已不可见预期无输出test ! -e .beads确认.beads/已不存在bd hooks list确认 hooks 状态如果二进制已删该命令会失败所以加了|| truegit config --get merge.beads.driver预期无输出说明 merge-driver 配置已清除。bd hooks list的实现见 cmd/bd/hooks.go会逐项报告各 hook 的 installed / outdated / missing 状态。以后想重新初始化在仓库里重新初始化 Beadsbd init它会重新创建.beads/工作区并重新安装受管 hooks。Beads 的 hook 采用段落标记模型# --- BEGIN/END BEADS INTEGRATION与你自己的 hook 内容可以共存——这正是卸载与重装都能做到只动 Beads 的部分、不动你的部分的根本原因。小结场景推荐命令行为删除整个仓库的 Beads 数据bd admin reset先预览→bd admin reset --force删.beads/、Beads 整文件安装的 hooks、.git/beads-worktrees/你的文件保留并报告保留数据、只去 hooksbd hooks uninstall只剥离 Beads 段落保留标记外的用户内容并清理 Beads 管理的 git 配置reset 不可用手工清理按 grep 结果逐文件判断归属后处理注意core.hooksPath是否属于其他工具卸载二进制brew uninstall beads/rm -f $(which bd)按安装方式对应再次使用bd init重新初始化无论走哪条路径记住两条底线删除.beads/等于永久删除本地 Dolt 数据库先做bd backup initbd backup sync而这个 hook 是不是 Beads 的只看文件里的受管标记不看文件里有没有提到 beads 这个词。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考