watchexec - Cheatsheet Run Commands on File Changes
watchexec osserva un set di file o directory ed esegue un comando quando cambiano. È language- e project-agnostic — nessun file di config richiesto — e maneggia le parti fastidiose di file-watching per te: debouncing i cambiamenti rapidi, rispettando .gitignore, riavviando pulitamente i processi long-running, e passando i path cambiati al tuo comando. Usalo per auto-run test, riavviare un dev server, o ricostruire su salvataggio.
Installazione
| Piattaforma | Comando |
|---|
| Cargo (tutte piattaforme) | cargo install watchexec-cli |
| macOS (Homebrew) | brew install watchexec |
| Arch Linux | sudo pacman -S watchexec |
| Debian/Ubuntu | scarica il .deb da Releases |
| Windows (Scoop) | scoop install watchexec |
| Verifica | watchexec --version |
Utilizzo di Base
| Comando | Descrizione |
|---|
watchexec "cargo test" | Esegui test su qualsiasi cambiamento |
watchexec -e py "pytest" | Solo osserva file .py |
watchexec -e js,ts,jsx "npm run build" | Osserva multiple estensioni |
watchexec -- ls -la | Tutto dopo -- è il comando |
watchexec --help | Lista opzione completa |
Filtraggio Cosa Osservare
| Opzione | Descrizione |
|---|
-e, --exts py,rs | Solo trigger su queste file extensions |
-w, --watch DIR | Osserva un percorso specifico (ripetibile) |
-i, --ignore GLOB | Ignora percorsi matching un glob |
--ignore-file FILE | Carica ignore patterns da un file |
--no-vcs-ignore | Non usare regole .gitignore |
-f, --filter GLOB | Solo osserva file matching un glob |
Process Management
| Opzione | Descrizione |
|---|
-r, --restart | Riavvia il comando su cambiamento (kill + rerun) |
-s, --signal SIG | Segnale da inviare quando riavvi (e.g. SIGTERM) |
--stop-timeout 5s | Grace period prima di force-kill |
-o, --on-busy-update MODE | queue, do-nothing, restart, o signal |
-n | Nessun process group (invia segnale al direct child solamente) |
Usa -r per processi long-running (server), e il default per comandi one-shot (test, build).
Debouncing & Timing
| Opzione | Descrizione |
|---|
--debounce 200ms | Aspetta che i cambiamenti si sistemino prima di eseguire |
--delay-run 1s | Ritardo prima che il comando esegua |
-p, --postpone | Non eseguire finché il primo cambiamento (salta initial run) |
Comportamento Utile
| Opzione | Descrizione |
|---|
-c, --clear | Pulisci lo schermo prima di ogni run |
--emit-events-to environment | Passa i path cambiati via env vars |
-N, --notify | Notifica desktop su completamento |
--project-origin DIR | Imposta la root del progetto per ignore rules |
-v | Verbose (debug cosa trigga) |
Environment Variables (Changed Paths)
Quando gli eventi vengono emessi all”ambiente, il tuo comando può vedere cosa è cambiato:
| Variabile | Contiene |
|---|
WATCHEXEC_COMMON_PATH | Common prefix dei path cambiati |
WATCHEXEC_WRITTEN_PATH | File scritti |
WATCHEXEC_CREATED_PATH | File creati |
WATCHEXEC_REMOVED_PATH | File rimossi |
Workflow Comuni
# Auto-run il test suite su qualsiasi source change
watchexec -e rs "cargo test"
# Riavvia un dev server pulitamente su cambiamento
watchexec -r -e go "go run ./cmd/server"
# Ricostruisci e pulisci lo schermo, ignorando la cartella dist
watchexec -c -i "dist/**" -e ts "npm run build"
# Solo dopo che i cambiamenti si sistemino (evita thrashing su bulk save)
watchexec --debounce 500ms -e py "pytest -x"
| Tool | Model |
|---|
| watchexec | Standalone, config-free file watcher |
| entr | Minimal, legge lista file da stdin |
| nodemon | Node-focused, riavvia node app |
| mise/just + watchexec | Task runner che shell out a watchexec |
Task runner come just e mise spesso pair con watchexec per aggiungere file-watching alle loro ricette.
Risorse
