- Getting started
- Settings
- Excluding files
- Editor integration
- Magic comments
- Unicode syntax
- Comparison with other formatters
- Suggested setup per use-case
- Contribution
- License
Tilia is a formatter for Haskell source code. Its primary design choices are:
- Use
ghc-lib-parserfor parsing, thus achieving correct parsing at all times. - Let single vs multiline layout be influenced by the input.
- Admit as little configuration as possible.
- Ensure high-quality formatting of comments.
- Provide first-class support for CPP.
- Guarantee inference of operator fixity with absolute precision at all times.
If you are curious how Tilia works, see this blog post.
The two most useful commands are inplace and check:
$ tilia inplace [COMPONENT] # format all files of COMPONENT in place
$ tilia check [COMPONENT] # check that all files of COMPONENT are formattedCOMPONENT may be omitted and in that case it defaults to all. To be
precise, the kind of component we are talking about is exactly Cabal's
notion of component: libraries, foreign libraries, executables, test
suites, and benchmarks.
For example, in the case of Tilia itself the valid choices are:
alltilia, the package, which means every component of itlib:tiliaortilia:lib:tiliaexe:tiliaortilia:exe:tiliatest:testsortilia:test:tests, or justtestsbench:benchortilia:bench:bench, or justbench
It may be surprising that we talk about components rather than individual
files. Well, formatting a Haskell module, fortunately or unfortunately,
depends on much more than the input text. It depends on things like
default-extensions, default-language, and, most importantly, the actual
dependencies, because that's where the fixities of the operators you use
come from. What all these things have in common is that they are properties
of the respective Cabal components your modules belong to. Therefore, it
makes sense to consider those components the unit of formatting rather than
individual files.
Tilia respects Cabal projects as defined by cabal.project files. It finds
the project by starting at the working directory and walking upwards for a
cabal.project or a .cabal file. A cabal.project anywhere above wins
over a .cabal file that is nearer, so a package inside a multi-package
repository resolves to the repository. It is worth pointing out that a
package in the tree that neither packages nor optional-packages names is
not part of the project and will not be visited. Within a package, only the
modules a component declares get formatted: its exposed-modules,
other-modules, signatures, and main-is, in every conditional branch,
found under its hs-source-dirs as .hs, .hs-boot, or .hsig files.
A Setup.hs next to a package's .cabal file is formatted too.
If there is no build plan yet, or it is older than the .cabal and
cabal.project files, or it says nothing about a component you asked for,
Tilia has Cabal solve it with cabal build :all --dry-run. If the plan is
fine but some dependencies have been neither downloaded nor built, it
fetches them with cabal build :all --only-download. These commands do not
build anything. A download is made once, since Cabal's package cache is
shared between projects, and a solve is made again only when the plan goes
out of date. So do not worry if the first run in a project prints a few
lines from Cabal before Tilia starts formatting. Later runs check the plan
with a read and a stat per package.
Both of those calls also pass --enable-tests and --enable-benchmarks,
because test suites and benchmarks are components Tilia formats, but they
are often not enabled by default and that would be confusing. Where a
project will not solve with those flags, Tilia settles for what Cabal builds
by default, so you get a narrower plan rather than none.
Finally, here are some other flags that may be of interest:
--check-astperforms an AST-equivalence check.--check-idempotenceperforms an idempotence check.--debug-fixityprints information that is useful for debugging formatting of operator chains.--build-plan PLANtrusts a given build plan as up to date rather than having Cabal solve one, see Haskell.nix.--no-cacheneither reads from nor writes to the cache.--no-downloadsdoes not download sources that are missing, and a file whose operators come from a dependency that could not be read is then declined.--must-not-declineturns declined files into failures.
A project can change how Tilia formats it in a tilia.toml file in its
root: the directory holding its cabal.project, or its .cabal file where
it has no cabal.project. Here is an example that tweaks every available
setting:
# Use indentation step 4.
indentation = 4
# Break what runs past column 100 rather than 80.
column-limit = 100
# Start each line of a broken list with its comma.
leading-commas = true
# Start each line of a broken type with its arrow.
leading-arrows = trueThe file is TOML, restricted to lines of key = value where a value is
true, false, or a whole number, and to # comments.
| Setting | Values | Default |
|---|---|---|
indentation |
2 or 4 | 2 |
column-limit |
a whole number above 0 | 80 |
leading-commas |
true or false |
false |
leading-arrows |
true or false |
false |
You can tell Tilia to skip certain files and/or directories by listing them
in a .tiliaignore file, which Tilia reads the way Git reads .gitignore:
# Fixtures compiled by a separate driver
tests/shouldwork/
tests/shouldfail/
# Generated modules wherever they are, except one
*Generated.hs
!/src/Keep/Generated.hsA .tiliaignore can be in the project root or in any directory below it,
and its patterns are relative to that directory. Everything .gitignore
offers works the same: the globs *, ?, […], and **, a / at the
start or in the middle to anchor a pattern to its directory, a / at the
end to match directories only, ! to re-include what an earlier pattern
excluded, # for comments, and \ to escape any of these. As with Git, a
pattern in a deeper file wins over one above it, and a file whose directory
is excluded cannot be re-included.
Tilia offers a dedicated command for editor integrations:
$ tilia for-editor FILE < buffer.hsIt reads a module from standard input and formats it as if it were the
contents of FILE (a path): the project, the extensions in force, and the
dependencies are found by walking upwards from FILE rather than from the
working directory. FILE need not exist, but it has to be under the
hs-source-dirs of a component. The formatted module goes to standard
output. A module that is declined or excluded (see below), is returned
unchanged, and a failure exits with a non-zero status and prints nothing to
standard output, so an editor keeps its buffer as it is. The module is
always formatted as a whole; there is no formatting of a selected range.
For example, with conform.nvim:
require("conform").setup({
formatters = {
tilia = { command = "tilia", args = { "for-editor", "$FILENAME" }, stdin = true },
},
formatters_by_ft = { haskell = { "tilia" } },
})A program that would rather call Tilia as a library, such as a language
server plugin, can use editorSession and formatBuffer from
Tilia.Editor, which is what for-editor runs.
The lines from a {- TILIA_OFF -} to the next {- TILIA_ON -} are left
exactly as written, and so is everything below a {- TILIA_OFF -} which is
not followed by {- TILIA_ON -}. Each of these magic comments can only be
placed on a line of its own between top-level declarations, and the code
around them is formatted as usual. A {- TILIA_OFF -} above all of a
module's code, with no {- TILIA_ON -} after it, leaves the whole module as
written, whether or not Tilia could format it. Tilia declines a module whose
magic comments stand anywhere else, or when the regions of code they
encompass contain a CPP directive.
Because Tilia respects grouping of declarations and can format CPP just like ordinary Haskell, you normally should not need magic comments at all. They are only useful for exceptional cases, e.g. if you deal with in-code tabular data and want to preserve an arrangement such as this:
{- TILIA_OFF -}
patterns =
-- name warp weft twist
[ ("herringbone", [ 3, 2, 4 ])
, ("houndstooth", [ 2, 3, 5 ])
]
{- TILIA_ON -}Where UnicodeSyntax is in force, Tilia prints ∷, ⇒, →, ←, ∀,
and the other Unicode forms GHC accepts, throughout the module, whichever
form they were written in. Elsewhere it prints their ASCII forms. Turning
the extension on in a component's default-extensions therefore rewrites
every module of that component the next time it is formatted.
- Fourmolu formats operator chains by consulting a hardcoded library of
operator fixities which it builds partly by running a rudimentary analysis
over some hand-picked packages and partly by consuming a Hoogle dump. That
hardcoded fixity library is built during development and then bundled into
the executable. The library is necessarily both incomplete and prone to
going out of date. Furthermore, Fourmolu does not automatically account
for custom operators that occur in the code it is asked to format. For
that you need to add
fixitiesinfourmolu.yamlwhere you redeclare the fixities of your custom operators and any relevant re-exports. Tilia performs resolution of operator fixities automatically and needs no hand-holding. - Fourmolu's CPP support is rudimentary. It splits the input file into sections that must be parseable on their own, then preserves CPP conditional blocks verbatim. First, the requirement for the sections to be parseable on their own is only sometimes satisfied—CPP directives tend to fall at arbitrary points in the code, which makes Fourmolu choke. Second, preserving CPP conditional blocks verbatim is not good enough. For example, if Fourmolu re-indents the surrounding code and the CPP conditional block stays as it was, the result is broken code. Tilia handles CPP as a first-class formattable object and is capable of formatting 99% of Hackage.
- Fourmolu has a very different CLI focused on explicit file names, so that
its users find themselves running invocations like
fourmolu -i $(git ls-files '*.hs' '*.hs-boot'). Tilia focuses on Cabal components, which is arguably better ergonomics. - Fourmolu can be asked to format regions in a file with
--start-lineand--end-lineoptions. Tilia has no such functionality since it operates at a higher level (Cabal components or whole projects), which is aligned with the current trends in software development. - Fourmolu is self-contained and makes no assumption about tools on the
system where it is run. Tilia needs Cabal: it shells out to it and may
download packages, unless the build plan is given with
--build-planand downloads are ruled out with--no-downloads. Fourmolu does none of this, which may be an advantage in some situations. - Fourmolu is much more configurable.
- With
respectful: true, its default, Fourmolu keeps together any declarations written without an empty line between them unless one has a Haddock, so a function spanning several lines stays glued to a data declaration under it. Withrespectful: falseit puts an empty line between every two, a run of fixity declarations included. Tilia takes the middle course: one-line declarations of one kind written together stay together, while a declaration spanning several lines or having a Haddock, and declarations of different kinds, get an empty line between them. - Tilia implements a number of layout improvements over Fourmolu: e.g.
recognizing
let/inchains and printing them nicely instead of letting them “explode”. - Tilia breaks excessively long lines automatically. This feature is always
on and is not known to introduce any problems with idempotence, whereas
Fourmolu warns that setting its
column-limitoption may break idempotence. - Tilia is capable of handling comments with absolute fidelity—they never move in unexpected ways and never disappear.
- Tilia separates third-party and first-party imports with a blank line.
This is analogous to
import-grouping: by-scope, except Tilia takes all packages in yourcabal.projectto be first-party, not only the current package that is being formatted. - Tilia is more correct. For example, it never rearranges pragmas or GHC
options in a way that changes the meaning of the program, whereas Fourmolu
does that. It is careful not to merge
hidingclauses of otherwise matching imports that hide different names—something Fourmolu does, despite it changing the meaning of the program. There are other examples as well.
Have cabal and the compiler your project is built with on PATH, as you
would to build it, and nothing else needs setting up. Tilia gets the build
plan and the sources of dependencies through Cabal as described above, and
maintains its cache in the user's cache directory: ~/.cache/tilia, or
%LOCALAPPDATA%\tilia on Windows.
On GitHub Actions, setup-tilia
installs Tilia and maintains its caches automatically, keyed on the version
of Tilia and on your .cabal and cabal.project files:
- uses: haskell-actions/setup@v2
with:
ghc-version: '9.10.3'
- uses: actions/checkout@v7
- uses: mrkkrp/setup-tilia@v1
- run: tilia checkNothing has to be built before the check.
haskell.nix builds each
component with every dependency already installed and keeps the plan it
solved in plan-nix. --build-plan points Tilia at that plan, so Cabal is
not asked to solve one, and with --no-downloads nothing is fetched either:
only the interfaces of what is installed are read. Cabal is then not run at
all and need not be installed.
This makes a formatting check that runs as part of the build, before a component is compiled, with no development shell to set up for it. Each component is built from the whole package source, so each checks the component it builds:
project = pkgs.haskell-nix.cabalProject {
# ...
modules = [{
packages.my-package.components = {
library.preBuild = tiliaCheck "lib:my-package";
exes.my-exe.preBuild = tiliaCheck "exe:my-exe";
};
}];
};
tiliaCheck = target: ''
${tilia.packages.${system}.default}/bin/tilia check ${target} \
--build-plan ${project.plan-nix}/plan.json \
--no-cache \
--no-downloads \
--must-not-decline
'';Here tilia is this repository as a flake input. There is nowhere to keep a
cache between Nix builds, hence --no-cache, so every check reads the
interfaces it needs again, which has been optimized to perform nearly as
fast as a cached run outside of Nix (a fraction of a second on a project the
size of Tilia).
Issues, bugs, and questions may be reported in the GitHub issue tracker for this project.
Pull requests are also welcome, see HACKING.md.
Copyright © 2026–present Mark Karpov
Distributed under the BSD 3-clause license.