Command Line Reference

The gcovr command recursively searches a directory tree to find gcov coverage files, and generates a text summary of the code coverage. The -h/--help option generates the following summary of the gcovr command line options:

gcovr

A utility to run gcov and summarize the coverage in simple reports.

usage: gcovr [options] [search_paths...]

See <http://gcovr.com/> for the full manual.

Options

search_paths

Search paths for coverage files. Defaults to --root and --gcov-object-directory. If path is a file it is used directly. Config key(s): search-path.

-h, --help

Show this help message, then exit.

--version

Print the version number, then exit.

-v, --verbose

Print progress messages. Please include this output in bug reports. Config key(s): verbose.

--no-color

Turn off colored logging. Is also set if environment variable NO_COLOR is present. Ignored if --force-color is used. Config key(s): no-color.

--force-color

Force colored logging, this is the default for a terminal. Is also set if environment variable FORCE_COLOR is present. Has precedence over --no-color. Config key(s): force-color.

-r <root>, --root <root>

The root directory of your source files. Defaults to ‘.’, the current directory. File names are reported relative to this root. The --root is the default --filter. Config key(s): root.

--config <config>

Load that configuration file. Defaults to gcovr.cfg, gcovr.toml or pyproject.toml (section tool.gcovr) in the --root directory.

--no-markers

Turn off exclusion markers. Any exclusion markers specified in source files will be ignored. ATTENTION: This option has no effect when generating reports from JSON tracefile. Config key(s): no-markers.

--fail-under-line <min>

Exit with a status of 2 if the total line coverage is less than MIN. Can be ORed with exit status of ‘--fail-under-branch’, ‘--fail-under-condition-or-decision’ and ‘--fail-under-function’. Config key(s): fail-under-line.

--fail-under-branch <min>

Exit with a status of 4 if the total branch coverage is less than MIN. Can be ORed with exit status of ‘--fail-under-line’, ‘--fail-under-condition-or-decision’ and ‘--fail-under-function’. Config key(s): fail-under-branch.

--fail-under-condition-or-decision <min>, --fail-under-condition <min>, --fail-under-decision <min>

Exit with a status of 8 if the total condition or decision coverage is less than MIN. Can be ORed with exit status of ‘--fail-under-line’, ‘--fail-under-branch’ and ‘--fail-under-function’. Config key(s): fail-under-condition-or-decision, fail-under-condition, fail-under-decision.

--fail-under-function <min>

Exit with a status of 16 if the total function coverage is less than MIN. Can be ORed with exit status of ‘--fail-under-line’, ‘--fail-under-branch’ and ‘--fail-under-condition-or-decision’. Config key(s): fail-under-function.

--source-encoding <source_encoding>

Select the source file encoding. Defaults to the system default encoding (UTF-8). Config key(s): source-encoding.

--exclude-function <exclude_function>

Exclude coverage of functions. If function starts and end with ‘/’ it is treated as a regular expression. This option needs at least GCC 14 with a supported version of JSON output format. ATTENTION: This option has no effect when generating reports from JSON tracefile. Config key(s): exclude-function.

--exclude-lines-by-pattern <exclude_lines_by_pattern>

Exclude lines that match this regex. The regex must match the start of the line.ATTENTION: This option has no effect when generating reports from JSON tracefile. Config key(s): exclude-lines-by-pattern.

--exclude-branches-by-pattern <exclude_branches_by_pattern>

Exclude branches that match this regex. The regex must match the start of the line.ATTENTION: This option has no effect when generating reports from JSON tracefile. Config key(s): exclude-branches-by-pattern.

--exclude-pattern-prefix <exclude_pattern_prefix>

Define the regex prefix used in markers / line exclusions (i.e …_EXCL_START, …_EXCL_START, …_EXCL_STOP). ATTENTION: This option has no effect when generating reports from JSON tracefile except for the syntax highlighting in the HTML report Config key(s): exclude-pattern-prefix.

--warn-excluded-lines-with-hits

Print a warning if a line excluded by comments has a hit counter != 0. ATTENTION: This option has no effect when generating reports from JSON tracefile. Config key(s): warn-excluded-lines-with-hits.

Filter Options

