From c9ef205cfc4bbf9f8e22aa41eea1df81e5c7266f Mon Sep 17 00:00:00 2001
From: Runxi Yu
Date: Tue, 24 Mar 2026 06:13:33 +0000
Subject: README: Add finding your way around

---
 README.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)

diff --git a/README.md b/README.md
index c0fdcb53..6a3d0e72 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,82 @@ Furgit is a low-level Git library in Go.
 * 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
-- 
cgit v1.3.1-10-gc9f91