gdtoolkit

gdtoolkit — GDScript Lint & Format

Use this as an optional local lint pass. Headless compilation and the project's tests remain the acceptance checks; lint output alone is not a reason to change working Godot code.

Wraps two CLI tools from the gdtoolkit Python package:

• gdlint — static analysis and style checking
• gdformat — deterministic auto-formatter

Prerequisites

pip install "gdtoolkit==4.*"    # Godot 4 projects
pip install "gdtoolkit==3.*"    # Godot 3 projects

Verify installation: gdlint --version && gdformat --version

If not installed, tell the user and offer to install. The version major must match the project's Godot major version (read from project.godot config/features).

Lint workflow

Run gdlint

gdlint path/to/file.gd          # single file
gdlint path/to/directory/       # all .gd files recursively

Interpret output

Each problem is one line on stderr:

path/to/file.gd:42: Error: Function name "MyFunc" is not valid (function-name)

Format: {file}:{line}: Error: {message} ({rule-id})

Exit codes:

• 0 — no problems (stdout: Success: no problems found)
• 1 — problems found (stderr: Failure: N problem(s) found)

Fix lint issues

For each reported issue, either:

1. Fix the code — rename to match convention, remove unused arg, reorder members
2. Suppress inline — when the violation is intentional:

   # gdlint:ignore = rule-id
   var _unusedButNeeded := 0   # this line + next line are suppressed
   

3. Suppress region — for larger blocks:

   # gdlint: disable=function-name
   func ALLCAPS_required_by_engine():
       pass
   # gdlint: enable=function-name
   

When suppressing, always add a brief comment explaining why.

Format workflow

Run gdformat

gdformat path/to/file.gd        # format in-place
gdformat path/to/directory/      # format all .gd files
gdformat --check path/           # check only, don't modify (exit 1 if changes needed)
gdformat --diff path/            # show unified diff on stderr, don't modify