gdtidy

Moving from gdtoolkit

Convert gdlintrc and gdformatrc with gdtidy migrate, and every way gdtidy differs from gdlint and gdformat.

Convert the configuration

gdtidy migrate              # ./gdlintrc and ./gdformatrc, with or without a leading dot
gdtidy migrate --stdout     # print the result instead of writing it

gdtidy migrate reads gdlintrc and gdformatrc and writes a gdtidy.toml next to them, or adds the sections to the gdsuite.toml there when the project has one and no gdtidy.toml:

  • its [lint] section reports the same problems as gdlint. It keeps the values the project changed, keeps gdlint's tab width for max-line-length, and says where each dropped rule went, such as unused-argument, which Godot reports.
  • its [fmt] section keeps gdformat's excluded folders and its {"a": 1} dictionaries. gdformat's line_length has no equivalent, because gdtidy does not wrap lines.

The original files are left as they are. If gdtidy.toml (or gdsuite.toml) exists, only the sections it does not have yet are added, so a project converted from gdlint can convert its gdformatrc later. --force replaces a whole gdtidy.toml, but never touches a section already in gdsuite.toml.

Rule names and silencing comments are gdlint's, so nothing else in the project needs to change. Formatting differences with gdformat are listed on the Formatting page.

Differences with gdlint

gdtidy keeps 24 of gdlint 4.5's rules with the same names, defaults and findings, and max-line-length with a different tab width. This page lists every place where the two report something different, and why. The comparison test (GDTIDY_PARITY=1, see crates/gdtidy/tests/parity.rs) checks it: it fails if gdlint reports something gdtidy does not, and lists what only gdtidy reports.

On the 14 public projects used to test gdsyntax (1,119 files), gdlint could not parse 21 files, which gdtidy lints as usual. On the other 1,098 files, gdtidy reports all 835 of gdlint's findings, plus 8 from the static-function difference below.

Rules that moved

gdlint ruleWhere it went
unused-argumentGodot's UNUSED_PARAMETER warning (gdtypecheck)
expression-not-assignedGodot's STANDALONE_EXPRESSION warning (gdtypecheck)
mixed-tabs-and-spacesA Godot parse error (gdtypecheck)
trailing-whitespacegdtidy fmt removes it
tab-charactersThe tab-width option of max-line-length

Deliberate differences

RulegdlintgdtidyWhy
max-line-lengthCounts a tab as 1 column (tab-characters: 1)Counts a tab as 4 columns (tab-width = 4)Godot's editor shows a tab as 4 columns. gdtidy migrate writes gdlint's value, so a converted project gets the same results
max-returns, function-arguments-number, max-public-methodsLeaves static functions outCounts themA static function is a function; nothing in gdlint's documentation says they are exempt
class-nameSkips class_name Name extends Base on one lineChecks itThe same name, written on one line
duplicated-loadCompares the quoted text, so load("a.gd") and load('a.gd') differCompares the pathBoth load the same file
unnecessary-passNot reported in a class whose other members are all functions or inner classes, nor in a block whose other statements are all typed for loopsReportedpass is unneeded in both
no-else-return, no-elif-returnA match with a guarded wildcard branch (_ when x:) counts as always returningDoes not countA guarded branch does not catch everything
Every ruleFails on some valid Godot 4 code (such as ( in some expressions) and reports nothing for the fileLints itgdsyntax is translated from Godot's own parser
Every ruleLints a nested Godot project (a folder with its own project.godot) as part of the outer oneSkips it when walking folders, as the Godot editor does; name the folder to lint itIt is another project, with its own gdtidy.toml
Every ruleReports a file with a syntax error as a problemSkips it, lists it under skipped, and exits with 2Syntax errors are Godot's to report: gdtypecheck

Configuration

gdlintrcgdtidy.toml
rule-name: value[lint.rules.rule-name] with pattern, max or sections
disable: [...][lint] disable = [...]
excluded_directories[lint] exclude, where a name alone matches a folder at any depth, as in gdlint. Hidden folders and addons are always skipped
Found by walking up from the current folderFound by walking up from each script, stopping at project.godot

gdtidy migrate does this conversion.