Skip to content
Latest releasev1.0.0Release notes
trellis

Configuration

Configuration is optional. With no configuration, trellis uses the git repository root as the workspace root. Every non-gitignored gleam.toml outside build/ marks a member. You can start with a Gleam monorepo or a single-package repository.

Workspace setup

Section titled “Workspace setup”

Add a [tools.trellis] table to the root gleam.toml when you need to change a setting. The table identifies the workspace root; you do not need a separate configuration file. The root manifest can describe a Gleam package or contain only configuration.

gleam.toml
[tools.trellis]

Every key is optional. Omit members to keep auto-discovery while configuring other settings. To add a custom task:

gleam.toml
[tools.trellis.tasks.lint]
command = "gleam run -m glinter"
needs_deps = true

needs_deps = true runs gleam deps download first if dependencies are not cached. Built-in tasks such as build, test, and format need no declaration. See Task running for task selection and execution.

A member is a directory with its own gleam.toml: a Gleam package that belongs to the workspace. Path dependencies define the graph. Trellis rejects cycles and path dependencies that escape the workspace.

Bootstrapping with trellis init

Section titled “Bootstrapping with trellis init”

Run trellis init to write the table at the repository root. It creates a config-only gleam.toml if the root is not a package, or adds the table to the existing manifest.

Terminal window
$ trellis init
created /repo/gleam.toml
members are auto-discovered; found 2:
  packages/a
  packages/b

The generated table keeps auto-discovery: init writes comments about available settings rather than a members list. It reports the packages it found and finishes by running doctor.

init refuses to run if the repository is already a trellis workspace or if a member manifest contains a [tools.trellis] table.

You do not need init to use trellis. Run it when you want to configure a setting or make the workspace root explicit.

Member discovery

Section titled “Member discovery”

members accepts paths relative to the workspace root. An entry containing *, ?, or [ is a wildcard member pattern; any other entry is literal.

gleam.toml
[tools.trellis]
members = ["packages/core", "examples/**"]

In a Git repository, wildcard discovery honors nested .gitignore files and .git/info/exclude. It does not honor global core.excludesFile, generic .ignore files, or automatically hide dot paths. Outside a Git repository, Git ignore rules do not apply.

Wildcard traversal follows symlinks but does not enter .git. Only matching directories that contain a gleam.toml become members. Literal entries bypass ignore status and are resolved directly, even when Git ignores the path.

[tools.trellis.exclude] is a separate post-discovery filter. It can drop packages from task or release sets, but it never prunes traversal.

A [tools.trellis] table in a member manifest is a doctor error because it would change root discovery. Trellis walks up from the current directory to the first manifest with that table, as git and cargo do for their roots.

Package exclusions

Section titled “Package exclusions”

Add a key under exclude for any built-in or custom trellis run task whose package set differs from the full workspace:

gleam.toml
[tools.trellis]
members = ["packages/*", "examples/*", "benchmarks/*"]
exclude = { docs = ["examples/*", "benchmarks/*"], "@release" = ["examples/*", "benchmarks/*"] }

Inline TOML is concise for a small map. The equivalent table form is easier to scan as more tasks gain exclusions:

gleam.toml
[tools.trellis.exclude]
docs = ["examples/*", "benchmarks/*"]
"@release" = ["examples/*", "benchmarks/*"]

Patterns match member paths relative to the workspace root, not package names. A task exclusion applies after package selection, including packages named explicitly or selected through --since.

Key What it excludes
docs Matching packages from trellis run docs, without overriding its command.
Any custom task name Matching packages from that trellis run <name> invocation.
@release Matching packages from changelog, version, tag, publish, and release CI operations. This selects the workspace release lifecycle. Explicit changelog creation and publishing are rejected.
@members Matching directories from workspace membership itself. No command parses or uses them.

Release-excluded packages remain in the graph and participate in list, graph, exec, and tasks that do not exclude them. info and JSON output expose releasable: false; list --releasable returns the git_only and hex packages:

Terminal window
$ trellis list --releasable
lat_core  hex
lat_mid   hex
lat_cli   hex

trellis doctor reports exclusion globs that match no member. For packages that need versions and git tags without publishing to Hex, configure their release lifecycle.

Verifying it

Section titled “Verifying it”

Run trellis doctor after any configuration change:

Terminal window
trellis doctor

It checks member discovery, the dependency graph, task exclusions, release boundaries, tag uniqueness, locked versions, changelogs, dependency pins, shared dependencies, and unrecognized keys. It exits non-zero on an error.

More settings

Section titled “More settings”

The configuration reference contains all keys, defaults, release settings, and migration rules.