grit-lib API layout
Grit’s stable surface is the canonical domain tree (≤25 root modules plus prelude). Flat implementation modules such as odb or fetch at the crate root are private; use grit_lib::objects::odb and grit_lib::remote::fetch instead. The map in grit-lib/canonical-modules.toml lists every previously flat path and its canonical replacement.
Domain roots
| Domain | Role |
|---|---|
objects |
Object ids/kinds, ODB, packs, MIDX, hashing, deltas, bitmaps |
refs |
Ref backends, reflog, refspecs, reftable, name validation |
index |
Index file, sparse checkout, split index, untracked cache |
revwalk |
rev-parse, rev-list, merge-base, commit-graph |
diff |
Tree/content diff, merge diffs, rerere, patch-ids helpers |
config |
Config cascade, identity, init/bootstrap |
remote |
Remotes, fetch/push, transport, credentials |
worktree |
Working tree, ignore, attributes, pathspec |
stash |
Stash stack (porcelain types) |
notes |
Git notes |
bundle |
Bundle files and bundle-over-remote |
parallel |
Thread policy and parallel helpers (root) |
Cross-cutting entry points (repo, error, porcelain, progress, …) remain at the crate root.
Flat → canonical map
The authoritative map lives in grit-lib/canonical-modules.toml. CI checks that every grit_lib::… import in grit-cli, grit-protocol, grit-examples, grit-utils, grit-test-support, and grit-lib/tests appears in that file (scripts/check_canonical_layout.py, wired from canonical_paths integration test). Imports must use the canonical domain path (for example grit_lib::objects::odb, not the private flat odb module); scripts/check_noncanonical_grit_lib_imports.py enforces that (no_noncanonical_grit_lib_imports in the same integration test, and scripts/tests/test_canonical_layout.py in the docs CI job).
Examples:
| Private flat module | Canonical path |
|---|---|
odb |
grit_lib::objects::odb |
pack_bitmap |
grit_lib::objects::bitmap |
bitmap_walk |
grit_lib::objects::bitmap |
rev_list |
grit_lib::revwalk::rev_list |
fetch |
grit_lib::remote::fetch |
ignore |
grit_lib::worktree::ignore |
sparse_checkout |
grit_lib::index::sparse_checkout |
reflog |
grit_lib::refs::reflog |
serve |
grit_lib::remote::serve |
transfer |
grit_lib::remote::transfer |
Removed view modules (use domains above instead): object_store, references, worktree_index, revision, diffing, merging, configuration, and the empty plumbing scaffold.
Nested implementation modules
Some canonical paths re-export submodules of the flat implementation (for example grit_lib::objects::odb::store is the public path for the object-store backend). Prefer the canonical prefix in all new code.