.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
.TH GCOVR "1" "May 2024" "gcovr 7.2+really" "User Commands"
.SH NAME
gcovr \- generate simple coverage reports
.SH DESCRIPTION
usage: gcovr [options] [search_paths...]
.PP
A utility to run gcov and summarize the coverage in simple reports.
.SH OPTIONS
.TP
\fB\-h\fR, \fB\-\-help\fR
Show this help message, then exit.
.TP
\fB\-\-version\fR
Print the version number, then exit.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Print progress messages. Please include this output in
bug reports. Config key(s): verbose.
.TP
\fB\-\-no\-color\fR
Turn off colored logging. Is also set if environment
variable NO_COLOR is present. Ignored if \fB\-\-force\-color\fR
is used. Config key(s): no\-color.
.TP
\fB\-\-force\-color\fR
Force colored logging, this is the default for a
terminal. Is also set if environment variable
FORCE_COLOR is present. Has presedence over \fB\-\-nocolor\fR. Config key(s): force\-color.
.TP
\fB\-r\fR ROOT, \fB\-\-root\fR ROOT
The root directory of your source files. Defaults to
\&'.', the current directory. File names are reported
relative to this root. The \fB\-\-root\fR is the default
\fB\-\-filter\fR. Config key(s): root.
.TP
\fB\-\-config\fR CONFIG
Load that configuration file. Defaults to gcovr.cfg in
the \fB\-\-root\fR directory.
.TP
\fB\-\-no\-markers\fR
Turn off exclusion markers. Any exclusion markers
specified in source files will be ignored. Config
key(s): no\-markers.
.TP
\fB\-\-fail\-under\-line\fR 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.
.TP
\fB\-\-fail\-under\-branch\fR 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.
.TP
\fB\-\-fail\-under\-decision\fR 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.
.TP
\fB\-\-fail\-under\-function\fR 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.
.TP
\fB\-\-source\-encoding\fR SOURCE_ENCODING
Select the source file encoding. Defaults to the
system default encoding (utf\-8). Config key(s):
source\-encoding.
.TP
\fB\-\-cobertura\-add\-tracefile\fR 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.
.TP
\fB\-a\fR JSON_ADD_TRACEFILE, \fB\-\-json\-add\-tracefile\fR JSON_ADD_TRACEFILE, \fB\-\-add\-tracefile\fR 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.
.TP
\fB\-\-txt\-report\-covered\fR
Report the covered lines instead of the uncovered.
Config key(s): txt\-covered.
.TP
\fB\-\-exclude\-lines\-by\-pattern\fR EXCLUDE_LINES_BY_PATTERN
Exclude lines that match this regex. Config key(s):
exclude\-lines\-by\-pattern.
.TP
\fB\-\-exclude\-branches\-by\-pattern\fR EXCLUDE_BRANCHES_BY_PATTERN
Exclude branches that match this regex. Config key(s):
exclude\-branches\-by\-pattern.
.TP
\fB\-\-exclude\-pattern\-prefix\fR 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.
.TP
search_paths
Search paths for coverage files. Defaults to \fB\-\-root\fR
and \fB\-\-gcov\-object\-directory\fR. If path is a file it is
used directly. Config key(s): search\-path.
.SS "Output Options:"
.IP
Gcovr prints a text report by default, but can switch to XML or HTML.
.TP
\fB\-o\fR OUTPUT, \fB\-\-output\fR OUTPUT
Print output to this filename. Defaults to stdout.
Individual output formats can override this. Config
key(s): output.
.TP
\fB\-\-decisions\fR
Report the decision coverage. For HTML, JSON, and the
summary report. Config key(s): decisions.
.TP
\fB\-\-calls\fR
Report the calls coverage. For HTML and the summary
report. Config key(s): calls.
.TP
\fB\-\-sort\-branches\fR
Sort entries by branches instead of lines. Can only be
used together with \fB\-\-sort\-uncovered\fR or \fB\-\-sort\-percent\fR
is used. Config key(s): sort\-branches.
.TP
\fB\-\-sort\fR {filename,uncovered\-number,uncovered\-percent}
Sort entries by filename, number or percent of
uncovered lines or branches(if the option \fB\-\-sortbranches\fR is given). The default order is increasing
and can be changed by \fB\-\-sort\-reverse\fR. 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.
.TP
\fB\-u\fR, \fB\-\-sort\-uncovered\fR
Deprecated, please use '\-\-sort\-key uncovered\-number'
instead. Sort entries by number of uncovered lines or
branches (if the option \fB\-\-sort\-branches\fR is given). The
default order is increasing and can be changed by
\fB\-\-sort\-reverse\fR. 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.
.TP
\fB\-p\fR, \fB\-\-sort\-percentage\fR
Deprecated, please use '\-\-sort\-key uncovered\-percent'
instead. Sort entries by percentage of uncovered lines
or branches (if the option \fB\-\-sort\-branches\fR is given).
The default order is increasing and can be changed by
\fB\-\-sort\-reverse\fR. 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.
.TP
\fB\-\-sort\-reverse\fR
Sort entries in reverse order (see \fB\-\-sort\fR). Config
key(s): sort_reverse.
.TP
\fB\-\-clover\fR [OUTPUT]
Generate a Clover XML report. OUTPUT is optional and
defaults to \fB\-\-output\fR. Config key(s): clover.
.TP
\fB\-\-clover\-pretty\fR
Pretty\-print the Clover XML report. Implies \fB\-\-clover\fR.
Config key(s): clover\-pretty.
.TP
\fB\-\-clover\-project\fR CLOVER_PROJECT
The project name for the Clover XML report. Config
key(s): clover\-project.
.TP
\fB\-\-cobertura\fR [OUTPUT], \fB\-x\fR [OUTPUT], \fB\-\-xml\fR [OUTPUT]
Generate a Cobertura XML report. OUTPUT is optional
and defaults to \fB\-\-output\fR. Config key(s): cobertura,
xml.
.TP
\fB\-\-cobertura\-pretty\fR, \fB\-\-xml\-pretty\fR
Pretty\-print the Cobertura XML report. Implies
\fB\-\-cobertura\fR. Config key(s): cobertura\-pretty, xmlpretty.
.TP
\fB\-\-coveralls\fR [OUTPUT]
Generate Coveralls API coverage report in this file
name. OUTPUT is optional and defaults to \fB\-\-output\fR.
Config key(s): coveralls.
.TP
\fB\-\-coveralls\-pretty\fR
Pretty\-print the coveralls report. Implies
\fB\-\-coveralls\fR. Config key(s): coveralls\-pretty.
.TP
\fB\-\-csv\fR [OUTPUT]
Generate a CSV summary report. OUTPUT is optional and
defaults to \fB\-\-output\fR. Config key(s): csv.
.TP
\fB\-\-html\fR [OUTPUT]
Generate a HTML report. OUTPUT is optional and
defaults to \fB\-\-output\fR. Config key(s): html.
.TP
\fB\-\-html\-details\fR [OUTPUT]
Add annotated source code reports to the HTML report.
Implies \fB\-\-html\fR, can not be used together with \fB\-\-htmlnested\fR. OUTPUT is optional and defaults to \fB\-\-output\fR.
Config key(s): html\-details.
.TP
\fB\-\-html\-nested\fR [OUTPUT]
Add annotated source code reports to the HTML report.
A page is created for each directory that summarize
subdirectories with aggregated statistics. Implies
\fB\-\-html\fR, can not be used together with \fB\-\-html\-details\fR.
OUTPUT is optional and defaults to \fB\-\-output\fR. Config
key(s): html\-nested.
.TP
\fB\-\-html\-template\-dir\fR OUTPUT
Override the default Jinja2 template directory for the
HTML report. Config key(s): html\-template\-dir.
.TP
\fB\-\-html\-syntax\-highlighting\fR, \fB\-\-html\-details\-syntax\-highlighting\fR
Use syntax highlighting in HTML source page. Enabled
by default. Negation: \fB\-\-no\-html\-syntax\-highlighting\fR,
\fB\-\-no\-html\-details\-syntax\-highlighting\fR. Config key(s):
html\-syntax\-highlighting, html\-details\-syntaxhighlighting.
.TP
\fB\-\-html\-theme\fR THEME
Override the default color theme for the HTML report.
Default is green. Config key(s): html\-theme.
.TP
\fB\-\-html\-css\fR CSS
Override the default style sheet for the HTML report.
Config key(s): html\-css.
.TP
\fB\-\-html\-title\fR TITLE
Use TITLE as title for the HTML report. Default is
\&'GCC Code Coverage Report'. Config key(s): html\-title.
.TP
\fB\-\-html\-medium\-threshold\fR 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 \fB\-\-html\-high\-threshold\fR
and greater than 0. If MEDIUM is equal to value of
\fB\-\-html\-high\-threshold\fR the report has only high and low
coverage. Default is 75.0. Config key(s): html\-mediumthreshold.
.TP
\fB\-\-html\-high\-threshold\fR 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 \fB\-\-html\-mediumthreshold\fR. If HIGH is equal to value of \fB\-\-html\-mediumthreshold\fR the report has only high and low coverage.
Default is 90.0. Config key(s): html\-high\-threshold.
.TP
\fB\-\-html\-medium\-threshold\-branch\fR 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 \fB\-\-html\-high\-threshold\-branch\fR and greater than 0. If
MEDIUM_BRANCH is equal to value of \fB\-\-html\-mediumthreshold\-branch\fR the report has only high and low
coverage. Default is taken from \fB\-\-html\-mediumthreshold\fR. Config key(s): html\-medium\-thresholdbranch.
.TP
\fB\-\-html\-high\-threshold\-branch\fR 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 \fB\-\-html\-medium\-threshold\-branch\fR. If HIGH_BRANCH is
equal to value of \fB\-\-html\-medium\-threshold\-branch\fR the
report has only high and low coverage. Default is
taken from \fB\-\-html\-high\-threshold\fR. Config key(s): htmlhigh\-threshold\-branch.
.TP
\fB\-\-html\-medium\-threshold\-line\fR 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 \fB\-\-html\-highthreshold\-line\fR and greater than 0. If MEDIUM_LINE is
equal to value of \fB\-\-html\-medium\-threshold\-line\fR the
report has only high and low coverage. Default is
taken from \fB\-\-html\-medium\-threshold\fR. Config key(s):
html\-medium\-threshold\-line.
.TP
\fB\-\-html\-high\-threshold\-line\fR 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
\fB\-\-html\-medium\-threshold\-line\fR. If HIGH_LINE is equal to
value of \fB\-\-html\-medium\-threshold\-line\fR the report has
only high and low coverage. Default is taken from
\fB\-\-html\-high\-threshold\fR. Config key(s): html\-highthreshold\-line.
.TP
\fB\-\-html\-tab\-size\fR HTML_TAB_SIZE
Used spaces for a tab in a source file. Default is 4
Config key(s): html\-tab\-size.
.TP
\fB\-\-html\-absolute\-paths\fR
Use absolute paths to link the \fB\-\-html\-details\fR reports.
Defaults to relative links. Config key(s): htmlabsolute\-paths.
.TP
\fB\-\-html\-encoding\fR HTML_ENCODING
Override the declared HTML report encoding. Defaults
to UTF\-8. See also \fB\-\-source\-encoding\fR. Config key(s):
html\-encoding.
.TP
\fB\-\-html\-self\-contained\fR
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 \fB\-\-html\-details\fR is used. Negation: \fB\-\-nohtml\-self\-contained\fR. Config key(s): html\-selfcontained.
.TP
\fB\-\-jacoco\fR [OUTPUT]
Generate a JaCoCo XML report. OUTPUT is optional and
defaults to \fB\-\-output\fR. Config key(s): jacoco.
.TP
\fB\-\-jacoco\-pretty\fR
Pretty\-print the JaCoCo XML report. Implies \fB\-\-jacoco\fR.
Config key(s): jacoco\-pretty.
.TP
\fB\-\-json\fR [OUTPUT]
Generate a JSON report. OUTPUT is optional and
defaults to \fB\-\-output\fR. Config key(s): json.
.TP
\fB\-\-json\-pretty\fR
Pretty\-print the JSON report. Implies \fB\-\-json\fR. Config
key(s): json\-pretty.
.TP
\fB\-\-json\-summary\fR [OUTPUT]
Generate a JSON summary report. OUTPUT is optional and
defaults to \fB\-\-output\fR. Config key(s): json\-summary.
.TP
\fB\-\-json\-summary\-pretty\fR
Pretty\-print the JSON SUMMARY report. Implies \fB\-\-jsonsummary\fR. Config key(s): json\-summary\-pretty.
.TP
\fB\-\-json\-base\fR PATH
Prepend the given path to all file paths in JSON
report. Config key(s): json\-base.
.TP
\fB\-\-lcov\fR [OUTPUT]
Generate a LCOV info file. OUTPUT is optional and
defaults to \fB\-\-output\fR. Config key(s): lcov.
.TP
\fB\-\-lcov\-comment\fR COMMENT
The comment used in LCOV file. Config key(s): lcovcomment.
.TP
\fB\-\-lcov\-test\-name\fR NAME
The name used for TN in LCOV file. Default is 'GCOVR
report'. Config key(s): lcov\-test\-name.
.TP
\fB\-\-sonarqube\fR [OUTPUT]
Generate sonarqube generic coverage report in this
file name. OUTPUT is optional and defaults to
\fB\-\-output\fR. Config key(s): sonarqube.
.TP
\fB\-\-txt\-metric\fR {line,branch,decision}
The metric type to report. Config key(s): txt\-metric.
.TP
\fB\-b\fR, \fB\-\-txt\-branches\fR, \fB\-\-branches\fR
Deprecated, please use '\-\-txt\-metric branch'
instead.Report the branch coverage instead of the line
coverage in text report. Config key(s): txt\-branch.
.TP
\fB\-\-txt\fR [OUTPUT]
Generate a text report. OUTPUT is optional and
defaults to \fB\-\-output\fR. Config key(s): txt.
.TP
\fB\-s\fR, \fB\-\-txt\-summary\fR, \fB\-\-print\-summary\fR
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.
.TP
\fB\-\-timestamp\fR 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.
.SS "Filter Options:"
.IP
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.
.TP
\fB\-\-gcov\-filter\fR GCOV_FILTER
Keep only gcov data files that match this filter. Can
be specified multiple times. Config key(s): gcovfilter.
.TP
\fB\-\-gcov\-exclude\fR GCOV_EXCLUDE
Exclude gcov data files that match this filter. Can be
specified multiple times. Config key(s): gcov\-exclude.
.TP
\fB\-\-gcov\-exclude\-directories\fR GCOV_EXCLUDE_DIRS, \fB\-\-exclude\-directories\fR 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.
.TP
\fB\-f\fR FILTER, \fB\-\-filter\fR 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 \fB\-\-root\fR. Config key(s): filter.
.TP
\fB\-e\fR EXCLUDE, \fB\-\-exclude\fR EXCLUDE
Exclude source files that match this filter. Can be
specified multiple times. Config key(s): exclude.
.SS "GCOV Options:"
.IP
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.
.TP
\fB\-g\fR, \fB\-\-gcov\-use\-existing\-files\fR, \fB\-\-use\-gcov\-files\fR
Use existing gcov files for analysis. Config key(s):
gcov\-use\-existing\-files, use\-gcov\-files.
.TP
\fB\-\-gcov\-ignore\-errors\fR [{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.
.TP
\fB\-\-gcov\-ignore\-parse\-errors\fR [{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.
.TP
\fB\-\-gcov\-executable\fR 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.
.TP
\fB\-\-gcov\-object\-directory\fR GCOV_OBJDIR, \fB\-\-object\-directory\fR 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.
.TP
\fB\-k\fR, \fB\-\-gcov\-keep\fR, \fB\-\-keep\fR
Keep gcov files after processing. This applies both to
files that were generated by gcovr, or were supplied
via the \fB\-\-gcov\-use\-existing\-files\fR option. Config
key(s): keep\-gcov\-files.
.TP
\fB\-d\fR, \fB\-\-gcov\-delete\fR, \fB\-\-delete\fR
Delete gcda files after processing. Config key(s):
delete\-gcov\-files.
.TP
\fB\-j\fR [GCOV_PARALLEL]
Set the number of threads to use in parallel. Config
key(s): gcov\-parallel.
.TP
\fB\-\-merge\-mode\-functions\fR MERGE_MODE
The merge mode for functions coverage from different
gcov files for same sourcefile.Default is 'strict'.
Config key(s): merge\-mode\-functions.
.TP
\fB\-\-include\-internal\-functions\fR
Include function coverage of compiler internal
functions (starting with '__' or '_GLOBAL__sub_I_').
Config key(s): include\-internal\-functions.
.TP
\fB\-\-exclude\-unreachable\-branches\fR
Exclude branch coverage from lines without useful
source code (often, compiler\-generated 'dead' code).
Config key(s): exclude\-unreachable\-branches.
.TP
\fB\-\-exclude\-function\-lines\fR
Exclude coverage from lines defining a function.
Config key(s): exclude\-function\-lines.
.TP
\fB\-\-exclude\-noncode\-lines\fR
Exclude coverage from lines which seem to be non\-code.
Negation: \fB\-\-no\-exclude\-noncode\-lines\fR. Config key(s):
exclude\-noncode\-lines.
.TP
\fB\-\-exclude\-throw\-branches\fR
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.
.PP
See <http://gcovr.com/> for the full manual.