Configuration Reference

covdbg uses a YAML settings file named .covdbg.yaml to define include/exclude filters, the source lines to leave out, the shared libraries (DLLs) to measure, target-specific overrides, child-process following, telemetry, and logging settings.

Configuration File Resolution

covdbg resolves the configuration file using this precedence (first match wins):

Priority Source Description
1 --config CLI option specifying path to config file
2 COVDBG_CONFIG Environment variable with path to config file
3 Auto-discovery .covdbg.yaml in the working directory covdbg is started from
4 Auto-discovery .covdbg.yaml in the same directory as the target executable

Important: A configuration file is required. If no configuration file is found or cannot be loaded (file not found or invalid YAML), covdbg exits with an error. The error names the file and gives the parser's reason, with its line and column, such as a value of the wrong type. From covdbg 1.5.1, an auto-discovered .covdbg.yaml that cannot be loaded stops the run too: covdbg no longer passes over it to the next place, nor ends with "No configuration file found".

From covdbg 1.5.1, a key whose value has the wrong shape is refused rather than ignored: a single value where a list belongs (include: "src/**", baseline: app.exe, exclude_lines: '.*NOCOV'), a list where a map belongs (files: ["src/**"]), or a map or list inside a list of patterns. covdbg names the key and where its value is, such as Invalid coverage.default.files.include at line 5, column 16: expected a list, found a single value 'src/**', and exits with code 1. A single value is not taken as a one-item list: write include: ["src/**"], or each entry on a line of its own after - . A key with no value at all (include: with nothing after it) is still accepted and means no entries, as [] does.

From covdbg 1.5.1, covdbg warns about a key it does not know, for a run and for covdbg analyze, on stderr and in the log, and names the key with its path, line and column. For a key close to a known one it suggests that one: Warning: Unknown key coverage.default.exclude_line at line 7, column 5: covdbg ignores it; did you mean 'exclude_lines'?. The run goes on, so a configuration written for a newer covdbg still runs. A version other than 1, a type other than extend or override, and a targets: entry without target: are refused, as a value of the wrong shape is, with the key, its line and column, and exit code 1. Before, covdbg ignored an unknown key, read the first two as 1 and extend, and dropped the entry.

Quick Start Examples

Minimal Configuration

Track a single source file:

version: 1
coverage:
  default:
    files:
      include:
        - "src/main.cpp"

Typical Project Configuration

Track all source files, exclude build artifacts and system code:

version: 1
coverage:
  default:
    files:
      include:
        - "src/**/*.cpp"
        - "src/**/*.h"
      exclude:
        - "build/**"
        - "third_party/**"
    functions:
      exclude:
        - "__empty_global_delete"

Complete Example

version: 1
source_root: "."
baseline:
  - "build/app.exe"
settings:
  log_level: "INFO"
  log_file: "C:/logs/covdbg.log"
  follow_children: false
  telemetry: true
coverage:
  default:
    files:
      include:
        - "src/**/*.cpp"
        - "src/**/*.h"
        - "lib/**/*.cpp"
      exclude:
        - "build/**"
        - "third_party/**"
        - "**/*_test.cpp"
    functions:
      include:
        - "*"
      exclude:
        - "operator*"
        - "*::<lambda>*"
    modules:
      include:
        - "mylib*.dll"
        - "*_tests.exe"    # The test executables too, measured only when selected
  targets:
    - target: "integration_tests.exe"
      type: override
      baseline:
        - "build/integration_app.exe"
      settings:
        follow_children: true
      files:
        include:
          - "integration/**"

Top-Level Keys

version

Config format version. Currently only version 1 is supported. From covdbg 1.5.1, any other value is refused: Invalid version at line 1, column 10: expected a whole number, found 'abc'. An empty version:, or none, means 1.

version: 1

source_root

Base directory used to resolve and normalize source paths. Useful when PDBs contain absolute paths from other machines (CI builds).

source_root: "."

Behavior:

  • Relative paths are resolved relative to the config file's directory
  • Absolute paths are used as-is
  • Affects how source files appear in coverage exports
  • Names the repository a run is licensed for: the git checkout around the source root, found by walking up from it (from covdbg 1.5.1), so a config in a subfolder of a checkout counts for that checkout. See which repository a run is licensed for

baseline

Optional list of binaries (executables or DLLs) that covdbg analyzes before the normal run. Each baseline binary produces an internal zero-hit .covdb database, then covdbg runs the requested target and merges the baseline databases with the runtime database into the --output file.

