Config files are an experimental feature and may be subject to change without prior notice.
Defaults for the command line options can be set in a configuration file. Example:
filter = src/ html-details = yes # info about each source file output = build/coverage.html
How the configuration file is found:
--config option is provided, that file is used.
gcovr.cfg file in the
directory is used, if that file exists.
Each line contains a
key = value pair.
Space around the
= is optional.
The value may be empty.
Comments start with a hash
# and ignore the rest of the line,
but cannot start within a word.
Empty lines are also ignored.
The available config keys correspond closely to the command line options,
and are parsed similarly.
In most cases, the name of a long command line option
can be used as a config key.
If not, this is documented in the option’s help message.
can be set via the
gcov-executable config key.
-b/--branches is set via
Just like command line options,
the config keys can be specified multiple times.
Depending on the option the last one wins or a list will be built.
-f/--filter can be provided multiple times:
# Only show coverage for files in src/, lib/foo, or for main.cpp files. filter = src/ filter = lib/foo/ filter = *./main\.cpp
Note that relative filters specified in config files will be interpreted relative to the location of the config file itself.
Option arguments are parsed with the following precedence:
- First the config file is parsed, if any.
- Then, all command line arguments are added.
- Finally, if an option was specified neither in a config file nor on the command line, its documented default value is used.
Therefore, it doesn’t matter whether a value is provided in the config file or the command line.
Boolean flags are treated specially.
When their config value is “yes” they are enabled,
as if the flag had been provided on the command line.
When their value is “no”, they are explicitly disabled
by assigning their default value.
-j flag is special as it takes an optional argument.
In the config file,
gcov-parallel = yes would refer to the no-argument form,
gcov-parallel = 4 would provide an explicit argument.
If the option is a path and is not absolute the path is used relative to
the config file. For the option
gcovr --json-add-tracefile the
directory of the config file is always prepended.
Some config file syntax is explicitly reserved for future extensions: Semicolon comments, INI-style sections, multi-line values, quoted values, variable substitutions, alternative key–value separators, …