fswatch Documentation

1. Project Overview & Quickstart (emcrisostomo/fswatch) Copy Chapter

File: README.md Copy Chapter

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 fanotify, a Linux kernel subsystem that reports file
  system events 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.

Table of Contents Copy Chapter

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

libfswatch Copy Chapter

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

Features Copy Chapter

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, with
  legacy and conjunctive evaluation modes.
• Customizable record format.
• Support for periodic idle events.

Limitations Copy Chapter

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
  from several limitations. It provides no information about the user or
  process that triggered an event, so it cannot easily distinguish events it
  triggers itself from those triggered by other processes. It reports only
  events triggered through the filesystem API, so it does not catch remote
  events on network filesystems and cannot monitor pseudo-filesystems such as
  /proc, /sys, or /dev/pts. It also does not report accesses or
  modifications that occur through mmap(2), msync(2), or munmap(2).
  Events identify files by name, but the name may already have been deleted
  or renamed by the time the application handles the event. Events are also
  identified by watch descriptors, so applications must cache a mapping to
  pathnames if they need one, and directory renames can affect several cached
  pathnames at once. Inotify monitoring of directories is not recursive, so
  additional watches must be created for subdirectories, and that can take a
  significant amount of time on large trees. If a new subdirectory appears
  or is renamed into a monitored tree, the application may need to rescan it
  immediately after adding the watch so that it does not miss children that
  already exist. The event queue can overflow, in which case events are lost
  and robust applications may need to rebuild some or all of their cache.
  Finally, if a filesystem is mounted on top of a monitored directory, no
  event is generated until the filesystem is unmounted again.

• The fanotify monitor, available on Linux since kernel 2.6.37, reports
  only events triggered through the filesystem API, so it does not catch
  remote events on network filesystems. It also does not report accesses or
  modifications that occur through mmap(2), msync(2), or munmap(2).
  Directory events are generated only when the directory itself is opened,
  read, and closed, so adding, removing, or changing children does not create
  events for the monitored directory itself. Fanotify monitoring of
  directories is not recursive: subdirectories require additional marks, and
  using FAN_CREATE to detect them is racy because events may be lost before
  the new mark is added. Monitoring mounts or entire filesystems avoids this
  race. The event queue can also overflow, in which case events are lost.

• 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 Copy Chapter

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 Copy Chapter

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 (i) you are a
developer, (ii) you have the GNU Build System installed on your machine, and
(iii) you know how to bootstrap it on the sources.

CMake-support is unofficially offered as a courtesy.

On Windows, MSYS2 with a MinGW-w64 toolchain is the recommended build
environment. Cygwin builds are kept for compatibility, but Cygwin is not
required to build fswatch on Windows. See README.windows for details.

Installation Copy Chapter

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:

  text Copy

  $ ldconfig

fswatch is a C++ program and a C++ compiler compliant with the C++ standard
currently used is required.

As of version 1.17.1 included, fswatch has required a C++11-compliant
compiler. Subsequent versions require a C++17-compliant compiler. 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 Copy Chapter

fswatch provides the following documentation:

• Texinfo documentation, included with the distribution.
• HTML documentation.
• PDF documentation.
• The GitHub website.
• 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.

The project website also provides maintained online documentation and release
resources.

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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

Bug Reports Copy Chapter

Bug reports can be sent directly to the authors.

Contact the Authors Copy Chapter

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

License Copy Chapter

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

Copyright (c) 2013-2026 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/.

File: README.libfswatch.md Copy Chapter

README

libfswatch is a library that provides developers the functionality of
fswatch, the main libfswatch frontend. The library provides both C and C++
bindings. Go bindings are also available.

libfswatch provides the following documentation:

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

libfswatch official documentation is provided in Texinfo format. This is the
most comprehensive source of information about libfswatch 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 libfswatch 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.

Bug Reports Copy Chapter

Bug reports can be sent directly to the authors.

Contact the Authors Copy Chapter

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

Copyright (c) 2013-2025 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/.

2. Official Technical Reference & Guides (emcrisostomo/docs) Copy Chapter

Rancher Docs Copy Chapter

Running for development/editing Copy Chapter

The rancher/docs:dev docker image runs a live-updating server. To run on your workstation, run:

Linux

./scripts/dev

Windows

./scripts/dev-windows.ps1

and then navigate to http://localhost:9001/. You can customize the port by passing it as an argument:

Linux

./scripts/dev 8080

Windows

./scripts/dev-windows.ps1 -port 8080

License

Copyright (c) 2014-2019 Rancher Labs, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.