README
¶
go-fswatch
Polling-based file system watcher for Go. Zero dependencies.
Installation
go get github.com/philiprehberger/go-fswatch
Usage
package main
import (
"context"
"fmt"
"os/signal"
"syscall"
"time"
"github.com/philiprehberger/go-fswatch"
)
func main() {
w, err := fswatch.New(
fswatch.Paths("./src", "./config"),
fswatch.Glob("*.go", "*.yaml"),
fswatch.Ignore(".git", "*.tmp", "node_modules"),
fswatch.Debounce(300*time.Millisecond),
fswatch.PollInterval(1*time.Second),
fswatch.Recursive(true),
)
if err != nil {
panic(err)
}
w.OnChange(func(events []fswatch.Event) {
for _, e := range events {
fmt.Printf("%s %s\n", e.Op, e.Path)
}
})
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()
if err := w.Start(ctx); err != nil && err != context.Canceled {
panic(err)
}
}
Configuration
| Option | Description | Default |
|---|---|---|
Paths(...) |
Directories to watch | required |
Glob(...) |
Include patterns | all files |
Ignore(...) |
Exclude patterns | none |
Debounce(d) |
Debounce interval | 500ms |
PollInterval(d) |
Poll frequency | 1s |
Recursive(bool) |
Watch subdirs | true |
Events
| Op | Description |
|---|---|
Create |
New file detected |
Modify |
File content changed |
Delete |
File removed |
API
| Function / Type | Description |
|---|---|
New(opts ...Option) (*Watcher, error) |
Create a new watcher |
(*Watcher).OnChange(fn func([]Event)) |
Register change callback |
(*Watcher).Start(ctx context.Context) error |
Start watching (blocks) |
(*Watcher).Close() error |
Stop watching |
Paths(paths ...string) Option |
Set directories to watch |
Glob(patterns ...string) Option |
Set include patterns |
Ignore(patterns ...string) Option |
Set exclude patterns |
Debounce(d time.Duration) Option |
Set debounce interval |
PollInterval(d time.Duration) Option |
Set poll frequency |
Recursive(enabled bool) Option |
Enable/disable recursive watching |
Event |
File system change event |
Op |
Operation type (Create, Modify, Delete) |
Development
go test ./...
go vet ./...
License
MIT
Documentation
¶
Overview ¶
Package fswatch provides a polling-based file system watcher for Go.
It uses polling (not OS-level events) to detect file changes, which means zero external dependencies. File modification times are tracked via os.Stat, directories are walked with filepath.WalkDir, and glob matching uses filepath.Match from the standard library.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Event ¶
type Event struct {
// Path is the absolute path of the affected file.
Path string
// Op is the operation that triggered the event.
Op Op
// ModTime is the last modification time of the file at the time the event was detected.
ModTime time.Time
}
Event represents a file system change event.
type Option ¶
type Option func(*config)
Option configures a Watcher.
func Debounce ¶
Debounce sets the debounce interval. Events are batched and delivered after no new events have been detected for this duration. Default is 500ms.
func Glob ¶
Glob sets file patterns to include (e.g., "*.yaml", "*.go"). Patterns are matched using filepath.Match against the file's base name. If no glob patterns are set, all files are included.
func Ignore ¶
Ignore sets patterns to exclude (e.g., ".git", "*.tmp", "node_modules"). Patterns are matched using filepath.Match against the file's base name.
func PollInterval ¶
PollInterval sets how often the watcher checks for file system changes. Default is 1s.
type Watcher ¶
type Watcher struct {
// contains filtered or unexported fields
}
Watcher watches directories for file system changes using polling.
func New ¶
New creates a new Watcher with the given options. At least one path must be specified via the Paths option.
Source Files