baseline:
  - "build/app.exe"
  - "build/tools/helper.exe"

Behavior:

  • Relative paths are resolved relative to the config file's directory
  • Paths must point to executables or DLLs that can be analyzed with the configured symbol backend
  • A DLL listed here shows at 0% when the run never loads it; when the run does load and measure it, its hits are merged in
  • Run mode requires --output when baseline contains entries because the final result is a merged .covdb
  • baseline: [] is valid and disables baseline analysis
  • Target overrides can also define baseline; type: extend appends to the global list, while type: override replaces it for that target
  • Each baseline binary is filtered by the targets: entry for its own file name, found as described in Target Matching, without regard to case

settings

General settings for logging and runtime behavior.

settings:
  log_level: "INFO"
  log_file: "C:/logs/covdbg.log"
  follow_children: false
  telemetry: true
Setting Values Description
log_level TRACE, DEBUG, INFO, WARN, ERROR, NONE Log file level (default: DEBUG; NONE writes no log file)
log_file File path Custom log file path (default: .covdbg\Logs\covdbg.log in the working directory)
follow_children true, false Also instrument the processes the target spawns, and theirs in turn, and merge their coverage into the output (default: false). A target with no symbols of its own, such as ctest.exe, then runs unmeasured and only the processes it starts are measured
telemetry true, false Report the run to the telemetry service afterwards (default: true); see the CLI reference for what is sent

Note: Command-line options (--log-level, --log-file, --follow-children) and their environment variables override YAML settings; --follow-children and COVDBG_FOLLOW_CHILDREN can only turn following on. A target-specific settings block (see Per-Target Settings) overrides follow_children for one executable.


Coverage Filters

How Filtering Works

The filtering logic follows a specific precedence:

  1. Include patterns: If include patterns are specified, ONLY files/functions matching at least one include pattern are considered. If no include patterns are specified, ALL files/functions are included by default.

  2. Exclude patterns: Exclude patterns ALWAYS take precedence over include patterns. If a file/function matches any exclude pattern, it is excluded regardless of whether it matched an include pattern.

  3. Evaluation order:

    • Check if file/function matches any include pattern (or all if no includes)
    • If included, check if it matches any exclude pattern
    • If it matches an exclude pattern, it is excluded (exclude wins)
    • Otherwise, it is included

coverage.default

The default coverage profile applied to all targets unless overridden.

coverage:
  default:
    files:
      include:
        - "src/**"
      exclude:
        - "build/**"
    functions:
      include:
        - "*"
      exclude:
        - "operator*"

File Patterns

coverage:
  default:
    files:
      include:
        - "src/**/*.cpp"   # All .cpp files under src/
        - "lib/**"          # Everything under lib/
      exclude:
        - "build/**"        # Exclude build directory
        - "**/test_*"       # Exclude test files

Pattern syntax:

  • * - Match any characters within a path segment
  • ? - Match one character; [abc], [a-z] and [!a-z] match one character of a class
  • ** - Match any number of path segments (recursive)
  • Patterns are taken relative to the directory that holds the config file (the base directory) and matched against the source file's path as the PDB records it, ignoring case as Windows compares file names: letters outside ASCII too (Ä and ä, Ω and ω), without a language's rules (the Turkish İ and ı are letters of their own). \ and / are the same. Changed in 1.5.1: only ASCII letters matched in any case.

