mise watch

• 用法： mise watch [FLAGS] [TASK] [ARGS]…
• 别名： w
• 源代码： src/cli/watch.rs

Run tasks and rerun them when files change

Runs the tasks with mise run under watchexec, then reruns them whenever one of their sources changes, including the sources of their dependencies unless you pass --skip-deps. When no selected task declares sources, watchexec watches the current directory. With no task, runs the default task.

Choose what to watch with --watch, --exts, and --filter, and use --print-events to see what triggered a run. Arguments for the task go after --. Requires watchexec, which mise use -g watchexec installs.

To keep a server or database running alongside your tasks, with readiness checks and automatic restarts, see mise daemons (experimental): https://mise.jdx.dev/daemons.html. For cron scheduling and standalone process management, see pitchfork: https://pitchfork.jdx.dev

Arguments

• [TASK] — Task to watch (default: default); separate several tasks with :::
• [ARGS]… — Arguments for the task; ::: starts the next task

Flags

• -g --glob <GLOB> — Globs to watch instead of the tasks' sources

• --skip-deps — Run and watch only the named tasks, not the tasks they depend on

• -o --on-busy-update <MODE> — What to do when files change while the tasks are running

  do-nothing (the default) ignores the change, so files the tasks write do not trigger another run. queue runs the tasks again when the current run finishes. restart stops the running tasks and starts them again. signal sends the --signal signal and keeps the tasks running, for programs that reload their configuration on a signal.

  选项： queue、do-nothing、restart、signal

  Default: do-nothing

• -r --restart — Restart the tasks if they are still running when files change

  Same as --on-busy-update=restart.

• -s --signal <SIGNAL> — Signal to send to the running tasks when files change

  Implies --on-busy-update=signal. Accepts the same forms as --stop-signal. Signals are not supported on Windows, where the tasks are always killed.

• --stop-signal <SIGNAL> — Signal that stops the tasks before a restart (default on Unix: SIGTERM)

  Used by the restart and signal modes of --on-busy-update unless --signal is given. Accepts a full name (SIGTERM), a short name (TERM), or a number (15), in any case. If the tasks have not exited after --stop-timeout, they are killed. On Windows the tasks are always killed.

• --stop-timeout <TIMEOUT> — How long to wait for the tasks to stop before killing them (default: 10s)

  Takes a duration such as 5s or 1min 20s. Set it to 0 to kill the tasks right away. Has no effect on Windows, where the tasks are always killed.

  Default: 10s

• --map-signal <SIGNAL:SIGNAL> — Translate a signal that watchexec receives into one it sends to the tasks

  Takes two signal names separated by a colon, such as TERM:INT. Leave out the second name to discard the first signal (TERM:). A mapped SIGINT or SIGTERM no longer stops watching; INT:INT passes Ctrl-C to the tasks without stopping watchexec. Repeat the flag to map several signals.

• -d --debounce <TIMEOUT> — How long to wait for more changes before running (default: 50ms)

  One save can produce several events, and a file can be written in pieces, so watchexec waits this long after an event before running the tasks. Takes a duration such as 500ms or 2s.

  Default: 50ms

• --stdin-quit — Exit when stdin closes

• -p --postpone — Wait for the first change before running the tasks

• --delay-run <DURATION> — Wait this long after a change before running the tasks, e.g. 5s

• --poll [INTERVAL] — Poll for changes instead of using native file watching

  Use it on file systems where native events do not work, such as network shares. Takes an optional interval such as 2s (default: 30s). Also accepted as --force-poll.

• --project-origin <DIRECTORY> — Set the project origin

  项目起点用于确定某些忽略文件的路径、正在使用的 VCS、过滤模式中开头的 '/' 的含义，以及未来可能增加的其他内容。

  设置后，Watchexec 也不会再执行搜索，从而可以显著加快速度。

• --workdir <DIRECTORY> — 设置工作目录

  When set, Watchexec will also not bother searching, which can be significantly faster.

  The directory must contain every watched task's sources, which mise makes relative to it.

