Template format¶
Inheritance pins resolve exact tags (including refs/tags/<name>) or unique commit-object SHA prefixes
of 7–40 hexadecimal characters.
Tags take precedence over same-named branches; hexadecimal branch names never provide a fallback.
Ambiguous prefixes and noncommit objects fail with tpl::git::no_such_revision.
Rendered files retain Git modes 100644, 100755 and 120000.
Symbolic-link targets are opaque bytes, never template expressions, even for links named .jinja.
Output names still follow path rendering and suffix removal.
Dirty traversal reads target bytes and never descends through a directory link.
No output may be a descendant of another output, including a link.
A template is a normal Git repository. Nothing registers it, nothing packages it, and any Git URL that libgit2 can clone will do — including a local path.
Layout¶
rust-library-template/
├── template.toml ← the manifest
├── data/ ← optional structured data
│ ├── licenses.toml
│ └── defaults.toml
├── migrations/ ← optional file moves to apply across a version jump
│ └── 2026-08-config-move.toml
├── macros.jinja ← a shared partial, not rendered
├── macros/
│ └── rust.jinja ← likewise
├── template/ ← everything here is rendered
│ ├── Cargo.toml.jinja
│ ├── README.md.jinja
│ ├── src/
│ │ └── lib.rs.jinja
│ └── .github/
│ └── workflows/
│ └── ci.yml
├── README.md ← the template's own README, not rendered
└── LICENSE ← likewise
Only template/ is rendered.
The rest of the repository — the template's own README, its CI, its license — is invisible to the projects that
use it.
The exception, and the only one, is a .jinja file outside template/: it is still never rendered into a
project, but it is importable as a shared partial.
migrations/ is likewise never rendered — it declares file moves for update to apply when a project crosses
them. See Migrations.
The rendered subdirectory is configurable:
The manifest¶
template.toml at the repository root.
name = "rust-library"
description = "A small Rust library"
root = "template"
[data.licenses]
source = "data/licenses.toml"
[questions.project_name]
type = "string"
prompt = "Project name"
[computed]
package_name = "{{ project_name | lower | replace(' ', '-') }}"
line_length = 100
Top level¶
| Key | Type | Default | Meaning |
|---|---|---|---|
name |
string | required | The template's name. Used in output, and in the rendered commit subject. |
description |
string | — | One line, shown when prompting. |
root |
string | "template" |
The subdirectory that gets rendered. |
strict |
bool | false |
Fail on an undeclared name in a rendered file, rather than rendering it to an empty string. git tpl lint reports the same names as warnings. |
note |
string | — | A note shown after init. May be an expression. Mutually exclusive with note_file. |
note_file |
string | — | A path in the template repository, relative to its root, whose content is shown after init. Rendered if it ends in .jinja. The path may be an expression. |
All of these must be written above the first table header.
In TOML a bare key belongs to the table that most recently opened, so a note_file written below [computed] is
a computed value and the note never appears.
The manifest stays valid and nothing fails, which is why
git tpl lint reports it as tpl::lint::absorbed_key.
The template id — which determines the ref name — is derived from the source the project records, not from
name.
See Configuration.
Each entry in [computed] is an expression or a literal value: a string containing {{ or {% is evaluated,
anything else is kept as written.
[questions], [computed] and [data] are covered in Questions, Computed values
and Data sources.
[data.<name>]¶
| Key | Type | Default | Meaning |
|---|---|---|---|
source |
string | required | Where the data comes from. May be an expression. |
kind |
string | inferred | template, local, remote or git. Required when source only becomes a URL after interpolation. |
ref |
string | — | The revision a git source is read at — branch, tag or SHA. May be an expression. |
path |
string | — | The path inside a git source's repository. May be an expression. |
format |
string | inferred | toml, json or yaml. Inferred from the extension. |
sha256 |
string | — | The expected digest of the content, as 64 hex characters. A mismatch stops the render. |
ref and path go together: a half-declared triple is refused at load time.
See Git data sources.
[remotes]¶
Git remotes to add on init, as <name> = "<url>".
The URL may be an expression, which is the point — a remote a template can usefully declare is one derived from
the answers.
Added in declaration order, on init only, and never fetched or pushed.
If the repository already has a remote of that name pointing somewhere else, it is left alone and a warning names
both URLs.
git-tpl does not repoint an existing origin: the one in the repository was put there by a person, and a
template that could redirect it could redirect a push.
These are Git remotes.
A remote data source under [data] is an unrelated thing — an HTTP URL the loader reads.
[[compose]]¶
Render independent module trees from one or more sibling repositories, tracking the exact commit resolved from a ref.
Every declaration has source (local path or Git URL, optionally an expression), ref (branch, tag or commit),
and from (the parent list question that names zero or more module IDs).
The child has a separate answer namespace and declares module_name and module_path as its own questions.
Composition supplies those two values explicitly and forwards parent answers named version and memcastle
only when the child declares matching questions.
Other child questions use their own defaults; parent answers are not inherited wholesale.
See Composing module templates for the output layout, trust decisions and updating projects.
[extends]¶
A template may declare one parent, pinned to a tag or a commit:
[extends]
source = "https://github.com/org/base-template"
rev = "v3.1.0"
remove = ["template/.github/workflows/ci.yml.jinja"]
| Key | Type | Default | Meaning |
|---|---|---|---|
source |
string | required | Any Git URL, or a path on this machine — the same shape as git tpl init's own template argument. |
rev |
string | required | The revision the parent is pinned to. Must be a tag or a commit SHA, never a branch — an unpinned parent would make the same child revision render two different trees on two different days. |
remove |
array of strings | [] |
Paths to drop from the merge, relative to the parent's own repository root — including its root prefix, so a partial can be removed too. Naming a path the parent does not have is an error. |
A child renders on top of its parent: it may add questions, data sources, computed values and remotes, override any of them by name, add files, and replace files the parent renders. The rules, applied uniformly:
- The unit of override is a whole
[questions.<name>],[computed]entry,[data.<name>]or[remotes]entry, not a field within one. A child redeclaring[questions.license]replaces the parent's entirely. - Order: the parent's own entries come first, in the parent's own declaration order, then the child's new ones. An entry the child overrides keeps the parent's position — overriding a question does not move it in the prompt sequence.
name,description,root,strict,noteandnote_fileare never inherited. Each layer's own manifest is authoritative for these; a child that wants its parent's note copies it.- Files are merged by their pre-render path: a child's
template/README.md.jinjareplaces the parent's file at the same path entirely; a parent's file the child does not mention is included unchanged. - A child may add no files of its own at all — one that only overrides a question or a data source has
nothing under its own
root, which is fine: only a template with no[extends]must have a non-emptyroot. - Partials merge into one namespace by name: the nearer layer's own declaration wins for a bare
{% import "macros.jinja" %}, and{% import "parent:macros.jinja" %}reaches the next declaration of that same name, one layer further out — the value a bare reference would have resolved to had the nearer layer not overridden it. This is the<prefix>:loader namespace shared partials already reserves.
Extending a shared base across the chain¶
{% extends %}/{% block %} compose with the chain exactly like shared partials do, because
they are shared partials, merged into the same namespace by the same rule.
The everyday case needs nothing special: a parent declares a base with blocks, and a child with no partial of its own by that name just extends it bare — the parent's declaration is the only, and therefore nearest, one:
{# the parent's base.html.jinja #}
{% block title %}Default title{% endblock %}
{% block content %}Default content{% endblock %}
{# the child's template/page.html.jinja #}
{% extends "base.html.jinja" %}
{% block title %}Overridden title{% endblock %}
{% block content %}{{ super() }} + more{% endblock %}
renders to:
The <prefix>: form matters only once the child declares its own base.html.jinja too, shadowing the
parent's for a bare reference — the same trap ADR-012 built the prefix for.
parent:base.html.jinja selects the second declaration of that name in the merged namespace,
regardless of which file contains the reference:
{# the child's own base.html.jinja -- shadows the parent's for a bare reference #}
{% extends "parent:base.html.jinja" %}
{% block content %}{{ super() }} + child layer{% endblock %}
{# the child's template/page.html.jinja -- extends its own base.html.jinja, bare #}
{% extends "base.html.jinja" %}
{% block content %}{{ super() }} + page layer{% endblock %}
renders content to Default content + child layer + page layer: the parent's original, extended once by the
child's own shadow, extended again by the child's page.
For a three-layer chain leaf → parent → base where all three declare base.html.jinja,
a bare base.html.jinja selects the leaf and parent:base.html.jinja selects the parent.
That remains true inside the parent's own files: references are not relative to their file's repository.
Consequently, repeating extends "parent:base.html.jinja" in the parent's declaration would select itself;
use distinct partial names when a deeper chain needs to reach multiple ancestor implementations.
A chain may be several templates deep (a base, extended by a language-specific template, extended by a
project's own), up to a small depth limit, but each template names exactly one parent — no multiple inheritance,
no diamonds. A chain that revisits a template it has already resolved is rejected before anything renders.
A remote (non-local) source needs the same confirmation a [data] kind = "git" source does — --trust, a
[trust] entry, or an interactive confirmation — because it is chosen by the template's author, not typed on the
command line, exactly like a git-kind data source is. See Confirmation. Unlike
[data], which is confirmed all at once before evaluation, an ancestor is confirmed as it is discovered — the
chain is only readable one clone at a time.
Inspection commands resolve ancestors too, but git tpl lint, git tpl questions and git tpl status
do not offer interactive confirmation or an invocation-wide --trust flag.
Remote ancestors must already have persistent [trust] entries in the user configuration.
Without that trust, lint and questions refuse resolution; status instead reports the available revision as unknown
(availableReferenceDescription and availableCommit are null) while retaining recorded rendering information.
This ancestor-resolution trust is separate from loading runtime data sources.
git tpl status and the rendered commit's trailers record the whole chain, not just the directly-configured
template — see What is in the commit. Full reasoning:
ADR-034.
Talking to the user¶
A template can show one note after init, and only after init.
Two forms, mutually exclusive:
# A literal, for a line or two.
note = "Next: run scripts/bootstrap.sh"
# A file in the template repository, for more than fits in a TOML string.
note_file = "NEXT-STEPS.md"
The key is note and not message because [questions.<name>].message already exists — it explains a
pattern.
TOML would fold a top-level message = written after any table into that question, silently.
note_file¶
The path is relative to the template repository root, not to the render root.
A note beside template.toml is "NEXT-STEPS.md", never "template/NEXT-STEPS.md".
This is the same namespace partials live in.
The file is read from the template and never rendered into the project. A note is guidance, not an artifact — if you want a file the user keeps, render one and let the note say to read it.
It is evaluated with MiniJinja if and only if the path ends in .jinja, exactly as a file is:
note_file = "NEXT-STEPS.md" # no interpolation; braces are preserved
note_file = "NEXT-STEPS.md.jinja" # evaluated with the answers
The path itself may be an expression, so a template can choose its note:
note_file = "notes/{{ language }}.md"
note_file = "{% if ci %}notes/ci.md{% endif %}" # renders empty: no note
A path that renders to nothing means no note.
A non-empty path naming nothing is an error, and init refuses before it writes anything — git tpl lint
reports the same thing without a repository.
Markdown presentation¶
Both inline notes and note files are displayed using Termimad when colour is enabled. Its supported Markdown includes headings, emphasis, code blocks, unordered lists, blockquotes and tables. Links, images, ordered lists and HTML remain source text; no resource is loaded. Code blocks are styled uniformly, without language-aware syntax highlighting. Markdown presentation is independent of MiniJinja evaluation and does not depend on a file's suffix.
When colour is disabled, the sanitised Markdown source is shown instead, preserving syntax and line breaks.
The normal colour policy applies: --color always renders Markdown even through a pipe,
while --color never always preserves the source.
Automatic colour normally turns formatting off for piped stderr, NO_COLOR or TERM=dumb.
What a note cannot do¶
Nothing here runs.
git-tpl executes no command a note names, and a note saying "run curl … | sh" is exactly as dangerous as a
README.md saying it — which is to say the user has to do it themselves.
See ADR-019.
In human terminal output, the note is shown in a block attributed to the template and sanitised first:
colour and https links survive, and everything else a terminal could act on does not.
When colour is disabled, terminal colour escapes and clickable hyperlinks are stripped too.
Markdown link destinations remain visible text.
Under --json, note carries the raw, unsanitised text instead.
JSON consumers must sanitise terminal controls before displaying it; the same applies to migration messages.
Rendering rules¶
.jinja files are templates¶
Cargo.toml.jinja is rendered and written as Cargo.toml.
The suffix is stripped, and only that suffix — a.jinja.jinja becomes a.jinja.
Everything else is copied byte-for-byte¶
.github/workflows/ci.yml lands unchanged.
This matters more than it sounds: GitHub Actions files are full of ${{ }}, and a tool that rendered every file
would mangle them.
If you want to template a workflow, name it ci.yml.jinja and escape the Actions syntax with {% raw %}.
Paths are templates too¶
Every path segment is itself rendered:
A segment that renders to the empty string causes that entry — and, for a directory, everything beneath it — to be skipped:
That is how you make a whole subtree conditional.
A directory segment that renders to . is different: it is transparent, not skipped.
It contributes nothing to the output path, but — unlike an empty segment — nothing beneath it is skipped either;
the rest of the path renders one level up, exactly as if that segment were never there:
renders to {{ package_name }}/mod.rs when use_src is false, and to src/{{ package_name }}/mod.rs when it is
true — one subtree, not two copies kept in sync by hand. Each level is independent, so several such segments
compose: a template with both a src/ toggle and a namespace toggle needs one physical copy of the subtree, not
one per combination.
. only means this on a directory segment. On the file's own name — the last segment of the path — it is still
an error; a file has no "above" to promote its content to.
A rendered value may also contain / itself, and it is split the same way: each piece between the separators
becomes its own real directory level, exactly as if the template had that many nested directories.
with package_path a computed value of "{{ 'src/' if use_src else '' }}" renders to pkg/__init__.py or
src/pkg/__init__.py depending on use_src — one expression, one subtree, no {% if %} needed at all. This is
the same mechanism as the .-transparent form above, generalized: a chain of {% if %}...{% else %}.{% endif
%} segments and one fanning-out expression build the same variable-depth path. Use whichever reads more clearly
for the template — several independent booleans usually read better one level at a time, while a single computed
path reads better as one expression.
A rendered path may not escape the tree
A piece may not be .., or contain a backslash — unconditionally, at any position. That is the actual
danger: .. is a request to write outside the render root, and a backslash is a separator Git itself treats
differently across platforms. Neither is about / itself, which is why / inside a rendered value is safe
to allow: it only ever produces more pieces, each checked the same way.
A piece that disappears — empty or . — is otherwise dropped in place, except as the file's own name, which
has no "above" to promote its content to and so still rejects both there.
The rendered tree is built directly as a Git tree, so all of this is caught before anything is written, but
it is rejected explicitly rather than left to chance.
Shared partials¶
A .jinja file outside the rendered subdirectory is a partial.
It is never written into a project, and it can be imported by name from any file that is:
flowchart LR
accTitle: Importing a shared partial
readme("template/README.md.jinja") -->|Imports| macros("macros.jinja: partial")
A partial is named by its path relative to the repository root, not to the rendered subdirectory, so a partial in a directory is:
{% include %} follows the same path rule but takes no alias — it inlines the partial's output directly, e.g.
{% include "macros/rust.jinja" %}.
Being outside the rendered subdirectory is the whole rule, and it is what keeps a macro definition from landing in every generated project. There is no manifest key and no reserved filename.
Two consequences worth stating:
- A
.jinjafile inside the rendered subdirectory is an output file and is not importable. One file, one meaning. - Only
.jinjafiles are loadable.{% include "data/licenses.toml" %}does not work; declare a data source instead, which knows how to parse it.
Partials are read from the same pinned revision as everything else, so editing one changes the rendered tree and
advances the ref.
They are available to manifest expressions too — a computed value may {% import %} the same macro a file
does.
A partial can also be the base of a {% extends %} chain. {% block %}, {% extends %} and {{ super() }} are
plain Jinja, and the loader that serves {% import %} and {% include %} serves these exactly the same way, by
name, from the same partial namespace — there is nothing extends-specific to configure:
flowchart LR
accTitle: Extending a shared Jinja partial
page("template/page.html.jinja") -->|Jinja extends| base("base.html.jinja: partial, declares blocks")
{# base.html.jinja #}
{% block title %}Default title{% endblock %}
{% block content %}Default content{% endblock %}
{# template/page.html.jinja #}
{% extends "base.html.jinja" %}
{% block title %}{{ project_name }}{% endblock %}
{% block content %}{{ super() }} + more{% endblock %}
renders to:
title is replaced outright; content extends the base's own content with {{ super() }} rather than
replacing it. The overall shape — which block comes first, and the newline between them — comes from the base,
since a file extending another contributes only its blocks, nothing else in its own body.
Getting the name wrong
A failed import lists the partials that do exist.
The usual cause is a path written relative to template/ instead of the repository root.
Binary files¶
A file with a NUL byte in its first 8 KiB is treated as binary and copied verbatim, even if it is named .jinja.
Rendering a PNG would corrupt it, and the failure would be silent.
Permissions¶
Git file kind and executable mode are preserved: regular files (100644), executable files (100755),
and symbolic links (120000) with their opaque target bytes.
For regular files, Git records no permission bits beyond executable mode.
Determinism¶
Byte-identical output for identical inputs, always. See Determinism for what that rules out.
The template context¶
Inside a .jinja file, these names are available:
| Name | What it is |
|---|---|
| (answers, by name) | Every answered question, at the top level. {{ project_name }}. |
| (computed, by name) | Every computed value, at the top level. {{ package_name }}. |
data |
Loaded data sources. {{ data.licenses }}. |
template |
Template metadata: template.name, template.description. |
Answers and computed values are at the top level because that is what templates actually read, and
{{ answers.project_name }} is noise.
They share one namespace, and a computed value may not reuse an answer's name — that is an error at load time,
not a silent shadow.
Full detail: Template context.
Publishing¶
There is nothing to package and nowhere to register.
Publishing a template is git push, and sharing it is sharing the URL someone passes to git tpl init.
What a visitor lands on is the repository itself, so the template's own README.md and LICENSE — the files
outside template/ that are never rendered — are the ones worth writing.
They are the only description anyone gets before cloning.
On GitHub, add both git-tpl and template topics to reusable template repositories, existing or new.
From the template repository's checkout, run:
Or, on the repository's main page, click the gear beside About, add git-tpl and template under Topics,
and click Save changes.
Browse templates on GitHub to find repositories carrying both topics.
These topics are a discovery convention between humans, nothing more.
git-tpl never queries GitHub, has no registry and resolves no names: git tpl init takes a Git URL and clones it.
A template without the topics works exactly as well — it is just harder to come across.