Skip to content
Command line utility to perform actions when files are updated, added or deleted. No config files. Pure Ruby implementation and minimalistic Ruby API.
Latest commit b45c5be Mar 10, 2016 @thomasfl upgrade dependencies


Gem Version Build Status Dependency Status Code Climate

Lightweight filewatcher weighing less than 200 LoC. No dependencies or platform specific code. Works everywhere. Monitors changes in the filesystem by polling. Has no config files. When running filewatcher from the command line, you specify which files to monitor and what action to perform on updates.

For example to search recursively for javascript files and run jshint when a file is updated, added, renamed or deleted:


$ filewatcher '**/*.js' 'jshint $FILENAME'

In Windows:

> filewatcher "**/*.js" "jshint %FILENAME%"


Needs Ruby and Rubygems:

$ [sudo] gem install filewatcher

Command line utility

Filewatcher scans the filesystem and execute shell commands when files are updated, added, renamed or deleted.

    filewatcher [--restart][--list][--dontwait] "<filename>" "<shell command>"

    filename: filename(s) to scan.
    shell command: shell command to execute when a file is changed


Run the echo command when the file myfile is changed:

$ filewatcher "myfile" "echo 'myfile has changed'"

Run any javascript in the current directory when it is updated in Windows Powershell:

> filewatcher *.js "node %FILENAME%"

In Linux/OSX:

$ filewatcher *.js 'node $FILENAME'

Place filenames or filenames in quotes to use ruby filename globbing instead of shell filename globbing. This will make filewatcher look for files in subdirectories too. To watch all javascript files in subdirectories in Windows:

> filewatcher "**/*.js" "node %FILENAME%"

In Linux/OSX:

> filewatcher '**/*.js' 'node $FILENAME'

Try to run the updated file as a script when it is updated by using the --exec/-e option. Works with files with file extensions that looks like a python, ruby, perl, php, javascript or awk script.

$ filewatcher -e *.rb

Print a list of all files matching *.css first and then output the filename when a file is beeing updated by using the --list/-l option:

$ filewatcher -l '**/*.css' 'echo file: $FILENAME'

Watch the "src" and "test" folders recursively, and run test when the filesystem gets updated:

$ filewatcher "src test" "ruby test/test_suite.rb"

Restart long running commands

The --restart option kills the command if it's still running when a filesystem change happens. Can be used to restart locally running webservers on updates, or kill long running tests and restart on updates. This option often makes filewatcher faster in general. To not wait for tests to finish:

$ filewatcher --restart "**/*.rb" "rake test"

The --dontwait option starts the command on startup without waiting for filesystem updates. To start a webserver and have it automatically restart when html files are updated:

$ filewatcher --restart --dontwait "**/*.html" "python -m SimpleHTTPServer"

Available enviroment variables

The environment variable $FILENAME is available in the shell command argument. On unix like systems the command has to be enclosed in single quotes. To run node whenever a javascript file is updated:

$ filewatcher *.js 'node $FILENAME'

Environment variables available from the command string:

BASENAME           File basename.
FILENAME           Relative filename.
ABSOLUTE_FILENAME  Asolute filename.
RELATIVE_FILENAME  Same as FILENAME but starts with "./"
EVENT              Event type. Is either 'changed', 'delete' or 'new'.
DIRNAME            Absolute directory name.

Command line options

Useful command line options:

        --list, -l:   Print name of matching files on startup
     --restart, -r:   Run command in separate fork and kill it on filesystem updates
    --dontwait, -d:   Run the command before any filesystem updates
     --spinner, -s:   Display an animated spinner while scanning

Other command line options:

     --version, -v:   Print version and exit
        --help, -h:   Show this message
--interval, -i <f>:   Interval in seconds to scan filesystem. Defaults to 0.5 seconds.
        --exec, -e:   Execute file as a script when file is updated
 --include, -n <s>:   Include files (default: *)
 --exclude, -x <s>:   Exclude file(s) matching (default: "")

Ruby API

Watch a list of files and directories:

require 'filewatcher'["lib/", "Rakefile"]).watch do |filename|
  puts "Changed " + filename

Watch a single directory, for changes in all files and subdirectories:"lib/").watch do |filename|

Notice that the previous is equivalent to the following:"lib/**/*").watch do |filename|

Watch files and dirs in the given directory - and not in subdirectories:"lib/*").watch do |filename|

Watch an absolute directory:"/tmp/foo").watch do |filename|

To detect if a file is updated, added or deleted:["README.rdoc"]).watch() do |filename, event|
  if(event == :changed)
    puts "File updated: " + filename
  if(event == :delete)
    puts "File deleted: " + filename
  if(event == :new)
    puts "Added file: " + filename

When a file is renamed it is detected as a new file followed by a file deletion.

The API takes some of the same options as the command line interface. To watch all files recursively except files that matches *.rb, display a spinner and only wait for 0.1 seconds between each scan:'**/*.*', exclude: '**/*.rb', spinner: true, interval: 0.1).watch() do |filename|
    puts filename

To do the same from the command line, use the same options:

$ filewatcher '**/*.*' --exclude '**/*.rb' --spinner --interval 0.1 'echo $FILENAME'

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.["*.rb", "*.xml"]).watch do |filename|
  puts "Updated " + filename

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

filewatcher =["*.rb"])
thread ={|fw|{|f| puts "Updated " + f}}
filewatcher.pause       # block stops responding to filesystem changes
filewatcher.finalize    # Ensure all filesystem changes made prior to
                        # pausing are handled.
filewatcher.resume       # block begins responding again, but is not given
                         # changes made between #pause_watch and
                         # #resume_watch
filewatcher.end        # block stops responding to filesystem changes
                       # and takes a final snapshot of the filesystem

filewatcher.finalize   # Ensure all filesystem changes made prior to
                       # ending the watch are handled.

If basename, relative filename or absolute filename is necessay use the stanard lib 'pathname' like this:

require 'pathname'["**/*.*"]).watch() do |filename|
  path =
  puys "Basename         : " + path.basename.to_s
  puts "Relative filename: " + File.join('.').to_s, path.to_s)
  puts "Absolute filename: " + File.join('.').realpath.to_s, path.to_s)

The filewatcher library is a single file with 180 LOC (including comments) with no dependencies.


  • 0.5.3 Exclude files. More environment variables. Options in ruby api.
  • 0.5.2 Start, stop and finalize API.
  • 0.5.1 Kill and restart long running command with --restart option.


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

  • 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 by

  • Kristoffer RoupĂ© Command line globbing by

This gem was initially inspired by Tom Lieber's blogg posting:

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.


Copyright (c) 2011 - 2015 Thomas Flemming. See LICENSE for details.

Something went wrong with that request. Please try again.