git_remote_object_store/
lib.rs

1//! `git-remote-object-store` — a Rust library and CLI for storing Git
2//! repositories in cloud object stores (AWS S3 and Azure Blob Storage).
3//!
4//! # Library usage
5//!
6//! This crate provides the [`Remote`] struct as the primary entry point for
7//! library consumers. It wraps an [`ObjectStore`] backend together with the
8//! repository-level key prefix, so you can read and write objects in the
9//! project's on-bucket format without tracking these separately:
10//!
11//! ```no_run
12//! # #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> {
13//! use git_remote_object_store::Remote;
14//!
15//! let remote = Remote::connect("s3+https://my-bucket.s3.us-east-1.amazonaws.com/my-repo").await?;
16//! let head = remote.get_head().await?;
17//! println!("{}", String::from_utf8_lossy(&head));
18//! # Ok(())
19//! # }
20//! ```
21//!
22//! See [`remote`] for the full key layout and API documentation.
23//!
24//! ## Direct file access (packchain remotes only)
25//!
26//! [`read_blob`] returns the bytes of a single file at a ref's tip
27//! without cloning the repo. The companion [`PackIndexCache`]
28//! amortises pack-index parses across calls — long-running consumers
29//! (CI agents, build systems) keep one cache for the lifetime of the
30//! process.
31//!
32//! ```no_run
33//! # #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> {
34//! use git_remote_object_store::{PackIndexCache, Remote, read_blob};
35//!
36//! let remote = Remote::connect("s3+https://bucket/repo?engine=packchain").await?;
37//! let cache = PackIndexCache::default();
38//! let bytes = read_blob(&remote, "refs/heads/main", "src/main.rs", &cache).await?;
39//! println!("{}", String::from_utf8_lossy(&bytes));
40//! # Ok(())
41//! # }
42//! ```
43//!
44//! # CLI
45//!
46//! The binaries (`git-remote-s3-https`, `git-remote-az-https`, etc.) are
47//! packaged in the companion `git-remote-object-store-cli` crate under
48//! `cli/`. Build and install with `cargo install --path cli`.
49//!
50//! # Architecture
51//!
52//! This crate ships two backends behind one shared [`ObjectStore`]
53//! trait — AWS S3 (and S3-compatible endpoints) and Azure Blob
54//! Storage. The on-bucket key layout, locking semantics, helper-
55//! protocol behaviour, and management-CLI shape are this project's
56//! own decisions; the only external contracts are the git
57//! helper-protocol, the LFS protocol, and the cloud-provider HTTP
58//! APIs.
59
60// Public docs intentionally cross-reference pub(crate) items as
61// cues for crate-internal readers; rendering broken in public rustdoc
62// is acceptable.
63#![allow(rustdoc::private_intra_doc_links)]
64
65pub(crate) mod bundle;
66pub mod git;
67pub(crate) mod keys;
68pub mod lfs;
69pub mod manage;
70pub mod object_store;
71pub mod packchain;
72pub mod protocol;
73pub mod remote;
74pub mod url;
75
76/// Shared test helpers (git CLI shellouts, in-process REPL driver,
77/// seed-repo factory) consumed by both `tests/` integration tests and
78/// the cli crate's `cli/tests/` integration tests. Gated on
79/// `#[cfg(any(test, feature = "test-util"))]` so production builds
80/// never see it; the cli crate enables the feature on its path
81/// dependency.
82#[cfg(any(test, feature = "test-util"))]
83pub mod test_util;
84
85// Re-export the most commonly used types at the crate root so consumers
86// do not need three-level import paths.
87#[doc(no_inline)]
88pub use object_store::{
89    BoxError, GetOpts, ObjectMeta, ObjectStore, ObjectStoreError, ProgressSink, PutOpts,
90};
91/// Re-export of the packchain engine's public API: the error enum
92/// surfaced through [`protocol::push::PushError::Packchain`] /
93/// [`protocol::fetch::FetchError::Packchain`], plus the Phase 4
94/// direct-file-access entry points [`packchain::read_blob`] and
95/// [`packchain::PackIndexCache`].
96#[doc(no_inline)]
97pub use packchain::{PackIndexCache, PackchainError, read_blob};
98#[doc(no_inline)]
99pub use protocol::backend::{BackendError, BackendKind};
100#[doc(no_inline)]
101pub use remote::{Remote, RemoteError};
102#[doc(no_inline)]
103pub use url::{RemoteUrl, StorageEngine};
git_remote_object_store/lib.rs

git_remote_object_store/
lib.rs
