diff options
Diffstat (limited to 'repository')
| -rw-r--r-- | repository/commit_graph.go | 5 | ||||
| -rw-r--r-- | repository/commit_queries.go | 2 | ||||
| -rw-r--r-- | repository/fetcher.go | 4 | ||||
| -rw-r--r-- | repository/objects.go | 4 | ||||
| -rw-r--r-- | repository/open.go | 6 | ||||
| -rw-r--r-- | repository/reachability.go | 3 | ||||
| -rw-r--r-- | repository/refs.go | 4 | ||||
| -rw-r--r-- | repository/repository.go | 17 |
8 files changed, 36 insertions, 9 deletions
diff --git a/repository/commit_graph.go b/repository/commit_graph.go index 3f0a0888..4f210b56 100644 --- a/repository/commit_graph.go +++ b/repository/commit_graph.go @@ -31,6 +31,11 @@ func openCommitGraph(root *os.Root, algo objectid.Algorithm) (*commitgraphread.R // CommitGraph returns the configured commit-graph reader, if available. // +// Not all repositories have a commit-graph, so CommitGraph may return nil. +// Most callers should prefer [Repository.CommitQueries] or +// [Repository.Reachability] unless they specifically need direct +// commit-graph access. +// // Labels: Life-Parent, Close-No. func (repo *Repository) CommitGraph() *commitgraphread.Reader { return repo.commitGraph diff --git a/repository/commit_queries.go b/repository/commit_queries.go index e3d223ae..1377fd96 100644 --- a/repository/commit_queries.go +++ b/repository/commit_queries.go @@ -5,6 +5,8 @@ import "codeberg.org/lindenii/furgit/commitquery" // CommitQueries returns commit queries backed by the repository's object store // and optional commit-graph. // +// Use CommitQueries for ancestor checks and merge-base computation. +// // Labels: Life-Parent, Close-No. func (repo *Repository) CommitQueries() *commitquery.Queries { return repo.commitQueries diff --git a/repository/fetcher.go b/repository/fetcher.go index 6701b806..7c3ea421 100644 --- a/repository/fetcher.go +++ b/repository/fetcher.go @@ -4,6 +4,10 @@ import "codeberg.org/lindenii/furgit/object/fetch" // Fetcher returns an object fetcher backed by the repository's object store. // +// Use Fetcher when you want typed commits, trees, blobs, or tags, when you +// need to peel through annotated tags, or when you want path-based access +// within trees. +// // Labels: Life-Parent, Close-No. func (repo *Repository) Fetcher() *fetch.Fetcher { return fetch.New(repo.objects) diff --git a/repository/objects.go b/repository/objects.go index ea1956c1..62170514 100644 --- a/repository/objects.go +++ b/repository/objects.go @@ -77,6 +77,10 @@ func openObjectStore( // Objects returns the configured object store. // +// Use Objects for direct object-ID lookups, object headers, sizes, raw object +// bytes, or streamed object contents. Callers who want typed object values +// should usually prefer [Repository.Fetcher]. +// // Labels: Life-Parent, Close-No. // //nolint:ireturn diff --git a/repository/open.go b/repository/open.go index 3c400f60..3724df26 100644 --- a/repository/open.go +++ b/repository/open.go @@ -8,7 +8,11 @@ import ( reffiles "codeberg.org/lindenii/furgit/ref/store/files" ) -// Open opens a repository and wires object/ref stores from its on-disk format. +// Open opens a repository and wires its stores and helpers from the on-disk +// repository format. +// +// root must refer to the Git directory itself: +// a bare repository root or a non-bare ".git" directory. // // Labels: Deps-Borrowed. func Open(root *os.Root) (repo *Repository, err error) { diff --git a/repository/reachability.go b/repository/reachability.go index 4e6a4559..24f9e2bd 100644 --- a/repository/reachability.go +++ b/repository/reachability.go @@ -5,6 +5,9 @@ import "codeberg.org/lindenii/furgit/reachability" // Reachability returns graph traversal helpers backed by the repository's // object store and optional commit-graph. // +// Use Reachability to walk reachable commits or objects and to perform +// connectivity checks. +// // Labels: Life-Parent, Close-No. func (repo *Repository) Reachability() *reachability.Reachability { return reachability.New(repo.objects, repo.commitGraph) diff --git a/repository/refs.go b/repository/refs.go index 2e89aed6..0403e001 100644 --- a/repository/refs.go +++ b/repository/refs.go @@ -4,6 +4,10 @@ import refstore "codeberg.org/lindenii/furgit/ref/store" // Refs returns the configured ref store. // +// Use Refs when starting from branch names, tags, HEAD, or other references. +// A common pattern is to resolve a reference first and then pass the resulting +// object ID to [Repository.Fetcher] or [Repository.Objects]. +// // Labels: Life-Parent, Close-No. // //nolint:ireturn diff --git a/repository/repository.go b/repository/repository.go index 119f8c42..301607f9 100644 --- a/repository/repository.go +++ b/repository/repository.go @@ -1,4 +1,10 @@ -// Package repository opens stores and other objects to access a typical on-disk repo. +// Package repository opens a typical on-disk Git repository and exposes its +// main stores and helpers. +// +// Start with [Open] when working with a bare repository root or a non-bare +// ".git" directory. [Repository] then provides access to ref storage, object +// storage, typed object fetching, commit queries, reachability helpers, and +// optional commit-graph access. package repository import ( @@ -14,17 +20,12 @@ import ( refstore "codeberg.org/lindenii/furgit/ref/store" ) -// Repository represents a typical on-disk Git repository by composing -// its stores together for access. +// Repository represents a typical on-disk Git repository by composing its +// stores and helpers together for access. // // Open expects a root for the Git directory itself: // a bare repository root or a non-bare ".git" directory. // -// Accessors such as [Repository.Objects], [Repository.CommitGraph], -// [Repository.CommitQueries], [Repository.Reachability], [Repository.Refs], -// [Repository.Fetcher], and [Repository.LooseStoreForWriting] return -// repository-backed views. -// // Labels: MT-Safe, Close-Caller. type Repository struct { config *config.Config |