gix_pack/
lib.rs

1//! Git stores all of its data as _Objects_, which are data along with a hash over all data. Storing objects efficiently
2//! is what git packs are concerned about.
3//!
4//! Packs consist of [data files][data::File] and [index files][index::File]. The latter can be generated from a data file
5//! and make accessing objects within a pack feasible.
6//!
7//! A [Bundle] conveniently combines a data pack alongside its index to allow [finding][Find] objects or verifying the pack.
8//! Objects returned by `.find(…)` are [objects][gix_object::Data] which know their pack location in order to speed up
9//! various common operations like creating new packs from existing ones.
10//!
11//! When traversing all objects in a pack, a _delta tree acceleration structure_ can be built from pack data or an index
12//! in order to decompress packs in parallel and without any waste.
13//! ## Feature Flags
14#![cfg_attr(
15    all(doc, feature = "document-features"),
16    doc = ::document_features::document_features!()
17)]
18#![cfg_attr(all(doc, feature = "document-features"), feature(doc_cfg))]
19#![deny(missing_docs, unsafe_code)]
20
21use std::{borrow::Cow, ops::Deref, path::Path};
22
23/// The default memory-backed storage for pack data and index files.
24pub use memmap2::Mmap as MMap;
25
26/// A byte-oriented backing store for pack data and indices.
27pub trait FileData: Deref<Target = [u8]> {}
28
29impl<T> FileData for T where T: Deref<Target = [u8]> {}
30
31///
32pub mod bundle;
33/// A bundle of pack data and the corresponding pack index
34pub struct Bundle {
35    /// The pack file corresponding to `index`
36    pub pack: data::File,
37    /// The index file corresponding to `pack`
38    pub index: index::File,
39}
40
41///
42pub mod find;
43
44///
45pub mod cache;
46///
47pub mod data;
48
49mod find_traits;
50pub use find_traits::{Find, FindExt};
51
52///
53pub mod index;
54///
55pub mod multi_index;
56
57///
58pub mod verify;
59
60///
61#[cfg(feature = "testing")]
62pub mod testing;
63
64mod mmap {
65    use std::path::Path;
66
67    pub fn read_only(path: &Path) -> std::io::Result<memmap2::Mmap> {
68        let file = std::fs::File::open(path)?;
69        // SAFETY: we have to take the risk of somebody changing the file underneath. Git never writes into the same file.
70        #[expect(unsafe_code)]
71        unsafe {
72            memmap2::MmapOptions::new().map_copy_read_only(&file)
73        }
74    }
75}
76
77/// Return a display-friendly name for pack- or index-related progress messages.
78///
79/// Prefer the file name, but fall back to the full path for paths without a terminal component.
80fn source_name(path: &Path) -> Cow<'_, str> {
81    if path.as_os_str().is_empty() {
82        Cow::Borrowed("<memory>")
83    } else if let Some(name) = path.file_name() {
84        name.to_string_lossy()
85    } else {
86        path.as_os_str().to_string_lossy()
87    }
88}
89
90#[inline]
91fn read_u32(b: &[u8]) -> u32 {
92    u32::from_be_bytes(b.try_into().unwrap())
93}
94
95#[inline]
96fn read_u64(b: &[u8]) -> u64 {
97    u64::from_be_bytes(b.try_into().unwrap())
98}
99
100fn exact_vec<T>(capacity: usize) -> Vec<T> {
101    let mut v = Vec::new();
102    v.reserve_exact(capacity);
103    v
104}
105
106#[inline]
107fn fan_is_monotonically_increasing(fan: &[u32]) -> bool {
108    !fan.windows(2).any(|window| window[0] > window[1])
109}
gix_pack/lib.rs

gix_pack/
lib.rs
