README: Clarify the finding your way around section again v0.1.111

1 files changed, 16 insertions, 23 deletions

diff --git a/README.md b/README.md
index 5e9e136b..151bcf01 100644
--- a/README.md
+++ b/README.md
@@ -21,12 +21,10 @@ Furgit is a low-level Git library in Go.
 
 ## 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:
+If you are working with a normal on-disk repository, start with
+`repository.Open(...)`. It opens the repository and wires together the refs
+storage, object storage, and resolver. Note that it requires either a
+bare repository or a `.git` directory. Then,
 
 * `repo.Refs()` is for branch names, tags, `HEAD`, and ref updates.
   * Use it when you are starting from names rather than object IDs.
@@ -41,7 +39,7 @@ serve different purposes:
   * 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.
+* `repo.Objects()` is the storage layer underneath `Resolver`.
   * Use it when you need to read object headers, read raw object contents,
     stream object data, or otherwise look up objects directly by ID.
   * Most callers who want to work with Git objects as commits, trees, blobs, or
@@ -49,7 +47,7 @@ serve different purposes:
   * However, checking an object ID's size and type are somewhat common
     operations that should be done here.
 
-Some object concepts are kept separate:
+Note that:
 
 * `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
@@ -66,26 +64,21 @@ As a rule of thumb:
 * 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:
+Some useful operations are separate 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.
+  bases, construct a `commitquery.Query` over `repo.Objects()`. 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.
+  construct a `reachability.Reachability` over `repo.Objects()`. 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.
+* To accept pushes on the server side, construct `network/receivepack` or
+  `network/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