GDSuite Docs

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

  1. the [health] section of gdsuite.toml, for a project that uses gdsuite and keeps every tool's settings in one file;
  2. 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.

FieldTypeDefaultDescription
rootstring"."Project root path. Overridden by --root flag.

[discovery]

Controls which files are discovered and analyzed.

FieldTypeDefaultDescription
includestring[]["**/*.gd"]Glob patterns for files to include
excludestring[]["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.

FieldTypeDefault
file_lines_warnint500
file_lines_criticalint1000
function_lines_warnint40
function_lines_criticalint80
cyclomatic_warnint10
cyclomatic_criticalint15
nesting_warnint4
nesting_criticalint6
parameters_warnint5

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"
FieldTypeValues
fromstringGroup name defined in [groups]
tostringGroup name defined in [groups]
severitystringinfo, 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).

FieldTypeDefaultDescription
enabledbooltrueSet false to skip git entirely (same effect as --no-git)
blame_max_file_linesint2000Skip git blame on files larger than this, to bound cost
hotspot_halflife_daysfloat60Decay half-life for the temporal hotspot score
co_change_window_daysfloat90Decay time constant for co-change weight and change entropy
co_change_max_files_per_commitint20Commits touching more files than this are excluded as mass-edit noise
prior_defect_window_daysint180Trailing 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.

FieldTypeDefaultDescription
max_cycle_filesint8Skip Break Cycle on cycles larger than this
max_cut_edgesint2Try removing up to this many edges to break a cycle (capped at 2 regardless of a higher value)
split_file_min_symbolsint4Minimum top-level symbols before Split File is attempted
split_file_modularity_gatefloat0.3Minimum 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.

FieldTypeDefaultDescription
enabledbooltrueSet false to skip duplication detection
min_token_windowint150Minimum 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).