New Watcher Dialog

File | Settings | Tools | File Watchers - New Watcher for Windows and Linux

IntelliJ IDEA | Preferences | Tools | File Watchers - New Watcher for macOS

⌘,⌘,⌘,⌥F7⌃⌥S

---

The dialog opens when you click the Add  or Edit  button on the File Watchers page. Use the dialog box to create a project File Watcher based on a predefined IntelliJ IDEA File Watcher template or to edit an existing project File Watcher.

Each template contains the settings that are optimal for the selected compiler. So in most cases, all you need is specify the path to the compiler executable.

On this page:

• Name
• Files to watch
• Tool to run on changes
• Working Directory and Environment Variables
• Advanced Options
• Options area
• Examples of customizing the behaviour of a compiler

Name

Item	Description
Name	In this text box, type the name of the File Watcher. By default, IntelliJ IDEA suggests the name of the selected predefined template.

Files to watch

In this area, specify the type and the range of files the File Watcher can be applied to. Changes in these files will invoke the File Watcher either immediately or upon save or frame deactivation, depending on the status of the Immediate file synchronization checkbox.

You can choose one of the predefined scopes from the drop-down list:

• Project Files: all the files within the project content roots (see Configuring Projects ).
• Project Production Files: all the files within the project content roots excluding test sources.
• Project Test Files: all the files within the project test source roots.
• Open Files: all the files that are currently opened in the editor.

VCS Scopes: these scopes are only available if your project is under version control.

• Changed Files: all changed files, that is, all files associated with all existing changelists.
• Default: all the files associated with the changelist Default.

Alternatively, click the Browse button and configure a custom scope in the Scopes dialog box that opens.

Item	Description
File type	Use this drop-down list to specify the expected type of input files. The File Watcher will consider only files of this type as subject for analyzing and processing. File types are recognised based on associations between file types and file extensions. By default, the field shows the file type in accordance with the chosen predefined File Watcher template.
Scope Learn more from Scope and Scopes page.	Use this drop-down list to define the range of files the File Watcher can be applied to. Changes in these files will invoke the File Watcher either immediately or upon save or frame deactivation, depending on the status of the Immediate file synchronization checkbox. You can choose one of the predefined scopes from the drop-down list: Project Files: all the files within the project content roots (see Configuring Projects ). Project Production Files: all the files within the project content roots excluding test sources. Project Test Files: all the files within the project test source roots. Open Files: all the files that are currently opened in the editor. VCS Scopes: these scopes are only available if your project is under version control. Changed Files: all changed files, that is, all files associated with all existing changelists. Default: all the files associated with the changelist Default. Alternatively, click the Browse button and configure a custom scope in the Scopes dialog box that opens.
Track only root files	When the File Watcher is invoked on a file, IntelliJ IDEA detects all the files in which this file is included. For each of these files, in its turn, IntelliJ IDEA again detects the files into which it is included. This operation is repeated recursively until IntelliJ IDEA reaches the files that are not included anywhere within the specified scope. These files are referred to as root files (do not confuse with content roots). When this checkbox is selected, the File Watcher runs only against the root files. When the checkbox is cleared, the File Watcher runs against the file from which it is invoked and against all the files in which this file is included recursively within the specified scope. This option is available only for Babel, Closure Compiler, Compass, Jade, Less, Sass/SCSS, Stylus, UglifyJS, and YUI Compressor JS.

Tool to run on changes

In this area, configure interaction with the compiler: specify the executable file to use, the arguments to pass to it, and customize the default template settings for input and output.

Item	Description
Program	In this text box, specify the path to the executable file of the compiler (.exe, .cmd, .bat, or other depending on the specific tool.) Do one of the following: Type the path explicitly. Click the Browse button to open the Select Path dialog box and navigate to the desired location. Click the Insert Macro button to open the Macros dialog box where you can select the relevant macro from the list.
Arguments	In this text box, define the arguments to pass to the compiler and thus influence its behaviour. Among other cases, use this text box to change the default output location, that is, specify a custom location where you want the compiler to store the files generated during compilation. Note that if you re-define the default output location here you need to clear the Create output file from stdout checkbox in the Advanced Options area because otherwise the content of your generated file will be overwritten by the compiler's output stream. Do one of the following: Type the list of arguments in the text box. Click the Insert Macro button to open the Macros dialog box where you can select the desired macro from the list. When specifying the arguments, follow these rules: Use spaces to separate individual arguments. If an argument includes spaces, enclose the spaces or the argument that contains the spaces in double quotes, for example, some" "arg or "some arg". If an argument includes double quotes (e.g. as part of the argument), escape the double quotes by means of the backslashes, for example, -Dmy.prop=\"quoted_value"\.
Output paths to refresh	In this text box, specify the files where the compiler stores its output: the resulting source code, source maps, and dependencies. In other words, tell IntelliJ IDEA where it should search for the files generated through compilation. Please note, that changing the value in this text box does not make the compiler store its output in another location. To do that, specify the desired output location in the Arguments text box: type the output paths using colons as separators or click the Insert Macro button to open the Macros dialog box and select the desired pattern from the list.

