gopls/internal/filewatcher/filewatcher.go - tools.git - Git at Google

 // Copyright 2025 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.

 package filewatcher

 import (
 	"errors"
 	"io/fs"
 	"log/slog"
 	"os"
 	"path/filepath"
 	"strings"
 	"sync"
 	"time"

 	"github.com/fsnotify/fsnotify"
 	"golang.org/x/tools/gopls/internal/protocol"
 )

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

 // Watcher collects events from a [fsnotify.Watcher] and converts them into
 // batched LSP [protocol.FileEvent]s.
 type Watcher struct {
 	logger *slog.Logger

 	stop chan struct{} // closed by Close to terminate run loop

 	// errs is an internal channel for surfacing errors from the file watcher,
 	// distinct from the fsnotify watcher's error channel.
 	errs chan error

 	runners sync.WaitGroup // counts the number of active run goroutines (max 1)

 	watcher *fsnotify.Watcher

 	mu sync.Mutex // guards all fields below

 	// watchers counts the number of active watch registration goroutines,
 	// including their error handling.
 	// After [Watcher.Close] called, watchers's counter will no longer increase.
 	watchers sync.WaitGroup

 	// dirCancel maps a directory path to its cancellation channel.
 	// A nil map indicates the watcher is closing and prevents new directory
 	// watch registrations.
 	dirCancel map[string]chan struct{}

 	// events is the current batch of unsent file events, which will be sent
 	// when the timer expires.
 	events []protocol.FileEvent
 }

 // New creates a new file watcher and starts its event-handling loop. The
 // [Watcher.Close] method must be called to clean up resources.
 //
 // The provided handler is called sequentially with either a batch of file
 // events or an error. Events and errors may be interleaved. The watcher blocks
 // until the handler returns, so the handler should be fast and non-blocking.
 func New(delay time.Duration, logger *slog.Logger, handler func([]protocol.FileEvent, error)) (*Watcher, error) {
 	watcher, err := fsnotify.NewWatcher()
 	if err != nil {
 		return nil, err
 	}
 	w := &Watcher{
 		logger:    logger,
 		watcher:   watcher,
 		dirCancel: make(map[string]chan struct{}),
 		errs:      make(chan error),
 		stop:      make(chan struct{}),
 	}

 	w.runners.Add(1)
 	go w.run(delay, handler)

 	return w, nil
 }

 // run is the main event-handling loop for the watcher. It should be run in a
 // separate goroutine.
 func (w *Watcher) run(delay time.Duration, handler func([]protocol.FileEvent, error)) {
 	defer w.runners.Done()

 	// timer is used to debounce events.
 	timer := time.NewTimer(delay)
 	defer timer.Stop()

 	for {
 		select {
 		case <-w.stop:
 			return

 		case <-timer.C:
 			if events := w.drainEvents(); len(events) > 0 {
 				handler(events, nil)
 			}
 			timer.Reset(delay)

 		case err, ok := <-w.watcher.Errors:
 			// When the watcher is closed, its Errors channel is closed, which
 			// unblocks this case. We continue to the next loop iteration,
 			// allowing the <-w.stop case to handle the shutdown.
 			if !ok {
 				continue
 			}
 			if err != nil {
 				handler(nil, err)
 			}

 		case err, ok := <-w.errs:
 			if !ok {
 				continue
 			}
 			if err != nil {
 				handler(nil, err)
 			}

 		case event, ok := <-w.watcher.Events:
 			if !ok {
 				continue
 			}

 			// fsnotify does not guarantee clean filepaths.
 			event.Name = filepath.Clean(event.Name)

 			// fsnotify.Event should not be handled concurrently, to preserve their
 			// original order. For example, if a file is deleted and recreated,
 			// concurrent handling could process the events in reverse order.
 			//
 			// Only reset the timer if a relevant event happened.
 			// https://github.com/fsnotify/fsnotify?tab=readme-ov-file#why-do-i-get-many-chmod-events
 			e, isDir := w.convertEvent(event)
 			if e == (protocol.FileEvent{}) {
 				continue
 			}

 			if isDir {
 				switch e.Type {
 				case protocol.Created:
 					// Newly created directories are watched asynchronously to prevent
 					// a potential deadlock on Windows(see fsnotify/fsnotify#502).
 					// Errors are reported internally.
 					if done, release := w.addWatchHandle(event.Name); done != nil {
 						go func() {
 							w.errs <- w.watchDir(event.Name, done)

 							// Only release after the error is sent.
 							release()
 						}()
 					}
 				case protocol.Deleted:
 					// Upon removal, we only need to remove the entries from
 					// the map. The [fsnotify.Watcher] removes the watch for
 					// us. fsnotify/fsnotify#268
 					w.removeWatchHandle(event.Name)
 				default:
 					// convertEvent enforces that dirs are only Created or Deleted.
 					panic("impossible")
 				}
 			}

 			w.addEvent(e)
 			timer.Reset(delay)
 		}
 	}
 }

 // skipDir reports whether the input dir should be skipped.
 // Directories that are unlikely to contain Go source files relevant for
 // analysis, such as .git directories or testdata, should be skipped to
 // avoid unnecessary file system notifications. This reduces noise and
 // improves efficiency. Conversely, any directory that might contain Go
 // source code should be watched to ensure that gopls can respond to
 // file changes.
 func skipDir(dirName string) bool {
 	// TODO(hxjiang): the file watcher should honor gopls directory
 	// filter or the new go.mod ignore directive, or actively listening
 	// to gopls register capability request with method
 	// "workspace/didChangeWatchedFiles" like a real LSP client.
 	return strings.HasPrefix(dirName, ".") || strings.HasPrefix(dirName, "_") || dirName == "testdata"
 }

 // WatchDir walks through the directory and all its subdirectories, adding
 // them to the watcher.
 func (w *Watcher) WatchDir(path string) error {
 	return filepath.WalkDir(filepath.Clean(path), func(path string, d fs.DirEntry, err error) error {
 		if d.IsDir() {
 			if skipDir(d.Name()) {
 				return filepath.SkipDir
 			}

 			done, release := w.addWatchHandle(path)
 			if done == nil { // file watcher closing
 				return filepath.SkipAll
 			}
 			defer release()

 			return w.watchDir(path, done)
 		}
 		return nil
 	})
 }

 // convertEvent translates an [fsnotify.Event] into a [protocol.FileEvent].
 // It returns the translated event and a boolean indicating if the path was a
 // directory. For directories, the event Type is either Created or Deleted.
 // It returns empty event for events that should be ignored.
 func (w *Watcher) convertEvent(event fsnotify.Event) (_ protocol.FileEvent, isDir bool) {
 	// Determine if the event is for a directory.
 	if info, err := os.Stat(event.Name); err == nil {
 		isDir = info.IsDir()
 	} else if os.IsNotExist(err) {
 		// Upon deletion, the file/dir has been removed. fsnotify does not
 		// provide information regarding the deleted item.
 		// Use watchHandles to determine if the deleted item was a directory.
 		isDir = w.isWatchedDir(event.Name)
 	} else {
 		// If statting failed, something is wrong with the file system.
 		// Log and move on.
 		if w.logger != nil {
 			w.logger.Error("failed to stat path, skipping event as its type (file/dir) is unknown", "path", event.Name, "err", err)
 		}
 		return protocol.FileEvent{}, false
 	}

 	// Filter out events for directories and files that are not of interest.
 	if isDir {
 		if skipDir(filepath.Base(event.Name)) {
 			return protocol.FileEvent{}, true
 		}
 	} else {
 		switch strings.TrimPrefix(filepath.Ext(event.Name), ".") {
 		case "go", "mod", "sum", "work", "s":
 		default:
 			return protocol.FileEvent{}, false
 		}
 	}

 	var t protocol.FileChangeType
 	switch {
 	case event.Op.Has(fsnotify.Rename):
 		// A rename is treated as a deletion of the old path because the
 		// fsnotify RENAME event doesn't include the new path. A separate
 		// CREATE event will be sent for the new path if the destination
 		// directory is watched.
 		fallthrough
 	case event.Op.Has(fsnotify.Remove):
 		// TODO(hxjiang): Directory removal events from some LSP clients may
 		// not include corresponding removal events for child files and
 		// subdirectories. Should we do some filtering when adding the dir
 		// deletion event to the events slice.
 		t = protocol.Deleted
 	case event.Op.Has(fsnotify.Create):
 		t = protocol.Created
 	case event.Op.Has(fsnotify.Write):
 		if isDir {
 			return protocol.FileEvent{}, isDir // ignore dir write events
 		}
 		t = protocol.Changed
 	default:
 		return protocol.FileEvent{}, isDir // ignore the rest of the events
 	}

 	return protocol.FileEvent{
 		URI:  protocol.URIFromPath(event.Name),
 		Type: t,
 	}, isDir
 }

 // watchDir registers a watch for a directory, retrying with backoff if it fails.
 // It can be canceled by calling removeWatchHandle.
 // Returns nil on success or cancellation; otherwise, the last error after all
 // retries.
 func (w *Watcher) watchDir(path string, done chan struct{}) error {
 	// On darwin, watching a directory will fail if it contains broken symbolic
 	// links. This state can occur temporarily during operations like a git
 	// branch switch. To handle this, we retry multiple times with exponential
 	// backoff, allowing time for the symbolic link's target to be created.

 	// TODO(hxjiang): Address a race condition where file or directory creations
 	// under current directory might be missed between the current directory
 	// creation and the establishment of the file watch.
 	//
 	// To fix this, we should:
 	// 1. Retrospectively check for and trigger creation events for any new
 	// files/directories.
 	// 2. Recursively add watches for any newly created subdirectories.
 	var (
 		delay = 500 * time.Millisecond
 		err   error
 	)

 	for i := range 5 {
 		if i > 0 {
 			select {
 			case <-time.After(delay):
 				delay *= 2
 			case <-done:
 				return nil // cancelled
 			}
 		}
 		// This function may block due to fsnotify/fsnotify#502.
 		err = w.watcher.Add(path)
 		if afterAddHook != nil {
 			afterAddHook(path, err)
 		}
 		if err == nil {
 			break
 		}
 	}

 	return err
 }

 var afterAddHook func(path string, err error)

 // addWatchHandle registers a new directory watch.
 // The returned 'done' channel should be used to signal cancellation of a
 // pending watch, the release function should be called once watch registration
 // is done.
 // It returns nil if the watcher is already closing.
 func (w *Watcher) addWatchHandle(path string) (done chan struct{}, release func()) {
 	w.mu.Lock()
 	defer w.mu.Unlock()

 	if w.dirCancel == nil { // file watcher is closing.
 		return nil, nil
 	}

 	done = make(chan struct{})
 	w.dirCancel[path] = done

 	w.watchers.Add(1)

 	return done, w.watchers.Done
 }

 // removeWatchHandle removes the handle for a directory watch and cancels any
 // pending watch attempt for that path.
 func (w *Watcher) removeWatchHandle(path string) {
 	w.mu.Lock()
 	defer w.mu.Unlock()

 	if done, ok := w.dirCancel[path]; ok {
 		delete(w.dirCancel, path)
 		close(done)
 	}
 }

 // isWatchedDir reports whether the given path has a watch handle, meaning it is
 // a directory the watcher is managing.
 func (w *Watcher) isWatchedDir(path string) bool {
 	w.mu.Lock()
 	defer w.mu.Unlock()

 	_, isDir := w.dirCancel[path]
 	return isDir
 }

 func (w *Watcher) addEvent(event protocol.FileEvent) {
 	w.mu.Lock()
 	defer w.mu.Unlock()

 	// Some systems emit duplicate change events in close
 	// succession upon file modification. While the current
 	// deduplication is naive and only handles immediate duplicates,
 	// a more robust solution is needed.
 	//
 	// TODO(hxjiang): Enhance deduplication. The current batching of
 	// events means all duplicates, regardless of proximity, should
 	// be removed. Consider checking the entire buffered slice or
 	// using a map for this.
 	if len(w.events) == 0 || w.events[len(w.events)-1] != event {
 		w.events = append(w.events, event)
 	}
 }

 func (w *Watcher) drainEvents() []protocol.FileEvent {
 	w.mu.Lock()
 	events := w.events
 	w.events = nil
 	w.mu.Unlock()

 	return events
 }

 // Close shuts down the watcher, waits for the internal goroutine to terminate,
 // and returns any final error.
 func (w *Watcher) Close() error {
 	// Set dirCancel to nil which prevent any future watch attempts.
 	w.mu.Lock()
 	dirCancel := w.dirCancel
 	w.dirCancel = nil
 	w.mu.Unlock()

 	// Cancel any ongoing watch registration.
 	for _, ch := range dirCancel {
 		close(ch)
 	}

 	// Wait for all watch registration goroutines to finish, including their
 	// error handling. This ensures that:
 	// - All [Watcher.watchDir] goroutines have exited and it's error is sent
 	//   to the internal error channel. So it is safe to close the internal
 	//   error channel.
 	// - There are no ongoing [fsnotify.Watcher.Add] calls, so it is safe to
 	//   close the fsnotify watcher (see fsnotify/fsnotify#704).
 	w.watchers.Wait()
 	close(w.errs)

 	err := w.watcher.Close()

 	// Wait for the main run loop to terminate.
 	close(w.stop)
 	w.runners.Wait()

 	return err
 }
	// Copyright 2025 The Go Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style
	// license that can be found in the LICENSE file.

	package filewatcher

	import (
	"errors"
	"io/fs"
	"log/slog"
	"os"
	"path/filepath"
	"strings"
	"sync"
	"time"

	"github.com/fsnotify/fsnotify"
	"golang.org/x/tools/gopls/internal/protocol"
	)

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

	// Watcher collects events from a [fsnotify.Watcher] and converts them into
	// batched LSP [protocol.FileEvent]s.
	type Watcher struct {
	logger *slog.Logger

	stop chan struct{} // closed by Close to terminate run loop

	// errs is an internal channel for surfacing errors from the file watcher,
	// distinct from the fsnotify watcher's error channel.
	errs chan error

	runners sync.WaitGroup // counts the number of active run goroutines (max 1)

	watcher *fsnotify.Watcher

	mu sync.Mutex // guards all fields below

	// watchers counts the number of active watch registration goroutines,
	// including their error handling.
	// After [Watcher.Close] called, watchers's counter will no longer increase.
	watchers sync.WaitGroup

	// dirCancel maps a directory path to its cancellation channel.
	// A nil map indicates the watcher is closing and prevents new directory
	// watch registrations.
	dirCancel map[string]chan struct{}

	// events is the current batch of unsent file events, which will be sent
	// when the timer expires.
	events []protocol.FileEvent
	}

	// New creates a new file watcher and starts its event-handling loop. The
	// [Watcher.Close] method must be called to clean up resources.
	//
	// The provided handler is called sequentially with either a batch of file
	// events or an error. Events and errors may be interleaved. The watcher blocks
	// until the handler returns, so the handler should be fast and non-blocking.
	func New(delay time.Duration, logger slog.Logger, handler func([]protocol.FileEvent, error)) (Watcher, error) {
	watcher, err := fsnotify.NewWatcher()
	if err != nil {
	return nil, err
	}
	w := &Watcher{
	logger: logger,
	watcher: watcher,
	dirCancel: make(map[string]chan struct{}),
	errs: make(chan error),
	stop: make(chan struct{}),
	}

	w.runners.Add(1)
	go w.run(delay, handler)

	return w, nil
	}

	// run is the main event-handling loop for the watcher. It should be run in a
	// separate goroutine.
	func (w *Watcher) run(delay time.Duration, handler func([]protocol.FileEvent, error)) {
	defer w.runners.Done()

	// timer is used to debounce events.
	timer := time.NewTimer(delay)
	defer timer.Stop()

	for {
	select {
	case <-w.stop:
	return

	case <-timer.C:
	if events := w.drainEvents(); len(events) > 0 {
	handler(events, nil)
	}
	timer.Reset(delay)

	case err, ok := <-w.watcher.Errors:
	// When the watcher is closed, its Errors channel is closed, which
	// unblocks this case. We continue to the next loop iteration,
	// allowing the <-w.stop case to handle the shutdown.
	if !ok {
	continue
	}
	if err != nil {
	handler(nil, err)
	}

	case err, ok := <-w.errs:
	if !ok {
	continue
	}
	if err != nil {
	handler(nil, err)
	}

	case event, ok := <-w.watcher.Events:
	if !ok {
	continue
	}

	// fsnotify does not guarantee clean filepaths.
	event.Name = filepath.Clean(event.Name)

	// fsnotify.Event should not be handled concurrently, to preserve their
	// original order. For example, if a file is deleted and recreated,
	// concurrent handling could process the events in reverse order.
	//
	// Only reset the timer if a relevant event happened.
	// https://github.com/fsnotify/fsnotify?tab=readme-ov-file#why-do-i-get-many-chmod-events
	e, isDir := w.convertEvent(event)
	if e == (protocol.FileEvent{}) {
	continue
	}

	if isDir {
	switch e.Type {
	case protocol.Created:
	// Newly created directories are watched asynchronously to prevent
	// a potential deadlock on Windows(see fsnotify/fsnotify#502).
	// Errors are reported internally.
	if done, release := w.addWatchHandle(event.Name); done != nil {
	go func() {
	w.errs <- w.watchDir(event.Name, done)

	// Only release after the error is sent.
	release()
	}()
	}
	case protocol.Deleted:
	// Upon removal, we only need to remove the entries from
	// the map. The [fsnotify.Watcher] removes the watch for
	// us. fsnotify/fsnotify#268
	w.removeWatchHandle(event.Name)
	default:
	// convertEvent enforces that dirs are only Created or Deleted.
	panic("impossible")
	}
	}

	w.addEvent(e)
	timer.Reset(delay)
	}
	}
	}

	// skipDir reports whether the input dir should be skipped.
	// Directories that are unlikely to contain Go source files relevant for
	// analysis, such as .git directories or testdata, should be skipped to
	// avoid unnecessary file system notifications. This reduces noise and
	// improves efficiency. Conversely, any directory that might contain Go
	// source code should be watched to ensure that gopls can respond to
	// file changes.
	func skipDir(dirName string) bool {
	// TODO(hxjiang): the file watcher should honor gopls directory
	// filter or the new go.mod ignore directive, or actively listening
	// to gopls register capability request with method
	// "workspace/didChangeWatchedFiles" like a real LSP client.
	return strings.HasPrefix(dirName, ".") \|\| strings.HasPrefix(dirName, "_") \|\| dirName == "testdata"
	}

	// WatchDir walks through the directory and all its subdirectories, adding
	// them to the watcher.
	func (w *Watcher) WatchDir(path string) error {
	return filepath.WalkDir(filepath.Clean(path), func(path string, d fs.DirEntry, err error) error {
	if d.IsDir() {
	if skipDir(d.Name()) {
	return filepath.SkipDir
	}

	done, release := w.addWatchHandle(path)
	if done == nil { // file watcher closing
	return filepath.SkipAll
	}
	defer release()

	return w.watchDir(path, done)
	}
	return nil
	})
	}

	// convertEvent translates an [fsnotify.Event] into a [protocol.FileEvent].
	// It returns the translated event and a boolean indicating if the path was a
	// directory. For directories, the event Type is either Created or Deleted.
	// It returns empty event for events that should be ignored.
	func (w *Watcher) convertEvent(event fsnotify.Event) (_ protocol.FileEvent, isDir bool) {
	// Determine if the event is for a directory.
	if info, err := os.Stat(event.Name); err == nil {
	isDir = info.IsDir()
	} else if os.IsNotExist(err) {
	// Upon deletion, the file/dir has been removed. fsnotify does not
	// provide information regarding the deleted item.
	// Use watchHandles to determine if the deleted item was a directory.
	isDir = w.isWatchedDir(event.Name)
	} else {
	// If statting failed, something is wrong with the file system.
	// Log and move on.
	if w.logger != nil {
	w.logger.Error("failed to stat path, skipping event as its type (file/dir) is unknown", "path", event.Name, "err", err)
	}
	return protocol.FileEvent{}, false
	}

	// Filter out events for directories and files that are not of interest.
	if isDir {
	if skipDir(filepath.Base(event.Name)) {
	return protocol.FileEvent{}, true
	}
	} else {
	switch strings.TrimPrefix(filepath.Ext(event.Name), ".") {
	case "go", "mod", "sum", "work", "s":
	default:
	return protocol.FileEvent{}, false
	}
	}

	var t protocol.FileChangeType
	switch {
	case event.Op.Has(fsnotify.Rename):
	// A rename is treated as a deletion of the old path because the
	// fsnotify RENAME event doesn't include the new path. A separate
	// CREATE event will be sent for the new path if the destination
	// directory is watched.
	fallthrough
	case event.Op.Has(fsnotify.Remove):
	// TODO(hxjiang): Directory removal events from some LSP clients may
	// not include corresponding removal events for child files and
	// subdirectories. Should we do some filtering when adding the dir
	// deletion event to the events slice.
	t = protocol.Deleted
	case event.Op.Has(fsnotify.Create):
	t = protocol.Created
	case event.Op.Has(fsnotify.Write):
	if isDir {
	return protocol.FileEvent{}, isDir // ignore dir write events
	}
	t = protocol.Changed
	default:
	return protocol.FileEvent{}, isDir // ignore the rest of the events
	}

	return protocol.FileEvent{
	URI: protocol.URIFromPath(event.Name),
	Type: t,
	}, isDir
	}

	// watchDir registers a watch for a directory, retrying with backoff if it fails.
	// It can be canceled by calling removeWatchHandle.
	// Returns nil on success or cancellation; otherwise, the last error after all
	// retries.
	func (w *Watcher) watchDir(path string, done chan struct{}) error {
	// On darwin, watching a directory will fail if it contains broken symbolic
	// links. This state can occur temporarily during operations like a git
	// branch switch. To handle this, we retry multiple times with exponential
	// backoff, allowing time for the symbolic link's target to be created.

	// TODO(hxjiang): Address a race condition where file or directory creations
	// under current directory might be missed between the current directory
	// creation and the establishment of the file watch.
	//
	// To fix this, we should:
	// 1. Retrospectively check for and trigger creation events for any new
	// files/directories.
	// 2. Recursively add watches for any newly created subdirectories.
	var (
	delay = 500 * time.Millisecond
	err error
	)

	for i := range 5 {
	if i > 0 {
	select {
	case <-time.After(delay):
	delay *= 2
	case <-done:
	return nil // cancelled
	}
	}
	// This function may block due to fsnotify/fsnotify#502.
	err = w.watcher.Add(path)
	if afterAddHook != nil {
	afterAddHook(path, err)
	}
	if err == nil {
	break
	}
	}

	return err
	}

	var afterAddHook func(path string, err error)

	// addWatchHandle registers a new directory watch.
	// The returned 'done' channel should be used to signal cancellation of a
	// pending watch, the release function should be called once watch registration
	// is done.
	// It returns nil if the watcher is already closing.
	func (w *Watcher) addWatchHandle(path string) (done chan struct{}, release func()) {
	w.mu.Lock()
	defer w.mu.Unlock()

	if w.dirCancel == nil { // file watcher is closing.
	return nil, nil
	}

	done = make(chan struct{})
	w.dirCancel[path] = done

	w.watchers.Add(1)

	return done, w.watchers.Done
	}

	// removeWatchHandle removes the handle for a directory watch and cancels any
	// pending watch attempt for that path.
	func (w *Watcher) removeWatchHandle(path string) {
	w.mu.Lock()
	defer w.mu.Unlock()

	if done, ok := w.dirCancel[path]; ok {
	delete(w.dirCancel, path)
	close(done)
	}
	}

	// isWatchedDir reports whether the given path has a watch handle, meaning it is
	// a directory the watcher is managing.
	func (w *Watcher) isWatchedDir(path string) bool {
	w.mu.Lock()
	defer w.mu.Unlock()

	_, isDir := w.dirCancel[path]
	return isDir
	}

	func (w *Watcher) addEvent(event protocol.FileEvent) {
	w.mu.Lock()
	defer w.mu.Unlock()

	// Some systems emit duplicate change events in close
	// succession upon file modification. While the current
	// deduplication is naive and only handles immediate duplicates,
	// a more robust solution is needed.
	//
	// TODO(hxjiang): Enhance deduplication. The current batching of
	// events means all duplicates, regardless of proximity, should
	// be removed. Consider checking the entire buffered slice or
	// using a map for this.
	if len(w.events) == 0 \|\| w.events[len(w.events)-1] != event {
	w.events = append(w.events, event)
	}
	}

	func (w *Watcher) drainEvents() []protocol.FileEvent {
	w.mu.Lock()
	events := w.events
	w.events = nil
	w.mu.Unlock()

	return events
	}

	// Close shuts down the watcher, waits for the internal goroutine to terminate,
	// and returns any final error.
	func (w *Watcher) Close() error {
	// Set dirCancel to nil which prevent any future watch attempts.
	w.mu.Lock()
	dirCancel := w.dirCancel
	w.dirCancel = nil
	w.mu.Unlock()

	// Cancel any ongoing watch registration.
	for _, ch := range dirCancel {
	close(ch)
	}

	// Wait for all watch registration goroutines to finish, including their
	// error handling. This ensures that:
	// - All [Watcher.watchDir] goroutines have exited and it's error is sent
	// to the internal error channel. So it is safe to close the internal
	// error channel.
	// - There are no ongoing [fsnotify.Watcher.Add] calls, so it is safe to
	// close the fsnotify watcher (see fsnotify/fsnotify#704).
	w.watchers.Wait()
	close(w.errs)

	err := w.watcher.Close()

	// Wait for the main run loop to terminate.
	close(w.stop)
	w.runners.Wait()

	return err
	}