=====================
 Triggered execution
=====================

.. howto::
   :id: basic
   :title: Run a command when sources change
   :type: command
   
   ~ test

You can make a command run when certain files change by prefixing the command with `~`.  Monitoring is terminated when `enter` is pressed.  This triggered execution is configured by the `watch` setting, but typically the basic settings `watchSources` and `pollInterval` are modified as described in later sections.

The original use-case for triggered execution was continuous compilation:

::

    > ~ test:compile

    > ~ compile

You can use the triggered execution feature to run any command or task, however.  The following will poll for changes to your source code (main or test) and run `testOnly` for the specified test.

::

    > ~ testOnly example.TestA

.. howto::
   :id: multi
   :title: Run multiple commands when sources change
   :type: command
   
   ~ ;a ;b

The command passed to `~` may be any command string, so multiple commands may be run by separating them with a semicolon.  For example,

::

    > ~ ;a ;b

This runs `a` and then `b` when sources change.

.. howto::
   :id: sources
   :title: Configure the sources that are checked for changes
   :type: setting
   
   watchSources += baseDirectory.value / "examples.txt"

* `watchSources` defines the files for a single project that are monitored for changes.  By default, a project watches resources and Scala and Java sources.
* `watchTransitiveSources` then combines the `watchSources` for the current project and all execution and classpath dependencies (see :doc:`/Getting-Started/Full-Def` for details on inter-project dependencies).

To add the file `demo/example.txt` to the files to watch,

::

    watchSources += baseDirectory.value / "demo" / "examples.txt"

.. howto::
   :id: interval
   :title: Set the time interval between checks for changes to sources
   :type: setting
   
   pollInterval := 1000 // in ms

`pollInterval` selects the interval between polling for changes in milliseconds.  The default value is `500 ms`.  To change it to `1 s`,

::

    pollInterval := 1000 // in ms