Skip to content

git tpl push

Publish template refs to a remote.

git tpl push [--remote <name>] [--dry-run]

Pushes refs/tpl/<id> explicitly:

refs/tpl/<id>:refs/tpl/<id>

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

git config tpl.autoPush true

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.