History

[commitgraph] Tweak and expand documentation.

* Use "number of" phrasing instead of "amount of." * Describe the graph as an index instead of a cache. * Add module-level documentation for `file::commit`, `file::verify`, and `graph::verify`.

Conor Davis committed 5 years ago

Commit ac528671 parent 5569c8f8 files · +27 −20Browse files

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

Unified · Split

8 files
  1. git-commitgraph/src/file/access.rs +1 −1
  2. git-commitgraph/src/file/commit.rs +1 −0
  3. git-commitgraph/src/file/mod.rs +0 −2
  4. git-commitgraph/src/file/verify.rs +5 −4
  5. git-commitgraph/src/graph/access.rs +1 −1
  6. git-commitgraph/src/graph/mod.rs +0 −1
  7. git-commitgraph/src/graph/verify.rs +8 −5
  8. git-commitgraph/src/lib.rs +11 −6
git-commitgraph/src/file/access.rs+1−1
@@ -9,7 +9,7 @@ use std::{ · 8 unmodified lines
9 9
10/// Access10/// Access
11impl File {11impl File {
12 /// The amount of base graphs that this file depends on.12 /// The number of base graphs that this file depends on.
13 pub fn base_graph_count(&self) -> u8 {13 pub fn base_graph_count(&self) -> u8 {
14 self.base_graph_count14 self.base_graph_count
15 }15 }
git-commitgraph/src/file/commit.rs+1−0
@@ -1,3 +1,4 @@
1//! Low-level operations on individual commits.
1use crate::{2use crate::{
2 file::{self, File},3 file::{self, File},
3 graph,4 graph,
git-commitgraph/src/file/mod.rs+0−2
@@ -2,12 +2,10 @@ · 1 unmodified line
2 2
3mod access;3mod access;
4 4
5///
6pub mod commit;5pub mod commit;
7pub use commit::Commit;6pub use commit::Commit;
8 7
9mod init;8mod init;
10///
11pub mod verify;9pub mod verify;
12 10
13pub use init::Error;11pub use init::Error;
git-commitgraph/src/file/verify.rs+5−4
@@ -1,3 +1,4 @@
1//! Auxiliary types used in commit graph file verification methods.
1use crate::{2use crate::{
2 file::{self, File},3 file::{self, File},
3 GENERATION_NUMBER_INFINITY, GENERATION_NUMBER_MAX,4 GENERATION_NUMBER_INFINITY, GENERATION_NUMBER_MAX,
@@ -42,15 +43,15 @@ pub enum Error<E: std::error::Error + 'static> { · 38 unmodified lines
42#[derive(Clone, Debug, Eq, PartialEq)]43#[derive(Clone, Debug, Eq, PartialEq)]
43#[cfg_attr(feature = "serde1", derive(serde::Deserialize, serde::Serialize))]44#[cfg_attr(feature = "serde1", derive(serde::Deserialize, serde::Serialize))]
44pub struct Outcome {45pub struct Outcome {
45 /// The highest encountered [`file::Commit`] generation number.46 /// The largest encountered [`file::Commit`] generation number.
46 pub max_generation: u32,47 pub max_generation: u32,
47 /// The smallest encountered [`file::Commit`] generation number.48 /// The smallest encountered [`file::Commit`] generation number.
48 pub min_generation: u32,49 pub min_generation: u32,
49 /// The highest amount parents in a single [`file::Commit`].50 /// The largest number of parents in a single [`file::Commit`].
50 pub max_parents: u32,51 pub max_parents: u32,
51 /// The total amount of [`commits`][file::Commit] seen in the iteration.52 /// The total number of [`commits`][file::Commit]s seen in the iteration.
52 pub num_commits: u32,53 pub num_commits: u32,
53 /// A mapping of `parent-count -> amount of [commits][file::Commit] with that count`.54 /// A mapping of `N -> number of commits with N parents`.
54 pub parent_counts: HashMap<u32, u32>,55 pub parent_counts: HashMap<u32, u32>,
55}56}
56 57
git-commitgraph/src/graph/access.rs+1−1
@@ -45,7 +45,7 @@ impl Graph { · 44 unmodified lines
45 Some(self.lookup_by_id(id)?.graph_pos)45 Some(self.lookup_by_id(id)?.graph_pos)
46 }46 }
47 47
48 /// Returns the amount of commits stored in this file.48 /// Returns the number of commits stored in this file.
49 pub fn num_commits(&self) -> u32 {49 pub fn num_commits(&self) -> u32 {
50 self.files.iter().map(|f| f.num_commits()).sum()50 self.files.iter().map(|f| f.num_commits()).sum()
51 }51 }
git-commitgraph/src/graph/mod.rs+0−1
@@ -1,7 +1,6 @@
1//! Operations on a complete commit graph.1//! Operations on a complete commit graph.
2mod access;2mod access;
3mod init;3mod init;
4///
5pub mod verify;4pub mod verify;
6 5
7use crate::file::File;6use crate::file::File;
git-commitgraph/src/graph/verify.rs+8−5
@@ -1,3 +1,4 @@
1//! Auxiliary types used by graph verification methods.
1use crate::{2use crate::{
2 file::{self, commit},3 file::{self, commit},
3 graph, Graph, GENERATION_NUMBER_MAX,4 graph, Graph, GENERATION_NUMBER_MAX,
@@ -50,17 +51,19 @@ pub enum Error<E: std::error::Error + 'static> { · 46 unmodified lines
50 TooManyFiles(usize),51 TooManyFiles(usize),
51}52}
52 53
53/// Statistics gathered while verifying the integrity of the graph as returned by [`Graph::verify_integrity()]`.54/// Statistics gathered while verifying the integrity of the graph as returned by [`Graph::verify_integrity()`].
54#[derive(Clone, Debug, Eq, PartialEq)]55#[derive(Clone, Debug, Eq, PartialEq)]
55#[cfg_attr(feature = "serde1", derive(serde::Deserialize, serde::Serialize))]56#[cfg_attr(feature = "serde1", derive(serde::Deserialize, serde::Serialize))]
56pub struct Outcome {57pub struct Outcome {
57 /// The longest consecutive amount of commits in a chain of commits.58 /// The length of the longest path between any two commits in this graph.
58 ///59 ///
59 /// For example, a repository with 10 commits would have 10 as value.60 /// For example, this will be `Some(9)` for a commit graph containing 10 linear commits.
61 /// This will be `Some(0)` for a commit graph containing 0 or 1 commits.
62 /// If the longest path length is too large to fit in a [u32], then this will be [None].
60 pub longest_path_length: Option<u32>,63 pub longest_path_length: Option<u32>,
61 /// The total amount traversed commits.64 /// The total number of commits traversed.
62 pub num_commits: u32,65 pub num_commits: u32,
63 /// A mapping of `parent-count -> amount of [commits][file::Commit] with that count`.66 /// A mapping of `N -> number of commits with N parents`.
64 pub parent_counts: BTreeMap<u32, u32>,67 pub parent_counts: BTreeMap<u32, u32>,
65}68}
66 69
git-commitgraph/src/lib.rs+11−6
@@ -1,11 +1,12 @@
1//! Read, verify, and traverse git commit graphs.1//! Read, verify, and traverse git commit graphs.
2//!2//!
3//! A [commit graph][Graph] acts as a cache is a set of [graph files][file::File] each storing3//! A [commit graph][Graph] is an index of commits in the git commit history.
4//! various commits in a way that accelerates lookups considerably compared to traversing the git history by usual means.4//! The [Graph] stores commit data in a way that accelerates lookups considerably compared to
5//! traversing the git history by usual means.
5//!6//!
6//! A [`Graph`] is generated as each [`File`][file::File] only contains a subset of all commits in the git commit7//! As generating the full commit graph from scratch can take some time, git may write new commits
7//! history to avoid having to recreate the entire cache each time the cache should be updated, thus avoiding to traverse8//! to separate [files][file::File] instead of overwriting the original file.
8//! the git history that is already present in the [`Graph`].9//! Eventually, git will merge these files together as the number of files grows.
9#![forbid(unsafe_code)]10#![forbid(unsafe_code)]
10#![deny(rust_2018_idioms, missing_docs)]11#![deny(rust_2018_idioms, missing_docs)]
11 12
@@ -16,7 +17,11 @@ pub use graph::Graph; · 4 unmodified lines
16 17
17/// The number of generations that are considered 'infinite' commit history.18/// The number of generations that are considered 'infinite' commit history.
18pub const GENERATION_NUMBER_INFINITY: u32 = 0xffff_ffff;19pub const GENERATION_NUMBER_INFINITY: u32 = 0xffff_ffff;
19/// The biggest possible amount of commits in the history of a repository.20/// The largest valid generation number.
21///
22/// If a commit's real generation number is larger than this, the commit graph will cap the value to
23/// this number.
24/// The largest distinct generation number is `GENERATION_NUMBER_MAX - 1`.
20pub const GENERATION_NUMBER_MAX: u32 = 0x3fff_ffff;25pub const GENERATION_NUMBER_MAX: u32 = 0x3fff_ffff;
21 26
22/// The maximum number of commits that can be stored in a commit graph.27/// The maximum number of commits that can be stored in a commit graph.