History

remaining docs for git-commitgraph crate

Sebastian Thiel committed 5 years ago

Commit 91461761 parent a81ea673 files · +22 −1Browse files

Showing the changes to git-commitgraph/src (3 of 3 files). Show all

Unified · Split

3 files
  1. git-commitgraph/src/graph/mod.rs +2 −0
  2. git-commitgraph/src/graph/verify.rs +9 −0
  3. git-commitgraph/src/lib.rs +11 −1
git-commitgraph/src/graph/mod.rs+2−0
@@ -1,6 +1,7 @@
1//! Operations on a complete commit graph.1//! Operations on a complete commit graph.
2mod access;2mod access;
3mod init;3mod init;
4///
4pub mod verify;5pub mod verify;
5 6
6use crate::file::File;7use crate::file::File;
@@ -15,6 +16,7 @@ pub struct Graph { · 8 unmodified lines
15 files: Vec<File>,16 files: Vec<File>,
16}17}
17 18
19/// A generalized position for use in [`Graph`].
18#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Hash)]20#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Hash)]
19pub struct Position(pub u32);21pub struct Position(pub u32);
20 22
git-commitgraph/src/graph/verify.rs+9−0
@@ -50,15 +50,24 @@ pub enum Error<E: std::error::Error + 'static> { · 49 unmodified lines
50 TooManyFiles(usize),50 TooManyFiles(usize),
51}51}
52 52
53/// Statistics gathered while verifying the integrity of the graph as returned by [`Graph::verify_integrity()]`.
53#[derive(Clone, Debug, Eq, PartialEq)]54#[derive(Clone, Debug, Eq, PartialEq)]
54#[cfg_attr(feature = "serde1", derive(serde::Deserialize, serde::Serialize))]55#[cfg_attr(feature = "serde1", derive(serde::Deserialize, serde::Serialize))]
55pub struct Outcome {56pub struct Outcome {
57 /// The longest consecutive amount of commits in a chain of commits.
58 ///
59 /// For example, a repository with 10 commits would have 10 as value.
56 pub longest_path_length: Option<u32>,60 pub longest_path_length: Option<u32>,
61 /// The total amount traversed commits.
57 pub num_commits: u32,62 pub num_commits: u32,
63 /// A mapping of `parent-count -> amount of [commits][file::Commit] with that count`.
58 pub parent_counts: BTreeMap<u32, u32>,64 pub parent_counts: BTreeMap<u32, u32>,
59}65}
60 66
61impl Graph {67impl Graph {
68 /// Traverse all commits in the graph and call `processor(&commit) -> Result<(), E>` on it while verifying checksums.
69 ///
70 /// When `processor` returns an error, the entire verification is stopped and the error returned.
62 pub fn verify_integrity<E>(71 pub fn verify_integrity<E>(
63 &self,72 &self,
64 mut processor: impl FnMut(&file::Commit<'_>) -> Result<(), E>,73 mut processor: impl FnMut(&file::Commit<'_>) -> Result<(), E>,
git-commitgraph/src/lib.rs+11−1
@@ -1,12 +1,22 @@
1//! Read, verify, and traverse git commit graphs.
2//!
3//! A [commit graph][Graph] acts as a cache is a set of [graph files][file::File] each storing
4//! various commits in a way that accelerates lookups considerably compared to traversing the git history by usual means.
5//!
6//! A [`Graph`] is generated as each [`File`][file::File] only contains a subset of all commits in the git commit
7//! history to avoid having to recreate the entire cache each time the cache should be updated, thus avoiding to traverse
8//! the git history that is already present in the [`Graph`].
1#![forbid(unsafe_code)]9#![forbid(unsafe_code)]
2#![deny(rust_2018_idioms)]10#![deny(rust_2018_idioms, missing_docs)]
3 11
4pub mod file;12pub mod file;
5pub mod graph;13pub mod graph;
6 14
7pub use graph::Graph;15pub use graph::Graph;
8 16
17/// The number of generations that are considered 'infinite' commit history.
9pub const GENERATION_NUMBER_INFINITY: u32 = 0xffff_ffff;18pub const GENERATION_NUMBER_INFINITY: u32 = 0xffff_ffff;
19/// The biggest possible amount of commits in the history of a repository.
10pub const GENERATION_NUMBER_MAX: u32 = 0x3fff_ffff;20pub const GENERATION_NUMBER_MAX: u32 = 0x3fff_ffff;
11 21
12/// The maximum number of commits that can be stored in a commit graph.22/// The maximum number of commits that can be stored in a commit graph.