Cruise

Add to your Gemfile:

gem "cruise"

Or install directly:

gem install cruise

Precompiled native gems are available for macOS and Linux. If a precompiled gem isn't available for your platform, it will compile from source (requires Rust).

Watch a directory for changes:

require "cruise"

Cruise.watch("app/views") do |event|
  puts "#{event.kind}: #{event.path}"
end

The callback receives a Cruise::Event with two attributes:

Watch several paths at once:

Cruise.watch("app/views", "app/components", "lib/templates") do |event|
  puts event.inspect
  # => #<Cruise::Event kind="modified" path="/app/views/users/show.html.erb">
end

Cruise releases the GVL while waiting for filesystem events, so Ruby threads run freely:

Thread.new { do_background_work }

Cruise.watch("src") do |event|
  puts event
end

Only receive events for files matching a pattern:

Cruise.watch("app/views", glob: "**/*.html.erb") do |event|
  puts event
end

Multiple patterns:

Cruise.watch("app", glob: ["**/*.html.erb", "**/*.html"]) do |event|
  puts event
end

Configure the debounce interval (default: 100ms):

Cruise.watch("src", debounce: 0.5) do |event|
  puts event
end

You can also pass a Proc via the callback: keyword:

handler = proc { |event| puts event }

Cruise.watch("app/views", callback: handler)

The watcher runs in a blocking loop. Use Interrupt to stop it cleanly:

begin
  Cruise.watch("app") do |event|
    # process event
  end
rescue Interrupt
  puts "Stopped."
end

Cruise is a Ruby binding (via Magnus and rb-sys) around the Rust notify crate.

1. Cruise.watch sets up a notify watcher with event debouncing (100ms)
2. A background thread monitors filesystem events using the OS-native API
3. The main loop calls rb_thread_call_without_gvl to wait without blocking Ruby
4. When an event arrives, the GVL is re-acquired and your callback is invoked

All backends watch recursively by default.

Requirements: Rust toolchain, Ruby 3.2+

git clone https://github.com/marcoroth/cruise
cd cruise
bundle install
bundle exec rake compile
bundle exec rake test

Cruise uses rake-compiler and rake-compiler-dock for building native gems:

bundle exec rake gem:native

MIT License. See LICENSE.txt.