git2db/lib.rs
1//! Git2DB - Git-native database operations using libgit2
2//!
3//! This library provides a high-level interface for using Git repositories
4//! as databases, with submodules as the primary storage mechanism for artifacts.
5//!
6//! Now enhanced with hyprstream-inspired patterns for better thread safety,
7//! UUID-based model management, and robust registry operations.
8
9pub mod auth;
10pub mod callback_config;
11pub mod clone_options;
12pub mod config;
13pub mod errors;
14pub mod transport;
15pub mod transport_registry;
16pub mod utils;
17
18// Enhanced modules with git-native patterns
19pub mod branch;
20pub mod clone_builder;
21pub mod manager;
22pub mod merge;
23pub mod pinned_disk;
24pub mod pinned_tree;
25pub mod references;
26pub mod registration_builder;
27pub mod registry;
28pub mod remote;
29pub mod repo_accessor;
30pub mod repository;
31pub mod repository_handle;
32pub mod stage;
33pub mod transaction;
34
35// Storage drivers (Docker's graphdriver pattern)
36pub mod storage;
37
38// Optional gittorrent integration
39#[cfg(feature = "gittorrent-transport")]
40pub mod gittorrent_integration;
41
42// Optional XET large file storage integration
43#[cfg(feature = "xet-storage")]
44pub mod xet_filter;
45
46// Public XET module with high-level API
47#[cfg(feature = "xet-storage")]
48pub mod xet {
49 //! XET large file storage integration
50 //!
51 //! Provides high-level XET storage operations for model files and large data.
52
53 pub use crate::xet_filter::{clear_last_error, initialize, is_initialized, last_error};
54 pub use git_xet_filter::config::XetConfig;
55 pub use git_xet_filter::storage::{StorageBackend, XetStorage};
56}
57
58// LFS pointer support with XET backend
59#[cfg(feature = "xet-storage")]
60pub mod lfs;
61
62#[cfg(test)]
63mod security_tests;
64
65// Re-export main types
66pub use config::{Git2DBConfig, GitSignature, WorktreeConfig};
67pub use errors::{Git2DBError, Git2DBResult, LfsErrorKind};
68
69// Re-export LFS types when xet-storage feature is enabled
70#[cfg(feature = "xet-storage")]
71pub use lfs::{is_lfs_pointer, LfsPointer, LfsSmudge, LfsStorage, ProcessingStats};
72
73// Re-export git2 types for cleaner API boundary
74// Consumers should use git2db::Oid and git2db::Repository instead of git2::Oid and git2::Repository
75// This maintains a clean abstraction layer while allowing low-level access when needed
76pub use git2::{Oid, Repository};
77
78// Re-export XetConfig only when xet-storage feature is enabled
79// This prevents API confusion - if you can import XetConfig, XET functionality is available
80#[cfg(feature = "xet-storage")]
81pub use config::XetConfig;
82
83// Enhanced exports with git-native API (v2)
84pub use branch::{Branch, BranchKind, BranchManager};
85pub use clone_builder::CloneBuilder;
86pub use manager::GitManager;
87pub use merge::{
88 Candidate, CandidateComposer, ConflictEntry, ConflictReport, ConflictSide, MergeTreesResult,
89};
90pub use references::{GitRef, IntoGitRef};
91pub use registration_builder::RegistrationBuilder;
92pub use registry::{Git2DB, RemoteConfig, RepoId, TrackedRepository};
93pub use remote::{Remote, RemoteManager};
94pub use repository_handle::{RepositoryHandle, RepositoryStatus};
95pub use stage::{StageManager, StagedFile};
96pub use transaction::{IsolationMode, TransactionHandle};
97pub use transport::TransportFactory;
98
99// Storage driver exports
100pub use storage::{Driver, DriverRegistry, StorageDriver};
101
102/// Version of git2db library
103pub const VERSION: &str = env!("CARGO_PKG_VERSION");
104
105/// Initialize global Git2DB with default config (hyprstream pattern)
106pub fn init() {
107 let _ = manager::GitManager::global();
108}
109
110/// Initialize global Git2DB with custom configuration
111///
112/// This must be called before any operations that use the global manager.
113/// Returns Ok(true) if initialization succeeded, Ok(false) if already initialized.
114///
115/// # Example
116///
117/// ```rust,no_run
118/// use git2db::{init_with_config, config::Git2DBConfig};
119///
120/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
121/// let config = Git2DBConfig::default();
122/// init_with_config(config)?;
123/// # Ok(())
124/// # }
125/// ```
126pub fn init_with_config(config: Git2DBConfig) -> Result<(), errors::Git2DBError> {
127 manager::GitManager::init_with_config(config)
128}
129
130/// Get the global GitManager instance
131pub fn manager() -> &'static GitManager {
132 GitManager::global()
133}
134
135/// Create a new registry at the specified path
136pub async fn create_registry<P: AsRef<std::path::Path>>(base_dir: P) -> Git2DBResult<Git2DB> {
137 Git2DB::open(base_dir).await
138}
139
140/// Quick operations using global manager
141pub mod ops {
142 use super::*;
143 use std::path::Path;
144
145 /// Clone a repository
146 ///
147 /// # Examples
148 ///
149 /// ```rust,ignore
150 /// // Simple clone with defaults
151 /// git2db::ops::clone("https://github.com/user/repo.git", "./repo", None).await?;
152 ///
153 /// // Clone with custom options
154 /// use git2db::clone_options::CloneOptions;
155 /// use git2db::callback_config::{CallbackConfigBuilder, ProgressConfig};
156 /// use git2db::auth::AuthStrategy;
157 ///
158 /// let options = CloneOptions::builder()
159 /// .callback_config(
160 /// CallbackConfigBuilder::new()
161 /// .auth(AuthStrategy::SshAgent { username: Some("git".to_owned()) })
162 /// .progress(ProgressConfig::Stdout)
163 /// .build()
164 /// )
165 /// .shallow(true)
166 /// .depth(1)
167 /// .build();
168 ///
169 /// git2db::ops::clone("https://github.com/user/repo.git", "./repo", Some(options)).await?;
170 /// ```
171 pub async fn clone(
172 url: &str,
173 target: &Path,
174 options: Option<clone_options::CloneOptions>,
175 ) -> Git2DBResult<git2::Repository> {
176 manager().clone_repository(url, target, options).await
177 }
178
179 /// Open a repository
180 pub fn open<P: AsRef<Path>>(path: P) -> Git2DBResult<git2::Repository> {
181 manager().get_repository(path)?.open()
182 }
183
184 /// Remove a worktree
185 pub fn remove_worktree(base_repo: &Path, worktree_name: &str) -> Git2DBResult<()> {
186 manager().remove_worktree(base_repo, worktree_name, None)
187 }
188}