Struct Materializer 

pub struct Materializer { /* private fields */ }

Materializes git stubs into actual file content.

Reads .gitstub files, fetches the referenced content from Git history, and writes the content to an output directory.

Implementations

impl Materializer

pub fn standard( repo_root: impl Into<Utf8PathBuf>, output_dir: impl Into<Utf8PathBuf>, ) -> Result<Self, MaterializeError>

Creates a new materializer for general use.

repo_root must be the repository root, and it is treated as relative to the current working directory. (It is also allowed to be absolute.)

output_dir is an output directory relative to the current working directory. (It is also allowed to be absolute.)

Returns an error if no VCS (.git or .jj) is detected at repo_root, or if the repository is a shallow clone.

pub fn for_build_script( repo_root: impl Into<Utf8PathBuf>, ) -> Result<Self, MaterializeError>

Creates a new materializer for use in Cargo build scripts.

This constructor reads OUT_DIR from the environment for the output directory, and writes files to the git-stub-vcs directory within OUT_DIR. It also emits cargo::rerun-if-changed directives for each materialized file.

repo_root is relative to CARGO_MANIFEST_DIR (the directory containing the crate’s Cargo.toml), and is typically a relative path.

Panics

Panics if the OUT_DIR or CARGO_MANIFEST_DIR environment variables are not set. Both these environment variables are expected to be set in a Cargo build script context.

pub fn with_vcs(self, vcs: Vcs) -> Result<Self, MaterializeError>

Overrides the detected VCS.

Use this when you want to force a specific VCS instead of relying on automatic detection.

Returns an error if shallow-clone checking fails, or if the repository is shallow under the new VCS.

pub fn vcs(&self) -> &Vcs

Returns the VCS that will be used for materialization.

pub fn materialize( &self, git_stub_path: impl AsRef<Utf8Path>, ) -> Result<Utf8PathBuf, MaterializeError>

Materializes a git stub.

Reads the file at git_stub_path (relative to the repository root), fetches the referenced content from history, and writes it to the output directory.

Returns the path to the materialized file.

Examples

// In build.rs:
let materializer = git_stub_vcs::Materializer::for_build_script("../..")
    .expect("VCS detected at repo root");
let spec_path = materializer
    .materialize("openapi/my-api/my-api-1.0.0-abc123.json.gitstub")
    .expect("materialized successfully");

pub fn materialize_to( &self, git_stub_path: impl AsRef<Utf8Path>, output_path: impl AsRef<Utf8Path>, ) -> Result<(), MaterializeError>

Materializes a git stub to a specific path.

Like materialize, but writes to output_path (relative to the output directory, or absolute) instead of deriving the path from the Git stub file name.

git_stub_path is relative to the repository root.

Trait Implementations

impl Clone for Materializer

fn clone(&self) -> Materializer

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Materializer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.