Scroll to navigation

GCOVR(1) User Commands GCOVR(1)

NAME

gcovr - generate simple coverage reports

DESCRIPTION

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

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

OPTIONS

Show this help message, then exit.
Print the version number, then exit.
Print progress messages. Please include this output in bug reports. Config key(s): verbose.
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 colored logging, this is the default for a terminal. Is also set if environment variable FORCE_COLOR is present. Has precedence over --nocolor. Config key(s): force-color.
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.
Load that configuration file. Defaults to gcovr.cfg in the --root directory.
Turn off exclusion markers. Any exclusion markers specified in source files will be ignored. Config key(s): no-markers.
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-decision', and '-- fail-under-function' option. Config key(s): failunder-line.
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-decision', and '-- fail-under-function' option. Config key(s): failunder-branch.
Exit with a status of 8 if the total decision coverage is less than MIN. Can be ORed with exit status of '-- fail-under-line', '--fail-under-branch', and '--failunder-function' option. Config key(s): fail-underdecision.
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-decision' option. Config key(s): fail-under-function.
Select the source file encoding. Defaults to the system default encoding (utf-8). Config key(s): source-encoding.
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-addtracefile.
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 run to collect the new coverage data. Config key(s): addtracefile.
Report the covered lines instead of the uncovered. Config key(s): txt-covered.
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. Config key(s): excludefunction.
Exclude lines that match this regex. The regex must match the start of the line. Config key(s): excludelines-by-pattern.
Exclude branches that match this regex. The regex must match the start of the line. Config key(s): excludebranches-by-pattern.
Define the regex prefix used in markers / line exclusions (i.e ..._EXCL_START, ..._EXCL_START, ..._EXCL_STOP) Config key(s): exclude-pattern-prefix.
Print a warning if a line excluded by comments has a hit counter != 0. Config key(s): warn-excluded-lineswith-hits.
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.

Output Options:

