Documentation
¶
Overview ¶
Package watcher provides a thin wrapper around fsnotify for watching file system paths. It offers a configurable interface to register event and error handlers, and ensures safe lifecycle management of the watcher.
The Watcher struct is the main type that manages:
- Configured paths to watch
- Event handlers for file changes
- Error handlers for watcher errors
Example usage:
events := make(chan fsnotify.Event, 1)
errors := make(chan error, 1)
w, err := watcher.Create(
watcher.OnPath("/tmp"),
watcher.WithEventChainAsHandler(events),
watcher.WithErrorChainAsHandler(errors),
)
if err != nil {
log.Fatalf("failed to create watcher: %v", err)
}
if err := w.Start(); err != nil {
log.Fatalf("failed to start watcher: %v", err)
}
go func() {
for {
select {
case e := <-events:
fmt.Println("file event:", e)
case err := <-errors:
fmt.Println("watcher error:", err)
}
}
}
defer w.Close()
Index ¶
- Variables
- type Option
- func OnPath(path string) Option
- func OnPaths(paths ...string) Option
- func WatchSubfolders(enabled bool) Option
- func WithErrorChainAsHandler(eventsCh chan<- error) Option
- func WithErrorEventHandler(handler func(error)) Option
- func WithEventChainAsHandler(eventsCh chan<- fsnotify.Event) Option
- func WithEventHandler(handler func(fsnotify.Event)) Option
- type Watcher
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNoPathsConfigured is returned when Start is called // without any paths configured to watch. ErrNoPathsConfigured = errors.New("no paths has been configured") )
Functions ¶
This section is empty.
Types ¶
type Option ¶
Option represents a configuration option that can be applied to a Watcher.
func WatchSubfolders ¶ added in v1.4.4
WatchSubfolders enables or disables recursive monitoring of subfolders.
By default, fsnotify does not watch subfolders of a directory automatically. When enabled, this option ensures that all nested directories are included in the watch scope, so events such as file creation, modification, renaming, or deletion inside subdirectories will also be detected. Parameters:
- enabled: set to true to include subfolders in the watch, false to restrict watching only to the top-level directory.
func WithErrorChainAsHandler ¶
WithErrorChainAsHandler sends all watcher errors to the provided channel. This is useful for external error handling loops.
func WithErrorEventHandler ¶
WithErrorEventHandler sets the error handler that will be called whenever the watcher encounters an error.
func WithEventChainAsHandler ¶
WithEventChainAsHandler sends all file system events to the provided channel. This is useful for external event processing loops.
func WithEventHandler ¶
WithEventHandler sets the event handler that will be called whenever a file system event occurs on a watched path.
type Watcher ¶ added in v1.4.4
type Watcher struct {
// contains filtered or unexported fields
}
Watcher wraps fsnotify.Watcher and provides higher-level configuration via functional options. It simplifies setting up file system watchers with custom event and error handlers.
It tracks its lifecycle (`started`) and ensures consistent behavior when adding paths or starting multiple times.
func Create ¶ added in v1.4.4
Create creates a new Watcher with the given options.
Example:
w, err := watcher.Create(
watcher.OnPath("/tmp"),
watcher.WithEventHandler(func(e fsnotify.Event) { fmt.Println(e) }),
)
if err != nil {
log.Fatal(err)
}
func (*Watcher) AddPath ¶ added in v1.4.4
AddPath adds a new path to the watcher. It must be called before Start. If the watcher has already been started, this returns ErrOnStartedStateNotAllowingNewPath.
The path must exist on the filesystem, otherwise an error is returned.
func (*Watcher) Start ¶ added in v1.4.4
Start initializes the underlying fsnotify.Watcher and begins watching all configured paths. It also launches the event processing goroutine.
Returns ErrNoPathsConfigured if no paths were added.
After Start, the watcher cannot accept new paths (AddPath will fail).
Source Files