emcrisostomo / fswatch Goto Github PK

A cross-platform file change monitor with multiple backends: Apple OS X File System Events, *BSD kqueue, Solaris/Illumos File Events Notification, Linux inotify, Microsoft Windows and a stat()-based backend.

Home Page: https://emcrisostomo.github.io/fswatch/

License: GNU General Public License v3.0

Shell 1.54% C++ 56.25% C 12.20% Makefile 2.70% M4 24.41% CMake 2.91%

event-notifications change-monitor fswatch kqueue inotify solaris c c-plus-plus

fswatch's Introduction

README

fswatch is a file change monitor that receives notifications when the contents of the specified files or directories are modified. fswatch implements several monitors:

A monitor based on the File System Events API of Apple macOS.
A monitor based on kqueue, a notification interface introduced in FreeBSD 4.1 (and supported on most *BSD systems, including macOS).
A monitor based on the File Events Notification API of the Solaris kernel and its derivatives.
A monitor based on inotify, a Linux kernel subsystem that reports file system changes to applications.
A monitor based on ReadDirectoryChangesW, a Microsoft Windows API that reports changes to a directory.
A monitor which periodically stats the file system, saves file modification times in memory, and manually calculates file system changes (which works anywhere stat (2) can be used).

fswatch should build and work correctly on any system shipping either of the aforementioned APIs.

libfswatch
Features
Limitations
Getting fswatch
Building from Source
Installation
Documentation
Localization
Usage
Contributing
Bug Reports

libfswatch

fswatch is a frontend of libfswatch, a library with C and C++ binding. More information on libfswatch can be found here.

Features

fswatch main features are:

Support for many OS-specific APIs such as kevent, inotify, and FSEvents.
Recursive directory monitoring.
Path filtering using including and excluding regular expressions.
Customizable record format.
Support for periodic idle events.

Limitations

The limitations of fswatch depend largely on the monitor being used:

The FSEvents monitor, available only on macOS, has no known limitations, and scales very well with the number of files being observed.
The File Events Notification monitor, available on Solaris kernels and its derivatives, has no known limitations.
The kqueue monitor, available on any *BSD system featuring kqueue, requires a file descriptor to be opened for every file being watched. As a result, this monitor scales badly with the number of files being observed, and may begin to misbehave as soon as the fswatch process runs out of file descriptors. In this case, fswatch dumps one error on standard error for every file that cannot be opened.
The inotify monitor, available on Linux since kernel 2.6.13, may suffer a queue overflow if events are generated faster than they are read from the queue. In any case, the application is guaranteed to receive an overflow notification which can be handled to gracefully recover. fswatch currently throws an exception if a queue overflow occurs. Future versions will handle the overflow by emitting proper notifications.
The Windows monitor can only establish a watch directories, not files. To watch a file, its parent directory must be watched in order to receive change events for all the directory's children, recursively at any depth. Optionally, change events can be filtered to include only changes to the desired file.
The poll monitor, available on any platform, only relies on available CPU and memory to perform its task. The performance of this monitor degrades linearly with the number of files being watched.

Usage recommendations are as follows:

On macOS, use only the FSEvents monitor (which is the default behaviour).
On Solaris and its derivatives use the File Events Notification monitor.
On Linux, use the inotify monitor (which is the default behaviour).
If the number of files to observe is sufficiently small, use the kqueue monitor. Beware that on some systems the maximum number of file descriptors that can be opened by a process is set to a very low value (values as low as 256 are not uncommon), even if the operating system may allow a much larger value. In this case, check your OS documentation to raise this limit on either a per process or a system-wide basis.
If feasible, watch directories instead of files. Properly crafting the receiving side of the events to deal with directories may sensibly reduce the monitor resource consumption.
On Windows, use the windows monitor.
If none of the above applies, use the poll monitor. The authors' experience indicates that fswatch requires approximately 150 MB of RAM memory to observe a hierarchy of 500.000 files with a minimum path length of 32 characters. A common bottleneck of the poll monitor is disk access, since stat()-ing a great number of files may take a huge amount of time. In this case, the latency should be set to a sufficiently large value in order to reduce the performance degradation that may result from frequent disk access.

Getting fswatch

A regular user may be able to fetch fswatch from the package manager of your OS or a third-party one. If you are looking for fswatch for macOS, you can install it using either MacPorts or Homebrew:

# MacPorts
$ port install fswatch

# Homebrew
$ brew install fswatch

On FreeBSD, fswatch can be installed using pkg:

# pkg install fswatch-mon

Check your favourite package manager and let us know if fswatch is missing there.

Building from Source

A user who wishes to build fswatch should get a release tarball. A release tarball contains everything a user needs to build fswatch on their system, following the instructions detailed in the Installation section below and the INSTALL file.

A developer who wishes to modify fswatch should get the sources (either from a source tarball or cloning the repository) and have the GNU Build System installed on their machine. Please read README.gnu-build-system to get further details about how to bootstrap fswatch from sources on your machine.

Getting a copy of the source repository is not recommended unless you are a developer, you have the GNU Build System installed on your machine, and you know how to bootstrap it on the sources.

Installation

See the INSTALL file for detailed information about how to configure and install fswatch. Since the fswatch builds and uses dynamic libraries, in some platforms you may need to perform additional tasks before you can use fswatch:

