fswatcher

README

fswatcher

Cross-platform file system notifications for Go.

Previously published as github.com/gofsnotify/fsnotify (package fsnotify). The old path is deprecated and redirects here; update imports and rename fsnotify.X to fswatcher.X. See #27.

Install

go get github.com/fswatcher/fswatcher

Usage

package main

import (
	"log"

	"github.com/fswatcher/fswatcher"
)

func main() {
	w, err := fswatcher.NewWatcher()
	if err != nil {
		log.Fatal(err)
	}
	defer w.Close()

	if err := w.Add("/path/to/dir", fswatcher.Create|fswatcher.Write|fswatcher.Remove); err != nil {
		log.Fatal(err)
	}

	for {
		select {
		case ev := <-w.Events:
			log.Println(ev)
		case err := <-w.Errors:
			log.Println("error:", err)
		}
	}
}

API

• NewWatcher() (*Watcher, error) — creates a watcher.
• (*Watcher).Add(path string, op Op) error — registers path with the given event mask. Returns ErrAlreadyAdded if path is already registered.
• (*Watcher).AddRecursive(path string, op Op) error — registers path and every directory under it. New subdirectories created inside are watched automatically; removed subdirectories are dropped. Remove may only be called on the original recursive root.
• (*Watcher).Remove(path string) error — unregisters path. For an AddRecursive registration this drops the entire subtree.
• (*Watcher).Close() error — stops the watcher and closes the channels.
• (*Watcher).Events <-chan Event — receives change notifications.
• (*Watcher).Errors <-chan error — receives non-fatal errors.

Paths are canonicalized (absolute, cleaned, with symlinks resolved when the target exists; on Windows 8.3 short forms are expanded and case is folded), so two spellings of the same path dedupe and Event.Name is always returned in canonical form.

Events

Op	Description
Create	A file or directory was created.
Write	A file's contents were modified.
Remove	A file or directory was removed.
Rename	A file or directory was renamed or moved.
Chmod	Permissions or attributes changed.

Op is a bitmask; combine values with | when calling Add. The All constant is shorthand for the union of every Op bit.

Guarantees

• Thread-safe: methods may be called from multiple goroutines.
• Event ordering is preserved as far as the underlying OS allows.
• Behavior is normalized across supported platforms.

Platform Support

OS	Backend	Status
Linux	inotify	Supported
Windows	ReadDirectoryChangesW	Supported
macOS	FSEvents (purego)	Supported
FreeBSD	kqueue	Supported

License

MIT

Documentation

Overview

Package fswatcher provides cross-platform file system change notifications.

Index

• Constants
• Variables
• type Event
  • func (e Event) String() string
• type Op
  • func (op Op) Has(target Op) bool
  • func (op Op) String() string
• type Watcher
  • func NewWatcher() (*Watcher, error)
  • func (w *Watcher) Add(path string, op Op) error
  • func (w *Watcher) AddRecursive(path string, op Op) error
  • func (w *Watcher) Close() error
  • func (w *Watcher) Remove(path string) error

Constants

const All = Create | Write | Remove | Rename | Chmod

All is the union of every supported Op bit.

Variables

var (
	// ErrAlreadyAdded is returned by Add when path is already registered.
	ErrAlreadyAdded = errors.New("fswatcher: path already added")
	// ErrNotAdded is returned by Remove when path is not registered.
	ErrNotAdded = errors.New("fswatcher: path not added")
	// ErrClosed is returned by methods called on a closed Watcher.
	ErrClosed = errors.New("fswatcher: watcher closed")
	// ErrUnsupported is returned by NewWatcher on platforms without a backend.
	ErrUnsupported = errors.New("fswatcher: platform not supported")
)

Sentinel errors returned by Watcher methods.

Types

type Event

type Event struct {
	// Name is the absolute or watcher-relative path of the affected entry.
	Name string
	// Op is the set of changes that occurred. A single notification may
	// carry more than one bit when the underlying OS coalesces events.
	Op Op
}

Event represents a single file system change.

func (Event) String

func (e Event) String() string

String returns a human-readable representation such as "CREATE: /tmp/x".

type Op

type Op uint32

Op describes a set of file system event types as a bitmask.

const (
	// Create indicates a file or directory was created.
	Create Op = 1 << iota
	// Write indicates a file's contents were modified.
	Write
	// Remove indicates a file or directory was removed.
	Remove
	// Rename indicates a file or directory was renamed or moved.
	Rename
	// Chmod indicates permissions or attributes changed.
	Chmod
)

func (Op) Has

func (op Op) Has(target Op) bool

Has reports whether op contains any bit set in target.

func (Op) String

func (op Op) String() string

String returns a human-readable representation such as "CREATE|WRITE".

type Watcher

type Watcher struct {
	// Events delivers change notifications. Closed when Close returns.
	Events <-chan Event
	// Errors delivers non-fatal errors from the read loop. Closed when Close returns.
	Errors <-chan error
	// contains filtered or unexported fields
}

Watcher monitors registered paths for file system changes via inotify.

func NewWatcher

func NewWatcher() (*Watcher, error)

NewWatcher returns a Watcher backed by Linux inotify.

func (*Watcher) Add

func (w *Watcher) Add(path string, op Op) error

Add registers path with the given event mask. Returns ErrAlreadyAdded if path is already registered, or ErrClosed if the watcher is closed.

func (*Watcher) AddRecursive

func (w *Watcher) AddRecursive(path string, op Op) error

AddRecursive registers path and every directory below it. New subdirectories created inside path are watched automatically; subtrees that disappear are dropped via the kernel's IN_IGNORED notification. Returns ErrAlreadyAdded if path is already registered.

When a directory is created underneath an AddRecursive root, the watcher attaches an inotify watch to it and walks it for any pre-existing descendants (for example after mkdir -p or after a populated subtree is moved in) so that their Create events are not lost. If another process concurrently creates entries inside the new directory in the brief window between watch attachment and the walk, the same Create may be reported twice; consumers should handle duplicate Create events idempotently.

func (*Watcher) Close

func (w *Watcher) Close() error

Close stops the watcher. Subsequent calls are no-ops. Close blocks until the read loop has fully exited so the kernel cannot reuse the inotify fd while a stale goroutine is still reading from it.

func (*Watcher) Remove

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

Remove unregisters path. For an AddRecursive registration, every descendant watch added on its behalf is dropped too. Returns ErrNotAdded if path is not registered.