fetch

Documentation

Overview

Package fetch loads typed Git objects from object storage and provides higher-level object queries.

Fetching is above objectstore: it parses stored objects into blobs, trees, commits, and tags, exposes object metadata, peels tree-ish or commit-ish objects, resolves paths within trees, and can expose one tree as an io/fs view.

Index

• type Fetcher
  • func New(store objectstore.Reader) *Fetcher
  • func (r *Fetcher) ExactBlob(id objectid.ObjectID) (*stored.Stored[*blob.Blob], error)
  • func (r *Fetcher) ExactBlobReader(id objectid.ObjectID) (io.ReadCloser, int64, error)
  • func (r *Fetcher) ExactCommit(id objectid.ObjectID) (*stored.Stored[*commit.Commit], error)
  • func (r *Fetcher) ExactObject(id objectid.ObjectID) (*stored.Stored[object.Object], error)
  • func (r *Fetcher) ExactTag(id objectid.ObjectID) (*stored.Stored[*tag.Tag], error)
  • func (r *Fetcher) ExactTree(id objectid.ObjectID) (*stored.Stored[*tree.Tree], error)
  • func (r *Fetcher) Header(id objectid.ObjectID) (objecttype.Type, int64, error)
  • func (r *Fetcher) Path(root objectid.ObjectID, parts [][]byte) (tree.TreeEntry, error)
  • func (r *Fetcher) PeelToBlob(id objectid.ObjectID) (*stored.Stored[*blob.Blob], error)
  • func (r *Fetcher) PeelToBlobID(id objectid.ObjectID) (objectid.ObjectID, error)
  • func (r *Fetcher) PeelToBlobReader(id objectid.ObjectID) (io.ReadCloser, int64, error)
  • func (r *Fetcher) PeelToCommit(id objectid.ObjectID) (*stored.Stored[*commit.Commit], error)
  • func (r *Fetcher) PeelToCommitID(id objectid.ObjectID) (objectid.ObjectID, error)
  • func (r *Fetcher) PeelToTree(id objectid.ObjectID) (*stored.Stored[*tree.Tree], error)
  • func (r *Fetcher) PeelToTreeID(id objectid.ObjectID) (objectid.ObjectID, error)
  • func (r *Fetcher) Size(id objectid.ObjectID) (int64, error)
  • func (r *Fetcher) TreeFS(root objectid.ObjectID) (*TreeFS, error)
• type PathEmptyError
  • func (err *PathEmptyError) Error() string
• type PathNotFoundError
  • func (err *PathNotFoundError) Error() string
• type PathNotTreeError
  • func (err *PathNotTreeError) Error() string
• type PathSegmentEmptyError
  • func (err *PathSegmentEmptyError) Error() string
• type TreeFS
  • func (treeFS *TreeFS) Open(name string) (fs.File, error)
  • func (treeFS *TreeFS) ReadDir(name string) ([]fs.DirEntry, error)
  • func (treeFS *TreeFS) ReadFile(name string) ([]byte, error)
  • func (treeFS *TreeFS) Stat(name string) (fs.FileInfo, error)
  • func (treeFS *TreeFS) Sub(dir string) (fs.FS, error)

Types

type Fetcher

type Fetcher struct {
	// contains filtered or unexported fields
}

Fetcher provides ordinary object access above an object store.

It exposes object metadata, typed object loading, tree-ish and commit-ish peeling, path resolution, one-tree fs views, and blob content streaming.

Labels: MT-Safe.

func New

func New(store objectstore.Reader) *Fetcher

New returns a Fetcher that reads objects from store.

Labels: Deps-Borrowed, Life-Parent.

func (*Fetcher) ExactBlob

func (r *Fetcher) ExactBlob(id objectid.ObjectID) (*stored.Stored[*blob.Blob], error)

ExactBlob reads, parses, and wraps the blob at id.

Labels: Life-Parent.

func (*Fetcher) ExactBlobReader

func (r *Fetcher) ExactBlobReader(id objectid.ObjectID) (io.ReadCloser, int64, error)

ExactBlobReader returns a reader for the content of the blob at id, together with its content size in bytes.

Labels: Life-Parent, Close-Caller.

func (*Fetcher) ExactCommit

func (r *Fetcher) ExactCommit(id objectid.ObjectID) (*stored.Stored[*commit.Commit], error)

ExactCommit reads, parses, and wraps the commit at id.

Labels: Life-Parent.

func (*Fetcher) ExactObject

func (r *Fetcher) ExactObject(id objectid.ObjectID) (*stored.Stored[object.Object], error)

ExactObject reads, parses, and wraps the object at id without constraining its concrete object kind.

Labels: Life-Parent.

func (*Fetcher) ExactTag

func (r *Fetcher) ExactTag(id objectid.ObjectID) (*stored.Stored[*tag.Tag], error)

ExactTag reads, parses, and wraps the tag at id.

Labels: Life-Parent.

func (*Fetcher) ExactTree

func (r *Fetcher) ExactTree(id objectid.ObjectID) (*stored.Stored[*tree.Tree], error)

ExactTree reads, parses, and wraps the tree at id.

Labels: Life-Parent.

func (*Fetcher) Header

func (r *Fetcher) Header(id objectid.ObjectID) (objecttype.Type, int64, error)

Header returns the object type and content size at id.

Labels: Life-Parent.

func (*Fetcher) Path

func (r *Fetcher) Path(root objectid.ObjectID, parts [][]byte) (tree.TreeEntry, error)

