fsnotify
Cross-platform file system notifications for Go.
What is it?
What it is
Cross‑platform file system notification library for Go, formerly known as gofsnotify/fsnotify, providing a unified API to watch files and directories for changes across Linux, Windows, macOS, and FreeBSD.
Why it exists
To give Go programs a simple, thread‑safe way to receive file system events (create, write, remove, rename, chmod) with consistent semantics and path handling across major operating systems, including support for recursive directory watching and automatic handling of new subdirectories.
Who should use it
Developers building Go applications requiring real-time file system monitoring, such as live reload servers, configuration watchers, or automated build tools.
Who should avoid it
Users who do not need file system event tracking or prefer polling-based solutions. Not recommended for non-Go projects.
How it works
A quick walkthrough in plain English
How fswatcher works
Step 1 of 3
You interact with it
Open fswatcher, send a request, or connect it to your stack.
Features
Advantages
- Easy to integrate into Go projects with minimal dependencies
- Supports all major desktop operating systems
- Provides consistent event semantics across platforms
- Recursive watching eliminates manual bookkeeping of subdirectories
- Thread‑safe design simplifies concurrent use
- Event ordering guarantees reliable processing
- Canonicalized paths prevent duplicate watches and simplify path handling
- Open source with permissive MIT license
Disadvantages
- Relies on OS‑specific backends; may not work on very old or uncommon systems
- Limited by OS constraints such as maximum number of watches (e.g., inotify limits)
- Performance overhead can be significant under very high event rates
- Does not support watching network file systems with full semantics on all platforms
- Requires Go 1.13+ (purego FSEvents may add runtime overhead)
- No built‑in filtering or ignore patterns beyond user‑defined logic
Installation
native
go get github.com/fswatcher/fswatcher
FAQ
How do I install fswatcher in my Go project?
Run `go get github.com/fswatcher/fswatcher` to download and add the module to your project. The package can then be imported with `import "github.com/fswatcher/fswatcher"`.
What is the difference between `Add` and `AddRecursive`?
`Add` watches a single path for the specified events. `AddRecursive` watches a directory and all its current subdirectories; any new subdirectories created after registration are automatically watched, and removing a subdirectory drops it from the watch list. `Remove` can only be called on the original recursive root.
How do I handle paths that may be written in different forms?
Use `Canonicalize(path)` to convert any path to the internal canonical form used by fswatcher. This resolves symlinks, normalizes case and short names on Windows, and ensures that event names are always in this canonical form.
Which operating systems are supported by fswatcher?
fswatcher supports Linux (inotify), Windows (ReadDirectoryChangesW), macOS (FSEvents via purego), and FreeBSD (kqueue). The backend used depends on the OS at runtime.
How do I receive and handle events and errors?
After creating a watcher with `NewWatcher()`, read from the `Events` channel for `Event` structs and from the `Errors` channel for non‑fatal errors. Example: `select { case ev := <-w.Events: ... case err := <-w.Errors: ... }`.
Featured in Videos
YouTube tutorials and walkthroughs for fsnotify
Alternatives
Similar projects ranked by category, topics, and text overlap.