git-stub 1.0.0

Parsing types for git stubs (commit:path references)
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
60
61
62
63
64
65
66
67
68
69
70
71
72
73

// Copyright 2026 Oxide Computer Company

// This line is automatically updated by cargo-release.
#![doc(html_root_url = "https://docs.rs/git-stub/1.0.0")]

//! Parsing types for Git stubs.
//!
//! A *Git stub* (e.g., `foo.json.gitstub`) contains a reference to a file
//! stored in Git history, in the format `commit:path`. This allows storing a
//! pointer to a file's contents without duplicating the actual data in the
//! working tree.
//!
//! Git stubs are useful in case you have several different versions of a file
//! that must be stored side by side, but the files aren't large enough to be
//! stored through a mechanism like [Git LFS](https://git-lfs.com/). Git stubs
//! are similar to [LFS pointer
//! files](https://github.com/git-lfs/git-lfs/blob/main/docs/spec.md#the-pointer),
//! with the difference being that the canonical versions are stored in old
//! versions of Git history rather than on an external server.
//!
//! For more about the motivation and design decisions behind Git stubs, see
//! [RFD 634 Git stub files for Dropshot versioned
//! APIs](https://rfd.shared.oxide.computer/rfd/0634).
//!
//! The main entry point is [`GitStub`].
//!
//! # Examples
//!
//! ```
//! use git_stub::{GitCommitHash, GitStub};
//!
//! // A Git stub contains a single line in the format "commit:path\n".
//! let file_contents =
//!     "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2:openapi/api-v1.json\n";
//! let stub: GitStub = file_contents.parse().unwrap();
//!
//! // Inspect the parsed commit hash and path.
//! assert!(matches!(stub.commit(), GitCommitHash::Sha1(_)));
//! assert_eq!(stub.path().as_str(), "openapi/api-v1.json");
//!
//! // Canonical input: needs_rewrite is false.
//! assert!(!stub.needs_rewrite());
//!
//! // Round-trip back to canonical file contents.
//! assert_eq!(stub.to_file_contents(), file_contents);
//!
//! // Parsing from non-canonical input (e.g., missing trailing newline)
//! // sets needs_rewrite to true.
//! let stub2: GitStub =
//!     "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2:openapi/api-v1.json"
//!         .parse()
//!         .unwrap();
//! assert!(stub2.needs_rewrite());
//!
//! // To retrieve the actual file from Git history, use
//! // `git_stub_vcs::Vcs` to read the contents.
//! ```
//!
//! # Related crates
//!
//! For materializing files from version control systems like Git or Jujutsu,
//! see [`git-stub-vcs`](https://crates.io/crates/git-stub-vcs) ([source
//! tree](https://github.com/oxidecomputer/git-stub/tree/main/crates/git-stub-vcs)).

#![deny(missing_docs)]

mod errors;
mod git_stub;
mod hash;

pub use errors::{CommitHashParseError, GitStubParseError};
pub use git_stub::GitStub;
pub use hash::GitCommitHash;