Configuration Reference

covdbg uses a YAML settings file named .covdbg.yaml to define include/exclude filters, target-specific overrides, child-process following, telemetry, and logging settings.

Configuration File Resolution

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

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.

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>*"
  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.

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

baseline

Optional list of executable paths that covdbg analyzes before the normal run. Each baseline executable 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 that can be analyzed with the configured symbol backend
• 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

settings

General settings for logging and runtime behavior.

settings:
  log_level: "INFO"
  log_file: "C:/logs/covdbg.log"
  follow_children: false
  telemetry: true

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 any number of path segments (recursive)
• Patterns are matched against the normalized source file paths

Pattern examples:

• "src/**/*.cpp" - All .cpp files under src/ recursively
• "test/*.cpp" - .cpp files directly in test/ folder only
• "**/basic-1.cpp" - Any file named basic-1.cpp anywhere
• "cpp/basic-1.cpp" - Specific file path

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

---

Target-Specific Overrides

Override or extend filters 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), and target baseline entries are appended to the global baseline list.

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. If the target defines baseline, it also replaces the global baseline list for that target.

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)
• Matching is case-sensitive
• If no target matches, the default profile is used

---

Common Patterns

Focus on Your Code

Exclude third-party libraries and build artifacts:

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"

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

• CLI Reference - Command-line options
• Quick Start - Getting started
• Troubleshooting - Filter issues