Filters decide which files are included in the report. Any filter must match, and no exclude filter must match. A filter is a regular expression that matches a path. Filter paths use forward slashes, even on Windows. If the filter looks like an absolute path it is matched against an absolute path. Otherwise, the filter is matched against a relative path, where that path is relative to the current directory or if defined in a configuration file to the directory of the file.

--gcov-filter <gcov_include_filter>

Keep only gcov data files that match this filter. Can be specified multiple times. Config key(s): gcov-filter.

--gcov-exclude <gcov_exclude_filter>

Exclude gcov data files that match this filter. Can be specified multiple times. Config key(s): gcov-exclude.

-i <include_search_filter>, --include <include_search_filter>

Include source files that match this filter. This is to ensure that files are in report even if no coverage data is found. Files are searched recursive from the --root directory. Can be specified multiple times. Config key(s): include.

-f <include_filter>, --filter <include_filter>

Keep only source files that match this filter. Can be specified multiple times. Relative filters are relative to the current working directory or if defined in a configuration file. If no filters are provided, defaults to --root. Config key(s): filter.

-e <exclude_filter>, --exclude <exclude_filter>

Exclude source files that match this filter. Can be specified multiple times. Config key(s): exclude.

--exclude-directory <exclude_directory>, --gcov-exclude-directory <exclude_directory>, --gcov-exclude-directories <exclude_directory>, --exclude-directories <exclude_directory>

Exclude directories that match this regex while searching raw coverage files. Can be specified multiple times. ATTENTION: This option has no effect when generating reports from JSON tracefile. Config key(s): exclude-directory, gcov-exclude-directory, gcov-exclude-directories, exclude-directories.

--trace-include <trace_include_filter>

Log output for files that match this filter. The output is logged without activating verbose mode. Can be specified multiple times. Config key(s): trace-include.

--trace-exclude <trace_exclude_filter>

Do not log very verbose output for files that match this filter. Can be specified multiple times. Config key(s): trace-exclude.

Output Options

Gcovr prints a text report by default, but can switch to XML, HTML and other formats.

--medium-threshold <medium>, --html-medium-threshold <medium>

If the coverage is below MEDIUM, the value is marked as low coverage in the report. MEDIUM has to be lower than or equal to value of --high-threshold and greater than 0. If MEDIUM is equal to value of --high-threshold the report has only high and low coverage. Default is 75.0. Config key(s): medium-threshold, html-medium-threshold.

--high-threshold <high>, --html-high-threshold <high>

If the coverage is below HIGH, the value is marked as medium coverage in the report. HIGH has to be greater than or equal to value of --medium-threshold. If HIGH is equal to value of --medium-threshold the report has only high and low coverage. Default is 90.0. Config key(s): high-threshold, html-high-threshold.

--medium-threshold-branch <medium_branch>, --html-medium-threshold-branch <medium_branch>

If the coverage is below MEDIUM_BRANCH, the value is marked as low coverage in the report. MEDIUM_BRANCH has to be lower than or equal to value of --high-threshold-branch and greater than 0. If MEDIUM_BRANCH is equal to value of --medium-threshold-branch the report has only high and low coverage. Default is taken from --medium-threshold. Config key(s): medium-threshold-branch, html-medium-threshold-branch.

--high-threshold-branch <high_branch>, --html-high-threshold-branch <high_branch>

If the coverage is below HIGH_BRANCH, the value is marked as medium coverage in the report. HIGH_BRANCH has to be greater than or equal to value of --medium-threshold-branch. If HIGH_BRANCH is equal to value of --medium-threshold-branch the report has only high and low coverage. Default is taken from --high-threshold. Config key(s): high-threshold-branch, html-high-threshold-branch.

--medium-threshold-line <medium_line>, --html-medium-threshold-line <medium_line>

If the coverage is below MEDIUM_LINE, the value is marked as low coverage in the report. MEDIUM_LINE has to be lower than or equal to value of --high-threshold-line and greater than 0. If MEDIUM_LINE is equal to value of --medium-threshold-line the report has only high and low coverage. Default is taken from --medium-threshold. Config key(s): medium-threshold-line, html-medium-threshold-line.

