watchexec - Cheatsheet de Executar Comandos em Mudanças de Arquivo
watchexec assiste um conjunto de arquivos ou diretórios e executa um comando sempre que eles mudam. É agnóstico a linguagem e projeto — nenhum arquivo config necessário — e manipula as partes fidgety do file-watching para você: debouncing de mudanças rápidas, respeitando .gitignore, reiniciando processos longos cleanly e passando caminhos mudados para seu comando. Use-o para auto-run testes, reiniciar um dev server ou reconstruir na gravação.
Instalação
| Platform | Command |
|---|
| Cargo (todas plataformas) | cargo install watchexec-cli |
| macOS (Homebrew) | brew install watchexec |
| Arch Linux | sudo pacman -S watchexec |
| Debian/Ubuntu | faça download do .deb de Releases |
| Windows (Scoop) | scoop install watchexec |
| Verificar | watchexec --version |
Uso Básico
| Command | Descrição |
|---|
watchexec "cargo test" | Execute testes em qualquer mudança |
watchexec -e py "pytest" | Apenas assista arquivos .py |
watchexec -e js,ts,jsx "npm run build" | Assista múltiplas extensões |
watchexec -- ls -la | Tudo após -- é o comando |
watchexec --help | Lista de opção completa |
Filtrando O Que Assistir
| Option | Descrição |
|---|
-e, --exts py,rs | Apenas dispare nessas extensões de arquivo |
-w, --watch DIR | Assista um caminho específico (repeatable) |
-i, --ignore GLOB | Ignore caminhos matching um glob |
--ignore-file FILE | Carregue padrões de ignore de um arquivo |
--no-vcs-ignore | Não use regras .gitignore |
-f, --filter GLOB | Apenas assista arquivos matching um glob |
Gerenciamento de Processo
| Option | Descrição |
|---|
-r, --restart | Reinicie o comando em mudança (kill + rerun) |
-s, --signal SIG | Sinal para enviar ao reiniciar (ex. SIGTERM) |
--stop-timeout 5s | Período de graça antes de force-kill |
-o, --on-busy-update MODE | queue, do-nothing, restart ou signal |
-n | Sem process group (envie sinal apenas para criança direta) |
Use -r para processos longos (servers) e o padrão para comandos one-shot (testes, builds).
Debouncing & Timing
| Option | Descrição |
|---|
--debounce 200ms | Aguarde as mudanças se assentarem antes de rodar |
--delay-run 1s | Atraso antes do comando rodar |
-p, --postpone | Não rode até a primeira mudança (pule run inicial) |
Comportamento Útil
| Option | Descrição |
|---|
-c, --clear | Limpe a tela antes de cada execução |
--emit-events-to environment | Passe caminhos mudados via env vars |
-N, --notify | Notificação de desktop em conclusão |
--project-origin DIR | Defina a raiz do projeto para regras ignore |
-v | Verboso (debug o que dispara) |
Variáveis de Ambiente (Caminhos Mudados)
Quando eventos são emitidos ao ambiente, seu comando pode ver o que mudou:
| Variable | Contém |
|---|
WATCHEXEC_COMMON_PATH | Prefixo comum de caminhos mudados |
WATCHEXEC_WRITTEN_PATH | Arquivos escritos |
WATCHEXEC_CREATED_PATH | Arquivos criados |
WATCHEXEC_REMOVED_PATH | Arquivos removidos |
Fluxos de Trabalho Comuns
# Auto-execute a suíte de testes em qualquer mudança de source
watchexec -e rs "cargo test"
# Reinicie um dev server cleanly em mudança
watchexec -r -e go "go run ./cmd/server"
# Reconstrua e limpe a tela, ignorando a pasta dist
watchexec -c -i "dist/**" -e ts "npm run build"
# Apenas após mudanças se assentarem (evite trashing em bulk saves)
watchexec --debounce 500ms -e py "pytest -x"
watchexec vs Ferramentas Relacionadas
| Tool | Modelo |
|---|
| watchexec | Standalone, config-free file watcher |
| entr | Minimalista, lê lista de arquivo do stdin |
| nodemon | Node-focused, reinicia node apps |
| mise/just + watchexec | Task runners que shell out para watchexec |
Task runners como just e mise frequentemente emparelham com watchexec para adicionar file-watching a suas recipes.
Recursos
