Analysis Scope

There are often situations 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 allowing you to focus on the issues that really matter. SonarCloud gives you several options for configuring exactly what will be analyzed and how.

Where to configure the settings

The main scoping options can be set in the UI under:

Your Organization > Your Project > Administration > General Settings > Analysis Scope.

Language-specific file suffixes can be set in the UI under:

Your Organization > Your Project > Administration > General Settings > Languages > Your Language.

Many of the settings related to analysis scope use pattern matching to define the paths of files and directories. The patterns are defined using the following wildcards:

  • * - Match zero or more characters
  • ** - Match zero or more directories
  • ? - Match a single character
ExampleMatchesDoes not match
**/*Bean.javaorg/sonar.api/MyBean.java org/sonar/util/MyOtherBean.javaorg/sonar/util/MyDTO.java
**/*Bean?.javaorg/sonar/util/MyOtherBean1.javaorg/sonar/util/MyOtherBean.java org/sonar.api/MyBean.java org/sonar/util/MyDTO.java
org/sonar/*org/sonar/MyClass.java org/sonar/MyOtherClass.javaorg/sonar/util/MyClassUtil.java
org/sonar/**/*org/sonar/MyClass.java org/sonar/MyOtherClass.java

Restrict the scope of analysis (in general)

You can restrict the scope of code analysis to specific subdirectories and files of your project.

To determine the location within the project of source code to be analyzed SonarCloud starts with the analysis parameters sonar.sources and sonar.tests.

sonar.sources

The sonar.sources parameter defines the starting point for SonarCloud to recursively search for (non-test) source code files to analyze. This parameter holds a comma-delimited list of directories (not a path matching pattern) relative to the current working directory.

Other parameters (see below) can be used to further narrow the scope within these initial directories.

For projects that use SonarScanner for Maven, or SonarScanner for .NET , sonar.sources is automatically set to the appropriate value, using metadata from the build framework.

For other projects (both CI-based and automatic analysis setups) the default value of "." (the current working directory) is used. In most cases, this will be equivalent to the root directory of the repository, though in cases where the SonarScanner CLI is used manually, it will be the directory within which the command-line tool is invoked (which would usually be the root of the repository but might not be).

In cases where sonar.sources is not automatically set and therefore defaults to ".", but where your sources are in one or more subdirectories of the root, you should set the parameter to those subdirectories. For example:

sonar.sources = server/src, client/src

sonar.tests

The sonar.tests parameter holds a comma-delimited list of directories (not a path matching pattern) relative to the current working directory. SonarCloud uses the listed directories (actually there is often just one) as the starting point to recursively search for test code files to analyze. Other parameters (see below) can be used to further narrow the scope within these initial directories.

The sonar.tests parameter defines the starting point for SonarCloud to recursively search for test source code files to analyze. This parameter holds a comma-delimited list of directories (not a globbing pattern) relative to the current working directory. Other parameters (see below) can be used to further narrow the scope within these initial directories.

SonarCloud uses the is parameter because it is sometimes useful for the system to distinguish between "normal" source code and source code that implements tests.

For projects that use SonarScanner for MavenSonarScanner for Gradle, or SonarScanner for .NETsonar.tests is automatically set to the appropriate value, using metadata from the build framework.

For other projects (both CI-based and automatic analysis setups) the default value is null, meaning that the system assumes that there is no test code.

In cases where sonar.tests is not automatically set and therefore defaults to null, but where you do have tests (which you should!), you should set the parameter to the test subdirectories. For example:

sonar.tests = server/test, client/test

Exclusions and inclusions

Within the source and test directories specified, you can further narrow down the files to be analyzed by using exclusions and inclusions:

Exclusions and inclusions can be set either in the UI or by key.

In the UI the settings are under:

Your Organization > Your Project > Administration > General Settings > Analysis Scope > Files.

The values of these use path matching patterns. These are interpreted as relative to the current working directory of the scanner (which is usually the root of the directory of the repository)

sonar.exclusions: One or more path matching patterns defining files to be excluded from analysis, among those found below the directories specified in sonar.sources.

sonar.inclusions: One or more path matching patterns defining files to be included in analysis, among those found below directories specified in sonar.sources.

sonar.test.exclusions: One or more path matching patterns defining files to be excluded from analysis, among those found below the directories specified in sonar.tests.

sonar.test.inclusions: One or more path matching patterns defining files to be included in analysis, among those found below directories specified in sonar.tests. Applied after sonar.test.exclusions and therefore overriding it.

When considering your scoping configuration, keep in mind that the vast majority of needs are met simply by setting sonar.sources and sonar.tests correctly (or relying on automatic setting by frameworks). Most other needs are met with the addition of a few simple exclusions. In a few corner cases, it is necessary to be explicit about what's included in analysis and leave out everything else, but that is not the normal case, and setting inclusions should not be the first thing you try when configuring a new project.

Examples

Let's say your repository looks something like this:

