pin

Freeze a build’s caches into direct reads (pin).

Each materialized cache becomes a direct read of its cache file, so the pinned build executes by reading artifacts instead of re-deriving them. Combine with –relocate-reads to produce a self-contained, portable build.

Usage

xorq pin BUILD_PATH [OPTIONS]

Arguments

• BUILD_PATH—Path to the build directory produced by xorq build.

Options

Option	Default	Description
--builds-dir	builds	Directory for the resulting build artifact.
--cache-dir	$XORQ_CACHE_DIR or ~/.cache/xorq	Directory for parquet cache files.
-e, --ensure-materialized	off	Materialize any unpopulated caches (by executing) before pinning.
--relocate-reads / --no-relocate-reads	--relocate-reads	Bundle local-file Read nodes (including frozen caches) into the build so it is self-contained and runnable from anywhere. Remote reads (s3://, gs://, …) are already location-independent and left in place. Pass –no-relocate-reads for a lean, machine-local build; this only affects reads not already bundled – relocation discards a read’s original path, so it cannot be undone by a later –no-relocate-reads on an already-relocated input.

Examples

# Pin a build whose caches are already materialized
xorq pin builds/f02d28198715 --cache-dir ./cache
# Materialize any missing caches, then pin into a portable bundle
xorq pin builds/f02d28198715 --cache-dir ./cache -e --relocate-reads