watchexec - Ausführe Befehle auf Datei-Änderungen-Spickzettel
watchexec beobachtet eine Menge von Dateien oder Verzeichnissen und führt einen Befehl immer dann aus, wenn sie sich ändern. Es ist Sprach- und Projekt-agnostisch — keine Konfigurationsdatei erforderlich — und handhhabt die fiddly Teile des Datei-Beobachtens für dich: Debouncing schneller Änderungen, .gitignore respektieren, langlebige Prozesse sauber neu starten und geänderte Pfade an deinen Befehl weitergeben. Verwende es, um Tests automatisch auszuführen, einen Dev-Server neu zu starten oder beim Speichern neu zu bauen.
Installation
| Plattform | Befehl |
|---|
| Cargo (alle Plattformen) | cargo install watchexec-cli |
| macOS (Homebrew) | brew install watchexec |
| Arch Linux | sudo pacman -S watchexec |
| Debian/Ubuntu | .deb von Releases herunterladen |
| Windows (Scoop) | scoop install watchexec |
| Verifizieren | watchexec --version |
Grundlegende Nutzung
| Befehl | Beschreibung |
|---|
watchexec "cargo test" | Tests bei jeder Änderung ausführen |
watchexec -e py "pytest" | Nur .py-Dateien beobachten |
watchexec -e js,ts,jsx "npm run build" | Mehrere Extensions beobachten |
watchexec -- ls -la | Alles nach -- ist der Befehl |
watchexec --help | Vollständige Optionsliste |
Filtern, was zu beobachten ist
| Option | Beschreibung |
|---|
-e, --exts py,rs | Nur bei diesen Datei-Extensions triggern |
-w, --watch DIR | Einen spezifischen Pfad beobachten (wiederholbar) |
-i, --ignore GLOB | Pfade matching a glob ignorieren |
--ignore-file FILE | Ignore-Muster aus einer Datei laden |
--no-vcs-ignore | Keine .gitignore-Regeln verwenden |
-f, --filter GLOB | Nur Dateien, die a glob matching beobachten |
Prozess-Management
| Option | Beschreibung |
|---|
-r, --restart | Befehl bei Änderung neu starten (Kill + Rerun) |
-s, --signal SIG | Signal beim Neustart zu senden (z.B. SIGTERM) |
--stop-timeout 5s | Grace-Zeit vor Force-Kill |
-o, --on-busy-update MODE | queue, do-nothing, restart oder signal |
-n | Keine Prozess-Gruppe (Signal nur zum direkten Kind senden) |
Verwende -r für langlebige Prozesse (Server), und die Standard für One-Shot-Befehle (Tests, Builds).
Debouncing & Timing
| Option | Beschreibung |
|---|
--debounce 200ms | Warte auf Änderungen zum Settled, bevor du läufst |
--delay-run 1s | Verzögerung, bevor der Befehl läuft |
-p, --postpone | Nicht bis zum ersten Wechsel ausführen (Skip-Initialität-Lauf) |
Nützliches Verhalten
| Option | Beschreibung |
|---|
-c, --clear | Screen vor jedem Lauf löschen |
--emit-events-to environment | Geänderte Pfade via Env-Vars weitergeben |
-N, --notify | Desktop-Benachrichtigung auf Completion |
--project-origin DIR | Projekt-Root für Ignore-Regeln setzen |
-v | Verbose (Debug, was triggert) |
Umgebungs-Variablen (Geänderte Pfade)
Wenn Events zur Umgebung emittiert werden, kann dein Befehl sehen, was sich geändert hat:
| Variable | Enthält |
|---|
WATCHEXEC_COMMON_PATH | Gemeinsamer Prefix der geänderten Pfade |
WATCHEXEC_WRITTEN_PATH | Geschriebene Dateien |
WATCHEXEC_CREATED_PATH | Erstellte Dateien |
WATCHEXEC_REMOVED_PATH | Entfernte Dateien |
Häufige Workflows
# Auto-Run der Test-Suite bei jeder Source-Änderung
watchexec -e rs "cargo test"
# Dev-Server sauber bei Änderung neu starten
watchexec -r -e go "go run ./cmd/server"
# Neubauen und Screen löschen, dist-Ordner ignorieren
watchexec -c -i "dist/**" -e ts "npm run build"
# Nur nach Änderungen settled (Thrashing bei Bulk-Saves vermeiden)
watchexec --debounce 500ms -e py "pytest -x"
| Tool | Modell |
|---|
| watchexec | Standalone, konfigurationsfrei Datei-Watcher |
| entr | Minimal, liest Datei-Liste von Stdin |
| nodemon | Node-fokussiert, startet Node-Apps neu |
| mise/just + watchexec | Task-Läufer, die zu watchexec ausschellen |
Task-Läufer wie just und mise werden oft mit watchexec gekoppelt, um Datei-Beobachtung zu ihren Rezepten hinzuzufügen.
Ressourcen
