Configuration Files¶
Warning
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:
If a --config
option is provided, that file is used.
Otherwise, a gcovr.cfg
file in the -r/--root
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.
For example, --gcov-executable
can be set via the gcov-executable
config key.
But -b/--branches
is set via txt-branch
.
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.
For example, -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.
The -j
flag is special as it takes an optional argument.
In the config file,
gcov-parallel = yes
would refer to the no-argument form,
whereas 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, …