fsnotify

https://pkg.go.dev/github.com/fsnotify/fsnotify@latest
Admin
fsnotify is a Go library providing cross-platform file system notifications on Windows, Linux,...
Tokens:7,543
Snippets:60
Trust Score:9.6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Run fsnotify examples with go run

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Command to run the additional examples located in the cmd/fsnotify directory. The command is executed from the project root.

```bash
% go run ./cmd/fsnotify

```

--------------------------------

### FSNOTIFY_DEBUG example output

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Example output when FSNOTIFY_DEBUG is set to "1". Each line shows a timestamp, event mask, event type, and the affected path.

```text
FSNOTIFY_DEBUG: 11:34:23.633087586   256:IN_CREATE            → "/tmp/file-1"
FSNOTIFY_DEBUG: 11:34:23.633202319     4:IN_ATTRIB            → "/tmp/file-1"
FSNOTIFY_DEBUG: 11:34:28.989728764   512:IN_DELETE            → "/tmp/file-1"
```

--------------------------------

### Basic fsnotify watcher example

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Basic usage of fsnotify: create a watcher, listen for events and errors in a goroutine, add a path, and block the main goroutine. Requires Go 1.23 or newer. The example watches /tmp and logs events, printing "modified file:" when the event has the Write flag.

```go
package main

import (
    "log"

    "github.com/fsnotify/fsnotify"
)

func main() {
    // Create new watcher.
    watcher, err := fsnotify.NewWatcher()
    if err != nil {
        log.Fatal(err)
    }
    defer watcher.Close()

    // Start listening for events.
    go func() {
        for {
            select {
            case event, ok := <-watcher.Events:
                if !ok {
                    return
                }
                log.Println("event:", event)
                if event.Has(fsnotify.Write) {
                    log.Println("modified file:", event.Name)
                }
            case err, ok := <-watcher.Errors:
                if !ok {
                    return
                }
                log.Println("error:", err)
            }
        }
    }()

    // Add a path.
    err = watcher.Add("/tmp")
    if err != nil {
        log.Fatal(err)
    }

    // Block main goroutine forever.
    <-make(chan struct{})
}

```

--------------------------------

### func (*Watcher) Add

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Starts monitoring a path for changes.

```APIDOC
## func (*Watcher) Add

### Description
Starts monitoring the path for changes. A path can only be watched once; watching it more than once is a no-op and will not return an error. Paths that do not yet exist on the filesystem cannot be watched. A watch will be automatically removed if the watched path is deleted or renamed (except on Windows). Notifications on network filesystems (NFS, SMB, FUSE, etc.) or special filesystems (/proc, /sys, etc.) generally don't work. Returns ErrClosed if Watcher.Close was called.

### Signature
`func (w *Watcher) Add(path string) error`

### Parameters
- **path** (string) - Required - The path to monitor for changes.

### Returns
- **error** - Returns an error if the watch could not be added, or ErrClosed if the watcher is closed.
```

--------------------------------

### Event.String method signature

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

String returns a string representation of the event with their path.

```go
func (e Event) String() string
```

--------------------------------

### Op constants (Create, Write, Remove, Rename)

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Operation constants for file events. Create, Write, Remove, and Rename. Write does not mean the write has finished; on Windows and kqueue, Write on a directory can indicate contents changed.

```go
const (
	// A new pathname was created.
	Create Op = 1 << iota

	// The pathname was written to; this does *not* mean the write has finished,
	// and a write can be followed by more writes. On Windows and kqueue, a
	// Write on a directory can also indicate that its contents changed; see
	// the per-platform notes on [Watcher].
	Write

	// The path was removed; any watches on it will be removed. Some "remove"
	// operations may trigger a Rename if the file is actually moved (for
	// example "remove to trash" is often a rename).
	Remove

	// The path was renamed to something else; any watches on it will be
	// removed.
	Rename
```

--------------------------------

### Op.String method

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Returns the string representation of the operation. Added in v1.4.0.

```go
func (o Op) String() string

```

--------------------------------

### WithBufferSize function signature

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Sets the ReadDirectoryChangesW buffer size. Only affects Windows; no-op on other backends. Default is 64K (65536 bytes); increase if hitting ErrEventOverflow.

```go
func WithBufferSize(bytes int) addOpt
```

--------------------------------

### func (*Watcher) AddWith

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Adds a watch with additional options.

