# Configuration Reference

- Section: Documentation > Reference > Configuration Reference
- Canonical: https://covdbg.com/docs/reference/configuration/

---

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

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

## Quick Start Examples

### Minimal Configuration

Track a single source file:

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

### Typical Project Configuration

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

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

### Complete Example

```yaml
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.

```yaml
version: 1
```

### `source_root`

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

```yaml
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.

```yaml
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.

```yaml
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`) |
| `telemetry` | `true`, `false` | Report the run to the telemetry service afterwards (default: `true`); see the [CLI reference](/docs/reference/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](#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.

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

### File Patterns

```yaml
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:

```yaml
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.

```yaml
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.

```yaml
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:

```yaml
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:

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

### Exclude Test Code from Coverage

Track only production code:

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

### Exclude Generated Code

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

### Different Filters for Different Test Suites

```yaml
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:

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

Environment variable:

```powershell
$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
```

```powershell
cd C:\project
covdbg --output "results.covdb" "build\tests.exe"
```

---

## See Also

* [CLI Reference](/docs/reference/cli-reference/) - Command-line options
* [Quick Start](/docs/getting-started/quick-start/) - Getting started
* [Troubleshooting](/docs/reference/troubleshooting/) - Filter issues