Configuration Reference

This page lists key accepted in fatou.toml. All keys are optional and omitting a key uses its default. Unknown keys are rejected with an error.

FATOU_CONFIG and global config files use this same schema. For a task-oriented walkthrough, see the configuration guide. A machine-readable JSON Schema is also available for editor completion and validation.

Set FATOU_CONFIG to a custom user config path. Fatou uses it when no project fatou.toml is found, before checking the platform’s user config directory. An unset or empty value uses the normal user config location. Relative paths resolve from the process’s working directory. In VS Code, set it through fatou.serverEnv and run Fatou: Restart Server; see User-Wide Defaults for an example.

Top-level keys

Both keys take gitignore-style patterns, resolved relative to the directory containing fatou.toml (or, for a FATOU_CONFIG or global config, the working directory). Excluded directories are pruned during discovery.

Files named explicitly on the command line are processed even when they match a pattern, unless --force-exclude is passed. Extra patterns can be added per run with --exclude on fatou format and fatou lint.

exclude = ["vendored/"]
extend-exclude = ["generated.jl"]

[project]

Paths are literal files, without glob expansion, relative to the containing configuration file. This also applies to --config, FATOU_CONFIG, and global configuration files. Duplicate normalized paths are ignored. Configure entry points in a file; editor-pushed settings do not establish a project root.

[project]
entry-points = ["scripts/main.jl"]

The CLI and language server enable undefined-name by default for these programs. An explicit [lint] select replaces the defaults, and ignore = ["undefined-name"] disables the rule. Files outside the configured programs keep their usual defaults.

Entry points provide resolution context without expanding the files selected for linting. Fatou follows static include("path") calls and resolves global bindings in their host modules. Each entry point and host module is analyzed separately. Findings identify the contexts in which a name is undefined. Includes may supply names even when their files are excluded from diagnostic reporting.

A missing or unreadable entry point fails CLI linting. The language server logs the failure and continues checking other entries. Dynamic includes, eval, unresolved whole-module usings, include cycles, and unreadable or unparseable dependencies make an entry’s undefined-name analysis incomplete and suppress its findings. Relative whole-module usings remain unresolved. Other independent entries still run.

The language server uses unsaved buffers and refreshes dependent diagnostics after edits, closes, and watched file changes. Script contexts currently support diagnostics; completion and navigation do not use them. Cross-file method-table checks (call-arity and function-has-no-methods) remain disabled for these contexts because the script model records names, not method tables.

[format]

line-width and indent-width can be overridden per run with the --line-width and --indent-width flags on fatou format.

line-ending accepts:

• auto (default): mirror the source file’s first line ending, defaulting to lf when the file has none.
• lf: always \n (Unix).
• crlf: always \r\n (Windows).
• native: \n on Unix, \r\n on Windows.

[format]
line-width = 92
indent-width = 4
line-ending = "auto"

Deprecation: the snake_case keys line_width and indent_width are still accepted but print a warning. Use the kebab-case line-width and indent-width instead; the snake_case forms will be removed in a future release.

[lint]

See the rule reference for the available rule IDs. An unrecognized ID in select, extend-select, ignore, or severity is a warning, not an error.

Fatou starts with the defaults, or select when set, adds extend-select, and then removes rules in ignore. Repeated IDs do not run a rule more than once. An empty select = [] disables the defaults; extend-select can still add rules. For workspace package files, the language server also enables rules that need project resolution, unless they are ignored.

[lint.severity] maps a rule ID to the severity its findings report, one of "error", "warning", "info", or "hint". Rules not listed keep their default severity.

[lint]
extend-select = ["undefined-name"]
ignore = ["unused-binding"]

[lint.severity]
undefined-name = "error"

[lint.rules.<id>]

A rule with a tunable knob reads it from its own table, named after the rule ID. Rules without options have no table. Keys are kebab-case, matching the rest of the file.

Unlike select, extend-select, ignore, and severity, these tables are a schema: a misspelled rule ID, or a misspelled key inside one, is a configuration parse error and the run stops.

Per-rule severity is not set here; use [lint.severity] for that.

[lint.rules.discouraged-function]

Options for discouraged-function. Both keys are tables mapping a function name to the suggestion shown in the diagnostic.

The built-in set covers Base functions with process-wide or memory-unsafe effects: exit, cd, redirect_stdout, redirect_stderr, unsafe_load, unsafe_store!, unsafe_wrap, unsafe_string, pointer_from_objref, and unsafe_pointer_to_objref.

Setting functions = {} silences the rule without having to ignore it, which is the way to keep the rule available for a future project-specific list.

# Keep the built-ins and add a project rule of your own.
[lint.rules.discouraged-function]
extend-functions = { sleep = "use a timer instead of blocking the task" }

# Or replace the built-ins outright.
# functions = { my_legacy_helper = "call `new_helper` instead" }