README
¶
filewatch
A Go library to watch for changes of a file or a directory and its contents.
Overview
This library allows one to watch for file changes in a directory with
the option of watching sub-directories recursively or to just watch a
single file. See filewatch.go for full documentation and usage.
Also, demo/demo.go contains a simple monitoring program illustrating
the usage of the library.
Known Issues
A file change is detected when the scanned modification time differs
from a previously taken modification time or the size of a file has
changed. However, even though time package in Go's standard library
allows specifying the nanosecond in the time.Time type, this
nanosecond isn't recorded when writing a change to a file (most likely
depends on the underlying OS). Thus, if a change or a series occurs
to a file or directory within a single second and the size hasn't
changed from the last recorded file change then no change will be
detected. In practice, this issue may be pretty rare depending on how
one uses the library but important to note.
License
Zlib
Documentation
¶
Overview ¶
Package filewatch provides a utility to watch a file or directory for changes.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Watch ¶
func Watch(done <-chan struct{}, path string, recurse bool, interval *time.Duration) (<-chan []Update, error)
Watches a file or the contents of a directory for changes.
This function can watch an individual file or the contents of directory on a set interval and any changes will be aggregated to a slice and sent to the returned channel. Path will be resolved to its absolute path and failure to do so will return an error. If path is a directory then that directory along with all of its contents will be watched and when recurse is set to true then any files and directories within sub-directories of path will be watched.
The default interval to check for updates is every two seconds unless interval is non nil which then that is used. If interval is non nil and is less than or equal to zero than an error is returned. Watch will continue to scan for file changes on the set interval until a value is received from the done channel or it is closed. Changes are pushed to the returned channel only when actual changes are detected. In other words, Watch will never send an empty slice unless the done channel is closed which causes the returned channel to be closed.
If an error occurs when checking for a change of a file or directory during an update scan then that error is attached to the Update.Error field and Watch will continue scanning on its regular interval. If the error was caused due to the file or directory being deleted then the error will still be attached to Update.Error but Update.WasRemoved will also be set to true and the file or directory will no longer be watched.
Since Watch uses filepath.Walk to setup which files to watch means that it will not follow symbolic links even when recurse is true. If an error is encountered on the initial walk of a directory then that error is returned and no files are watched. If the setup is successful then the returned channel will immediately receive an initial value of each file or directory being watched and the Update.WasAdded field will be set to true.
Types ¶
type Update ¶
type Update struct {
AbsPath string // absolute file path of the file that was updated
Prev os.FileInfo // previous file info from the last update
Next os.FileInfo // file info received for this update
Error error // an error if one occurred
WasRemoved bool // was removed from last update
WasAdded bool // was added since last update
}
Source Files
Directories