Configuration Reference

covdbg uses a YAML settings file named .covdbg.yaml to define include/exclude filters, target-specific overrides, 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 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.

Quick Start Examples

Minimal Configuration

Track a single source file:

version: 1
coverage:
  default:
    files:
      include:
        - "src/main.cpp"Code language: YAML (yaml)

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"Code language: YAML (yaml)

Complete Example

version: 1
source_root: "."
baseline:
  - "build/app.exe"
settings:
  log_level: "INFO"
  log_file: "C:/logs/covdbg.log"
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"
      files:
        include:
          - "integration/**"Code language: YAML (yaml)

---

Top-Level Keys

version

Config format version. Currently only version 1 is supported.

version: 1Code language: YAML (yaml)

source_root

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

source_root: "."Code language: YAML (yaml)

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"Code language: YAML (yaml)

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"Code language: YAML (yaml)

Setting	Values	Description
log_level	TRACE, DEBUG, INFO, WARN, ERROR, NONE	Console log level (default: WARN)
log_file	File path	Custom log file path (default: %APPDATA%\Liasoft\covdbg\Logs\covdbg.log)

Note: Command-line options (--log-level, --log-file) override YAML settings.

---

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.

1. 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.

1. 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*"Code language: YAML (yaml)

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 filesCode language: YAML (yaml)

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 libraryCode language: YAML (yaml)

---

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 includesCode language: YAML (yaml)

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 includesCode language: YAML (yaml)

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

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/**"Code language: YAML (yaml)

Exclude Test Code from Coverage

Track only production code:

coverage:
  default:
    files:
      include:
        - "src/**"
      exclude:
        - "**/*_test.cpp"
        - "**/test_*.cpp"
        - "tests/**"Code language: YAML (yaml)

Exclude Generated Code

coverage:
  default:
    files:
      exclude:
        - "**/*.generated.cpp"
        - "**/moc_*.cpp"
        - "**/ui_*.h"Code language: YAML (yaml)

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/**"Code language: YAML (yaml)

---

Using the Config from CLI

Explicit path:

covdbg --config "C:\project\.covdbg.yaml" --output "results.covdb" "tests.exe"Code language: PowerShell (powershell)

Environment variable:

$env:COVDBG_CONFIG = "C:\project\.covdbg.yaml"
covdbg --output "results.covdb" "tests.exe"Code language: PowerShell (powershell)

Automatic discovery (place .covdbg.yaml next to your executable):

C:\project\build\
├── tests.exe
├── .covdbg.yaml
└── tests.pdbCode language: CSS (css)

covdbg --output "results.covdb" "C:\project\build\tests.exe"Code language: PowerShell (powershell)

---

See Also

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