Skip to content

Home

git-tpl

Git-native project templates.

git-tpl renders a template into a dedicated Git ref. Updating the template advances that ref. You incorporate the changes with a normal git merge.

That is the whole idea. There is no reconciliation algorithm, no patch replay, no conflict resolver — Git already has all of those, and they are better than anything a template tool would write.

The difference

Traditional template tools own the update:

flowchart LR
    accTitle: Traditional template update pipeline
    template("Template") --> generated("Generated project")
    generated --> reconcile("Custom reconciliation logic") --> updated("Updated project")

git-tpl owns only the rendering:

flowchart LR
    accTitle: Git-native template update pipeline
    template("Template") --> ref("Rendered Git ref")
    ref --> merge("Normal Git merge") --> updated("Updated project")

What that buys you is not subtle. git log refs/tpl/<id> is the template's history. git tpl diff is what the template would change. git merge refs/tpl/<id> is the update, with the same three-way merge, the same conflict markers, the same git rerere, the same --abort you already know.

Getting started

brew install noirbizarre/tap/git-tpl

cd my-project
git tpl init https://github.com/noirbizarre/rust-library-template

Homebrew is one of five ways in — see Installation. Homebrew and AUR packages install the man page and completions; release archives contain them for manual installation. cargo install git-tpl and cargo binstall git-tpl place only the binary, as does mise's cargo backend. With these binary-only installations, git tpl --help reports No manual entry for git-tpl until you generate and install the man page. Use git tpl help or git tpl help <command> for built-in help without man pages.

That works on an empty repository and on a project that already has files — see adopting an existing project.

Later, when the template moves on:

git tpl update   # advances refs/tpl/<id> — rendered files are not applied
git tpl diff     # what would change
git tpl merge    # take it

Two things worth knowing up front

git tpl update leaves HEAD, the index, and rendered worktree files untouched. It writes a Git tree directly and advances the rendered ref. Changed answers or composed child locks can update .config/git.tpl.toml as an unstaged edit. You decide when to merge, and merging is an ordinary Git operation you can abort.

Template refs are not pushed automatically. A contributor cloning the project does not need template state to work on it. git push and git pull ignore refs/tpl/* entirely; git tpl push and git tpl fetch are explicit.

What git-tpl deliberately is not

This is not a project generator

Generating files is the least interesting thing a template tool does. It is the second and hundredth update that is hard, and git-tpl's answer to that is to not solve it — to produce a Git state and let Git do the rest.

Templates cannot execute code. There are no hooks, no post-generation scripts, no embedded Python, no shell. Dynamic behaviour is MiniJinja expressions over a controlled context, and nothing else. See Security.

Compatibility with Copier or Cruft is not a goal. They are useful references when weighing a design decision, and that is all.