Skip to content

git tpl update

A clean update after committing an exact dirty template snapshot records clean provenance even if output is unchanged. This lets source-history inspection recover after the resulting commit is merged. Dry runs validate ordered migration moves against the previous rendering and report the same move errors as an update.

Source objects use the Git cache; mutable refs refresh online and never fall back to stale names. Global --offline requires local sources or cached full commit IDs for every source actually used. Publication through --push or tpl.autoPush is refused before the rendered ref advances when offline.

Concurrent init/update operations in one worktree are refused until the first finishes saving configuration. A changed ref or configuration discovered after prompting is refused rather than overwriting the newer state.

Publication compares the rendered ref's tip under a lock, including when the ref was absent. If another writer has changed it, tpl::git::stale_ref reports the expected and actual tips. Inspect the current ref before retrying; the failed publication does not save newly answered configuration.

Re-render the template and advance refs/tpl/<id>.

To update and immediately integrate in one invocation, use git tpl pull.

Read pending source commit messages before updating with git tpl log ..<ref>, where the reference names a branch, tag or commit in the template repository.

git tpl update [options]

What it does not do

It does not touch your branch. Not HEAD, not the index, and it never writes a rendered file into your working directory.

This is structural rather than a promise: the rendered tree is built directly as a Git tree object and the ref is moved. There is no code path that opens a rendered file for writing.

The one file update does write on disk is .config/git.tpl.toml itself — project configuration, not render output. It saves that file only when resolved answers or composed child locks change semantically, including answer overrides and new questions, unstaged, exactly as a hand edit would. This applies whether a new rendered commit is made or the output is already up to date. When answers and locks are unchanged, the configuration keeps its exact bytes, comments and formatting, even if the rendered output changed. Nothing else in the worktree moves.

$ git tpl update
...
$ git status
On branch main
nothing to commit, working tree clean

What it does

flowchart TD
    accTitle: Update advances the rendered ref
    accDescr: Rendering builds a Git tree and advances the ref, optionally inserting a rename-only migration commit.
    config(".config/git.tpl.toml") --> source("Template source/ref")
    source --> resolve("Fetch/resolve template")
    resolve --> data("Load data sources")
    data --> answers("Resolve answers/computed values")
    answers --> render("MiniJinja rendering") --> tree("New Git tree")
    tree --> migration{Newly crossed migration needs a rename-only commit?}
    migration -->|Yes: move beside other changes| rename("Rename-only commit: parent is current ref tip")
    migration -->|No| commit("New commit: parent is current ref tip")
    rename --> child("New commit: parent is rename-only commit")
    commit --> ref("refs/tpl/#60;template-id#62;")
    child --> ref

Output

$ git tpl update

Template:  https://github.com/noirbizarre/rust-library-template
Revision:  v1.3.0 (8b3e7d1) → v1.4.0 (4f2c1a9)

Updated refs/tpl/github-com-noirbizarre-rust-library-template

  modified  Cargo.toml
  modified  README.md
  added     .github/workflows/release.yml

── from the template ──────────────────────────────────────
  0.4 split `config.rs` into a module; your overrides moved
  with it.
────────────────────────────────────────────────────────────

Your rendered worktree files were not modified.

Run:
  git tpl diff
  git tpl merge

When nothing changed

If the rendered tree is byte-identical to the current ref tip, normally no commit is made:

$ git tpl update
Already up to date with https://github.com/noirbizarre/rust-library-template at v1.4.0 (4f2c1a9).

This is why determinism matters. A renderer that varied by a timestamp would create a commit every run, and every one of them would be noise you had to merge.

A newly crossed migration still produces a commit to record that it was applied. A changed composed child revision can also require a provenance-only commit, even when the rendered tree is identical, so the pinned child commit is recorded in history.

What triggers a change

Any of:

  • the template moved (a new commit on the tracked branch, or a changed ref)
  • an answer changed in .config/git.tpl.toml
  • a data source returned something different
  • git-tpl itself renders differently

All four produce the same thing — a new commit on the ref — because from Git's point of view they are the same event: the desired state changed.

Append-only

The new commit's parent is the current tip. update never amends, never rebases, never force-updates.

That holds even when the reason is a changed answer. Rewriting the ref would destroy the merge base your branch already shares with it, and the next merge would conflict on everything. See The Git model § Append-only.

