opschain templates version upsert

templates

opschain templates version upsert <project>/<code> --version <v> [--git-rev <rev>] [--description <text>] [--fetch] [--float] [--ignore-in-use]

One write verb for a template version's content: it creates the named version when it does not exist (pinned to --git-rev, which a first create requires), and updates it when it does. At least one of --git-rev, --description, --float or --fetch must be passed — an empty upsert is refused.

What each input does on an existing version:

• --git-rev repins the version to a different branch, tag or commit of the template's Git remote.
• --description re-describes it (an empty value clears it — the flag is sent whenever given).
• --fetch re-resolves the stored revision against the remote, so a floating branch picks up new commits without repinning.
• --float marks the version as following its revision on every fetch (--float=false unmarks it; the flag is sent only when given). Not allowed while the version is locked.

Lifecycle guards: a locked or archived version only accepts its own unlock/unarchive, so upserting one is refused. Changing or fetching the revision of a version that assets are pinned to is refused; --ignore-in-use overrides that refusal and rolls the pinned assets onto the newly resolved commit.

Flags

Flag	Meaning
--version <v>	The version string, e.g. 1.2.0 (required).
--git-rev <rev>	The branch, tag or commit to pin (required on first create).
--description <text>	The version's description.
--fetch	Re-resolve the stored revision against the Git remote.
--float	Follow the revision: every fetch repins to its current commit.
--ignore-in-use	Override the in-use refusal: repin even while assets use this version, rolling them onto the new commit.

Exit codes

Code	Meaning
0	Upserted — prints upserted version <v> of <project>/<code> (<state>, git rev <rev>).
1	The template was not found, or the server refused (locked/archived version, in-use revision change, unresolvable revision).
2	Usage error — empty upsert, missing required flag, malformed address, no server target.

Named errors

• nothing to upsert — pass --git-rev, --description, --float and/or --fetch — exit 2.
• required flag(s) "version" not set — exit 2.
• expected <project>/<template-code>, got "<arg>" — exit 2.
• template "<code>" not found in project "<project>" — exit 1.

Examples

Create a version pinned to a tag:

opschain templates version upsert demo/web_stack --version 1.1.0 --git-rev v1.1.0
upserted version 1.1.0 of demo/web_stack (available, git rev v1.1.0 (8c04e7b))

A floating development version that tracks a branch:

opschain templates version upsert demo/web_stack --version edge --git-rev main --float

Pick up the branch's new commits, rolling the assets pinned to it:

opschain templates version upsert demo/web_stack --version edge --fetch --ignore-in-use

See also

• opschain docs cli/templates-version-lock — freeze a version once it is proven.
• opschain docs cli/templates-assign — move assets between versions.
• opschain learn 3.3 — the guided tour.