ADR-001: The rendered state of a template is a Git ref¶
Status: accepted
Context¶
A project generated from a template needs to receive template updates later. That is the hard part — generating files once is trivial.
The established approach (Copier, Cruft, Yeoman) is for the tool to own the update: keep a copy of, or a description of, the previously generated output; re-render; compute a difference; apply it to the user's files. Every tool in this space then spends most of its complexity budget on that application step — three-way reconstruction, patch replay, conflict markers, rename detection.
We have a system that does all of this, extremely well, and that the user already has installed and already understands.
Decision¶
The rendered output of a template is a commit on a dedicated ref, refs/tpl/<template-id>.
Updating the template adds a commit to that ref.
The user incorporates changes with a normal git merge.
---
config:
theme: base
# Zensical overrides classless text; inherit Mermaid's per-branch label colors instead.
themeCSS: ".branchLabel text { fill: inherit !important; }"
---
gitGraph
accTitle: Project and rendered-template histories
accDescr: Independent roots A and G0 meet at B; later, rendered state G2 is merged into main at M.
%% Create both lanes before any commit so G0 has no parent.
branch "refs/tpl/foo"
checkout main
commit id: "A"
checkout "refs/tpl/foo"
commit id: "G0"
checkout main
merge "refs/tpl/foo" id: "B"
commit id: "C"
checkout "refs/tpl/foo"
commit id: "G1"
checkout main
commit id: "D"
checkout "refs/tpl/foo"
commit id: "G2"
checkout main
merge "refs/tpl/foo" id: "M"
git-tpl's entire job is to produce the desired rendered Git state. Once that state exists, Git takes over.
Consequences¶
The previous rendering is a real commit, so a merge has a real base. Your edits and the template's changes are just two sides of a three-way merge.
Everything in Git works, unchanged: git log refs/tpl/<id>, git diff HEAD refs/tpl/<id>, git merge, --abort,
rerere, mergetool, .gitattributes merge drivers, signed commits, bisect.
There is no sidecar state. Nothing can disagree with anything, because there is only one record.
The tool is small. Most of what a template tool normally does is not here.
The cost: rendering must be deterministic, because a rendering that varied would create a commit on every run
(ADR-006).
And the model requires the user to understand that refs/tpl/<id> exists — which the documentation leads with,
rather than hiding.