Analysis scope
On this page
There are many cases where you do not want to analyze every aspect of every source file in your project. For example, your project may contain generated code, source code from libraries, or intentionally duplicated code.
In such cases, it makes sense to skip some or all aspects of analysis for these files, thus removing noise and narrowing the focus to issues that really matter.
To help narrow the focus, SonarQube Community Build gives you several options to precisely configure what will be analyzed and how. Most of the properties that define your analysis scope can be defined in the SonarQube Community Build UI. Other parameters must be set explicitly in the scanner invocation or in the appropriate configuration file as we describe in more detail below; see the Analysis parameters page for more detail.
Setting the initial scope
The initial scope of analysis is controlled by the following parameters:
sonar.sources
define the initial scope of analysis for non-test code in your project.sonar.tests
define the initial scope of analysis for test code in your project.
These parameters define the starting point for analysis scope adjustment:
- Files outside the scope defined by these parameters will not be analyzed at all.
- Files within the scope defined by these parameters will be analyzed unless excluded by further adjustments (exclusions, inclusions, etc. See below.)
Additionally, these parameters are:
- only set at the project level. There are no global, server-level equivalents for these parameters.
- either set automatically by your SonarScanner, set explicitly in the
sonar-project.properties
configuration file, or set on the command line that invokes the scanner. There are no UI settings for these parameters. - set explicitly and both accept a comma-delimited list of paths. Pattern matching with wildcards is not supported.
Why is test code scoped separately?
Test and non-test code are distinguished because
- Different analysis rules are applied to the two categories.
- The two categories have different metrics
- Test code does not count toward lines-of-code limits defined by your license.
- Test code does not count towards coverage (you don't have to test your test code)
Automatic setting for Maven, Gradle, and .NET
If you are analyzing code using the SonarScanner for Maven, the sonar.sources
and sonar.tests
parameters are automatically determined based on information in your project configuration. You do not have to explicitly set the parameters.
If you do explicitly set the parameters, for example in your pom.xml file, they will override the automatically determined values.
See also the Adjusting the analysis scope article on the SonarScanner for Maven page.
If you are analyzing code using the SonarScanner for Gradle, the sonar.sources
and sonar.tests
parameters are automatically determined based on information in your project configuration. You do not have to explicitly set the parameters.
If you do explicitly set the parameters, for example in your gradle.properties file, they will override the automatically determined values.
See also the Adjusting the analysis scope article on the SonarScanner for Gradle page.
The sonar.sources
and sonar.tests
parameters are not compatible with the SonarScanner for .NET. They are automatically detected and cannot be changed.
If you are analyzing code using the SonarScanner for .NET v8.0.1 or earlier, the sonar.sources
and sonar.tests
parameters are automatically determined based on information in your project configuration. The SonarScanner for .NET does not support user-defined values for sonar.sources
and sonar.tests
.
Please see the Configuring the SonarScanner for .NET page for information about limiting your analysis scope.
Default settings for other scenarios
If you are not using Maven, Gradle or .NET then
- By default,
sonar.sources
is set to the current working directory (the path.
). - By default,
sonar.tests
is not set.
Explicit settings
If the defaults are not suitable (for example, if you do have test code) you must set the parameters explicitly in the scanner invocation or in the appropriate configuration file (see Analysis parameters).
When explicitly set, both sonar.sources
and sonar.tests
take a comma-delimited list of directories or files.
- The entries in the list are simple paths. Wildcards (
*
,**
, and?
) are not allowed. - A directory in the list means that all analyzable files and directories recursively below it are included. An individual file in the list means that the file is included.
- The paths are interpreted relative to the project base directory. The base directory is defined by the scanner you are using. In most cases, this is the root directory of the project. If you are using the SonarScanner CLI, your base directory will be the current directory from which you invoke the tool (though this can be overridden using the parameter
sonar.projectBaseDir
).
Example 1
Let's say your repository looks something like this, with your source and test code clearly separated at the top level:
In this case, you would set your sonar.sources
like this:
and your sonar.tests
like this:
If you configure your scope in the sonar-project.properties
file, it would look like this:
There is no need for any further fine-tuning.
Wildcard patterns
Most of the parameters discussed below, such as exclusion and inclusion-related parameters, use path-matching patterns (sometimes known as simple wildcard patterns).
The recognized path-matching patterns are case-sensitive and defined using the following wildcards:
*
Match zero or more characters (not including the directory delimiter,/
).**
Match zero or more directory segments or files within the path.?
Match a single character (not including the directory delimiter,/
).
Wildcard examples
- The pattern
**/*.css
- matches
anyDirectory/anyFile.css
- doesn't match
org/sonar.api/MyBean.java
- matches
- The pattern
**/*Bean.java
- matches
org/sonar.api/MyBean.java
- doesn't match
org/sonar.api/mybean.java
ororg/sonar/util/MyDTO.java
- matches
- The pattern
**/*Bean?.java
- matches
org/sonar/util/MyOtherBean1.java
- doesn't match
org/sonar/util/MyOtherBean.java
- matches
- The pattern
org/sonar/*
- matches
org/sonar/MyClass.java
- doesn't match
org/sonar/util/MyClassUtil.java
- matches
- The pattern
org/sonar/**/*
is equivalent toorg/sonar/**
and- matches
org/sonar/anyDirectory/anyFile
- matches
org/sonar/MyClass.java
- doesn't match
org/radar/MyClass.java
- matches
Note that the sonar.sources
and sonar.tests
parameters take simple paths and cannot use wildcard patterns.
SonarQube (Server,Cloud) support simple wildcard patterns and do not support glob patterns.
Location of UI settings
Unless otherwise noted, all the parameters below are settable at both the global and project level. The UI locations for the settings are found under:
- Administration > Configuration > General Settings (for global settings)
- Project Settings > General Settings (for project-level settings)
Any setting made at the global level will apply to all projects unless overridden at the project level (the only exceptions are the global exclusion parameters discussed above).
File exclusion and inclusion
If the directory structure of your project does not cleanly separate source code from test code at the top level, you may have to adjust the scope using exclusions and inclusions.
Inclusions and exclusions should not be part of the initial analysis configuration. We recommend setting them only to solve issues. For example, when you notice that an analysis picked up files that you did not want analyzed.
These are set in the UI for both global and project levels, as follows:
Global level
Administration > Configuration > General Settings > Analysis Scope > A. File Exclusions
- Global Source File Exclusions: One or more wildcard patterns defining which files are filtered out from those defined by
sonar.sources
. This setting will apply to all projects on your SonarQube Community Build. It cannot be overridden by any project-level source file exclusion. It also cannot be set as a key in a configuration file. If it is set, it must be set in the UI. - Source File Exclusions: The same as the global version above except that it can be overridden by a project-level source file exclusion. It cannot be set as a key in a configuration file. If it is set, it must be set in the UI.
- Global Test File Exclusions: Same as the Global Source File Exclusions, above, except that it applies to test files.
- Source File Inclusions: One or more wildcard patterns defining which files to retain, while filtering out all others, from those defined by
sonar.sources
. This applies to all projects on your SonarQube Community Build, though it can be overridden at the project level. It cannot be set as a key in a configuration file. If it is set, it must be set in the UI. - Test File Exclusions: Same as the Source File Exclusions, above, except that it applies to test files.
- Test File Inclusions: Same as the Source File Inclusions, above, except that it applies to test files.
Project level
Project Settings > General Settings > Analysis Scope > A. File Exclusions
- Source File Exclusions: One or more wildcard patterns defining which files are filtered out from those defined by
sonar.sources
. This can also be set in a configuration file using the keysonar.exclusions
. - Source File Inclusions: One or more wildcard patterns defining which files to retain, while filtering out all others, from those defined by
sonar.sources
. This can also be set in a configuration file using the keysonar.inclusions
. - Test File Exclusions: One or more wildcard patterns defining which files are filtered out from those defined by
sonar.tests
. This can also be set in a configuration file with the keysonar.test.exclusions
. - Test File Inclusions: One or more wildcard patterns defining which files to retain, while filtering out all others, from those defined by
sonar.tests
. This can also be set in a configuration file using the keysonar.test.inclusions
.
To set these parameters by key you can:
- Set them in the configuration file
<YOUR_PROJECT>/sonar-project.properties
. - Set them on the command line when invoking the scanner.
- In the case of Maven, Gradle, or .NET projects, set them in the appropriate framework-specific configuration file.
How the parameter values are interpreted
The wildcard patterns are interpreted relative to the project base directory.
Exclusions and inclusions apply on top of the sonar.sources
and sonar.tests
settings. Both the exclusion and inclusion parameters act as filters. They only ever reduce the number of files in the analyzable set, they never add to the set.
Example 2
Let's say your repository looks something like this, with your test code intermingled with your source code:
You would define your sonar.sources
like this, taking in the whole src
directory:
and then set Source File Exclusions (key sonar.exclusions
) to
The result is that the set of source files to be scanned is everything under src
minus every test
subdirectory:
To define the test files, first set sonar.tests
to the whole src
directory:
and then set Test File Inclusions (key sonar.test.inclusions
) to
The result is that the set of source files to be scanned is everything under src
minus everything that is not a test
subdirectory:
If you configure your scope in the sonar-project.properties
file, it would look like this:
Naming of parameters
Note that the initial scoping parameter for test code is sonar.tests
(that's tests
with an s
!) while the exclusion and inclusion parameters for test code are sonar.test.exclusions
and sonar.test.inclusions
(that's test
, without an s
!).
Relationship with test coverage reporting
The test scoping parameters ( sonar.tests
, sonar.test.exclusion
, and sonar.test.inclusion
) do not have anything to do with setting up test coverage reporting (see Test coverage). However, SonarQube Community Build will report an error if an imported coverage report lists a test file not encountered in the directories specified by the scoping parameters.
The parameter sonar.coverage.exclusions
, on the other hand, is directly related to test coverage reporting (see below).
Code coverage exclusion
Analysis Scope > B. Code Coverage Exclusions
This setting lets you exclude specific files or directories from code coverage reporting. The value of the parameter is a comma-delimited list of path-matching patterns relative to the current working directory.
When setting by key, use sonar.coverage.exclusions
Duplication exclusions
Analysis Scope > C. Duplication Exclusions
This setting lets you exclude specific files or directories from duplication checking. The value is a comma-delimited list of path-matching patterns relative to the current working directory.
When setting by key, use sonar.cpd.exclusions
Setting the scope by file type
Languages > Your Language
Most languages offer a way to restrict the scope of analysis to files matching a set of extensions. You can specify one or more suffixes (file extensions) for each language. For example, for the C language, .c
and .h
are set by default.
When setting by key, use the appropriate parameter of the form sonar.<LANGUAGE>.file.suffixes
.
Setting the secret detection scope
By default, SonarQube Community Build detects exposed secrets in all files processed by the language analyzers. You can refine the scope of the secret detection: see Adjusting the secret detection scope.
Ignoring issues in files based on content
Analysis Scope > D. Issue Exclusions > Ignore Issues on Files
You can ignore files that contain a block of code matching a given regular expression. All issues as well as security hotspots, will be ignored within those files. In this setting, you can enter one or more regular expression patterns. Any file containing at least one of the specified patterns will be ignored.
For example, let's say you have generated class files in your Java project that you wish to exclude. The files look something like this:
To exclude all such files, you might set this parameter to:
Note that since this value is a regular expression, you need to escape the (
and )
parentheses characters and use the expression .*
match the string in between those parentheses.
The key for this parameter is sonar.issue.ignore.allfile
, however, because it is a multi-value property, we recommend that it only be set through the UI.
Ignoring blocks within files
Analysis Scope > D. Issue Exclusions > Ignore Issues on Blocks
You can ignore specific blocks of code within a file while continuing to scan the remainder of the file. Blocks to be ignored are delimited within the file by start and end strings. You specify these start and end strings by regular expressions. All issues as well as security hotspots within those blocks, will be ignored. You can enter one or more pairs of regular expression patterns. Any code in any file that lies between the start pattern and its corresponding end pattern will be ignored. Note that:
- If the first regular expression is found but not the second one, the end of the file is considered to be the end of the block.
- Regular expressions are not matched across multiple lines.
For example, let's say you want to ignore the code in the method doSomethingElse
using block delimiters, like this:
You could specify the following regular expressions:
Start of block: \s*//\s*START-NOSCAN
End of block: \s*//\s*END-NOSCAN
These regular expressions ensure that the start and end block delimiters will be recognized regardless of the number of spaces around the line comment characters (//
).
The key for this parameter is sonar.issue.ignore.block
. However, because it is a multi-value property, we recommend that it only be set through the UI.
Excluding specific rules from specific files
Analysis Scope > D. Issue Exclusions > Ignore Issues on Multiple Criteria
You can prevent specific rules from being applied to specific files by combining one or more pairs of strings consisting of a rule key pattern and a file path pattern.
The key for this parameter is sonar.issue.ignore.multicriteria,
however, because it is a multi-value property, we recommend that only be set through the UI.
Rule key pattern
A rule key pattern consists of a rule repository name, followed by a colon, followed by a rule key, or a rule name globbing pattern.
For example:
java:S1195
matches exactly the rule S1195 in the Java rule repository.java:*Naming*
matches all rules in the Java repository that include the stringNaming
in their rule name.
You can find the fully qualified rule ID of the rule definition and the rule name in the rule definition.
For example, for this rule:
- Rule ID:
css:S4655
- Rule name: "!important" should not be used on "keyframes"
File path pattern
A file path pattern uses the path-matching format described above to specify a set of directories or files.
File path pattern examples
- Ignore all issues in all files:
- Rule key pattern:
*
- File path pattern:
**/*
- Rule key pattern:
- Ignore all issues in the file
bank/ZTR00021.cbl
:- Rule key pattern:
*
- File path pattern:
bank/ZTR00021.cbl
- Rule key pattern:
- Ignore all issues in files located directly in the Java package
com.foo
, but not in its sub-packages:- Rule key pattern:
*
- File path pattern:
com/foo/*
- Rule key pattern:
- Ignore all issues against the coding rule
cpp:Union
in files in the directoryobject
and its sub-directories:- Rule key pattern:
cpp:Union
- File path pattern:
object/**/*
- Rule key pattern:
Applying specific rules to specific files
You can only apply specific rules to specific files.
- Global level: Administration > Configuration > General Settings > Analysis Scope > D. Issue Exclusions > Restrict Scope of Coding Rules
- Project level: Project Settings > General Settings > Analysis Scope > D. Issue Exclusions > Restrict Scope of Coding Rules
The mechanics of setting these parameters are the same as for sonar.issue.ignore.multicriteria
, above: Each entry consists of a rule key pattern and a file path pattern. The difference is that in this case, it means that the specified rule will only be applied to the specified set of files.
The key for this parameter is sonar.issue.enforce.multicriteria
. However, because it is a multi-value property, we recommend that it should only be set through the UI.
Multi-value pattern examples
- Only check the rule "Magic Number" on "Bean" objects and not on anything else:
- Rule key pattern:
checkstyle:com.puppycrawl.tools.checkstyle.checks.coding.MagicNumberCheck
- File path pattern:
**/*Bean.java
- Rule key pattern:
- Only check against the rule Prevent GO TO statement from transferring control outside current module on COBOL programs in the directories
bank/creditcard
andbank/bankcard
(this restriction requires two criteria):- Rule key pattern 1:
cobol:COBOL.GotoTransferControlOutsideCurrentModuleCheck
- File path pattern 1:
bank/creditcard/**/*
- Rule key pattern 2:
cobol:COBOL.GotoTransferControlOutsideCurrentModuleCheck
- File path pattern 2:
bank/bankcard/**/*
- Rule key pattern 1:
SonarQube Server respects ignored files
Your SonarQube Community Build analysis will automatically exclude files that are ignored by your source code control system. For example, in git repositories, it respects the .gitignore
file. SonarQube Community Build also respects the ignore directives used in SVN repositories.
This behavior can be disabled by setting sonar.scm.exclusions.disabled = true
in the configuration file or command line.
Note that while SonarQube Community Build understands standard .gitignore
directives, it does not understand .gitignore
negation patterns. These are the patterns preceded by an exclamation mark(!
). We recommend not using them in SonarQube Community Build projects.
Was this page helpful?