Skip to content

Reference

Command What it does
litany check runs the selected rules over the project
litany rules lists the rules
litany explain RULE prints one rule’s documentation
litany unit NAME --cmt PATH --source PATH lints one unit
litany units saves or prints a unit file

litany COMMAND --help says the same at length. Every command exits 0 clean, 1 on findings, 2 on a refusal and 3 on an internal error.

Option What it does
--select=NAMES, --ignore=NAMES choose the rules, replacing the file’s lists
--fix, --unsafe apply safe fixes, and unsafe ones too
--format=FMT text, json or github
--root=DIR run against the workspace at DIR
--no-build don’t build first; stale artifacts are skips
--list-units list the units that would be linted and those skipped, and run no rule
--explain-withheld say which skip blocked which project rule
--units=FILE take the units from a unit file
--cmt-root=DIR walk a directory of artifacts
--trust-build with a build litany didn’t run, lint preprocessed units instead of skipping them; a stale one is still skipped
-j N, --jobs=N use N worker processes
--cache-dir=DIR, --no-cache, --cache-stats control the cache
--no-progress don’t draw the progress line, which only a terminal gets
Option What it does
--dump print the file readably; the default
--save=FILE write it to FILE
--root=DIR, --no-build, --cmt-root=DIR as for litany check
Option What it does
--cmt=PATH, --source=PATH the unit’s artifact and source, both required
Variable What it does
LITANY_CACHE_DIR, XDG_CACHE_HOME where the cache is
LITANY_NO_PROGRESS as --no-progress
GITHUB_ACTIONS makes github the default format
NO_COLOR, OCAML_COLOR NO_COLOR turns colour off; OCAML_COLOR is always or never

The opam package installs the command alone. Its libraries are private to its source tree, where rules and a custom binary are built against them:

  • Rule – declares a rule.
  • Pat – matches the typed tree by resolved declaration.
  • Unit – a source and its artifact.
  • Finding, Fix, Source and Span – what a rule returns, what it edits, and where.

The rest of Litany is the driver’s, and carries no promise of compatibility.