gd-tools

A modern development workflow CLI for GDScript projects in Godot 4.5+.

1. Overview

gd-tools brings professional development tooling to GDScript -- test, lint, format, and code coverage in a single CLI. It wraps mature, community-trusted tools (GUT for testing, gdtoolkit for linting and formatting) and fills the remaining gap with a custom hybrid coverage system -- production-quality line and branch coverage for GDScript that no existing tool provides.

One install, one config, one mental model.

2. Features

3. Installation

pip install gd-tools-cli

gd-tools requires Python 3.10+ and a Godot 4.5+ binary on your system. The Godot binary is auto-detected from configuration, environment variables (GODOT_BIN, GODOT4_BIN, GODOT_PATH), PATH, or common install locations.

4. Quick Start

# 1. Install
pip install gd-tools-cli

# 2. Bootstrap your Godot project
cd your-godot-project
gd-tools init

# 3. Run your tests
gd-tools test

# 4. Run tests with coverage
gd-tools test --coverage --min 80

gd-tools init installs GUT, deploys the coverage addon, generates gd-tools.toml, and creates per-tool config files (.gutconfig.json, gdlintrc, gdformatrc). The command is idempotent -- safe to re-run.

5. CLI Command Summary

See the User Guide for full command reference, flags, examples, and exit codes.

6. Configuration

gd-tools uses a single gd-tools.toml file as the source of truth for all tool configuration. gd-tools init generates this file with sensible defaults.

[godot]
binary = ""  # Optional -- auto-detected if unset

[test]
test_dirs = ["test", "tests"]
prefix = "test_"
suffix = ".gd"
gutconfig = ".gutconfig.json"

[lint]
exclude = ["addons", ".godot", ".gd-tools", ".git"]

[format]
exclude = ["addons", ".godot", ".gd-tools", ".git"]

[coverage]
enabled = false
min_percent = 0
format = "html"  # html, lcov, cobertura, text
output_dir = ".gd-tools/coverage"
exclude = ["addons", ".godot", ".gd-tools", ".git"]
test_dirs = ["test", "tests"]

See the User Guide for a full configuration reference with all keys, defaults, and examples.

7. Documentation

8. Development

# Clone and install in editable mode with dev dependencies
git clone https://github.com/mansyar/gd-tools.git
cd gd-tools
pip install -e ".[dev]"

Running Tests

Unit tests run without Godot. Integration tests require a Godot 4.5+ binary -- configure via .env (see .env.example):

cp .env.example .env
# Edit .env: set GODOT_BIN to your Godot binary path

# Run all tests with coverage
pytest --cov=src/gd_tools --cov-report=term-missing

See Testing Strategy for the full testing guide and Contributing Guide for development setup details.

9. License

MIT