Skip to main content

git2db/storage/
mod.rs

1//! Storage drivers following Docker's graphdriver pattern
2//!
3//! This module implements a driver-based abstraction for worktree storage optimization,
4//! following the proven pattern from Docker's container filesystem layer management.
5//! Just as Docker uses "graphdrivers" to abstract storage backends (overlay2, btrfs, zfs),
6//! we use "storage drivers" to abstract worktree optimization mechanisms.
7//!
8//! # Design Philosophy (from Docker)
9//!
10//! 1. **"Driver"** is the term - not "mechanism", "strategy", or "backend"
11//! 2. Drivers are named after the **actual technology** they use
12//! 3. Simple string-based selection in configuration
13//! 4. `vfs` is the universal fallback (plain directories)
14//!
15//! # Architecture
16//!
17//! Git worktrees are ALWAYS used as the base mechanism. Storage drivers are optional
18//! layers that sit UNDERNEATH git worktrees to provide benefits like:
19//!
20//! - **Copy-on-Write (CoW)**: ~80% disk space savings
21//! - **Isolation**: Changes are isolated to an upper layer
22//! - **Performance**: Faster creation and cleanup
23//!
24//! # Example
25//!
26//! ```toml
27//! # In configuration file (Docker-style)
28//! [worktree]
29//! driver = "overlay2"  # or "btrfs", "reflink", "vfs", etc.
30//! ```
31//!
32//! ```rust,no_run
33//! use git2db::storage::{StorageDriver, DriverRegistry};
34//!
35//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
36//! let registry = DriverRegistry::new();
37//!
38//! // Select a driver explicitly
39//! let driver = registry.get_driver(StorageDriver::Overlay2)?;
40//!
41//! // Or use vfs as a safe fallback
42//! let driver = registry.get_driver(StorageDriver::Vfs)?;
43//! # Ok(())
44//! # }
45//! ```
46
47mod driver;
48mod overlay2;
49mod reflink;
50mod registry;
51mod vfs;
52
53pub use driver::{Driver, DriverError, DriverFactory, DriverOpts, StorageDriver, WorktreeHandle};
54pub use registry::DriverRegistry;