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

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

coverage:
  default:
    files:
      include:
        - "src/main.cpp"
    functions:
      exclude:
        - "__empty_global_delete"
  targets:
    - target: "multi-file.exe"
      type: extend
      files:
        include:
          - "src/math_utils.cpp"  # Added to default includesCode language: YAML (yaml)

Result: Both main.cpp AND math_utils.cpp are tracked.

Override Mode

Completely replaces the default profile patterns for that target.

coverage:
  default:
    files:
      include:
        - "src/main.cpp"
        - "src/string_utils.cpp"
    functions:
      exclude:
        - "__empty_global_delete"
  targets:
    - target: "multi-file.exe"
      type: override
      files:
        include:
          - "src/math_utils.cpp"  # Replaces default includesCode language: YAML (yaml)

Result: ONLY math_utils.cpp is tracked (default patterns ignored).

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