Skip to content

JSON output

Template test context assertions report contextMissing, contextUnexpected, contextMismatch and contextExpression. Path failures include path and actualPresent; missing values omit actual rather than encoding absence as null. Equality failures include typed expected and, when present, typed actual, preserving null recursively. Presence-only missing failures omit expected; expression failures include expression, expected: true and actual. See context assertions.

Render files entries retain executable (boolean) and add mode, an octal string: "100644", "100755" or "120000". For a symbolic link, bytes counts its opaque target bytes and templated is false.

--json is global. Every command accepts it and every runtime failure emits the same envelope — including commands with no success payload of their own. Almost every command emits its payload to stdout; the three whose stdout is already the payload are show, completion and man.

Human output goes to stderr, so a piped --json stream stays parseable even when the command is chatty:

git tpl --json questions ./template | jq '.questions[] | select(.when == null) | .name'

The global flags

Six flags are accepted by every command, before or after the subcommand:

Flag Default Meaning
--json off The payload on stdout as one object, as described here. Silences the prose narration, as --quiet does.
-q, --quiet off Suppress everything but errors and warnings. The exit code still says what happened.
-v, --verbose off More detail. Repeatable — -vv for more again.
--color <auto\|always\|never> auto Auto-detect git-tpl's colors; native diff display follows Git's configuration.
--offline off Disable network acquisition; require local or already cached immutable sources.
--cache-dir <PATH> platform cache Override the source-object cache directory; the path must be absolute.

--cache-dir takes precedence over GIT_TPL_CACHE_DIR, which takes precedence over the platform default. See cache location and offline policy for the full rules.

A warning is deliberately louder than the rest: neither --quiet nor --json suppresses one, because a warning names something the caller is getting wrong right now. Warnings go to stderr, so a JSON payload on stdout stays parseable. Lint findings are report data: --quiet retains them on stderr, while --json puts them only in diagnostics[]. Without --json, diff patches and diffstats are also payloads on stdout, displayed by native Git. With --json, diff bypasses Git's display tools and pager entirely.

Failure

Argument parsing happens before command dispatch and JSON reporting. Unknown options, missing arguments and conflicting flags produce the parser's plain-text diagnostic on stderr and exit 2, even with --json; they have no JSON envelope or error.code. Successful help, help <command>, --help and --version also retain their raw output. After successful parsing, runtime failures use one shape, from every command:

{
  "ok": false,
  "error": {
    "code": "tpl::render::collision",
    "message": "`a.jinja` and `b.jinja` both render to `x`",
    "help": "two template files cannot produce the same output file",
    "causes": [{ "code": "tpl::eval::expression", "message": "…", "help": "…" }],
    "labels": [{ "offset": 412, "length": 9, "label": "…" }]
  }
}

Branch on error.code, never on message. causes carries the chain: the outer error names the file, the one beneath names the reason, and only the pair is actionable.

The exit code is unchanged — non-zero on failure, 2 from status when a template update is pending. Reading the code to decide what went wrong and the exit status to decide whether it did are different jobs.

Success

Every payload carries "ok": true, so a caller can check one field without first knowing which command it ran.

render

See also log for source commits without rendering.

{ "ok": true,
  "template": { "name": "rust", "description": "…" },
  "revision": { "reference": "main", "commit": "a17b0b2…", "dirty": false },
  "output": "/tmp/out",
  "files": [{ "path": "Cargo.toml", "bytes": 412, "executable": false, "templated": true }],
  "ignoredAnswers": [],
  "skippedByGitignore": [] }

templated says whether the file went through MiniJinja or was copied byte-for-byte. It is the only way to tell, from the output, that a workflow full of ${{ }} was copied rather than rendered-and-survived.

skippedByGitignore names the working-tree files a .gitignore kept out of a --dirty render — always empty for a committed revision. Only paths a render reads are listed: those under root, the .jinja partials outside it, and the files named by declared data sources. A path that could never have been rendered is not reported, however it is ignored. It is a report, not an error: the render succeeded, and a caller comparing the file list against its expectations needs to know why one is absent. See the authoring loop.

log

{ "ok": true,
  "source": "https://github.com/org/template", "id": "github-com-org-template",
  "ref": "refs/tpl/github-com-org-template", "appliedRendering": "8b3e7d1…",
  "applied": { "reference": "v1.0.0", "commit": "a17b0b2…", "dirty": false },
  "target": { "reference": "main", "commit": "4f2c1a9…", "dirty": false },
  "exclude": { "reference": "v1.0.0", "commit": "a17b0b2…", "dirty": false },
  "mode": "range", "targetDescendsFromApplied": true, "maxCount": 20,
  "entries": [{ "commit": "4f2c1a9…", "subject": "feat(ci): add a release workflow",
                "committedAt": 1793284542,
                "conventional": { "type": "feat", "scope": "ci", "breaking": false } }] }

