ref: c9ef205cfc4bbf9f8e22aa41eea1df81e5c7266f
parent: a454068d748a363833df3a2219ac278bcaf4c39b
author: Runxi Yu <runxiyu@umich.edu>
date: Tue Mar 24 02:13:33 EDT 2026
README: Add finding your way around
--- a/README.md
+++ b/README.md
@@ -18,6 +18,82 @@
* Aim for clear architecture then high performance
* Expect familiarity with Git internals
+## Finding your way around
+
+If you are working with an on-disk repository, start with
+`repository.Open(...)`. It opens the repository and wires together the refs storage, object
+storage, and resolver.
+
+That gives you a repository handle with a few different entry points, but they
+serve different purposes:
+
+* `repo.Refs()` is for branch names, tags, `HEAD`, and ref updates.
+ * Use it when you are starting from names rather than object IDs.
+ * A common pattern is to resolve a ref first, then pass the resulting object
+ ID to the resolver.
+
+* `repo.Resolver()` is the main object-facing API for most callers.
+ * Use it when you want commits, trees, blobs, or tags as typed values.
+ * It also handles peeling through annotated tags, resolving objects to the
+ type you actually want, and walking paths inside trees.
+ * It even allows you to access a tree as an `io/fs.FS`.
+ * If your goal is "show me this commit", "read this tree", "follow this tag",
+ or "get me the file at this path", this is usually the right layer.
+
+* `repo.Objects()` is the storage layer underneath resolution.
+ * Use it when you need to read object headers, read raw object contents,
+ stream object data, or look up objects directly by ID.
+ * Most callers who want to work with Git objects as commits, trees, blobs, or
+ tags should prefer the resolver instead.
+ * However, checking an object ID's size and type are somewhat common
+ operations that should be done here.
+
+Some object concepts are kept separate:
+
+* `object` contains parsed Git object values such as blobs, trees, commits, and
+ tags. These are the decoded contents of Git objects and do not tell you
+ anything about the object's identity.
+
+* `object/stored` wraps a parsed object together with the object ID it was
+ loaded from. This is used when you need both the parsed value and the
+ identity it was loaded under.
+
+As a rule of thumb:
+
+* If you have a ref name, start with `repo.Refs()`.
+* If you want typed objects or path-based access, use `repo.Resolver()`.
+* If you need raw object lookup by ID, object headers, or object streams, use
+ `repo.Objects()`.
+
+Some useful operations are built separately and are meant to be constructed
+over the stores that `Repository` already exposes:
+
+* To check whether one revision is an ancestor of another, or to compute merge
+ bases, construct a `commitquery.Query` over `repo.Objects()`.
+ * This is the tool to reach for when you already have object IDs and want to
+ ask commit-history questions.
+ * If you already have a commit-graph reader, pass it in as well for
+ performance.
+
+* To walk commits or all reachable objects from a set of starting points,
+ construct a `reachability.Reachability` over `repo.Objects()`.
+ * Use commit traversal when you only care about history, and full object
+ traversal when you care about the complete reachable object set.
+ * This is useful for tasks such as connectivity checks and computing the
+ object set that a fetch or push needs to account for.
+
+* To accept pushes on the server side, construct `receivepack` or
+ `receivepack/service` with the repository's ref store, object store, and
+ object ID algorithm.
+ * Push handling also needs the repository's object storage root so incoming
+ objects can be quarantined and later promoted.
+ * `Repository` does not currently expose that root directly (we'll consider
+ possible solutions sometime later), so a push server usually keeps the
+ repository path or object root handle alongside the `Repository` value.
+ * Hook-based checks are just Go functions; then, a fast-forward check can use
+ `commitquery` over the existing and quarantined object stores. Some hooks
+ are provided.
+
## Features
* Configuration
--
⑨