$ reference
Filtros TOML
~/.boost/filters/ o .boost/filters/ — sin recompilar. Dónde se cargan los filtros
Boost fusiona filtros de varias ubicaciones y aplica cada filtro seleccionado por el comando o la salida. Los archivos dentro de una carpeta se cargan en orden determinista.
- Filtros integrados incluidos con Boost (
make,terraform,shellcheck, …) ~/.boost/filters/*.toml(carpeta global, un filtro por archivo).boost/filters/*.tomlen el proyecto (carpeta, un filtro por archivo)
Las fuentes se fusionan, no se sobrescriben. Un filtro de proyecto no reemplaza un integrado con el mismo nombre — ambos se cargan (nombre + origen), y se aplica cada filtro cuyo match_command o match_output_select coincida, en orden (builtin → global → project). Para reemplazar un integrado, desactívalo con boost filters disable y publica el tuyo.
Disposición de carpetas (un filtro por archivo)
Los filtros personalizados viven en archivos de un solo filtro: cada uno tiene un bloque [filters.<name>] y ejemplos [[tests.<name>]]. Así puedes ajustar un filtro sin tocar los demás.
~/.boost/filters/
git-status.toml # [filters.git-status] + [[tests.git-status]]
my-deploy.toml # [filters.my-deploy] + [[tests.my-deploy]]Los filtros en ~/.boost/filters/ los recoge el siguiente proceso boost sin recompilar.
Selectores y campos comunes
Cada filtro necesita al menos un selector. Estos campos aparecen en casi todos los ejemplos; el glosario completo está al final de la página.
| Campo | Propósito |
|---|---|
| match_command | Select by command line (capture path) |
| match_output_select | Select by piped output signature (hook path); use (?m) for line anchors |
| strip_ansi | Remove terminal color codes first |
| strip_lines_matching | Drop lines matching any pattern |
| keep_lines_matching | Keep only matching lines |
| on_empty | Message when filtering removes everything |
Sabor de regex
Todos los patrones usan el paquete regexp de Go (sintaxis RE2), no PCRE. Sin backreferences ni lookbehind. ^/$ multilínea requieren (?m) al coincidir contra la salida completa. Ver regexp/syntax.
Ejemplo: script de deploy personalizado
Tu equipo ejecuta ./scripts/deploy.sh a través de Boost. El hook solo envía la salida, así que hace falta match_output_select además de match_command.
.boost/filters/deploy.toml
schema_version = 1
[filters.deploy]
description = "Keep failures from deploy.sh"
version = "1"
match_command = '(?:^|[;&|]\s*)(?:bash\s+)?(?:\S*/)?deploy\.sh\b'
# The hook pipes output to boost, so select by a distinctive output signature.
# (?m) makes ^ and $ match each line, not only the full output boundaries.
match_output_select = [
'(?m)^Starting deployment$\n^Environment: ',
]
strip_ansi = true
keep_lines_matching = [
'^Starting deployment$',
'^Environment: ',
'^\[(WARN|ERROR)\]',
'^ERROR DETAILS:$',
'failed readiness probe',
'^File:$',
'^deploy/check_health\.go:\d+$',
'^Reason:$',
'^connection refused',
'^Rollback started\.\.\.$',
'^Deployment FAILED$',
]
[[tests.deploy]]
name = "keeps failures, drops info chatter"
input = """
Starting deployment
Environment: staging
[INFO] Waiting for rollout
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging
"""
expected = """
Starting deployment
Environment: staging
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging
"""Starting deployment Environment: staging [INFO] Waiting for rollout [WARN] High memory usage detected [ERROR] Deployment validation failed ERROR DETAILS: service payment-service failed readiness probe File: deploy/check_health.go:142 Reason: connection refused to database Rollback started... Deployment FAILED Environment: staging
Starting deployment Environment: staging [WARN] High memory usage detected [ERROR] Deployment validation failed ERROR DETAILS: service payment-service failed readiness probe File: deploy/check_health.go:142 Reason: connection refused to database Rollback started... Deployment FAILED Environment: staging
$ ./scripts/deploy.sh staging # the installed Boost hook pipes output automatically
Tests inline
Cada bloque [[tests.<name>]] es un fixture de regresión: name, input y expected. expect_match_output opcional comprueba si match_output_select seleccionaría el filtro.
Cómo ejecutarlos
Aún no hay boost filters test. Comprueba filtros personalizados enviando salida de ejemplo por boost. Los fixtures integrados se ejecutan con go test:
# Spot-check a custom filter: pipe sample output through boost
printf '%s\n' 'Starting deployment' 'Environment: staging' '[INFO] noise' | boost
# Built-in [[tests.*]] fixtures run in the Boost repo / CI:
go test ./internal/tomlfilter/ -run TestInlineTestDefsEjemplo: recortar ruido de make
Los filtros integrados usan el mismo esquema. Esto refleja el filtro make incluido: elimina líneas de entrar/salir de directorio y filas en blanco.
schema_version = 1
[filters.make]
match_command = "^make\\b"
match_output_select = [
"^make\\[\\d+\\]:",
"^gcc ",
]
strip_lines_matching = [
"^make\\[\\d+\\]:",
"^\\s*$",
"^Nothing to be done",
]
on_empty = "make: ok"make[1]: Entering directory '/home/user/app' gcc -O2 -c src/main.c gcc -O2 -o app src/main.o make[1]: Leaving directory '/home/user/app'
gcc -O2 -c src/main.c gcc -O2 -o app src/main.o
Ejemplo: resumen en lint limpio
Usa match_output para devolver un resumen de una línea cuando la herramienta terminó en silencio.
schema_version = 1
[filters.eslint-quiet]
match_command = "^eslint\\b"
match_output_select = [
"problems",
]
match_output = [
{ pattern = "0 problems", message = "eslint: ok" },
]Desactivar un filtro
Prefiere la CLI:
boost filters show # inventory with enabled/disabled status
boost filters show --enabled # enabled filters only
boost filters disable git-status # bare name or toml:builtin:git-status
boost filters enable git-statusO edita ~/.boost/config.toml directamente — lista nombres bajo [filters] disabled. Tras retrieve_disable_threshold eventos retrieve (predeterminado 3), boost retrieve añade automáticamente los nombres revertidos. Usa 0 para desactivar el auto-disable.
[filters]
disabled = ["git-status", "make"]
retrieve_disable_threshold = 3Campos del filtro
| Campo | Tipo | Propósito |
|---|---|---|
| schema_version | int | File-level schema marker (recommended 1; reserved for future validation) |
| description | string | Human-readable note (not used at filter runtime) |
| version | string | Capability version for retrieve / telemetry (e.g. "1") |
| match_command | string | Command-path selector: regex against the full command line |
| match_output_select | string[] | Pipe-path selector: regexes against the complete piped output; use (?m) for line anchors |
| strip_ansi | bool | Remove terminal color codes first (before other stages) |
| replace | array | Line-level regex replacements: { pattern, replacement } |
| match_output | array | If output matches pattern, return message instead (optional unless) |
| strip_lines_matching | string[] | Drop lines matching any pattern |
| keep_lines_matching | string[] | Keep only matching lines |
| dedupe_lines_matching | string[] | Keep the first exact copy of each matching line; drop later identical copies |
| collapse_lines_matching | array | Replace matching lines with one summary: { pattern, template } — {count} = number of matches |
| head_lines / tail_lines | int | Keep first or last N lines |
| on_empty | string | Message when filtering removes everything |
Pon schema_version = 1 al inicio de cada archivo. Etapas en orden: strip ANSI → replace → match_output → strip/keep → dedupe → collapse → head/tail → on_empty. Referencia completa en docs/TOML_FILTERS.md.