fs

README

fs

Go package exposing minimal APIs to watch unix file systems.

Motivation

Go has long had a package to receive notification from file system changes: fsnotify. The package took on the challenging task to provide cross-platform solution, and inherits complexity and limitations. One of these limitations is the inability to watch for changes on symbolic links, which adds barriers to using fsnotify in contexts like kubernetes config maps (which are exposed to pods via symbolic links).

The fs package aims to address these limitations by giving up some of the cross-platform goals and providing a simpler API mirrored after the standard signal package.

Usage Example

A key difference of the fs package is it installs one-shot notifications instead of persistent watchers. This design decision was made after observing that programs tend to make adjustments to the watchers after each event, especially when files are created, removed, or renamed, the persistence ends up forcing complexity on the program.

import (
    "github.com/segmentio/fs"
)

...

for {
    ch := make(chan string)
    if err := fs.Notify(ch, "/dir", "/dir/file"); err != nil {
        return err
    }

    select {
    case path := <-ch:
        switch path {
        case "/dir":
            ...
        case "/dir/file":
            ...
        }

    case <-ctx.Done():
        fs.Stop(ch)
        return ctx.Err()
    }
}

Documentation

Index

• func Notify(events chan<- string, paths ...string) error
• func Stop(events chan<- string)

Functions

func Notify

func Notify(events chan<- string, paths ...string) error

Notify installs the events channel as a receiver for file system change notifications that occur on the paths passed as arguments.

Calling Notify with an events channel that was already installed replaces the previous installation. Calling Notify with no paths uninstalls the events channel in a way similar to calling Stop.

Notifications are only triggered once, if the program needs to receive further notification for the paths, it needs to re-install the events channel by calling Notify again.

When a change occurs on one of the paths, the events channel receives the path that was modified. Paths may point to directories or files. If a path is removed the OS removes the watchers installed by Notify (after emitting a notification).

func Stop

func Stop(events chan<- string)

Stop uninstalls an events channel previously installed by a call to Notify.

Calling stops is not necessary if the events channel was triggered because it will be automatically uninstalled.