crates/gunnar-bitmap/src/lib.rs
//! Git's EWAH bitmap format and the `.bitmap` reachability index.
//!
//! gitoxide has no bitmap support: `gix-pack`, `gix-odb` and `gix-features`
//! contain no `ewah` and no bitmap reader (checked 2026-08-04). A gix-based
//! server therefore walks the commit graph everywhere real git reads a bitmap
//! and answers with two set operations. This crate is the missing half.
//!
//! ```no_run
//! use gunnar_bitmap::{Index, Reachability};
//!
//! # fn main() -> Result<(), gunnar_bitmap::Error> {
//! # let (want_pos, have_pos) = (0u32, 1u32);
//! let index = Index::at("objects/pack/pack-abc.bitmap", gix_hash::Kind::Sha1)?;
//! index.verify_checksum()?;
//!
//! // A fetch, as set arithmetic: one OR, one AND-NOT, no graph walk and no
//! // object read. `want_pos` and `have_pos` are `.idx` positions of commits.
//! let selection = Reachability::new(&index).objects_to_send([want_pos], [have_pos]);
//! assert!(selection.is_complete());
//! println!("{} objects to send", selection.objects.count_ones());
//! # Ok(())
//! # }
//! ```
//!
//! # Scope
//!
//! Plumbing. The crate reads and writes the file and does set arithmetic over
//! pack positions. It never opens a pack, never resolves an object id and never
//! walks a graph — mapping positions to object ids is the caller's `.idx`, and
//! completing a query whose `want` has no stored bitmap needs the caller's
//! object database. See [`reachability`] for why that boundary is where it is.
//!
//! # The one thing to get right before using a position
//!
//! Bitmap positions are **pack positions** — rank by offset in the `.pack` — and
//! not `.idx` positions, even though the format documentation says "position in
//! the index". Confusing the two returns a set of the right size made of the
//! wrong objects. [`PackOrder`] converts, and [`pack_order`] documents the
//! measurement that settled it.
//!
//! # Donation shape (D21)
//!
//! Standalone from the first line: no gunnar dependency, no gunnar type, gix
//! conventions throughout, liftable with `cp -r`.
//! `tests/donation_shape.rs` asserts it and proves each check red first.
//!
//! # What it was verified against
//!
//! Not against itself. A decoder that only round-trips its own encoder proves
//! nothing, so the tests point at the 52 `.bitmap` files stock git had already
//! written on this machine and at git's own `rev-list --test-bitmap`. See
//! `tests/stock_git.rs` and `tests/damage.rs` — both read real `.bitmap` files
//! from disk. (Until 2026-08-27 this pointed at a third file, real_bitmaps.rs,
//! which exists in neither this crate nor any checkout beside it — the pointer
//! named nothing. Written without its directory here on purpose: the citation
//! audit is right to flag a dead path, including one inside its own correction.)
#![deny(missing_docs, rust_2018_idioms)]
mod bitmap;
mod error;
pub mod ewah;
pub mod file;
pub mod kind;
pub mod pack_order;
pub mod reachability;
pub mod words;
mod write;
pub use bitmap::Bitmap;
pub use error::Error;
pub use ewah::{Builder, Chunk, Ewah};
pub use file::{Entry, Index, Triplet};
pub use kind::Kind;
pub use pack_order::PackOrder;
pub use reachability::{Reachability, Selection};
pub use write::{Writer, XorPolicy};