fix(reset): a comment is content when the question is deletion (follow-up to #5221) (#5227)

* fix(reset): a comment is content when the question is deletion

GH#5221 stopped `bd admin reset` from deleting hooks it never installed, but
left one path open. classifyResetHook decides a sectioned hook by stripping
bd's block and asking isOnlyShebangOrEmpty whether anything remains — and that
predicate, by its own documented design, treats every comment as nothing.

So a hook of the user's whose own content is a shebang plus comments — a header
they wrote, a note to whoever edits it next, a lint step they commented out for
now — strips to "empty", classifies hookBdOwned, and is deleted whole. There is
nothing to restore it from: performReset renames <hook>.backup back into place,
and a backup exists only for hooks bd itself displaced, which is never the case
for a hook bd only injected a section into. A comment was once again enough to
make a hook bd's to delete, which is the failure GH#5221 exists to close.

The looser predicate is right where it lives. shouldPreserveHookContent is
deciding whether to COPY a hook forward into .beads/hooks, and declining to
carry a comment-only file loses a comment out of a file that still exists on
disk (GH#3536). Reset is deciding whether to DESTROY the file. The two
questions differ in what being wrong costs, so they no longer share an answer:
isOnlyShebangOrBlank counts only the leading shebang and blank lines as
nothing. It anchors the shebang on the first non-blank line rather than on
index 0, so it does not depend on whether stripping bd's section left a blank
line above it, and a second `#!` further down is read as the comment it is.

The divergence is deliberate and one-way, so both tests that could hide it now
say so. TestClassifyResetHook_AgreesWithHookPreservation keeps the arm that
matters — what preservation calls the user's, reset must not delete — and
replaces its converse with the weaker claim that still needs pinning: reset may
never call a marker-carrying file none of bd's business, or a hook bd wrote
survives a reset unremoved and unreported. TestResetEmptinessPredicateIsStricter
ThanPreservation pins the gap between the two predicates directly, so a later
cleanup that notices they answer "the same" question and collapses them into
one fails here instead of quietly restoring the deletion.

Verified the fix is load-bearing: pointed classifyResetHook back at the old
predicate and the three new cases fail (both classify cases, and the
collectResetItems case in both directions — removed when it should be kept,
absent from the preserved report when it should be named).

Agent-Signature: claude-opus-5-high on behalf of maphew

* docs(uninstall): stop handing out an rm -f batch under a "check first" warning

GH#5221 added a warning above the manual-cleanup hook deletions telling the
reader that these are the standard git hook names, that any of them may be a
hook they wrote, and to check each file before deleting it. It then left the
five unconditional `rm -f .git/hooks/<name>` lines directly beneath it, inside
the same copy-pasteable fence.

A warning that is followed, in the same block, by the commands that do the
thing it warns about is not a safeguard. Anyone treating the fence the way
fences in this document are meant to be treated deletes all five hooks and
reads the reason afterwards. Someone in this section has already lost the
command that could tell the difference for them.

So the hook step is no longer a batch. A read-only grep lists which of the five
exist and which carry a beads marker, and the disposition is then per file:
delete the ones beads generated whole, edit the block out of the ones that are
yours, leave the rest. `rm -f .git/hooks/<name>` appears once, with a
placeholder, in a sentence about a file the reader has just opened.

The per-file rules are the ones the code applies, including the case the
accompanying commit fixes: a hook that is your header comment plus beads'
block is yours to edit, not beads' to delete.

`bd dolt stop` and the `.beads` / worktree removals stay executable; those are
beads' own state, not files that might be the user's.

Agent-Signature: claude-opus-5-high on behalf of maphew
This commit is contained in:
matt wilkie 2026-08-01 03:04:55 -07:00 • committed by GitHub
commit 2c0f92318e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 164 additions and 27 deletions

View file

@ -190,9 +190,10 @@ func classifyResetHook(hookPath string) hookOwnership {
// Order matters, and matches shouldPreserveHookContent: a sectioned file is
// user-owned unless stripping bd's block leaves nothing but a shebang, in
// which case bd effectively wrote all of it.
// which case bd effectively wrote all of it. What counts as "nothing" is
// where the two part company — see isOnlyShebangOrBlank.
if strings.Contains(content, hookSectionBeginPrefix) {
if stripped, _ := removeHookSection(content); isOnlyShebangOrEmpty(stripped) {
if stripped, _ := removeHookSection(content); isOnlyShebangOrBlank(stripped) {
return hookBdOwned
}
return hookUserOwnedWithBdSection
@ -205,6 +206,47 @@ func classifyResetHook(hookPath string) hookOwnership {
return hookNotOurs
}
// isOnlyShebangOrBlank reports whether what is left of a hook after bd's
// section is stripped is nothing but an optional shebang and blank lines.
// Comments count as content.
//
// This is deliberately stricter than isOnlyShebangOrEmpty (hooks.go), which
// answers the same shape of question for shouldPreserveHookContent and treats
// comments as nothing (GH#3536). The two callers are not symmetric and must not
// share a predicate:
//
// - Preservation copies a hook forward into .beads/hooks. Declining to copy a
// comment-only file loses a comment; the original is still on disk.
// - Reset deletes. Getting it wrong destroys the user's file, and
// performReset cannot undo it — its restore path renames <hook>.backup back
// into place, and a backup exists only for hooks bd itself displaced, which
// is never the case for a hook bd only injected a section into.
//
// So a hook of the user's whose own content is a shebang and comments — a
// header they wrote, a note to whoever edits it next, hook logic they commented
// out for now — is theirs. Reset leaves it and says so. Sharing the looser
// predicate meant a comment was once again enough to make a hook bd's to
// delete, which is the failure classifyResetHook exists to close.
func isOnlyShebangOrBlank(content string) bool {
seenContent := false
for _, line := range strings.Split(content, "\n") {
trimmed := strings.TrimSpace(line)
if trimmed == "" {
continue
}
// Only the leading line can be a shebang; `#!` below it is a comment,
// and comments are content here. Anchoring on the first non-blank line
// rather than index 0 keeps this from depending on whether stripping
// bd's section left a blank line above the shebang.
if !seenContent && strings.HasPrefix(trimmed, "#!") {
seenContent = true
continue
}
return false
}
return true
}
func showResetPreview(items, preserved []resetItem) error {
if jsonOutput {
result := map[string]interface{}{

View file

@ -63,6 +63,27 @@ func TestClassifyResetHook(t *testing.T) {
content: "#!/bin/sh\nset -e\n./scripts/lint\n\n" + section,
want: hookUserOwnedWithBdSection,
},
{
// The user's own file: a header they wrote and a note to whoever
// edits it next, with bd's block injected below. Stripping the block
// leaves only comments, which shouldPreserveHookContent is entitled
// to call nothing — it is deciding whether to COPY the file forward.
// Reset is deciding whether to DELETE it, and has no backup to
// restore, so comments are content here.
name: "user hook whose own content is only comments",
content: "#!/bin/sh\n" +
"# pre-commit — team hook.\n" +
"# TODO(ana): re-enable the lint step once CI stops flaking.\n" +
"# ./scripts/lint\n\n" + section,
want: hookUserOwnedWithBdSection,
},
{
// Same shape, but the comment sits below bd's section rather than
// above it: position must not decide whether the file is the user's.
name: "user comment below bd's section",
content: "#!/bin/sh\n" + section + "\n# leave this hook alone, see docs/hooks.md\n",
want: hookUserOwnedWithBdSection,
},
{
// The regression. No bd marker anywhere; "beads" appears only in a
// comment and in a call to bd, both of which the old first-ten-lines
@ -104,17 +125,24 @@ func TestClassifyResetHook_MissingFileIsNotOurs(t *testing.T) {
// Two functions decide, separately, whether a hook file holds anything of the
// user's: shouldPreserveHookContent when bd migrates hooks into .beads/hooks,
// and classifyResetHook when bd is about to delete them. They have to give the
// same answer. If preservation would carry content forward, that content is the
// user's and reset must not remove the file; if preservation discards the file
// as wholly bd-managed, reset may.
// and classifyResetHook when bd is about to delete them. They must not drift
// into disagreement, but the agreement they owe each other is one-way, because
// the cost of being wrong is not symmetric:
//
// Drift between them is not a tidiness problem — it is deletion without a
// restore path, since performReset only renames <hook>.backup back into place
// and a backup exists only for hooks bd itself displaced.
// - Preservation copying too little loses a comment out of a file that still
// exists on disk.
// - Reset deleting too much destroys the user's hook with no way back —
// performReset only renames <hook>.backup into place, and a backup exists
// only for hooks bd itself displaced.
//
// So the invariant is: whatever preservation treats as the user's, reset must
// keep; and reset may additionally keep files preservation was willing to drop
// (a hook whose own content is only comments is the case that differs). What
// reset may never do is call a marker-carrying file none of bd's business —
// that would leave a hook bd wrote installed after a reset claimed to remove it.
//
// This runs over the repository's own tracked .githooks rather than fixtures,
// so the inputs are hooks a person actually composed. It asserts the agreement,
// so the inputs are hooks a person actually composed. It asserts the invariant,
// not a hardcoded verdict per file, so editing those hooks cannot make it lie.
func TestClassifyResetHook_AgreesWithHookPreservation(t *testing.T) {
for _, name := range managedHookNames {
@ -131,9 +159,46 @@ func TestClassifyResetHook_AgreesWithHookPreservation(t *testing.T) {
t.Errorf("classifyResetHook(%s) = hookBdOwned, but shouldPreserveHookContent keeps this file: "+
"reset would delete content bd itself considers the user's, with no backup to restore", path)
}
if !wouldPreserve && got != hookBdOwned {
t.Errorf("classifyResetHook(%s) = %v, but shouldPreserveHookContent discards this file as wholly "+
"bd-managed: reset would leave behind a hook bd wrote", path, got)
if !wouldPreserve && got == hookNotOurs {
t.Errorf("classifyResetHook(%s) = hookNotOurs, but shouldPreserveHookContent discards this file as "+
"wholly bd-managed: a hook bd wrote would survive a reset unremoved and unreported", path)
}
})
}
}
// The divergence between the two emptiness predicates is the fix, so pin it.
// A later cleanup that notices they answer "the same" question and collapses
// them into one has to fail here rather than quietly restore the deletion.
func TestResetEmptinessPredicateIsStricterThanPreservation(t *testing.T) {
tests := []struct {
name string
content string
preservationSees bool // isOnlyShebangOrEmpty: comments are nothing
resetSees bool // isOnlyShebangOrBlank: comments are content
}{
{"empty", "", true, true},
{"shebang only", "#!/bin/sh\n", true, true},
{"shebang and blank lines", "#!/bin/sh\n\n\n", true, true},
{"shebang and a comment", "#!/bin/sh\n# team hook, see docs/hooks.md\n", true, false},
{"comment with no shebang", "# nothing here yet\n", true, false},
{"commented-out logic", "#!/bin/sh\n# ./scripts/lint\n", true, false},
{"real logic", "#!/bin/sh\n./scripts/lint\n", false, false},
{"shebang below a blank line", "\n#!/bin/sh\n", true, true},
{"second #! is a comment, not a shebang", "#!/bin/sh\n#!/bin/false\n", true, false},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := isOnlyShebangOrEmpty(tt.content); got != tt.preservationSees {
t.Errorf("isOnlyShebangOrEmpty(%q) = %v, want %v", tt.content, got, tt.preservationSees)
}
if got := isOnlyShebangOrBlank(tt.content); got != tt.resetSees {
t.Errorf("isOnlyShebangOrBlank(%q) = %v, want %v", tt.content, got, tt.resetSees)
}
if tt.resetSees && !tt.preservationSees {
t.Errorf("%q: reset's predicate must never call empty what preservation calls content — "+
"that is the direction that deletes", tt.content)
}
})
}
@ -147,6 +212,7 @@ func TestCollectResetItems_OnlyRemovesHooksBdOwns(t *testing.T) {
bdOwned := writeHook(t, hooksDir, "post-merge", "#!/bin/sh\n# bd-hooks-version: 0.40.0\n# bd (beads) post-merge hook\nbd import\n")
sectioned := writeHook(t, hooksDir, "pre-commit", "#!/bin/sh\nset -e\n./scripts/lint\n\n"+generateHookSection("pre-commit"))
foreign := writeHook(t, hooksDir, "pre-push", composedForeignHook)
commentOnly := writeHook(t, hooksDir, "post-checkout", "#!/bin/sh\n# post-checkout — ours; bd's block was added below.\n\n"+generateHookSection("post-checkout"))
items, preserved := collectResetItems(gitCommonDir, beadsDir)
@ -171,6 +237,13 @@ func TestCollectResetItems_OnlyRemovesHooksBdOwns(t *testing.T) {
if inItems[foreign] || inPreserved[foreign] {
t.Errorf("hook %s carries no bd marker; it is neither ours to remove nor ours to mention", foreign)
}
if inItems[commentOnly] {
t.Errorf("hook %s is the user's file — everything outside bd's section is a comment they wrote, "+
"and reset has no backup to restore it from", commentOnly)
}
if !inPreserved[commentOnly] {
t.Errorf("hook %s should be reported as left in place, not silently ignored", commentOnly)
}
// The .beads directory is always in the removal list — that is the point of
// the command, and this pins that the hook change did not disturb it.

View file

@ -68,24 +68,46 @@ unrelated user hook content outside its managed hook markers.
Use manual cleanup only if `bd admin reset` is unavailable or cannot run in
the repository.
Start by stopping a local Dolt server, if one is running:
```bash
# Stop a local Dolt server if one is running.
bd dolt stop 2>/dev/null || true
```
# Remove beads-managed hooks when bd hooks uninstall is unavailable.
#
# Check each file before deleting it. These are the standard git hook names,
# not names beads reserves, so any of them may be a hook you wrote. Delete
# only the ones whose entire content beads generated — they carry a
# "# bd-hooks-version:", "# bd-shim", or "# bd (beads)" line. A hook of yours
# with a "# --- BEGIN BEADS INTEGRATION ... ---" block in it should be edited,
# removing the block between the BEGIN and END markers and keeping the rest.
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
### Hooks: look before you delete
There is no batch command for this step, deliberately. `pre-commit`,
`prepare-commit-msg`, `post-merge`, `pre-push` and `post-checkout` are the
standard git hook names, not names beads reserves, so any of them may be a hook
you wrote — and if you are reading this section, `bd hooks uninstall` was not
available to tell the difference for you.
List which of them exist and what beads left in them:
```bash
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
```
Open each file that matched and decide from what is in it:
- A file whose **whole content** beads generated carries a
`# bd-hooks-version:`, `# bd-shim`, or `# bd (beads)` line and has nothing
else in it but the shebang. Delete that one: `rm -f .git/hooks/<name>`.
- A file of yours with a `# --- BEGIN BEADS INTEGRATION ... ---` block in it is
**your** file. Edit it: remove the lines from the `BEGIN` marker to the `END`
marker, keep the rest, and leave the file in place. Comments of yours around
the block count — a hook that is a header comment plus beads' block is still
yours to edit rather than delete.
Hooks the command did not list are yours regardless of what they mention.
Naming beads in a comment, or calling `bd` from a hook you composed, does not
make the file beads'.
### The rest
```bash
# Remove the local beads database and config.
rm -rf .beads