reflex
Run commands on file changes
TLDR
Rebuild with make if any file changes
Compile and run Go application if any .go file changes
Ignore a directory when watching for changes
Run command when reflex starts and restarts on file changes
Substitute the filename that changed in
SYNOPSIS
reflex [options] <command>
Example: reflex -r '\.go$' go run main.go
Example: reflex -s -d 500ms -e 'vendor' make
PARAMETERS
-A <path>
Add an additional directory path to watch. This option can be specified multiple times to watch several distinct directories. By default, reflex watches the current working directory.
-c
Clear the terminal screen before each command execution, providing a clean output for every run.
-d <duration>
Set a debounce duration (e.g., 500ms
, 1s
) to wait for file changes to settle before re-executing the command. This prevents rapid, multiple executions from quick saves.
-e <regexp>
Provide a regular expression to exclude files or directories from being watched. Files matching this pattern will be ignored even if they are in a watched directory.
-g <glob>
Specify a glob pattern to match files to watch. Use as an alternative to the -r
(regular expression) option for simpler pattern matching.
-i
Ignore common version control directories (e.g., .git
, .hg
, .svn
, .bzr
) and dependency directories (e.g., node_modules
, vendor
) from being watched.
-L <level>
Set the log level for reflex itself (e.g., debug
, info
, warn
, error
). This controls the verbosity of reflex's internal output.
-m <num>
Set the maximum number of events to debounce before forcing command execution. This ensures the command eventually runs even if changes are continuous.
-r <regexp>
Provide a regular expression to match files to watch. Only files matching this pattern will trigger command execution. By default, it watches all files (`.*`).
-s
Start the command immediately upon reflex startup, before any file changes occur. Useful for ensuring the service is running from the start.
-t <regexp>
Provide a regular expression that, if matched by a changed file, will trigger command execution. By default, any change (`.*`) triggers a run.
-x
Do not clear the terminal screen before executing the command. This option overrides the -c
option if both are specified.
-h, --help
Display the help message, showing all available options and their usage, and then exit.
-v, --version
Display the version information of reflex and then exit.
DESCRIPTION
reflex is a powerful and flexible command-line utility designed to watch files and directories for changes, automatically re-executing a specified command upon detecting modifications. It's particularly useful for developers, enabling real-time feedback during development cycles by recompiling code, restarting servers, or running tests whenever source files are updated.
reflex supports various filtering options, allowing users to define specific files or patterns to watch (or ignore) using regular expressions or glob patterns. It can also debounce multiple rapid changes into a single execution and clear the terminal output for a cleaner development experience. Written in Go, it's cross-platform and efficient for diverse development environments.
CAVEATS
reflex is primarily designed for development workflows and may not be suitable for high-performance, production monitoring systems where very low latency or guaranteed event delivery is critical. Performance might be affected when watching a very large number of files or directories, especially on older file systems or network mounts. The accuracy of file change detection can sometimes be limited by the underlying operating system's file system notification capabilities.
COMMON USE CASES
reflex is widely used for auto-reloading web servers during front-end development, recompiling Go or other compiled languages on save, automatically running unit tests, or triggering build scripts for static site generators. Its flexibility allows it to integrate into various development pipelines, reducing manual intervention and speeding up the feedback loop.
PATTERN MATCHING
Users should be aware of the differences between regular expressions (used with -r
and -e
) and glob patterns (used with -g
). Regular expressions offer more power and precision for complex matching, while glob patterns are often simpler and more intuitive for basic file matching like *.js
or **/*.go
. Choosing the right pattern type is crucial for effective file watching.
HISTORY
reflex is a relatively modern tool, implemented in Go. It was created to provide a simple, cross-platform, and efficient solution for the common development need of automatically re-running commands on file changes. Its design draws inspiration from similar tools in various language ecosystems (like `nodemon` for Node.js or `rackup` for Ruby) but offers a generic approach, making it applicable to any programming language or build system. Its active development reflects its utility in contemporary development workflows, emphasizing speed and ease of use.
SEE ALSO
inotifywait(1), watch(1), fswatch(1), entr(1)