/
|- docs/
|  |- ...
|  ...
|
|- src/
|  |- ...
|  ...
|
|- test/
|  |- ...
|  ...
|
...

In this case, your source and test code are clearly separated at the top level. So, your scoping configuration would simply be:

sonar.sources = src
sonar.tests = tests

There is no need for any inclusions or exclusions.

Alternatively, let's say your repository looks more like this:

/
|- docs/
|  |- ...
|  ...
|
|- src/
|  |- foo/
|  |  |- foo.js
|  |  |- test/
|  |     |- foo.test.js
|  |
|  |- bar/
|  |  |- bar.js
|  |  |- test/
|  |     |- bar.test.js
|  ...
...

Here your test code is intermingled with your source code. To deal with this, you would set your scoping parameters to something like this:

# Define the same root directory for sources and tests
sonar.sources = src
sonar.tests = src

# Include test subdirectories in test scope
sonar.test.inclusions = src/**/test/**/*

# Exclude test subdirectories from source scope
sonar.exclusions = src/**/test/**/*

Why source vs test

The separation of "normal" source code and source code that implements tests allows SonarCloud to analyze the two categories of code differently when necessary.

These settings do not have anything to do with setting up test coverage reporting, since that is handled by importing reports from an external tool (see Test Coverage).

The only role that these scoping parameters play with respect to coverage is that an error will be reported if an imported coverage report lists a test file that SonarCloud has not encountered in the directories specified by the test code scoping parameters.

Restrict the scope of coverage detection

You can prevent specific files or directories from being taken into account when code coverage is reported.

By key, set sonar.coverage.exclusions to a comma-delimited list of path matching patterns relative to the current working directory.

In the UI, go to:

Your Organization > Your Project > Administration > General Settings > Analysis Scope > Code Coverage.

Restrict the scope duplication detection

You can prevent specific files or directories from being checked for duplications.

By key, set sonar.cpd.exclusions to a comma-delimited list of path matching patterns relative to the current working directory.

In the UI, go to:

Your Organization > Your Project > Administration > General Settings > Analysis Scope > Duplications.

Restrict the scope by file type

Most languages offer a way to restrict the scope of analysis to files matching a set of extensions. In the UI, go to:

Your Organization > Your Project > Administration > General Settings > Languages > Your Language.

To set by key, see the UI setting for the names of the parameters specific to your language. It is usually of the form sonar.<language>.file.suffixes.

SonarCloud respects .gitignore

SonarCloud automatically excludes from analysis the files listed in your project's .gitignore file. This behavior can be disabled by setting sonar.scm.exclusions.disabled = true in the configuration file or command line.

Restrict the scope by issue

You can have SonarCloud ignore issues on certain components and against certain rules. Go to:

Your Organization > Your Project > Administration > General Settings > Analysis Scope > Issues.

Note that these parameters should only be set through the UI.

Ignore Issues on Files

You can ignore all issues on files that contain a block of code matching a given regular expression.

For example, to ignore all issues in files containing @javax.annotation.Generated you would set this parameter to

@javax\.annotation\.Generated

(Note that since this value is a regular expression, you need to escape the "." characters to use them literally.)

Ignore Issues in Blocks

You can ignore all issues on specific blocks of code, while continuing to scan and mark issues on the remainder of the file. Blocks to be ignored are delimited by start and end strings which can be specified by regular expressions.

Notes:

  • 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 on a multi-line basis.

Ignore Issues on Multiple Criteria

You can ignore issues in certain directories and for certain coding rules.

The rule key matching pattern consists of the rule repository name, followed by a colon, followed by a rule key or rule name fragment (using wildcards`). For example:

  • squid:S1195 matches exactly the rule S1195 in the squid rule repository.
  • squid:*Naming* matches all rule in the squid repository tat include the string Naming.

The file matching pattern follows the same conventions as those used elsewhere in this section.

Examples:

  • Ignore all issues in all files:
    • Rule key pattern: *
    • File path pattern: **/*
  • Ignore all issues in the program bank/ZTR00021.cbl:
    • Rule key pattern: *
    • File path pattern: bank/ZTR00021.cbl
  • Ignore all issues in classes located directly in the Java package com.foo, but not in its sub-packages:
    • Rule key pattern: *
    • File path pattern: com/foo/*
  • Ignore all issues against coding rule cpp:Union in files in the directory object and its sub-directories:
    • Rule key pattern:cpp:Union
    • File path pattern:object/**/*

Restrict Scope of Coding Rules

  • 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
  • Only check the rule "Prevent GO TO statement from transferring control outside current module on COBOL programs" located in the directories "bank/creditcard" and "bank/bankcard"
    • 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/**/* (This restriction requires two criteria)

Effect on Pricing

Paid plans are tiered according to the total number of lines of code (LOC) analyzed in your private repositories. This LOC calculation does not count code in excluded files (nor does it count blank lines or comments).

Only private code that is actually analyzed counts toward the LOC limit. For more details, see Pricing.


© 2008-2022, SonarCloud by SonarSource SA. All rights reserved.