watchexec

• New feature: --watch-file (#849)
• Fix: manpage entry in deb/rpm packagings

• Regression: -w, --watch was accidentally set to behave as -W (#828)

• New: -W, --watch-non-recursive for watching paths without also watching subfolders.
• New: out-of-tree git repositories are now detected (i.e. when .git is a file rather than a folder)
• Logs are also improved slightly with less nonsense at startup.

This is the first breaking release. Most of it is cleaning up a number of deprecated options, and changing some defaults. The idea, however, is to start a new era of Watchexec releases, where breaking changes are allowed more easily (to give an idea of how breaking-change-averse the project has been: this release was planned in January 2022! and ever-delayed since).

Fear not! The cadence of breaking releases will be at most once or twice a year, and whenever possible a deprecation will precede a break by at least three months. Watchexec will remain a stable part of your workflow, while allowing ourselves some evolution.

• Shell default changes to $SHELL when it is present. (#210)
  Use --shell=sh to switch back if your $SHELL is something else.
• Shell default changes to Powershell on Windows when Watchexec detects it is running in Powershell. (#80)
  Use --shell=cmd to switch back to CMD.EXE, or set the SHELL environment variable.
  A reminder that Windows 7 is not supported, and hasn't been for years.
• --on-busy-update defaults to do-nothing now (was queue).
  Events received while a command is running won't trigger a run of the command immediately following this one.
• -W / --watch-when-idle is removed, as it is now the default.
• The default for --stop-timeout is now 10 seconds.
• --debounce, --delay-run, --poll, and --stop-timeout now prefer durations with a unit, and warn if given unit-less durations. The default units for these are millisecond for --debounce and --poll, and seconds for --delay-run and --stop-timeout, which is a source of confusion. Unit-less durations will be removed in a future breaking release.
• --no-shell is removed.
  Use --shell=none instead. The -n short option remains as an alias to --shell=none.
• -k / --kill is removed.
  Use --signal=KILL instead.
• --changes-only is removed.
  Use --print-events instead.
• --emit-events-to defaults to none, and the environment mode is deprecated.
• --emit-events-to no longer accepts stdin (deprecated alias for stdio) and json-stdin(deprecated alias for json-stdio).
• --no-ignore is removed.
  Use --no-project-ignore instead.
• --no-environment is deprecated.
• --clear=reset will reset the screen on graceful shutdown. (#797)
• --no-process-group is deprecated.
• Watchexec no longer warns (nor does anything else) when it sees the deprecated WATCHEXEC_FILTERER environment variable.

Improvements

• New: --wrap-process=MODE lets you choose between using process groups, process sessions, or nothing at all. (#794)
• New: the WATCHEXEC_TMPDIR environment variable can be used to customize where Watchexec will write temporary files, if for some reason your $TMPDIR is unwritable. (#814)
• Fix: watchexec no longer creates a temporary file at startup. (#814)
• Fix: the screen is no longer cleared on all events, only when starting a new process. (#809)

Experimental new feature

As a treat, this release also features an experimental new option: -j or --filter-prog, which lets you write filter programs.

-j, --filter-prog EXPRESSION

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. In addition to the jaq stdlib, watchexec adds some custom filter definitions:

• 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!

Examples:

Regexp ignore filter on paths:

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

Pass any event that creates a file:

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

Pass events that touch executable files:

any(.tags[] | select(.kind == "path" && .filetype == "file"); .absolute | metadata | .executable)

Ignore files that start with shebangs:

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

More examples can be found and contributed in the discussion thread

Software development often involves running the same commands over and over. Boring! Watchexec is a simple, standalone tool that watches a path and runs a command whenever it detects modifications. Install it today with cargo-binstall watchexec-cli, from the binaries below, find it in your favourite package manager, or build it from source with cargo install watchexec-cli.

In this release:

• Fix compatibility with 32-bit platforms (#730)
• Fix bugs introduced by inconsistent path normalisation in optimised ignore handling (#759)

Software development often involves running the same commands over and over. Boring! Watchexec is a simple, standalone tool that watches a path and runs a command whenever it detects modifications. Install it today with cargo-binstall watchexec-cli, from the binaries below, find it in your favourite package manager, or build it from source with cargo install watchexec-cli.

In this release:

• Startup performance improvements reducing the amount of directories visited when discovering ignore files. (#663 by @t3hmrman)
• Improvements to handling of nested ignore files. (#745 by @thislooksfun)

Other changes:

• Project origin detection tweaked a little to avoid some false positives. (#748)

Software development often involves running the same commands over and over. Boring! Watchexec is a simple, standalone tool that watches a path and runs a command whenever it detects modifications. Install it today with cargo-binstall watchexec-cli, from the binaries below, find it in your favourite package manager, or build it from source with cargo install watchexec-cli.

In this release:

• Fix queueing behaviour (#726, #734, #735)

Other changes:

• Optional eyra support (#728)

Software development often involves running the same commands over and over. Boring! Watchexec is a standalone tool that watches a path and runs a command whenever it detects modifications. Install it today with cargo-binstall watchexec-cli, from the binaries below, find it in your favourite package manager, or build it from source with cargo install watchexec-cli.

In this release:

• Fix bug where @argfile arguments were parsed from beyond the -- separator. (#717, #720)
• Fix bug where Ctrl-C would kill Watchexec, but not the command within (#716, #721)

Software development often involves running the same commands over and over. Boring! Watchexec is a simple, standalone tool that watches a path and runs a command whenever it detects modifications. Install it today with cargo-binstall watchexec-cli, from the binaries below, find it in your favourite package manager, or build it from source with cargo install watchexec-cli.

In this release:

• New: start/stop messages are now in colour. Use --colour=never (--color also accepted) to disable, or the conventional always and auto. (#144, #237, #698)
• New: --timings to print how long the command took. (#278, #698)
• New: --quiet to disable printing any message (except warning and error logs). (#698)
• New: --bell to ring the terminal bell on command end. (#238, #698)
• New: --ignore-nothing to switch on all the --no-*-ignore flags. (#275, #625, #695)
• New: --only-emit-events disables launching a command, and only prints events to stdout. Requires --emit-events-to to specify the format to print. This lets you obtain a stream of change events to handle directly rather than mediating via a command. (#676, #691)
• New: --map-signal to map signals received by Watchexec to other signals sent to the command. (#151, #387, #710)
• Change: --emit-events-to stdin and json-stdin modes are renamed to stdio and json-stdio respectively; the old names are aliased to preserve compatibility.

Other changes:

• Uses the Watchexec library 3.0. (#601)
• -w /dev/null disables watching any files. This is the literal string /dev/null, it won't detect the null device via links or fifos. (#601)
• Running as PID1 (e.g. in Docker) is fully supported. (#140, #601, #624)
• Performance improvements and bugfixes around reaping processes (via command-group 5). (#601)
• Performance improvements and bugfixes around watching files (via notify 6). (#601)
• Clear the screen before printing events, so --print-events and --clear can meaningfully be used together. (#601)
• Hint that more or less help is available with long --help and short -h flags. (#601)
• The PDF version of the manual page is gone, due to the tooling I used disappearing, and the general ugliness of its typesetting. (#710)

Software development often involves running the same commands over and over. Boring! Watchexec is a simple, standalone tool that watches a path and runs a command whenever it detects modifications. Install it today with cargo-binstall watchexec-cli, from the binaries below, find it in your favourite package manager, or build it from source with cargo install watchexec-cli.

In this release:

• Don't search for project, global ignores when --no-project-ignore, --no-global-ignore are given respectively (#644, #643)
• Add --no-discover-ignore which implies --no-project-ignore, --no-global-ignore, and --no-vcs-ignore and completely disables ignore discovery — useful on very large repos (#645)

Other changes:

• Restore -d short flag (for --debounce) which got removed by accident (#635)
• Clippy and dependency updates (#646)

Software development often involves running the same commands over and over. Boring! Watchexec is a simple, standalone tool that watches a path and runs a command whenever it detects modifications. Install it today with cargo-binstall watchexec-cli, from the binaries below, find it in your favourite package manager, or build it from source with cargo install watchexec-cli.

In this release:

• Handle nested gitignores properly (#580, #578)
• Fix ignores on Windows (#580, #487)

Software development often involves running the same commands over and over. Boring! Watchexec is a simple, standalone tool that watches a path and runs a command whenever it detects modifications. Install it today with cargo-binstall watchexec-cli, from the binaries below, find it in your favourite package manager, or build it from source with cargo install watchexec-cli.

In this release:

• Paths on windows are normalised to unix format prior to being filtered. Windows-style patterns still work, but unix-style patterns will also now work (better). (#487, #546, #558)
• Options that would send signals to processes are ignored on Windows, as we don't have support for non-kill signals there. (#219, #544, #559)

Software development often involves running the same commands over and over. Boring! Watchexec is a simple, standalone tool that watches a path and runs a command whenever it detects modifications. Install it today with cargo-binstall watchexec-cli, from the binaries below, find it in your favourite package manager, or build it from source with cargo install watchexec-cli.

In this release:

• Fix --restart and --stop-timeout (#544, #548)
• Fix process group not always being killed on restart (#274, #549)

Software development often involves running the same commands over and over. Boring! Watchexec is a simple, standalone tool that watches a path and runs a command whenever it detects modifications. Install it today with cargo-binstall watchexec-cli, from the binaries below, find it in your favourite package manager, or build it from source with cargo install watchexec-cli.

In this release:

• New: --emit-events-to <mode> provides alternative ways to receive event details. To the environment mode, equivalent to the previous behaviour (and still the default), the file, stdin, json-file, and json-stdint modes are added. The watchexec-events crate can be used to parse the JSON format from Rust programs.
• New: --fs-events <events> provides a more flexible way to filter which kinds of filesystem events cause command runs. The --no-meta option is now an alias to the configuration of this method omitting metadata changes.
• New: --clear=reset performs a stronger screen clear (roughly equivalent to a tput reset).
• Whole new extended help, manual page, and completion scripts (now for bash, elvish, fish, nu, and powershell in addition to zsh).
• New: --manual shows the manual page, --help shows extended help (-h shows short help), --completion <shell> prints a completion script, such that even installing from source can benefit from the manpage or completions.

Other changes:

• New: --filter-file and --ignore-file provide ways to load arbitrary ignore files, and also "filter files", which should be formatted like ignore files but patterns are treated the same as --ignore patterns.
• New: --stop-signal lets you override the signal used to stop the process during a restart.
• New: --stop-timeout lets you override the time waited between sending a signal and killing the process (which defaults to 30 seconds).
• --log-file's path argument is now optional. Providing the bare --log-file option uses the current directory. Further, the option also accepts a directory instead of a file, in which case it will create a file named watchexec.<timestamp>.log there.
• --poll is the new name for --force-poll (the old name exists as an alias), and the polling interval is now optional, with a default provided if no value is given.
• All options that take durations now both take numbers in the unit described, but also expressions of the form 2mins 30s. This is a very similar format as systemd's durations, implemented by the humantime crate.
• Removed support for the "tagged" filterer experiment.
• The long --version option now prints extended version information, including the build date and commit hash (where that information is available). This is powered by a new crate, bosion.

Software development often involves running the same commands over and over. Boring! Watchexec is a simple, standalone tool that watches a path and runs a command whenever it detects modifications. Install it today with cargo-binstall watchexec-cli, from the binaries below, find it in your favourite package manager, or build it from source with cargo install watchexec-cli.

In this release:

• Running as PID 1 (for examples, in a container) is now partially supported. Watchexec will properly exit, but may not behave exactly like an init program should. (#140, #497)
• Fixed a critical bug due to Rust 1.66 changing a behaviour. (#494)

Other changes:

• Added checksum files that are per-file as well as the bulk SUMS files, and added sha256 sums. (#500)
• Added dist-manifest.json (#500)

Software development often involves running the same commands over and over. Boring! Watchexec is a simple, standalone tool that watches a path and runs a command whenever it detects modifications. Install it today with cargo-binstall watchexec-cli, from the binaries below, find it in your favourite package manager, or build it from source with cargo install watchexec-cli.

In this release:

• New: --stdin-quit makes watchexec exit when STDIN closes, which avoids zombies when running with Elixir. (#440, #449)
• Clearscreen improvements on systems without a functioning terminfo database. (#463)

Other changes:

• MSRV bumped to 1.61.0
• ZSH autocomplete fixes (#417)
• Artifacts are not signed due to a process failure. A new more standard signing setup is being prepared for next release.

Software development often involves running the same commands over and over. Boring! Watchexec is a simple, standalone tool that watches a path and runs a command whenever it detects modifications. Install it today with cargo-binstall watchexec-cli, from the binaries below, find it in your favourite package manager, or build it from source with cargo install watchexec-cli.

In this release:

• Origins: detect Go, Zig, Pip (#370)
• Docs: document known packages, and prioritise package managers in documentation
• Deps: update notify to 5.0.0 (#382, #384)
• Releng: use cargo-bins/release-pr
• Releng: change tag scheme. CLI versions are tagged v1.2.3, all other crates are strictly {crate-name}-v1.2.3. Historical tag names are preserved as aliases.

Other changes:

• Deps: update miette to 5.3.0 (#406)
• Deps: update git-config to 0.7.1 (#406)
• Releng: enable dependency updates (#394)
• Releng: remove bors

• Fix: mimalloc was set as the global allocator in the watchexec library, instead of leaving it to downstreams. (#369)
• Releng: s390x and ppc64le targets were added to be prebuilt. (#373)

• Remove CLI help tests. They'll be replaced with brand new integration testing that's not obnoxious. (#362, #363, #365)
• Fix the install filenames for first-party RPM packagings, and possibly for DEBs as well. (#292, #364)

• Dependencies are set manually for first-party deb and rpm packages, so they should install without error. A note that these are provided on a best-effort basis and not tested; when available you should prefer your distribution's packaging. (#292, #358)