watchexec

Bad release, see 1.18.4. Yanked from crates.io on 2022-01-26.

• Everything in Lib pre.7
• Fix: --shell should default to sh on unix, not none (#240)
• Doc: fix glob pattern for ignoring subdirs (#243)

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

• Bugfix: invalid default value for --signal causing a crash on Windows (#239)

• Bugfix: -e can now accept extensions with a leading period again. (#236)

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.

• Globset filterer was erroneously passing files with no extension when an extension filter was specified

• Update MSRV (to 1.58) and policy (bump incurs minor semver only)
• Some bugfixes around canonicalisation of paths
• Eliminate context-less IO errors
• Move error types around
• Prep library readme
• Update deps

• More logging, especially around ignore file discovery and filtering
• The const paths::PATH_SEPARATOR is now public, being : on Unix and ; and Windows.
• Add Subversion to discovered ProjectTypes
• Add common (sub)Filterer for ignore files, so they benefit from a single consistent implementation. This also makes ignore file discovery correct and efficient by being able to interpret ignore files which searching for ignore files, or in other words, not descending into directories which are ignored.
• Integrate this new IgnoreFilterer into the GlobsetFilterer and TaggedFilterer. This does mean that some old v1 behaviour of patterns in gitignores will not behave quite the same now, but that was arguably always a bug. The old "buggy" v1 behaviour around folder filtering remains for manual filters, which are those most likely to be surprising if "fixed".

• summarise_events_to_env used to return COMMON_PATH, it now returns COMMON, in keeping with the other variable names.

• summarise_events_to_env returns a HashMap<&str, OsString> rather than HashMap<&OsStr, OsString>, because the expectation is that the variable names are processed, e.g. in the CLI: WATCHEXEC_{}_PATH. OsStr makes that painful for no reason (the strings are static anyway).
• The Action struct's events field changes to be an Arc<Vec<Event>> rather than a Vec<Event>: the intent is for the events to be immutable/read-only (and it also made it easier/cheaper to implement the next change below).
• The PreSpawn and PostSpawn structs got a new events: Arc<Vec<Event>> field so these handlers get read-only access to the events that triggered the command.

• MSRV bumped to 1.56
• Rust 2021 edition
• More documentation around tagged filterer:
  • == and != are case-insensitive
  • the mapping of matcher to tags
  • the mapping of matcher to auto op
• Finished the tagged filterer:
  • Proper path glob matching
  • Signal matching
  • Process completion matching
  • Allowlisting pattern works
  • More matcher aliases to the parser
  • Negated filters
  • Some silly filter parsing bugs
  • File event kind matching
  • Folder filtering (main confusing behaviour in v1)
• Lots of tests:
  • Globset filterer
  • Including the "buggy"/confusing behaviour of v1, for parity/compat
  • Tagged filterer:
    • Paths
    • Including verifying that the v1 confusing behaviour is fixed
    • Non-path filters
    • Filter parsing
  • Ignore files
  • Filter scopes
  • Outcomes
  • Change reporting in the environment
    • ...Specify behaviour a little more precisely through that process
• Prepare the watchexec event type to be serializable
  • A synthetic FileType
  • A synthetic ProcessEnd (ExitStatus replacement)
• Some ease-of-use improvements, mainly removing generics when overkill

• Experimental: --notify/-N flag sends a desktop notification when a change is observed (which may or may not trigger a command restart). While objectively the better behaviour would be to notify on command finish and vary the notification on exit status, we just can't do that at the moment with the current architecture.

• RPM builds are temporarily disabled due some shifts in the ecosystem not being all caught up yet.

• #168 The default debounce time was further decreased to 100ms.

• #145 New: @path-style argument parsing. (like rustc) You can now specify @argfile as the first argument to watchexec: this will read the file argfile and insert each line as an argument (no need to quote for whitespace, blank lines make empty arguments). This is a rudimentary way to have a configuration file, or as shorthand for established workflows; a more thorough file-based configuration system may be introduced later (#33, #136).

• New: there’s now a website. Some of it is still being drafted, notably dedicated general documentation for this tool, but there’s already some specific documentation that’s been brought over and rewritten/improved, such as the inotify limitations and the glob patterns pages. Eventually a lot of the documentation that’s in readmes and issues will be moved there and improved.

• #158 New: --no-process-group flag to disable process groups.

• New: RPM packages are now available. These are built from the same binaries in the tarballs and DEB packages, so may not work properly for distros due to glibc versions or whatever. Untested as I don’t run RPM-based distros, tell me how it goes.

• New: checksums (BLAKE3 and SHA512) and signatures (minisign) for first-party pre-built packages. See on the website.

• New: fatal errors (panics) will now be displayed via eyre; for a bit of a friendlier look and easier to debug. Hopefully these aren't seen much though!

• Packagers: if you’re reading these notes:

  • The website now has a JSON metadata file for every release and the latest, and that’s probably easier to parse than fighting it out with the API and the filenames. It also has the release notes and the checksums in nicely machine readable locations if you’re into that.
  • The archive format for tarballs will change to ZStandard (.tar.zst) at some point in the future (probably next year).

• Process handling code replaced with the new command-group crate.
• #158 New option use_process_group (default true) allows disabling use of process groups.
• #168 Default debounce time further decreased to 100ms.
• Binstall configuration and transitional cargo install watchexec stub removed.

• #200 When using --watch-when-idle or --on-busy-update=do-nothing, watchexec did not appear to respond to new events after the initial run of the command. This release fixes that.

• #200: Expose when the process is done running
• ba26999028cfcac410120330800a9a9026ca7274 Pin globset to 0.4.6 to avoid breakage due to a bugfix in 0.4.7

• Fix --clear with clearscreen 1.0.4 (ref watchexec/clearscreen#1)

This is a new CLI release only so that the binaries work, if you're using the library running cargo upgrade is sufficient.

• 🍏 New: build config for Apple M1 builds, which will become available sometime in May/June
• 🦾 New: Windows ARM builds
• 🖊️ #99 #185 #171 Use clearscreen library. This should in particular help with the -c flag on Windows, and provide a more consistent experience (as much as is possible) everywhere.
• 🚨 Change: project split into two-package workspace.
  • ⚠️ Use cargo install watchexec-cli when installing via cargo.
  • 📦 Prefer cargo binstall watchexec-cli when installing via cargo-binstall, though cargo binstall watchexec will still work for now but will rapidly stop working well as the versions diverge.
  • ↪️ A stub main.rs is in place which will direct you to install watchexec-cli when using cargo install watchexec. This stub will go away in a future release.
  • 📚 The watchexec crate is now the library only and is versioned separately from the binary, which means semver now applies.

• #191 Bugfix: Type change caused a warning message to have dupe info.
• #192 Bugfix: Windows critical on some (?) versions of Win10 due to XML schemas in the manifest