gaze

README

Gaze

Simple Filesystem Watcher Written in Pure Go

[!IMPORTANT] Gaze is still pre-release software. Expect Minor versions to have breaking changes until v1 is hit.

Documentation

Overview

Gaze is a pure-Go filesystem watcher for Linux, macOS, and Windows.

For the common case, start with a directory watch:

w, err := gaze.WatchDirectory("my-directory")

If you need filters, callbacks, or logger control, use a types.Config value with a ...WithConfig constructor:

cfg := types.Config{
	ExcludeGlobs: []string{"*.tmp"},
	OnEvent: func(evt types.Event) {
		fmt.Println(evt)
	},
}

w, err := gaze.WatchDirectoryWithConfig("my-directory", cfg)

Gaze owns the watcher goroutines internally. You can handle events and errors with callbacks, or let the package log them through slog.

Linux and Windows generally handle large recursive trees best. macOS is still pure Go and works well for normal project sizes, but it uses more kernel watches and tends to be less efficient on very large trees.

Index

• Variables
• type Watcher
  • func New() (*Watcher, error)
  • func NewWithConfig(cfg types.Config) (*Watcher, error)
  • func WatchDirectory(path string) (*Watcher, error)
  • func WatchDirectoryWithConfig(path string, cfg types.Config) (*Watcher, error)
  • func WatchFile(path string) (*Watcher, error)
  • func WatchFileWithConfig(path string, cfg types.Config) (*Watcher, error)
  • func (w *Watcher) Add(path string) error
  • func (w *Watcher) Close() error
  • func (w *Watcher) Remove(path string) error

Examples

• WatchDirectory

Variables

var ErrWatcherClosed = errors.New("gaze: watcher closed")

ErrWatcherClosed is returned when an operation is attempted after Close.

Types

type Watcher

type Watcher struct {
	// contains filtered or unexported fields
}

func New

func New() (*Watcher, error)

func NewWithConfig

func NewWithConfig(cfg types.Config) (*Watcher, error)

func WatchDirectory

func WatchDirectory(path string) (*Watcher, error)

Example

package main

import (
	"fmt"
	"os"

	"go.ofkm.dev/gaze"
	"go.ofkm.dev/gaze/types"
)

func main() {
	root, err := os.MkdirTemp("", "gaze-example-*")
	if err != nil {
		panic(err)
	}
	defer func() {
		_ = os.RemoveAll(root)
	}()

	events := make(chan types.Event, 1)
	cfg := types.Config{
		ExcludeGlobs: []string{"*.tmp"},
		OnEvent: func(evt types.Event) {
			select {
			case events <- evt:
			default:
			}
		},
	}

	w, err := gaze.WatchDirectoryWithConfig(root, cfg)
	if err != nil {
		panic(err)
	}
	defer func() {
		if err := w.Close(); err != nil {
			panic(err)
		}
	}()

	select {
	case evt := <-events:
		fmt.Println(evt)
	default:
	}
}

func WatchDirectoryWithConfig

func WatchDirectoryWithConfig(path string, cfg types.Config) (*Watcher, error)

func WatchFile

func WatchFile(path string) (*Watcher, error)

func WatchFileWithConfig

func WatchFileWithConfig(path string, cfg types.Config) (*Watcher, error)

func (*Watcher) Add

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

func (*Watcher) Close

func (w *Watcher) Close() error

func (*Watcher) Remove

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