VibeWatch

A fast and extensible file watcher utility built in Rust with glob pattern support and cross-platform compatibility.

Features

• Custom command execution: Run commands on file changes with event-specific triggers (--on-create, --on-modify, --on-delete, --on-change)
• Template substitution: Use {file_path}, {relative_path}, {absolute_path}, {event_type} in commands
• Structured logging: Objective, timestamp-based logs with exit codes for monitoring and automation
• Cross-platform file watching: Fully tested on Linux, macOS, and Windows with platform-specific event handling
• Glob pattern support: Include and exclude files using glob patterns like *.rs, node_modules/**
• Extensible architecture: Clean separation of concerns for easy feature additions
• Fast performance: Built in Rust for minimal resource usage
• Flexible CLI: Intuitive command-line interface with verbose logging and quiet mode
• Comprehensive testing: 90.95% code coverage with 187 tests covering unit, filesystem, and integration scenarios

Installation

From crates.io (Recommended)

cargo install vibewatch

From Binary Releases (Recommended for Production)

Download pre-built binaries from the latest release.

Available platforms:

• Linux: x86_64, ARM64 (.tar.gz)
• macOS: Intel (x86_64), Apple Silicon (ARM64) (.tar.gz)
• Windows: x64 (.zip)

# Example: Linux x86_64
wget https://github.com/rodrigogs/vibewatch/releases/latest/download/vibewatch-x86_64-unknown-linux-gnu.tar.gz
tar -xzf vibewatch-x86_64-unknown-linux-gnu.tar.gz
sudo mv vibewatch /usr/local/bin/

# Example: macOS ARM (Apple Silicon)
wget https://github.com/rodrigogs/vibewatch/releases/latest/download/vibewatch-aarch64-apple-darwin.tar.gz
tar -xzf vibewatch-aarch64-apple-darwin.tar.gz
sudo mv vibewatch /usr/local/bin/

From Source

Make sure you have Rust installed via mise or rustup:

# Clone and build
git clone https://github.com/rodrigogs/vibewatch.git
cd vibewatch
cargo build --release

⚡ Performance

vibewatch is built in Rust for minimal resource usage and fast execution:

• Efficient memory usage - Static strings and optimized path handling minimize allocations
• Async event processing - Non-blocking command execution via tokio
• Smart debouncing - Prevents redundant commands from rapid file changes (configurable with --debounce)
• Fast pattern matching - Compiled glob patterns for quick file filtering
• Lightweight binary - Single executable, no runtime dependencies

Benchmarks

Benchmark the core operations to verify performance on your system:

cargo bench                               # Run all benchmarks
cargo bench --bench template_substitution # Specific suite
cargo bench --bench pattern_matching      # Pattern matching performance

The benchmark suite measures:

• Template substitution - Variable replacement in command strings
• Path normalization - Cross-platform path handling
• Pattern matching - Glob compilation and file filtering speed

Results are compared against baseline measurements to track performance over time.

Usage

Command Execution on File Changes

The primary use case is executing commands when files change:

# Run tests on any change
vibewatch . --on-change "npm test"

# Format Rust files when modified
vibewatch src --include "*.rs" --on-modify "rustfmt {file_path}"

# Run linter on TypeScript files (using brace expansion)
vibewatch . --include "*.{ts,tsx}" --exclude "node_modules/**" --on-modify "npx eslint {file_path} --fix"

# Different commands for different events
vibewatch src \
  --on-create "git add {file_path}" \
  --on-modify "cargo check" \
  --on-delete "echo Removed: {relative_path}"

Available Templates:

• {file_path} - Full path to the changed file
• {relative_path} - Path relative to watched directory
• {absolute_path} - Absolute path to the changed file
• {event_type} - Type of event (create, modify, delete)

Brace Expansion: You can use brace expansion syntax for convenience with both --include and --exclude patterns:

# Include patterns - these are equivalent:
vibewatch . --include "*.{ts,tsx}"
vibewatch . --include "*.ts" --include "*.tsx"

# Works with multiple extensions:
vibewatch . --include "*.{js,jsx,ts,tsx}"

# Works with paths:
vibewatch . --include "src/**/*.{rs,toml}"

# Exclude patterns - these are equivalent:
vibewatch . --exclude "{target,dist,node_modules}/**"
vibewatch . --exclude "target/**" --exclude "dist/**" --exclude "node_modules/**"

# Combined include and exclude with brace expansion:
vibewatch . --include "src/**/*.{rs,toml}" --exclude "{target,build}/**"

