Excluding files from analysis based on path-matching patterns at the global level

As a system administrator, you can adjust the initial analysis scope at the global level by excluding files based on path-matching patterns. To exclude files, you define file exclusion parameters based on directory and file name patterns. This analysis scope adjustment applies to all projects in your instance. However, they can be overridden at the project level in the UI or through analysis parameters set on the CI/CD host.

Example of an initial scope adjustment

We consider the following repository example where test files are contained in both test/ directories. Source and test code files are contained in the same ancestor directory: src/ which is chosen as the initial analysis scope for both source and test code. Therefore, a scope adjustment is necessary.

We adjust the initial scope as follows:

• For source files: by defining an exclusion parameter with the pattern src/**/test/**/*

• For test files: by defining an inclusion parameter with the pattern src/**/test/**/*

Principles governing the use of file exclusion parameters

A global file exclusion parameter:

• Applies either to source code (also called main code) or to test code files.
  The Sonar Scanner must identify the source code as well as the test code since they are processed differently by SonarQube. A code file is either a source or a test code, it cannot be both (If this is the case, the scanner will fail the analysis with an error message.).
• Contains:
  • Either exclusion patterns: to define files to be excluded from the analysis scope.
  • Or inclusion patterns: to define files to be included in the scope.
    It means that the rest of the files is excluded from the analysis scope.
• Applies at one of the following levels:
  • Forced global (only for exclusion patterns): The parameter applies to all projects and cannot be overridden by any other setting.  
  • Global: The parameter applies to all projects but can be overridden by the corresponding project-level parameter.

For a given code category (source or test), we strongly recommend that you use either exclusion-pattern or inclusion-pattern parameters, depending on what is simpler in your situation (If you do not and there is an overlapping, then exclusion patterns have precedence over inclusion patterns.). 

The following applies:

• The parameter defined at the project level will override the same parameter defined at the global level.
  For example, if you define at the global level the exclusion pattern for source code src/**/test1/**/*, then, if the project administrator sets the exclusion pattern for source code src/**/test2/**/* for their project, the scanner will consider only the pattern src/**/test2/**/* to compute source file exclusion.
• If you define Forced global exclusion patterns then the scanner will consider them in addition to the "regular" exclusion patterns.
  For example, if you define the global forced exclusion pattern for source code src/**/test3/**/* and the project administrator sets at project level the exclusion pattern for source code src/**/test4/**/*, then the scanner will consider both patterns src/**/test3/**/* and src/**/test4/**/* to compute the source file exclusion.
• If test file inclusion patterns are used, the scanner will automatically set these patterns as source file exclusion patterns during project analysis. These souce file exclusion patterns will apply in addition to the other configured source file exclusion patterns.
  For example:
  • If the exclusion pattern for source code is src/**/test5/**/* and the inclusion pattern for test code is src/**/test6/**/*
  • Then the scanner will consider both patterns to compute the source file exclusion:
    src/**/test5/**/* and src/**/test6/**/*

Defining a file exclusion parameter

1. Go to Administration > Configuration > General Settings > Analysis Scope.
2. In A. File Exclusions, choose the parameter to configure (source or test code; exclusion or inclusion patterns; forced global (indicated by the Global prefix) or not), and enter and save the first pattern. See Defining path-matching patterns.
3. Add additional patterns to the parameter if necessary.
4. Define other parameters if necessary. Make sure you use either  (Global) Source File Exclusions or Source File Inclusions, and either (Global) Test File Exclusions or Test File Inclusions.

Global Source File Exclusions and Global Test File Exclusions are forced global parameters. A forced global parameter applies to all projects and cannot be overridden by any other setting. 

Related pages

• Excluding specific files from code coverage or duplication check at the global level
• Using advanced exclusion features at the global level
• Setting the analysis scope of your project