--high-threshold-line <high_line>, --html-high-threshold-line <high_line>

If the coverage is below HIGH_LINE, the value is marked as medium coverage in the report. HIGH_LINE has to be greater than or equal to value of --medium-threshold-line. If HIGH_LINE is equal to value of --medium-threshold-line the report has only high and low coverage. Default is taken from --high-threshold. Config key(s): high-threshold-line, html-high-threshold-line.

-o <output>, --output <output>

Print output to this filename. Defaults to stdout. Individual output formats can override this. Config key(s): output.

--decisions

Report the decision coverage. For HTML, JSON, SonarQube and the summary report. Config key(s): decisions.

--calls

Report the calls coverage. For HTML and the summary report. Config key(s): calls.

--sort-branches

Sort entries by branches instead of lines. Can only be used together with ‘--sort uncovered-number’ or ‘--sort uncovered-percent’. Config key(s): sort-branches.

--sort {filename,uncovered-number,uncovered-percent}

Sort entries by filename, number or percent of uncovered lines or branches(if the option --sort-branches is given). The default order is increasing and can be changed by --sort-reverse. The secondary sort key (if values are identical) is always the filename (ascending order). For CSV, HTML, JSON, LCOV and text report. Config key(s): sort.

-u, --sort-uncovered

Deprecated, please use ‘--sort uncovered-number’ instead. Config key(s): sort-uncovered.

-p, --sort-percentage

Deprecated, please use ‘--sort uncovered-percent’ instead. Config key(s): sort-percentage.

--sort-reverse

Sort entries in reverse order (see --sort). Config key(s): sort_reverse.

--timestamp <timestamp>