Gcovr prints a text report by default, but can switch to XML or HTML.
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 --highthreshold the report has only high and low coverage. Default is 75.0. Config key(s): medium-threshold, html-medium-threshold.
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.
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 --highthreshold-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): mediumthreshold-branch, html-medium-threshold-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 --mediumthreshold-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-highthreshold-branch.
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 --highthreshold-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-thresholdline, html-medium-threshold-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 --mediumthreshold-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-highthreshold-line.
Print output to this filename. Defaults to stdout. Individual output formats can override this. Config key(s): output.
Report the decision coverage. For HTML, JSON, and the summary report. Config key(s): decisions.
Report the calls coverage. For HTML and the summary report. Config key(s): calls.
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 entries by filename, number or percent of uncovered lines or branches(if the option --sortbranches 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.
Deprecated, please use '--sort uncovered-number' instead. Config key(s): sort-uncovered.
Deprecated, please use '--sort uncovered-percent' instead. Config key(s): sort-percentage.
Sort entries in reverse order (see --sort). Config key(s): sort_reverse.
Generate a Clover XML report. OUTPUT is optional and defaults to --output. Config key(s): clover.
Pretty-print the Clover XML report. Implies --clover. Config key(s): clover-pretty.
The project name for the Clover XML report. Config key(s): clover-project.
Generate a Cobertura XML report. OUTPUT is optional and defaults to --output. Config key(s): cobertura, xml.
Pretty-print the Cobertura XML report. Implies --cobertura. Config key(s): cobertura-pretty, xmlpretty.
Generate Coveralls API coverage report in this file name. OUTPUT is optional and defaults to --output. Config key(s): coveralls.
Pretty-print the coveralls report. Implies --coveralls. Config key(s): coveralls-pretty.
Generate a CSV summary report. OUTPUT is optional and defaults to --output. Config key(s): csv.
Generate a HTML report. OUTPUT is optional and defaults to --output. Config key(s): html.
Add annotated source code reports to the HTML report. Implies --html, can not be used together with --htmlnested. OUTPUT is optional and defaults to --output. Config key(s): html-details.
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.
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.
Create a static report without javascript. Config key(s): html-static-report.
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-selfcontained. Config key(s): html-self-contained.
Add the block ids to the HTML report for debugging the branch coverage. Config key(s): html-block-ids.
Override the default Jinja2 template directory for the HTML report. Config key(s): html-template-dir.
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-syntaxhighlighting.
Override the default color theme for the HTML report. Default is green. Config key(s): html-theme.
Override the default style sheet for the HTML report. Config key(s): html-css.
Use TITLE as title for the HTML report. Default is 'GCC Code Coverage Report'. Config key(s): html-title.
Used spaces for a tab in a source file. Default is 4 Config key(s): html-tab-size.
Use absolute paths to link the --html-details reports. Defaults to relative links. Config key(s): htmlabsolute-paths.
Override the declared HTML report encoding. Defaults to UTF-8. See also --source-encoding. Config key(s): html-encoding.
Generate a JaCoCo XML report. OUTPUT is optional and defaults to --output. Config key(s): jacoco.
Pretty-print the JaCoCo XML report. Implies --jacoco. Config key(s): jacoco-pretty.
The name used for the JaCoCo report. Default is 'GCOVR report'. Config key(s): jacoco-report-name.
Generate a JSON report. OUTPUT is optional and defaults to --output. Config key(s): json.
Pretty-print the JSON report. Implies --json. Config key(s): json-pretty.
Generate a JSON summary report. OUTPUT is optional and defaults to --output. Config key(s): json-summary.
Pretty-print the JSON SUMMARY report. Implies --jsonsummary. Config key(s): json-summary-pretty.
Prepend the given path to all file paths in JSON report. Config key(s): json-base.
Write the data source to the tracefile. Config key(s): json-trace-data-source.
Generate a LCOV info file. OUTPUT is optional and defaults to --output. Config key(s): lcov.
The format version to write. Config key(s): lcov_format_version.
Deprecated, please use --lcov-format-version=1.x instead. Config key(s): lcov-format-1.x.
The comment used in LCOV file. Config key(s): lcovcomment.
The name used for TN in LCOV file, must not contain spaces. Default is 'GCOVR_report'. Config key(s): lcov-test-name.
Generate a markdown report. OUTPUT is optional and defaults to --output. Config key(s): markdown.
Generate a markdown summary report. OUTPUT is optional and defaults to --output. Config key(s): markdownsummary.
Override the default color theme for the Markdown report. Default is green. Config key(s): markdowntheme.
Override the default title of the Markdown report. Default is GCC Code Coverage Report. Config key(s): markdown-title.
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.
Link the files using given URL by replacing {file} with the current file. Config key(s): markdown-filelink.
Generate Sonarqube generic coverage report in this file name. OUTPUT is optional and defaults to --output. Config key(s): sonarqube.
Pretty-print the Sonarqube XML report. Implies --sonarqube. Config key(s): sonarqube-pretty.
The metric type to report. Default is 'branch'. Config key(s): sonarqube-metric.
The metric type to report. Default is 'line'. Config key(s): txt-metric.
Deprecated, please use '--txt-metric branch' instead.Report the branch coverage instead of the line coverage in text report. Config key(s): txt-branch.
Generate a text report. OUTPUT is optional and defaults to --output. Config key(s): txt.
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.
Override current time for reproducible reports. Can use `YYYY-MM-DD hh:mm:ss` or epoch notation. Used by HTML, Coveralls, and Cobertura reports. Default is taken from environment variable SOURCE_DATE_EPOCH (see https://reproducible-builds.org/docs/source-dateepoch) or current time. Config key(s): timestamp.

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.
Keep only gcov data files that match this filter. Can be specified multiple times. Config key(s): gcovfilter.
Exclude gcov data files that match this filter. Can be specified multiple times. Config key(s): gcov-exclude.
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.
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.
Exclude source files that match this filter. Can be specified multiple times. Config key(s): exclude.
Exclude directories that match this regex while searching raw coverage files. Can be specified multiple times. Config key(s): exclude-directory, gcov-exclude-directory, gcov-exclude-directories, exclude-directories.
Log output for files that match this filter. The output is logged without activating verbose mode. Can be specified multiple times. Config key(s): traceinclude.
Do not log very verbose output for files that match this filter. Can be specified multiple times. Config key(s): trace-exclude.

GCOV Options:

The 'gcov' tool turns raw coverage files (.gcda and .gcno) into .gcov files that are then processed by gcovr. The gcno files are generated by the compiler. The gcda files are generated when the instrumented program is executed.
Use existing gcov files for analysis. Config key(s): gcov-use-existing-files, use-gcov-files.
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-ignoreerrors.
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-ignoreparse-errors.
Set the threshold for detecting suspicious hits in gcov output files. Set to 0 to turn the detection of. Config key(s): gcov-suspicious-hits-threshold.
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.
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): gcovobject-directory, object-directory.
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 line coverage for same line coming from different functions, e.g. template instances. The branches, conditions and calls are merged accordingly. Config key(s): merge-lines.
Exclude coverage from lines defining a function. Config key(s): exclude-function-lines.
Include function coverage of compiler internal functions (starting with '__' or '_GLOBAL__sub_I_'). Config key(s): include-internal-functions.
Remove branch coverage from lines without useful source code (often, compiler-generated 'dead' code). Config key(s): exclude-unreachable-branches.
Remove coverage from lines which seem to be non-code. Negation: --no-exclude-noncode-lines. Config key(s): exclude-noncode-lines.
For branch coverage, remove branches that the compiler generates for exception handling. This often leads to more 'sensible' coverage reports. Config key(s): exclude-throw-branches.

LLVM Options:

The 'llvm-profdata' tool turns raw coverage files (.profraw) into .profdata files which are then exported by 'llvm-cov' into a JSON string.
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-profdataexecutable.
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.

GCOV and LLVM Options:

Options which are applicable for GCOV and LLVM processing.
Keep gcov/profdata files after processing. This applies both to files that were generated by gcovr, or were supplied via the --gcov-use-existingfiles/--llvm-use-existing-files option. Config key(s): keep-intermediate-files.
Delete gcda/profraw files after processing, used gcno files are never deleted. Config key(s): delete-inputfiles.
The merge mode for functions coverage from different gcov files for same sourcefile. Default is 'strict'. Config key(s): merge-mode-functions.

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

August 2026 gcovr 8.6