git tpl fetch¶
Retrieve template refs from a remote.
Fetches refs/tpl/* into refs/remotes/<remote>/tpl/*, using an explicit refspec:
Why this is a separate command¶
git fetch does not retrieve template refs, and git tpl fetch is how you ask for them.
That is deliberate. Someone who clones the project to fix a typo should not download template state to do it, and should not have to know what a template ref is. Template refs are opt-in for the people who work with templates.
The refspec is passed per-invocation rather than written into .git/config, so a plain git fetch stays
plain — including for contributors who never run git-tpl and never configured anything.
After fetching¶
$ git tpl fetch
From github.com:acme/my-project
* [new ref] refs/tpl/github-com-noirbizarre-rust-library-template -> origin/tpl/github-com-noirbizarre-rust-library-template
The remote copy is 2 commit(s) ahead of your local ref.
Review its provenance and ancestry before conditionally fast-forwarding the local rendered ref.
Fetching never moves your local refs/tpl/<id>.
It brings the remote copy into a remote-tracking ref and tells you how they relate.
What to do about it is your decision:
- The remote is ahead — someone else rendered a newer state. Review it before conditionally fast-forwarding your local rendered ref. Merging into your project branch alone does not advance the rendered ref used by update and push.
- The remote is behind — you have renderings they do not.
git tpl push. - Diverged — you both rendered independently. See
git tpl push.
Restoring an absent local ref¶
Fetching does not restore refs/tpl/<id>: it only retrieves a remote-tracking candidate.
Before the first update in a fresh clone, restore the original rendering so the next commit keeps its ancestry.
Use full project history (git fetch --unshallow for a shallow clone).
For a shared rendering, fetch and select its candidate:
git tpl fetch
ref=refs/tpl/<id>
candidate=$(git rev-parse 'refs/remotes/origin/tpl/<id>^{commit}')
git show --no-patch --format=full "$candidate"
git log --oneline "$candidate"
Review the Template-Source, Template-Commit and Answers-Digest trailers against your attachment.
Check which rendering is already merged with git merge-base --is-ancestor "$candidate" HEAD;
a newer shared candidate may legitimately not yet be merged, so inspect its ancestry back to the applied rendering.
If the ref was local-only, find the original rendered commit in merged history instead:
git log HEAD --topo-order --format=full --grep='^Template-Source: <configured-source>$'
# Set candidate to the reviewed original rendered commit, not the project merge commit.
candidate=<original-rendered-commit>
git merge-base --is-ancestor "$candidate" HEAD
After reviewing the candidate, create the local ref only if it is still absent:
The empty expected old value rejects an existing ref, including one created concurrently. If it fails, inspect the existing ref before proceeding. Re-rendering an equal tree cannot recreate the original commit or merge ancestry. If you already created an orphan rendering, this absent-only procedure does not reconcile it; preserve both histories and see divergence.
Fast-forwarding an existing local ref¶
After reviewing the remote rendering's provenance and answers, capture both tips and require ancestry:
ref=refs/tpl/<id>
old=$(git rev-parse "$ref^{commit}")
candidate=$(git rev-parse 'refs/remotes/origin/tpl/<id>^{commit}')
git merge-base --is-ancestor "$old" "$candidate" &&
git update-ref "$ref" "$candidate" "$old"
The ancestry check permits only a fast-forward; the expected old tip rejects concurrent local movement.
If either command fails, stop and inspect both histories.
Use the absent-only procedure when no local ref exists.
For genuine divergence, preserve both histories: no automatic reconciliation is available.
After adoption, git tpl diff and git tpl merge preview and apply the rendering to your project branch.
Options¶
| Option | Meaning |
|---|---|
--remote <name> |
Default origin, or tpl.remote. |
--dry-run |
Report the refspec and remote; transfer nothing. |
Machine-readable output¶
state: "absent" means one or both compared refs are missing.
localPresent and remotePresent distinguish all presence combinations;
relation is null unless both the local ref and fetched remote-tracking copy exist.
When the local ref is missing but a shared copy was fetched, fetch reports that copy as available
and leaves the local ref absent.
The other states remain synced, ahead, behind and diverged.
git tpl --json fetch emits its outcome on stdout as a single JSON object, with the prose on stderr.
The payload is described in JSON output.