1[](https://github.com/emcrisostomo/fswatch/blob/master/COPYING) 2 3README 4====== 5 6`fswatch` is a file change monitor that receives notifications when the contents 7of the specified files or directories are modified. `fswatch` implements 8several monitors: 9 10 * A monitor based on the _File System Events API_ of Apple OS X. 11 * A monitor based on _kqueue_, a notification interface introduced in FreeBSD 12 4.1 (and supported on most *BSD systems, including OS X). 13 * A monitor based on the _File Events Notification_ API of the Solaris kernel 14 and its derivatives. 15 * A monitor based on _inotify_, a Linux kernel subsystem that reports file 16 system changes to applications. 17 * A monitor based on _ReadDirectoryChangesW_, a Microsoft Windows API that 18 reports changes to a directory. 19 * A monitor which periodically stats the file system, saves file modification 20 times in memory, and manually calculates file system changes (which works 21 anywhere `stat (2)` can be used). 22 23`fswatch` should build and work correctly on any system shipping either of the 24aforementioned APIs. 25 26Table of Contents 27----------------- 28 29 * [libfswatch](#libfswatch) 30 * [Features](#features) 31 * [Limitations](#limitations) 32 * [Getting fswatch](#getting-fswatch) 33 * [Building from Source](#building-from-source) 34 * [Installation](#installation) 35 * [Documentation](#documentation) 36 * [Localization](#localization) 37 * [Usage](#usage) 38 * [Contributing](#contributing) 39 * [Bug Reports](#bug-reports) 40 41libfswatch 42---------- 43 44`fswatch` is a frontend of `libfswatch`, a library with C and C++ binding. More 45information on `libfswatch` can be found [here][README.libfswatch.md]. 46 47[README.libfswatch.md]: README.libfswatch.md 48 49Features 50-------- 51 52`fswatch` main features are: 53 54 * Support for many OS-specific APIs such as kevent, inotify, and FSEvents. 55 * Recursive directory monitoring. 56 * Path filtering using including and excluding regular expressions. 57 * Customizable record format. 58 * Support for periodic idle events. 59 60Limitations 61----------- 62 63The limitations of `fswatch` depend largely on the monitor being used: 64 65 * The **FSEvents** monitor, available only on OS X, has no known limitations, 66 and scales very well with the number of files being observed. 67 68 * The **File Events Notification** monitor, available on Solaris kernels and 69 its derivatives, has no known limitations. 70 71 * The **kqueue** monitor, available on any \*BSD system featuring kqueue, 72 requires a file descriptor to be opened for every file being watched. As a 73 result, this monitor scales badly with the number of files being observed, 74 and may begin to misbehave as soon as the `fswatch` process runs out of file 75 descriptors. In this case, `fswatch` dumps one error on standard error for 76 every file that cannot be opened. 77 78 * The **inotify** monitor, available on Linux since kernel 2.6.13, may suffer 79 a queue overflow if events are generated faster than they are read from the 80 queue. In any case, the application is guaranteed to receive an overflow 81 notification which can be handled to gracefully recover. `fswatch` 82 currently throws an exception if a queue overflow occurs. Future versions 83 will handle the overflow by emitting proper notifications. 84 85 * The **Windows** monitor can only establish a watch _directories_, not files. 86 To watch a file, its parent directory must be watched in order to receive 87 change events for all the directory's children, _recursively_ at any depth. 88 Optionally, change events can be filtered to include only changes to the 89 desired file. 90 91 * The **poll** monitor, available on any platform, only relies on 92 available CPU and memory to perform its task. The performance of this 93 monitor degrades linearly with the number of files being watched. 94 95Usage recommendations are as follows: 96 97 * On OS X, use only the `FSEvents` monitor (which is the default behaviour). 98 99 * On Solaris and its derivatives use the _File Events Notification_ monitor. 100 101 * On Linux, use the `inotify` monitor (which is the default behaviour). 102 103 * If the number of files to observe is sufficiently small, use the `kqueue` 104 monitor. Beware that on some systems the maximum number of file descriptors 105 that can be opened by a process is set to a very low value (values as low as 106 256 are not uncommon), even if the operating system may allow a much larger 107 value. In this case, check your OS documentation to raise this limit on 108 either a per process or a system-wide basis. 109 110 * If feasible, watch directories instead of files. Properly crafting the 111 receiving side of the events to deal with directories may sensibly reduce 112 the monitor resource consumption. 113 114 * On Windows, use the `windows` monitor. 115 116 * If none of the above applies, use the poll monitor. The authors' experience 117 indicates that `fswatch` requires approximately 150 MB of RAM memory to 118 observe a hierarchy of 500.000 files with a minimum path length of 32 119 characters. A common bottleneck of the poll monitor is disk access, since 120 `stat()`-ing a great number of files may take a huge amount of time. In 121 this case, the latency should be set to a sufficiently large value in order 122 to reduce the performance degradation that may result from frequent disk 123 access. 124 125Getting fswatch 126--------------- 127 128A regular user may be able to fetch `fswatch` from the package manager of your 129OS or a third-party one. If you are looking for `fswatch` for OS X, you can 130install it using either [MacPorts] or [Homebrew]: 131 132``` 133# MacPorts 134$ port install fswatch 135 136# Homebrew 137$ brew install fswatch 138``` 139 140Check your favourite package manager and let us know if `fswatch` is missing 141there. 142 143[MacPorts]: https://www.macports.org 144[Homebrew]: http://brew.sh 145 146Building from Source 147-------------------- 148 149A user who wishes to build `fswatch` should get a [release tarball][release]. 150A release tarball contains everything a user needs to build `fswatch` on their 151system, following the instructions detailed in the Installation section below 152and the `INSTALL` file. 153 154A developer who wishes to modify `fswatch` should get the sources (either from a 155source tarball or cloning the repository) and have the GNU Build System 156installed on their machine. Please read `README.gnu-build-system` to get further 157details about how to bootstrap `fswatch` from sources on your machine. 158 159Getting a copy of the source repository is not recommended unless you are a 160developer, you have the GNU Build System installed on your machine, and you know 161how to bootstrap it on the sources. 162 163[release]: https://github.com/emcrisostomo/fswatch/releases 164 165Installation 166------------ 167 168See the `INSTALL` file for detailed information about how to configure and 169install `fswatch`. Since the `fswatch` builds and uses dynamic libraries, in 170some platforms you may need to perform additional tasks before you can use 171`fswatch`: 172 173 * Make sure the installation directory of dynamic libraries (`$PREFIX/lib`) is 174 included in the lookup paths of the dynamic linker of your operating system. 175 The default path, `/usr/local/lib`, will work in nearly every operating 176 system. 177 * Refreshing the links and cache to the dynamic libraries may be required. In 178 GNU/Linux systems you may need to run `ldconfig`: 179 180 $ ldconfig 181 182`fswatch` is a C++ program and a C++ compiler compliant with the C++11 standard 183is required to compile it. Check your OS documentation for information about 184how to install the C++ toolchain and the C++ runtime. 185 186No other software packages or dependencies are required to configure and install 187`fswatch` but the aforementioned APIs used by the file system monitors. 188 189Documentation 190------------- 191 192`fswatch` provides the following [documentation]: 193 194 * Texinfo documentation, included with the distribution. 195 * HTML documentation. 196 * PDF documentation. 197 * A [wiki] page. 198 * A man page. 199 200`fswatch` official documentation is provided in Texinfo format. This is the 201most comprehensive source of information about `fswatch` and the only 202authoritative one. The man page, in particular, is a stub that suggests the 203user to use the info page instead. 204 205If you are installing `fswatch` using a package manager and you would like the 206PDF manual to be bundled into the package, please send a feature request to the 207package maintainer. 208 209[documentation]: http://emcrisostomo.github.io/fswatch/doc 210[wiki]: https://github.com/emcrisostomo/fswatch/wiki 211 212Localization 213------------ 214 215`fswatch` is localizable and internally uses GNU `gettext` to decouple 216localizable string from their translation. The currently available locales are: 217 218 * English (`en`). 219 * Italian (`it`). 220 * Spanish (`es`). 221 222To build `fswatch` with localization support, you need to have `gettext` 223installed on your system. If `configure` cannot find `<libintl.h>` or the 224linker cannot find `libintl`, then you may need to manually provide their 225location to `configure`, usually using the `CPPFLAGS` and the `LDFLAGS` 226variables. See `README.osx` for an example. 227 228If `gettext` is not available on your system, `fswatch` shall build correctly, 229but it will lack localization support and the only available locale will be 230English. 231 232Usage 233----- 234 235`fswatch` accepts a list of paths for which change events should be received: 236 237 $ fswatch [options] ... path-0 ... path-n 238 239The event stream is created even if any of the paths do not exist yet. If they 240are created after `fswatch` is launched, change events will be properly 241received. Depending on the watcher being used, newly created paths will be 242monitored after the amount of configured latency has elapsed. 243 244The output of `fswatch` can be piped to other program in order to process it 245further: 246 247 $ fswatch -0 path | while read -d "" event \ 248 do \ 249 // do something with ${event} 250 done 251 252To run a command when a set of change events is printed to standard output but 253no event details are required, then the following command can be used: 254 255 $ fswatch -o path | xargs -n1 -I{} program 256 257The behaviour is consistent with earlier versions of `fswatch` (v. 0.x). 258Please, read the _Compatibility Issues with fswatch v. 0.x_ section for further 259information. 260 261By default `fswatch` chooses the best monitor available on the current platform, 262in terms of performance and resource consumption. If the user wishes to specify 263a different monitor, the `-m` option can be used to specify the monitor by name: 264 265 $ fswatch -m kqueue_monitor path 266 267The list of available monitors can be obtained with the `-h` option. 268 269For more information, refer to the `fswatch` documentation. 270 271Contributing 272------------ 273 274Everybody is welcome to contribute to `fswatch`. Please, see 275[`CONTRIBUTING`][contrib] for further information. 276 277[contrib]: CONTRIBUTING.md 278 279Bug Reports 280----------- 281 282Bug reports can be sent directly to the authors. 283 284Contact the Authors 285------------------- 286 287The author can be contacted on IRC, using the Freenode `#fswatch` channel. 288 289----- 290 291Copyright (c) 2013-2017 Enrico M. Crisostomo 292 293This program is free software; you can redistribute it and/or modify it under 294the terms of the GNU General Public License as published by the Free Software 295Foundation; either version 3, or (at your option) any later version. 296 297This program is distributed in the hope that it will be useful, but WITHOUT ANY 298WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A 299PARTICULAR PURPOSE. See the GNU General Public License for more details. 300 301You should have received a copy of the GNU General Public License along with 302this program. If not, see <http://www.gnu.org/licenses/>. 303
){kind=link}