```APIDOC
## func (*Watcher) AddWith

### Description
Like Watcher.Add, but allows adding options. When using Add() the defaults described below are used. Possible options are: WithBufferSize sets the buffer size for the Windows backend; no-op on other platforms. The default is 64K (65536 bytes).

### Signature
`func (w *Watcher) AddWith(path string, opts ...addOpt) error`

### Parameters
- **path** (string) - Required - The path to monitor for changes.
- **opts** (addOpt) - Optional - Options to configure the watch.

### Returns
- **error** - Returns an error if the watch could not be added.
```

--------------------------------

### Increase inotify limits with sysctl

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Use sysctl to increase the inotify limits for the current session. The variables fs.inotify.max_user_watches and fs.inotify.max_user_instances control the maximum number of watches per user and inotify instances per user, respectively. Reaching these limits results in "no space left on device" or "too many open files" errors.

```bash
sysctl fs.inotify.max_user_watches=200000
sysctl fs.inotify.max_user_instances=256

```

--------------------------------

### Event.Has method signature

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Has reports if this event has the given operation.

```go
func (e Event) Has(op Op) bool
```

--------------------------------

### Persistent inotify limits configuration

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Add these lines to /etc/sysctl.conf or /usr/lib/sysctl.d/50-default.conf to make the inotify limit changes persist across reboots. The exact file and details vary by Linux distribution; check your distro's documentation.

```plaintext
fs.inotify.max_user_watches=200000
fs.inotify.max_user_instances=256

```

--------------------------------

### Op.Has method

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Reports if the operation has the given operation. Added in v1.6.0.

```go
func (o Op) Has(h Op) bool

```

--------------------------------

### Op type definition

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Op describes a set of file operations.

```go
type Op uint32
```

--------------------------------

### func NewWatcher

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Creates a new Watcher.

```APIDOC
## func NewWatcher

### Description
Creates a new Watcher.

### Signature
`func NewWatcher() (*Watcher, error)`

### Returns
- **(*Watcher, error)** - A new Watcher instance or an error.
```

--------------------------------

### Event struct definition

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Event represents a file system notification. Name is the path relative to the input, Op is a bitmask; use Event.Has() instead of comparing with ==.

```go
type Event struct {
	// Path to the file or directory.
	//
	// Paths are relative to the input; for example with Add("dir") the Name
	// will be set to "dir/file" if you create that file, but if you use
	// Add("/path/to/dir") it will be "/path/to/dir/file".
	Name string

	// File operation that triggered the event.
	//
	// This is a bitmask and some systems may send multiple operations at once.
	// Use the Event.Has() method instead of comparing with ==.
	Op Op
	// contains filtered or unexported fields
}
```

--------------------------------

### Watcher struct definition

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Defines the Watcher type with Events and Errors channels. The Events channel sends filesystem change events, and Errors sends any errors. A watcher should not be copied.

```go
type Watcher struct {

	// Events sends the filesystem change events.
	//
	// fsnotify can send the following events; a "path" here can refer to a
	// file, directory, symbolic link, or special file like a FIFO.
	//
	//   fsnotify.Create    A new path was created; this may be followed by one
	//                      or more Write events if data also gets written to a
	//                      file.
	//
	//   fsnotify.Remove    A path was removed.
	//
	//   fsnotify.Rename    A path was renamed. A rename is always sent with the
	//                      old path as Event.Name, and a Create event will be
	//                      sent with the new name. Renames are only sent for
	//                      paths that are currently watched; e.g. moving an
	//                      unmonitored file into a monitored directory will
	//                      show up as just a Create. Similarly, renaming a file
	//                      to outside a monitored directory will show up as
	//                      only a Rename.
	//
	//   fsnotify.Write     A file or named pipe was written to. A Truncate will
	//                      also trigger a Write. A single "write action"
	//                      initiated by the user may show up as one or multiple
	//                      writes, depending on when the system syncs things to
	//                      disk. For example when compiling a large Go program
	//                      you may get hundreds of Write events, and you may
	//                      want to wait until you've stopped receiving them
	//                      (see the dedup example in cmd/fsnotify).
	//
	//                      Some systems also send Write events for directories
	//                      when the directory contents change. This is the
	//                      case for kqueue, and on Windows for the directory
	//                      that contains a created, renamed, or removed child
	//                      entry. It does not happen on inotify. See the
	//                      per-platform notes on [Watcher].
	//
	//   fsnotify.Chmod     Attributes were changed. On Linux this is also sent
	//                      when a file is removed (or more accurately, when a
	//                      link to an inode is removed). On kqueue it's sent
	//                      when a file is truncated. On Windows it's never
	//                      sent.
	Events chan Event

	// Errors sends any errors.
	Errors chan error
	// contains filtered or unexported fields
}

```

--------------------------------

