Analysis Scope

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

Initial Scope

The initial scope of analysis, sometimes known as Narrowing the Focus, is controlled by the parameters sonar.sources, and sonar.tests.

  • sonar.sources defines the initial scope of analysis for non-test code.
  • sonar.tests defines the initial scope of analysis for test code.

These parameters define the starting point for analysis scope adjustment.

  • Files outside the scope defined by these parameters will not be analyzed.
  • Files within the scope defined by these parameters will be analyzed unless excluded by further adjustments (exclusions, inclusions, etc. See below.)

Why is test code scoped separately?

Test and non-test code are distinguished because different analysis rules are applied to each category; the two categories have different metrics.

Additionally, test code does not counts toward your lines of code (LOC) usage in paid SonarCloud accounts and does not count toward coverage (you don’t have to test your test code).

Automatic setting for Maven, Gradle and .NET

If you are analyzing code using SonarScanner for Maven, SonarScanner for Gradle or SonarScanner for .NET then sonar.sources and sonar.tests are set automatically based on your project configuration. Using the parameters explicitly will override these defaults (for example, in your pom.xml, in the case of Maven).

Defaults settings for other scenarios

In cases other than Maven, Gradle or .NET (including both CI-based analysis and automatic analysis):

  • By default, sonar.sources is set to the current working directory (ie: the path .).
  • sonar.tests defaults to null, meaning there is assumed to be no test code.

No UI settings

The parameters sonar.sources and sonar.tests are only settable by key in configuration files or on the command line, not in the SonarCloud UI.

Explicit settings

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. Wildcard patterns 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 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 it is, by default, the current directory in which you invoke the tool (though this can be overridden using the parameter sonar.projectBaseDir).

Example

Let's say your repository looks something like this, with your source and test code clearly separated at the top level. 

Source code and test code are separated at the project root.

In this case, you would set your sonar.sources like this:

Source code is in the src/ directory.

and your sonar.tests like this:

Test code is in the test/ directory.

If you configure your scoping in the sonar-project.properties file, it would look like this:

# Define separate root directories for sources and tests
sonar.sources = src/
sonar.tests = test/

There is no need for more fine-tuning.

Wildcard patterns

Although the sonar.sources and sonar.tests parameters take simple paths, many of the settings related to analysis scope accept wildcard patterns to define the paths of files and directories.

To match any folder/directory plus the file extension with any prefix before it, use the following wildcards:

  • * - Match zero or more characters (not including the directory delimiter, /).
  • ** - Match zero or more directory segments within the path.
  • ? - Match a single character (not including the directory delimiter, /).
ExampleMatches
**/*.js, or **/*.cssMatches: anyDirectory/anyFile.js or anyDirectory/anyFile.css
**/*Bean.java

Matches: org/sonar.api/MyBean.java``org/sonar/util/MyOtherBean.java

Doesn't match: org/sonar/util/MyDTO.java

**/*Bean?.java

Matches: org/sonar/util/MyOtherBean1.java

Doesn't match: org/sonar/util/MyOtherBean.java``org/sonar.api/MyBean.java``org/sonar/util/MyDTO.java

org/sonar/*

Matches: org/sonar/MyClass.java``org/sonar/MyOtherClass.java

Doesn't match: org/sonar/util/MyClassUtil.java

org/sonar/**/*

Matches: org/sonar/MyClass.java``org/sonar/util/MyOtherClass.java

Doesn't match: org/radar/MyClass.java

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. This refinement is sometimes referred to as narrowing the focus.

Currently, test file exclusions and inclusions are assigned in the UI at the project level; assignment at the global level is not possible. 

Project level

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

  • 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 key sonar.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 key sonar.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 key sonar.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 key sonar.test.inclusions.

To set these parameters by key you can:

  • Set them in the configuration file <sonarcloud-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

Let's say your repository looks something like this, with your test code intermingled with your source code. 

A complex example of a project root with intermingled source and test code.

You would define your sonar.sources like this, taking in the whole src directory:

directory-sonar-sources.png
Define `sonar.sources` as the entire src/ directory.

then set Source File Exclusions (key sonar.exclusions) to src/**/test/**/*

The result is that the set of source files to be scanned is everything under src minus every test subdirectory:

