spmx
Concepts

The global store

One content-addressable store of checkouts, artifacts and prebuilts, cloned into every worktree.

One global store cloned into many worktreesThe global store at ~/.spmx/store holds checkouts, artifacts and prebuilts once. The clonefile system call clones them into the SourcePackages folder of each Git worktree, sharing disk blocks until a file is modified.~/.spmx/storecheckouts/<identity>-<revision>artifacts/<identity>/<target>prebuilts/<toolchain>/<package>clonefile()worktree-a SourcePackages/checkouts · artifacts · prebuiltsworktree-b SourcePackages/checkouts · artifacts · prebuiltsworktree-c SourcePackages/checkouts · artifacts · prebuilts
Diagram: the global store is cloned into every worktree with APFS copy-on-write.

The store lives at ~/.spmx/store. Override the location with SPMX_STORE_DIR. It must be on the same APFS volume as your worktrees for zero-copy clones; see APFS clonefile for what happens otherwise.

Layout

KindPathKeyed by
Source checkoutscheckouts/<identity>-<revision>/package identity and Git revision
Binary artifactsartifacts/<identity>/<target>-<checksum>/package, target and checksum
Macro prebuiltsprebuilts/<toolchain-hash>/<package>-<version-or-checksum>/Swift and Xcode version, then package
Indexindex.jsonlinked projects, toolchain fingerprint, last access

Prebuilts are partitioned by a hash of swift --version and xcodebuild -version. After an Xcode update the old prebuilts are simply not selected, so a stale module ABI is never served.

Hydrate and harvest

  • spmx hydrate reads Package.resolved, and for every pin already in the store clones it into the worktree's SourcePackages (or .build). It rewrites workspace-state.json so paths point at the current worktree.
  • spmx harvest goes the other way: after a build it copies any new, complete package into the store and records the project in index.json.

The shims run both for you. A modified checkout is never overwritten unless you pass --force.

Concurrency

Every write to the store takes a per-package flock and goes through atomic staging, so several worktrees, or several AI agents, can hydrate and harvest at the same time.

Inspecting and cleaning

spmx store path      # print the store location
spmx store status    # packages, sizes, registered projects, estimated copy-on-write savings
spmx store prune     # drop entries no registered worktree references
Maintained by LuisRibeirooLast updated Edit this page on GitHub