watchexec - Ejecutar Comandos en Cambios de Archivo
watchexec observa un conjunto de archivos o directorios y ejecuta un comando cuando cambian. Es agnóstico de lenguaje y proyecto — no se requiere archivo de configuración — y maneja las partes fidedignas de la observación de archivos para ti: debouncing de cambios rápidos, respetando .gitignore, reiniciando procesos de larga ejecución limpiamente y pasando las rutas cambiadas a tu comando. Úsalo para ejecutar automáticamente pruebas, reiniciar un servidor de desarrollo o reconstruir al guardar.
Installation
| Plataforma | Comando |
|---|
| Cargo (todas las plataformas) | cargo install watchexec-cli |
| macOS (Homebrew) | brew install watchexec |
| Arch Linux | sudo pacman -S watchexec |
| Debian/Ubuntu | descarga el .deb desde Releases |
| Windows (Scoop) | scoop install watchexec |
| Verificar | watchexec --version |
Basic Usage
| Comando | Descripción |
|---|
watchexec "cargo test" | Ejecuta pruebas en cualquier cambio |
watchexec -e py "pytest" | Solo observa archivos .py |
watchexec -e js,ts,jsx "npm run build" | Observa múltiples extensiones |
watchexec -- ls -la | Todo después de -- es el comando |
watchexec --help | Lista completa de opciones |
Filtering What to Watch
| Opción | Descripción |
|---|
-e, --exts py,rs | Solo desencadena en estas extensiones de archivo |
-w, --watch DIR | Observa una ruta específica (repetible) |
-i, --ignore GLOB | Ignora rutas que coincidan con un glob |
--ignore-file FILE | Carga patrones de ignorancia desde un archivo |
--no-vcs-ignore | No uses reglas de .gitignore |
-f, --filter GLOB | Solo observa archivos que coincidan con un glob |
Process Management
| Opción | Descripción |
|---|
-r, --restart | Reinicia el comando en cambio (mata + reejecutar) |
-s, --signal SIG | Señal a enviar al reiniciar (p. ej. SIGTERM) |
--stop-timeout 5s | Período de gracia antes de force-kill |
-o, --on-busy-update MODE | queue, do-nothing, restart, o signal |
-n | Sin grupo de procesos (envía señal solo al hijo directo) |
Usa -r para procesos de larga ejecución (servidores), y el predeterminado para comandos de una sola ejecución (pruebas, compilaciones).
Debouncing & Timing
| Opción | Descripción |
|---|
--debounce 200ms | Espera a que los cambios se estabilicen antes de ejecutar |
--delay-run 1s | Retraso antes de que el comando se ejecute |
-p, --postpone | No ejecutes hasta el primer cambio (omite ejecución inicial) |
Useful Behavior
| Opción | Descripción |
|---|
-c, --clear | Limpia la pantalla antes de cada ejecución |
--emit-events-to environment | Pasa rutas cambiadas vía variables de entorno |
-N, --notify | Notificación de escritorio en completación |
--project-origin DIR | Establece la raíz del proyecto para reglas de ignorancia |
-v | Verboso (debug qué desencadena) |
Environment Variables (Changed Paths)
Cuando los eventos se emiten al entorno, tu comando puede ver qué cambió:
| Variable | Contiene |
|---|
WATCHEXEC_COMMON_PATH | Prefijo común de rutas cambiadas |
WATCHEXEC_WRITTEN_PATH | Archivos escritos |
WATCHEXEC_CREATED_PATH | Archivos creados |
WATCHEXEC_REMOVED_PATH | Archivos eliminados |
Common Workflows
# Ejecuta automáticamente el conjunto de pruebas en cualquier cambio de código fuente
watchexec -e rs "cargo test"
# Reinicia un servidor de desarrollo de forma limpia en cambio
watchexec -r -e go "go run ./cmd/server"
# Reconstruye y limpia la pantalla, ignorando la carpeta dist
watchexec -c -i "dist/**" -e ts "npm run build"
# Solo después de que los cambios se estabilicen (evita agotar en guardados masivos)
watchexec --debounce 500ms -e py "pytest -x"
| Herramienta | Modelo |
|---|
| watchexec | Observador de archivo independiente, sin configuración |
| entr | Minimalista, lee lista de archivos desde stdin |
| nodemon | Enfocado en Node, reinicia apps de node |
| mise/just + watchexec | Corredores de tareas que salen a watchexec |
Los corredores de tareas como just y mise a menudo se emparejan con watchexec para añadir observación de archivos a sus recetas.
Resources
