Configuration reference

Configuration reference

Optional, at the repo root. Every tool works with stock defaults; a section overrides only what it names, and a repo with no godot-devkit.toml behaves byte-identically to one declaring the defaults. check <gate> --help prints each gate's section in full.

The block below is src/godot_devkit/data/godot-devkit.example.toml in the repo, one example of every key a reader accepts. A test keeps it complete: a new config key lands with its example in the same PR.

[roster]
checks = ["uid", "tres", "props"]  # narrows `check all` for THIS repo (stock: all eight);
                                   # an unknown name exits 2
[checks]
godot = ["uid", "tres", "props"]   # 3.x only: the pre-3.0 spelling of `[roster] checks`, read
                                   # with a deprecation line; removed in 4.0

[uid]
exclude_prefixes = ["addons/"]     # scopes every uid check
[tres]
exclude_prefixes = ["addons/"]
baseline = { "scenes/legacy/hub.tscn" = 7 }   # existing debt, per file at its CURRENT finding
                                   # count; held and counted every run, and only shrinks
[props]
exclude_prefixes = ["addons/"]
baseline = { "scenes/legacy/hub.tscn" = 2 }
extra_properties = { MyWidget = ["virtual_prop"] }   # a `_get_property_list` shape the scanner
                                   # cannot see; the key is the class_name (or an ancestor's) or
                                   # the engine type, and the carve-out applies only to it
[defaults]
exclude_prefixes = ["addons/"]
baseline = { "data/enemies/grunt.tres" = 3 }
[canonical]                         # opt-in: name it in [roster] checks to run it in `check all`
exclude_prefixes = ["addons/"]
[rng]
roots = ["systems/run/"]           # stock ".": keep it NARROW — the roots that hold run-scoped randomness
allowlist = { "systems/run/dice.gd:roll" = "a cosmetic jitter; the reason is required" }
baseline = { "systems/run/loot_roll.gd" = 4 }
[tres_comment]
exclude_prefixes = ["addons/"]
baseline = { "data/legacy/tuning.tres" = 12 }
[unit_disk]
roots = ["tests/unit"]
forbidden_literals = { "a real save path" = ["user://saves/", "user://settings\\.json"] }
                                   # a TABLE, reason = [regexes], like forbidden_calls — not a
                                   # list; stock { "a real user:// path" = ["user://"] }
forbidden_calls = { "the live settings autoload" = ["SettingsManager\\.(save|load)_settings\\("] }
min_args = { "SaveService.save" = 2 }
baseline = { "tests/unit/test_save_roundtrip.gd" = 3 }
[test_shape]
scenario_root = "tests/integration"
unit_root = "tests/unit"           # the other side of the tier-balance line
cap = 300                          # lines; a NEW scenario over it fails
infra = ["scenario_base.gd"]       # basenames of the tier's shared harness, not priced as scenarios
ledger = { "tests/integration/big_flow.gd" = 812 }   # existing debt at its CURRENT size; only shrinks
header = true                      # every booted scenario declares `## covers:` and `## Boots because:`
header_ledger = ["tests/integration/big_flow.gd"]    # scenarios exempt until they carry both lines; only shrinks
runner = "tools/dev/runners/integration.sh"

[autoloads]
suffixes = { Manager = "emits", Registry = "inert" }
expected_prefixes = ["autoloads/core/", "autoloads/presentation/"]
[refs]
exclude_prefixes = [".git/", ".godot/", "addons/"]
[orphans]
vendored_prefixes = ["addons/"]
entry_point_prefixes = ["tools/"]
auto_discovered_prefixes = ["tests/", "data/"]
convention_files = ["default_bus_layout.tres"]
[stats]
tests = ["tests/"]
tools = ["tools/"]
vendored = ["addons/"]                # list only the vendored addons; your own addon is game code
[pot]
output = "locale/messages.pot"     # required by `godot-devkit pot`: repo-relative, ends in .pot;
                                   # Godot stores no POT path in project.godot

See also: The eight gates.