Make sure the installation directory of dynamic libraries ($PREFIX/lib) is included in the lookup paths of the dynamic linker of your operating system. The default path, /usr/local/lib, will work in nearly every operating system.
Refreshing the links and cache to the dynamic libraries may be required. In GNU/Linux systems you may need to run ldconfig:
```
$ ldconfig
```

fswatch is a C++ program and a C++ compiler compliant with the C++11 standard is required to compile it. Check your OS documentation for information about how to install the C++ toolchain and the C++ runtime.

No other software packages or dependencies are required to configure and install fswatch but the aforementioned APIs used by the file system monitors.

Documentation

fswatch provides the following documentation:

Texinfo documentation, included with the distribution.
HTML documentation.
PDF documentation.
A wiki page.
A man page.

fswatch official documentation is provided in Texinfo format. This is the most comprehensive source of information about fswatch and the only authoritative one. The man page, in particular, is a stub that suggests the user to use the info page instead.

If you are installing fswatch using a package manager and you would like the PDF manual to be bundled into the package, please send a feature request to the package maintainer.

Localization

fswatch is localizable and internally uses GNU gettext to decouple localizable string from their translation. The currently available locales are:

English (en).
Italian (it).
Spanish (es).

To build fswatch with localization support, you need to have gettext installed on your system. If configure cannot find <libintl.h> or the linker cannot find libintl, then you may need to manually provide their location to configure, usually using the CPPFLAGS and the LDFLAGS variables. See README.macos for an example.

If gettext is not available on your system, fswatch shall build correctly, but it will lack localization support and the only available locale will be English.

Usage

fswatch accepts a list of paths for which change events should be received:

$ fswatch [options] ... path-0 ... path-n

The event stream is created even if any of the paths do not exist yet. If they are created after fswatch is launched, change events will be properly received. Depending on the watcher being used, newly created paths will be monitored after the amount of configured latency has elapsed.

The output of fswatch can be piped to other program in order to process it further:

$ fswatch -0 path | while read -d "" event \
  do \
    // do something with ${event}
  done

To run a command when a set of change events is printed to standard output but no event details are required, then the following command can be used:

$ fswatch -o path | xargs -n1 -I{} program

The behaviour is consistent with earlier versions of fswatch (v. 0.x). Please, read the Compatibility Issues with fswatch v. 0.x section for further information.

By default fswatch chooses the best monitor available on the current platform, in terms of performance and resource consumption. If the user wishes to specify a different monitor, the -m option can be used to specify the monitor by name:

$ fswatch -m kqueue_monitor path

The list of available monitors can be obtained with the -h option.

For more information, refer to the fswatch documentation.

Contributing

Everybody is welcome to contribute to fswatch. Please, see CONTRIBUTING for further information.

Bug Reports

Bug reports can be sent directly to the authors.

Contact the Authors

The author can be contacted on IRC, using the Freenode #fswatch channel.

License

This software is dual-licensed under the GPL v. 3.0 and the Apache License v. 2.0.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

fswatch's People

Contributors

Stargazers

Watchers

Forkers

emaxerrno marceloandrader zuxfoucault yagee-de aleksir bclennox unphased az2tonez staticfloat lucrocha vikrum lloeki nanch swirepe garbelini ksato9700 binarytemple taku-o ayyar chetbox delciotorres tzarskyz jsholmes benesch pieper moffe42 alexmchardy fictorial dartdl royalwang thinkbox nobeans walterdolce myownclone vnd dankeder sachinsudheendra kaanuki ifireall jamesblunt gsamokovarov silky vlaxy linearregression zirias 7imbrook huangjialin caiodangelo josephwinston highpharoah alainodea scm maxgabriel ailnitskiy noscripter yanivkarta zmukwa dluobo darwinbeing fteychene beikezcs donspaulding tonyliu2ca focusware antoinelee cloudxtreme gguitang leepro rizamaemain10 nhi-vanye dolfly johndid ampg99 ahjmorton ashang tagyro alimousazy alma4rebi jijicanyu triplekill itrace modulexcite fxcebx sunyazhou13 ellerbrock liquidairstudios ektapopat bdx0 allidev nickmccurdy mkll lnlab loudbirds linuxex naughtycode samsun639 optionalg jack2007 rowhit connectthefuture

fswatch's Issues

Add verbose mode

This allows developers to debug why, for example the script invokes the action twice.

Add option: --include [regex]

This could be useful in the case that you want to watch for files of a specific type being changed or created, for example:

fswatch src --include '\.coffee$'

If you attempt to achieve this with the following command:

