fsnotify

README

fsnotify

Cross-platform file system notifications for Go.

Install

go get github.com/gofsnotify/fsnotify

Usage

package main

import (
	"log"

	"github.com/gofsnotify/fsnotify"
)

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

	if err := w.Add("/path/to/dir", fsnotify.Create|fsnotify.Write|fsnotify.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	kqueue	Supported

License

MIT

Documentation

Overview

Package fsnotify 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("fsnotify: path already added")
	// ErrNotAdded is returned by Remove when path is not registered.
	ErrNotAdded = errors.New("fsnotify: path not added")
	// ErrClosed is returned by methods called on a closed Watcher.
	ErrClosed = errors.New("fsnotify: watcher closed")
	// ErrUnsupported is returned by NewWatcher on platforms without a backend.
	ErrUnsupported = errors.New("fsnotify: 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 every 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.

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.