• -h --help — Print help

Filtering

• -w --watch <PATH> — Watch a file or directory

  By default, mise watches each task's directory and any source directory outside it, and filters events to the tasks' sources. When no task declares sources, watchexec watches the current directory. Paths given here are added to the task directories, or replace the current-directory default when there are no sources. Events are still filtered to the sources, so use --filter to widen what triggers a rerun.

  To watch a single file, watch its directory and filter on the file name instead: some editors replace a file when they save it, and some platforms do not report changes to the replacement. Repeat the flag to watch several paths.

• -W --watch-non-recursive <PATH> — Watch a directory without recursing into it

  Repeat the flag to watch several directories.

• -F --watch-file <PATH> — Read paths to watch from a file, one per line

  Each line is treated like a --watch value. The value - reads from stdin and cannot be combined with --stdin-quit.

• --no-vcs-ignore — Do not apply Git and other version control ignore files

  Use it to watch files that Git ignores. A task can turn this on for itself with watch = { no_vcs_ignore = true }.

• --no-project-ignore — Do not apply ignore files in the project, such as .gitignore and .ignore

• --no-global-ignore — Do not apply global ignore files, such as ~/.gitignore and ~/.config/watchexec/ignore

• --no-default-ignore — Do not apply watchexec's built-in ignores

  They cover editor swap files, *.pyc, .DS_Store, and version control directories such as .git.

• --no-discover-ignore — Do not look for ignore files at all

  Same as --no-global-ignore --no-vcs-ignore --no-project-ignore, but faster. Built-in ignores still apply.

• --ignore-nothing — Ignore nothing

  Same as --no-discover-ignore --no-default-ignore. Patterns from --ignore and --ignore-file still apply.

• -e --exts <EXTENSIONS> — Only react to files with these extensions, e.g. js,ts

  Give extensions with or without the leading dot. Repeat the flag or separate extensions with commas.

• -f --filter <PATTERN> — Only react to files that match this glob

  Combined with the patterns mise derives from the tasks' sources. Repeat the flag for more patterns. Events that do not come from files, such as signals, pass through.

• --filter-file <PATH> — Files to load filters from

  环境变量： WATCHEXEC_FILTER_FILES

• -J --filter-prog <EXPRESSION> — [实验性] 过滤程序。

  /!\ 此选项为实验性功能，可能会在不另行通知的情况下发生变化或消失。

  使用 jaq（类似于 jq）语法提供自定义过滤程序。程序会接收一个事件，格式与 '--emit-events-to' 中所述的格式相同，并且必须返回布尔值。无效程序会导致 watchexec 启动失败；使用 '-v' 查看程序运行时错误。

  除 jaq 标准库外，watchexec 还添加了一些自定义过滤器定义：

  Provide your own custom filter programs in jaq (similar to jq) syntax. Programs are given an event in the same format as described in '--emit-events-to' and must return a boolean. Invalid programs will make watchexec fail to start; use '-v' to see program runtime errors.

  • 'path | file_size' 返回路径中文件的大小；如果文件不存在，则返回 null。

  • 'path | file_meta' returns file metadata or null if the file does not exist.

  • 'path | file_size' returns the size of the file at path, or null if it does not exist.

  • 'path | file_read(bytes)' returns a string with the first n bytes of the file at path. If the file is smaller than n bytes, the whole file is returned. There is no filter to read the whole file at once to encourage limiting the amount of data read and processed.

  • 'string | hash', and 'path | file_hash' return the hash of the string or file at path. No guarantee is made about the algorithm used: treat it as an opaque value.

  • 'any | kv_store(key)', 'kv_fetch(key)', and 'kv_clear' provide a simple key-value store. Data is kept in memory only, there is no persistence. Consistency is not guaranteed.

  • 'any | printout', 'any | printerr', and 'any | log(level)' will print or log any given value to stdout, stderr, or the log (levels = error, warn, info, debug, trace), and pass the value through (so '[1] | log("debug") | .[]' will produce a '1' and log '[1]').

  All filtering done with such programs, and especially those using kv or filesystem access, is much slower than the other filtering methods. If filtering is too slow, events will back up and stall watchexec. Take care when designing your filters.

  If the argument to this option starts with an '@', the rest of the argument is taken to be the path to a file containing a jaq program.

  Jaq programs are run in order, after all other filters, and short-circuit: if a filter (jaq or not) rejects an event, execution stops there, and no other filters are run. Additionally, they stop after outputting the first value, so you'll want to use 'any' or 'all' when iterating, otherwise only the first item will be processed, which can be quite confusing!

  Find user-contributed programs or submit your own useful ones at <https://github.com/watchexec/watchexec/discussions/592>.

  示例：

  对路径使用正则表达式忽略过滤器：

  'all(.tags[] | select(.kind == "path"); .absolute | test("[.]test[.]js$")) | not'

  传递创建文件的任意事件：

  'any(.tags[] | select(.kind == "fs"); .simple == "create")'

  传递涉及可执行文件的事件：

  'any(.tags[] | select(.kind == "path" and .filetype == "file"); .absolute | file_meta | .executable)'

  忽略以 shebang 开头的文件：

  'any(.tags[] | select(.kind == "path" and .filetype == "file"); .absolute | file_read(2) == "#!") | not'

