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, …