watchexec - Cheatsheet Exécuter les Commandes sur Changements de Fichiers
watchexec observe un ensemble de fichiers ou de répertoires et exécute une commande chaque fois qu”ils changent. C”est agnostique au langage et au projet — aucun fichier de configuration requis — et gère les parties délicates de l”observation de fichiers pour toi : débounce des changements rapides, respect de .gitignore, redémarrage propre des processus longue durée et passage des chemins changés à ta commande. Utilise-le pour réexécuter auto les tests, redémarrer un serveur de dev ou reconstruire à la sauvegarde.
Installation
| Plateforme | Commande |
|---|
| Cargo (toutes les plateformes) | cargo install watchexec-cli |
| macOS (Homebrew) | brew install watchexec |
| Arch Linux | sudo pacman -S watchexec |
| Debian/Ubuntu | télécharger le .deb depuis Releases |
| Windows (Scoop) | scoop install watchexec |
| Vérification | watchexec --version |
Utilisation Basique
| Commande | Description |
|---|
watchexec "cargo test" | Exécuter les tests sur n”importe quel changement |
watchexec -e py "pytest" | Observer uniquement les fichiers .py |
watchexec -e js,ts,jsx "npm run build" | Observer plusieurs extensions |
watchexec -- ls -la | Tout après -- est la commande |
watchexec --help | Liste complète des options |
Filtrer Quoi Observer
| Option | Description |
|---|
-e, --exts py,rs | Déclencher uniquement sur ces extensions de fichier |
-w, --watch DIR | Observer un chemin spécifique (répétable) |
-i, --ignore GLOB | Ignorer les chemins correspondant un glob |
--ignore-file FILE | Charger les motifs d”ignorage depuis un fichier |
--no-vcs-ignore | Ne pas utiliser les règles de .gitignore |
-f, --filter GLOB | Observer uniquement les fichiers correspondant un glob |
Gestion des Processus
| Option | Description |
|---|
-r, --restart | Redémarrer la commande au changement (tuer + réexécuter) |
-s, --signal SIG | Signal à envoyer au redémarrage (ex. SIGTERM) |
--stop-timeout 5s | Période de grâce avant force-kill |
-o, --on-busy-update MODE | queue, do-nothing, restart ou signal |
-n | Pas de groupe de processus (envoyer le signal uniquement à l”enfant direct) |
Utiliser -r pour les processus longue durée (serveurs) et le défaut pour les commandes uniques (tests, builds).
Débounce et Timing
| Option | Description |
|---|
--debounce 200ms | Attendre que les changements se stabilisent avant d”exécuter |
--delay-run 1s | Délai avant l”exécution de la commande |
-p, --postpone | Ne pas exécuter jusqu”au premier changement (ignorer l”exécution initiale) |
Comportement Utile
| Option | Description |
|---|
-c, --clear | Effacer l”écran avant chaque exécution |
--emit-events-to environment | Passer les chemins changés via les variables d”env |
-N, --notify | Notification de bureau à l”achèvement |
--project-origin DIR | Définir la racine du projet pour les règles d”ignorage |
-v | Verbose (debug ce qui déclenche) |
Variables d”Environnement (Chemins Changés)
Quand les événements sont émis à l”environnement, ta commande peut voir ce qui a changé :
| Variable | Contient |
|---|
WATCHEXEC_COMMON_PATH | Préfixe commun des chemins changés |
WATCHEXEC_WRITTEN_PATH | Fichiers écrits |
WATCHEXEC_CREATED_PATH | Fichiers créés |
WATCHEXEC_REMOVED_PATH | Fichiers supprimés |
Flux de Travail Courants
# Réexécuter auto la suite de tests sur n''importe quel changement source
watchexec -e rs "cargo test"
# Redémarrer proprement un serveur dev au changement
watchexec -r -e go "go run ./cmd/server"
# Reconstruire et effacer l''écran, en ignorant le dossier dist
watchexec -c -i "dist/**" -e ts "npm run build"
# Uniquement après que les changements se stabilisent (éviter les thrashings en saveout vrac)
watchexec --debounce 500ms -e py "pytest -x"
watchexec vs Outils Connexes
| Outil | Modèle |
|---|
| watchexec | Observateur de fichiers autonome, sans config |
| entr | Minimaliste, lit la liste de fichiers depuis stdin |
| nodemon | Focalisé Node, redémarrage des apps node |
| mise/just + watchexec | Task runners qui font un shell vers watchexec |
Les task runners comme just et mise s”associent souvent avec watchexec pour ajouter l”observation de fichiers à leurs recettes.
Ressources
