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