Quick Start¶
This builds a template from scratch and uses it, so that every piece is visible. If you already have a template, skip to Use it.
Write a template¶
A template is a normal Git repository with a template.toml at its root and the files to render in a
template/ directory.
template.toml:
name = "rust-library"
description = "A small Rust library"
[questions.project_name]
type = "string"
prompt = "Project name"
[questions.license]
type = "choice"
prompt = "License"
choices = ["MIT", "Apache-2.0"]
default = "MIT"
[questions.ci]
type = "boolean"
prompt = "Enable CI?"
default = true
[computed]
package_name = "{{ project_name | lower | replace(' ', '-') }}"
template/Cargo.toml.jinja:
template/README.md.jinja:
And a file rendered only when asked for. Path segments are rendered too, and a segment that comes out empty skips that entry — and, for a directory, everything beneath it. So put the condition in the path:
Answer Enable CI? with no and the whole .github subtree is left out.
Commit it:
Use it¶
From the template directory, return to its parent so the project and template are siblings:
init also accepts the destination directly, which is mkdir, git init and init in one line — see
Starting from nothing.
The template path stays relative to wherever you run the command though, so that form reads
../rust-library-template differently; commands below assume you cded into my-project as above.
git-tpl asks the questions, writes .config/git.tpl.toml, renders the template into
refs/tpl/rust-library-template, and merges it into your branch.
This works on a project that already has files too — the merge reconciles the two sides. See an existing project.
Template: ../rust-library-template
Revision: main (4f2c1a9)
Created refs/tpl/rust-library-template
added .github/workflows/ci.yml
added Cargo.toml
added README.md
Merged into main.
Answers recorded in .config/git.tpl.toml and committed.
Look at what happened:
Change the template, then update¶
Back in the template, edit template/README.md.jinja and commit.
Then, in your project:
Template: ../rust-library-template
Ref: refs/tpl/rust-library-template
Revision: main (4f2c1a9) → main (8b3e7d1) template has moved
Rendered: 1 rendering
Merged: yes
Worktree: clean
The template has moved. Run:
git tpl update
Template: ../rust-library-template
Revision: main (4f2c1a9) → main (8b3e7d1)
Updated refs/tpl/rust-library-template
modified README.md
Your working tree was not modified.
Run:
git tpl diff
git tpl merge
Note "Your working tree was not modified."
update moved a ref and nothing else — git status is still clean, HEAD has not moved.
When you want to update and merge immediately, git tpl pull combines those steps.
Use the separate commands above when you want to inspect the diff first.
If you had also edited README.md yourself, that merge behaves like any other Git merge: it combines the
changes, or it stops with conflict markers and you resolve them.
git merge --abort works, because it is a merge.
Where to go next¶
- The Git model — what is actually happening
- Template format — the full manifest
- Questions — conditionals, dynamic defaults
- Local template development — the tight loop