Occasionally update adds two commits instead of one: a migration that moves a file alongside some other change gets a content-identical rename commit first, then the ordinary rendered commit as its child. Both are ordinary commits on the same append-only history; see Migrations.

Migrations

A template repository may declare migrations in a migrations/ directory, sibling to template.toml. Each file may carry a message and a list of path moves:

# migrations/2026-08-config-move.toml
message = "0.4 split `config.rs` into a module; your overrides moved with it."

[[moves]]
from = "src/config.rs"
to = "src/config/mod.rs"

No template ever declares a version, and no project ever records one: update discovers a migration by diffing the template repository's own tree between the revision your project was previously rendered from and the one it just resolved. A migration is discovered — its message shown, its moves applied — exactly once, at whichever update first crosses it, however many template commits separate the two renderings. See ADR-024 for the full reasoning, including why a move is applied as its own commit rather than folded into the ordinary one.

If the template branch used for the previous rendering was squash-merged and deleted, its recorded source commit may no longer be available in a fresh template clone. The local refs/tpl/<id> still holds the previous rendering, so update and update --dry-run can continue from it when the current template has no migration files. If the current template does contain migrations, update cannot tell which were already applied and stops with tpl::ops::missing_template_revision before changing the ref. Restore the recorded Template-Commit under a fetchable branch or tag in the template repository, then retry. Fetching it into the project repository alone does not help: migration discovery reads the template repository.

A migration message is sanitised and framed exactly like a template's init-time note (see init): shown once, in an attributed block, never executed. It is rendered as Markdown when colour is enabled; otherwise its sanitised Markdown source is preserved. Its --json field carries the raw text, since a --json consumer is not a terminal.

git tpl lint validates a migration file's shape without a project. Whether its declared moves actually apply — whether from exists in your project's previous rendering — can only be known at update time, and a mismatch there is refused before any commit is written.

Template authors can exercise this with declarative migration test cases. They initialize a known old revision, commit optional local customisations, update and merge, then assert the resulting project paths, contents and migration messages. Use both direct jumps and explicit intermediate destinations to verify upgrades across multiple revisions.

When there is no ref to advance

update needs refs/tpl/<id> to hang the new commit from. If it is not there, the commit is written as an orphan and update says so:

$ git tpl update
...
No refs/tpl/rust existed here, so this update started a new history.
Preserve this history and inspect the original rendering before merging:
fetching alone cannot repair an orphan's missing merge base.

If this warning has already appeared, preserve the new ref for inspection. The absent-ref restoration procedure does not reconcile an existing orphan.

Two things cause it, and both are legitimate, which is why this is a warning and not a refusal:

  • You cloned a project without the local ref. refs/tpl/* is not fetched by default. Before updating, restore the original rendered ref. Fetching alone does not adopt it; an equal re-render cannot recover its ancestry.
  • You edited source or id in .config/git.tpl.toml. The ref name is derived from them, so a new one means a new ref. That is the documented way to point a project at a different template, and starting a fresh history is what you asked for.

New questions

A template that added a question since your last render has no recorded answer for it. update prompts, and writes the answer back to .config/git.tpl.toml.

With --defaults, or tpl.interactive false, the default is taken instead; a new question with no default is then an error.

Options

Option Meaning
--ref <ref> Render this revision instead of the configured one. Does not change the configuration.
--answer k=v Override an answer for this run and record it, even if the rendered tree is unchanged. Repeatable.
--answers-from <path> Read answers from a TOML, JSON or YAML file. Repeatable. See Answers from a file.
--defaults Accept defaults for unanswered questions instead of prompting.
--strict-answers Fail on an answer that names no question, rather than warning.
--trust Fetch remote data sources without confirming. Per invocation; nothing is recorded.
--dirty Render the template's working tree. Local templates only.
--push Push after creating a rendered commit. Same as tpl.autoPush; unchanged renderings are not pushed.
--remote <name> The remote --push uses. Default origin, or tpl.remote.
--dry-run Report what would change, including migration-only commits; write nothing.

--ref and --dirty are mutually exclusive — asking for both is refused at the parser.

Use git tpl push to publish an existing rendering or retry a failed automatic push. An already-current update --push does not push, even if the remote lacks the local rendering.

Machine-readable output

Dry runs predict semantic configuration edits through answersChanged and composedChanged, including child-lock repairs when the rendered tree is already current. They leave the configuration unchanged.

git tpl --json update emits its outcome on stdout as a single JSON object, with the prose on stderr. The payload is described in JSON output.