Enum Commands 

pub enum Commands {
    Anchor,
    Salvage,
    Stow,
    Bilge,
    Heave {
        gc: GcArgs,
        dry_run: bool,
        debug: bool,
        age_threshold_days: u32,
        auto_max_target_size: bool,
    },
    Voyage {
        gc: GcArgs,
        gc_min_interval_hours: Option<u64>,
        force_gc: bool,
        gc_dry_run: bool,
        gc_debug: bool,
        gc_age_threshold_days: u32,
        gc_auto_max_target_size: bool,
    },
}

Available cargo-hold subcommands.

Each variant represents a different operation that cargo-hold can perform, from managing timestamps and metadata to cleaning up build artifacts.

Variants

Anchor

Anchor your build state (recommended CI command)

This is the main command that performs the complete workflow:

1. Restores timestamps from the metadata file based on content changes
2. Scans all Git-tracked files for modifications
3. Updates and saves the metadata with the current state

Use this command in CI before running cargo build to ensure incremental compilation works correctly with cached artifacts.

Salvage

Salvage file timestamps from the metadata

Restores timestamps based on the previous build state:

• Unchanged files: Restored to their original timestamps
• Modified files: Given a new monotonic timestamp
• New files: Given a new monotonic timestamp

This prevents unnecessary rebuilds while ensuring changed files are properly recompiled.

Stow

Stow files in the cargo hold

Scans all Git-tracked files and saves their current state:

• Computes BLAKE3 hashes for content-based change detection
• Records file sizes and modification times
• Saves metadata to enable future timestamp restoration

Run this after a successful build to update the metadata.

Bilge

Bilge out the metadata file

Removes the metadata file, forcing a fresh start on the next run. Use this when:

• You want to reset the timestamp tracking state
• The metadata file has become corrupted
• You’re troubleshooting incremental compilation issues

Heave

Heave ho! Clean up old build artifacts

Performs garbage collection on build artifacts to reclaim disk space:

• First ensures target directory is under size limit (if specified)
• Then removes artifacts older than the age threshold (default: 7 days)
• Both conditions are always applied together for consistent cleanup
• Always preserves: Binaries, important Cargo files, and recent artifacts
• Also cleans: ~/.cargo/registry/cache and ~/.cargo/git/checkouts

Artifacts are removed by crate (all related files together) to maintain build consistency.

Fields

gc: GcArgs

dry_run: bool

Show what would be deleted without actually deleting

debug: bool

Enable debug output for garbage collection

age_threshold_days: u32

Age threshold in days for removing artifacts (default: 7)

auto_max_target_size: bool

Enable auto max-target-size suggestions derived from prior runs.

Voyage

Full voyage - anchor and heave in one command

Combines the anchor and heave commands for a complete CI workflow:

1. First runs anchor to restore timestamps and update metadata
2. Then runs heave to clean up old artifacts and manage disk usage

This is ideal for CI pipelines that need both timestamp management and disk space control in a single command.

Fields

gc: GcArgs

gc_min_interval_hours: Option<u64>

Minimum hours between GC runs; anchor always runs (default: no cooldown)

force_gc: bool

Run GC even within the cooldown (still respects –gc-dry-run)

gc_dry_run: bool

Show what would be deleted without actually deleting

gc_debug: bool

Enable debug output for garbage collection

gc_age_threshold_days: u32

Age threshold in days for garbage collection (default: 7)

gc_auto_max_target_size: bool

Enable auto max-target-size suggestions derived from prior runs.

Trait Implementations

impl Debug for Commands

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromArgMatches for Commands

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut<'b>( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Subcommand for Commands

fn augment_subcommands<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_subcommands_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

fn has_subcommand(__clap_name: &str) -> bool

Test whether Self can parse a specific subcommand