PathWatcher

Description

Manage a subscription to filesystem events that occur beneath a root directory. Construct these by calling watchPath. To watch for events within active project directories, use Project::onDidChangeFiles instead.

Multiple PathWatchers may be backed by a single native watcher to conserve operation system resources.

Call PathWatcher::dispose to stop receiving events and, if possible, release underlying resources. A PathWatcher may be added to a CompositeDisposable to manage its lifetime along with other Disposable resources like event subscriptions.

const {watchPath} = require('atom')

const disposable = await watchPath('/var/log', {}, events => {
  console.log(`Received batch of ${events.length} events.`)
  for (const event of events) {
    // "created", "modified", "deleted", "renamed"
    console.log(`Event action: ${event.action}`)

    // absolute path to the filesystem entry that was touched
    console.log(`Event path: ${event.path}`)

    if (event.action === 'renamed') {
      console.log(`.. renamed from: ${event.oldPath}`)
    }
  }
})

 // Immediately stop receiving filesystem events. If this is the last
 // watcher, asynchronously release any OS resources required to
 // subscribe to these events.
 disposable.dispose()

watchPath accepts the following arguments:

API documentation

All methods

::getStartPromise()

Return a Promise that will resolve when the underlying native watcher is ready to begin sending events. When testing filesystem watchers, it's important to await this promise before making filesystem changes that you intend to assert about because there will be a delay between the instantiation of the watcher and the activation of the underlying OS resources that feed its events.

PathWatchers acquired through watchPath are already started.

const {watchPath} = require('atom')
const ROOT = path.join(__dirname, 'fixtures')
const FILE = path.join(ROOT, 'filename.txt')

describe('something', function () {
  it("doesn't miss events", async function () {
    const watcher = watchPath(ROOT, {}, events => {})
    await watcher.getStartPromise()
    fs.writeFile(FILE, 'contents\n', err => {
      // The watcher is listening and the event should be
      // received asynchronously
    }
  })
})

::onDidError(callback)

Invoke a Function when any errors related to this watcher are reported.

Argument Description
callback

Function to be called when an error occurs.
err

An Error describing the failure condition.
Return values

::dispose()

Unsubscribe all subscribers from filesystem events. Native resources will be released asynchronously, but this watcher will stop broadcasting events immediately.