Home

Awesome

License

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:

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

Table of Contents

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:

Limitations

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

Usage recommendations are as follows:

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:

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:

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:

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.


Copyright (c) 2013-2021 Enrico M. Crisostomo

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/.