File Watchers allow you to automatically run command-line tools like compilers, formatters, or linters when you change or save a file in the IDE.
You can configure a File Watcher from scratch or use one of the available templates. Configured File Watcher can be saved in your project settings or in the IDE settings and used in different projects.
Creating a File Watcher
Create a File Watcher
In the Settings/Preferences dialog (Ctrl+Alt+S), click File Watchers under Tools. The File Watchers page opens showing a list of File Watchers that are already configured in this project and in the IDE.
Click and choose the predefined template from which you want to create a File Watcher. The choice depends on the tool you are going to use. To use a tool that is not on the list, choose Custom. The New Watcher dialog box opens.
In the Name text box, type the name of the File Watcher. By default, CLion suggests the name of the selected predefined template.
Configuring the expected type and location of input files
Use the controls in the Files to watch area to define the range of files where you want to apply the File Watcher.
From the File type drop-down list, choose 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.
- Choose the Scope in which the File Watcher is applicable. Changes in these files will invoke the File Watcher either immediately or upon save or frame deactivation, depending on the status of the Auto-save edited files to trigger the watcher checkbox.
Choose one of the predefined scopes from the drop-down list. For a project-level File Watcher, you can also click to configure a custom scope in the Scopes dialog that opens.
All Places: all the scopes listed below.
Project Files: all the files within the project roots.
Scratches and Consoles: all the files from the Scratches and Consoles directory located in the Project tool window.
Open Files: all the files that are currently opened in the editor.
Current File: the file opened in the active editor tab.
- Optionally: specify how you want the File Watcher to deal with dependencies. A root file is a file that is not included (e.g. via
import) in any other file within the specified scope.
To run the File Watcher only against root files, select the Track only root files checkbox.
Clear the checkbox to run the File Watcher against the file from which it is invoked and against all the files in which this file is recursively included within the specified scope.
Configuring interaction with the external tool
In the Tool to run on changes area, specify the tool to use, the arguments to pass to it, the expected output file types, etc.
- In the Program text box, specify the path to the executable file of the tool (
.bat, or other depending on the specific tool).
If you are configuring a global file watcher for a tool installed inside a project (e.g. Prettier), you need to specify the path to it using a macro. To use one of the available macros in the path, press the Insert Macro button. For example, with the path $ProjectFileDir$/node_modules/.bin/prettier, the File Watcher will use prettier installed in the project’s node_module folder.
In the Arguments text box, define the arguments to pass to the tool. Arguments are usually specified using macros, for example,
$FileNameWithoutExtension$, that will be replaced with actual file names.
Type the macros manually or click Insert Macro and select the relevant pattern fom the list in the Macros dialog that opens.
- In the Output paths to refresh text box, specify the files where the tool stores its output: the resulting source code, source maps, and dependencies. Based on these settings, CLion recognizes the files generated through compilation.
Please note, that changing the value in the Output paths to refresh text box does not make the tool store its output in another place. If you still need to do that, specify the desired custom output location in the Arguments text box: type the output paths with colons as separators and use macros.
Output paths are usually specified using macros. Type the path manually o click Insert Macro and select the relevant pattern from the list.
Expand the Working Directory and Environment Variables hidden area.
Define the environment variables. For example, specify the
PATHvariable for the tools that are required for starting the tool you are configuring but are not referenced in the path to it. In most cases it is Node.js or ruby.exe. Such situation may result from custom manual installation instead of installation through the Node Package Manager (npm) or gem manager.
In the Working Directory text box, specify the directory to which the tool 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. The default working directory is specified in all predefined templates through a
$FileDir$macros. To specify a custom working directory, type the path to it in the text box, or click and choose the directory in the Select Path dialog box, or click Insert Macro and select the desired macro from the list in the Macros dialog box.
Configuring advanced options
In the Advanced Options area, customize the default behaviour of the File Watcher.
- Specify the events that will invoke the File Watcher:
To invoke the File Watcher as soon as any changes are made to the source code, select the Auto-save edited files to trigger the watcher checkbox.
When the checkbox is cleared, the File Watcher starts upon save ( ) or when you move the focus from CLion (on frame deactivation).
By default, the File Watcher wakes up on any saved change, including the updates received from you version control system when you, for example, check out a branch. To ignore such changes and invoke the File Watcher only you update your code in CLion, clear the Trigger the watcher on external changes checkbox.
- Specify whether you want the File Watcher to interact with the CLion syntax parser:
When the Trigger watcher regardless of syntax errors checkbox is selected, the File Watcher start regardless of the syntactical correctness of a file. The File Watcher will start upon update, save, or frame deactivation, depending on the status of the Auto-save edited files to trigger the watcher checkbox.
When the Trigger watcher regardless of syntax errors checkbox is cleared, the File Watcher ignores all triggers in files that are syntactically invalid and starts only in error-free files.
- Use the Create output file from stdout checkbox to specify how you want to generate the output file.
When the checkbox is selected, CLion reads the native tool's output (
standard output stream (stdout)) and generates the resulting files from it.
When the checkbox is cleared, the tool writes its output directly to the files specified in the Output paths to refresh field.
- In the Show console drop-down list, choose when you want the File Watcher to open the console.
Always: with this option, the console always opens after the tool execution is completed.
On error: with this option, the console opens after the tool execution only when the
Exit codeis different from
Never: choose this option to suppress opening the console at all.
Showing information reported by File Watcher in the editor
If the tool configured in the File Watcher reports errors or warnings about your code with the links to the files and specific lines, you can see this information right in the editor:
In File Watcher Problems., enable the inspection
In the Output Filters field of the Edit Watcher dialog, describe the format of the output you want to match. Use the macros
$MESSAGE$for that. You need to avoid using special symbols like braces and dot with
\. The text matched with the
$MESSAGE$macro will be shown in the editor.
The tool reports errors in the following format:
ERROR: /Users/Alice/WebstormProjects/angular-app/src/main.ts[6, 27]: " should be '
ERROR: $FILE_PATH$\[$LINE$, $COLUMN$\]: $MESSAGE$
Saving, enabling and disabling File Watchers
Once you’ve saved the new File Watcher, you can decide if it’s going to be available only in the current project (select Project in the right column) or for all projects (select Global).
To enable or disable a File Watcher, select or clear the checkbox next to it indialog.
To toggle the enable/disable status of a File Watcher, select/clear the checkbox next to it on the File Watchers page of the Settings dialog box. If an error occurs while a File Watcher is running, the File Watcher is automatically disabled. To restore the status, enable the File Watcher manually.
When a File Watcher is enabled, it starts automatically as soon as a file of the selected type and in the selected scope is changed or saved, see Configuring advanced options.
Troubleshooting File Watchers
There might be a red error message next to the File Watcher in the list in.
Here is a list of possible errors:
The File Watcher uses a scope that is not defined in this project.
Double-click on the watcher and select an available scope or create a new one.
The project uses a global File Watcher that was removed.
Delete the watcher from the list using the Remove button () or edit it to create a new global watcher with the same name.
Example: managing Makefile projects with File Watchers
The following example presents a possible solution for those who wish to work with Make-based projects in CLion. Using a combination of CLion features, the Compilation Database support and File Watchers, we will construct a meta build system that will monitor changes in Makefiles, regenerate and reload the compilation database accordingly, and let us manage a Makefile project to a full extent from within the IDE.
Suppose we have a simple Makefile project consisting of three modules, general, io_lib, and math_lib, each stored in a separate directory that contains a Makefile, and in the root directory, the main Makefile that builds all the targets:
TARGETS = Math Io General all: $(TARGETS) Math: @$(MAKE) -C math_lib -f Makefile Io: @$(MAKE) -C io_lib -f Makefile General: @$(MAKE) -C general -f Makefile clean: @$(MAKE) -C io_lib -f Makefile clean @$(MAKE) -C math_lib -f Makefile clean @$(MAKE) -C general -f Makefile clean
1. Create a compilation database
First of all, we need to create a JSON compilation database for our test project. The tool we'll use for this is compiledb-generator. Having installed the tool, we can run
compiledb makefrom the project root and get the compile_commands.json file:
2. Install the Makefile Support plugin
3. Open and configure the compilation database in CLion
The next step is to open the compilation database that we created in step 1 as a project in CLion. After the import has finished successfully, we can start working with the project files. To have the project automatically reloaded upon every change in compile_command.json, we need to set the Use auto-import checkbox in :
4. Create a File Watcher for the Makefiles
Now we can create a File Watcher to follow up the changes in the Makefiles. Let's navigate to GNU Makefile type located in the project root and subdirectories (note the, create a new File Watcher and assign it to all the files of
5. Modify the Makefiles
Now, let's change something in our Makefiles. We can do this outside the IDE (since the Trigger the watcher on external changes checkbox is set), or right from the CLion editor.
For example, we can add a new source file to the math_lib module and put it to the list of sources in the corresponding Makefile:
Right after that change, the Makefile_watcher is triggered to run
compiledb -n make. This command regenerates the compilation database without performing the actual build, and CLion automatically reloads it so the project gets synchronized with the modified Makefile.
Now there are four entries in compile_commands.json:
Similarly, if we then decide not to include the io_funcs library into the build, we can remove the
Iotarget from the main Makefile:In response to this change, the Makefile_watcher triggers again, and the compilation database gets reloaded accordingly:
TARGETS = Math General
6. Make the File Watcher global
The final thing that we might want to do is make the Makefile_watcher global. With this setting enabled, the watcher becomes available across all projects so we'll easily reuse it for other Makefile applications that we manage in CLion:
This way, the combination of a File Watcher and a compilation database creates a mechanism to work with Make-based projects without leaving CLion to edit the Makefiles or recreate the compilation database manually. Moreover, you can apply this approach to any build system that has complementary tools for generating compilation databases.
Note that currently, in this scheme, CLion reloads the entire compilation database for each change in the Makefile that triggers the File Watcher. Due to that, you may experience performance problems when applying this workflow to large code bases.