IntelliJ IDEA 2020.1 Help

Scopes and file colors

A scope the Scope icon is a group of files, packages, and folders in a project. You can use scopes to visually distinguish project items in different IDE views and to limit the range of specific operations.

Scopes are designed to logically organize files in your project: test sources can go to the test-related scope, and production code can be associated with the scope of production files. These logical chunks make your project easier to manage. For example, running test-related inspections only in test classes takes less than if you run them in all files in your application.

IntelliJ IDEA comes with a set of predefined scopes, but you can also create custom scopes. There, you can include any files and folders. For example, a custom scope can include only those files in the project for which you are responsible.

In IntelliJ IDEA, scopes are used in code inspections, some refactorings, search, in copyright settings, in various features for code analysis, and so on.

There are 2 types of scopes: local and shared.

  • Local scopes are stored in the IDE configuration directory, that is why they are not shared through VCS and are not available to other members of your team.

  • Shared scopes are added to a VCS so that people who work on a project can use the same scopes. These scopes are stored together with the project in the scopes folder under .idea. Each scope is saved as a file with the .xml extension (for example: MyProject/.idea/scopes/shared-scope.xml).

Using shared scopes makes sense if your project is under version control. If you don't use a VCS, local scopes will be sufficient to cover your needs.

Define a new scope

In IntelliJ IDEA, there's a set of predefined scopes, but you can also define your own scopes.

  1. In the Settings/Preferences dialog Ctrl+Alt+S, select Appearance & Behavior | Scopes.

  2. Click the Add Scope button and select what kind of scope you want to define: local or shared.

    You can change the state of the selected scope (local or shared) later using the Share through VCS checkbox.

    Creating a new scope: selecting between a shared and a local scope
  3. In the dialog that opens, name the new scope and click OK.

  4. Add files to the new scope. Select the necessary items in the project tree and click one of the options located on the right from the tree:

    • Include: include the selected items. If you are including a folder, this action adds only the files located inside this folder. All nested subfolders and their contents will not be included.

    • Include Recursively: include the selected folder together with the nested subfolders and their contents.

    • Exclude: exclude the selected items from the scope. If you are excluding a folder, this action removes only the files located inside this folder. All nested subfolders and their contents will remain in the scope.

    • Exclude Recursively: exclude the selected folder together with the nested subfolders and their contents.

    A new scope with added files and folders

    As you add files to the scope, IntelliJ IDEA creates an expression and displays it in the Pattern field. Instead of using the buttons, you can also type a pattern in the Pattern field manually using the scope language syntax reference.

  5. Apply the changes and close the dialog.

When you add items to the scope, their names change the color accordingly:

  • the green color sample Green: folders and files included in the scope.

  • the dark blue color sample Blue: folders that contain both excluded and included files and folders.

  • the black color sample Black: files and folders whose names are written in black are excluded from the scope.

After you create a custom scope, you can find it in the Project tool window> and in all dialogs that allow you to limit the number of files to which you want to apply an action.

The new scope shown in the Project tool window

Predefined scopes

IntelliJ IDEA provides a set of predefined scopes. The IDE adds files to these scopes automatically based on in the information about them. Note that these scopes cannot be modified.

List of predefined scopes

  • Project Files: includes all files within the project content roots. For more information, refer to Content roots. Libraries and SDKs are not included in this scope.

  • Problems: includes files within the project content roots with syntax errors.

  • Scratches and Consoles: includes all files from the Scratches and Consoles directory located in the Project tool window.

  • Recently Viewed Files and Recently Changed Files: includes the last 50 files that you have opened or modified in the editor. You can change the number of recent files in the Editor | General | Limits page of the Settings/Preferences Ctrl+Alt+S.

  • Project and Libraries: includes all files within the project content roots and also all module dependencies (libraries and SDKs).

  • Project Production Files: includes all files within the project content roots except test sources roots. In the Project tool window, this scope corresponds to the Production view.

  • Project Test Files: includes files from test sources roots. In the Project tool window, this scope corresponds to the Tests view.

  • Non-Project Files: this scope is available only as a view in the Project tool window. It includes libraries and SDKs.

  • Open Files: includes the files that are currently opened in the editor.

  • Current File: corresponds to the file that is currently active in the editor.

  • Selected Files: includes the selected files that are selected in a tool window (for example, in the Project tool window).

  • Favorite 'name': corresponds to the list of favorite items with the specified name. This scope becomes available only after you configure at least one list with favorite items.

  • Class Hierarchy: includes classes that are interconnected with the selected class. After you select this scope, you will be prompted to pick the base class of the hierarchy.

  • Local Changes (These scopes appear if VCS integration is enabled)

    • All Changed Files: includes the modified files with changes that are not yet added to VCS from all changelists.

    • Default Changelist: includes the modified files with changes that are not yet added to VCS from the Default changelist.

    • 'Changelist name': includes the modified files with changes that are not yet added to VCS from a specific custom changelist.

  • Data Sources

    • Context Data Sources: includes the data source you are working with at the moment. The context can be defined either from the console you are working with, the data editor, or by selecting it in the database explorer.

    • Connected Data Sources: includes the data sources that have an active connection.

    • All Data Sources: includes all added data sources.

Associate scopes with colors

Files that belong to different scopes can be highlighted in different colors in search results, in editor tabs, and in the Project tool window.

Scope highlighting in the editor tabs and search results

To each scope, you can assign its own color. For example, you can assign a color to the Open Files scope and configure the IDE to show this color in the Project tool window. In this case, the files that you are currently working with in the editor will be colored in the project tree. This makes project navigation faster and simpler. Note that file colors work only in association with scopes.

Similarly to scopes, color associations can be local and shared.

  • Local colors are only visible to you and are not shared through VCS.

  • Shared colors are placed under version control so that people who work on a project can use the same color associations. They are stored in the project folder under .idea in the fileColors.xml file (for example: MyProject/.idea/fileColors.xml).

Create a new color association

  1. In the Settings/Preferences dialog Ctrl+Alt+S, select Appearance & Behavior | File Colors.

  2. Make sure that the Enable File Colors checkbox is selected, and then choose where you want to use the colors: select Use in Editor Tabs or Use in Project View.

    If you select the Use in Project View checkbox, you will see colors in the Project tool window and in search results (for example, in the Find in Path dialog Ctrl+Shift+F).

  3. Choose whether you want to configure local or shared colors and click Add icon in the corresponding section of the dialog.

    You can always share local color associations and vice versa, make shared colors local, using the the Share button (Share) and the Unshare button (Unshare) buttons.

  4. In the Add Color Label dialog, select a scope and pick a color for it. Click OK.

    Creating a new color association
  5. Apply changes and close the dialog.

If a file is included in several scopes, the order of the scopes becomes important: IntelliJ IDEA processes the scopes from the top to the bottom starting from local scopes. It means that the IDE will apply the color of the last scope in the list to such a file.

You can change the order of the scopes if you want IntelliJ IDEA to process color associations in a different order.

Change the order of scopes

  1. In the Settings/Preferences dialog Ctrl+Alt+S, select Appearance & Behavior | Scopes.

  2. Select the scope that you want to move and click the Move Up button (Alt+Up) or the Move Down button (Alt+Down).

  3. Apply the changes and close the dialog.

Last modified: 13 May 2020