sprawl ignore

Workspace & DNA

Fingerprints workspace technology stacks, diagnoses exposed build caches/secrets on disk, harvests legacy custom ignore rules, and compiles deterministic 2-tier ignore shields across .agentignore, .ignore, and bound IDE ignore files.


📌 1. The Target Problem

1. The Target Problem

"How do I stop Cursor, Claude Code, Windsurf, RooCode, Cline, JetBrains AI, Gemini CLI, Aider, OpenCode, and Antigravity from indexing `node_modules/`, `.venv/`, build caches, or secrets without polluting my repository root with unused IDE ignore files or losing custom rules?"

Every AI coding assistant reads its own ignore file (.cursorignore, .claudeignore, .codeiumignore, .windsurfignore, .rooignore, .clineignore, .geminiignore, .aiignore, .aiderignore, .agentignore, or ripgrep's .ignore). Generating all eleven files blindly clutters workspaces that only use one or two editors, while maintaining them manually leads to drift, leaked .env secrets, and severe context token inflation.


⚙️ 2. Usage & Options

# Run directly inside your workspace directory (defaults to current working directory)
sprawl ignore
sprawl ignore [detect|sync|check] [DIR] [--path DIR] [--all]

Subcommands & Flags

  • sync (default): Fingerprints active workspace stacks, harvests custom rules across any pre-existing ignore files into .agentignore, and synchronizes the 2 base files (.agentignore, .ignore) plus any bound or pre-existing IDE ignore files.
  • detect: Scans the workspace root for technology markers, explains why each stack profile matched, and lists which actual bloat or sensitive folders (.venv, node_modules, .env, .obsidian, 99_Archive) currently exist on disk without modifying files.
  • check: Read-only CI/CD drift gate. Verifies all active ignore targets match the canonical stack shield and explains the exact reason for any drift (missing file, unmanaged legacy file, or out-of-sync stack rules); exits with code 1 on drift.
  • [DIR] / --path DIR: Optional target workspace directory passed positionally (sprawl ignore ./my-repo or sprawl ignore check ./my-repo) or via --path (defaults to the current working directory).
  • --all: Synchronizes all 11 supported ignore targets (.agentignore, .ignore, .cursorignore, .claudeignore, .codeiumignore, .windsurfignore, .rooignore, .clineignore, .geminiignore, .aiignore, .aiderignore) regardless of active bindings in .agents/sprawl_manifest.yml.
  • --dry-run: Simulates ignore shield synchronization without writing to disk.
  • --json: Emits structured JSON output for CI pipelines and telemetry.

🔍 3. How it Works (Under the Hood)

  1. Pure Stack Fingerprinting & Bloat Diagnosis (src/sprawl/analyzers/stack.py): Scans root workspace filenames against declarative stack markers (pyproject.toml, package.json, Cargo.toml, go.mod, manifest.md, Dockerfile) in <1ms and identifies which matching bloat/secret paths exist in the repository root right now.
  2. 2-Tier Target Resolution (src/sprawl/generators/ignore.py):
  • Tier 1 (Always-On Base): .agentignore (canonical SSoT for sprawl-workspace-fs and Google Antigravity) and .ignore (universal ripgrep / fd shield natively consumed by OpenCode, OpenAI Codex CLI, Zed, and VS Code search).
  • Tier 2 (Bound or Pre-Existing IDEs): Reads bindings from .agents/sprawl_manifest.yml (cursor -> .cursorignore, claude-code -> .claudeignore, windsurf -> .codeiumignore + .windsurfignore, cline-roo -> .rooignore + .clineignore, gemini-cli -> .geminiignore, intellij -> .aiignore, aider -> .aiderignore) and includes any ignore file already present on disk. Passing --all forces all 11 targets.
  1. Cross-File Custom Rule Harvesting (sprawl ignore & sprawl graft): Before writing targets, Sprawl inspects all existing ignore files in the workspace, extracts custom rules (or migrates unmanaged legacy files), and unions/deduplicates them below # === CUSTOM WORKSPACE IGNORES ===. Running sprawl graft automatically triggers this harvest so zero legacy rules are ever lost.

🩺 4. Troubleshooting

  • sprawl ignore check exits with code 1 in CI
  • Resolution: Inspect the Details / What Changed column in the sprawl ignore check table (for example, missing on disk, unmanaged file: missing Sprawl shield header, or out of sync: managed block differs). Run sprawl ignore locally and commit the updated ignore files.
  • Why didn't sprawl ignore create .cursorignore or .windsurfignore?
  • Resolution: By default, sprawl ignore only generates .agentignore and .ignore plus adapters listed under bindings: in .agents/sprawl_manifest.yml. Bind your editor via sprawl bind or pass sprawl ignore --all to generate all 11 files.

🔗 Related Resources & Tutorials