watchexec - 파일 변경 시 명령 실행 치트시트
watchexec은 파일이나 디렉토리 세트를 감시하고 변경될 때마다 명령을 실행한다. 언어 및 프로젝트 불가지론적이다 — 설정 파일 필요 없음 — 파일 감시의 까다로운 부분을 처리한다: 빠른 변경의 디바운싱, .gitignore 존경, 장기 실행 프로세스 깨끗한 재시작, 변경된 경로를 명령에 전달. 테스트 자동 실행, dev 서버 재시작, 또는 저장 시 재구축에 사용하자.
설치
| 플랫폼 | 명령어 |
|---|
| Cargo (모든 플랫폼) | cargo install watchexec-cli |
| macOS (Homebrew) | brew install watchexec |
| Arch Linux | sudo pacman -S watchexec |
| Debian/Ubuntu | 릴리스에서 .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 | glob과 일치하는 경로 무시 |
--ignore-file FILE | 파일에서 무시 패턴 로드 |
--no-vcs-ignore | .gitignore 규칙을 사용하지 않음 |
-f, --filter GLOB | 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"
# 변경 시 dev 서버를 깨끗하게 재시작
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 vs 관련 도구
| 도구 | 모델 |
|---|
| watchexec | 독립 실행형, 설정 없음 파일 감시 |
| entr | 최소, stdin에서 파일 목록 읽기 |
| nodemon | Node 포커스, node 앱 재시작 |
| mise/just + watchexec | 작업 실행기가 watchexec으로 셸 아웃 |
just 및 mise와 같은 작업 실행기는 종종 watchexec과 페어링하여 레시피에 파일 감시를 추가한다.
자료
