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, SonarQube Cloud 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 SonarQube Cloud accounts and does not count toward coverage (you don’t have to test your test code).

Automatic setting for Maven, Gradle and .NET

Default 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 SonarQube Cloud 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 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:

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

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
• The pattern  **/*Bean.java
  • matches  org/sonar.api/MyBean.java
  • doesn't match org/sonar.api/mybean.java or org/sonar/util/MyDTO.java
• The pattern  **/*Bean?.java
  • matches  org/sonar/util/MyOtherBean1.java
  • doesn't match  org/sonar/util/MyOtherBean.java
• The pattern  org/sonar/*
  • matches  org/sonar/MyClass.java
  • doesn't match  org/sonar/util/MyClassUtil.java
• The pattern  org/sonar/**/* is equivalent to org/sonar/** and
  • matches  org/sonar/anyDirectory/anyFile
  • matches org/sonar/MyClass.java
  • doesn't match  org/radar/MyClass.java

Note that the sonar.sources and sonar.tests parameters take simple paths and cannot use wildcard patterns.

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.

Organization level

As an organization admin, you can define in the UI an analysis scope adjustment at the organization level provided your organization is assigned the Enteprise plan. See Adjusting the analysis scope at the organization level. This setting is overridden by the project-level setting.

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.

If the adjustment is defined at the organization-level in your Enterprise plan organization, you can reset the setting to the organization's default by selecting Reset to default.

To set these parameters by key you can:

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

src/**/test/**/*

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

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:

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 (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 Cloud 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 SonarQube Cloud. 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.

Secret detection scope

By default, SonarQube Cloud 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.

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 Project > Administration > 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.

See also the Metric definitions page for more information about duplications. 

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() {
      ...
   }

   // START-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.

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

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
• Only check against 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/**/*

SonarQube Cloud respects .gitignore

Your SonarQube Cloud 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 SonarQube Cloud does understand standard .gitignore directives, it does not understand .gitignore negation patterns. These are patterns preceded by an !. We recommend not using them in SonarQube Cloud projects.

Effect on Pricing

Paid and Enterprise 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 code from private projects that is actually analyzed counts toward the LOC limit determined by your subscription plan.  Effectively, you cannot use up your LOC limit by analyzing the same code again. 

For more details, see LOC-based pricing in Subscription plans.