cargo-rerun

A tool that runs cargo run and automatically restarts your application whenever watched files change.

Perfect for development workflows where you want instant feedback as you code—similar to nodemon for Node.js or live reload for web development, but optimized for Rust projects.

Features

• 🚀 Instant Restarts - Detects file changes and restarts within milliseconds
• 📁 Flexible Glob Patterns - Watch exactly what you need: source files, config files, data directories
• 📦 Parent Directory Support - Monitor files outside your project (e.g., ../api/**/*.proto)
• ⚙️ Easy Configuration - Simple TOML config in your Cargo.toml
• 🛑 Clean Exit - Single Ctrl-C to gracefully stop everything
• 🏃 No Dependencies Headaches - Lightweight binary with efficient file watching

Installation

From crates.io

cargo install cargo-rerun

From source

git clone https://github.com/yourusername/cargo-rerun.git
cd cargo-rerun
cargo install --path .

Quick Start

Optionally add this to your Cargo.toml:

[tool.rerun]
watch = ["src/**/*.rs"]

Then run:

cargo-rerun

cargo-rerun will:

1. Start your application with cargo run
2. Watch for file changes matching your patterns
3. Restart automatically whenever a matched file changes

Your app will restart automatically whenever a Rust file in src/ changes—perfect for rapid development iteration.

Passing Arguments to cargo run

Pass arguments through to your application:

# Pass arguments to cargo run
cargo-rerun -- --release --verbose

# Arguments before `--` go to cargo, after `--` go to your app
cargo-rerun --release -- --debug-mode

Configuration

Configure what to watch in your Cargo.toml. There are three ways to configure cargo-rerun, listed in priority order:

Option 1: Package Metadata (Recommended)

[package.metadata.rerun]
watch = ["src/**/*.rs"]

Option 2: Workspace Metadata

Use this for workspace-level configuration (only used if package metadata is not found):

[workspace.metadata.rerun]
watch = ["src/**/*.rs"]

Option 3: Tool Section (Deprecated)

Supported for backward compatibility (shows deprecation warning):

watch = [ "src//*.rs", # Rust source "assets//*", # Static assets "config.toml", # Config file ]

**Parent Directory Support**

Watch files outside your project:

```toml
[package.metadata.rerun]
watch = [
    "src/**/*.rs",
    "../shared/**/*.proto",    # Proto definitions
    "../config/app.yaml",      # Shared config
]

Default Behavior

If no [tool.rerun] section exists, it defaults to watching src/**/*.rs.

Usage Examples

Web Application

Watch source and static files:

[tool.rerun]
watch = [
    "src/**/*.rs",
    "templates/**/*.html",
    "static/**/*",
    "config/**/*.toml",
]

Microservice With Shared Proto

[tool.rerun]
watch = [
    "src/**/*.rs",
    "../proto/**/*.proto",
    "../shared/**/*.rs",
]

TUI Application

Monitor source and data directories:

[tool.rerun]
watch = [
    "src/**/*.rs",
    "data/**/*",
]

How It Works

1. Starts Application - Runs cargo run when cargo-rerun launches
2. Watches Files - Uses efficient platform-specific file watchers (inotify on Linux, FSEvents on macOS, etc.)
3. Matches Patterns - Compiled glob patterns determine which file changes trigger a restart
4. Stops Process - Gracefully terminates your running application on file change
5. Restarts Process - Immediately re-runs cargo run with fresh code
6. Repeats - Listens for the next file change and repeats the cycle

Architecture

• Built on watchexec for reliable, efficient file watching
• Uses globset for fast glob pattern matching
• Powered by tokio for async task coordination
• Configured via toml and serde

Requirements

• Rust 1.56+ (2021 edition)
• cargo command available in PATH

Troubleshooting

Application restarts too frequently

Make sure your glob patterns are specific. For example:

• ❌ Bad: watch = ["**/*"] (watches everything)
• ✅ Good: watch = ["src/**/*.rs", "config/**/*.toml"] (specific paths)

Parent directory globs not working

Ensure the path exists and use ../ syntax:

• ❌ Bad: watch = ["api/**/*.rs"]
• ✅ Good: watch = ["../api/**/*.rs"] (relative to your crate root)

Editor swap files triggering restarts

Some editors (vim, emacs) create temporary files. Standard globs like src/**/*.rs won't match .swp files, so you shouldn't be affected. If you experience issues, check your glob patterns.

Performance

• Startup: < 100ms overhead
• Change Detection: Platform-optimized (inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows)
• Pattern Matching: O(1) glob compilation, O(log n) per-file matching with compiled globs
• Memory: ~5-10MB typical process

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

See THIRD_PARTY_LICENSES.md for third-party dependency licenses.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

See Also

• watchexec - The file watching engine behind cargo-rerun
• cargo-watch - Alternative with different design philosophy
• cargo-deny - Audit your dependencies