Path resolves parts within the tree identified by root and returns the final tree entry.

The root object may be any tree-ish object accepted by PeelToTree.

parts must contain at least one path segment. Intermediate path segments must resolve to tree entries. The final entry is returned without loading its object. Path segments may not contain \x00.

The path cannot be accurately represented as a string or a single []byte because Git tree entry names may include slashes. While []string is technically possible (since Go strings are not necessarily UTF-8), they do often imply UTF-8 in practice, which would be undesirable.

If your entry names are valid UTF-8 and uses / solely as segment separators, it may be convenient to use TreeFS for an io/fs.FS-like interface.

Labels: Life-Parent.

func (*Fetcher) PeelToBlob

func (r *Fetcher) PeelToBlob(id objectid.ObjectID) (*stored.Stored[*blob.Blob], error)

PeelToBlob peels tags until it reaches a blob.

Labels: Life-Parent.

func (*Fetcher) PeelToBlobID

func (r *Fetcher) PeelToBlobID(id objectid.ObjectID) (objectid.ObjectID, error)

PeelToBlobID peels tags until it reaches a blob object ID.

func (*Fetcher) PeelToBlobReader

func (r *Fetcher) PeelToBlobReader(id objectid.ObjectID) (io.ReadCloser, int64, error)

PeelToBlobReader returns a reader for the content of the peeled blob at id, together with its content size in bytes.

Labels: Life-Parent, Close-Caller.

func (*Fetcher) PeelToCommit

func (r *Fetcher) PeelToCommit(id objectid.ObjectID) (*stored.Stored[*commit.Commit], error)

PeelToCommit peels tags until it reaches a commit.

Labels: Life-Parent.

func (*Fetcher) PeelToCommitID

func (r *Fetcher) PeelToCommitID(id objectid.ObjectID) (objectid.ObjectID, error)

PeelToCommitID peels tags until it reaches a commit object ID.

func (*Fetcher) PeelToTree

func (r *Fetcher) PeelToTree(id objectid.ObjectID) (*stored.Stored[*tree.Tree], error)

PeelToTree peels tags until it reaches a tree or commit. If it reaches a commit, it returns the commit's root tree.

Labels: Life-Parent.

func (*Fetcher) PeelToTreeID

func (r *Fetcher) PeelToTreeID(id objectid.ObjectID) (objectid.ObjectID, error)

PeelToTreeID peels tags until it reaches a tree object ID, or a commit whose root tree object ID is then returned.

func (*Fetcher) Size

func (r *Fetcher) Size(id objectid.ObjectID) (int64, error)

Size returns the object content size at id.

Labels: Life-Parent.

func (*Fetcher) TreeFS

func (r *Fetcher) TreeFS(root objectid.ObjectID) (*TreeFS, error)

TreeFS returns a new filesystem view rooted at root, which may be any tree-ish object accepted by PeelToTreeID.

Labels: Deps-Borrowed, Life-Parent.

type PathEmptyError

type PathEmptyError struct{}

PathEmptyError indicates that Path received no segments.

func (*PathEmptyError) Error

func (err *PathEmptyError) Error() string

type PathNotFoundError

type PathNotFoundError struct {
	Index int
	Name  []byte
}

PathNotFoundError indicates that one tree path segment was not found.

func (*PathNotFoundError) Error

func (err *PathNotFoundError) Error() string

type PathNotTreeError

type PathNotTreeError struct {
	Index int
	Name  []byte
}

PathNotTreeError indicates that one intermediate path segment was not a tree.

func (*PathNotTreeError) Error

func (err *PathNotTreeError) Error() string

type PathSegmentEmptyError

type PathSegmentEmptyError struct {
	Index int
}

PathSegmentEmptyError indicates that one path segment is empty.

func (*PathSegmentEmptyError) Error

func (err *PathSegmentEmptyError) Error() string

type TreeFS

type TreeFS struct {
	// contains filtered or unexported fields
}

TreeFS exposes one Git tree as an fs.FS view backed by a Fetcher.

TreeFS interprets names using io/fs path rules. Those rules do not match raw Git tree entry naming exactly: names are UTF-8, slash-separated, and must be valid fs.FS paths. Tree entries that cannot be represented under those rules are not addressable through this API.

Labels: MT-Safe.

func (*TreeFS) Open

func (treeFS *TreeFS) Open(name string) (fs.File, error)

Open opens name for reading.

Directories are returned as fs.ReadDirFile values. Gitlink entries are not readable through TreeFS.

func (*TreeFS) ReadDir

func (treeFS *TreeFS) ReadDir(name string) ([]fs.DirEntry, error)

ReadDir reads and returns all directory entries for name.

func (*TreeFS) ReadFile

func (treeFS *TreeFS) ReadFile(name string) ([]byte, error)

ReadFile reads the blob contents at name.

Directories and gitlink entries are not readable through TreeFS.

func (*TreeFS) Stat

func (treeFS *TreeFS) Stat(name string) (fs.FileInfo, error)

Stat returns synthetic file metadata for name.

TreeFS metadata reflects Git tree entry mode and blob size where applicable. It does not represent filesystem stat metadata: ModTime is zero, ownership is unavailable, and Sys returns the underlying tree.TreeEntry when one exists.

func (*TreeFS) Sub

func (treeFS *TreeFS) Sub(dir string) (fs.FS, error)

Sub returns a new TreeFS rooted at dir.