git-stub-vcs 0.1.0

VCS abstraction and materialization for git stubs
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

<!-- cargo-sync-rdme title [[ -->
# git-stub-vcs
<!-- cargo-sync-rdme ]] -->
<!-- cargo-sync-rdme badge [[ -->
![License: MIT OR Apache-2.0](https://img.shields.io/crates/l/git-stub-vcs.svg?)
[![crates.io](https://img.shields.io/crates/v/git-stub-vcs.svg?logo=rust)](https://crates.io/crates/git-stub-vcs)
[![docs.rs](https://img.shields.io/docsrs/git-stub-vcs.svg?logo=docs.rs)](https://docs.rs/git-stub-vcs)
[![Rust: ^1.85.0](https://img.shields.io/badge/rust-^1.85.0-93450a.svg?logo=rust)](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field)
<!-- cargo-sync-rdme ]] -->
<!-- cargo-sync-rdme rustdoc [[ -->
VCS abstraction and materialization for git stubs.

A [`GitStub`](https://docs.rs/git-stub/1.0.0/git_stub/git_stub/struct.GitStub.html) (e.g., `foo.json.gitstub`) contains a
reference to a file stored in Git history, in the format `commit:path`. This
crate provides a VCS abstraction for reading file contents from history, and
helpers to materialize these references into actual files.

## Usage in build scripts

````rust,no_run
// build.rs
use git_stub_vcs::Materializer;

fn main() {
    // repo_root is relative to CARGO_MANIFEST_DIR (the directory containing
    // this crate's Cargo.toml). Typically "." or some number of "..".
    let repo_root = "../..";
    let materializer = Materializer::for_build_script(repo_root)
        .expect("VCS detected at repo root");

    // git_stub_path is relative to repo_root.
    let spec_path = materializer
        .materialize("openapi/my-api/my-api-1.0.0-abc123.json.gitstub")
        .expect("materialized successfully");

    // spec_path is a path in OUT_DIR with the materialized content.
    // The materializer also emits cargo::rerun-if-changed for the git stub.
}
````

## Usage outside build scripts

````rust,no_run
use git_stub_vcs::Materializer;

// repo_root is relative to the current working directory.
let materializer = Materializer::standard("../..", "/tmp/output")
    .expect("VCS detected at repo root");

// git_stub_path is relative to repo_root.
let spec_path = materializer
    .materialize("openapi/my-api/my-api-1.0.0-abc123.json.gitstub")
    .expect("materialized successfully");
````
<!-- cargo-sync-rdme ]] -->

## License

This project is available under the terms of either the [Apache 2.0 license](LICENSE-APACHE) or the [MIT license](LICENSE-MIT).