fswatch src/*.coffee

then only changes to .coffee files that exist at the time of calling fswatch will be detected—since the shell expands the glob in the argument, new files won’t be detected.

@emcrisostomo has suggested that until this feature is added, the desired behaviour can be achieved with grep:

fswatch -0 src | while read -d "" i
do
  if echo $i | grep -q "\.coffee$" > /dev/null ; then
    // do something
  fi
done

problems building on ubuntu

It seems to build without any errors, but when running it, it fails to find libfswatch.so.0:

$ ./configure
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... /bin/mkdir -p
checking for gawk... no
checking for mawk... mawk
checking whether make sets $(MAKE)... yes
checking whether make supports nested variables... yes
checking whether make supports nested variables... (cached) yes
checking for style of include used by make... GNU
checking for gcc... gcc
checking whether the C compiler works... yes
checking for C compiler default output file name... a.out
checking for suffix of executables... 
checking whether we are cross compiling... no
checking for suffix of object files... o
checking whether we are using the GNU C compiler... yes
checking whether gcc accepts -g... yes
checking for gcc option to accept ISO C89... none needed
checking whether gcc understands -c and -o together... yes
checking dependency style of gcc... gcc3
checking for ar... ar
checking the archiver (ar) interface... ar
checking build system type... x86_64-unknown-linux-gnu
checking host system type... x86_64-unknown-linux-gnu
checking how to print strings... printf
checking for a sed that does not truncate output... /bin/sed
checking for grep that handles long lines and -e... /bin/grep
checking for egrep... /bin/grep -E
checking for fgrep... /bin/grep -F
checking for ld used by gcc... /usr/bin/ld
checking if the linker (/usr/bin/ld) is GNU ld... yes
checking for BSD- or MS-compatible name lister (nm)... /usr/bin/nm -B
checking the name lister (/usr/bin/nm -B) interface... BSD nm
checking whether ln -s works... yes
checking the maximum length of command line arguments... 1572864
checking whether the shell understands some XSI constructs... yes
checking whether the shell understands "+="... yes
checking how to convert x86_64-unknown-linux-gnu file names to x86_64-unknown-linux-gnu format... func_convert_file_noop
checking how to convert x86_64-unknown-linux-gnu file names to toolchain format... func_convert_file_noop
checking for /usr/bin/ld option to reload object files... -r
checking for objdump... objdump
checking how to recognize dependent libraries... pass_all
checking for dlltool... no
checking how to associate runtime and link libraries... printf %s\n
checking for archiver @FILE support... @
checking for strip... strip
checking for ranlib... ranlib
checking command to parse /usr/bin/nm -B output from gcc object... ok
checking for sysroot... no
checking for mt... mt
checking if mt is a manifest tool... no
checking how to run the C preprocessor... gcc -E
checking for ANSI C header files... yes
checking for sys/types.h... yes
checking for sys/stat.h... yes
checking for stdlib.h... yes
checking for string.h... yes
checking for memory.h... yes
checking for strings.h... yes
checking for inttypes.h... yes
checking for stdint.h... yes
checking for unistd.h... yes
checking for dlfcn.h... yes
checking for objdir... .libs
checking if gcc supports -fno-rtti -fno-exceptions... no
checking for gcc option to produce PIC... -fPIC -DPIC
checking if gcc PIC flag -fPIC -DPIC works... yes
checking if gcc static flag -static works... yes
checking if gcc supports -c -o file.o... yes
checking if gcc supports -c -o file.o... (cached) yes
checking whether the gcc linker (/usr/bin/ld -m elf_x86_64) supports shared libraries... yes
checking whether -lc should be explicitly linked in... no
checking dynamic linker characteristics... GNU/Linux ld.so
checking how to hardcode library paths into programs... immediate
checking whether stripping libraries is possible... yes
checking if libtool supports shared libraries... yes
checking whether to build shared libraries... yes
checking whether to build static libraries... yes
checking for clang++... no
checking for g++... g++
checking whether we are using the GNU C++ compiler... yes
checking whether g++ accepts -g... yes
checking dependency style of g++... gcc3
checking how to run the C++ preprocessor... g++ -E
checking for ld used by g++... /usr/bin/ld -m elf_x86_64
checking if the linker (/usr/bin/ld -m elf_x86_64) is GNU ld... yes
checking whether the g++ linker (/usr/bin/ld -m elf_x86_64) supports shared libraries... yes
checking for g++ option to produce PIC... -fPIC -DPIC
checking if g++ PIC flag -fPIC -DPIC works... yes
checking if g++ static flag -static works... yes
checking if g++ supports -c -o file.o... yes
checking if g++ supports -c -o file.o... (cached) yes
checking whether the g++ linker (/usr/bin/ld -m elf_x86_64) supports shared libraries... yes
checking dynamic linker characteristics... (cached) GNU/Linux ld.so
checking how to hardcode library paths into programs... immediate
checking whether ln -s works... yes
checking for zsh... no
checking for bash... /bin/bash
checking whether g++ supports C++11 features by default... no
checking whether g++ supports C++11 features with -std=c++11... yes
checking CXXFLAGS for maximum warnings... -Wall
checking for stdlib.h... (cached) yes
checking getopt.h usability... yes
checking getopt.h presence... yes
checking for getopt.h... yes
checking for stdbool.h that conforms to C99... yes
checking for _Bool... no
checking for working strtod... yes
checking for getopt_long... yes
checking for realpath... yes
checking for regcomp... yes
checking that generated files are newer than configure... done
configure: creating ./config.status
config.status: creating Makefile
config.status: creating scripts/fswatch-run-bash
config.status: creating scripts/fswatch-run-zsh
config.status: creating config.h
config.status: executing depfiles commands
config.status: executing libtool commands
=== configuring in libfswatch (/home/slang/pkgs/fswatch-1.4.2/libfswatch)
configure: running /bin/bash ./configure --disable-option-checking '--prefix=/usr/local'  --cache-file=/dev/null --srcdir=.
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... /bin/mkdir -p
checking for gawk... no
checking for mawk... mawk
checking whether make sets $(MAKE)... yes
checking whether make supports nested variables... yes
checking whether make supports nested variables... (cached) yes
checking for style of include used by make... GNU
checking for gcc... gcc
checking whether the C compiler works... yes
checking for C compiler default output file name... a.out
checking for suffix of executables... 
checking whether we are cross compiling... no
checking for suffix of object files... o
checking whether we are using the GNU C compiler... yes
checking whether gcc accepts -g... yes
checking for gcc option to accept ISO C89... none needed
checking whether gcc understands -c and -o together... yes
checking dependency style of gcc... gcc3
checking for ar... ar
checking the archiver (ar) interface... ar
checking build system type... x86_64-unknown-linux-gnu
checking host system type... x86_64-unknown-linux-gnu
checking how to print strings... printf
checking for a sed that does not truncate output... /bin/sed
checking for grep that handles long lines and -e... /bin/grep
checking for egrep... /bin/grep -E
checking for fgrep... /bin/grep -F
checking for ld used by gcc... /usr/bin/ld
checking if the linker (/usr/bin/ld) is GNU ld... yes
checking for BSD- or MS-compatible name lister (nm)... /usr/bin/nm -B
checking the name lister (/usr/bin/nm -B) interface... BSD nm
checking whether ln -s works... yes
checking the maximum length of command line arguments... 1572864
checking whether the shell understands some XSI constructs... yes
checking whether the shell understands "+="... yes
checking how to convert x86_64-unknown-linux-gnu file names to x86_64-unknown-linux-gnu format... func_convert_file_noop
checking how to convert x86_64-unknown-linux-gnu file names to toolchain format... func_convert_file_noop
checking for /usr/bin/ld option to reload object files... -r
checking for objdump... objdump
checking how to recognize dependent libraries... pass_all
checking for dlltool... no
checking how to associate runtime and link libraries... printf %s\n
checking for archiver @FILE support... @
checking for strip... strip
checking for ranlib... ranlib
checking command to parse /usr/bin/nm -B output from gcc object... ok
checking for sysroot... no
checking for mt... mt
checking if mt is a manifest tool... no
checking how to run the C preprocessor... gcc -E
checking for ANSI C header files... yes
checking for sys/types.h... yes
checking for sys/stat.h... yes
checking for stdlib.h... yes
checking for string.h... yes
checking for memory.h... yes
checking for strings.h... yes
checking for inttypes.h... yes
checking for stdint.h... yes
checking for unistd.h... yes
checking for dlfcn.h... yes
checking for objdir... .libs
checking if gcc supports -fno-rtti -fno-exceptions... no
checking for gcc option to produce PIC... -fPIC -DPIC
checking if gcc PIC flag -fPIC -DPIC works... yes
checking if gcc static flag -static works... yes
checking if gcc supports -c -o file.o... yes
checking if gcc supports -c -o file.o... (cached) yes
checking whether the gcc linker (/usr/bin/ld -m elf_x86_64) supports shared libraries... yes
checking whether -lc should be explicitly linked in... no
checking dynamic linker characteristics... GNU/Linux ld.so
checking how to hardcode library paths into programs... immediate
checking whether stripping libraries is possible... yes
checking if libtool supports shared libraries... yes
checking whether to build shared libraries... yes
checking whether to build static libraries... yes
checking for clang++... no
checking for g++... g++
checking whether we are using the GNU C++ compiler... yes
checking whether g++ accepts -g... yes
checking dependency style of g++... gcc3
checking how to run the C++ preprocessor... g++ -E
checking for ld used by g++... /usr/bin/ld -m elf_x86_64
checking if the linker (/usr/bin/ld -m elf_x86_64) is GNU ld... yes
checking whether the g++ linker (/usr/bin/ld -m elf_x86_64) supports shared libraries... yes
checking for g++ option to produce PIC... -fPIC -DPIC
checking if g++ PIC flag -fPIC -DPIC works... yes
checking if g++ static flag -static works... yes
checking if g++ supports -c -o file.o... yes
checking if g++ supports -c -o file.o... (cached) yes
checking whether the g++ linker (/usr/bin/ld -m elf_x86_64) supports shared libraries... yes
checking dynamic linker characteristics... (cached) GNU/Linux ld.so
checking how to hardcode library paths into programs... immediate
checking whether g++ supports C++11 features by default... no
checking whether g++ supports C++11 features with -std=c++11... yes
checking CXXFLAGS for maximum warnings... -Wall
checking for stdlib.h... (cached) yes
checking for unistd.h... (cached) yes
checking fcntl.h usability... yes
checking fcntl.h presence... yes
checking for fcntl.h... yes
checking sys/event.h usability... no
checking sys/event.h presence... no
checking for sys/event.h... no
checking sys/inotify.h usability... yes
checking sys/inotify.h presence... yes
checking for sys/inotify.h... yes
checking CoreServices/CoreServices.h usability... no
checking CoreServices/CoreServices.h presence... no
checking for CoreServices/CoreServices.h... no
checking unordered_map usability... yes
checking unordered_map presence... no
configure: WARNING: unordered_map: accepted by the compiler, rejected by the preprocessor!
configure: WARNING: unordered_map: proceeding with the compiler's result
checking for unordered_map... yes
checking unordered_set usability... yes
checking unordered_set presence... no
configure: WARNING: unordered_set: accepted by the compiler, rejected by the preprocessor!
configure: WARNING: unordered_set: proceeding with the compiler's result
checking for unordered_set... yes
checking mutex usability... yes
checking mutex presence... no
configure: WARNING: mutex: accepted by the compiler, rejected by the preprocessor!
configure: WARNING: mutex: proceeding with the compiler's result
checking for mutex... yes
checking for stdbool.h that conforms to C99... yes
checking for _Bool... no
checking for size_t... yes
checking for uint32_t... yes
checking for mode_t... yes
checking for struct stat.st_mtime... yes
checking for struct stat.st_mtimespec... no
checking for std::unique_ptr<std::string>... yes
checking for realpath... yes
checking for modf... yes
checking for regcomp... yes
checking whether kqueue is declared... no
checking whether kevent is declared... no
checking for thread_local storage specifier... yes
checking that generated files are newer than configure... done
configure: creating ./config.status
config.status: creating Makefile
config.status: creating libfswatch_config.h
config.status: executing depfiles commands
config.status: executing libtool commands

$ make
make  all-recursive
make[1]: Entering directory `/home/slang/pkgs/fswatch-1.4.2'
Making all in libfswatch
make[2]: Entering directory `/home/slang/pkgs/fswatch-1.4.2/libfswatch'
make  all-am
make[3]: Entering directory `/home/slang/pkgs/fswatch-1.4.2/libfswatch'
  CXX      c/libfswatch.lo
  CXX      c/libfswatch_log.lo
  CXX      c++/libfswatch_exception.lo
  CXX      c++/event.lo
  CXX      c++/monitor.lo
  CXX      c++/poll_monitor.lo
  CXX      c++/inotify_monitor.lo
  CXX      c++/path_utils.lo
  CXXLD    libfswatch.la
make[3]: Leaving directory `/home/slang/pkgs/fswatch-1.4.2/libfswatch'
make[2]: Leaving directory `/home/slang/pkgs/fswatch-1.4.2/libfswatch'
make[2]: Entering directory `/home/slang/pkgs/fswatch-1.4.2'
  CXX      fswatch.o
  CXX      fswatch_log.o
  CXXLD    fswatch
make[2]: Leaving directory `/home/slang/pkgs/fswatch-1.4.2'
make[1]: Leaving directory `/home/slang/pkgs/fswatch-1.4.2'

$ make check
Making check in libfswatch
make[1]: Entering directory `/home/slang/pkgs/fswatch-1.4.2/libfswatch'
make[1]: Leaving directory `/home/slang/pkgs/fswatch-1.4.2/libfswatch'
make[1]: Entering directory `/home/slang/pkgs/fswatch-1.4.2'
make[1]: Leaving directory `/home/slang/pkgs/fswatch-1.4.2'

$ sudo make install
Making install in libfswatch
make[1]: Entering directory `/home/slang/pkgs/fswatch-1.4.2/libfswatch'
make[2]: Entering directory `/home/slang/pkgs/fswatch-1.4.2/libfswatch'
 /bin/mkdir -p '/usr/local/lib'
 /bin/bash ./libtool   --mode=install /usr/bin/install -c   libfswatch.la '/usr/local/lib'
libtool: install: /usr/bin/install -c .libs/libfswatch.so.0.0.0 /usr/local/lib/libfswatch.so.0.0.0
libtool: install: (cd /usr/local/lib && { ln -s -f libfswatch.so.0.0.0 libfswatch.so.0 || { rm -f libfswatch.so.0 && ln -s libfswatch.so.0.0.0 libfswatch.so.0; }; })
libtool: install: (cd /usr/local/lib && { ln -s -f libfswatch.so.0.0.0 libfswatch.so || { rm -f libfswatch.so && ln -s libfswatch.so.0.0.0 libfswatch.so; }; })
libtool: install: /usr/bin/install -c .libs/libfswatch.lai /usr/local/lib/libfswatch.la
libtool: install: /usr/bin/install -c .libs/libfswatch.a /usr/local/lib/libfswatch.a
libtool: install: chmod 644 /usr/local/lib/libfswatch.a
libtool: install: ranlib /usr/local/lib/libfswatch.a
libtool: finish: PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/sbin" ldconfig -n /usr/local/lib
----------------------------------------------------------------------
Libraries have been installed in:
   /usr/local/lib

If you ever happen to want to link against installed libraries
in a given directory, LIBDIR, you must either use libtool, and
specify the full pathname of the library, or use the `-LLIBDIR'
flag during linking and do at least one of the following:
   - add LIBDIR to the `LD_LIBRARY_PATH' environment variable
     during execution
   - add LIBDIR to the `LD_RUN_PATH' environment variable
     during linking
   - use the `-Wl,-rpath -Wl,LIBDIR' linker flag
   - have your system administrator add LIBDIR to `/etc/ld.so.conf'

See any operating system documentation about shared libraries for
more information, such as the ld(1) and ld.so(8) manual pages.
----------------------------------------------------------------------
 /bin/mkdir -p '/usr/local/share/doc/libfswatch'
 /usr/bin/install -c -m 644 README.md AUTHORS COPYING LICENSE NEWS '/usr/local/share/doc/libfswatch'
 /bin/mkdir -p '/usr/local/include/libfswatch/c'
 /usr/bin/install -c -m 644 c/libfswatch.h c/cevent.h c/cfilter.h c/cmonitor.h c/error.h '/usr/local/include/libfswatch/c'
 /bin/mkdir -p '/usr/local/include/libfswatch/c++'
 /usr/bin/install -c -m 644 c++/monitor.h c++/inotify_monitor.h c++/poll_monitor.h c++/filter.h c++/event.h c++/libfswatch_exception.h '/usr/local/include/libfswatch/c++'
make[2]: Leaving directory `/home/slang/pkgs/fswatch-1.4.2/libfswatch'
make[1]: Leaving directory `/home/slang/pkgs/fswatch-1.4.2/libfswatch'
make[1]: Entering directory `/home/slang/pkgs/fswatch-1.4.2'
make[2]: Entering directory `/home/slang/pkgs/fswatch-1.4.2'
 /bin/mkdir -p '/usr/local/bin'
  /bin/bash ./libtool   --mode=install /usr/bin/install -c fswatch '/usr/local/bin'
libtool: install: /usr/bin/install -c .libs/fswatch /usr/local/bin/fswatch
 /bin/mkdir -p '/usr/local/bin'
 /usr/bin/install -c scripts/fswatch-run-bash scripts/fswatch-run-zsh '/usr/local/bin'
make  install-exec-hook
make[3]: Entering directory `/home/slang/pkgs/fswatch-1.4.2'
rm /usr/local/bin/fswatch-run
ln -s /usr/local/bin/fswatch-run-bash /usr/local/bin/fswatch-run
make[3]: Leaving directory `/home/slang/pkgs/fswatch-1.4.2'
 /bin/mkdir -p '/usr/local/share/doc/fswatch'
 /usr/bin/install -c -m 644 README.bsd README.freebsd README.gnu-build-system README.md README.osx AUTHORS COPYING LICENSE NEWS '/usr/local/share/doc/fswatch'
 /bin/mkdir -p '/usr/local/share/man/man7'
 /usr/bin/install -c -m 644 fswatch.7 '/usr/local/share/man/man7'
make[2]: Leaving directory `/home/slang/pkgs/fswatch-1.4.2'
make[1]: Leaving directory `/home/slang/pkgs/fswatch-1.4.2'

$ fswatch
fswatch: error while loading shared libraries: libfswatch.so.0: cannot open shared object file: No such file or directory

Unable to easily build on Mac

Makefile is gone but didn't add the referenced configure file so can't easily build

The inotify monitor prints diagnostic messages even when not run in verbose mode

fswatch-run needs an help message and a man page

As pointed out by @nobeans in Issue 29, fswatch-run is documented only in README.md. It should print a proper help message and have a man page too.

Get file that changed?

Can fswatch tell me which file in a directory changed? I want to use it to copy files on update as a backup, but I want to know which file to copy. Thanks.

Redirect usage text to sdterr unless -h or --help

Usage instructions should only go to stdout when --help is used. Right now any invalid option/argument causes the whole text to be piped to xargs or whatever is capturing the output.

Add gettext support

MINOR issue; suggestion, even.

Just a suggestion: add an example using xargs, not read, and point out the importance of using -n 1 with it, i.e. fswatch . -0 | xargs -0 -n 1 sshOrWhatever. I couldn't find such an example in your documentation (though it might be in there), and I know a few people who have struggled with this.

Need bundle markers (latency has no effect on the FSEvents monitor).

I want to put a latency so that I "bundle" my changes. There needs to be some way that the output tells me that I've reached the end of a set of updates so I can go process them.

configure error line 2386: syntax error near unexpected token `m4'

After autogen.sh without any warning or error,

fswatch# ./configure
./configure: line 2386: syntax error near unexpected token `m4'
./configure: line 2386: `AC_CONFIG_MACRO_DIRS(m4)'

OS: CentOS release 5.8 (Final) x86_64
Autoreconf: autoreconf (GNU Autoconf) 2.69

multiple folders not working on Mavericks

Sorry I can't leave a more detailed description of what's going on, as I'm not as experienced with C.

I can start fswatch in a certain directory with fswatch app "echo hello", and on another directory in the same parent directory with fswatch test "echo hello". However, fswatch test:app "echo hello" does not echo "hello" for edits in either folder.

Could this be an issue with CFStringCreateWithCString or CFStringCreateArrayBySeparatingStrings (lines 65-66)?

Documentation for fswatch?

I'm trying to convert an inotifywait to fswatch so that I can also use it on a Mac. The command I'm trying to convert is:

inotifywait -r -m 'my_folder/' | while read MODFILE
// etc

Following the example in the README, I created a folder called testfswatch/ and I tried running the following commands in the parent folder and then adding and changing files on the testfswatch/ folder:

fswatch -o testfswatch/ | echo "LALA"
fswatch -o testfswatch/ | someSimpleProgram
fswatch -o testfswatch/ | xargs -n1 -I{} echo "LALA"
fswatch -o testfswatch/ | xargs -n1 -I{} ./someExecutable

None of these commands seem to do anything when I change or add files in the tesfswatch/ folder though.

Does anybody know what I'm doing wrong here? All tips are welcome!

All tips are welcome!

License?

I can't find information on program's license. Could you add one in a LICENSE file or in a file comment?

Allow filtering by event type

Execute Command Only After All IO Operations are Completed

./fswatch /somedir "echo modified"
this command execute echo modified when ever /somedir is changed but the problem is
the command is not aware of IO Operations for an example
if im copying a 300MB File to /somedir the command "echo modified" is being executed several times
modify the tool to wait until the copy operation to fully complete then execute after

No man page when installed using Homebrew

Unable to build source

If I clone your repository there's no configure script. Running autoconf fails as well due to missing dependencies.

Problems building fswatch 1.3.6 on Mac v10.8.5

I just downloaded the 1.3.6 release and tried to configure and make, but I get the error below. Anything special I should feed into configure and/or make?
(Sorry about the crappy formatting :( )

make  all-am
clang++ -DHAVE_CONFIG_H -I.     -g -O2 -std=c++11 -Wall -MT fsevent_monitor.o -MD -MP -MF .deps/fsevent_monitor.Tpo -c -o fsevent_monitor.o fsevent_monitor.cpp
fsevent_monitor.cpp:34:38: error: no matching constructor for initialization of 'const vector<FSEventFlagType>'
static const vector<FSEventFlagType> event_flag_type = {
                                     ^                 ~
/usr/include/c++/4.2.1/bits/stl_vector.h:255:9: note: candidate constructor template not viable: requires at most 3 arguments, but 20 were provided
        vector(_InputIterator __first, _InputIterator __last,
        ^
/usr/include/c++/4.2.1/bits/stl_vector.h:201:7: note: candidate constructor not viable: allows at most single argument '__a', but 20 arguments were provided
      vector(const allocator_type& __a = allocator_type())
      ^
/usr/include/c++/4.2.1/bits/stl_vector.h:213:7: note: candidate constructor not viable: requires at most 3 arguments, but 20 were provided
      vector(size_type __n, const value_type& __value = value_type(),
      ^
/usr/include/c++/4.2.1/bits/stl_vector.h:231:7: note: candidate constructor not viable: requires single argument '__x', but 20 arguments were provided
      vector(const vector& __x)
      ^
1 error generated.
make[1]: *** [fsevent_monitor.o] Error 1
make: *** [all] Error 2

Get fswatch included with homebrew

It would be awesome if homebrew included the ability to install fswatch. I'm not sure how you go about getting a package added to the homebrew repository, but if you did then users with homebrew could install fswatch with:

brew install fswatch

Thanks for a great utility!

Ignore while command is running?

Would it be possible to (optionally) ignore new events while the specified command is running. In the case where the command outputs to the watched directory, this currently created an infinite loop.

fswatch broken on OS X 10.10 Yosemite

After upgrading from OS X 10.9 to 10.10, fswatch doesn't work for me anymore, i.e. it doesn't report file changes anymore. I installed it via homebrew, brew updated, brew doctord, and all is fine. I updated XCode, brew uninstall fswatchd and reinstalled it after the OS upgrade, too, but it just doesn't report file changes anymore.

I feel quite stupid reporting this issue without any further information, but I'm not sure where to start. Are there other ways besides fswatch -v (tells me that SIGTERM, SIGABRT and SIGINT handler have been registered) to debug? Are there dependencies that I should check?

support file-content change watching

Many times an application is interested not in the fact that the modified date changed, but that the actual content of the file changed.

Obviously this does not apply to directories, and adds a whole new set of edge cases to deal with. Is this something which makes sense as part of fswatch, or should it be a separate tool?

Does this no longer take a command to run on file changes?

I just upgraded, and fswatch . "./foo" doesn't run foo anymore, it just prints out a list of the files changes.

Review inotify_add_watch mask

Handle monitor queue overflows.

Both the Windows and the Linux inotify monitor internal buffers may overflow if events are generated too quickly. Currently, fswatch exits with an error. I'd like to add an option to have fswatch emit a placeholder event for queue overflows without exiting, so that callers may gracefully recover.

Watch a directory containing aliases?

Thank you for sharing this!

I have a directory of aliases pointing to files in other directories. Right now any changes to the target file do not trigger an event in the directory containing the alias.

What would be a good way to implement this in fswatch or otherwise?

Cheers :)

Functional changes for version > 0.0.2

I just upgraded by Homebrews and got a new fswatch that works totally differently than before. OK, I can see a point in working more like inotifywatch, but the old API was very useful for me. How about adding a compatibility mode to run some command whenever an event occurs? Maybe something like

fswatch --execute ./do-stuff.sh dir1 dir2 ...

beautiful project home page

I'm wanting to link to fswatch from a project of mine: https://github.com/discoteq/discoteq.rb

It would be really nice to have a beautiful home page for fswatch, or at least a rendered version of the man page.

Freebsd gettext version

Running Freebsd.

in ./configure.ac and ./libfswatch/configure.ac there is a dependency on gettext 0.19.2 . Latest package / port available in Freebsd is currently 0.18.3 . Any special need for 0.19.2 instead of 0.18.3 ?

Support Solaris/Illumos File Events Notification API

Described here: https://blogs.oracle.com/praks/entry/file_events_notification

Event flags are missing mappings for finer-grained monitor backends flags

inotify_monitor does not support recursive scan of directories

Running a command with it's own arguments

Not sure this is the right place to ask, but Stackoverflow didn't come through http://stackoverflow.com/questions/25689589/how-to-run-fswatch-to-call-a-program-with-static-arguments

Basically, I used to use fswatch (0.0.2) like so:

fswatch . 'python manage.py test'

That ran the command python with the two arguments manage.py and test

Since upgrading fswatch I can't figure out a way to run my simple command without writing it into a bash script and then running that. Is there a way to do it? If so, I think it'd be a good thing to add to the wiki / readme - I can't be the only one stuck on this..

BASH read now ignores NUL character

According to this: http://wiki.bash-hackers.org/commands/builtin/read , BASH read now ignores the NUL character. I am trying to find a workaround, and will probably succeed soon enough, but I just wanted to drop a line.

I can't find where to download a "release tarball"

The README directs me to a "release tarball" to install, but I can't find where I can download this from.

Build fails on Ubuntu 14.04.1 LTS

$ autoconf
configure.ac:31: error: possibly undefined macro: AC_CONFIG_MACRO_DIRS
If this token and others are legitimate, please use m4_pattern_allow.
See the Autoconf documentation.
configure.ac:45: error: possibly undefined macro: AM_INIT_AUTOMAKE
configure.ac:46: error: possibly undefined macro: AM_SILENT_RULES
configure.ac:47: error: possibly undefined macro: AM_PROG_AR
configure.ac:59: error: possibly undefined macro: AM_GNU_GETTEXT
configure.ac:60: error: possibly undefined macro: AM_GNU_GETTEXT_VERSION
configure.ac:71: error: possibly undefined macro: AM_CONDITIONAL

$ cat /etc/issue
Ubuntu 14.04.1 LTS \n \l

$ autoconf -V
autoconf (GNU Autoconf) 2.69
Copyright (C) 2012 Free Software Foundation, Inc.
License GPLv3+/Autoconf: GNU GPL version 3 or later
http://gnu.org/licenses/gpl.html, http://gnu.org/licenses/exceptions.html
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Written by David J. MacKenzie and Akim Demaille.

Update fswatch-run to accept multiple path arguments

Currenty, fswatch-run accepts only two arguments: one for the path to watch and another for the command to run. Consider adding the possibility of specifying multiple path arguments.

How to check which file got modified?

I couldn't figure it out or find in the examples/man. Is it even possible?

broken fswatch-run symlink installed if using DESTDIR=...

If installing using make install DESTIR=... the fswatch-run symlink incorrectly points into the destdir.

The fix is to remove $(DESTDIR) from the source part when creating the symlink.

In fact since the source and destination are in the same directory there's no need to use the absolute path at all.

This patch should fix this:

--- Makefile.am.orig    2014-09-04 05:24:39.000000000 -0500
+++ Makefile.am 2014-09-07 19:59:51.000000000 -0500
@@ -37,10 +37,10 @@

 install-exec-hook: fswatch-remove-links
 if HAVE_ZSH
-   $(LN_S) $(DESTDIR)$(bindir)/fswatch-run-zsh $(DESTDIR)$(bindir)/fswatch-run
+   $(LN_S) fswatch-run-zsh $(DESTDIR)$(bindir)/fswatch-run
 else
 if HAVE_BASH
-   $(LN_S) $(DESTDIR)$(bindir)/fswatch-run-bash $(DESTDIR)$(bindir)/fswatch-run
+   $(LN_S) fswatch-run-bash $(DESTDIR)$(bindir)/fswatch-run
 else
    @echo "No compatible shell was found for fswatch-run."
 endif

Add support for custom record format (Was: Add separator character)

Right now you're just appending event flags with spacing. I'd like to be able to specify something besides space because my filenames have spaces in them. Makes parsing harder.

watch a file?

Nice!

Would it be possible to watch a single file instead of a complete directory?

cheers
Mark

Check for candidate code reuse between the poll and the inotify watcher.

Have monitor exit when -1/--one-shot is used instead of using ::exit().

A patch has been applied that makes fsw exit using ::exit() after the first even is notified when the -1/--one-shot option is used. Monitor cleanup is performed using a function registered with ::atexit(), but in this simple case I believe a better solution would be having the monitor exit from the run loop to have main() return instead of terminating the process with ::exit().

Add watch filters to prevent action being invoked twice

I'm fswatch to watch my unit tests and source code directories run some tests automatically on file change. This works fairly well, but every modification I seem to make causes two events. I'm guessing this is

one for the modified file
one for the directory

This is undesirable and inconvenient.

install fswatch via aptitude/apt-get

releasing a debian package would be really helpful for linux users

Ignoring some files?

Would it be possible to specify a list of files to ignore? Typical use case: avoiding re-running the unit tests when vim's swap file changes.
Thanks for the work so far!

Update man page

Man page has been merged from fsw where every reference to fsw has been substituted with a reference to fswatch. However, the man page should be review and documentation about all the monitors should be updated (the inotify monitor is missing altogether).

Allow excluding file patterns by passing in a file

Basically what I'd like is to pass in my .gitignore file(s) and have it exclude everything that matches rather than specify everything via regexp.