log uses mode: "applied" without an argument, mode: "history" for a single explicit revision, and mode: "range" for two-dot syntax. The example above represents git tpl log ..main. target is the included endpoint; exclude is the excluded endpoint in range mode, otherwise null. In applied mode, target equals applied; in history mode, all ancestry of target is selected. Omitted range endpoints resolve to applied, including its reference (which may be null). appliedRendering is a project-side commit; the revision objects and entries identify source-side commits. All commit IDs are full hexadecimal strings; the examples abbreviate them for readability. The applied reference can be null when old provenance records only a source commit. source comes from that applied rendering's provenance, not a subsequently edited attachment.

entries is always an ordered array, empty when there are no selected commits. maxCount is the effective count limit, or null with --all. targetDescendsFromApplied indicates whether the target includes the applied commit in its ancestry. Ranges use target reachability minus exclude reachability, even when this field is false. The ancestry field is metadata, not a filter on the selected history.

committedAt is the signed Unix committer timestamp in seconds. Relative/absolute date preferences do not affect JSON. subject preserves decoded source text; non-UTF-8 messages are decoded lossily. conventional is null for unrecognized subjects; otherwise it contains the original type, an optional scope (null when absent), and whether the subject carries !. Breaking-change footers in the body are not parsed.

lint

{ "ok": true,
  "template": "rust",
  "diagnostics": [{ "severity": "warning", "code": "tpl::lint::undeclared",
                    "message": "…", "help": "…", "path": "Cargo.toml.jinja",
                    "denied": false }],
  "errors": 0, "warnings": 1, "denied": 0 }

ok is about the command, not the template: warnings do not fail it unless --deny says so. Check the exit code, or errors and denied together.

severity is the rule's, denied is this run's policy. A --deny never rewrites the severity, so "severity": "warning", "denied": true remains distinguishable from a native error. errors and warnings count by severity; denied counts the warnings promoted, and is what makes the exit code 1 when errors is 0. An --allowed finding appears nowhere and is counted nowhere.

questions

Each question includes itemPattern and itemMessage for enforced list-item validation, or null when unset. itemMessage contains the effective validation message, including the default when no custom message is declared.

{ "ok": true,
  "template": { "name": "rust", "description": "…", "root": "template" },
  "questions": [{ "name": "crate", "order": 0, "type": "string", "prompt": "Crate name",
                  "help": null, "default": null, "defaultIsExpression": false,
                  "when": null, "defaultWhenSkipped": false, "pattern": "^[a-z0-9-]+$",
                  "message": "…", "defaultFrom": null }],
  "computed": ["lib_name"],
  "data": [{ "name": "targets", "source": "data/targets.toml", "kind": "template",
             "format": "toml", "sha256": null }] }

Questions come in resolution order, which is the order they must be answered in when a when or a default references an earlier answer.

defaultIsExpression distinguishes "{{ crate }}" from a literal. defaultFrom is the machine-seeded default, which pre-fills a prompt and is never the answer. defaultWhenSkipped mirrors the manifest's default_when_skipped: when true, default reaches the context even while the question is skipped, though it is still never the answer.

Three keys appear only when the question declares them: choices, an array of { value, label, help }; choicesFrom, the reference a choices_from names; and choicesResolved, that reference's values, present only when it points at a data file inside the template — which saves the caller fetching and parsing it, and is why a remote source has no resolved form here. choicesResolved is always a string array, including for structured choices. An accompanying choicesResolvedDetails array carries {value, label, help} records; label falls back to the value and absent help is null. Static sources use TOML/JSON/YAML format and checksum validation and their declaring layer's origin.

context

{ "ok": true,
  "answers": {…}, "computed": {…}, "gatedDefaults": {…}, "data": {…}, "template": {…}, "flat": {…},
  "extends": { "chain": [], "questions": {…}, "data": {…} } }

flat is what a template body sees: answers, computed values and gatedDefaults merged into one table. gatedDefaults holds the values injected for skipped default_when_skipped questions — kept apart from answers because they are not answers. data and template are not in flat — they are siblings of it here, and namespaces of their own in a template.

extends is documented in context: the [extends] chain, and which layer of it declared each inherited question or data source — []/{} for a template with no chain.

With --eval:

{ "ok": true, "expression": "{{ x | length }}", "type": "an integer", "value": 3 }

status

Documented in status. --json is the only spelling: the --format json it replaced was removed in 0.7.

diff

Dirty previews include ignoredAnswers for supplied or recorded keys that name no question; non-dirty diffs return an empty list. Dirty show keeps raw stdout and reports those keys only on stderr.

{ "ok": true,
  "conflicts": ["mise.toml"],
  "changes": [{ "path": "mise.toml", "kind": "modified", "insertions": 9,
                "deletions": 3, "binary": false }],
  "insertions": 9, "deletions": 3 }

conflicts names the paths a merge could not resolve on its own. They are still reported as changes — the preview contains them with conflict markers, which is what a merge would leave in the worktree.

init

For init --dry-run, files is null without --defaults because no rendering was attempted. With --defaults, success requires a completed rendering and files is its path array; missing answers, trust refusals and render failures produce the ordinary diagnostic failure envelope.

{ "ok": true,
  "id": "rust", "ref": "refs/tpl/rust",
  "template": "https://github.com/noirbizarre/rust.tpl",
  "revision": { "reference": "main", "commit": "a17b0b2…", "dirty": false },
  "commit": "f4c9e21…",
  "changes": [{ "path": "Cargo.toml", "kind": "added" }],
  "merge": { "result": "merged", "commit": "…" },
  "configPath": ".config/git.tpl.toml", "configCommitted": true,
  "ignoredAnswers": [],
  "note": "Next: run scripts/bootstrap.sh",
  "remotes": [{ "name": "origin", "url": "git@github.com:acme/demo.git",
                "status": "added", "existing": null }] }

revision describes the template — the same shape render reports. commit is the different, project-side commit init created on the rendered ref; the two are never the same repository's history.

template is the expanded URL, never the mine: shortcut that may have been typed: it is what was recorded in the project, and a shortcut means nothing on anyone else's machine.

merge is null under --no-merge, which is a different thing from a merge that ran and found nothing to do ({"result": "upToDate"}).

note is the template's own note, null when it declares none. It is unsanitised, even if stdout is a terminal: JSON preserves the raw text. Strip terminal control sequences before displaying decoded text to a user. Branch on its presence, never on its text: note prose is not a contract.

remotes lists the [remotes] a template declared, in declaration order, with what became of each:

status Meaning
added It was not configured, and now is.
unchanged It was already configured with this URL.
skipped A remote of that name exists with a different URL, and was left alone. existing names it.

url is always what the template asked for, including when it was refused — which is the case you most need it in. existing is null unless the two disagree, so its presence is the signal. Both are init-only: update neither adds a remote nor shows an init-time note. It has its own, narrower mechanism for the same purpose — see migrations under update, below.

With --dry-run the payload is a different shape entirely, because nothing was created and there is no ref, commit or merge to report:

{ "ok": true, "dryRun": true,
  "template": "https://github.com/noirbizarre/rust.tpl",
  "revision": { "reference": "main", "commit": "a17b0b2…", "dirty": false },
  "questions": [{ "name": "crate", "kind": "question", "supplied": false },
                { "name": "lib_name", "kind": "computed", "supplied": false }],
  "files": ["Cargo.toml"],
  "ignoredAnswers": [] }

questions is in resolution order and includes the computed and data nodes the graph resolves alongside them, which kind distinguishes. files is null, not [], unless --defaults was passed: without it the list was never computed, and producing it would mean asking the whole questionnaire — which is what a dry run is avoiding. An empty array would claim the template renders nothing.

update

{ "ok": true, "result": "upToDate",
  "id": "rust", "ref": "refs/tpl/rust",
  "template": "https://github.com/noirbizarre/rust.tpl",
  "revision": { "reference": "main", "commit": "a17b0b2…", "dirty": false },
  "answersChanged": false, "ignoredAnswers": [] }
{ "ok": true, "result": "updated",
  "id": "rust", "ref": "refs/tpl/rust", "template": "…",
  "commit": "f4c9e21…",
  "previousRevision": { "reference": "main", "commit": "a1b2c3d…", "dirty": false },
  "revision": { "reference": "main", "commit": "a17b0b2…", "dirty": false },
  "changes": [{ "path": "Cargo.toml", "kind": "modified" }],
  "answersChanged": false, "startedNewHistory": false,
  "migrations": [{ "path": "migrations/2026-08-config-move.toml",
                    "message": "0.4 split `config.rs` …",
                    "moves": [{ "from": "src/config.rs", "to": "src/config/mod.rs" }] }],
  "movedCommit": "9c1f4a0…",
  "ignoredAnswers": [], "pushed": null }