Watch-Only Mode

Watch a directory and log all file changes (no commands):

vibewatch /path/to/directory

Include Patterns

Watch only specific file types:

vibewatch /path/to/directory --include "*.rs" --include "*.ts"

Exclude Patterns

Ignore common directories and files:

vibewatch /path/to/directory --exclude "node_modules/**" --exclude ".git/**" --exclude "target/**"

Combined Patterns

Use both include and exclude patterns:

vibewatch . \
  --include "*.rs" \
  --include "*.ts" \
  --include "*.tsx" \
  --exclude "target/**" \
  --exclude "node_modules/**" \
  --verbose

Options

Directory:

• <DIRECTORY>: Directory to watch (can be relative or absolute)

Command Execution:

• --on-create <COMMAND>: Run command when files are created
• --on-modify <COMMAND>: Run command when files are modified
• --on-delete <COMMAND>: Run command when files are deleted
• --on-change <COMMAND>: Run command on any file change (fallback)

Filtering:

• -i, --include <PATTERN>: Include patterns like *.ts, *.rs (use multiple times for multiple patterns)
• -e, --exclude <PATTERN>: Exclude patterns like node_modules/**, .git/**, .next/**

General:

• -v, --verbose: Enable verbose output with debug logging
• -q, --quiet: Suppress command output (only show file events and status)
• -h, --help: Show help message
• -V, --version: Show version information

Structured Logging (v0.4.0+)

vibewatch provides objective, timestamp-based logs for monitoring and automation:

File Events:

[2025-10-06T14:23:15] [CREATED] src/main.rs
[2025-10-06T14:23:16] [MODIFIED] src/watcher.rs
[2025-10-06T14:23:17] [DELETED] tmp/test.txt

Command Execution:

[2025-10-06T14:23:15] Executing command: cargo build
<command output appears here>
[2025-10-06T14:23:18] Command succeeded (exit code: 0)

Command Failure:

[2025-10-06T14:23:19] Executing command: cargo check
<error output appears here>
[2025-10-06T14:23:20] Command failed (exit code: 1)

Features:

• ISO 8601 timestamps for sortable, parseable logs
• Uppercase event types (CREATED, MODIFIED, DELETED, CHANGED)
• Exit codes shown for all command executions
• Grep-friendly format (all lines start with [YYYY-MM-DD)
• Use --quiet to suppress command output, keeping only events and status

Examples

Auto-format TypeScript on save

vibewatch src \
  --include "*.{ts,tsx}" \
  --exclude "node_modules/**" --exclude "dist/**" \
  --on-modify "npx prettier --write {file_path}"

Run Rust tests on file changes

vibewatch . \
  --include "*.rs" --include "Cargo.toml" \
  --exclude "target/**" \
  --on-change "cargo test"

Rebuild documentation on changes

vibewatch docs \
  --include "*.md" --include "*.rst" \
  --exclude "_build/**" \
  --on-change "mdbook build"

Watch and restart development server

vibewatch src \
  --include "*.js" --include "*.json" \
  --exclude "node_modules/**" \
  --on-change "pkill -f 'node server.js' && node server.js &"

Auto-commit on file creation

vibewatch src \
  --on-create "git add {file_path} && git commit -m 'Add {relative_path}'"

Architecture

The application is structured for extensibility:

• main.rs: CLI argument parsing and application entry point
• watcher.rs: Core file watching logic using the notify crate
• filter.rs: Glob pattern matching for include/exclude functionality

Common Glob Patterns

Exclude Patterns

• node_modules/** - Node.js dependencies
• .git/** - Git repository files
• .next/** - Next.js build files
• target/** - Rust build directory
• dist/** - Build output directory
• {target,dist,build}/** - Multiple build directories (brace expansion)
• *.tmp - Temporary files
• *.swp - Vim swap files
• *.{tmp,swp,bak} - Multiple temporary file types (brace expansion)

Include Patterns

• *.rs - Rust source files
• *.{ts,tsx} - TypeScript files (brace expansion supported)
• *.{js,jsx} - JavaScript files (brace expansion supported)
• *.py - Python files
• *.go - Go files
• *.{cpp,c,h} - C/C++ files (brace expansion supported)
• *.md - Markdown files

Note: Brace expansion like *.{ext1,ext2} or {dir1,dir2}/** works with both --include and --exclude patterns. The syntax is automatically expanded to multiple patterns before glob compilation. You can also use multiple flags if you prefer explicit patterns.

Future Enhancements

The following features are planned for future releases:

• Configuration file support: Store watch patterns and commands in .vibewatch.toml
• Ignore file support: Respect .gitignore, .watchignore patterns

Requirements

• Rust 1.70+ (managed via mise)
• Unix-like system (macOS, Linux) or Windows

Development

Quick Start with Just

The project uses just for task automation:

# Install just (if not already installed)
cargo install just
# or: brew install just

# List all available tasks
just --list

# Common tasks
just test              # Run all tests
just coverage          # Generate coverage report
just lint              # Run linter
just check             # Run all checks (fmt, lint, test)
just demo              # Run vibewatch on src/ directory

Running Tests

# Run all tests (187 total: 140 unit + 21 filesystem + 26 integration)
cargo test
# or: just test

# Run tests with output
cargo test -- --nocapture
# or: just test-verbose

# Run specific test suite
cargo test --test it  # Integration tests only
# or: just test-integration test_name

Code Coverage

The project maintains 90.95% code coverage (1096/1205 lines):

# Generate coverage report
cargo llvm-cov --all-features --workspace --html

# View report
open target/llvm-cov/html/index.html

Coverage by file:

• filter.rs: 100.00% (177/177) ✅
• main.rs: 97.67% (252/258) ✅
• watcher.rs: 86.62% (667/770) ✅

Note: The watcher.rs coverage is lower due to command execution happening in spawned async tasks that are harder to test in unit tests. All command execution logic is thoroughly tested through our comprehensive integration test suite.

Development Commands

# Run with debug logging
RUST_LOG=debug cargo run -- /path/to/directory --verbose

# Build for release
cargo build --release

# Run linter
cargo clippy

# Format code
cargo fmt

Contributing

Commit Message Convention

This project uses Conventional Commits for automated versioning and changelog generation.

Format: <type>(<optional scope>): <description>

Types:

• feat: - New feature (triggers minor version bump)
• fix: - Bug fix (triggers patch version bump)
• docs: - Documentation changes
• chore: - Maintenance tasks
• refactor: - Code refactoring
• test: - Adding or updating tests
• feat!: or fix!: - Breaking changes (triggers major version bump)

Examples:

feat: add support for symlink watching
fix: resolve race condition in file detection
docs: update README with new examples
feat!: change CLI argument structure (breaking change)

Release Process

Releases are fully automated via Release Please:

1. Commit using conventional commits - Each commit to master is analyzed
2. Release PR is created - Release Please opens a PR with updated version and CHANGELOG
3. Merge the Release PR - This triggers:
   • GitHub Release creation with release notes
   • Binary builds for 5 platforms (parallel execution, ~4 minutes):
     • Linux x86_64 and ARM64
     • macOS Intel and Apple Silicon
     • Windows x64
   • Publish to crates.io (requires CARGO_TOKEN secret)

Current version: v0.4.0 (October 2025)

Binary build tool: Uses taiki-e/upload-rust-binary-action for reliable cross-compilation

• Automatic cross-compilation for Linux ARM64
• No timeout issues (resolved in v0.3.0)
• Battle-tested by tokio-console and cargo-hack

CI/CD

Branch Protection: Enabled on master with 6 required status checks

All PRs and pushes to master run:

• ✅ Tests (187 tests on Linux, macOS, Windows)
• ✅ Formatting check (cargo fmt --check)
• ✅ Linting (cargo clippy -D warnings)
• ✅ Coverage report (uploaded to Codecov)

On release (after merging Release PR):

• ✅ Build binaries for 5 platforms (parallel)
• ✅ Create GitHub Release with all binaries
• ✅ Publish to crates.io

Release Process:

• Uses Release Please with Personal Access Token (RELEASE_PLEASE_TOKEN)
• PAT required to trigger CI workflows on Release Please PRs
• Ensures all tests pass before releases are created

See docs/CI_CD.md for complete CI/CD architecture documentation.

Documentation

For comprehensive technical documentation:

• CI/CD Architecture: docs/CI_CD.md - Complete CI/CD pipeline, release process, branch protection (v2.0)
• Testing Guide: docs/TESTING.md - Test organization, best practices, and quick reference
• Coverage Analysis: docs/COVERAGE.md - Detailed coverage metrics and industry benchmarks
• Integration Tests: docs/INTEGRATION_TEST.md - Testing research, rationale, and best practices
• Justfile Guide: docs/JUSTFILE_IMPLEMENTATION.md - Task runner implementation and benefits