gitlimes/lib.rs
1//! Reading git history without holding it in memory.
2//!
3//! This is the engine behind the `gitlimes` command line tool, exposed as a
4//! library so a TUI, a graphical front end or a script can reuse it instead of
5//! shelling out to the binary and parsing its output.
6//!
7//! # The one rule
8//!
9//! Nothing here scales with the length of the history. [`repo::Records`] streams
10//! `git log` output through a buffer that is reused for every record, and
11//! [`graph::lanes::Lanes`] holds one entry per *open branch lane* rather than
12//! one per commit. Memory is bounded by how many branches are simultaneously in
13//! flight - typically a handful - and by the number of authors or refs, never by
14//! the number of commits.
15//!
16//! Any addition that would break that is a deliberate decision, not an accident.
17//!
18//! # Layers
19//!
20//! - [`repo`] spawns git and streams records. It is the only module that knows
21//! git is a subprocess, so swapping in a different backend touches only it.
22//! - [`graph::lanes`] turns a stream of commits into branch-lane geometry. It
23//! emits an abstract [`graph::lanes::Step`] per commit and draws nothing.
24//! - [`graph::draw`] renders those steps as terminal rows. A second renderer -
25//! SVG, HTML, a canvas - plugs in here and reuses the layout unchanged.
26//! - [`json`] emits newline-delimited JSON, the machine-readable form of every
27//! command's output.
28//! - [`fmt`] and [`style`] are presentation helpers: column fitting, relative
29//! dates, sparklines, ANSI colour.
30//!
31//! # Example
32//!
33//! Walk the current repository's history without collecting it:
34//!
35//! ```no_run
36//! use gitlimes::repo::{self, Commit, Records, LOG_FORMAT};
37//!
38//! let mut records = Records::spawn_lines(repo::git(&["log", LOG_FORMAT, "--"]))?;
39//! while let Some(record) = records.next_record()? {
40//! if let Some(commit) = Commit::parse(&record) {
41//! println!("{} {}", commit.short, commit.subject);
42//! }
43//! }
44//! records.finish()?;
45//! # Ok::<(), std::io::Error>(())
46//! ```
47
48pub mod fmt;
49pub mod graph;
50pub mod json;
51pub mod pager;
52pub mod repo;
53pub mod style;