| Type: | Package |
| Title: | Watch the File System for Changes |
| Version: | 0.1.4 |
| Description: | R binding for 'libfswatch', a file system monitoring library. Watch files, or directories recursively, for changes in the background. Log activity, or run an R function every time a change event occurs. |
| License: | MIT + file LICENSE |
| URL: | https://watcher.r-lib.org, https://github.com/r-lib/watcher |
| BugReports: | https://github.com/r-lib/watcher/issues |
| Depends: | R (≥ 3.5) |
| Imports: | later, R6, rlang |
| Suggests: | testthat (≥ 3.0.0) |
| Biarch: | true |
| Config/Needs/website: | tidyverse/tidytemplate |
| Config/testthat/edition: | 3 |
| Config/usethis/last-upkeep: | 2025-04-23 |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.2 |
| SystemRequirements: | 'libfswatch', or 'cmake' to compile from package sources |
| NeedsCompilation: | yes |
| Packaged: | 2025-07-16 07:06:25 UTC; shikokuchuo |
| Author: | Charlie Gao  [aut,
cre],
Posit Software, PBC  [cph,
fnd] |
| Maintainer: | Charlie Gao <charlie.gao@posit.co> |
| Repository: | CRAN |
| Date/Publication: | 2025-07-16 09:30:02 UTC |
watcher: Watch the File System for Changes
Description
R binding for 'libfswatch', a file system monitoring library. Watch files, or directories recursively, for changes in the background. Log activity, or run an R function every time a change event occurs.
Author(s)
Maintainer: Charlie Gao charlie.gao@posit.co (ORCID)
Other contributors:
Posit Software, PBC (03wc8by49) [copyright holder, funder]
See Also
Useful links:
Report bugs at https://github.com/r-lib/watcher/issues
Watch a Filesystem Location
Description
Create a 'Watcher' on a filesystem location to monitor for changes in the background.
Usage
watcher(path = getwd(), callback = NULL, latency = 1)
Arguments
path |
Character path to a file, or directory to watch recursively, or a vector of paths. Defaults to the current working directory. |
callback |
A function or formula (see rlang::as_function), which takes
at least one argument. It will be called back with a character vector
comprising the paths of all files that have changed. The default, |
latency |
Numeric latency in seconds for events to be reported or callbacks triggered. The default is 1s. |
Details
Uses an optimal event-driven API for each platform: 'ReadDirectoryChangesW' on Windows, 'FSEvents' on MacOS, 'inotify' on Linux, 'kqueue' on BSD, and 'File Events Notification' on Solaris/Illumos.
Note: the latency setting controls how often the changes are processed, and
does not mean that changes are polled for at this interval. The changes are
monitored in an event-driven fashion by the platform-specific monitor. Events
are 'bubbled' such that a single change that triggers multiple filesystem
events will cause the callback to be called only once.
It is possible to set a watch on a path that does not currently exist, and it will be monitored once created.
Value
A 'Watcher' R6 class object.
Watcher Methods
A Watcher is an R6 class with the following methods:
-
$start()starts background monitoring. Returns logicalTRUEupon success,FALSEotherwise. -
$stop()stops background monitoring. Returns logicalTRUEupon success,FALSEotherwise. -
$get_path()returns the watched path as a character string. -
$is_running()returns logicalTRUEorFALSEdepending on whether the monitor is running.
Examples
w <- watcher(tempdir())
w$start()
w
w$get_path()
w$stop()
w$is_running()
Sys.sleep(1)