Flash ⚡

A blazingly fast file watcher that executes commands when files change.

2.1ms startup time • 1.7x faster than watchexec • 18x faster than watchman

Think nodemon, but more general purpose and written in Rust.

Features

• ⚡ Blazingly fast - 2.1ms startup time, 1.7x faster than watchexec, 18x faster than watchman (benchmarks)
• 🎯 Flexible filtering - Support for glob patterns, file extensions, and ignore patterns
• 🔧 Configurable - YAML configuration files for complex setups
• 📊 Performance monitoring - Built-in statistics and benchmarking
• 🔄 Process management - Restart long-running processes or spawn new ones
• 🌍 Cross-platform - Works on Windows, macOS, and Linux
• 🎨 Beautiful output - Colored terminal output with clear status messages
• 💾 Memory efficient - Low memory footprint, single 1.9MB binary

Installation

From Crates.io (Recommended)

cargo install flash-watcher

From Source

git clone https://github.com/sage-scm/Flash.git
cd Flash
cargo install --path .

Pre-built Binaries

Download pre-built binaries from the releases page.

Usage

flash [OPTIONS] <COMMAND>...

Arguments

• <COMMAND>...: Command to run when files change

Options

• -w, --watch <WATCH>: Paths/patterns to watch (supports glob patterns like src/**/*.js)
• -e, --ext <EXT>: File extensions to watch (e.g., "js,jsx,ts,tsx")
• -p, --pattern <PATTERN>: Specific glob patterns to include (e.g., "src/**/*.{js,ts}")
• -i, --ignore <IGNORE>: Glob patterns to ignore (e.g., "/node_modules/")
• -d, --debounce <DEBOUNCE>: Debounce time in milliseconds [default: 100]
• -r, --restart: Restart long-running processes instead of spawning new ones
• -c, --clear: Clear console before each command run
• -n, --initial: Run command on startup
• -f, --config <CONFIG>: Use configuration from file
• --stats: Show performance statistics while running
• --stats-interval <SECONDS>: Statistics update interval in seconds [default: 10]
• --bench: Run benchmark against other file watchers
• --fast: Fast startup mode - minimal output and optimizations
• -h, --help: Print help
• -V, --version: Print version

Glob Pattern Support

Flash supports powerful glob pattern matching for both watching files and filtering them:

Watch Patterns (-w)

Watch specific file patterns directly:

# Watch all JavaScript files in src directory
flash -w "src/**/*.js" echo "JS file changed"

# Watch multiple specific patterns
flash -w "src/**/*.js" -w "public/**/*.css" echo "File changed"

Ignore Patterns (-i)

Ignore specific directories or files:

# Ignore node_modules and dist directories anywhere in the tree
flash -w "." -i "**/node_modules/**" -i "**/dist/**" echo "File changed"

# Ignore minified files
flash -w "src" -i "**/*.min.js" echo "File changed"

Include Patterns (-p)

Specifically include only certain file patterns:

# Only include TypeScript files in src and test directories
flash -w "." -p "src/**/*.ts" -p "test/**/*.ts" echo "TS file changed"

Combining Options

The most powerful usage comes from combining these options:

flash -w "." -e "js,ts" -p "src/**/*.{js,ts}" -i "**/node_modules/**" -i "**/dist/**" echo "File changed"

Examples

Watch current directory and restart a Node.js server when changes occur:

flash -r node server.js

Watch TypeScript files in the src directory and run the build script:

flash -w src -e ts npm run build

Watch multiple directories but ignore node_modules:

flash -w src -w tests -i "**/node_modules/**" cargo test

Watch using glob patterns to include only specific files:

flash -p "src/**/*.{js,jsx,ts,tsx}" -p "public/**/*.css" npm run build

Clear console and run command on startup:

flash -c -n -r npm start

Run with performance statistics:

flash --stats --stats-interval 5 npm run dev

Ultra-fast startup mode (minimal output):

flash --fast npm run dev

Configuration File

You can define a configuration file in YAML format to avoid typing long commands:

# flash.yaml
command: ["npm", "run", "dev"]
watch:
  - "src/**" # Watch all files in src directory recursively
  - "public/*.html" # Watch HTML files in public directory

ext: "js,jsx,ts,tsx"

pattern:
  - "src/**/*.{js,jsx,ts,tsx}" # JavaScript/TypeScript files in src

ignore:
  - "**/node_modules/**" # Ignore node_modules directory
  - "**/.git/**" # Ignore .git directory
  - "**/*.min.js" # Ignore minified JS files

debounce: 200
initial: true
clear: true
restart: true

Then run Flash with:

flash -f flash.yaml

You can also override configuration file settings with command line arguments.

Common Use Cases

Web Development

flash -w "src/**" -w "public/**" -e js,jsx,ts,tsx,css,html -i "**/node_modules/**" -r -c -n npm start

Rust Development

flash -w "src/**/*.rs" -w "tests/**/*.rs" -i "target/**" -c cargo test

Documentation

flash -w "docs/**/*.md" -c -n mdbook build

Performance and Benchmarks

Flash is designed to be blazingly fast and resource efficient. To see how it compares to other file watchers:

flash --bench

This will show sample benchmark results. For real benchmarks, you can run:

# Run actual benchmarks (requires benchmarks feature)
cargo bench --features benchmarks

# Or install with benchmarks enabled
cargo install flash-watcher --features benchmarks

Note: The --bench flag shows sample benchmark data for demonstration. For real benchmarks, use cargo bench --features benchmarks. Benchmarks are disabled by default in CI/CD pipelines to save workflow minutes.

Development Scripts

For developers, we provide convenient scripts:

# Generate code coverage reports (fast, excludes benchmarks)
./scripts/coverage.sh

# Run performance benchmarks (slow, requires benchmarks feature)
./scripts/benchmark.sh

Performance

Flash is designed for speed. See our performance benchmarks for detailed comparisons with other file watchers.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on how to get started.

Support

• 📖 Documentation: Check the README and examples
• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Open an issue
• 💬 Questions: Start a discussion

License

This project is licensed under the MIT License - see the LICENSE file for details.