watchexec

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.

• Fix --restart (#346, #353)
• Restore being able to use --signal with --restart (#353)
• Have windows builds in releases again (#356)
• Simplify logging levels, and make -v (info) more useful with actual, but sparse, information (#260, #354)

• Fix various crashes on start, mostly to do with option parsing (#345, #347, #348, #349, #350)
• Fix initialisation of logging systems with error handling (being louder) and a less brute-force approach (#348)
• Add runtime and --help warnings when running or building with non-standard options (#348)
• Allow non-UTF8 argument values for paths (and --exts, as a "path fragment") (#345, #349, #350)

Yanked on 2022-06-29

• Watchexec should not refuse to quit if there are too many events anymore. (#302, lib 2.0.0)
• The help text is reorganised in semantic sections rather than options/flags. (#304)
• Verbose logs now may include even more logging (from third-party libraries). (#300)
• All arguments must now be valid UTF-8. Previously the command and the -E flag would accept but silently discard invalid UTF-8, now watchexec errors on such input. (#317)
• New --log-file option makes it easier to collect logs without polluting the screen. (#321)
• New --delay-run option adds a configurable sleep before running the command. A native, cross-platform alternative to sleep N; command...! (#79)

Additionally, some repo changes:

• PRs are now exclusively merged by Bors, and pushing directly to main is not allowed.
• There's a PR-based (and thus Bors-assisted) release workflow, rather than initiating releases from a local checkout. For example, this release was made with PR #337.
• Github Discussions are enabled, and should be used for asking questions, discussing the project or features, and comments on releases. Feature requests and bug reports should go to the Issues as before.
  • One exception is discussion of "Known Issues", which has its own topic to keep the Issues list focused on discrete problems.
• The scheme for releases has changed slightly: only CLI releases will show up in GitHub releases, so the /latest link will always point to the last CLI release; the library and other crates now have their own, file-based CHANGELOG.md.

Not directly related to the CLI, but the library 2.0.0 version has now been released as stable! Full semver applies again.

Known issue with some packages: DEB and RPM packages may be missing dependencies due to being auto-generated instead of lovingly handcrafted. Prefer distributions from packagers rather than these ones, which are just provided on an ad-hoc, if convenient, as-is, basis.

• Decrease default debounce timeout to 50ms (#168).
• Add notice that the --shell default will be changing on Unix (#210).
• New option --project-origin provides an override which can be useful when the project origin is misdetected, or if you want to stop watchexec from looking for ignore files in (some) parent directories (#246).
• New option --workdir sets the command's working directory independent of Watchexec's.
• New option --env (short: -E) adds environment variables to the command without affecting Watchexec itself.

• We no longer depend on libgit2 (#267)
• Project origin resolution will no longer consider the home directory unless explicitly requested (#277)

• Replace git2 dependency by git-config (#267). This makes using the library more pleasant and will also avoid library version mismatch errors when the libgit2 library updates on the system.

• Bugfix: missed failure condition in project origin resolution (#271)

• Find project origin for all paths, including implicit . when no -w are passed. (#270)

• Partial revert of last release to fix a critical bug on Mac (#269)

Revert backend switch on mac from previous release. We'll do it a different way later (#269)

• Upgraded to Notify pre.14
• Internal change: kqueue backend is used on mac. This should reduce or eliminate some old persistent bugs on mac, and improve response times, but please report any issues you have!
• Watchexec::new() now reports the library's version at debug level
• Notify version is now specified with an exact (=) requirement, to avoid breakage (#266)

• New error::FsWatcherError enum split off from RuntimeError, and with additional variants to take advantage of targeted help text for known inotify errors on Linux
• Help text is now carried through elevated errors properly
• Globset filterer: extensions and filters are now cooperative rather than exclusionary. That is, a filters of ["Gemfile"] and an extensions of ["js", "rb"] will match both Gemfile and index.js rather than matching nothing at all. This restores pre 2.0 behaviour.
• Globset filterer: on unix, a filter of */file will match both file and dir/file instead of just dir/file. This is a compatibility fix and is incorrect behaviour which will be removed in the future. Do not rely on it.

• The on_error handler gets an upgraded parameter which lets it upgrade (runtime) errors to critical.
• summarize_events_to_paths now deduplicates paths within each variable.

• Action, PreSpawn, and PostSpawn structs passed to handlers now contain an Arc<[Event]> instead of an Arc<Vec<Event>>
• Outcome processing (the final bit of an action) now runs concurrently, so it doesn't block further event processing (#247, and to a certain extent, #241)

• Fix: globset filterer should pass all non-path events (#248)

Yanked for critical bug in globset (fixed in pre.8) on 2022-01-26

• Fix: typo in logging/errors (#242)
• Globset: an extension filter should fail all paths that are about folders (#244)
• Globset: in the case of an event with multiple paths, any pass should pass the entire event
• Removal: filter::check_glob and error::GlobParseError

This is the first release built on top of Watchexec library 2.0. Any change in behaviour other than listed below is a bug.

• Verbose mode is now more configurable, with -v, -vv… up to -vvvv printing increasingly more logs. Note that -v already prints a lot more logs than in previous releases, and that the log format has changed. Additionally, the RUST_LOG environment variable can be set for even finer-grained logging.
• --changes-only was renamed to --print-events, and its output changed. The former option persists as an alias for compatibility but will be removed eventually.
• --no-ignore was renamed to --no-project-ignore for clarity. The former option persists as an alias for compatibility but will be removed eventually.
• When the command ends with a non-0 exit code, or by a signal, or a Windows exception, a message is printed (e.g. [[Command exited with 63]]) (#37)
• The --notify / -N option now works properly, and is therefore out of experimental.
• Finding the "project origin" now considers other VCSs and many software development tooling conventions.
• Ignore file loading has been improved, with support for:
  • global VCS ignores (e.g. ~/.gitignore, ~/.bazaar/ignore) (#58)
  • global Git excludes (i.e. as configured in git config core.excludesFile)
  • local project git excludes (i.e. .git/info/exclude)
  • more VCS ignore files (for Mercurial, Darcs, Fossil, Bazaar) (nb gitignore syntax is assumed)
  • a watchexec-specific global ignore file in ~/.config/watchexec/ignore or as system-appropriate
  • any files listed in the new WATCHEXEC_IGNORE_FILES environment variable (format is as for the system PATH variable)
  • contextual ignores: git ignores won't be loaded for a Mercurial project, for example.
  • correct ignore file parsing, notably around folder patterns.
• The environment variables set on the command have a number of minor changes:
  • paths are absolute
  • WATCHEXEC_COMMON_PATH is always set, with the common prefix of all paths
  • WATCHEXEC_OTHERWISE_CHANGED_PATH is new, for event kinds not covered by the other five (CREATED, META_CHANGED, REMOVED, RENAMED, WRITTEN)
  • within each envvar, paths are sorted (with binary ordering).
• Permission and other errors encountered when watching files are now reported with the concerned file path, when available. (#149)
• Basic Pijul support was added.
• Some errors are now not fatal: they are reported to STDERR but won't cause a crash.
• Mimalloc is used for musl builds, which may improve performance and reduce memory use. This is only done on musl because its default allocator is so terrible. Non-musl builds use the system allocator.

Note that this release is not coincidental with the stable release of the library 2.0, which is still "in preview."

When installing from the DEB packages, a prior version may need to be uninstalled first, see #233.

New experimental filter engine

Set WATCHEXEC_FILTERER=tagged to opt into a new filter engine. This will disable the -e / --exts and -i / --ignore options and change the -f / --filter option to accept a "tagged filter" instead.

Documentation is available at: https://docs.rs/watchexec/2.0.0-pre.6/watchexec/filter/tagged/struct.TaggedFilterer.html

For example, this set of filters:

path=data/*.json
path*!test-*
kind=Create(*)

would only allow file creation events from JSON files in data/ except those starting with test-.

There are 8 "tags" that can be matched upon, including path, kind (of the event: creates, modifies, metadata, etc), type (of the path that was changed: file, folder, link, etc). There is a variety of operators: glob (*= and *!), exact (== and !=), sets (:= and :!), and regex (~= and ~!). The shorthand = operator resolves to the "most useful" operator for the tag being matched (currently *= for path, kind, and exit, := otherwise). This provides a lot more power and flexibility, but does make filtering less intuitive — ideas are welcome on improvements.

The tagged filterer also solves the current filterer's main confusing issue: folder filtering. path=folder/ and path!*folder/ will do the expected thing, instead of requiring obscure forms like **/folder/**.

Using the --filter-file / -F option, one or more "tagged filter files" can be loaded, with every filter on a new line. Blank lines and lines starting with # are ignored. Like for ignore files, the WATCHEXEC_FILTER_FILES envvar is also consulted, and the ~/.config/watchexec/filter global filter file applies if present (or in system-relevant location). There is no default project-local filter file.

This mode is experimental: it is not to be considered stable in any way. Using it will print a warning message when watchexec starts. The aim is to have it become good enough so it can be the default in a future breaking release (but not 2.0, which will instead focus on other long-standing issues which aren't as earth-shattering as this), or to use its ideas to improve the existing implementation, whichever ends up better for everyone!

Thanks

This release comes with special thanks to Radon Rosborough, supporting me via Ko-fi.