Configuration
Fatou is configured with a TOML file named fatou.toml. Every key is optional, so a config only needs to mention what you want to change from the defaults. Unknown keys are rejected with an error, which means a typo never silently falls back to a default.
The dprint plugin uses the fatou object in dprint.json for its settings and does not read fatou.toml.
A minimal project config looks like this:
exclude = ["vendored/"]
[format]
line-width = 100
[lint]
ignore = ["unused-argument"]This guide covers the common tasks. For the exhaustive list of keys, their types, and their defaults, see the configuration reference.
Editor support
Fatou publishes a JSON Schema for fatou.toml, so editors with TOML support can offer key and value completion, inline documentation, and validation while you edit the configuration.
Schema URL : https://fatou.dev/fatou.schema.json
The schema is generated from the same configuration types Fatou uses at runtime and checked for drift in the test suite.
VS Code and Even Better TOML
With the Even Better TOML extension installed, add this association to your user or workspace settings.json:
{
"evenBetterToml.schema.associations": {
"^(.*/)?fatou\\.toml$": "https://fatou.dev/fatou.schema.json"
}
}Inline schema directive
Editors that recognize Taplo's schema directive can select the schema from the configuration file itself:
#:schema https://fatou.dev/fatou.schema.jsonOther editors and language servers, including Helix, Neovim with taplo-lsp, Zed, and IntelliJ, can use the same URL through their TOML schema association settings.
Where Fatou looks for a config
For a given file, Fatou walks up from the file's directory through its ancestors, and uses the first fatou.toml it finds. The usual layout is a single fatou.toml beside .git at the root of the project.
The search stops at the repository root. See the full resolution order below for discovery rules and fallback paths.
User-Wide defaults
If you want the same settings across projects, do not put a fatou.toml above your repositories; use a global config instead. When no project fatou.toml is found, Fatou looks for one in your user config directory, typically ~/.config/fatou/fatou.toml.
To use a config on a synced drive, set FATOU_CONFIG to its absolute path. A non-empty value shadows the global config entirely. An unset or empty value uses the normal user config location. Relative paths resolve from the process's working directory; use an absolute path in editor settings.
In VS Code, add this to your user settings.json, then run Fatou: Restart Server:
{
"fatou.serverEnv": {
"FATOU_CONFIG": "P:/Softwares/fatou.toml"
}
}Project configs take precedence over user-wide defaults.
A missing or malformed config file makes the CLI fail. The language server logs a configuration warning in the Fatou output channel and uses editor settings or built-in defaults. Fix the file and restart the server to apply it.
The language server uses the same discovery rules as the CLI. It watches project fatou.toml files and files reached through extend. An edit to the primary global or FATOU_CONFIG file is picked up when the server restarts.
Extending another config
Use extend to inherit settings from a shared file and override only the keys this project needs:
extend = "../shared/fatou.toml"
[format]
line-width = 100The path is relative to this config file. See the reference for inheritance and merge rules.
Bypassing discovery
On the command line, --config <PATH> loads an explicit file and skips discovery altogether, and --no-config ignores every file (project, FATOU_CONFIG, and global) and runs with the built-in defaults.
Resolution order
Fatou uses the first source that applies:
--config <PATH>, which loads that file and skips discovery.--no-config, which ignores every file and uses the built-in defaults.- The nearest
fatou.toml, found by walking up from the file's directory. The walk stops at the repository root (the directory holding.git, whether a directory or a file), inclusive. This also bounds worktrees and submodules. A directory with no.gitancestor is walked to the filesystem root. $FATOU_CONFIG, when set and non-empty. A missing or malformed file here is a configuration error.- The global user config: the first existing file in the platform's search order below.
- The built-in defaults.
Fatou selects one source without merging it with the other fallbacks. A config inherits another file only through an explicit extend.
For the global config, Fatou checks these paths in order:
| Platform | First | Second | Third |
|---|---|---|---|
| Linux | $XDG_CONFIG_HOME/fatou/fatou.toml, if set | ~/.config/fatou/fatou.toml | — |
| macOS | $XDG_CONFIG_HOME/fatou/fatou.toml, if set | ~/.config/fatou/fatou.toml | ~/Library/Application Support/fatou/fatou.toml |
| Windows | $XDG_CONFIG_HOME/fatou/fatou.toml, if set | %APPDATA%/fatou/fatou.toml | ~/.config/fatou/fatou.toml |
Checking standalone scripts
The default entry-points list contains test/runtests.jl, docs/make.jl, and deps/build.jl. Fatou discovers these files relative to Julia projects above the lint target or open document, stopping at the repository boundary. Missing default files are ignored. Setting entry-points replaces the default list; entry-points = [] disables it. extend-entry-points adds paths to either the defaults or an explicit replacement list. Benchmark files and arbitrary include-graph roots are not inferred.
Add files you run as independent programs to check undefined names across their static includes:
[project]
extend-entry-points = ["scripts/**/*.jl"]The CLI and language server enable undefined-name by default for each entry point and its included files. An explicit [lint] select replaces those defaults; ignore = ["undefined-name"] disables the rule. Files outside these programs keep their usual defaults.
No Julia package is required for explicit paths. Both options accept literal files and globs relative to the configuration file. Globs honor .gitignore; unmatched globs add no files. Missing explicit literal paths are errors. If main.jl includes settings.jl and worker.jl, functions in worker.jl can use globals defined in settings.jl. Misspellings still produce warnings. Separate entry points do not share globals, even when they include the same helper file. Findings identify the entry point and module where the name is undefined.
Run fatou lint . to check the discovered Julia files. Running fatou lint scripts/main.jl reports findings only in that file; its includes still supply resolution context. The language server also uses unsaved changes in included files.
Fatou never executes Julia to analyze a script. Dynamic includes and broken dependencies can limit undefined-name checking. See the project reference for analysis limits, analysis-incomplete notices, and missing-include errors.
Choosing a syntax edition
Julia's syntax edition controls which grammar Fatou parses. Its supported runtime range controls compatibility linting. Declare both independently in Project.toml:
[compat]
julia = "1.6"
[syntax]
julia_version = "1.14"Fatou supports editions 1.13, 1.14, and 1.15. It selects an edition in this order:
- The project's
[syntax].julia_version. - The minimum version allowed by
[compat].julia. - Edition 1.13 for package sources, or the latest supported edition for scripts.
Versions below 1.13 select 1.13. Other versions select the greatest supported edition no newer than that version, capped at 1.15. Patch versions do not change the edition. Package sources use their owning project. Scripts use the active Julia project discovered through JULIA_PROJECT or project discovery. Standalone files without a project, and stdin, use the latest supported edition.
A manifest dependency uses its own syntax.julia_version field, defaulting to 1.13 when absent. The manifest's top-level julia_version describes the runtime and never selects a syntax edition. Fatou reads this metadata statically.
Use --syntax-edition for a command-local override:
fatou format --safe --syntax-edition 1.13 src/Example.jl
fatou lint --syntax-edition 1.14 src/Example.jl
fatou parse --syntax-edition 1.14 --to sexpr src/Example.jl
fatou debug format --syntax-edition 1.14 src/Example.jlThis flag accepts only supported editions. It does not change --julia-version or [julia].version, which set the runtime range for compatibility checks. Syntax editions have no fatou.toml or editor setting.
Includes inherit the loading program's edition, even across project boundaries. When several programs include the same file, Fatou analyzes every context and combines diagnostics. Formatting and fixes require agreement across those contexts and valid output in every edition.
The language server honors unsaved project and manifest edits immediately. Malformed metadata selects the role's default edition for analysis and reports an error. Fatou withholds source rewrites until the metadata is valid or a CLI override supplies a certain edition. Tokens, folding, and the document outline use the owning package's context first, then configured entry-point order.
Excluding files
Keep vendored code out of directory scans:
exclude = ["vendored/"]Use extend-exclude to add patterns to an inherited list. Files named explicitly on the command line are still processed; pass --force-exclude to exclude them too. See the top-level key reference for pattern roots and per-run overrides.
Formatting
Set only the formatting options you want to change. For example, to allow longer lines and always write Unix line endings:
[format]
line-width = 100
line-ending = "lf"To enable safe formatting for the CLI and editor formatting, including format-on-save and range formatting, add:
[format]
safe = trueSafe formatting verifies that the result preserves the parsed program and its comments. Malformed input and syntax the verifier cannot compare produce an error and leave the source untouched. Range formatting verifies the full document, so malformed code outside the selection also blocks edits. The default is false; fatou format --safe enables verification for a single run.
See the format reference for defaults, line-ending choices, command-line overrides, and deprecated key spellings.
Choosing lint rules
By default most rules run; the rule reference lists the few that are opt-in for loose files. Workspace package files also enable project-resolution rules, and declared script programs enable undefined-name. Use extend-select to enable additional rules while keeping the defaults. For example, to report undefined names in self-contained files without configuring entry points or losing unused-variable warnings:
[lint]
extend-select = ["undefined-name"]Use select to replace the defaults and ignore to turn individual rules off. An explicit select also replaces defaults enabled by package or script context. See the lint reference for selection order and empty selections.
[lint.severity] changes how loudly a rule reports, without changing whether it runs. Rules you do not list keep their default severity:
[lint.severity]
unused-binding = "warning"
undefined-name = "error"Tuning a rule
A rule with a tunable knob reads it from its own table, named after the rule ID. For example, discouraged-function ships a deny-list of Base functions with process-wide or memory-unsafe effects, and you can add your own entries to it:
[lint.rules.discouraged-function]
extend-functions = { sleep = "use a timer instead of blocking the task" }Rules without options have no table. The configuration reference lists the rules that do.