### func (*Watcher) Remove

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Removes a watch on a path.

```APIDOC
## func (*Watcher) Remove

### Description
Removes a watch on a path. (Note: The full description is not provided in the source, but the function signature is documented.)

### Signature
`func (w *Watcher) Remove(path string) error`

### Parameters
- **path** (string) - Required - The path to stop watching.

### Returns
- **error** - Returns an error if the watch could not be removed.
```

--------------------------------

### func (w *Watcher) WatchList() []string

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Returns all paths explicitly added with Watcher.Add that have not been removed. The order is undefined and may differ per call. Returns nil if Watcher.Close was called.

```APIDOC
## [GET] WatchList() []string

### Description
Returns all paths explicitly added with Watcher.Add that have not been removed. The order is undefined and may differ per call. Returns nil if Watcher.Close was called.

### Method
GET

### Endpoint
WatchList() []string

### Parameters
None

### Response
#### Success Response (200)
- **[]string** ([]string) - List of watched paths, or nil if Watcher.Close was called.

#### Response Example
```
["/tmp/dir", "/tmp/dir/subdir"]
```
```

--------------------------------

### Linux file removal event behavior (CHMOD then REMOVE)

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

On Linux, when a file is removed, a REMOVE event is not emitted until all file descriptors are closed; instead, a CHMOD event is emitted. This snippet demonstrates the sequence: opening a file, removing it (which triggers CHMOD), and closing the file descriptor (which triggers REMOVE). This behavior is due to inotify and cannot be changed.

```go
fp := os.Open("file")
os.Remove("file")        // CHMOD
fp.Close()               // REMOVE

```

--------------------------------

### fsnotify error variables

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Package-level error variables. ErrNonExistentWatch is returned by Remove() on a non-added path, ErrClosed when operating on a closed Watcher, and ErrEventOverflow when the event queue or buffer overflows.

```go
var (
	// ErrNonExistentWatch is used when Remove() is called on a path that's not
	// added.
	ErrNonExistentWatch = errors.New("fsnotify: can't remove non-existent watch")

	// ErrClosed is used when trying to operate on a closed Watcher.
	ErrClosed = errors.New("fsnotify: watcher already closed")

	// ErrEventOverflow is reported from the Errors channel when there are too
	// many events:
	//
	//  - inotify:      inotify returns IN_Q_OVERFLOW – because there are too
	//                  many queued events (the fs.inotify.max_queued_events
	//                  sysctl can be used to increase this).
	//  - windows:      The buffer size is too small; WithBufferSize() can be used to increase it.
	//  - kqueue, fen:  Not used.
	ErrEventOverflow = errors.New("fsnotify: queue or buffer overflow")
)
```

--------------------------------

### Linux file removal event behavior

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Shows that on Linux, a Remove event is not emitted until all file descriptors are closed, and deletes always emit a Chmod event. This is the event that inotify sends.

```go
fp := os.Open("file")
os.Remove("file")        // Triggers Chmod
fp.Close()               // Triggers Remove

```

--------------------------------

### func (*Watcher) Close

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Removes all watches and closes the Events channel.

```APIDOC
## func (*Watcher) Close

### Description
Removes all watches and closes the Events channel.

### Signature
`func (w *Watcher) Close() error`

### Returns
- **error** - Returns an error if closing fails.
```

--------------------------------

### func NewBufferedWatcher

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Creates a new Watcher with a buffered Events channel.

```APIDOC
## func NewBufferedWatcher

### Description
Creates a new Watcher with a buffered Events channel. Useful for situations with a very large number of events where the kernel buffer size cannot be increased.

### Signature
`func NewBufferedWatcher(sz uint) (*Watcher, error)`

### Parameters
- **sz** (uint) - Required - The buffer size for the Events channel.

### Returns
- **(*Watcher, error)** - A new Watcher instance or an error.
```

--------------------------------

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

Source: https://pkg.go.dev/github.com/fsnotify/fsnotify

Removes a path from monitoring. Directories are removed non-recursively. Returns ErrNonExistentWatch if the path was not added, or nil if Watcher.Close was called.

```APIDOC
## [REMOVE] Remove(path string) error

### Description
Removes a path from monitoring. Directories are removed non-recursively. Returns ErrNonExistentWatch if the path was not added, or nil if Watcher.Close was called.

### Method
REMOVE

### Endpoint
Remove(path string) error

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to stop monitoring.

### Response
#### Success Response (200)
- **error** (error) - Returns nil on success, ErrNonExistentWatch if the path was not added, or nil if Watcher.Close was called.

#### Response Example
```
nil
```
```
Tokens:
Raw