git_stub_vcs/
lib.rs

1// Copyright 2026 Oxide Computer Company
2
3// This line is automatically updated by cargo-release.
4#![doc(html_root_url = "https://docs.rs/git-stub-vcs/0.1.0")]
5
6//! VCS abstraction and materialization for git stubs.
7//!
8//! A [`GitStub`](git_stub::GitStub) (e.g., `foo.json.gitstub`) contains a
9//! reference to a file stored in Git history, in the format `commit:path`. This
10//! crate provides a VCS abstraction for reading file contents from history, and
11//! helpers to materialize these references into actual files.
12//!
13//! # Usage in build scripts
14//!
15//! ```no_run
16//! // build.rs
17//! use git_stub_vcs::Materializer;
18//!
19//! fn main() {
20//!     // repo_root is relative to CARGO_MANIFEST_DIR (the directory containing
21//!     // this crate's Cargo.toml). Typically "." or some number of "..".
22//!     let repo_root = "../..";
23//!     let materializer = Materializer::for_build_script(repo_root)
24//!         .expect("VCS detected at repo root");
25//!
26//!     // git_stub_path is relative to repo_root.
27//!     let spec_path = materializer
28//!         .materialize("openapi/my-api/my-api-1.0.0-abc123.json.gitstub")
29//!         .expect("materialized successfully");
30//!
31//!     // spec_path is a path in OUT_DIR with the materialized content.
32//!     // The materializer also emits cargo::rerun-if-changed for the git stub.
33//! }
34//! ```
35//!
36//! # Usage outside build scripts
37//!
38//! ```no_run
39//! use git_stub_vcs::Materializer;
40//!
41//! // repo_root is relative to the current working directory.
42//! let materializer = Materializer::standard("../..", "/tmp/output")
43//!     .expect("VCS detected at repo root");
44//!
45//! // git_stub_path is relative to repo_root.
46//! let spec_path = materializer
47//!     .materialize("openapi/my-api/my-api-1.0.0-abc123.json.gitstub")
48//!     .expect("materialized successfully");
49//! ```
50
51#![deny(missing_docs)]
52
53mod errors;
54mod materialize;
55mod vcs;
56
57pub use errors::{
58    AtomicWriteError, MaterializeError, ReadContentsError, ShallowCloneError,
59    VcsDetectError, VcsEnvError,
60};
61pub use materialize::Materializer;
62pub use vcs::{Vcs, VcsName};
git_stub_vcs/lib.rs

git_stub_vcs/
lib.rs
