watchexec - ファイル変更時にコマンド実行チートシート
watchexec はファイルまたはディレクトリのセットを監視し、変更時にコマンドを実行します。言語およびプロジェクトに依存しません — 設定ファイル不要 — ファイルウォッチングのたいくつな部分を処理します：急速な変更のデバウンス、.gitignore の尊重、長時間実行プロセスのクリーン再起動、変更されたパスをコマンドに渡すこと。テストの自動実行、サーバー再起動、または保存時リビルドに使用します。
インストール
| プラットフォーム | コマンド |
|---|
| Cargo (すべてのプラットフォーム) | cargo install watchexec-cli |
| macOS (Homebrew) | brew install watchexec |
| Arch Linux | sudo pacman -S watchexec |
| Debian/Ubuntu | Releases から .deb をダウンロード |
| Windows (Scoop) | scoop install watchexec |
| 確認 | watchexec --version |
基本的な使用
| コマンド | 説明 |
|---|
watchexec "cargo test" | 変更時にテスト実行 |
watchexec -e py "pytest" | .py ファイルのみを監視 |
watchexec -e js,ts,jsx "npm run build" | 複数の拡張子を監視 |
watchexec -- ls -la | -- の後のすべてはコマンド |
watchexec --help | 完全なオプションリスト |
監視対象のフィルタリング
| オプション | 説明 |
|---|
-e, --exts py,rs | これらのファイル拡張子のみでトリガー |
-w, --watch DIR | 特定のパスを監視 (繰り返し可) |
-i, --ignore GLOB | グロブにマッチするパスを無視 |
--ignore-file FILE | ファイルから無視パターンを読み込み |
--no-vcs-ignore | .gitignore ルールを使用しない |
-f, --filter GLOB | グロブにマッチするファイルのみを監視 |
プロセス管理
| オプション | 説明 |
|---|
-r, --restart | 変更時にコマンドを再起動 (kill + 再実行) |
-s, --signal SIG | 再起動時に送信するシグナル (例: SIGTERM) |
--stop-timeout 5s | 強制キル前のグレースピリオド |
-o, --on-busy-update MODE | queue、do-nothing、restart、または signal |
-n | プロセスグループなし (直接子供のみシグナル送信) |
長時間実行プロセス (サーバー)には -r を使用し、ワンショットコマンド (テスト、ビルド) にはデフォルト。
デバウンス & タイミング
| オプション | 説明 |
|---|
--debounce 200ms | 変更がセットルするまで待ってから実行 |
--delay-run 1s | コマンド実行前に遅延 |
-p, --postpone | 最初の変更まで実行を延期 (初期実行スキップ) |
有用な動作
| オプション | 説明 |
|---|
-c, --clear | 各実行前にスクリーンをクリア |
--emit-events-to environment | 変更されたパスを環境変数経由で渡す |
-N, --notify | 完了時にデスクトップ通知 |
--project-origin DIR | 無視ルール用のプロジェクトルートを設定 |
-v | 詳細 (トリガーをデバッグ) |
環境変数 (変更されたパス)
イベントが環境に発行される場合、コマンドが何が変更されたかを確認できます：
| 変数 | 含まれる |
|---|
WATCHEXEC_COMMON_PATH | 変更されたパスの共通プリフィックス |
WATCHEXEC_WRITTEN_PATH | 書き込まれたファイル |
WATCHEXEC_CREATED_PATH | 作成されたファイル |
WATCHEXEC_REMOVED_PATH | 削除されたファイル |
一般的なワークフロー
# ソース変更時にテストスイートを自動実行
watchexec -e rs "cargo test"
# 変更時にサーバーをクリーンに再起動
watchexec -r -e go "go run ./cmd/server"
# スクリーンをクリア、distフォルダを無視してリビルド
watchexec -c -i "dist/**" -e ts "npm run build"
# 変更がセットルするまでのみ実行 (バルク保存で激動を回避)
watchexec --debounce 500ms -e py "pytest -x"
watchexec と関連ツール
| ツール | モデル |
|---|
| watchexec | スタンドアロン、設定不要ファイルウォッチャー |
| entr | 最小限、stdinからファイルリストを読み込み |
| nodemon | Node フォーカス、nodeアプリを再起動 |
| mise/just + watchexec | watchexecにシェルアウトするタスクランナー |
just や mise のようなタスクランナーは、レシピにファイルウォッチングを追加するために watchexec とペア。
リソース