• -i --ignore <PATTERN> — Ignore files that match this glob

  Repeat the flag for more patterns. Events that do not come from files, such as signals, pass through.

• --ignore-file <PATH> — Read ignore patterns from a file, one per line

  Empty lines and lines that start with # are skipped. The patterns use the same format as --ignore. Also read from $WATCHEXEC_IGNORE_FILES.

  环境变量： WATCHEXEC_IGNORE_FILES

• --fs-events <EVENTS> — 要过滤的文件系统事件

  这是一个快速过滤器，仅发出指定类型的文件系统更改事件。可选类型包括 'access'、'create'、'remove'、'rename'、'modify'、'metadata'。可以重复此选项或使用逗号分隔来指定多个类型。默认情况下，包含除 'access' 之外的所有类型。

  在可能的情况下，这可能会在内核级别应用过滤，从而提高效率，但阅读日志时可能更容易造成困惑。

  选项： access、create、remove、rename、modify、metadata

  默认值： create,remove,rename,modify,metadata

• --no-meta — 不为元数据更改发出文件系统事件

  这是 '--fs-events create,remove,rename,modify' 的简写。与 '--fs-events' 选项同时使用没有意义，也不被允许。

Output

• -c --clear [MODE] — Clear the screen before each run

  If the default clear mode leaves output behind, use --clear=reset. Because the mode is optional, mise watch --clear build reads build as the mode: put --clear after the task name, as in mise watch build --clear, or write the mode with =.

  选项： clear、reset

• --only-emit-events — 仅向 stdout 发出事件，不运行命令。

  这是将 Watchexec 用作文件监视器的便利选项，不运行任何命令。它几乎等同于使用 cat 作为命令，但不会为每个事件生成一个新进程。

  此选项要求设置 --emit-events-to，并将可用模式限制为 stdio 和 json-stdio，同时修改它们的行为，使其写入 stdout，而不是写入命令的 stdin。

• -N --notify — 在命令开始和结束时发出提醒

  启用此选项后，在支持的平台上，Watchexec 会在命令开始和结束时发出桌面通知。在不支持的平台上，它可能静默不执行任何操作，或记录警告。

• --color <MODE> — 何时使用终端颜色

  将环境变量 NO_COLOR 设置为任意值等同于使用 --color=never。

  选项： auto、always、never

  默认值： auto

• --timings — 打印命令运行所需的时间

  This may not be exactly accurate, as it includes some overhead from Watchexec itself. Use the time utility, high-precision timers, or benchmarking tools for more accurate results.

• --watchexec-quiet — Don't print starting and stopping messages

  By default Watchexec will print a message when the command starts and stops. This option disables this behaviour, so only the command's output, warnings, and errors will be printed.

  This is watchexec's '--quiet'. In mise, '-q'/'--quiet' quiets mise's own messages, as it does for every other command.

