watcher

README

go-watcher

Package watcher provides a simple, thread-safe, polling-based filesystem watcher.

It allows you to monitor files and directories for changes (Create, Write, Remove) recursively. The watcher operates by periodically scanning the watched paths for modifications, making it a reliable choice across different platforms where native filesystem event notifications might be inconsistent.

Features:

• Watches directories recursively and can also watch individual files.
• Thread-safe: paths can be added or removed from the watchlist from multiple goroutines.
• Simple event system using a channel.

Basic Usage Snippet

The following snippet demonstrates how to create a watcher, add a path, and listen for events within your application.

// Create a new watcher. A 200ms poll interval is a reasonable default.
w := watcher.New(200 * time.Millisecond)
defer w.Close() // Ensure the watcher is closed gracefully on shutdown.

// Start a background goroutine to handle events.
go func() {
    for event := range w.Events {
        // When w.Close() is called, the Events channel will be closed,
        // and this for...range loop will exit.
        fmt.Println(event) // e.g., "Event{Path: "/path/to/file.txt", Op: WRITE}"
    }
}()

// Add a path to watch. This can be a directory or a single file.
// This call is thread-safe, so you can call it from other goroutines as well.
if err := w.Watch("/path/to/your/directory"); err != nil {
    log.Fatalln(err)
}

// Your main application logic continues here...
// The watcher will run in the background.
// To stop the watcher and its background goroutine, simply call w.Close().

Documentation

Overview

Package watcher provides a simple, thread-safe, polling-based filesystem watcher.

It allows you to monitor files and directories for changes (Create, Write, Remove) recursively. The watcher operates by periodically scanning the watched paths for modifications, making it a reliable choice across different platforms where native filesystem event notifications might be inconsistent.

Features:

• Watches directories recursively and can also watch individual files.
• Thread-safe: paths can be added or removed from the watchlist from multiple goroutines.
• Simple event system using a channel.

Basic Usage Snippet

The following snippet demonstrates how to create a watcher, add a path, and listen for events within your application.

// Create a new watcher. A 200ms poll interval is a reasonable default.
w := watcher.New(200 * time.Millisecond)
defer w.Close() // Ensure the watcher is closed gracefully on shutdown.

// Start a background goroutine to handle events.
go func() {
	for event := range w.Events {
		// When w.Close() is called, the Events channel will be closed,
		// and this for...range loop will exit.
		fmt.Println(event) // e.g., "Event{Path: "/path/to/file.txt", Op: WRITE}"
	}
}()

// Add a path to watch. This can be a directory or a single file.
// This call is thread-safe, so you can call it from other goroutines as well.
if err := w.Watch("/path/to/your/directory"); err != nil {
	log.Fatalln(err)
}

// Your main application logic continues here...
// The watcher will run in the background.
// To stop the watcher and its background goroutine, simply call w.Close().

Package watcher provides a simple, thread-safe, polling-based filesystem watcher.

Index

• type Event
  • func (e Event) String() string
• type Op
  • func (o Op) String() string
• type Watcher
  • func New(pollInterval time.Duration) *Watcher
  • func (w *Watcher) Close()
  • func (w *Watcher) Remove(path string) error
  • func (w *Watcher) Watch(path string) error

Types

type Event

type Event struct {
	Path string // The absolute path to the file or directory that changed.
	Op   Op     // The operation that occurred.
}

Event represents a single filesystem change.

func (Event) String

func (e Event) String() string

String returns a string representation of the event.

type Op

type Op uint32

Op represents the type of filesystem operation detected by the watcher.

const (
	Create Op = 1 << iota // A new file or directory was created.
	Write                 // A file was written to or a directory's metadata changed.
	Remove                // A file or directory was removed.
)

Filesystem operation constants.

func (Op) String

func (o Op) String() string

String returns a string representation of the operation type.

type Watcher

type Watcher struct {
	// Events is the channel where filesystem change notifications are sent.
	Events chan Event
	// contains filtered or unexported fields
}

Watcher scans registered paths for file changes and sends events.

func New

func New(pollInterval time.Duration) *Watcher

New creates a new Watcher instance and starts its background scanning goroutine. pollInterval specifies how often to scan for changes. To prevent excessive CPU usage, a minimum interval of 100ms is enforced.

func (*Watcher) Close

func (w *Watcher) Close()

Close gracefully shuts down the watcher.

func (*Watcher) Remove

func (w *Watcher) Remove(path string) error

Remove stops watching a path. It returns nil on success. An error is returned if the path cannot be resolved or if the path was not already being watched. The call is thread-safe.

func (*Watcher) Watch

func (w *Watcher) Watch(path string) error

Watch adds a new path to the watchlist. The path can be a single file or a directory, which will be watched recursively. The call is thread-safe.