watch() API connects globs to tasks using a file system watcher. It watches for changes to files that match the globs and executes the task when a change occurs. If the task doesn't signal Async Completion, it will never be run a second time.
This API provides built-in delay and queueing based on most-common-use defaults.
A watcher's task cannot be synchronous, like tasks registered into the task system. If you pass a sync task, the completion can't be determined and the task won't run again - it is assumed to still be running.
There is no error or warning message provided because the file watcher keeps your Node process running. Since the process doesn't exit, it cannot be determined whether the task is done or just taking a really, really long time to run.
By default, the watcher executes tasks whenever a file is created, changed, or deleted.
If you need to use different events, you can use the
events option when calling
watch(). The available events are
'all' is available, which represents all events other than
watch(), the tasks won't be executed, instead they'll wait for the first file change.
To execute tasks before the first file change, set the
ignoreInitial option to
watch() guarantees that its currently running task won't execute again concurrently. When a file change is made while a watcher task is running, another execution will queue up to run when the task finishes. Only one run can be queued up at a time.
To disable queueing, set the
queue option to
Upon file change, a watcher task won't run until a 200ms delay has elapsed. This is to avoid starting a task too early when many files are being changed at once - like find-and-replace.
To adjust the delay duration, set the
delay option to a positive integer.
You likely won't use this feature, but if you need full control over changed files - like access to paths or metadata - use the chokidar instance returned from
Be careful: The returned chokidar instance doesn't have queueing, delay, or async completion features.
Gulp has an optional dependency called fsevents, which is a Mac-specific file watcher. If you see an installation warning for fsevents - "npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents" - it is not an issue. If fsevents installation is skipped, a fallback watcher will be used and any errors occurring in your gulpfile aren't related to this warning.