diff options
| -rw-r--r-- | README.md | 39 |
1 files changed, 16 insertions, 23 deletions
@@ -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 |