In case we'd like to watch more than one file, the pattern-matching capabilities of the standard Grunt files configuration can be used. The following configuration example will observe all the files in the project root or any of its sub directories with the txt extension:

watch: {
  sample: {
    files: ['**/*.txt'],
    tasks: ['sample']
  }
}

In case we'd like to run more than one task each time a file event is observed, we can just add the tasks to the array passed to the tasks configuration:

watch: {
  sample: {
    files: ['sample.txt'],
    tasks: ['sample', 'another', 'finally']
  }
}

The default behavior of the watch task is to start each of the triggered tasks in their own child process. This prevents failing triggered tasks from causing the watch task itself to fail. As a side effect, it also clones the context of the watcher process for each task. This behavior can however be disabled by setting the spawn option to false, which triggers tasks a little faster and allows them to share a context between them. The following demonstrates the configuration for this:

watch: {
  sample: {
    files: ['sample.txt'],
    tasks: ['sample'],
    options: {
      spawn: false
    }
  }
}

The default behavior for the watcher is to wait for the completion of the tasks triggered by the previous change, before waiting for changes again. By setting the interrupt option to true, the watcher will stop running tasks when a change is detected and start rerunning them. The following demonstrates the configuration for this:

watch: {
  sample: {
    files: ['sample.txt'],
    tasks: ['sample'],
    options: {
      interrupt: true
    }
  }
}

The default period the watcher will wait before checking for file changes after a previous task run is 500ms. This amount of time can be changed by setting the debounceDelay option to the number of milliseconds you'd like for it to wait. The following demonstrates the configuration for this:

watch: {
  sample: {
    files: ['sample.txt'],
    tasks: ['sample'],
    options: {
      debounceDelay: 1000
    }
  }
}

In addition to being changed, files can also be added and deleted. The default behavior of the watcher is to observe all these events, but if you'd like it to run tasks only on specific events, the event option can be set to either changed, added, deleted, or all.

The following example will only start the sample task if a file named sample.txt is added or deleted to the same path as the configuration file:

watch: {
  sample: {
    files: ['sample.txt'],
    tasks: ['sample'],
    options: {
      event: ['added', 'deleted']
    }
  }
}

Warnings and failures that are raised by the tasks started by the watch task will, by default, not interrupt its execution. Setting the forever option to false will disable this behavior and allow child tasks to stop the watcher process on warnings and failures. The following demonstrates the configuration for this:

watch: {
  options: {
    forever: false
  },
  sample: {
    files: ['sample.txt'],
    tasks: ['sample']
  }
}

In the case that you'd like to run the tasks specified in the tasks option once the watcher starts up, and not only once file events are observed, you can set the atBegin option to true. The following demonstrates the configuration for this:

watch: {
  sample: {
    files: ['sample.txt'],
    tasks: ['sample'],
    options: {
      atBegin: true
    }
  }
}