Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
F

filewatcher

> 编程语言
Open source

Ruby gem to perform actions when files are changed. No config files. Pure Ruby implementation and minimalistic Ruby API.

464 stars0 likes2 views
WebsiteGitHub

About

Ruby gem to perform actions when files are changed. No config files. Pure Ruby implementation and minimalistic Ruby API.

Filewatcher

Lightweight file watcher weighing about 300 LOC. No runtime dependencies and no platform specific code. Works everywhere. Monitors changes in the file system by polling. Has no config files.

Installation

bash
$ gem install filewatcher

or with bundler:

ruby
# Gemfile
gem 'filewatcher'

Usage

Watch a list of files and directories:

ruby
require 'filewatcher'

Filewatcher.new(['lib/', 'Rakefile']).watch do |changes|
  changes.each do |filename, event|
    puts "#{filename} #{event}"
  end
end

Watch a single directory, for changes in all files and subdirectories:

ruby
Filewatcher.new('lib/').watch do |changes|
  # ...
end

Notice that the previous is equivalent to the following:

ruby
Filewatcher.new('lib/**/*').watch do |changes|
  # ...
end

Watch files and directories in the given directory - and not in subdirectories:

ruby
Filewatcher.new('lib/*').watch do |changes|
  # ...
end

Watch an absolute directory:

ruby
Filewatcher.new('/tmp/foo').watch do |changes|
  # ...
end

To detect if a file is updated, added or deleted:

ruby
Filewatcher.new(['README.rdoc']).watch do |changes|
  changes.each do |filename, event|
    puts "File #{event}: #{filename}"
  end
end

When a file is renamed and every option is enabled, it is detected as a new file followed by a file deletion:

ruby
Filewatcher.new(['lib/'], every: true).watch do |changes|
  changes.each do |filename, event|
    puts "File #{event}: #{filename}"
  end
end

# Rename from `old_test.rb` to `new_test.rb` will print:

# File created: /absolute/path/lib/new_test.rb
# File deleted: /absolute/path/lib/old_test.rb

The API takes some of the same options as the command line interface. To watch all files recursively except files that matches *.rb and only wait for 0.1 seconds between each scan:

ruby
Filewatcher.new('**/*.*', exclude: '**/*.rb', interval: 0.1).watch do |changes|
  changes.each do |filename, event|
    puts filename
  end
end

Use patterns to match filenames in current directory and subdirectories. The pattern is not a regular expression; instead it follows rules similar to shell filename globbing. See Ruby documentation for syntax.

ruby
Filewatcher.new(['*.rb', '*.xml']).watch do |changes|
  changes.each do |filename, _event|
    puts "Updated #{filename}"
  end
end

Start, pause, resume, stop, and finalize a running watch. This is particularly useful when the update block takes a while to process each file (e.g. sending over the network).

…

If basename, relative filename or absolute filename is necessary use the standard pathname like this:

ruby
require 'pathname'

Filewatcher.new(['**/*.*']).watch do |changes|
  changes.each do |filename, event|
    path = Pathname.new(filename)
    puts "Basename         : #{path.basename}"
    puts "Relative filename: #{File.join('.', path)}"
    puts "Absolute filename: #{path.realpath}"
  end
end

Plugins

You can require plugins for Filewatcher, which extends core functionality.

Example:

ruby
require 'filewatcher'
require 'filewatcher-spinner'

# With the `true` value of option there will be an ASCII spinner in the STDOUT while waiting changes
Filewatcher.new('lib/', spinner: true).watch do |changes|
  changes.each do |filename, event|
    puts "#{filename} #{event}"
  end
end

Available methods are:

  • #after_initialize
  • #before_pause_sleep
  • #before_resume_sleep
  • #after_stop
  • #finalizing

If you have questions, problems or suggestions about plugins system — please, don't hesitate to create a new issue.

Official plugins:

  • CLI
  • Matrix
  • Spinner
  • Access

Changelog

Changelog can be found in an adjacent file.

Credits

This project would not be where it is today without the generous help provided by people reporting issues and these contributors:

  • Thomas Flemming: Original author. Restart option. Exported variables.

  • Penn Taylor: Spinner displayed in the terminal and Start, pause, resume, stop, and finalize a running watch.

  • Franco Leonardo Bulgarelli: Support for absolute and globbed paths.

  • Kristoffer Roupé: Command line globbing.

  • Alexander Popov: Plugin system, daemon mode (CLI), tests improvements, code style improvements, many other fixes and improvements.

This gem was initially inspired by Tom Lieber's blog posting (Web Archive version).

Note on Patches/Pull Requests

  • Fork the project.
  • Make your feature addition or bug fix.
  • Add tests for it. This is important so I don't break it in a future version unintentionally.
  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
  • Send me a pull request. Bonus points for topic branches.

Releasing

This section is for maintainers.

Use toys gem release 9.8.7 for releasing new versions. It'll make changes to the version.rb file, CHANGELOG.md (with confirmation, feel free to edit before continue), make a git commit, a git tag, push them, build a gem, push the gem.

Copyright

Copyright (c) 2010 - 2026 Thomas Flemming. See LICENSE for details.

Issues· 8 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Ruby

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言