Skip to content

git tpl diff

Answer flags (--answer, --answers-from, --defaults, --strict-answers) require --dirty. The ordinary preview uses an existing rendering and cannot apply answer overrides. Native presentation is bound to the preview repository, including when ambient Git variables select another repository.

What merging the template would change.

For the template's source commit messages, use git tpl log [REVISION].

git tpl diff [--stat] [--name-only] [--reverse] [--exit-code] [--dirty] [-- <path>...]

It merges refs/tpl/<id> into HEAD in memory — no ref, no index and no worktree file is touched — and diffs HEAD against the result. What you see is what git tpl merge would do, before you do it.

$ git tpl diff --stat
 .github/workflows/release.yml | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 .travis.yml                  | 12 ------------
 README.md                    | 12 +++++++++---
 docs/logo.png                | Bin 0 -> 128 bytes
 4 files changed, 57 insertions(+), 15 deletions(-)

Patches and diffstats are displayed by native git diff, on stdout. A binary file shows Bin and byte sizes rather than misleading zero line counts.

Your Git display settings

Git selects its own pager and colors, exactly as for git diff. If you already use delta through core.pager, pager.diff or GIT_PAGER, it is used here too. No additional git-tpl configuration is needed. For example, to use an installed delta for Git diffs:

git config --global pager.diff delta

Git's configured diff drivers and textconv filters also apply as they would to git diff. This display step requires git on PATH. It runs after the preview is computed, including any --dirty rendering.

When stdout is a terminal, Git may open its pager; quitting it normally does not fail the command. pager.diff=false disables pagination. Redirected or piped stdout does not automatically open a pager:

git tpl diff > template-update.patch
git tpl diff --stat | cat

By default, Git's color.diff and color.ui settings determine patch/stat color. git tpl diff --color=always and --color=never override those settings. Git-tpl's environment-based color rules still apply to its own warnings, not to Git's display. If Git is configured to always emit colors, use --color=never to produce a plain patch.

--name-only remains a plain path list and --json remains structured data. Neither starts Git's display tools or pager.

The plain Git equivalent

For compatible, conflict-free merges, this is an approximate native-Git equivalent:

git diff HEAD "$(git merge-tree --write-tree HEAD refs/tpl/rust-library-template)"

git tpl diff computes its preview with the backend merge engine, which can differ from native Git and does not run external merge drivers. Native Git owns only the completed preview's presentation. The recipe above assumes merge-tree succeeds without conflicts; conflict output can contain more than a tree ID and cannot be passed verbatim as a revision. Pass -- <path> to narrow. Use whichever you prefer; nothing about git-tpl requires its own diff command.

Note that a plain git diff HEAD refs/tpl/<id> is not the same thing. It compares the two trees directly, so every file your project has and the template never produced — your own sources, your CHANGELOG.md, git-tpl's own .config/git.tpl.toml — appears as a deletion. Merging deletes none of them: they are in the merge base.

Reading it

The direction is HEAD → merged, so:

  • added — the template produces a file your project does not have
  • deleted — the template stopped producing a file it once did, and merging would remove it
  • modified — merging would change the file. Could be the template's change applied cleanly, or a conflict.

Conflicts

When the merge cannot reconcile a file on its own, the preview shows it with <<<<<<< markers — exactly what a merge would leave in your worktree — and says which files:

$ git tpl diff --stat
warning: 1 file would conflict; shown with conflict markers
         README.md

 README.md | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

The exit code is still 0. A conflicting preview is a correct answer, and knowing about it in advance is the point of looking.

In CI

git tpl diff --exit-code --name-only

--exit-code exits 1 when merging the template would change something and 0 when it would not — Git's own convention, so a job can assert "the template output has not drifted" without parsing anything.

It keys on difference, never on conflict. Without the flag a conflicting preview stays at 0, as above; with it, a conflicting preview exits 1 because it is a difference, not because it conflicts — and a clean difference exits 1 just the same. So --exit-code cannot answer "would this conflict?". That is deliberate: a conflicting preview is a correct answer to the question asked, and failing on it would make the flag useless on exactly the repositories that need it. To gate on conflicts, read the conflicts array from --json.

--json is a reporting mode, not a separate command: the exit code means the same thing there.

Previewing an uncommitted template edit

By default diff compares against refs/tpl/<id> — the last thing update rendered. --dirty renders the template's working tree now and previews against that instead, so a template edit can be inspected before it is committed, let alone updated to.

git tpl diff --dirty --stat

The preview reuses applicable answers recorded in .config/git.tpl.toml. New questions, or previously skipped questions that become applicable, can still prompt; untrusted network data can also require confirmation. Use --defaults for noninteractive answers and pre-authorize required network access through persistent trust. --answer overrides them for the preview only; nothing is recorded. Unknown answer keys warn on stderr, including under --quiet and --json; the JSON payload also includes ignoredAnswers (empty without a dirty preview).

Nothing is written. The preview is a commit no ref points at — a loose object git gc reclaims — so refs/tpl/<id> does not move and a later update has nothing to reconcile. Local templates only; a remote source fails with tpl::resolve::dirty_needs_local.

show --dirty reads one file out of the same preview, and status --dirty is the cheap check that there is anything to look at.

Narrowing

git tpl diff -- Cargo.toml
git tpl diff --stat -- src/
git tpl diff --name-only

-- <path> and --reverse apply to every mode: the patch, --stat and --name-only all report the same diff, so they narrow and reverse alike.

Options

Option Meaning
--stat A per-file summary with line counts, instead of the full patch.
--name-only Paths only, on stdout. Wins if --stat is also given.
--reverse Diff the other way, merged → HEAD: the inverse patch.
--exit-code Exit 1 when there is a difference, like git diff --exit-code. Keyed on difference, not conflict.
--dirty Preview the template's working tree rather than the rendered ref. Local templates only.
--answer, --answers-from, --defaults, --strict-answers Override the recorded answers for a --dirty preview. Nothing is recorded and no ref moves.
-- <path>... Limit to these paths.