Back to Details

file-watcher

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

File Watcher Skill

File Watcher Skill

Monitor files and directories for changes and trigger actions when changes occur.
监控文件和目录的变更，在变更发生时触发操作。

When to Use

适用场景

✅ USE this skill when:
  • "Watch for file changes"
  • "Run command when file changes"
  • "Monitor directory for new files"
  • "Execute script on file create"
  • "Watch multiple files for changes"
✅ 在以下场景使用本skill：
  • "监控文件变更"
  • "文件变更时运行命令"
  • "监控目录中的新文件"
  • "文件创建时执行脚本"
  • "监控多个文件的变更"

When NOT to Use

不适用场景

❌ DON'T use this skill when:
  • One-time file check → use test/read commands
  • Scheduled monitoring → use cron
  • Need persistent logging → use dedicated monitoring
❌ 请勿在以下场景使用本skill：
  • 一次性文件检查 → 使用测试/读取命令
  • 定时监控 → 使用cron
  • 需要持久化日志 → 使用专用监控工具

Commands

命令

Watch Directory

监控目录

bash
{baseDir}/watch.sh <directory> --command "echo 'Changed'"
{baseDir}/watch.sh ./src --command "npm run build"
{baseDir}/watch.sh ./logs --command "./process.sh" --pattern "*.log"
bash
{baseDir}/watch.sh <directory> --command "echo 'Changed'"
{baseDir}/watch.sh ./src --command "npm run build"
{baseDir}/watch.sh ./logs --command "./process.sh" --pattern "*.log"

Watch Single File

监控单个文件

bash
{baseDir}/watch.sh --file config.json --command "echo 'Config changed'"
{baseDir}/watch.sh --file /var/log/app.log --command "tail -5 /var/log/app.log"
bash
{baseDir}/watch.sh --file config.json --command "echo 'Config changed'"
{baseDir}/watch.sh --file /var/log/app.log --command "tail -5 /var/log/app.log"

Watch Multiple Files

监控多个文件

bash
{baseDir}/watch.sh --files "file1.txt,file2.txt,file3.txt" --command "echo 'Changed'"
{baseDir}/watch.sh --files-from list.txt --command "echo 'Changed'"
bash
{baseDir}/watch.sh --files "file1.txt,file2.txt,file3.txt" --command "echo 'Changed'"
{baseDir}/watch.sh --files-from list.txt --command "echo 'Changed'"

Event Types

事件类型

bash
{baseDir}/watch.sh ./src --command "make" --events create,modify,delete
{baseDir}/watch.sh ./src --command "make" --events create
{baseDir}/watch.sh ./src --command "make" --events modify
bash
{baseDir}/watch.sh ./src --command "make" --events create,modify,delete
{baseDir}/watch.sh ./src --command "make" --events create
{baseDir}/watch.sh ./src --command "make" --events modify

Background Mode

后台模式

bash
{baseDir}/watch.sh ./src --command "make" --daemon
{baseDir}/watch.sh ./src --command "make" --pidfile /tmp/watcher.pid
bash
{baseDir}/watch.sh ./src --command "make" --daemon
{baseDir}/watch.sh ./src --command "make" --pidfile /tmp/watcher.pid

Debounce

防抖机制

bash
{baseDir}/watch.sh ./src --command "npm run build" --debounce 2
{baseDir}/watch.sh ./src --command "npm run build" --debounce-file
bash
{baseDir}/watch.sh ./src --command "npm run build" --debounce 2
{baseDir}/watch.sh ./src --command "npm run build" --debounce-file

Options

选项

OptionDescriptionDefault
--command CMD
Command to run on changeRequired
--file FILE
Watch single fileNone
--files "F1,F2,..."
Watch multiple filesNone
--files-from FILE
Read file list from fileNone
--pattern GLOB
File pattern to match
*
--events TYPES
Events: create,modify,deleteall
--recursive
Watch subdirectoriestrue
--no-recursive
Don't recursefalse
--debounce SECS
Debounce time0
--debounce-file
Debounce per filefalse
--daemon
Run in backgroundfalse
--pidfile FILE
PID file for daemonNone
--timeout SECS
Stop after N secondsNone
--quiet
Suppress outputfalse
--verbose
Show all eventsfalse
选项描述默认值
--command CMD
变更时执行的命令必填
--file FILE
监控单个文件无
--files "F1,F2,..."
监控多个文件无
--files-from FILE
从文件中读取待监控文件列表无
--pattern GLOB
匹配的文件模式
*
--events TYPES
事件类型：create,modify,delete全部
--recursive
监控子目录true
--no-recursive
不递归监控false
--debounce SECS
防抖时间0
--debounce-file
按文件单独防抖false
--daemon
在后台运行false
--pidfile FILE
后台进程的PID文件无
--timeout SECS
N秒后停止运行无
--quiet
抑制输出false
--verbose
显示所有事件false

