spl:pin

Introduction
Moving to the version you just published
Pinning an exact version
Pinning another product without selecting it
Moving a product to another line
Advanced
Reference
1. Arguments and options
2. Messages
Requirements
See also

Introduction

spl:pin records, by DOI, which model of its product line the active product derives from. Deriving the product then needs only its repository and UVLHub.

splent spl:pin sample_splent_spl

  my_first_app now pins sample_splent_spl
    doi          10.5281/zenodo.23076870
    concept doi  10.5281/zenodo.18873371
    version      v4
    recorded in  /workspace/my_first_app/pyproject.toml

The product’s pyproject.toml now holds the pin.

[tool.splent]
spl = "sample_splent_spl"

[tool.splent.spl_model]
mirror = "uvlhub.io"
doi = "10.5281/zenodo.23076870"
concept_doi = "10.5281/zenodo.18873371"
version = "v4"
file = "sample_splent_spl.uvl"

doi pins the exact model, as org/repo@version pins a feature. concept_doi names the line across versions, which spl:outdated needs to ask UVLHub for a newer one.

Moving to the version you just published

splent spl:pin my_spl

  my_product now pins my_spl
    was          2 (10.5281/zenodo.10000002)
    doi          10.5281/zenodo.10000003
    version      3

Without --doi, it adopts the model this workspace holds, the working copy or else the newest cache entry. After spl:publish, that is the DOI just minted. A product that pins nothing yet may also take the pin the CLI ships for sample_splent_spl. Another product’s pin is never adopted.

It only moves a product forward. A product pinning a newer model keeps it (Keeping it.). When the version labels do not show which is newer, it writes nothing and prints the --doi to pass.

Pinning an exact version

splent spl:pin my_spl --doi 10.5281/zenodo.10000002

--doi pins exactly that DOI, older ones included, to reproduce an older build. The version and file come only from a source that records the same DOI. Set the rest with --concept-doi, --version and --mirror.

Pinning another product without selecting it

SPLENT_APP=my_other_product splent spl:pin my_spl

SPLENT_APP=<product> names it for one command and keeps your selection.

Moving a product to another line

splent spl:pin web_spl --switch --doi 10.5281/zenodo.10000009

A pin of another line is refused unless you pass --switch, which also moves [tool.splent].spl.

Advanced

The [tool.splent.spl_model] block is replaced, comments above it included, or appended at the end of the file. A product that names no line gets spl = "<name>" too. The text is checked before an atomic write, so a failure changes nothing. file is the model’s name on UVLHub, not always <name>.uvl.

Reference

Arguments and options

Argument / Option	Description
`<spl_name>`	The line. Optional when the product names one under `[tool.splent].spl`
`--doi`	The version DOI to pin, the one that gets downloaded
`--concept-doi`	The line’s DOI, stable across versions. Used to report drift
`--version`	A version label, for people reading the file
`--mirror`	The mirror. Defaults to `uvlhub.io`
`--switch`	Move the product to another line, updating `[tool.splent].spl`

Messages

Message	What to do
`'<product>' does not name an SPL.`	Pass the line’s name
`'<product>' declares the SPL '<a>', not '<b>'.`	Pass `--switch` with the new line’s `--doi`
`Nothing shows the workspace model is newer`	Name the DOI with `--doi`
`Nothing records a DOI for '<name>'.`	A warning. The pin is written, but a clone of the product cannot download the model until you publish it

Requirements

An active product (SPLENT_APP). The command writes into its pyproject.toml.