Use wildcards to exclude the src/**/test/**/* directories from your scan.

To define the test files, first set sonar.tests to the whole src directory:

Set `sonar.tests` as the entire src/ directory.

then set Test File Inclusions (key sonar.test.inclusions) to src/**/test/**/*

The result is that the set of source files to be scanned is everything under src minus everything that is not a test subdirectory:

Use wildcards to include the src/**/test/**/* directories in your scan.

If you configure your scope in the sonar-project.properties file, it would look 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/**/*

Naming of parameters

Note that the initial scoping parameter for test code is sonar.tests (that is tests with an s!) while the exclusion and inclusion parameters for test code are sonar.test.exclusions and sonar.test.inclusions (that is test, without an s!).

Relationship with test coverage reporting

The test scope parameters (source.tests , sonar.test.exclusion, and sonar.test.inclusion) do not have anything to do with setting up test coverage reporting (see Test Coverage).

However, SonarCloud 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).

Refined scope settings

The initial scope settings and their associated exclusion and inclusion parameters define the set of files that will be analyzed by SonarCloud. The settings described below allow you to refine the analysis in different ways.

Setting scope by file type

Your Organization > Your Project > Administration - General Settings > 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. You can add or remove suffixes as required from the UI.

When setting by key, use the appropriate language suffix as a parameter in this form:  sonar.<language>.file.suffixes.

Scope of code coverage exclusions

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

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.

Scope of duplication detection

Your Organization > Your ProjectAdministration - General Settings > Analysis Scope > Duplications

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.

Ignoring issues

Ignoring files based on content

Your Organization > Your Project > Administration - General Settings > Analysis Scope > Issues > Ignore Issues on Files.

You can ignore files that contain a block of code matching a given regular expression. All issues (bugs, code smells, and vulnerabilities) as well as security hotspots will be ignored within those files. 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:

@Generated(“com.example.generated”)
public class GeneratedClass extends AnotherCLass {
   // Some generated code
}

To exclude all such files, you might set this parameter to:

@Generated\(".*"\)

Note that since this value is a regular expression, you need to escape the ( and ) parentheses characters and use the expression .* to 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

Your Organization > Your Project > Administration - General Settings > Analysis Scope > Issues > Ignore Issues in Blocks

As a project Administrator, 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 with regular expressions. All issues (bugs, code smells, and vulnerabilities) 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 paired 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:

Public class MyCLass {
   Public MyClass() {
      ...
   }

   Public void doSomething() {
      ...
   }

   // BEGIN-NOSCAN
   Public void doSomethingElse()
   {
      ...
   }
   // END-NOSCAN    
}

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.

Ignoring specific rules from specific files

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.

In the UI, go to Your Organization > Your Project > Administration - General Settings > Analysis Scope > Issues > Ignore Issues on Multiple Criteria.

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 pattern.

For example:

  • java:S3776 matches exactly the rule S3776 in the java rule repository.
  • java:*Naming* matches all rules in the java repository that include the string Naming in their rule name.

You can find the fully qualified rule ID in the top right corner of the rule definition and the rule name in the top left of 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 same format described above to describe a set of directories or files.

Examples

  • Ignore all issues in all files:
    • Rule key pattern: *
    • File path pattern: **/*
  • Ignore all issues in the file bank/ZTR00021.cbl:
    • Rule key pattern: *
    • File path pattern: bank/ZTR00021.cbl
  • 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/*
  • Ignore all issues against the coding rule cpp:Union in files in the directory object and its sub-directories:
    • Rule key pattern: cpp:Union
    • File path pattern: object/**/*

Restrict specific rules to specific files

Rule key and file path patterns can also allow you to further restrict the analysis scope by setting specific rules to specific files.

Your Organization > Your Project > Administration - General Settings > Analysis Scope > Issues > Restrict Scope of Coding Rules.

The mechanics of setting this 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.

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
  • Only check the rule Prevent GO TO statement from transferring control outside current module on COBOL programs in the directories bank/creditcard and bank/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/**/*

SonarCloud respects .gitignore

Your SonarCloud analysis will automatically exclude 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.

Note that while SonarCloud does understand standard .gitignore directives, it does not understand .gitignore negation patterns. These are patterns preceded by an !. We recommend not using them in SonarCloud projects.

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.