grit_lib/
lib.rs

1#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
2#![deny(missing_docs)]
3#![warn(rustdoc::unescaped_backticks)]
4
5//! grit-lib — fast, linkable Git engine for Rust.
6//!
7//! Grit reimplements Git's on-disk formats and wire protocols in idiomatic Rust
8//! so embedders can open repositories, walk history, diff, merge, fetch, and push
9//! without shelling out to the `git` binary. The [`grit`](https://github.com/gitbutlerapp/grit)
10//! CLI is a thin presentation layer over this crate; almost all behavior lives here.
11//!
12//! # Getting started
13//!
14//! [`Repository`](repo::Repository) is the primary entry point: discover or open a
15//! work tree, then use methods and focused modules for objects, refs, the index,
16//! config, remotes, and porcelain operations.
17//!
18//! ```
19//! use grit_lib::config::environment::RepositoryOptions;
20//! use grit_lib::repo::{InitOptions, Repository};
21//! use grit_lib::state::resolve_head;
22//!
23//! # fn main() -> grit_lib::error::Result<()> {
24//! let dir = tempfile::tempdir()?;
25//! let repo = Repository::init(dir.path(), &InitOptions::default())?;
26//! let head = resolve_head(repo.git_dir())?;
27//! assert!(matches!(head, grit_lib::state::HeadState::Branch { short_name, oid: None, .. } if short_name == "main"));
28//! let _ = Repository::open(
29//!     repo.git_dir(),
30//!     &RepositoryOptions::empty().with_work_tree(dir.path()),
31//! )?;
32//! # Ok(())
33//! # }
34//! ```
35//!
36//! - [`Repository`](repo::Repository) exposes typed handles for objects, refs, the
37//!   index, config, revision walking, and diffs ([`objects::Objects`],
38//!   [`refs::References`], [`index::IndexHandle`],
39//!   [`config::ConfigHandle`], [`revwalk::RevWalk`],
40//!   [`diff::Diff`]), plus [`repo_handles`] for remotes, worktrees, stash,
41//!   notes, reflogs, and bundles.
42//! - [`prelude`] re-exports the types most call sites need.
43//! - [`porcelain`] holds user-facing operations that return structured result
44//!   *models* (the CLI renders them).
45//! - Browse the engine by domain: [`objects`], [`refs`], [`index`], [`revwalk`],
46//!   [`diff`], [`config`], [`remote`], [`worktree`], [`stash`], [`notes`], and
47//!   [`bundle`]. Legacy flat paths (`grit_lib::odb`, `grit_lib::fetch`, …) are
48//!   private; [grit-scm.com/docs/library/api-layout](https://grit-scm.com/docs/library/api-layout)
49//!   maps each old path to its canonical replacement.
50//! - [`progress`] defines how long-running operations report progress and
51//!   observe cancellation without touching the terminal.
52//!
53//! # API layout (canonical domains)
54//!
55//! | Flat path | Canonical path |
56//! | --- | --- |
57//! | `odb`, `pack`, `midx`, `hash`, `pack_bitmap`, `bitmap_walk`, … | [`objects`] |
58//! | `reflog`, `refspec`, `reftable`, `check_ref_format`, … | [`refs`] |
59//! | `sparse_checkout`, `split_index`, `untracked_cache`, `resolve_undo`, … | [`index`] |
60//! | `rev_list`, `rev_parse`, `merge_base`, `commit_graph_file`, … | [`revwalk`] |
61//! | `bloom`, `patch_ids`, `merge_trees`, `rerere`, … | [`diff`] |
62//! | `dotfile`, `ident`, `init_filesystem`, … | [`config`] |
63//! | `fetch`, `push`, `transport`, `credentials`, … | [`remote`] |
64//! | `ignore`, `attributes`, `pathspec`, … | [`worktree`] |
65//! | porcelain stash types | [`stash`] |
66//! | `bundle_remote` | [`bundle`] |
67//! | `parallel` | [`parallel`] (root) |
68//! | `repo`, `error`, `porcelain`, `progress`, … | root (unchanged) |
69//!
70//! # Porcelain
71//!
72//! [`porcelain`] implements user-facing workflows (`status`, `log`, `merge`, …) as
73//! pure functions that return structured result models. The library/CLI contract
74//! is documented in [`porcelain`]: options in, models out, progress via
75//! [`ProgressSink`](progress::ProgressSink) — no terminal I/O in the library.
76//!
77//! # Storage and refs
78//!
79//! - **Object database ([`objects`])** — loose objects plus pack files, pack indexes,
80//!   multi-pack-index (MIDX), delta chains, and promisor/partial clone hooks.
81//!   Backends are pluggable via the ODB abstraction on [`objects::Objects`].
82//! - **References ([`refs`])** — loose files, `packed-refs`, and reftable stacks;
83//!   reflog read/write and ref storage format selection live in the same module.
84//!   [`RefStorageFormat`] selects the on-disk ref layout at init.
85//!
86//! # Network and bundles
87//!
88//! [`remote`] implements fetch, push, and ls-remote over local paths, git/ssh URLs,
89//! and (with the optional HTTP client) smart HTTP. [`bundle`] reads and writes Git
90//! bundle files and bundle-related transport helpers.
91//!
92//! # Features
93//!
94//! | Feature | Default | Description |
95//! | ------- | ------- | ----------- |
96//! | *(none)* | — | Core library: ODB, refs, index, diff, merge, local transport |
97//! | `http-ureq` | disabled | [`ureq`](https://docs.rs/ureq) HTTP client for smart-HTTP fetch/push (rustls) |
98//! | `http-ureq-native-tls` | disabled | Platform TLS for `http-ureq` (Secure Transport on macOS); use instead of rustls on Apple targets |
99//!
100//! Enable HTTP in `Cargo.toml`:
101//!
102//! ```toml
103//! grit-lib = { version = "0.1", features = ["http-ureq"] }
104//! ```
105//!
106//! # Errors and progress
107//!
108//! [`error`] defines typed failures with `thiserror`. Long-running work accepts a
109//! [`ProgressSink`](progress::ProgressSink) and optional cancellation; see [`progress`].
110//!
111//! # Scope
112//!
113//! Modules tied to removed Git-compatible CLI surface are documented in
114//! `docs/v1-scope.md`. Compatibility means **formats and protocols**, validated in
115//! tests against the system `git` binary — not argv or message strings.
116
117// --- Curated public API: domain roots and cross-cutting modules only.
118// Flat implementation modules are `pub(crate)`; use canonical domain paths. ---
119pub mod porcelain;
120pub mod progress;
121
122/// The types most callers need, re-exported for `use grit_lib::prelude::*;`.
123///
124/// Library guide: [embedding](https://grit-scm.com/docs/library/embedding)
125///
126/// ```rust
127/// use grit_lib::prelude::*;
128/// use grit_lib::repo::InitOptions;
129///
130/// # fn main() -> Result<()> {
131/// let dir = tempfile::tempdir()?;
132/// let repo = Repository::init(dir.path(), &InitOptions::default())?;
133/// let _cfg = repo.config()?;
134/// assert!(repo.refs().read_raw("HEAD")?.is_some());
135/// # Ok(())
136/// # }
137/// ```
138pub mod prelude {
139    pub use crate::command_runner::{CommandRunner, RecordingRunner, SystemCommandRunner};
140    pub use crate::config::ConfigSet;
141    pub use crate::diagnostics::{
142        CollectingDiagnostics, DiagnosticSink, NullDiagnostics, Trace, Warning,
143    };
144    pub use crate::environment::{Environment, RepositoryOptions};
145    pub use crate::error::{Error, MidxError, Result};
146    pub use crate::index::Index;
147    pub use crate::objects::odb::Odb;
148    pub use crate::objects::{Object, ObjectId, ObjectInfo, ObjectKind};
149    pub use crate::repo::{
150        resolve_initial_branch, DiscoveryInfo, InitOptions, InitOutcome, Repository,
151        RepositoryBuilder,
152    };
153}
154
155pub mod revwalk;
156pub mod stash;
157
158pub mod apply;
159pub(crate) mod attributes;
160pub mod blame;
161pub(crate) mod bloom;
162pub(crate) mod branch_inventory;
163pub(crate) mod branch_tracking;
164pub mod bundle;
165pub(crate) mod bundle_remote;
166pub mod change_id;
167pub(crate) mod check_ref_format;
168pub(crate) mod clone;
169pub(crate) mod combined_diff_patch;
170pub(crate) mod combined_tree_diff;
171pub mod command_runner;
172pub mod commit;
173pub(crate) mod commit_encoding;
174pub(crate) mod commit_graph_file;
175pub(crate) mod commit_graph_write;
176pub(crate) mod commit_pretty;
177pub(crate) mod commit_trailers;
178pub mod config;
179pub(crate) mod connectivity;
180pub(crate) mod credentials;
181pub(crate) mod crlf;
182pub(crate) mod delta_encode;
183pub(crate) mod delta_islands;
184pub(crate) mod delta_search;
185pub mod diagnostics;
186pub mod diff;
187pub(crate) mod diff_indent_heuristic;
188mod diff_rename_parallel;
189pub(crate) mod diffstat;
190pub(crate) mod dotfile;
191pub(crate) mod environment;
192pub mod error;
193mod ewah_bitmap;
194pub(crate) mod git_dir;
195pub(crate) mod github_auth;
196pub(crate) mod line_interner;
197pub mod line_range;
198pub(crate) mod oid_abbrev_cache;
199pub(crate) mod pack_roll_delta;
200pub(crate) mod partial_clone;
201
202#[path = "bench_fixture/mod.rs"]
203mod bench_fixture_root;
204pub(crate) mod bitmap_walk;
205pub(crate) mod fetch;
206pub(crate) mod fetch_head;
207pub(crate) mod fetch_negotiator;
208mod fetch_request;
209pub(crate) mod filter_process;
210pub(crate) mod fmt_merge_msg;
211pub(crate) mod fs_publish;
212pub(crate) mod fsck;
213pub(crate) mod fsck_standalone;
214#[path = "fsmonitor.rs"]
215mod fsmonitor_root;
216pub(crate) mod gc;
217pub(crate) mod git_binary_base85;
218pub(crate) mod git_date;
219pub(crate) mod git_path;
220pub(crate) mod gitmodules;
221pub(crate) mod hash;
222pub(crate) mod hide_refs;
223#[path = "history/mod.rs"]
224mod history_root;
225pub(crate) use history_root as history;
226pub(crate) mod hooks;
227pub mod ident;
228pub(crate) mod ident_config;
229pub(crate) mod ident_resolve;
230pub(crate) mod ignore;
231pub mod index;
232mod index_eoie_ieot;
233pub(crate) mod index_name_hash_lazy;
234pub(crate) mod index_pack;
235pub(crate) mod init_filesystem;
236pub(crate) mod interpret_trailers;
237pub mod list_limit;
238pub(crate) mod local_object_copy;
239pub mod lockfile;
240pub(crate) mod log_walk;
241pub(crate) mod mailmap;
242pub mod maintenance;
243pub(crate) mod merge_base;
244pub(crate) mod merge_diff;
245pub(crate) mod merge_driver;
246pub(crate) mod merge_file;
247pub(crate) mod merge_trees;
248pub(crate) mod midx;
249pub(crate) mod midx_error;
250pub(crate) mod net_trace;
251pub mod notes;
252#[path = "object_inspect.rs"]
253mod object_inspect_root;
254pub mod objects;
255pub(crate) mod odb;
256pub mod operation;
257pub(crate) mod pack;
258pub(crate) mod pack_bitmap;
259mod pack_delta;
260mod pack_delta_walk;
261mod pack_fsck_verify;
262mod pack_index;
263pub(crate) mod pack_index_build;
264mod pack_map;
265pub(crate) mod pack_name_hash;
266pub(crate) mod pack_object_select;
267pub(crate) mod pack_objects;
268pub(crate) mod pack_receive;
269#[path = "pack_reuse.rs"]
270mod pack_reuse_root;
271pub(crate) mod pack_rev;
272pub(crate) mod pack_store;
273pub(crate) mod pack_stream_scan;
274#[path = "pack_write.rs"]
275mod pack_write_root;
276pub(crate) mod pack_zlib;
277pub mod parallel;
278pub(crate) mod patch_ids;
279pub(crate) mod path_icase;
280pub(crate) mod path_population;
281pub mod path_validate;
282pub mod pathspec;
283pub(crate) mod pkt_line;
284pub(crate) mod precompose_config;
285pub(crate) mod promisor;
286pub(crate) mod promisor_fetch;
287pub(crate) mod promisor_remote;
288pub(crate) mod protocol;
289pub(crate) mod protocol_v2;
290pub(crate) mod prune_packed;
291pub(crate) mod push;
292pub(crate) mod push_report;
293#[path = "quote_path.rs"]
294mod quote_path_root;
295mod read_dir_kind;
296pub(crate) mod receive_pack;
297pub(crate) mod receive_quarantine;
298pub(crate) mod ref_exclusions;
299pub(crate) mod ref_namespace;
300pub(crate) mod ref_storage;
301pub(crate) mod reflog;
302pub mod refs;
303pub(crate) mod refs_fsck;
304pub(crate) mod refspec;
305pub(crate) mod reftable;
306pub mod remote;
307pub(crate) mod repack_pack;
308pub mod repo;
309pub(crate) mod repo_caches;
310pub mod repo_handles;
311#[doc(hidden)]
312pub mod repo_relpath;
313pub(crate) mod rerere;
314pub(crate) mod resolve_undo;
315pub(crate) mod rev_list;
316pub(crate) mod rev_list_error;
317pub(crate) mod rev_parse;
318pub(crate) mod rev_parse_error;
319pub(crate) mod serve;
320pub(crate) mod shallow;
321pub(crate) mod shared_repo;
322pub(crate) mod sideband_lines;
323pub(crate) mod signing;
324pub(crate) mod sparse_checkout;
325pub(crate) mod split_index;
326pub mod state;
327pub(crate) mod stripspace;
328pub(crate) mod submodule_gitdir;
329pub(crate) mod terminal;
330pub(crate) mod textconv_cache;
331pub(crate) mod trace;
332mod tracked_path_tree;
333pub(crate) mod transfer;
334pub(crate) mod transport;
335pub(crate) mod transport_path;
336pub mod tree_sha256;
337pub(crate) mod unicode_normalization;
338pub(crate) mod unpack_objects;
339pub(crate) mod untracked_cache;
340pub(crate) mod upload_filter;
341pub(crate) mod url_rewrite;
342pub(crate) mod userdiff;
343pub(crate) mod wildmatch;
344pub mod worktree;
345mod worktree_batch;
346pub(crate) mod worktree_cwd;
347pub(crate) mod worktree_ref;
348pub(crate) mod worktree_rules;
349mod worktree_rules_tests;
350mod worktree_scan;
351pub use crate::hooks::{HookName, PostOperationHooks};
352pub use worktree_scan::PARALLEL_STAT_MIN_ENTRIES;
353#[doc(hidden)]
354pub use worktree_scan::{reset_worktree_metadata_probe, worktree_metadata_probe_count};
355pub(crate) mod write_tree;
356pub(crate) mod ws;
357pub(crate) mod zlib_inflate;
358
359#[doc(hidden)]
360pub mod fuzz;
361
362pub use ref_storage::RefStorageFormat;
363
364pub use objects::bench_fixture;
365pub use objects::pack_reuse;
366pub use objects::pack_write;
367pub use porcelain::quote_path;
368pub use revwalk::object_inspect;
369pub use worktree::fsmonitor;
370
371#[cfg(feature = "unstable-bench-helpers")]
372pub use pack_receive::{read_sideband_pack_to, PackReceiveTarget};
373
374#[cfg(test)]
375pub(crate) mod hot_path_test_metrics;
376
377#[cfg(test)]
378mod object_write_regression;
379#[cfg(test)]
380mod repository_config_snapshot_tests;
381#[cfg(test)]
382mod status_clean_tree_regression;
grit_lib/lib.rs

grit_lib/
lib.rs
