Adds the project's first README. The repo previously had no README
(per AGENTS.md: "No README. No docs beyond the code."); this doc
collects the existing notes from AGENTS.md into a public-facing
overview so external consumers don't have to read source first.
Sections:
- Status: library only, single crate, edition 2024 (rustc ≥ 1.85),
streaming-first server surface exists as a contract but is not
implemented.
- Features: a per-module capability table for every public feature
module (commit, branch, tag, refs, tree, blob, diff, merge,
conflict, compare, remote, archive, setup, cleanup, config, blame,
submodule, command, cache, server).
- Architecture: ASCII diagram of GitBaby -> facade + feature
modules, plus bullets explaining:
* `impl GitBaby { ... }` blocks are where the public surface
lives,
* `RepositoryFacade` is consumer-implemented (no default),
* read/write ops mostly shell out to git via `Cmd` (order-
preserving `Env`, 64 MiB output cap, timeouts); metadata reads
go through `gix`,
* errors are hand-written (thiserror is declared but unused),
* `Env` order matters.
- Quick start: Cargo.toml snippet and a runnable `RepositoryFacade`
implementation that exercises `get_commit`, `get_tree_entries`,
`rev_parse`, and `list_branches`.
- Server (planned): lists the streaming contract methods, the
BoxedAsyncRead alias, the 64 MiB / 5 GiB caps, and the "do not
implement without a concrete protocol task" caveat.
- Cache: single-process foyer-backed store, namespace list, and
lifecycle helpers.
- Compatibility conventions: serde-serialized cache payloads are
additive-only with #[serde(default)] on every new field.
- Testing: cargo test / cargo test --test <file> / clippy / fmt
commands.
- License: TBD (placeholder).
CI: docs only, no compile impact. README is not picked up by cargo
build or any of the existing tests.
Notes:
- Cargo metadata (description, license, keywords, repository) is
intentionally NOT touched here — those belong in Cargo.toml and
can be added in a follow-up.
- The README duplicates a few bullets from AGENTS.md. AGENTS.md
stays as the project-internal contributor note; this README is
the consumer-facing entry point. A future cleanup could
deduplicate, but for now both stay since they serve different
audiences.