Working Directory and Environment Variables

Item	Description
Working directory	In this text box, specify the directory to which the compiler will be applied. Because the tool is always invoked in the context of a file, the default working directory is the directory of the current file. This setting is specified in all predefined templates through a macros $FileDir$. To update this default settings, do one of the following: Type the path explicitly in the text box. Click the Browse button to open the Select Path dialog box and navigate to the desired location. Click the Insert Macro button to open the Macros dialog box, where you can select the desired macro from the list. If the field is left blank, IntelliJ IDEA uses the directory of the file where the File Watcher is invoked.
Environment variables	Use this text box to specify a the PATH variable for a tool that is required for starting the compiler but is not referenced in the path to it.

Advanced Options

Item	Description
Immediate file synchronization	Select this checkbox to have the File Watcher invoked as soon as any changes are made to the source code. If the checkbox is cleared, the File Watcher will start upon save (File | Save All, ⌘S⌘S⌘S⌃S⌃X, ⌃S) or when you move focus from IntelliJ IDEA (upon frame deactivation).
Trigger watcher regardless of syntax errors	Select this checkbox to have the File Watcher ignore update, save, and change focus events in files that are syntactically invalid. If this checkbox is cleared, the File Watcher starts anyway upon update, save, or frame deactivation, depending on the status of the Immediate file synchronization checkbox.
Create output file from stdout	When this checkbox is selected, IntelliJ IDEA reads the native compiler output (standard output stream (stdout)) and generates the resulting files from it. When the checkbox is cleared, the compiler writes its output directly to the files specified in the Output paths to refresh field. Some compilers generate a standard output stream (stdout) file, others do not, which may lead to errors. Therefore it is strongly recommended to preserve the default setting.
Show console	Use this drop-down list to define when you want the File Watcher open its dedicated console with messages. The available options are: Always: when this option is chosen, the File Watcher opens the console when it starts. Error: when this option is chosen, the File Watcher opens the console only if any errors occur in compilation. Never: choose this option to suppress opening the console under any circumstances.
Output Filters	Click this button to open the Output Filters dialog where you can manage the list of filters to distinguish the output of the File Watcher from other output. These filters make the basis for: Displaying paths to the File Watcher output files as links in error and other messages and logs. When you click such link, the corresponding file is opened in the editor. For example, to get useful error messages displayed, specify the following expression in the Regular expression to match output field of the Add/Edit Filter Dialog: $FILE_PATH$:$LINE$ $MESSAGE$ Error highlighting in the output files.

Options area

In this area, configure the behaviour of the File Watcher.

Item	Description

Examples of customizing the behaviour of a compiler

Any compiler is an external, third-party tool. Therefore the only way to influence a compiler is pass arguments to it just as if you were working in the command line mode. These arguments are specific for each tool. Below are two examples of customizing the default output location for the CoffeeScript compiler.

Suppose, you have a project with the following folder structure:

By default, the generated files will be stored in the folder where the original file is. You can change this default location and have the generated files stored in the js folder. Moreover, you can have them stored in a flat list or arranged in the folder structure that repeats the original structure under the app node.

• To have all the generated files stored in the output js folder without retaining the original folder structure under the app folder:
  1. In the Arguments text box, type:

     --output $ProjectFileDir$\js\ --compile --map $FileName$
                         

  2. In the Output paths to refresh text box, type:

     $ProjectFileDir$\js\$FileNameWithoutExtension$.js:$ProjectFileDir$\js\$FileNameWithoutExtension$.map
                         

  As a result, the project tree looks as follows:

  

• To have the original folder structure under the app node retained in the output js folder:
  1. In the Arguments text box, type:

     --output $ProjectFileDir$\js\$FileDirRelativeToProjectRoot$\ --compile --map $FileName$
                         

  2. In the Output paths to refresh text box, type:

     $ProjectFileDir$\js\$FileDirRelativeToProjectRoot$\$FileNameWithoutExtension$.js:$ProjectFileDir$\js\$FileDirRelativeToProjectRoot$\$FileNameWithoutExtension$.map
                         

  As a result, the project tree looks as follows: