git tpl push¶
Publish template refs to a remote.
Pushes refs/tpl/<id> explicitly:
Why this is a separate command¶
Rendered refs are not pushed by default; tpl.autoPush or git tpl update --push opts in.
git push does not push them, and nothing git-tpl does changes what git push sends.
The two modes this gives you are both first-class:
flowchart LR
accTitle: Local-only rendered ref, the default
subgraph project[Local project]
main("refs/heads/main")
template("refs/tpl/foo: stays local")
end
main -->|git push| remote("Remote refs/heads/main")
Contributors can work on the project without the local ref.
Before running updates in a fresh clone, a collaborator must
restore the original rendered ref from full merged history.
Re-rendering from .config/git.tpl.toml can reproduce its tree, but cannot recover the original ancestry.
flowchart LR
accTitle: Explicitly shared rendered ref
subgraph project[Local project]
main("refs/heads/main")
template("refs/tpl/foo")
end
main -->|git push| remote_main("Remote refs/heads/main")
template -->|Explicit git tpl push| remote_template("Remote refs/tpl/foo")
Useful when several people run updates, when CI does, or when you want the rendering history visible to the team.
Never forced¶
$ git tpl push
To github.com:acme/my-project
* [new ref] refs/tpl/github-com-noirbizarre-rust-library-template -> refs/tpl/github-com-noirbizarre-rust-library-template
Divergence¶
$ git tpl push
Cannot push refs/tpl/github-com-noirbizarre-rust-library-template: the remote copy has diverged.
local 4f2c1a9 (2 commits not on the remote)
remote 9a8b7c6 (1 commit not local)
Preserve both histories. No automatic reconciliation operation is available.
There is no --force.
A rendered ref is history that others may have merged from, and overwriting it destroys the merge base their
branch depends on — which turns their next update into a whole-file conflict.
Genuinely divergent rendered refs currently have no automatic reconciliation operation.
Merging a remote-tracking rendering into your project branch changes that branch, not the local rendered ref
that git tpl push publishes; it cannot repair the rejected push.
Preserve both histories for inspection. Do not force, reset, or fabricate a rendered-ref merge commit.
Equal rendered trees do not imply shared commit ancestry.
An absent local ref or one strictly behind the remote is different: see absent restoration and conditional fast-forward adoption.
Options¶
A server hook or policy can reject a ref even after its objects have transferred successfully.
This fails with tpl::git::push_rejected, including the ref and server reason.
Resolve the rejection and retry git tpl push; the same rejection also fails an automatic push after update.
| Option | Meaning |
|---|---|
--remote <name> |
Default origin, or tpl.remote. |
--dry-run |
Report what would be pushed. |
Pushing automatically after an update¶
Or per-invocation, git tpl update --push.
These push only when update creates a rendered commit.
Use git tpl push to publish an existing rendering or retry a failed push after an already-current update.
Machine-readable output¶
git tpl --json push emits its outcome on stdout as a single JSON object, with the prose on stderr.
The payload is described in JSON output.