README
¶
watchdog 🐕
High-level file system event watching for Go
watchdog wraps fsnotify with everything Go's standard tooling is missing — debouncing, glob pattern matching, recursive watching, and typed event dispatch.
Install
go get github.com/Mritunjay2005/watchDog
Quickstart
package main
import (
"fmt"
watchdog "github.com/Mritunjay2005/watchDog"
)
func main() {
w := watchdog.New()
w.On(watchdog.Modified|watchdog.Created, "**/*.go", func(e watchdog.Event) {
fmt.Printf("changed: %s\n", e.Path)
})
w.Start(".")
select {}
}
Why watchdog over raw fsnotify?
| Feature | fsnotify | watchdog |
|---|---|---|
| Debouncing | ❌ | ✅ |
| Glob patterns | ❌ | ✅ |
| Recursive watching | ❌ | ✅ |
| Handler registration | ❌ | ✅ |
| Panic recovery | ❌ | ✅ |
Features
- Debouncing — collapses multiple rapid events into one handler call
- Glob patterns —
**/*.go,config/*.yaml,*.mdwith full**support - Recursive watching — automatically watches all subdirectories
- Typed dispatch — register handlers per operation:
Created,Modified,Deleted,Renamed - Panic recovery — a panicking handler never crashes the watcher
API Reference
Creating a watcher
w := watchdog.New(
watchdog.WithDebounce(200 * time.Millisecond), // default: 100ms
watchdog.WithRecursive(true), // default: true
watchdog.WithIgnore("vendor", ".git"), // default: none
)
Registering handlers
// single op
w.On(watchdog.Modified, "**/*.go", func(e watchdog.Event) { ... })
// combined ops
w.On(watchdog.Created|watchdog.Modified, "**/*.yaml", func(e watchdog.Event) { ... })
Event fields
type Event struct {
Path string // absolute path to the changed file
Op Op // Created, Modified, Deleted, or Renamed
Time time.Time // when the event was detected
Size int64 // file size in bytes
}
Op constants
watchdog.Created // file was created
watchdog.Modified // file was modified
watchdog.Deleted // file was deleted
watchdog.Renamed // file was renamed
Errors
watchdog.ErrWatcherClosed // Start() or On() called after Stop()
watchdog.ErrInvalidPattern // invalid glob pattern passed to On()
watchdog.ErrPathNotFound // path passed to Start() does not exist
Starting and stopping
if err := w.Start("."); err != nil {
log.Fatal(err)
}
defer w.Stop()
Examples
| Example | Description |
|---|---|
| basic | Minimal watcher — print every .go file change |
| hot-reload | Restart a subprocess when .go files change |
| config-watch | Auto-reload config.yaml on change |
Contributing
Pull requests are welcome. For major changes please open an issue first.
License
Documentation
¶
Overview ¶
Package watchdog provides a high-level file system event library. It wraps fsnotify with debouncing, glob pattern matching, recursive watching, and typed event dispatch.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrWatcherClosed is returned when On() or Start() is called // after Stop() has been called. ErrWatcherClosed = errors.New("watchdog: watcher is closed") // ErrInvalidPattern is returned by On() when the glob pattern // is not valid syntax. ErrInvalidPattern = errors.New("watchdog: invalid glob pattern") // ErrPathNotFound is returned by Start() when a watched path // does not exist on disk. ErrPathNotFound = errors.New("watchdog: path does not exist") )
Functions ¶
This section is empty.
Types ¶
type Event ¶
type Event struct {
// Path is the absolute path of the changed file.
Path string
// Op is the type of change that occurred.
Op Op
// Time is when the event was detected.
Time time.Time
// Size is the file size in bytes at the time of the event.
Size int64
}
Event represents a single file system change delivered to a handler.
type HandlerFunc ¶
type HandlerFunc func(Event)
HandlerFunc is the function signature for all event handlers. It receives an Event describing the file system change.
type Op ¶
type Op uint32
Op represents a file system operation as a bitmask. Multiple operations can be combined: Created | Modified.
Op constants represent the types of file system events.
type Option ¶
type Option func(*config)
Option is a functional option for configuring a Watcher.
func WithDebounce ¶
WithDebounce sets the debounce window — the quiet period after the last event before the handler is called. Default is 100ms.
func WithIgnore ¶
WithIgnore specifies glob patterns for directories to skip during recursive walking. Example: WithIgnore("vendor", ".git")
func WithRecursive ¶
WithRecursive controls whether subdirectories are watched automatically. Default is true.
type Watcher ¶
type Watcher struct {
// contains filtered or unexported fields
}
Watcher watches directories and files for changes, routing events to registered handlers. Create one with New(), register handlers with On(), then call Start() to begin watching.
func New ¶
New creates a Watcher with the given options. If no options are provided, sensible defaults are used: 100ms debounce window and recursive watching enabled.
func (*Watcher) On ¶
func (w *Watcher) On(op Op, pattern string, fn HandlerFunc) error
On registers fn to be called when a file matching pattern is changed with the given Op. Pattern supports glob syntax including ** for recursive matching. Returns ErrInvalidPattern if pattern is invalid. Returns ErrWatcherClosed if the watcher has been stopped.
Source Files