gastownhall/beads · error

ensure .beads/.gitignore: %w

Error message

ensure .beads/.gitignore: %w

What it means

This error wraps a failure from os.WriteFile when EnsureGitignoreForBeadsDir tries to rewrite .beads/.gitignore with the required runtime patterns appended. bd appends a '# Added by bd (missing required patterns)' section and each missing pattern, writing with 0600 permissions. If the write fails (permissions, disk space, I/O), the ensure operation aborts with this wrapped error.

Source

Thrown at cmd/bd/doctor/gitignore.go:217

			if err := os.Chmod(gitignorePath, 0600); err != nil {
				return fmt.Errorf("chmod .beads/.gitignore: %w", err)
			}
		}
	}

	existingContent := string(content)
	newContent := existingContent
	if len(newContent) > 0 && !strings.HasSuffix(newContent, "\n") {
		newContent += "\n"
	}

	newContent += "\n# Added by bd (missing required patterns)\n"
	for _, pattern := range missing {
		newContent += pattern + "\n"
	}

	if err := os.WriteFile(gitignorePath, []byte(newContent), 0600); err != nil {
		return fmt.Errorf("ensure .beads/.gitignore: %w", err)
	}

	// Tighten permissions on pre-existing files: os.WriteFile's mode argument
	// only applies at creation, and the file may predate the 0600 policy.
	if err := os.Chmod(gitignorePath, 0600); err != nil {
		return fmt.Errorf("chmod .beads/.gitignore: %w", err)
	}

	return nil
}

// FixGitignore brings .beads/.gitignore up to date: the full template when
// the file is missing, append-only for missing required patterns otherwise.
// It must never rewrite an existing file wholesale — local rules (e.g.
// keep-exports-off-master negations) live in this file too, and the old
// full-template rewrite destroyed them (bd-kaaz3).
// If a redirect exists, it writes to the redirect target's .gitignore instead.
// repoPath is the project root directory.

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify the directory is writable: `ls -ld .beads` and `test -w .beads/.gitignore || chmod u+w .beads/.gitignore`
2. Check disk space/quota (`df -h .`) and free space if the write failed with ENOSPC
3. If the file is immutable, remove the flag: `sudo chattr -i .beads/.gitignore`
4. Run bd as the file owner (avoid sudo-then-user mismatches) and re-run `bd doctor --fix`

Example fix

// before: read-only file blocks WriteFile
-r--r--r-- .beads/.gitignore
// after
chmod u+w .beads/.gitignore && bd doctor --fix

import { statSync, accessSync, constants } from 'node:fs';
try {
  accessSync('.beads', constants.W_OK);
  accessSync('.beads/.gitignore', constants.W_OK);
} catch {
  console.error('.beads/.gitignore not writable; fix permissions/disk before bd doctor --fix');
  process.exit(1);
}

When it happens

Trigger: EnsureGitignoreForBeadsDir computes missing required patterns and calls os.WriteFile(gitignorePath, []byte(newContent), 0600); WriteFile fails because the directory is not writable, the file is read-only by another user, the disk is full, or an I/O error occurs.

Common situations: Running bd doctor --fix in a repo where .beads/ is root-owned or mounted read-only; quota/disk-full conditions; the file was made immutable (chattr +i); CI runners with locked-down workspaces; antivirus or file locks on Windows intercepting writes.

Related errors

• read .beads/.gitignore: %w
• ensure .beads/.gitignore: %w
• failed to create output file: %w
• scanning artifacts at %s: %w
• unable to read plugin file: %w

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