Branch on result: upToDate or updated. It is the one thing the exit code does not say — both succeed. answersChanged may be true even for upToDate: newly resolved answers are saved to the project configuration without adding a rendered-ref commit. result is always updated, never upToDate, when migrations is non-empty: discovering a migration always produces a commit, so the same one is never discovered again on a later update. An update --dry-run that crosses such a migration reports wouldUpdate with its migrations and potentially empty changes, even when the rendered tree is identical. See ADR-024.

migrations lists every migration newly discovered by this update, in application order; empty on almost every update. message is null when the migration declares none, and — like note above — is unsanitised: strip escape sequences yourself before printing it. moves is [] when the migration moved nothing.

movedCommit is the intermediate, content-identical rename commit's id, or null when none was needed — which is most of the time, including most updates that do carry a migration. See Migrations.

startedNewHistory is true when there was no refs/tpl/<id> to descend from, so the new commit is an orphan sharing no ancestry with anything the branch has merged. Two causes, both legitimate: the configuration's source or id was edited, or the project was cloned without refs/tpl/* and never restored its local rendered ref. A git tpl merge from here has no merge base and can conflict on every file. Before updating a fresh clone, restore the original ref. Fetching alone does not adopt it or reconcile an orphan that has already been created; preserve both histories.

previousRevision is null on the first rendering. When present, its reference and commit are independently null if the recorded provenance the previous rendering left could not supply one — an older trailer format, or a hand-edited commit on the ref. pushed names the remote when tpl.autoPush pushed automatically, null otherwise — the push still happens under --json, only its prose is silenced.

With --dry-run, result is upToDate or wouldUpdate, and the payload has its own shape:

{ "ok": true, "dryRun": true, "result": "wouldUpdate",
  "id": "rust", "ref": "refs/tpl/rust", "template": "…",
  "revision": { "reference": "main", "commit": "a17b0b2…", "dirty": false },
  "changes": [{ "path": "Cargo.toml", "kind": "modified" }],
  "migrations": [], "ignoredAnswers": [], "answersChanged": false, "composedChanged": false }

wouldUpdate reports id, ref, template, revision, changes, migrations, ignoredAnswers, answersChanged and composedChanged. It does not report commit, previousRevision, startedNewHistory, movedCommit or pushed. A dry-run upToDate report includes changes: [], answersChanged and composedChanged, but no migrations field. Both outcomes predict semantic configuration edits, including child-lock repairs without a new rendered commit. Neither dry-run outcome writes configuration or publishes a ref.

pull

pull emits one success envelope with update and merge objects. Each contains the corresponding command's normal success payload, without a nested ok field:

{ "ok": true,
  "update": { "result": "upToDate", "id": "rust", "ref": "refs/tpl/rust",
    "template": "../rust.tpl",
    "revision": { "reference": "main", "commit": "937573e…", "dirty": false },
    "answersChanged": false, "ignoredAnswers": [] },
  "merge": { "result": "merged", "commit": "a17b0b2…", "id": "rust", "ref": "refs/tpl/rust" } }

Update's upToDate does not imply merge's upToDate: a previous rendering may still need integration. Conflicts report ok: true and merge.result: "conflicted", with paths in merge.conflicts. Failures use the normal diagnostic envelope and underlying stable code. They do not include successful phase payloads; an update or push may already have completed before a later failure. Inspect the rendered ref and project state before retrying.

merge

{ "ok": true, "result": "merged", "commit": "a17b0b2…",
  "id": "rust", "ref": "refs/tpl/rust" }

result is one of upToDate, fastForward, merged, staged, conflicted or aborted. commit accompanies fastForward and merged; conflicts accompanies conflicted. This is the same object init reports under merge, so a caller handles both with one function.

A conflicted merge is a success, not a failure: the index is left as Git leaves it, for the user to resolve. result is how a caller finds out.

backport

{ "ok": true, "result": "patched",
  "template": "../my-template",
  "revision": { "reference": "main", "commit": "937573e…", "dirty": false },
  "patch": "From 0000000…\nSubject: [PATCH] tpl: backport from my-service\n…",
  "output": null,
  "applyCommand": "git tpl backport | git -C ../my-template am",
  "files": [ { "rendered": "README.md", "source": "template/README.md.jinja",
               "insertions": 1, "deletions": 1, "added": false } ],
  "skipped": [], "unsubstituted": [], "insertions": 1, "deletions": 1 }

