reprotrail

Trace a data product back to the command, code, inputs, and environment that made it.

reprotrail is a Python command-line tool and library for recording the practical evidence behind data-processing runs. Wrap an existing command and it writes a readable, machine-checkable trail: what ran, which Git revision and inputs it used, available Pixi environment state, and which files belong to the resulting product.

command + inputs + Git + pixi.lock
                  │
           reprotrail run
                  │
                  ▼
       result + log + provenance
             + product metadata

Reprotrail is workflow-agnostic: use it from a shell, Snakemake, another workflow system, or Python. It records reproducibility evidence around your domain logic instead of replacing it.

See it in one command

From a clean Git project, wrap a product-producing command:

reprotrail run \
  --log results/output.log \
  --provenance-json results/output.prov.json \
  --product-output results/output.zarr \
  --input data/source.nc \
  -- python -m my_project.step --output results/output.zarr

The workflow still creates results/output.zarr. Reprotrail adds:

• output.log — combined standard output and error from the command;
• output.prov.json — versioned command, input, software, runtime, and status metadata;
• output.prov.json.sha256 — an integrity checksum for the provenance record;
• README.md and ro-crate-metadata.json — a human summary and structured product relationships; and
• LICENSE.md — only when the product has an explicit configured license.

If the command fails, the provenance record still explains what was attempted and how it ended.

Install

Reprotrail requires Python 3.11 or newer and Git. The recommended installation includes product metadata support:

python -m pip install "reprotrail[products]"

For command and provenance capture without RO-Crate, SPDX, xarray, and Zarr support, install the minimal package:

python -m pip install reprotrail

Pixi is an external executable, not a Python dependency. Basic provenance capture works without it; runtime snapshots, dependency epochs, Git dependency freshness checks, and the complete reproduction workflow expect a Pixi project and lockfile.

After the conda-forge recipe is accepted, the full Pixi-first installation will be available with:

conda install -c conda-forge reprotrail

What reprotrail helps answer

• What made this file? Inspect the recorded command, timestamps, inputs, Git commits, and runtime packages.
• Did the software change between runs? Use dependency epochs to reject or explicitly accept a new runtime snapshot.
• Can someone understand this product without the original workflow? Ship a README, checksum, attribution, license evidence, and RO-Crate metadata beside it.
• Can I rebuild it later? Prepare a fresh workspace from the recorded repositories and Pixi lockfile, validate the evidence, then choose whether to execute the command.

Deliberate limits

Reprotrail records and checks evidence; it does not make a non-deterministic program deterministic, archive remote repositories or input data, or guess a license for a generated product. Reproduction still depends on recorded commits, package sources, and inputs remaining accessible.

Review provenance before publishing it. Records can contain command arguments, repository URLs, input paths, dirty-file information, and explicitly whitelisted environment values. Portable “public” helpers remove selected local roots; they are not secret scanners or anonymizers.

Documentation

• Start with the practical workflow
• Learn the concepts and terminology
• Browse the command-line interface
• Configure a project
• Read the Python API reference

Reprotrail is currently alpha software. Module-level Python APIs may change during the 0.x series; the CLI and explicitly versioned provenance schemas are the clearer compatibility contracts. See the changelog before upgrading.

Contributions are welcome; start with the contributor guide.