fswatch

README

fswatch

go library for simple UNIX file system watching

fswatch provides simple UNIX file system watching in Go. It is based around the Watcher struct, which should be initialised with either NewWatcher or NewAutoWatcher. Both functions accept a variable number of string arguments specfying the paths to be loaded, which may be globbed, and return a pointer to a Watcher. This value can be started and stopped with the Start() and Stop() methods. The Watcher will automatically stop if all the files it is watching have been deleted.

The Start() method returns a read-only channel that receives Notification values. The Stop() method closes the channel, and no files will be watched from that point.

The list of files being watched may be retrieved with the Watch() method and the current state of the files being watched may be retrieved with the State() method. See the go docs for more information.

In synchronous mode (i.e. Watchers obtained from NewWatcher()), deleted files will not be removed from the watch list, allowing the user to watch for files that might be created at a future time, or to allow notification of files that are deleted and then recreated. The auto-watching mode (i.e. from NewAutoWatcher()) will remove deleted files from the watch list, as it automatically adds new files to the watch list.

Usage

There are two types of Watchers:

• static watchers watch a limited set of files; they do not purge deleted files from the watch list.
• auto watchers watch a set of files and directories; directories are watched for new files. New files are automatically added, and deleted files are removed from the watch list.

Take a look at the provided clinotify/clinotify.go for an example; the package is also well-documented. See the godocs for more specifics.

License

fswatch is licensed under the ISC license.

Documentation

Overview

Package fswatch provides simple UNIX file system watching in Go. It is based around the Watcher struct, which should be initialised with either NewWatcher or NewAutoWatcher. Both functions accept a variable number of string arguments specfying the paths to be loaded, which may be globbed, and return a pointer to a Watcher. This value can be started and stopped with the Start() and Stop() methods. The Watcher will automatically stop if all the files it is watching have been deleted.

The Start() method returns a read-only channel that receives Notification values. The Stop() method closes the channel, and no files will be watched from that point.

The list of files being watched may be retrieved with the Watch() method and the current state of the files being watched may be retrieved with the State() method. See the go docs for more information.

In synchronous mode (i.e. Watchers obtained from NewWatcher()), deleted files will not be removed from the watch list, allowing the user to watch for files that might be created at a future time, or to allow notification of files that are deleted and then recreated. The auto-watching mode (i.e. from NewAutoWatcher()) will remove deleted files from the watch list, as it automatically adds new files to the watch list.

If "." is not specified explicitly in the list of files to watch, new directories created in the current directory will not be seen (as per the behaviour of filepath.Match); any directories being watched will, however. If you wish to watch for changes in the current directory, be sure to specify ".".

Index

• Constants
• Variables
• type Notification
• type Watcher
  • func NewAutoWatcher(paths ...string) *Watcher
  • func NewWatcher(paths ...string) *Watcher
  • func (w *Watcher) Active() bool
  • func (w *Watcher) Add(inpaths ...string)
  • func (w *Watcher) Start() <-chan *Notification
  • func (w *Watcher) State() (state []Notification)
  • func (w *Watcher) Stop()
  • func (w *Watcher) Watching() (paths []string)

Constants

const (
	NONE     = iota // No event, initial state.
	CREATED         // File was created.
	DELETED         // File was deleted.
	MODIFIED        // File was modified.
	PERM            // Changed permissions
	NOEXIST         // File does not exist.
	NOPERM          // No permissions for the file (see const block comment).
	INVALID         // Any type of error not represented above.
)

These values represent the events fswatch knows about. fswatch uses a stat(2) call to look up file information; a file will only have a NOPERM event if the parent directory has no search permission (i.e. parent directory doesn't have executable permissions for the current user).

Variables

var NotificationBufLen = 16

NotificationBufLen is the number of notifications that should be buffered in the channel.

var WatchDelay time.Duration

WatchDelay is the duration between path scans. It defaults to 100ms.

Types

type Notification

type Notification struct {
	Path  string
	Event int
}

Notification represents a file state change. The Path field indicates the file that was changed, while last event corresponds to one of the event type constants.

type Watcher

type Watcher struct {

	// ignoreFn is used to ignore paths
	IgnorePathFn func(path string) bool
	// contains filtered or unexported fields
}

Watcher represents a file system watcher. It should be initialised with NewWatcher or NewAutoWatcher, and started with Watcher.Start().

func NewAutoWatcher

func NewAutoWatcher(paths ...string) *Watcher

NewAutoWatcher initialises a new Watcher with an initial set of paths. It behaves the same as NewWatcher, except it will automatically add files created in directories it is watching, including adding any subdirectories.

func NewWatcher

func NewWatcher(paths ...string) *Watcher

NewWatcher initialises a new Watcher with an initial set of paths. It does not start listening, and this Watcher will not automatically add files created under any directories it is watching.

func (*Watcher) Active

func (w *Watcher) Active() bool

Active returns true if the Watcher is actively looking for changes.

func (*Watcher) Add

func (w *Watcher) Add(inpaths ...string)

Add method takes a variable number of string arguments and adds those files to the watch list, returning the number of files added.

func (*Watcher) Start

func (w *Watcher) Start() <-chan *Notification

Start begins watching the files, sending notifications when files change. It returns a channel that notifications are sent on.

func (*Watcher) State

func (w *Watcher) State() (state []Notification)

State returns a slice of Notifications representing the files being watched and their last event.

func (*Watcher) Stop

func (w *Watcher) Stop()

Stop listening for changes to the files.

func (*Watcher) Watching

func (w *Watcher) Watching() (paths []string)

Watching returns a list of the files being watched.