sprawl ignore
📌 1. The Target Problem
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 code1on drift.[DIR]/--path DIR: Optional target workspace directory passed positionally (sprawl ignore ./my-repoorsprawl 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 activebindingsin.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)
- 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<1msand identifies which matching bloat/secret paths exist in the repository root right now. - 2-Tier Target Resolution (
src/sprawl/generators/ignore.py):
- Tier 1 (Always-On Base):
.agentignore(canonical SSoT forsprawl-workspace-fsand Google Antigravity) and.ignore(universalripgrep/fdshield natively consumed by OpenCode, OpenAI Codex CLI, Zed, and VS Code search). - Tier 2 (Bound or Pre-Existing IDEs): Reads
bindingsfrom.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--allforces all 11 targets.
- 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 ===. Runningsprawl graftautomatically triggers this harvest so zero legacy rules are ever lost.
🩺 4. Troubleshooting
sprawl ignore checkexits with code 1 in CI- Resolution: Inspect the
Details / What Changedcolumn in thesprawl ignore checktable (for example,missing on disk,unmanaged file: missing Sprawl shield header, orout of sync: managed block differs). Runsprawl ignorelocally and commit the updated ignore files. - Why didn't
sprawl ignorecreate.cursorignoreor.windsurfignore? - Resolution: By default,
sprawl ignoreonly generates.agentignoreand.ignoreplus adapters listed underbindings:in.agents/sprawl_manifest.yml. Bind your editor viasprawl bindor passsprawl ignore --allto generate all 11 files.