Health settings
All gdhealth settings, in gdsuite.toml or gdhealth.toml — sections, fields, types, and defaults.
gdhealth reads its configuration from the folder it runs in (or from the path given by --config):
- the
[health]section ofgdsuite.toml, for a project that uses gdsuite and keeps every tool's settings in one file; - otherwise
gdhealth.toml.
If neither is found, built-in defaults are used — you can run gdhealth without any config file.
The sections below are the same in both files: [groups] in gdhealth.toml is [health.groups] in gdsuite.toml, [thresholds] is [health.thresholds], and so on.
Keep gdhealth's settings in one file. When gdsuite.toml has a [health] section, a gdhealth.toml next to it is ignored, with a warning: the two files are not merged.
Full example
# ── Project ──────────────────────────────────────────────────────────────────
# Optional. Overridden at runtime by --root if provided.
[project]
root = "."
# ── Discovery ─────────────────────────────────────────────────────────────────
# Glob patterns for file discovery.
# Patterns prefixed with ! are negation (exclusions within an include pattern).
[discovery]
include = ["**/*.gd"]
exclude = ["addons/**", ".godot/**", "reports/**"]
# ── Groups ───────────────────────────────────────────────────────────────────
# Named groups assign files to logical layers.
# Files not matched by any group are labelled "ungrouped" in reports.
# Group patterns are matched against project-relative paths.
[groups]
gameplay = ["*.gd", "!server/**", "!net/**", "!ai/**", "!test/**"]
net = ["net/**"]
ai = ["ai/**", "server/ai/**"]
server = ["server/**"]
test = ["test/**"]
# ── Thresholds ───────────────────────────────────────────────────────────────
# Findings below warn are ignored. Findings between warn and critical get
# severity "warning". Findings at or above critical get severity "critical".
[thresholds]
file_lines_warn = 500
file_lines_critical = 1000
function_lines_warn = 40
function_lines_critical = 80
cyclomatic_warn = 10
cyclomatic_critical = 15
nesting_warn = 4
nesting_critical = 6
# parameters_warn has no critical counterpart
parameters_warn = 5
# ── Policy ────────────────────────────────────────────────────────────────────
[policy]
# Cycles whose files all match one of these glob patterns are suppressed.
# Leave empty to report all cycles.
allow_cycles = []
# Forbidden dependency rules: if a file in group `from` depends on a file
# in group `to`, a finding with the given severity is emitted.
[[policy.forbidden_dependencies]]
from = "server"
to = "gameplay"
severity = "critical"
[[policy.forbidden_dependencies]]
from = "net"
to = "server"
severity = "warning"
# ── Git ──────────────────────────────────────────────────────────────────────
# Git-derived signals (churn hotspots, ownership, co-change, prior-defect
# history) for `gdhealth health`. Shells to the system `git` binary — no
# git2/libgit2 dependency. Disable with --no-git or enabled = false.
[git]
enabled = true
blame_max_file_lines = 2000
hotspot_halflife_days = 60
co_change_window_days = 90
co_change_max_files_per_commit = 20
prior_defect_window_days = 180
# ── Refactoring ──────────────────────────────────────────────────────────────
# Bounds for the Break Cycle and Split File refactoring suggestions.
[refactoring]
max_cycle_files = 8
max_cut_edges = 2
split_file_min_symbols = 4
split_file_modularity_gate = 0.3
# ── Duplication ──────────────────────────────────────────────────────────────
# Token-kind clone detection (renamed identifiers still match).
[duplication]
enabled = true
min_token_window = 150[project]
Optional. Rarely needed since --root overrides this at runtime.
| Field | Type | Default | Description |
|---|---|---|---|
root | string | "." | Project root path. Overridden by --root flag. |
[discovery]
Controls which files are discovered and analyzed.
| Field | Type | Default | Description |
|---|---|---|---|
include | string[] | ["**/*.gd"] | Glob patterns for files to include |
exclude | string[] | ["addons/**", ".godot/**", "reports/**"] | Glob patterns for files to exclude |
Patterns prefixed with ! inside an include list act as negations. Patterns are matched against project-relative paths.
Whatever the patterns say, discovery never enters hidden folders (names starting with ., such as .godot/, .git/ or the .gdsuite/ folder that gdsuite installs), folders containing a .gdignore file, or nested Godot projects (folders with their own project.godot). This matches what Godot's editor, gdtidy and gdtest skip.
[groups]
Named groups assign files to logical layers. Each key is a group name; the value is a list of glob patterns.
[groups]
gameplay = ["*.gd", "!server/**", "!net/**"]
net = ["net/**"]
server = ["server/**"]Files not matched by any group are labelled ungrouped in reports. Groups are referenced by name in [policy] forbidden dependency rules.
If no groups are defined, all files are ungrouped and no forbidden dependency rules can fire.
[thresholds]
Complexity thresholds that drive policy findings. Each metric has a _warn and _critical pair — findings below warn are ignored, findings between warn and critical get severity warning, findings at or above critical get severity critical.
The warn threshold must be ≤ the critical threshold or config validation fails.
| Field | Type | Default |
|---|---|---|
file_lines_warn | int | 500 |
file_lines_critical | int | 1000 |
function_lines_warn | int | 40 |
function_lines_critical | int | 80 |
cyclomatic_warn | int | 10 |
cyclomatic_critical | int | 15 |
nesting_warn | int | 4 |
nesting_critical | int | 6 |
parameters_warn | int | 5 |
parameters_warn has no _critical counterpart — parameter count findings are always warning.
[policy]
allow_cycles
Dependency cycles whose files all match at least one of these glob patterns are suppressed (not emitted as findings).
[policy]
allow_cycles = ["test/**", "tools/**"]Leave empty to report all cycles.
[[policy.forbidden_dependencies]]
Each entry defines a forbidden dependency rule. If a file in group from depends on a file in group to, a finding with the given severity is emitted.
[[policy.forbidden_dependencies]]
from = "server"
to = "gameplay"
severity = "critical"| Field | Type | Values |
|---|---|---|
from | string | Group name defined in [groups] |
to | string | Group name defined in [groups] |
severity | string | info, warning, critical |
Multiple rules are allowed. Each is independent — all matching rules fire for a given edge.
[git]
Controls the git-derived signals (churn hotspots, ownership, co-change, change entropy,
prior-defect history) computed by gdhealth health, gdhealth risk, and gdhealth validate-defects.
Shells out to the system git binary — no git2/libgit2 dependency. Experimental (see
Schema Reference).
| Field | Type | Default | Description |
|---|---|---|---|
enabled | bool | true | Set false to skip git entirely (same effect as --no-git) |
blame_max_file_lines | int | 2000 | Skip git blame on files larger than this, to bound cost |
hotspot_halflife_days | float | 60 | Decay half-life for the temporal hotspot score |
co_change_window_days | float | 90 | Decay time constant for co-change weight and change entropy |
co_change_max_files_per_commit | int | 20 | Commits touching more files than this are excluded as mass-edit noise |
prior_defect_window_days | int | 180 | Trailing window for counting fix-shaped commits per file |
If the project root isn't a git repository (or git isn't installed), gdhealth degrades gracefully —
git_available: false in health.json, no other command fails.
[refactoring]
Bounds for the Break Cycle and Split File refactoring suggestions attached to policy findings.
| Field | Type | Default | Description |
|---|---|---|---|
max_cycle_files | int | 8 | Skip Break Cycle on cycles larger than this |
max_cut_edges | int | 2 | Try removing up to this many edges to break a cycle (capped at 2 regardless of a higher value) |
split_file_min_symbols | int | 4 | Minimum top-level symbols before Split File is attempted |
split_file_modularity_gate | float | 0.3 | Minimum modularity for a Split File suggestion to fire |
[duplication]
Token-kind clone detection (Rabin-Karp rolling hash). Identifiers collapse to a single token kind, so a copy-pasted block with renamed variables still matches.
| Field | Type | Default | Description |
|---|---|---|---|
enabled | bool | true | Set false to skip duplication detection |
min_token_window | int | 150 | Minimum matching token window. Lower values catch smaller clones but produce more noise — 40 was tried and found too short in practice (idiomatic GDScript field/export boilerplate matched across unrelated files). |