• --bell — Ring the terminal bell on command completion

命令

• --shell <SHELL> — 使用其他 shell

  默认情况下，在类 Unix 系统上，Watchexec 会使用已定义的 '$SHELL'，否则使用默认的 'sh'；在 Windows 上，则根据 Watchexec 检测到的运行中 shell，使用 'pwsh'、'powershell' 或 'cmd'（CMD.EXE）之一。

  使用此选项可以覆盖默认设置并使用其他 shell，例如功能更多的 shell，或包含你自定义别名和函数的 shell。

  如果值中包含空格，则会将其解析为命令行，并将第一个单词用作 shell 程序，其余部分作为 shell 参数。

  命令会使用 '-c' 标志运行（Windows 上的 'cmd' 除外，其使用 '/C'）。

  特殊值 'none' 可用于完全禁用 shell。在这种情况下，提供给 Watchexec 的命令会被解析，第一个单词作为可执行文件，其余部分作为参数，然后直接执行。请注意，此解析方式较为简单，在某些情况下可能无法按预期工作。

  使用 'none' 的效率略高，并且可以启用对输入更严格的解释，但这也意味着你无法使用 glob、重定向、控制流、逻辑或管道等 shell 功能。

  示例：

  不使用 shell：

  $ watchexec -n -- zsh -x -o shwordsplit scr

  使用 powershell core：

  $ watchexec --shell=pwsh -- Test-Connection localhost

  使用 CMD.exe：

  $ watchexec --shell=cmd -- dir

  使用其他 unix shell：

  $ watchexec --shell=bash -- 'echo $BASH_VERSION'

  使用带选项的 unix shell：

  $ watchexec --shell='zsh -x -o shwordsplit' -- scr

• -n — '--shell=none' 的简写

