PolyWatch

File change watcher which gets triggerred by events like file addition, contents update, ownership change or removal and run commands subsequently. It is designed to help in setting up a development environment for some golang services which are all run using live code. By using PolyWatch source code can get recompiled & started automatically on each service code file changes. See hotreload for a working example.

Contents

• Features
• Installation
  • Go
  • AUR (Arch User Repository)
• Usage
• Configuration
• Contributors
• Todo
• Related projects
• License

Features

• Configurable using a single config file; Supports JSON, TOML, YAML, HCL, INI files
• Watch multiple directories recursively or non-recursively
• Concurrent watchers which run independently having their own settings & command
• Inclusive & Exclusive file group filters using regular expressions or list
• Rate limit using different strategies like debounce and throttle
• Configurable kill signal; In fact running command can do a graceful shutdown, restart or reload due to the signal

Installation

Go

If you’re a Gopher and want to install PolyWatch locally in your GOPATH:

go install -v github.com/pouyanh/polywatch/cmd/polywatch@latest

AUR (Arch User Repository)

If you’re using Arch Linux install polywatch or polywatch-git package from AUR

yay -S polywatch

Usage

Create the config file, run polywatch & it runs the command(s) on start and then whenever changes happen

Configuration

Configuration is done using a single file named .pw with these extensions: json, toml, yml, yaml, hcl & ini. It have to be located in current working directory. Example yaml config file can be a proper starting point.

Configuration consists of multiple independent watchers:

watchers:
  - name: "watcher 1"
  - name: "watcher 2"
  - name: "watcher 3"

Each watcher have 5 configuration sections:

Name Config

Name is a single string field. It’s just a label for the watcher

name: "watcher name"

Watch Config

Watch as it’s expected contains files & directories watching settings

• method: Defines watching mechanism. Currently just supports polling method that watches for file changes in fixed intervals
• interval: When method is polling, it sets interval between each watch.
• files: Array of WatchFile. Matching files get appended together; they get combined by logical OR.
• filters: Array of WatchFilter. Each candidate file have to pass all filters’ tests in order to make notification.

WatchFile

WatchFilter

RateLimit Config

Kill Config

Command Config

Contributors

Thanks to Saman Koushki for enabling multiline commands & improving process management.

Todo

1. Implement fsnotify watch method
2. Support event filters like filters on operation scope
3. Consider kill timeout
4. Add wildcard filter type

Related projects

• fswatch: Command line tool to watch file changes using fsnotify
• PolyWatch uses watcher which is a library that can watch file changes by polling mechanism, but it’s not configurable
• fsnotify: A cross-platform library to work with filesystem notifications

License

This software is licensed under the GPL v3 License. © 2023 Janstun