How a pattern is anchored:

  • For a path below the base directory, the pattern is matched against the path relative to it:
    • A pattern with a / at the start or in the middle is anchored to the base directory: src/**/*.cpp and /src/**/*.cpp match <base>/src/app/main.cpp, but not <base>/lib/src/x.cpp.
    • A pattern without a / (*.cpp, main.cpp, third_party), or one that starts with **/ (**/tests/**), matches at any depth.
    • Directory names above the base directory play no part: with the config file in C:\agent\_work\build\proj, build/** matches C:\agent\_work\build\proj\build\... only.
  • A path outside the base directory is a source recorded where the binary was built (another checkout, another machine, a CI runner), a runtime or SDK source a PDB records, or a system DLL.
    • In files:, a pattern rooted at the base directory never matches it, whatever directory names its path has: ** itself, and every pattern with a / that does not start with **/ (src/**, src/*.cpp, /src/**). With the config file in C:\repo, src/** matches C:\repo\src\a.cpp, never D:\a\_work\1\s\src\vctools\..., and ** selects every file below C:\repo and nothing else.
    • A pattern that starts with **/ (**/vctools/**, **/include/mylib/**), or one without a / other than ** (*.cpp, pow.c, *), is tried against the full path and against each part of it after a /: it matches at any depth outside the base directory too. That is how an exclude like **/vctools/** removes the runtime's sources, and how an include can select sources outside the base directory on purpose.
    • A source path the PDB records relative (OSS\ARM-software\..., VCCRT\..., as the runtime records some of its own) is outside the base directory: it is not taken relative to the base directory or to source_root, so a rooted pattern never matches it. The exception is a build that trims its source paths: with source_root, covdbg reads such a path from there when the file is there, and it is then below the source root.
    • With source_root above the config file's directory (a config in C:\repo\conf with source_root: ".."), a path below the source root but outside the base directory is matched as before 1.5.1: every pattern but one with a leading / is tried against the full path and each part of it after a /.
    • In modules:, every pattern but one with a leading / is tried against the full path and each part of it after a /, so a bare DLL name still selects a DLL in a system directory.
  • A pattern matches a path and everything below it: build matches <base>/build/a.cpp and <base>/src/build/gen.cpp. A trailing / is dropped (build/ matches like build) and does not count as a / for anchoring; out/bin/ is anchored.
  • !pattern takes a path back out of the list; within one list the last pattern that matches decides. Exclude wins over include.
  • An absolute pattern (C:/Windows/System32/*.dll) is matched against the full path.

Pattern examples:

  • "src/**/*.cpp" - All .cpp files under src/ next to the config file, recursively
  • "test/*.cpp" - .cpp files directly in test/ next to the config file only
  • "**/basic-1.cpp" - Any file named basic-1.cpp anywhere
  • "cpp/basic-1.cpp" - cpp/basic-1.cpp next to the config file; "**/cpp/basic-1.cpp" matches it in any directory

Changed in 1.5.0: patterns change meaning only for paths below the config file's directory; paths outside it match as before. Before, only a leading / anchored a pattern, and every other pattern was matched against the full path and each part of it after a / for those paths too, so src/**/*.cpp also matched <base>/third_party/x/src/a.cpp. The names of the directories above the base directory counted too: with the config file under D:\build\..., build/**/*.dll in modules: selected every DLL in the checkout, and build/** in files: exclude: excluded every source file, so the same config gave different coverage on different machines. A pattern that relied on matching deeper below the base directory keeps its old meaning with **/ in front: src/foo/*.cpp becomes **/src/foo/*.cpp.

Changed in 1.5.1: in files:, a pattern rooted at the base directory (** itself, or one with a / that does not start with **/) no longer matches a path outside the base directory, nor a relative path. Before, include: ["**"] selected every source of the program's PDBs: the MSVC runtime and Windows SDK sources recorded on the toolchain's build drive (D:\a\_work\1\s\...) and those recorded by relative paths (OSS\ARM-software\..., VCCRT\...), which then looked like files of the repository in Cobertura and LCOV. And src/** matched the src in D:\a\_work\1\s\src\....

  • OpenCppCoverage's --sources <checkout root> is include: ["**"] in a .covdbg.yaml at that root, with source_root: ".". It needs no excludes for the runtime and SDK sources. Its --excluded_line_regex <regex> is an entry of exclude_lines (see Excluding Lines).
  • A pattern meant to select files outside the base directory takes **/ in front (third_party/zlib/** becomes **/third_party/zlib/**), or names them by their absolute path (D:/deps/zlib/**).
  • A config file in a subdirectory of the checkout has the checkout's other directories outside its base directory: its patterns for them take **/ in front too.
  • A build measured in another checkout (a CI test job on another runner) records its sources outside the base directory. With source_root set, covdbg reads them from below the source root, where rooted patterns match them. Where the build's checkout is still on the machine (several runners on one machine), its sources are measured there, outside the base directory, and only patterns that start with **/ select them (**/src/**/*.cpp).
  • modules: patterns are matched as before. What modules: selects changed in 1.5.1, see Shared Library Patterns.
  • A file outside source_root that a pattern does include is named by its absolute path in Cobertura (D:/a/_work/1/s/src/...), as in LCOV, not by a drive and a path that looks repository-relative. A source the PDB records by a relative path has no other path to give, and keeps that one.

Function Patterns

Filter which functions are tracked:

coverage:
  default:
    functions:
      include:
        - "*"              # Include all functions
      exclude:
        - "operator*"      # Exclude operators
        - "*::<lambda>*"   # Exclude lambdas
        - "std::*"         # Exclude std library

Function patterns are case-sensitive, unlike file and module patterns: std::* does not match Std::vector.

Shared Library Patterns

By default covdbg measures only the executable it launches. Code in shared libraries (a DLL your tests link against, a plugin loaded with LoadLibrary, a Python extension) runs, but is not measured, and its source files never enter the database. Select the modules to measure under modules: the libraries, and, from covdbg 1.5.1, the executable too:

coverage:
  default:
    files:
      include:
        - "src/**/*.cpp"
    modules:
      include:
        - "mylib*.dll"                # By file name, in any directory
        - "build/**/plugins/*.dll"    # By path, relative to the config file
        - "mylib_tests.exe"           # The executable, measured only when a pattern selects it
      exclude:
        - "mylib-thirdparty.dll"

Behavior:

  • Libraries are opt-in. Unlike file and function patterns, a missing or empty modules.include selects no library at all. Without a modules section, covdbg measures the executable and no library.
  • With modules.include, the executable is a module like the libraries: it is measured only when a pattern selects it (include: ["mylib*.dll", "mylib_tests.exe"]), and so is the executable of each followed child process. modules.exclude leaves an executable out, with or without an include list. A target's own modules (see Target-Specific Overrides) applies to its executable as to its libraries.
  • An executable left out still runs under covdbg, unmeasured: the libraries it loads are instrumented as they load, and with follow_children its children are followed. Its PDB is not read.
  • Patterns use the file pattern syntax and are matched against the module's full path (the DLL's, or the executable's), ignoring case as Windows compares file names, letters outside ASCII included (from covdbg 1.5.1; see File Patterns). A pattern without a / matches the file name in any directory, system directories included; for a DLL below the config file's directory, one with a / at the start or in the middle is anchored to that directory (see File Patterns). Exclude wins over include.
  • File and function patterns still decide which code is measured: a selected library contributes only functions whose source files pass files, so its sources must be included too.
  • A selected library is instrumented as soon as Windows maps it, before any of its code (including DllMain) runs. This holds for DLLs the executable imports and for DLLs loaded later with LoadLibrary. A library unloaded before the process exits keeps the coverage it collected.
  • Each library appears in the database as its own module, beside the executable when that is measured.
  • A selected library without a PDB, or whose sources are all excluded, is left unmeasured. "*.dll" is therefore safe, but slower, and covdbg reports each system DLL whose PDB it cannot find.
  • With follow_children, the same selection applies to every followed process: to its executable and to its libraries.
  • When libraries are selected, the executable itself may be left out, or have nothing to measure, for example a test host or python.exe. covdbg then runs it unmeasured and measures only the libraries. If no selected library with functions to track was loaded either, nothing was measured: the program still runs, covdbg writes an empty database and exits 2, and says why, for example mylib_tests.exe is not selected under modules: in .covdbg.yaml (see Nothing Measured).
  • follow_children works the same way for a launcher: an executable with nothing to measure, such as ctest.exe or cmd.exe, runs unmeasured and the processes it starts are measured. If none of them had functions to track either, nothing was measured, as above.
  • A library the run never loads is not in the database at all. List it under baseline to have it reported at 0%.

Changed in 1.5.1: the executable, and the executable of each followed child process, was always measured beside the selected libraries, and naming it under modules.exclude changed nothing. Where it compiled in sources a selected library has too (a shared core/ library, a header-only dependency), their lines and hits were merged with the library's. A modules.include that lists only libraries ("mylib.dll", "*.dll") now measures those libraries alone. To keep measuring the executable, add its name: include: ["*.dll", "mylib_tests.exe"].

Coming from OpenCppCoverage:

  • --modules mylib.dll is modules: include: ["mylib.dll"], which measures the library alone, not the program that loads it.
  • OpenCppCoverage matches --modules anywhere in the module's path; covdbg's patterns are globs (see File Patterns), so --modules mylib is "*mylib*".
  • --cover_children is --follow-children, or follow_children in .covdbg.yaml.

Excluding Lines

From covdbg 1.5.1. Single source lines can be left out of coverage: by regular expressions under exclude_lines, as OpenCppCoverage's --excluded_line_regex does, and by the marker comments that lcov and gcovr read, which work without any configuration.

version: 1
source_root: "."
coverage:
  default:
    files:
      include: ["**"]
    exclude_lines:              # OpenCppCoverage: --excluded_line_regex, once for each
      - '\s*else.*'
      - '\s*\}.*'
      - '\s*\{\s*'
    exclusion_markers: true     # the default; false turns the marker comments off
Key Values Description
exclude_lines List of regular expressions A line that one of them matches as a whole is excluded (default: none)
exclusion_markers true, false Read the marker comments in the sources (default: true)
marker_patterns Marker names and regular expressions Other words for the markers, as lcovrc's lcov_excl_line and its other settings give them (default: lcov's and gcovr's own)

An excluded line is not an executable line. It is not in the .covdb database at all, so it is in no report and no total made from it: Cobertura, LCOV, GCOV, HTML, and the summary covdbg prints after the run. A function whose lines are all excluded is left out of the functions, as gcovr leaves it out, and a basic block whose lines are all excluded is not measured. A function that keeps a line keeps its name and its other lines.

exclude_lines

  • Each entry is an ECMAScript regular expression (C++'s std::regex, which OpenCppCoverage uses too) that must match the whole line, as OpenCppCoverage's std::regex_match does. \s*else.* needs no ^ or $; else alone matches only a line that is else and nothing else; .*// NOCOV matches a line that ends with that comment.

  • The line is its bytes as the file has them (UTF-8 for most sources), without its \r\n or \n. A line is excluded when any pattern matches it.

  • Write the patterns in single quotes. YAML keeps a backslash in single quotes as it is ('\s*\{\s*'), where double quotes take \s for an escape and the file is refused.

  • A pattern that is not a regular expression is refused when the configuration is read, and covdbg does nothing (exit code 1):

    covdbg: Invalid regular expression '\s*(else' in coverage.default.exclude_lines: regex_error(error_paren): The expression contained mismatched ( and ).

Marker Comments

covdbg reads the marker comments as lcov 2's geninfo reads them. A marker is a whole word anywhere in its line, in a comment as a rule. The markers that gcovr knows as well are also read with gcovr's default prefixes, GCOVR_, GCOV_ and LCOVR_ (gcovr's --exclude-pattern-prefix '[GL]COVR?').

Marker Effect in covdbg
LCOV_EXCL_LINE Excludes its line
LCOV_EXCL_START ... LCOV_EXCL_STOP Excludes the lines from the start marker's line to the line before the stop marker's: the stop marker's line is not excluded
LCOV_UNREACHABLE_LINE Excludes its line, which should never run. If it runs, the run reports it
LCOV_UNREACHABLE_START ... LCOV_UNREACHABLE_STOP Excludes a region of such lines, as LCOV_EXCL_START does
GCOVR_EXCL_FUNCTION On the line a function starts on, excludes that function: all its lines, and with them the function itself
LCOV_EXCL_BR_LINE, LCOV_EXCL_BR_START ... LCOV_EXCL_BR_STOP Branch markers: no effect, see below
LCOV_EXCL_EXCEPTION_BR_LINE, LCOV_EXCL_EXCEPTION_BR_START ... LCOV_EXCL_EXCEPTION_BR_STOP Branch markers: no effect
GCOVR_EXCL_BR_SOURCE, GCOVR_EXCL_BR_WITHOUT_HIT: n/m gcovr's branch markers: no effect

LCOV_EXCL_*, LCOV_EXCL_BR_* and the function marker are also read as GCOVR_EXCL_*, GCOV_EXCL_* and LCOVR_EXCL_*. The spellings are one marker, so a GCOVR_EXCL_STOP ends a region an LCOV_EXCL_START began. The unreachable and exception markers are lcov's alone.

int Parse(char const* text)
{
    if (text == nullptr)
    {
        return Fail("no text"); // LCOV_EXCL_LINE
    }
    // LCOV_EXCL_START
    if (Trace())
    {
        Dump(text);
    }
    // LCOV_EXCL_STOP
    switch (Kind(text))
    {
    case 'a': return 1;
    case 'b': return 2;
    default: std::abort(); // LCOV_UNREACHABLE_LINE
    }
}

void DebugOnly() // GCOVR_EXCL_FUNCTION
{
    Dump("state");
}

How a source's markers are read, as in lcov:

  • LCOV_EXCL_START and LCOV_UNREACHABLE_START share one region. A start marker within a region starts it again, from its own line. A stop marker without a start, or of the other kind (an LCOV_UNREACHABLE_STOP in an LCOV_EXCL_START region), ends the region. covdbg reports both.
  • A line changes the region once: when it has a start and a stop marker, its start marker counts.
  • Of a single line, its own _EXCL_LINE marker decides first, then its LCOV_UNREACHABLE_LINE, then the exclude_lines patterns, and then the region it is in. A line with LCOV_EXCL_LINE in an unreachable region is an excluded line, not an unreachable one.
  • A region that is not closed runs to the end of the file, and covdbg reports it. gcovr excludes nothing for such a region.
  • A start marker within a region does not nest, as it does in gcovr: the first stop marker ends the region.

What covdbg reports: lcov stops with a mismatch or unreachable error unless it runs with --ignore-errors. covdbg prints the same findings and goes on; they do not change its exit code. A file is read once per binary, so a source that several test executables share is reported for each of them.

covdbg: D:\src\parse.cpp: LCOV_EXCL_START on line 40 has no stop marker; the lines to the end of the file are excluded
covdbg: D:\src\parse.cpp: LCOV_EXCL_STOP on line 52 ends no region
covdbg: D:\src\parse.cpp: LCOV_EXCL_START on line 60 is in the region LCOV_EXCL_START started on line 55, which it starts again
covdbg: D:\src\parse.cpp: LCOV_UNREACHABLE_STOP on line 70 ends the region LCOV_EXCL_START started on line 66, which is of the other kind
covdbg: D:\src\parse.cpp:23: a line marked unreachable ran
covdbg: D:\src\parse.cpp:27: GCOVR_EXCL_FUNCTION is on no line a function starts on; it excludes nothing

Unreachable lines: covdbg excludes them, and still watches the code they are on. When one runs, the run names it, as lcov reports a hit in an unreachable region. lcov then keeps the line in its report by default (retain_unreachable_coverpoints_if_executed = 1); covdbg keeps it excluded. A wrong marker therefore shows on the console, not as a changed percentage. covdbg analyze runs nothing, so it reports none.

The function marker excludes the function whose first line is the marker's line. MSVC gives a function the line of its opening brace as its first, so the marker may also be on the line before that brace, when the brace stands on a line of its own (blank lines between them are fine). A function defined inside the excluded one, such as a lambda, keeps the lines that are its own. Template instantiations of one function are all excluded. A marker on a line no function starts on excludes nothing and is reported.

Branch markers exclude branches and never lines, in lcov as in gcovr. covdbg measures lines and basic blocks, not branches (its Cobertura reports a branch-rate of 0 and its LCOV export has no BRDA records), so it reads branch markers as having nothing to exclude. They neither exclude a line nor end a region, and are not reported, as lcov ignores them when branch coverage is off.

Turning the markers off: exclusion_markers: false turns all of them off, as lcov's --no-markers does; exclude_lines still applies.

marker_patterns

lcov lets an lcovrc file change the words it reads as markers, and gcovr its prefix. marker_patterns does the same, by lcovrc's setting names without their lcov_. Each value is a regular expression that covdbg looks for as a whole word, and it replaces that marker's default; an empty value ('') turns that marker off. The markers a profile does not name keep their defaults.

Key lcovrc setting Default
excl_line lcov_excl_line [GL]COVR?_EXCL_LINE
excl_start lcov_excl_start [GL]COVR?_EXCL_START
excl_stop lcov_excl_stop [GL]COVR?_EXCL_STOP
unreachable_line lcov_unreachable_line LCOV_UNREACHABLE_LINE
unreachable_start lcov_unreachable_start LCOV_UNREACHABLE_START
unreachable_stop lcov_unreachable_stop LCOV_UNREACHABLE_STOP
excl_function none (gcovr's marker) [GL]COVR?_EXCL_FUNCTION
excl_br_line lcov_excl_br_line [GL]COVR?_EXCL_BR_LINE
excl_br_start lcov_excl_br_start [GL]COVR?_EXCL_BR_START
excl_br_stop lcov_excl_br_stop [GL]COVR?_EXCL_BR_STOP
excl_exception_br_line lcov_excl_exception_br_line LCOV_EXCL_EXCEPTION_BR_LINE
excl_exception_br_start lcov_excl_exception_br_start LCOV_EXCL_EXCEPTION_BR_START
excl_exception_br_stop lcov_excl_exception_br_stop LCOV_EXCL_EXCEPTION_BR_STOP

The branch marker keys are accepted, and checked, so that an lcovrc translates in full, but change nothing while covdbg records no branches.

coverage:
  default:
    marker_patterns:
      excl_line: 'LCOV_EXCL_LINE|NO_COVERAGE'   # lcovrc: lcov_excl_line = LCOV_EXCL_LINE|NO_COVERAGE
      excl_start: 'BEGIN_NO_COVERAGE'
      excl_stop: 'END_NO_COVERAGE'
      unreachable_line: ''                      # turns LCOV_UNREACHABLE_LINE off

A key that is no marker's name, or a value that is not a regular expression, is refused when the configuration is read (exit code 1):

covdbg: Invalid pattern 'NOCOV' of lcov_excl_line in coverage.default.marker_patterns: there is no marker 'lcov_excl_line'; the markers are excl_line, excl_start, ...

Where the Source Is Read

covdbg reads each source when it records the program's lines: in a run, in covdbg analyze, and for a baseline binary. It reads the file where the configuration finds it, under source_root when the build's checkout is not on this machine. A source covdbg cannot read keeps all its lines.

The database holds only the lines that are left, so covdbg convert and covdbg merge need no configuration. Databases written with different exclusions are merged as they are: a line that any of them has is a line of the result.

A target's entry under targets extends or overrides exclude_lines like files (see Target-Specific Overrides), and its exclusion_markers and each of its marker_patterns win in either mode.

Coming from OpenCppCoverage, lcov or gcovr

  • OpenCppCoverage: each --excluded_line_regex <regex> is an entry of exclude_lines, unchanged. Both tools match a pattern against the whole line with the same regular expression engine. OpenCppCoverage reads no marker comments; to exclude exactly what it excluded, set exclusion_markers: false. Boost's ci/opencppcoverage.ps1 (boost-ci) passes these, the first of which covdbg's markers cover anyway:

        exclude_lines:
          - '.*// LCOV_EXCL_LINE'
          - '.*// coverity\[dead_error_line\]'
          - '\s*[}{]*\s*'
          - '\s*(\} )?else( \{)?\s*'
  • lcov: the markers mean what they mean to lcov 2. An lcovrc's lcov_excl_line and the other marker settings go under marker_patterns, and --no-markers is exclusion_markers: false. lcov's --omit-lines (lcovrc omit_lines) is different from exclude_lines: its Perl regular expression may match any part of the line, so --omit-lines 'NOCOV' excludes every line with NOCOV in it. As an exclude_lines entry it needs .* around it: '.*NOCOV.*'. For lcov's --erase-functions, use functions: exclude:, whose patterns are wildcards, not regular expressions.

  • gcovr: GCOVR_EXCL_*, GCOV_EXCL_* and LCOV_EXCL_* markers work as they are. A project that sets --exclude-pattern-prefix MYPROJ lists its markers under marker_patterns (excl_line: 'MYPROJ_EXCL_LINE', and so on). gcovr's --exclude-lines-by-pattern matches from the start of the line but not to its end, so an exclude_lines entry needs .* at the end. Where gcovr and lcov differ, covdbg follows lcov: a marker must be a whole word, a start within a region does not nest, and a region that is not closed runs to the end of the file. For gcovr's --exclude-function, use functions: exclude:.


Target-Specific Overrides

Override or extend filters, shared library selections, and baseline binaries for specific executables. Two modes are available:

Extend Mode (default)

Adds patterns to the default profile. Include patterns are merged (OR logic), exclude patterns are merged (any match excludes), modules patterns are merged the same way, exclude_lines patterns are appended to the default ones, and target baseline entries are appended to the global baseline list. A target's exclusion_markers replaces the default's, and so does each marker it names under marker_patterns.

baseline:
  - "src/app.exe"
coverage:
  default:
    files:
      include:
        - "src/main.cpp"
    functions:
      exclude:
        - "__empty_global_delete"
  targets:
    - target: "multi-file.exe"
      type: extend
      baseline:
        - "src/math_utils.exe"
      files:
        include:
          - "src/math_utils.cpp"  # Added to default includes

Result: Both main.cpp AND math_utils.cpp are tracked, and both src/app.exe and src/math_utils.exe are analyzed for baseline coverage when running multi-file.exe.

Override Mode

Completely replaces the default profile patterns for that target. files, functions, modules, and exclude_lines are each replaced only when the target defines them. If the target defines baseline, it also replaces the global baseline list for that target. exclusion_markers and marker_patterns work as in extend mode: what the target sets wins, and the rest comes from the default profile.

baseline:
  - "src/app.exe"
coverage:
  default:
    files:
      include:
        - "src/main.cpp"
        - "src/string_utils.cpp"
    functions:
      exclude:
        - "__empty_global_delete"
  targets:
    - target: "multi-file.exe"
      type: override
      baseline:
        - "src/math_utils.exe"
      files:
        include:
          - "src/math_utils.cpp"  # Replaces default includes

Result: ONLY math_utils.cpp is tracked (default patterns ignored), and only src/math_utils.exe is analyzed for baseline coverage.

Per-Target Settings

A target can carry its own settings block. Only follow_children is read there; it replaces the global value for that executable in both extend and override mode:

settings:
  follow_children: false
coverage:
  default:
    files:
      include:
        - "src/**"
  targets:
    - target: "integration_tests.exe"
      settings:
        follow_children: true   # This runner launches the program under test

Result: Only integration_tests.exe follows the processes it spawns; every other target is measured on its own. Following costs analysis and instrumentation for each child, so keep it to the targets that need it.

Target Matching

  • target is matched against the executable filename (e.g., my_tests.exe). For a program run by its name alone, that is the file covdbg found on PATH, so covdbg ctest matches target: "ctest.exe" (from covdbg 1.5.1; see Finding the Program)
  • The name is compared as Windows compares file names: without regard to case, letters outside ASCII included, and with any 8.3 short name written out first. My_Tests.EXE gets the entry target: "my_tests.exe". The program is still shown and recorded by its name as it is spelled on disk
  • The binaries under baseline and the --input of covdbg analyze find their entry the same way
  • If no target matches, the default profile is used
  • Each entry needs a target: with the program's file name, and its type, if given, is extend (the default) or override. From covdbg 1.5.1, an entry without target: and any other type are refused, naming the line: Invalid type of target 'my_tests.exe' at line 9, column 13: expected extend or override, found 'overide'

Changed in 1.5.1: the name had to match in case too, so a program started as My_Tests.exe did not get the settings of target: "my_tests.exe".

Entries that differ only in case

Two entries whose names differ only in case, or are the same, name the same program. The first one in the file counts, all of it: the other's files, modules, baseline and settings do not fill in what the first leaves out. covdbg warns about each such entry when it loads the configuration, for a run and for covdbg analyze, on stderr and in the log, naming both entries and the one it uses:

Warning: targets: entries 'My_Tests.exe' and 'my_tests.exe' differ only in case and name the same program; covdbg uses the first, 'My_Tests.exe'
Warning: targets: names 'other_tests.exe' twice; covdbg uses the first entry

Keep one entry per program. Changed in 1.5.1: an entry applied only to a program whose name matched it in case, and covdbg said nothing about an entry that repeated another; follow_children came from the first matching entry that set it.


Common Patterns

Focus on Your Code

Exclude third-party libraries and build artifacts. Patterns such as build/** and third_party/** mean those directories next to the config file; use **/build/** to match them at any depth:

version: 1
source_root: "."
coverage:
  default:
    files:
      include:
        - "src/**"
      exclude:
        - "build/**"
        - "third_party/**"
        - "external/**"
        - "vendor/**"

Exclude Test Code from Coverage

Track only production code:

coverage:
  default:
    files:
      include:
        - "src/**"
      exclude:
        - "**/*_test.cpp"
        - "**/test_*.cpp"
        - "tests/**"

Exclude Generated Code

coverage:
  default:
    files:
      exclude:
        - "**/*.generated.cpp"
        - "**/moc_*.cpp"
        - "**/ui_*.h"

Measure a DLL Your Tests Load

Test executables that link against your library, or load it as a plugin:

coverage:
  default:
    files:
      include:
        - "src/**"
    modules:
      include:
        - "mylib.dll"
  targets:
    - target: "plugin_tests.exe"
      type: extend
      modules:
        include:
          - "myplugin.dll"   # Only this test suite loads the plugin

This measures the libraries alone, not the test executables that load them. To measure those too, add their names under include, such as "*_tests.exe".

Different Filters for Different Test Suites

coverage:
  default:
    files:
      include:
        - "src/**"
  targets:
    - target: "unit_tests.exe"
      type: override
      files:
        include:
          - "src/core/**"
    - target: "gui_tests.exe"
      type: override
      files:
        include:
          - "src/ui/**"

Using the Config from CLI

Explicit path:

covdbg --config "C:\project\.covdbg.yaml" --output "results.covdb" "tests.exe"

Environment variable:

$env:COVDBG_CONFIG = "C:\project\.covdbg.yaml"
covdbg --output "results.covdb" "tests.exe"

Automatic discovery (place .covdbg.yaml in the directory you run covdbg from, usually the repository root; a copy next to the executable is found when the working directory has none):

C:\project\
├── .covdbg.yaml
└── build\
    ├── tests.exe
    └── tests.pdb
cd C:\project
covdbg --output "results.covdb" "build\tests.exe"

See Also