cargo_hold/lib.rs
1//! # cargo-hold
2//!
3//! A CI tool that ensures Cargo's incremental compilation is reliable by
4//! managing timestamps using content-based change detection.
5//!
6//! ## Overview
7//!
8//! cargo-hold solves the fundamental problem of using Cargo's incremental
9//! compilation in CI environments where timestamps are unreliable. It uses
10//! BLAKE3 content hashing to detect actual file changes and intelligently
11//! manages timestamps to maximize build cache efficiency.
12//!
13//! ## Key Features
14//!
15//! - **Content-based change detection**: Uses BLAKE3 hashing instead of
16//! timestamps
17//! - **Monotonic timestamp generation**: Ensures Cargo's assumptions about file
18//! ordering
19//! - **Git-aware**: Only tracks version-controlled files, respecting .gitignore
20//! - **Zero-copy deserialization**: Fast metadata loading with rkyv
21//! - **Parallel processing**: Leverages rayon for efficient file scanning
22//! - **Garbage collection**: Intelligent cleanup of old build artifacts
23//!
24//! ## Architecture
25//!
26//! The crate is organized into several modules:
27//!
28//! - [`cli`]: Command-line interface definitions using clap
29//! - [`commands`]: Implementation of all cargo-hold subcommands
30//! - [`error`]: Error types and handling with thiserror + miette
31//! - [`gc`]: Garbage collection for build artifacts and cargo cache
32//!
33//! Internal modules (not part of the public API):
34//! - `state`: Core build state management with content tracking
35//! - `metadata`: Persistence layer for build state
36//! - `discovery`: Git integration for file discovery
37//! - `timestamp`: Monotonic timestamp generation
38//! - `hashing`: BLAKE3-based file hashing utilities
39//!
40//! ## Usage in CI
41//!
42//! The primary CI integration point is the `anchor` command:
43//!
44//! ```bash
45//! # In your CI pipeline, before building:
46//! cargo hold anchor
47//! cargo build --release
48//! ```
49//!
50//! For complete CI workflow with garbage collection:
51//!
52//! ```bash
53//! # Combines anchor + heave commands
54//! cargo hold voyage --max-target-size 5G
55//! cargo build --release
56//! ```
57//!
58//! ## Library Usage
59//!
60//! While cargo-hold is primarily a CLI tool, it exposes its core functionality
61//! as a library for integration into other tools:
62//!
63//! ```no_run
64//! use cargo_hold::cli::{Cli, Commands};
65//! use cargo_hold::commands;
66//!
67//! // Create CLI instance programmatically using the builder
68//! let cli = Cli::builder()
69//! .target_dir("target")
70//! .verbose(1)
71//! .command(Commands::Anchor)
72//! .build()?;
73//!
74//! // Execute the command
75//! commands::execute(&cli)?;
76//! # Ok::<(), Box<dyn std::error::Error>>(())
77//! ```
78//!
79//! ## Performance
80//!
81//! cargo-hold is designed for speed:
82//! - Memory-mapped I/O for file hashing
83//! - Parallel file processing with rayon
84//! - Zero-copy metadata deserialization
85//! - BLAKE3 for fast cryptographic hashing
86//!
87//! ## Error Handling
88//!
89//! The crate uses a combination of:
90//! - `thiserror` for strongly-typed errors
91//! - `miette` for rich diagnostic output in CLI
92//!
93//! All public functions return `Result` types with descriptive error variants.
94
95// Re-export public modules for library usage
96pub mod cli;
97pub mod commands;
98pub mod error;
99pub mod gc;
100
101// Internal modules
102mod discovery;
103mod hashing;
104mod logging;
105mod metadata;
106mod state;
107mod timestamp;