Provided by: gcovr_7.0-1_all 
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
-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.
-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 in the --root directory.
--no-markers
Turn off exclusion markers. Any exclusion markers specified in source files will be ignored.
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-decision', and '-- fail-under-function' option. Config
key(s): failunder-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-decision', and '-- fail-under-function' option.
Config key(s): failunder-branch.
--fail-under-decision MIN
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.
--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-decision' option. 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.
--cobertura-add-tracefile COBERTURA_ADD_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-addtracefile.
-a JSON_ADD_TRACEFILE, --json-add-tracefile JSON_ADD_TRACEFILE, --add-tracefile JSON_ADD_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 run to collect the new coverage data. Config key(s): addtracefile.
--txt-report-covered
Report the covered lines instead of the uncovered. Config key(s): txt-covered.
--exclude-lines-by-pattern EXCLUDE_LINES_BY_PATTERN
Exclude lines that match this regex. Config key(s): exclude-lines-by-pattern.
--exclude-branches-by-pattern EXCLUDE_BRANCHES_BY_PATTERN
Exclude branches that match this regex. 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) Config key(s): exclude-pattern-prefix.
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.
Output Options:
Gcovr prints a text report by default, but can switch to XML or HTML.
-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, 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 or
--sort-percent is used. 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
--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 ascending filename. For CSV, HTML,
JSON, LCOV and text report. Config key(s): sort.
-u, --sort-uncovered
Deprecated, please use '--sort-key uncovered-number' instead. Sort entries by number 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
ascending filename. For CSV, HTML, JSON, LCOV and text report. Config key(s): sortuncovered.
-p, --sort-percentage
Deprecated, please use '--sort-key uncovered-percent' instead. Sort entries by percentage 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 ascending filename. For CSV, HTML, JSON, LCOV and text report. Config key(s):
sortpercentage.
--sort-reverse
Sort entries in reverse order (see --sort). Config key(s): sort_reverse.
--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,
xmlpretty.
--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.
--csv [OUTPUT]
Generate a CSV summary report. OUTPUT is optional and defaults to --output. Config key(s): csv.
--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 --htmlnested. 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-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-syntaxhighlighting.
--html-theme THEME
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-medium-threshold MEDIUM
If the coverage is below MEDIUM, the value is marked as low coverage in the HTML report. MEDIUM
has to be lower than or equal to value of --html-high-threshold and greater than 0. If MEDIUM is
equal to value of --html-high-threshold the report has only high and low coverage. Default is
75.0. Config key(s): html-mediumthreshold.
--html-high-threshold HIGH
If the coverage is below HIGH, the value is marked as medium coverage in the HTML report. HIGH has
to be greater than or equal to value of --html-mediumthreshold. If HIGH is equal to value of
--html-mediumthreshold the report has only high and low coverage. Default is 90.0. Config key(s):
html-high-threshold.
--html-medium-threshold-branch MEDIUM_BRANCH
If the coverage is below MEDIUM_BRANCH, the value is marked as low coverage in the HTML report.
MEDIUM_BRANCH has to be lower than or equal to value of --html-high-threshold-branch and greater
than 0. If MEDIUM_BRANCH is equal to value of --html-mediumthreshold-branch the report has only
high and low coverage. Default is taken from --html-mediumthreshold. Config key(s):
html-medium-thresholdbranch.
--html-high-threshold-branch HIGH_BRANCH
If the coverage is below HIGH_BRANCH, the value is marked as medium coverage in the HTML report.
HIGH_BRANCH has to be greater than or equal to value of --html-medium-threshold-branch. If
HIGH_BRANCH is equal to value of --html-medium-threshold-branch the report has only high and low
coverage. Default is taken from --html-high-threshold. Config key(s): htmlhigh-threshold-branch.
--html-medium-threshold-line MEDIUM_LINE
If the coverage is below MEDIUM_LINE, the value is marked as low coverage in the HTML report.
MEDIUM_LINE has to be lower than or equal to value of --html-highthreshold-line and greater than
0. If MEDIUM_LINE is equal to value of --html-medium-threshold-line the report has only high and
low coverage. Default is taken from --html-medium-threshold. Config key(s):
html-medium-threshold-line.
--html-high-threshold-line HIGH_LINE
If the coverage is below HIGH_LINE, the value is marked as medium coverage in the HTML report.
HIGH_LINE has to be greater than or equal to value of --html-medium-threshold-line. If HIGH_LINE
is equal to value of --html-medium-threshold-line the report has only high and low coverage.
Default is taken from --html-high-threshold. Config key(s): html-highthreshold-line.
--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):
htmlabsolute-paths.
--html-encoding HTML_ENCODING
Override the declared HTML report encoding. Defaults to UTF-8. See also --source-encoding. Config
key(s): html-encoding.
--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 is used. Negation: --nohtml-self-contained. Config
key(s): html-selfcontained.
--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.
--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 --jsonsummary. 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.
--lcov [OUTPUT]
Generate a LCOV info file. OUTPUT is optional and defaults to --output. Config key(s): lcov.
--lcov-comment COMMENT
The comment used in LCOV file. Config key(s): lcovcomment.
--lcov-test-name NAME
The name used for TN in LCOV file. Default is 'GCOVR report'. Config key(s): lcov-test-name.
--sonarqube [OUTPUT]
Generate sonarqube generic coverage report in this file name. OUTPUT is optional and defaults to
--output. Config key(s): sonarqube.
--txt-metric {line,branch,decision}
The metric type to report. Config key(s): txt-metric.
-b, --txt-branches, --branches
Deprecated, please use '--txt-metric branch' instead.Report the branch coverage instead of the
line coverage in text report. Config key(s): txt-branch.
--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.
--timestamp TIMESTAMP
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.
--gcov-filter GCOV_FILTER
Keep only gcov data files that match this filter. Can be specified multiple times. Config key(s):
gcovfilter.
--gcov-exclude GCOV_EXCLUDE
Exclude gcov data files that match this filter. Can be specified multiple times. Config key(s):
gcov-exclude.
--gcov-exclude-directories GCOV_EXCLUDE_DIRS, --exclude-directories GCOV_EXCLUDE_DIRS
Exclude directories that match this regex while searching raw coverage files. Can be specified
multiple times. Config key(s): gcov-excludedirectories, exclude-directories.
-f FILTER, --filter 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 EXCLUDE
Exclude source files that match this filter. Can be specified multiple times. Config key(s):
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.
-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-ignoreerrors.
--gcov-ignore-parse-errors [{all,negative_hits.warn,negative_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-ignoreparse-errors.
--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): gcovobject-directory,
object-directory.
-k, --gcov-keep, --keep
Keep gcov files after processing. This applies both to files that were generated by gcovr, or were
supplied via the --gcov-use-existing-files option. Config key(s): keep-gcov-files.
-d, --gcov-delete, --delete
Delete gcda files after processing. Config key(s): delete-gcov-files.
-j [GCOV_PARALLEL]
Set the number of threads to use in parallel. Config key(s): gcov-parallel.
--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.
--include-internal-functions
Include function coverage of compiler internal functions (starting with '__' or
'_GLOBAL__sub_I_'). Config key(s): include-internal-functions.
--exclude-unreachable-branches
Exclude branch coverage from lines without useful source code (often, compiler-generated 'dead'
code). Config key(s): exclude-unreachable-branches.
--exclude-function-lines
Exclude coverage from lines defining a function. Config key(s): exclude-function-lines.
--exclude-noncode-lines
Exclude coverage from lines which seem to be non-code. Negation: --no-exclude-noncode-lines.
Config key(s): exclude-noncode-lines.
--exclude-throw-branches
For branch coverage, exclude branches that the compiler generates for exception handling. This
often leads to more 'sensible' coverage reports. Config key(s): exclude-throw-branches.
See <http://gcovr.com/> for the full manual.
gcovr 7.0 January 2024 GCOVR(1)