gastownhall/beads · error

failed to back up %s before injecting bd section: %w

Error message

failed to back up %s before injecting bd section: %w

What it means

When bd must inject its section into a foreign hook it does not own, it first saves a one-time .backup copy of the original (bd-5vdt8). If writing that .backup file fails, the install aborts rather than modify the hook without a backup. The underlying OS write error is wrapped in %w.

Source

Thrown at cmd/bd/hooks.go:960

			// Check if file already has section markers
			if strings.Contains(existingStr, hookSectionBeginPrefix) {
				// Update only the section between markers
				newContent = injectHookSection(existingStr, section)
			} else {
				// Check if this is a legacy bd hook (shim or inline)
				versionInfo, _ := getHookVersion(hookPath)
				if versionInfo.IsBdHook {
					// Legacy bd hook — replace entire file with section format
					newContent = "#!/usr/bin/env sh\n" + section
				} else {
					// Non-bd hook — this is the one write that modifies a file
					// bd does not own. Preserve the original as a one-time
					// .backup sidecar before injecting (bd-5vdt8).
					backupPath := hookPath + ".backup"
					if _, statErr := os.Lstat(backupPath); os.IsNotExist(statErr) {
						// #nosec G306 -- keep executable so a rename restores a working hook
						if backupErr := os.WriteFile(backupPath, existing, 0755); backupErr != nil {
							return fmt.Errorf("failed to back up %s before injecting bd section: %w", hookName, backupErr)
						}
					}
					// Inject section, preserving existing content
					newContent = injectHookSection(existingStr, section)
				}
			}
		}

		// Normalize line endings to LF
		newContent = strings.ReplaceAll(newContent, "\r\n", "\n")

		// Write hook file
		// #nosec G306 -- git hooks must be executable for Git to run them
		if err := os.WriteFile(hookPath, []byte(newContent), 0755); err != nil {
			return fmt.Errorf("failed to write %s: %w", hookName, err)
		}
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Fix write permission on the hooks directory (chown/chmod) and re-run
2. Remove any `<hook>.backup` entry that is a directory or otherwise unwritable
3. Free disk space if the filesystem is full, then re-run

Example fix

// before
$ ls -ld .git/hooks  # drwxr-xr-x root
// after
$ sudo chown -R $(whoami) .git/hooks && bd hooks install

[ -w "$(dirname "$hook")" ] || echo "hooks dir not writable; .backup would fail"

if err := installHooks(...); err != nil { if strings.Contains(err.Error(), "back up") { /* restore writability or clear blocking .backup path, then retry */ } }

When it happens

Trigger: installHooksWithOptions detects a foreign (non-bd) hook with content, attempts os.WriteFile(hookPath+".backup", existing, 0755), and the write fails — typically because the hooks directory is not writable.

Common situations: Read-only or root-owned .git/hooks directory; disk full; a directory named `<hook>.backup` already exists; immutable file attribute set.

Related errors

• failed to create backup directory: %w
• failed to create backup file: %w
• dolt path is not executable
• failed to create backup dir in git-repo: %w
• failed to read backup state: %w

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/4a4e079986821530. Report an issue: GitHub.