Events

事件类型

EventDescription
create
File or directory created
modify
File content modified
delete
File or directory deleted
move
File moved (renamed)
access
File accessed (read)
attrib
File attributes changed
事件描述
create
文件或目录被创建
modify
文件内容被修改
delete
文件或目录被删除
move
文件被移动（重命名）
access
文件被访问（读取）
attrib
文件属性被修改

Output Format

输出格式

[2026-02-25 20:41:00] MODIFY /path/to/file.txt
Running: echo 'Changed'
...
[2026-02-25 20:41:01] CREATE /path/to/newfile.txt
Running: echo 'Changed'
...
With 
--json
:
json
{"event": "MODIFY", "file": "/path/to/file.txt", "timestamp": "2026-02-25T20:41:00Z", "command_output": "..."}
[2026-02-25 20:41:00] MODIFY /path/to/file.txt
Running: echo 'Changed'
...
[2026-02-25 20:41:01] CREATE /path/to/newfile.txt
Running: echo 'Changed'
...
使用
--json
选项时：
json
{"event": "MODIFY", "file": "/path/to/file.txt", "timestamp": "2026-02-25T20:41:00Z", "command_output": "..."}

Examples

示例

Watch and rebuild:
bash
{baseDir}/watch.sh ./src --command "npm run build" --debounce 1
Watch for new log files:
bash
{baseDir}/watch.sh ./logs --command "./new-log.sh" --events create
Watch config and restart:
bash
{baseDir}/watch.sh --file config.json --command "pm2 restart app"
Watch multiple files:
bash
{baseDir}/watch.sh --files "config.json,.env,package.json" --command "npm run build"
Watch in background:
bash
{baseDir}/watch.sh ./src --command "make" --daemon --pidfile /tmp/watcher.pid
Watch for deleted files:
bash
{baseDir}/watch.sh ./uploads --command "echo 'File deleted'" --events delete
监控并重新构建：
bash
{baseDir}/watch.sh ./src --command "npm run build" --debounce 1
监控新日志文件：
bash
{baseDir}/watch.sh ./logs --command "./new-log.sh" --events create
监控配置文件并重启服务：
bash
{baseDir}/watch.sh --file config.json --command "pm2 restart app"
监控多个文件：
bash
{baseDir}/watch.sh --files "config.json,.env,package.json" --command "npm run build"
后台监控：
bash
{baseDir}/watch.sh ./src --command "make" --daemon --pidfile /tmp/watcher.pid
监控文件删除：
bash
{baseDir}/watch.sh ./uploads --command "echo 'File deleted'" --events delete

Debouncing

防抖机制

The 
--debounce
option prevents rapid-fire commands:
  • --debounce N
    : Wait N seconds after the last event before running the command
  • --debounce-file
    : Track debounce per file independently
bash
undefined
--debounce
选项可避免频繁执行命令：
  • --debounce N
    : 最后一次事件发生后等待N秒再执行命令
  • --debounce-file
    : 为每个文件单独跟踪防抖计时
bash
undefined

Wait 2 seconds after last change

最后一次变更后等待2秒再执行

{baseDir}/watch.sh ./src --command "build.sh" --debounce 2
{baseDir}/watch.sh ./src --command "build.sh" --debounce 2

Debounce per file (each file gets its own timer)

按文件单独防抖（每个文件拥有独立计时器）

{baseDir}/watch.sh ./src --command "process.sh" --debounce-file --debounce 1
undefined
{baseDir}/watch.sh ./src --command "process.sh" --debounce-file --debounce 1
undefined

Notes

注意事项

  • Uses inotifywait (Linux) or fswatch (macOS) when available
  • Falls back to polling on systems without native support
  • Command receives 
    $FILE
    and 
    $EVENT
    environment variables
  • Recursive by default for directories
  • Can watch thousands of files efficiently
  • Clean shutdown with SIGTERM or SIGINT
  • 系统支持时会使用inotifywait（Linux）或fswatch（macOS）
  • 无原生支持的系统会回退到轮询模式
  • 命令会接收
    $FILE
    和
    $EVENT
    环境变量
  • 默认递归监控目录
  • 可高效监控数千个文件
  • 可通过SIGTERM或SIGINT信号优雅关闭

Dependencies

依赖

  • Linux: 
    inotifywait
    (inotify-tools package)
  • macOS: 
    fswatch
    (brew install fswatch)
  • Both: Polling fallback with 1-second interval
  • Linux: 
    inotifywait
    （来自inotify-tools包）
  • macOS: 
    fswatch
    （通过brew install fswatch安装）
  • 通用：轮询回退模式，间隔1秒