Crate grit_lib 

grit-lib — fast, linkable Git engine for Rust.

Grit reimplements Git’s on-disk formats and wire protocols in idiomatic Rust so embedders can open repositories, walk history, diff, merge, fetch, and push without shelling out to the git binary. The grit CLI is a thin presentation layer over this crate; almost all behavior lives here.

Getting started

Repository is the primary entry point: discover or open a work tree, then use methods and focused modules for objects, refs, the index, config, remotes, and porcelain operations.

use grit_lib::config::environment::RepositoryOptions;
use grit_lib::repo::{InitOptions, Repository};
use grit_lib::state::resolve_head;

let dir = tempfile::tempdir()?;
let repo = Repository::init(dir.path(), &InitOptions::default())?;
let head = resolve_head(repo.git_dir())?;
assert!(matches!(head, grit_lib::state::HeadState::Branch { short_name, oid: None, .. } if short_name == "main"));
let _ = Repository::open(
    repo.git_dir(),
    &RepositoryOptions::empty().with_work_tree(dir.path()),
)?;

• Repository exposes typed handles for objects, refs, the index, config, revision walking, and diffs (objects::Objects, refs::References, index::IndexHandle, config::ConfigHandle, revwalk::RevWalk, diff::Diff), plus repo_handles for remotes, worktrees, stash, notes, reflogs, and bundles.
• prelude re-exports the types most call sites need.
• porcelain holds user-facing operations that return structured result models (the CLI renders them).
• Browse the engine by domain: objects, refs, index, revwalk, diff, config, remote, worktree, stash, notes, and bundle. Legacy flat paths (grit_lib::odb, grit_lib::fetch, …) are private; grit-scm.com/docs/library/api-layout maps each old path to its canonical replacement.
• progress defines how long-running operations report progress and observe cancellation without touching the terminal.

API layout (canonical domains)

Flat path	Canonical path
odb, pack, midx, hash, pack_bitmap, bitmap_walk, …	objects
reflog, refspec, reftable, check_ref_format, …	refs
sparse_checkout, split_index, untracked_cache, resolve_undo, …	index
rev_list, rev_parse, merge_base, commit_graph_file, …	revwalk
bloom, patch_ids, merge_trees, rerere, …	diff
dotfile, ident, init_filesystem, …	config
fetch, push, transport, credentials, …	remote
ignore, attributes, pathspec, …	worktree
porcelain stash types	stash
bundle_remote	bundle
parallel	parallel (root)
repo, error, porcelain, progress, …	root (unchanged)

Porcelain

porcelain implements user-facing workflows (status, log, merge, …) as pure functions that return structured result models. The library/CLI contract is documented in porcelain: options in, models out, progress via ProgressSink — no terminal I/O in the library.

Storage and refs

• Object database (objects) — loose objects plus pack files, pack indexes, multi-pack-index (MIDX), delta chains, and promisor/partial clone hooks. Backends are pluggable via the ODB abstraction on objects::Objects.
• References (refs) — loose files, packed-refs, and reftable stacks; reflog read/write and ref storage format selection live in the same module. RefStorageFormat selects the on-disk ref layout at init.

Network and bundles

remote implements fetch, push, and ls-remote over local paths, git/ssh URLs, and (with the optional HTTP client) smart HTTP. bundle reads and writes Git bundle files and bundle-related transport helpers.

Features

Feature	Default	Description
(none)	—	Core library: ODB, refs, index, diff, merge, local transport
http-ureq	disabled	ureq HTTP client for smart-HTTP fetch/push (rustls)
http-ureq-native-tls	disabled	Platform TLS for http-ureq (Secure Transport on macOS); use instead of rustls on Apple targets

Enable HTTP in Cargo.toml:

grit-lib = { version = "0.1", features = ["http-ureq"] }

Errors and progress

error defines typed failures with thiserror. Long-running work accepts a ProgressSink and optional cancellation; see progress.

Scope

Modules tied to removed Git-compatible CLI surface are documented in docs/v1-scope.md. Compatibility means formats and protocols, validated in tests against the system git binary — not argv or message strings.

Re-exports

pub use objects::bench_fixture;

pub use objects::pack_reuse;

pub use objects::pack_write;

pub use porcelain::quote_path;

pub use revwalk::object_inspect;

pub use worktree::fsmonitor;

Modules

apply

Unified/git-diff patch parsing and blob-level hunk application.

blame

Blame line-mapping algorithm.

bundle

Bundle files and bundle-over-remote transport.

change_id

Change identifiers stored in commit headers.

command_runner

Injectable subprocess execution for hooks, filters, credentials, and helpers.

commit

Commit-metadata helpers shared by the porcelain commands.

config

Configuration cascade, identity, and repository bootstrap helpers.

diagnostics

Git-style diagnostic prefixes and typed warning sinks for embedders and the CLI.

diff

Tree and content diffs, rename detection, merge diffs, and related helpers.

error

Shared error types for grit-lib.

ident

Git author/committer identity lines (ident in Git’s fsck.c / commit.c).

index

Git index (staging area) read/write and related cache extensions.

line_range

Resolve Git-style -L line ranges for blame (and future log -L).

list_limit

Bounded list results shared by notes, hooks, bundle heads, and CLI list commands.

lockfile

Exclusive lock files with optional Git-style acquisition backoff.

maintenance

Repository maintenance: repack, fsck, and garbage collection orchestration.

notes

Git notes refs and note commit helpers.

objects

Git objects: ids, kinds, in-memory representations, and the object database stack.

operation

Shared conflict classification and in-progress operation vocabulary.

parallel

Ordered scoped-thread parallelism and Git config-driven thread policy.

path_validate

Git-compatible path component validation (verify_path / tree fsck rules).

pathspec

Git-compatible pathspec matching (magic tokens and global flags).

porcelain

Porcelain operations — user-facing workflows that assemble structured result models from domain modules (e.g. diff, revwalk, status, log, merge, checkout, and related commands).

prelude

The types most callers need, re-exported for use grit_lib::prelude::*;.

progress

Progress reporting and cancellation across the library/CLI boundary.

refs

Reference storage — files backend + reftable backend.

remote

Remotes, fetch/push, transport, and credential helpers.

repo

Repository discovery and the primary Repository handle.

repo_handles

Typed Repository handles for remotes, worktrees, stash, notes, reflogs, and bundles.

revwalk

Revision walking: rev-parse, rev-list, merge-base, and commit-graph acceleration.

stash

Stash stack read/write — stable types from crate::porcelain::stash.

state

Repository state machine — HEAD resolution, branch status, and in-progress operation detection.

tree_sha256

SHA-256 tree digest over repository file contents (tree-sha256 spec).

worktree

Working tree, ignore/attributes, and checkout path helpers.

Enums

HookName

Well-known lifecycle hooks that porcelain operations run and report in their outcomes (for example crate::porcelain::commit::CommitOutcome::hooks_run).

PostOperationHooks

Whether an operation runs the hooks Git runs once it has completed (post-checkout, post-merge, post-rewrite).

RefStorageFormat

On-disk ref storage backend named by extensions.refStorage.

Constants

PARALLEL_STAT_MIN_ENTRIES

Minimum tracked blob entries before parallel stat preload is considered.