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(crate) mod bundle_uri;
167pub mod change_id;
168pub(crate) mod check_ref_format;
169pub(crate) mod clone;
170pub(crate) mod combined_diff_patch;
171pub(crate) mod combined_tree_diff;
172pub mod command_runner;
173pub mod commit;
174pub(crate) mod commit_encoding;
175pub(crate) mod commit_graph_file;
176pub(crate) mod commit_graph_write;
177pub(crate) mod commit_pretty;
178pub(crate) mod commit_trailers;
179pub mod config;
180pub(crate) mod connectivity;
181pub(crate) mod credentials;
182pub(crate) mod crlf;
183pub(crate) mod delta_encode;
184pub(crate) mod delta_islands;
185pub(crate) mod delta_search;
186pub mod diagnostics;
187pub mod diff;
188pub(crate) mod diff_indent_heuristic;
189mod diff_rename_parallel;
190pub(crate) mod diffstat;
191pub(crate) mod dotfile;
192pub(crate) mod environment;
193pub mod error;
194mod ewah_bitmap;
195pub(crate) mod git_dir;
196pub(crate) mod github_auth;
197pub(crate) mod grit_server_auth;
198pub(crate) mod line_interner;
199pub mod line_range;
200pub(crate) mod oid_abbrev_cache;
201pub(crate) mod pack_roll_delta;
202pub(crate) mod partial_clone;
203
204#[path = "bench_fixture/mod.rs"]
205mod bench_fixture_root;
206pub(crate) mod bitmap_walk;
207pub(crate) mod fetch;
208pub(crate) mod fetch_head;
209pub(crate) mod fetch_negotiator;
210mod fetch_request;
211pub(crate) mod filter_process;
212pub(crate) mod fmt_merge_msg;
213pub(crate) mod fs_publish;
214pub(crate) mod fsck;
215pub(crate) mod fsck_msg_policy;
216pub(crate) mod fsck_standalone;
217#[path = "fsmonitor.rs"]
218mod fsmonitor_root;
219pub(crate) mod gc;
220pub(crate) mod git_binary_base85;
221pub(crate) mod git_date;
222pub(crate) mod git_path;
223pub(crate) mod gitmodules;
224pub(crate) mod hash;
225pub(crate) mod hide_refs;
226#[path = "history/mod.rs"]
227mod history_root;
228pub(crate) use history_root as history;
229pub(crate) mod hooks;
230pub mod ident;
231pub(crate) mod ident_config;
232pub(crate) mod ident_resolve;
233pub(crate) mod ignore;
234pub mod index;
235mod index_eoie_ieot;
236pub(crate) mod index_name_hash_lazy;
237pub(crate) mod index_pack;
238pub(crate) mod init_filesystem;
239pub(crate) mod interpret_trailers;
240pub mod list_limit;
241pub(crate) mod local_object_copy;
242pub mod lockfile;
243pub(crate) mod log_walk;
244pub(crate) mod mailmap;
245pub mod maintenance;
246pub(crate) mod merge_base;
247pub(crate) mod merge_diff;
248pub(crate) mod merge_driver;
249pub(crate) mod merge_file;
250pub(crate) mod merge_trees;
251pub(crate) mod midx;
252pub(crate) mod midx_error;
253pub(crate) mod net_trace;
254pub mod notes;
255#[path = "object_inspect.rs"]
256mod object_inspect_root;
257pub mod objects;
258pub(crate) mod odb;
259pub mod operation;
260pub(crate) mod pack;
261pub(crate) mod pack_bitmap;
262mod pack_delta;
263mod pack_delta_walk;
264mod pack_fsck_verify;
265mod pack_index;
266pub(crate) mod pack_index_build;
267mod pack_map;
268pub(crate) mod pack_name_hash;
269pub(crate) mod pack_object_select;
270pub(crate) mod pack_objects;
271pub(crate) mod pack_receive;
272#[path = "pack_reuse.rs"]
273mod pack_reuse_root;
274pub(crate) mod pack_rev;
275pub(crate) mod pack_store;
276pub(crate) mod pack_stream_scan;
277mod pack_thin_bases;
278#[path = "pack_write.rs"]
279mod pack_write_root;
280pub(crate) mod pack_zlib;
281pub mod parallel;
282pub(crate) mod patch_ids;
283pub(crate) mod path_icase;
284pub(crate) mod path_population;
285pub mod path_validate;
286pub mod pathspec;
287pub(crate) mod pkt_line;
288pub(crate) mod precompose_config;
289pub(crate) mod promisor;
290pub(crate) mod promisor_fetch;
291pub(crate) mod promisor_remote;
292pub(crate) mod protocol;
293pub(crate) mod protocol_v2;
294pub(crate) mod prune_packed;
295pub(crate) mod push;
296pub(crate) mod push_bundle;
297pub(crate) mod push_report;
298#[path = "quote_path.rs"]
299mod quote_path_root;
300mod read_dir_kind;
301pub(crate) mod receive_pack;
302pub(crate) mod receive_quarantine;
303pub(crate) mod ref_exclusions;
304pub(crate) mod ref_namespace;
305pub(crate) mod ref_storage;
306pub(crate) mod reflog;
307pub mod refs;
308pub(crate) mod refs_fsck;
309pub(crate) mod refspec;
310pub(crate) mod reftable;
311pub mod remote;
312pub(crate) mod repack_pack;
313pub mod repo;
314pub(crate) mod repo_caches;
315pub mod repo_handles;
316#[doc(hidden)]
317pub mod repo_relpath;
318pub(crate) mod rerere;
319pub(crate) mod resolve_undo;
320pub(crate) mod resumable;
321pub(crate) mod rev_list;
322pub(crate) mod rev_list_error;
323pub(crate) mod rev_parse;
324pub(crate) mod rev_parse_error;
325pub(crate) mod serve;
326pub(crate) mod shallow;
327pub(crate) mod shared_repo;
328pub(crate) mod sideband_lines;
329pub(crate) mod signing;
330pub(crate) mod snapshot_checkout;
331pub(crate) mod sparse_checkout;
332pub(crate) mod split_index;
333pub mod state;
334pub(crate) mod stripspace;
335pub(crate) mod submodule_gitdir;
336pub(crate) mod terminal;
337pub(crate) mod textconv_cache;
338pub(crate) mod trace;
339mod tracked_path_tree;
340pub(crate) mod transfer;
341pub(crate) mod transport;
342pub(crate) mod transport_path;
343pub mod tree_sha256;
344pub(crate) mod unicode_normalization;
345pub(crate) mod unpack_objects;
346pub(crate) mod untracked_cache;
347pub(crate) mod upload_filter;
348pub(crate) mod url_rewrite;
349pub(crate) mod userdiff;
350pub(crate) mod wildmatch;
351pub mod worktree;
352mod worktree_batch;
353pub(crate) mod worktree_cwd;
354pub(crate) mod worktree_ref;
355pub(crate) mod worktree_rules;
356mod worktree_rules_tests;
357mod worktree_scan;
358pub use crate::hooks::{HookName, PostOperationHooks};
359pub use worktree_scan::PARALLEL_STAT_MIN_ENTRIES;
360#[doc(hidden)]
361pub use worktree_scan::{reset_worktree_metadata_probe, worktree_metadata_probe_count};
362pub(crate) mod write_tree;
363pub(crate) mod ws;
364pub(crate) mod zlib_inflate;
365
366#[doc(hidden)]
367pub mod fuzz;
368
369pub use ref_storage::RefStorageFormat;
370
371pub use objects::bench_fixture;
372pub use objects::pack_reuse;
373pub use objects::pack_write;
374pub use porcelain::quote_path;
375pub use revwalk::object_inspect;
376pub use worktree::fsmonitor;
377
378#[cfg(feature = "unstable-bench-helpers")]
379pub use pack_receive::{read_sideband_pack_to, PackReceiveTarget};
380
381#[cfg(test)]
382pub(crate) mod hot_path_test_metrics;
383
384#[cfg(test)]
385mod object_write_regression;
386#[cfg(test)]
387mod repository_config_snapshot_tests;
388#[cfg(test)]
389mod status_clean_tree_regression;
grit_lib/lib.rs

grit_lib/
lib.rs
