Crystal Inotify

A file system event monitoring library for Crystal, built on top of Linux's inotify system.

Why another Inotify library?

While there are several existing inotify shards in the Crystal community (like petoem/inotify.cr), this library was created because we needed one more! Plus, this one has colors! 🌈✨

"The best way to solve a problem is to create another library for it" - Every developer ever 😂

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     inotify:
       github: mamantoha/inotify-crystal
   

2. Run shards install

Usage

Simple blocking usage

require "inotify"

# Watch a directory for changes
Inotify::Watcher.watch("/path/to/watch", recursive: true) do |event|
  puts "[#{event.mask_to_s}] #{event.path}"
end

# Watch with symlink following
Inotify::Watcher.watch("/path/to/watch", recursive: true, follow_symlinks: true) do |event|
  puts "[#{event.mask_to_s}] #{event.path}"
end

# Watch with custom file matching options
Inotify::Watcher.watch("/path/to/watch", recursive: true, match: File::MatchOptions.glob_default | File::MatchOptions::DotFiles) do |event|
  puts "[#{event.mask_to_s}] #{event.path}"
end

Non-blocking with Spawn

require "inotify"

# Create a channel for events
channel = Channel(Inotify::Event).new

# Start watching in a spawn
spawn do
  watcher = Inotify::Watcher.new("/path/to/watch", recursive: true, follow_symlinks: true, match: File::MatchOptions.glob_default)

  watcher.each_event do |event|
    channel.send(event)
  end

  watcher.close
  channel.close
end

# Main thread receives events
loop do
  event = channel.receive
  puts "[#{event.mask_to_s}] #{event.path}"
end

Colorized Output

The library supports colorized output for better visual distinction of different event types:

require "inotify"

# Enable colorized output
Inotify::Watcher.watch("/path/to/watch", recursive: true) do |event|
  puts "[#{event.mask_to_s(true)}] #{event.path}"
end

Color Scheme

• 🟢 Green: CREATE events
• 🔴 Red: DELETE events
• 🟡 Yellow: MODIFY and ATTRIB events
• 🔵 Blue: MOVE events (MOVED_FROM, MOVED_TO, MOVE_SELF)
• 🔵 Cyan: File access events (CLOSE_WRITE, CLOSE_NOWRITE, OPEN)
• 🟣 Magenta: Directory indicator (ISDIR)
• 🔴 Light Red: System events (Q_OVERFLOW, UNMOUNT, IGNORED)
• ⚪ White: Other events
• ⚫ Dim: Unknown flags (hex values)

API Reference

# Event methods
event.mask_to_s           # Plain text: "CREATE | MODIFY"
event.mask_to_s(true)     # Colorized with ANSI codes

Contributing

1. Fork it (https://github.com/mamantoha/inotify-crystal/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Anton Maminov - creator and maintainer