usage: gcovr [options] [search_paths...] A utility to run gcov and summarize the coverage in simple reports. Options: -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 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, --fail-under-condition, --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. 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. 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 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, --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 EXCLUDE_FILTER Exclude source files that match this filter. Can be specified multiple times. Config key(s): exclude. --exclude-directory, --gcov-exclude-directory, --gcov-exclude-directories, --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, --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, --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, --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, --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, --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, --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 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 MERGE_MODE 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). --gcov-allowed-working-directory-root GCOV_ALLOWED_WORKING_DIRECTORY_ROOTS Do not run gcov in a working directory not in the list. The list contains by default the search paths. ATTENTION: This option has no effect when generating reports from JSON tracefile. Config key(s): gcov-allowed- working-directory-root. -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, --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, . --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 THEME Override the default theme for the HTML report. The themes green, blue, default.green and default.blue are deprecated and shall be replaced with github.green or github.blue. Default is github.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-add-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 THEME 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 . The XML file follows the schema . --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 . The XML file follows the schema .Reports in Cobertura format can also be used as input for GCOVR. --cobertura, -x, --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 . --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 . The XML file follows the schema . --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 . --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. See for the full manual.