• --emit-events-to <MODE> — 配置事件发出方式

  Watchexec 在运行命令时可以发出事件信息，子进程可以利用这些信息来定位特定的更改文件。

  需要注意的是，不要把可能性误认为必然行为。 尤其是，表面上看，RENAMED 变量似乎同时包含被重命名文件的原路径和新路径。在之前的版本中，在某些平台上甚至似乎总是原路径先于新路径。然而，这些都不是真的。无法可靠且可移植地判断哪个变更路径是旧路径或新路径；可能出现“半重命名”（只有原路径或只有新路径）、“未知重命名”（变更确实是重命名，但无法知道是旧路径还是新路径），重命名事件可能跨越两个防抖边界，等等。

  此选项控制发出这些信息的位置。默认值为 'none'，表示完全不发出事件信息。其他选项为 'environment'（已弃用）、'stdio'、'file'、'json-stdio' 和 'json-file'。

  'stdio' 和 'file' 模式基于文本：'stdio' 将绝对路径写入命令的 stdin，每行一个，每个路径前缀为 create:、remove:、rename:、modify: 或 other:，然后关闭该句柄；'file' 将相同内容写入临时文件，并通过 $WATCHEXEC_EVENTS_FILE 环境变量提供其路径。

  还有两种 JSON 模式，它们基于 JSON 对象，可以表示 Watchexec 处理的完整事件集合。以下是 Linux 上创建文件夹的示例：

    {
      "tags": [
        {
          "kind": "path",
          "absolute": "/home/user/your/new-folder",
          "filetype": "dir"
        },
        {
          "kind": "fs",
          "simple": "create",
          "full": "Create(Folder)"
        },
        {
          "kind": "source",
          "source": "filesystem"
        }
      ],
      "metadata": {
        "notify-backend": "inotify"
      }
    }

  字段如下：

  • tags, structured event data.
  • tags[].kind, which can be:
    • 'path', along with:
      • absolute, an absolute path.
      • filetype, a file type if known ('dir', 'file', 'symlink', 'other').
    • 'fs':
      • simple, the "simple" event type ('access', 'create', 'modify', 'remove', or 'other').
      • full, the "full" event type, which is too complex to fully describe here, but looks like 'General(Precise(Specific))'.
    • 'source', along with:
      • source, the source of the event ('filesystem', 'keyboard', 'mouse', 'os', 'time', 'internal').
    • 'keyboard', along with:
      • keycode. Currently only the value 'eof' is supported.
    • 'process', for events caused by processes:
      • pid, the process ID.
    • 'signal', for signals sent to Watchexec:
      • signal, the normalised signal name ('hangup', 'interrupt', 'quit', 'terminate', 'user1', 'user2').
    • 'completion', for when a command ends:
      • disposition, the exit disposition ('success', 'error', 'signal', 'stop', 'exception', 'continued').
      • code, the exit, signal, stop, or exception code.
  • metadata, additional information about the event.

  'json-stdio' 模式会将 JSON 事件发送到命令的标准输入，每行一个，然后关闭 stdin。'json-file' 模式会创建一个临时文件，将事件写入其中，并通过 $WATCHEXEC_EVENTS_FILE 环境变量提供文件路径。

  最后，'environment' 模式在 2.0 之前是默认模式。对于文件系统事件，它会设置包含受影响文件路径的环境变量：

  $WATCHEXEC_COMMON_PATH 被设置为以下所有变量中最长的公共路径，因此应将其添加到每个路径前面，以获得完整／实际路径。然后：

  • 创建文件／文件夹时设置 $WATCHEXEC_CREATED_PATH
  • 删除文件／文件夹时设置 $WATCHEXEC_REMOVED_PATH
  • 重命名文件／文件夹时设置 $WATCHEXEC_RENAMED_PATH
  • 修改文件／文件夹时设置 $WATCHEXEC_WRITTEN_PATH
  • 修改文件／文件夹元数据时设置 $WATCHEXEC_META_CHANGED_PATH
  • 对于其他所有类型的带路径事件设置 $WATCHEXEC_OTHERWISE_CHANGED_PATH

  多个路径使用系统路径分隔符分隔；Windows 上为 ';'，unix 上为 ':'。 在每个变量中，路径会去重并按二进制顺序排序（即不考虑 Unicode 或区域设置）。

  这是旧版模式，已弃用，并将在未来移除。环境变量空间非常有限，同时能够有效表示的信息也很有限。大量文件可能导致环境变量被截断，也可能使进程报错或完全崩溃。$WATCHEXEC_COMMON_PATH 也不直观，多年来收件箱中出现的多次困惑咨询就证明了这一点。

  选项： environment、stdio、file、json-stdio、json-file、none

  Default: none

• --watchexec-env <KEY=VALUE> — Add env vars to the command

  这是一个用于为命令设置环境变量的便利选项，不会为 Watchexec 进程本身设置这些变量。

  Use key=value syntax. Multiple variables can be set by repeating the option.

  This is watchexec's '--env'. In mise, '-E'/'--env' selects the mise environment (mise.<ENV>.toml), as it does for every other command.

• --wrap-process <MODE> — How to wrap the task process: group, session, or none

  By default watchexec uses a session on macOS, a process group on other Unix systems, and a Job Object on Windows. Some programs need a session, and some do not work in a process group; none runs the command directly. On Windows, group and session both use a Job Object.

  选项： group、session、none

Debugging

• --print-events — Print the events that trigger each run

  Use it to check which files --watch, --filter, and the tasks' sources are reacting to.

• --manual — Show the manual page

  如果输出目标是终端且 'man' 程序可用，则显示 Watchexec 的手册页。否则，以 ROFF 格式将手册页打印到 stdout（适合写入 watchexec.1 文件）。

Examples

Run build and rerun it whenever its sources change

mise watch build

Clear the screen before each run

mise watch build --clear

Start an API server and restart it when Rust files in ./src change

mise watch serve --watch src --exts rs --restart

Pass arguments after -- to the task

mise watch test -- --verbose

Related documentation

• Rerun tasks when files change.
• All commands.
• Global flags and argument syntax.