# api-layout

# grit-lib API layout

Grit’s stable surface is the **canonical domain tree** (≤25 root modules plus [`prelude`](https://docs.rs/grit-lib/latest/grit_lib/prelude/index.html)). 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`](https://github.com/gitbutlerapp/grit/blob/main/grit-lib/canonical-modules.toml) lists every previously flat path and its canonical replacement.

## Domain roots

| Domain | Role |
| --- | --- |
| [`objects`](https://docs.rs/grit-lib/latest/grit_lib/objects/index.html) | Object ids/kinds, ODB, packs, MIDX, hashing, deltas, bitmaps |
| [`refs`](https://docs.rs/grit-lib/latest/grit_lib/refs/index.html) | Ref backends, reflog, refspecs, reftable, name validation |
| [`index`](https://docs.rs/grit-lib/latest/grit_lib/index/index.html) | Index file, sparse checkout, split index, untracked cache |
| [`revwalk`](https://docs.rs/grit-lib/latest/grit_lib/revwalk/index.html) | `rev-parse`, `rev-list`, merge-base, commit-graph |
| [`diff`](https://docs.rs/grit-lib/latest/grit_lib/diff/index.html) | Tree/content diff, merge diffs, rerere, patch-ids helpers |
| [`config`](https://docs.rs/grit-lib/latest/grit_lib/config/index.html) | Config cascade, identity, init/bootstrap |
| [`remote`](https://docs.rs/grit-lib/latest/grit_lib/remote/index.html) | Remotes, fetch/push, transport, credentials |
| [`worktree`](https://docs.rs/grit-lib/latest/grit_lib/worktree/index.html) | Working tree, ignore, attributes, pathspec |
| [`stash`](https://docs.rs/grit-lib/latest/grit_lib/stash/index.html) | Stash stack (porcelain types) |
| [`notes`](https://docs.rs/grit-lib/latest/grit_lib/notes/index.html) | Git notes |
| [`bundle`](https://docs.rs/grit-lib/latest/grit_lib/bundle/index.html) | Bundle files and bundle-over-remote |
| [`parallel`](https://docs.rs/grit-lib/latest/grit_lib/parallel/index.html) | 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`](https://github.com/gitbutlerapp/grit/blob/main/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.