zhold-core 0.0.2

Deterministic domain model and retention policy for zhold
Documentation

zhold manages Cargo intermediate files for repositories that use multiple Git worktrees. Each worktree keeps isolated, reusable build storage. zhold removes inactive storage to stay near one configured budget.

zhold is a public alpha. Rust 1.91.1 or newer is required.

Problem

Sharing Cargo build intermediates across worktrees causes build-directory lock contention. Keeping them separate avoids that contention, but disk use grows with every worktree.

zhold keeps the build directories separate and manages their lifecycle under one budget.

Related Cargo issues: #16804 and #5026.

Install

cargo install zhold --locked

Start

zhold setup 200GiB
zhold cargo test
zhold
zhold gc --dry-run

Use zhold cargo ... in place of cargo ... for managed builds. Running zhold shows the current store status.

Pass a one-time budget to collection when needed:

zhold gc 100GiB --dry-run

Model

  • Cargo intermediates go into a zhold-owned build directory.
  • Builds with the same worktree, workspace, toolchain, compiler, and Cargo configuration reuse the same directory.
  • zhold reserves space and may remove inactive directories before and after a build.
  • Active, pinned, suspect, and uncertain directories are not removed.
  • Final artifacts remain in the workspace target/ directory and are outside the zhold budget.

Budget

The budget is a steady-state limit, not a hard quota. A running build can exceed its reservation. A minimum free-space floor can stop a new managed build before it starts:

zhold setup 200GiB --min-free 25GiB --build-reserve 2GiB

Safety

zhold removes only complete build directories that it created and can validate. It checks ownership, metadata, leases, pins, and worktree state before removal. Unknown state stops collection.

See the safety and threat model for the exact guarantees.

Development

cargo install --path crates/zhold-cli --locked
./scripts/check
./scripts/smoke
./scripts/package-smoke

See design, locking, and platform support for implementation details.

License

Apache-2.0. See LICENSE.