result is patched, nothingToBackport, or plan (with --list-hunks, below).

revision.reference is null when a commit was recorded but no reference was — a hand-edited commit on the ref, or an older trailer format — and backport declines to guess which reference it might have come from. revision.commit/revision.dirty are never null: when neither was recorded, they fall back to what the fresh render underneath the patch actually resolved.

patch carries the mailbox itself, rather than it going to stdout beside the payload: under --json, stdout is one JSON object, always. It is "" when there is nothing to backport. output is the --output path, or null when the patch went to stdout.

files[].source is the path in the template repository, render root and .jinja suffix included — the path the patch edits. files[].rendered is the path in the project. added marks a file the template did not previously produce.

skipped carries paths that were considered and deliberately not backported, each with a reason. For patch output, these are files deleted locally, which would remove them from every project rendering the template. For --list-hunks, binary added or modified files also appear there because they have no text hunks to list. Files the template never produced are not listed: they are out of scope rather than skipped.

unsubstituted names every line whose template expression was reversed — path, source, line, the rendered and project forms, the patched source line, and the expressions it kept. It is empty unless --unsubstitute was passed, since under --json there is nobody to confirm a reversal with. Worth branching on: a reversed substitution changes what the template produces for every project, and is the one part of a patch that should not be merged unread (ADR-022).

applyCommand is the git am invocation git-tpl declines to run (ADR-020), built from the configured source. When the template is a URL it contains the literal <your-template-clone>, because there is no local clone to name.

-p is refused under --json with tpl::backport::not_interactive: there is nobody to show hunks to, and a flag that silently sent everything instead would be the one answer that was not asked for. Choose hunks without a prompt with --list-hunks and --hunk instead, or limit the backport with pathspecs or --exclude.

With --list-hunks, result is plan, patch is "", files is empty, and the payload gains a plan array (ADR-037):

{ "ok": true, "result": "plan", "patch": "", "files": [],
  "plan": [ { "rendered": "README.md", "source": "template/README.md.jinja", "added": false,
              "hunks": [ { "id": "3f9a1c0be2d4", "spec": "README.md:3f9a1c0be2d4",
                           "header": "@@ -1,4 +1,5 @@", "insertions": 2, "deletions": 0,
                           "lines": [ "+# Acme", "+", " # Notes", " " ] } ] } ] }

spec is exactly what --hunk takes. id is derived from the hunk's content and the file's path, so it is stable while the file is unchanged and stops matching when it changes. lines is the hunk body, each line prefixed with a space, - or +. Eligible leaf-owned text files are listed before substitution and round-trip proof checks; a binary file appears in skipped instead. Symlink changes and inherited or composed content can fail before listing. Exclude unsupported paths and retry, or edit their owning template directly.

A refusal is a failure, with a tpl::backport::* code. Branch on the code: substituted_region is routine and means "edit the template by hand", while stale_rendering means "run update first".

fetch

{ "ok": true, "remote": "origin", "ref": "refs/tpl/rust",
  "state": "behind",
  "localPresent": true, "remotePresent": true,
  "relation": { "ahead": 0, "behind": 2, "synced": false, "diverged": false } }

state is one of absent, synced, diverged, behind or ahead. localPresent and remotePresent are booleans identifying the presence of the local ref and fetched remote-tracking copy. relation is null exactly when state is absent: one or both compared tips are missing. An available shared copy does not restore an absent local ref.

Fetching never moves the local ref, so behind is a report, not an action.

With --dry-run nothing is fetched and the payload says only what would be:

{ "ok": true, "dryRun": true, "remote": "origin",
  "refspec": "+refs/tpl/*:refs/remotes/origin/tpl/*" }

push

{ "ok": true, "remote": "origin", "ref": "refs/tpl/rust" }

With --dry-run nothing is pushed:

{ "ok": true, "dryRun": true, "remote": "origin", "ref": "refs/tpl/rust" }

fetch names a refspec and push a ref, because a fetch brings every template ref and a push moves the one this project has.

test

Documented with the command, at git tpl test. The payload carries summary and a cases array, each with its failures. Under --write, a case's snapshot: "updated" can mean only that its legacy MANIFEST was migrated or removed. Such a format-only update has an empty snapshotChanges array and counts toward summary.snapshotsWritten. An equal snapshot already using only manifest.toml reports unchanged and is not rewritten.

show, completion and man

No success envelope, with or without --json. Their stdout is already the payload — a rendered file's bytes, a shell script, troff — and wrapping it in JSON would only mean nothing could read, source or render it. Failures still carry the usual envelope.