Override current time for reproducible reports. Can use YYYY-MM-DD hh:mm:ss or epoch notation. Used by HTML, Clover, Cobertura, and Coveralls reports. Default is taken from environment variable SOURCE_DATE_EPOCH (see https://reproducible-builds.org/docs/source-date-epoch) or current time. Config key(s): timestamp.

-k, --keep-intermediate-files, --keep, --gcov-keep

Keep gcov/profdata files after processing. This applies both to files that were generated by gcovr, or were supplied via the --gcov-use-existing-files/--llvm-use-existing-files option. Config key(s): keep-intermediate-files.

-d, --delete-input-files, --delete, --gcov-delete

Delete gcda/profraw files after processing, used gcno files are never deleted. Config key(s): delete-input-files.

--merge-mode-functions {strict,merge-use-line-0,merge-use-line-min,merge-use-line-max,separate}

The merge mode for functions coverage from different gcov files for same sourcefile. Default is ‘strict’. Config key(s): merge-mode-functions.

GCOV options

Options for reading GCOV text and JSON reports. JSON reports are the default for gcc-14 and newer (JSON format 2, see gcc --version).

-g, --gcov-use-existing-files, --use-gcov-files

Use existing gcov files for analysis. Config key(s): gcov-use-existing-files, use-gcov-files.

--gcov-ignore-errors {all,source_not_found,output_error,no_working_dir_found}

Ignore errors from invoking GCOV command instead of exiting with an error. A report will be shown on stderr. Default is ‘None’. Config key(s): gcov-ignore-errors.

--gcov-ignore-parse-errors {all,negative_hits.warn,negative_hits.warn_once_per_file,suspicious_hits.warn,suspicious_hits.warn_once_per_file}

Skip lines with parse errors in GCOV files instead of exiting with an error. A report will be shown on stderr. Default is ‘None’. Config key(s): gcov-ignore-parse-errors.

--gcov-suspicious-hits-threshold <gcov_suspicious_hits_threshold>

Set the threshold for detecting suspicious hits in gcov output files. Set to 0 to turn the detection off. Config key(s): gcov-suspicious-hits-threshold.

--gcov-executable <gcov_cmd>

Use a particular gcov executable. Must match the compiler you are using, e.g. ‘llvm-cov gcov’ for Clang. Can include additional arguments. Defaults to the GCOV environment variable, or ‘gcov’: ‘gcov’. Config key(s): gcov-executable.

--gcov-object-directory <gcov_objdir>, --object-directory <gcov_objdir>

Override normal working directory detection. Gcovr needs to identify the path between gcda files and the directory where the compiler was originally run. Normally, gcovr can guess correctly. This option specifies either the path from gcc to the gcda file (i.e. gcc’s ‘-o’ option), or the path from the gcda file to gcc’s working directory. Config key(s): gcov-object-directory, object-directory.

-j <gcov_parallel>

Set the number of threads to use in parallel. 0=Number of CPUs, negative number=’all but N CPUs’. Config key(s): gcov-parallel.

--merge-lines

Merge line coverage for same line coming from different functions, e.g. template instances. The branches, conditions and calls are merged accordingly. ATTENTION: This option doesn’t affect the GCOVR JSON intermediate format here still the raw data is reported. If you use a two pass generation (1st run: GCOV -> JSON, 2nd run: JSON -> human readable reports), the option is only needed in the second run. Config key(s): merge-lines.

--exclude-function-lines

Exclude coverage from lines defining a function.ATTENTION: This option has no effect when generating reports from JSON tracefile. Config key(s): exclude-function-lines.

--include-internal-functions

Include function coverage of compiler internal functions (starting with ‘__’ or ‘_GLOBAL__sub_I_’). ATTENTION: This option has no effect when generating reports from JSON tracefile. Config key(s): include-internal-functions.

--exclude-unreachable-branches

Remove branch coverage from lines without useful source code (often, compiler-generated ‘dead’ code). ATTENTION: This option has no effect when generating reports from JSON tracefile. Config key(s): exclude-unreachable-branches.

--exclude-noncode-lines

Remove coverage from lines which seem to be non-code. ATTENTION: This option has no effect when generating reports from JSON tracefile. Negation: --no-exclude-noncode-lines. Config key(s): exclude-noncode-lines.

--exclude-throw-branches

For branch coverage, remove branches that the compiler generates for exception handling. This often leads to more ‘sensible’ coverage reports. ATTENTION: This option has no effect when generating reports from JSON tracefile. Config key(s): exclude-throw-branches.

LLVM options

Options for reading LLVM source based code coverage reports, <https://clang.llvm.org/docs/SourceBasedCodeCoverage.html#creating-coverage-reports>.

--llvm-profdata-executable <llvm_profdata_cmd>

Use a particular llvm-profdata executable to convert LLVM profraw files. This switches from searching gcno/gcda files and using gcov to searching profraw files (Source-based Code Coverage) of LLVM. Must match the compiler you are using, e.g. llvm-profdata-13 for clang-13. Defaults to the LLVM_PROFDATA environment variable: ‘None’. Config key(s): llvm-profdata-executable.

--llvm-cov-binary <llvm_cov_binaries>

The binary to export the coverage data for. See help of ‘llvm-cov export’ command. The option can be used multiple times. Config key(s): llvm-cov-binary.

GCOVR text options

Options for GCOVR classic text reports.

--txt-metric {line,branch,condition,decision}

The metric type to report. If option is given multiple times the reports are printed in the given order. Default is ‘line’. Config key(s): txt-metrics.

--txt-report-covered

Report the covered lines instead of the uncovered. Config key(s): txt-covered.

--txt <output>

Generate a text report. OUTPUT is optional and defaults to --output. Config key(s): txt.

-s, --txt-summary, --print-summary

Print a small report to stdout with line & function & branch percentage coverage optional parts are decision & call coverage. This is in addition to other reports. Config key(s): txt-summary, print-summary.

GCOVR HTML options

Options for GCOVR HTML reports with different themes.

--html <output>

Generate a HTML report. OUTPUT is optional and defaults to --output. Config key(s): html.

--html-details <output>

Add annotated source code reports to the HTML report. Implies --html, can not be used together with --html-nested. OUTPUT is optional and defaults to --output. Config key(s): html-details.

--html-nested <output>

Add annotated source code reports to the HTML report. A page is created for each directory that summarize subdirectories with aggregated statistics. Implies --html, can not be used together with --html-details. OUTPUT is optional and defaults to --output. Config key(s): html-nested.

--html-single-page

Use one single html output file containing all data in the specified mode. If mode is ‘js-enabled’ (default) and javascript is possible the page is interactive like the normal report. If mode is ‘static’ all files are shown at once. Config key(s): html-single-page.

--html-static-report

Create a static report without javascript. Config key(s): html-static-report.

--html-self-contained

Control whether the HTML report bundles resources like CSS styles. Self-contained reports can be sent via email, but conflict with the Content Security Policy of some web servers. Defaults to self-contained reports unless --html-details or --html-nested is used without --html-single-page. Negation: --no-html-self-contained. Config key(s): html-self-contained.

--html-block-ids

Add the block ids to the HTML report for debugging the branch coverage. Config key(s): html-block-ids.

--html-template-dir <output>

Override the default Jinja2 template directory for the HTML report. Config key(s): html-template-dir.

--html-syntax-highlighting, --html-details-syntax-highlighting

Use syntax highlighting in HTML source page. Enabled by default. Negation: --no-html-syntax-highlighting, --no-html-details-syntax-highlighting. Config key(s): html-syntax-highlighting, html-details-syntax-highlighting.

--html-theme {green,blue,boost.blue,boost.green,github.blue,github.green,github.dark-green,github.dark-blue}

Override the default color theme for the HTML report. Default is green. Config key(s): html-theme.

--html-css <css>

Override the default style sheet for the HTML report. Config key(s): html-css.

--html-title <title>

Use TITLE as title for the HTML report. Default is ‘GCC Code Coverage Report’. Config key(s): html-title.

--html-tab-size <html_tab_size>

Used spaces for a tab in a source file. Default is 4 Config key(s): html-tab-size.

--html-absolute-paths

Use absolute paths to link the --html-details reports. Defaults to relative links. Config key(s): html-absolute-paths.

--html-encoding <html_encoding>

Override the declared HTML report encoding. Defaults to UTF-8. See also --source-encoding. Config key(s): html-encoding.

GCOVR CSV options

Options for GCOVR CSV reports.

--csv <output>

Generate a CSV summary report. OUTPUT is optional and defaults to --output. Config key(s): csv.

GCOVR JSON options

Options for report generation in GCOVR JSON intermediate format. This file format contains a dump of the internal data model and can be used as input file to write other reports.

--json <output>

Generate a JSON report. OUTPUT is optional and defaults to --output. Config key(s): json.

--json-pretty

Pretty-print the JSON report. Implies --json. Config key(s): json-pretty.

--json-summary <output>

Generate a JSON summary report. OUTPUT is optional and defaults to --output. Config key(s): json-summary.

--json-summary-pretty

Pretty-print the JSON SUMMARY report. Implies --json-summary. Config key(s): json-summary-pretty.

--json-base <path>

Prepend the given path to all file paths in JSON report. Config key(s): json-base.

-a <json_tracefile>, --json-add-tracefile <json_tracefile>, --add-tracefile <json_tracefile>

Combine the coverage data from JSON files. Coverage files contains source files structure relative to root directory. Those structures are combined in the output relative to the current root directory. Unix style wildcards can be used to add the pathnames matching a specified pattern. In this case pattern must be set in double quotation marks. Option can be specified multiple times. When option is used gcov is not executed to collect the new coverage data. WARNING: The option --merge-lines doesn’t affect the JSON files and needs to be added when the JSON files are processed to generate the reports. Config key(s): add-tracefile.

--json-trace-data-source

Write the data source to the tracefile. Config key(s): json-trace-data-source.

--json-compare

Compare exactly two JSON files given with --json-add-tracefile. The comparison result is available for text, JSON and HTML report. Config key(s): json-compare.

GCOVR Markdown options

Options for GCOVR Markdown reports.

--markdown <output>

Generate a Markdown report. OUTPUT is optional and defaults to --output. Config key(s): markdown.

--markdown-summary <output>

Generate a Markdown summary report. OUTPUT is optional and defaults to --output. Config key(s): markdown-summary.

--markdown-theme {green,blue}

Override the default color theme for the Markdown report. Default is green. Config key(s): markdown-theme.

--markdown-title <text>

Override the default title of the Markdown report. Default is GCC Code Coverage Report. Config key(s): markdown-title.

--markdown-heading-level <int>

Override the default heading level of the Markdown report. This is useful if the report is embedded in another Markdown file. Default is 1. Config key(s): markdown-heading-level.

--markdown-file-link <text>

Link the files using given URL by replacing {file} with the current file. Config key(s): markdown-file-link.

Clover XML options

Options for report generation in Clover format, see <https://bitbucket.org/atlassian/clover/src/master>. The XML file follows the schema <https://bitbucket.org/atlassian/clover/raw/a688248db8ae15eb7158947b7ba275c9ffbaf008/etc/schema/clover.xsd>.

--clover <output>

Generate a Clover XML report. OUTPUT is optional and defaults to --output. Config key(s): clover.

--clover-pretty

Pretty-print the Clover XML report. Implies --clover. Config key(s): clover-pretty.

--clover-project <clover_project>

The project name for the Clover XML report. Config key(s): clover-project.

Cobertura XML options

Options for report generation in Cobertura format, see <https://github.com/cobertura/cobertura>. The XML file follows the schema <https://github.com/cobertura/cobertura/blob/e5eea8679ebce047ec6ccdfdbf6cf2c14b376875/cobertura/src/site/htdocs/xml/coverage-04.dtd>.Reports in Cobertura format can also be used as input for GCOVR.

--cobertura <output>, -x <output>, --xml <output>

Generate a Cobertura XML report. OUTPUT is optional and defaults to --output. Config key(s): cobertura, xml.

--cobertura-pretty, --xml-pretty

Pretty-print the Cobertura XML report. Implies --cobertura. Config key(s): cobertura-pretty, xml-pretty.

--cobertura-add-tracefile <cobertura_tracefile>

Combine the coverage data from Cobertura XML files. When this option is used gcov is not run to collect the new coverage data. Config key(s): cobertura-add-tracefile.

Coveralls JSON options

Options for report generation in Coveralls format, see <https://docs.coveralls.io/api-jobs-endpoint#the-coverage-report-json-objects>.

--coveralls <output>

Generate Coveralls API coverage report in this file name. OUTPUT is optional and defaults to --output. Config key(s): coveralls.

--coveralls-pretty

Pretty-print the Coveralls report. Implies --coveralls. Config key(s): coveralls-pretty.

JaCoCo XML options

Options for report generation in JaCoCo format, see <https://github.com/jacoco/jacoco>. The XML file follows the schema <https://www.jacoco.org/jacoco/trunk/coverage/report.dtd>.

--jacoco <output>

Generate a JaCoCo XML report. OUTPUT is optional and defaults to --output. Config key(s): jacoco.

--jacoco-pretty

Pretty-print the JaCoCo XML report. Implies --jacoco. Config key(s): jacoco-pretty.

--jacoco-report-name <name>

The name used for the JaCoCo report. Default is ‘GCOVR report’. Config key(s): jacoco-report-name.

LCOV info options

Options for report generation in LCOV format v1.x and v2.0.

--lcov <output>

Generate a LCOV info file. OUTPUT is optional and defaults to --output. Config key(s): lcov.

--lcov-format-version {1.x,2.0}

The format version to write. Config key(s): lcov_format_version.

--lcov-format-1.x

Deprecated, please use --lcov-format-version=1.x instead. Config key(s): lcov-format-1.x.

--lcov-comment <comment>

The comment used in LCOV file. Config key(s): lcov-comment.

--lcov-test-name <name>

The name used for TN in LCOV file, must not contain spaces. Default is ‘GCOVR_report’. Config key(s): lcov-test-name.

SonarQube XML options

Options for report generation in SonarQube generic format, see <https://docs.sonarsource.com/sonarqube-server/analyzing-source-code/test-coverage/generic-test-data>.

--sonarqube <output>

Generate SonarQube generic coverage report in this file name. OUTPUT is optional and defaults to --output. Config key(s): sonarqube.

--sonarqube-pretty

Pretty-print the SonarQube XML report. Implies --sonarqube. Config key(s): sonarqube-pretty.

--sonarqube-metric {line,branch,condition,decision}

The metric type to report. Default is ‘branch’. Config key(s): sonarqube-metric.

For guide-level explanation on using these options, see the User Guide.