Reproduce¶
reprotrail reproduce creates a fresh workspace from a v1 product provenance
sidecar. It validates the product checksum, restores the recorded project_repo
Git checkout, copies provenance artifacts, restores the Pixi lockfile, and
rewrites recorded editable dependency paths into repos/<name> when
editable-local provenance is present. Legacy records without project_repo fall
back to the first software_repos entry as the project checkout.
For each recorded Git repository, the commit hash selects the source state; the recorded branch is not required to exist on the remote. Reprotrail clones without checking out a remote branch and fetches the exact commit when the clone does not already contain it. When a branch name was recorded, reproduction creates that branch locally at the recorded commit without an upstream. Records without a usable branch name are checked out with a detached HEAD.
Reproduction invokes the external pixi executable and may contact recorded
Git remotes and package channels. Preparing a workspace does not execute the
recorded command unless --execute is supplied. Inspect the restored sources,
input mappings, warnings, and REPRODUCTION.md before executing provenance from
an untrusted source.
An exact hash identifies a commit but does not archive it. Reproduction cannot
restore a commit after the repository source has garbage-collected it or refuses
to serve it. Legacy or incomplete records without a commit fall back to their
recorded branch, or to the source’s default branch, and add a warning to the
reproduction report. This warning causes --strict reproduction to fail.
reprotrail reproduce arguments¶
reprotrail reproduce \
--provenance results/product/product.prov.json \
--workspace /tmp/product-reproduction \
--env dev
Use --execute to run the recorded command through Pixi after setup. Use
--repo-source NAME=PATH_OR_URL when a recorded repository has no cloneable
remote URL.
Syntax |
Status |
Behavior |
|---|---|---|
|
Required |
Reads the product provenance record at |
|
Required |
Creates the reproduction workspace at |
|
Optional |
Runs the recorded command after restoring the workspace and installing the locked Pixi environment. Without it, reprotrail prepares and validates the workspace but does not run the command. |
|
Optional |
Treats every reproduction warning as a failure. |
|
Optional |
Uses Pixi environment |
|
Optional |
Selects recorded repository |
|
Optional; repeatable |
Uses local path or URL |
|
Optional; repeatable |
Replaces exact recorded input path |
|
Optional |
Reuses an existing workspace and continues restoration instead of rejecting it. |
|
Optional |
Removes an existing workspace and recreates it from scratch. This takes precedence over resuming it. |
|
Optional |
Prints the reproduction report as JSON instead of a human-readable summary. |
|
Optional |
Rebuilds missing ancestors in dependency order; plans without installing or executing unless |
|
Optional |
Reads a transferred export directory or manifest and implies recursive mode. |
|
Optional |
Explicitly accepts reported metadata gaps for recursive replay; missing executable prerequisites still block. |
|
Optional; repeatable |
Resolves repository-relative inputs for recorded repository NAME in original provenance or relocated external inputs. |
Recursive reproduction¶
Use --recursive to regenerate missing ancestors before the target. Add
--bundle to use a transferred export; specifying it implies recursive mode.
The target can be any provenance record in the export, including an intermediate
whose data were excluded. The manifest supplies the paths, so both the current
products/ layout and older exports with datasets under metadata/ are supported.
Continuing the fictional survey example from
the export guide, reproduce a cleaned intermediate dataset:
reprotrail reproduce \
--bundle ./survey-export \
--provenance ./survey-export/metadata/survey-data/results/north/cleaned/cleaned.prov.json \
--workspace ./replay \
--input-root survey-data=/archive/survey-data
Without --execute, recursive reproduction writes a dependency plan and
validation report without installing environments or running producers. Add
--execute after inspecting it. Original input datasets and nonarchived code
sources/packages must remain accessible, possibly through --input-map and
--repo-source. --input-root resolves repository-relative inputs in an original
provenance tree and relocates external input repositories when replaying an export.
An exact --input-map takes precedence over a repository root mapping.
Available ancestors are reused when their recorded provenance and available identity evidence match. Reused ancestors prune their own dependencies from the execution plan. File SHA-256 is stronger evidence than size/mtime or directory stat manifests; the report explicitly identifies the evidence used. Checks cannot recover content checksums absent from historical records.
Missing dependencies are produced sequentially, once each, using each step’s
recorded code and environment. All outputs go into the reproduction workspace,
with separate producer checkouts and auxiliary output locations. Path tokens
are relocated using the manifest and explicit input mappings. Directory-based
inputs passed through --data-root use workspace overlays of links to the mapped
inputs. Recognized output flags are --output, --qc, --done,
--validation-json, and --provenance-json. Other command-line conventions
require explicit mappings for absolute paths or paths outside the restored checkout.
Arbitrary commands must obey these mappings: reprotrail is not an operating
system sandbox for untrusted producer code.
Regenerated records receive new hashes. Replay preserves archived originals,
substitutes the new hashes for downstream validation, and records the old-to-new
mapping in reproduction.json. Successful execution does not prove numerical
or byte equivalence to the historical product. Missing/mismatched metadata
blocks affected producers unless --accept-incomplete is supplied. This flag
records acceptance; missing inputs, lockfiles, or executable prerequisites still
block reproduction. --strict continues treating warnings as failures.
--resume checks replay signatures, observed inputs, output state, and generated
provenance before reusing completed steps. Changed inputs/options invalidate
reuse. A required producer failure stops downstream execution and leaves a
report. --force recreates only the specified workspace, refusing to remove an
enclosing source-data/export directory.