gix_commitgraph/
lib.rs

1//! Read, verify, and traverse git commit graphs.
2//!
3//! A [commit graph][Graph] is an index of commits in the git commit history.
4//! The [Graph] stores commit data in a way that accelerates lookups considerably compared to
5//! traversing the git history by usual means.
6//!
7//! As generating the full commit graph from scratch can take some time, git may write new commits
8//! to separate [files][File] instead of overwriting the original file.
9//! Eventually, git will merge these files together as the number of files grows.
10//! ## Feature Flags
11#![cfg_attr(
12    all(doc, feature = "document-features"),
13    doc = ::document_features::document_features!()
14)]
15#![cfg_attr(all(doc, feature = "document-features"), feature(doc_cfg))]
16#![deny(missing_docs, rust_2018_idioms, unsafe_code)]
17
18use gix_error::{Exn, Message};
19use std::path::Path;
20
21/// A single commit-graph file.
22///
23/// All operations on a `File` are local to that graph file. Since a commit graph can span multiple
24/// files, all interesting graph operations belong on [`Graph`].
25pub struct File {
26    base_graph_count: u8,
27    base_graphs_list_offset: Option<usize>,
28    commit_data_offset: usize,
29    data: memmap2::Mmap,
30    extra_edges_list_range: Option<std::ops::Range<usize>>,
31    fan: [u32; file::FAN_LEN],
32    oid_lookup_offset: usize,
33    path: std::path::PathBuf,
34    hash_len: usize,
35    object_hash: gix_hash::Kind,
36}
37
38/// A complete commit graph.
39///
40/// The data in the commit graph may come from a monolithic `objects/info/commit-graph` file, or it
41/// may come from one or more `objects/info/commit-graphs/graph-*.graph` files. These files are
42/// generated via `git commit-graph write ...` commands.
43pub struct Graph {
44    files: Vec<File>,
45}
46
47/// Instantiate a commit graph from an `.git/objects/info` directory, or one of the various commit-graph files.
48pub fn at(path: impl AsRef<Path>) -> Result<Graph, Exn<Message>> {
49    Graph::at(path.as_ref())
50}
51
52mod access;
53pub mod file;
54///
55pub mod init;
56pub mod verify;
57
58/// The number of generations that are considered 'infinite' commit history.
59pub const GENERATION_NUMBER_INFINITY: u32 = 0xffff_ffff;
60/// The largest valid generation number.
61///
62/// If a commit's real generation number is larger than this, the commit graph will cap the value to
63/// this number.
64/// The largest distinct generation number is `GENERATION_NUMBER_MAX - 1`.
65pub const GENERATION_NUMBER_MAX: u32 = 0x3fff_ffff;
66
67/// The maximum number of commits that can be stored in a commit graph.
68pub const MAX_COMMITS: u32 = (1 << 30) + (1 << 29) + (1 << 28) - 1;
69
70/// A generalized position for use in [`Graph`].
71#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Hash)]
72pub struct Position(pub u32);
73
74impl std::fmt::Display for Position {
75    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
76        self.0.fmt(f)
77    }
78}
gix_commitgraph/lib.rs

gix_commitgraph/
lib.rs
