A template is a Git repository that packages one kind of
conversion: a tern.toml manifest declaring profiles and
pipelines, the Lua converters they use, and data files such as filters,
stylesheets or setup scripts. Projects list templates in
.tern/config.toml, and tern -u installs them.
Reference https://git.yhkze.net/tern/pandoc-template for a
complete one.
Each [[templates]] entry in
.tern/config.toml installs one template:
[[templates]]
name = "pandoc-template"
url = "https://git.yhkze.net/tern/pandoc-template.git"
ref = "v1.0" # optional: tag, branch or commitThe name decides where the template is installed
(.tern/converters/<name>/,
.tern/data/<name>/) and how its profiles and
pipelines are addressed (<name>/<profile>).
Installing one template several times under different names gives
independent configurations of the same upstream, e.g. one install for
docs/ and another for the top-level README.
Install or update every configured template:
tern -utern -u fetches each template, copies its converters and
data, and recomputes its profiles from the manifest plus the overrides
below; pipelines are replaced entirely. Conversion history is kept, so
an update does not force a full rebuild. Because the result depends only
on the manifest and .tern/config.toml, rerunning it
reproduces the same state.
tern -a installs from the cache without fetching, and
skips profiles that already exist.
| Template directory | Installed to |
|---|---|
converters/ |
.tern/converters/<name>/ |
data/ |
.tern/data/<name>/ |
tern.toml profiles |
Database, as <name>/<profile> with engine
<name>/<file>.lua |
tern.toml pipelines |
Database, as <name>/<pipeline> |
tern -u replaces .tern/data/<name>/,
so edits to installed copies are lost on the next update. Durable
changes belong in a fork of the template; profile and pipeline changes
belong in .tern/config.toml.
Profiles and pipelines are derived on every tern -a and
tern -u, so a value edited in the database (through the TUI
or directly) is recomputed away. Project-specific adjustments live in
.tern/config.toml.
[templates.overrides.<profile>] replaces fields of
a profile, keyed by its short name in the template’s
tern.toml:
[[templates]]
name = "pandoc/readme"
url = "https://git.yhkze.net/tern/pandoc-template.git"
[templates.overrides.pandoc]
source_root = "."
ignore_patterns = ["*", "!README.md"]The overridable fields are source_root,
source_file_extension, output_root,
output_file_extension, options and
ignore_patterns; omitted ones keep the manifest’s value.
engine is not overridable, since it names a converter the
template ships.
Stage snippets are shell commands that profile overrides cannot
reach. [templates.snippet_overrides] replaces them, keyed
by "<pipeline>/<stage>". A template that refers
to its own default install path needs this under any other name:
[templates.snippet_overrides]
"convert/convert" = ["sh .tern/data/pandoc/readme/setup.sh"]An empty list removes the stage’s snippets.
A key naming a profile or stage the template does not declare is an error, as is an unknown field inside an override block, so typos and upstream renames surface immediately.
Pipelines run in parallel, and so do the items within a stage (reference Pipelines). Two installs of one template therefore run their snippets at the same time, against the same output root if they share one, and a snippet that writes files there must assume another copy of itself writes the same paths simultaneously.
A check-then-copy races on a cold output directory:
[ -f "$dst" ] || cp "$src" "$dst"Both processes find the destination missing, both have
cp create it with O_CREAT|O_EXCL, and the
loser aborts with cannot create regular file: File exists.
It passes every warm rebuild and fails in CI. cp -f does
not help: it only unlinks and retries when the destination cannot be
opened. Writing to a temporary file in the destination directory and
mv-ing it into place is safe: rename(2) is
atomic and replaces the target, so concurrent writers end in
last-writer-wins and no reader sees a half-written file.
Each template is cloned to .tern/cache/<name>/,
and the installed converters and data are copies taken from it. The
cache ignores itself through a generated
.tern/cache/.gitignore.
The cache is keyed by name, not URL, so two installs of
one upstream get two independent clones. Changing a template’s
url re-points the existing clone’s origin on
the next tern -a or tern -u, keeping the
objects already downloaded; a URL with unrelated history converges too,
since the fetch prunes and the worktree is reset to the configured
ref.
A template repository holds:
tern.toml — the manifest;converters/ — Lua converters, referenced by the
profiles’ engine (reference Converters);data/ — anything else the conversion needs at run time,
referenced from options and snippets as
.tern/data/<name>/….The manifest declares the template’s profiles and the pipelines that run them:
name = "my-template"
[[profiles]]
name = "default"
engine = "pandoc.lua"
source_root = "docs"
source_file_extension = "md"
output_root = "docs-html"
output_file_extension = "html"
options = ["--standalone --toc"]
ignore_patterns = ["drafts/"]
[[pipelines]]
name = "build"
[[pipelines.stages]]
name = "convert"
converters = ["default"]
snippets = ["sh .tern/data/my-template/setup.sh"]Paths in options and snippets use the default install name
(.tern/data/my-template/); projects that install the
template under another name retarget them with overrides.