gitrepofs

README

gitrepofs

A Go fs.FS git repository file system to easily access a repository at a specific tag (or other git reference).

The main envisioned use case is for go generate-based updates from upstream repositories to fetch the latest C definitions without the need to integrate upstream C libraries.

remoteURL := "https://gohub.org/froozle/baduzle"
latest, latestref, err := version.LatestReleaseTag(context.Background(),
    remoteURL, version.SemverMatcher)
gfs, err := NewForRevision(context.Background(), remoteURL, latestref)
contents, err := fs.ReadFile(gfs, "some/useful/file.h")

Other Implementations

• @hairyhenderson/go-fsimpl includes a git file system implementation (beside others). It uses the neat trick of cloning a repository into a local work tree in memory (instead of on "disk") and then serves from this memory-based file system. This design requires files to be present twice: once in the in-memory cloned repository and another time in the memory-based file system. Actively maintained at the time of this writing, as well as equiped with lots of unit tests.

• @ear7h/go-git-fs serves directly from an in-memory git repository clone without a work tree. It doesn't come with any unit tests and hasn't been maintained since May 2021. The code does the fs.ValidPath checks but then adds an unnecessary path.Clean because fs.ValidPath blocks all the things that path.Clean is supposed to sanitize.

• out of competition: @posener/gitfs tackles http.FileSystem instead.

Supported Go Versions

gitrepofs supports versions of Go that are noted by the Go release policy, that is, major versions N and N-1 (where N is the current major version).

Copyright and License

gitrepofs is Copyright 2023 Harald Albrecht, and licensed under the Apache License, Version 2.0.

Documentation

Overview

package gitrepofs provides a fs.FS interface onto a remote git repository at a specific tag.

The main envisioned use case is for “go generate”-based updates from upstream repositories to fetch the latest C definitions without the need to integrate upstream C libraries.

	remoteURL := "https://gohub.org/froozle/baduzle"
	latest, latestref, err := version.LatestReleaseTag(context.Background(),
      remoteURL, version.SemverMatcher)
	gfs, err := NewForRevision(context.Background(), remoteURL, latestref)
	contents, err := fs.ReadFile(gfs, "some/useful/file.h")

The fs.FS Zoo

The number of interfaces and their relationships in fs.FS look like a (small) zoo and it is easy to get lost in what returns what, or extends that, or whatever. So here's our own little fs.FS Zoo map. For whatever reason, there's no cafeteria and no rest rooms (unless counting in runtime.GC).

fs.FS provides access to a hierarchical file system. Additional optional interfaces (discussed next) then offer more functionality.

• fs.FS.Open opens not only files, but also directories, returning an fs.File. However, in order to successfully open directories, either the file system itself must additionally implement the interface fs.ReadDirFS, or the fs.File returned must also implement fs.ReadDirFile.

fs.File provides access to a single file or directory; for directories, the additional interface fs.ReadDirFiles should also be implemented (Golang soundbite). We implement regular and executable file access in the File type and directory access in the Directory type.

• fs.File.Stat returns an fs.FileInfo.
• fs.File.Read reads the file contents; it doesn't return anything for directories.
• fs.File.Close closes the fs.File.

fs.FileInfo describes a file or directory and is returned by fs.File.Stat, but can also be returned from fs.DirEntry.Info. We implement the fs.FileInfo interface in our aptly named FileInfo type.

• Name
• Size
• Mode: file mode bits.
• ModTime
• IsDir
• Sys: underlying data source of nil.

Next on to fs.ReadDirFile: it provides fs.File operations and on top of it reading a directory. We implemented this interface in the Directory type.

• fs.ReadDirFile.ReadDir returns a bunch of fs.DirEntry objects. To complicate things, callers are allowed to read only piecemeal wise.

fs.DirEntry is an entry from a directory. These entries also have fs.FileInfo objects attached to them. We implement the interface in the DirEntry type.

• Name
• IsDir
• Type: file mode bits.
• fs.DirEntry.Info: returns an fs.FileInfo about this directory entry.

Index

• func New(repo *git.Repository, tree *object.Tree, mtime time.Time) fs.FS
• func NewForRevision(ctx context.Context, remoteURL string, revision string) (fs.FS, error)
• type DirEntry
  • func NewDirEntry(entry object.TreeEntry, size int64, mtime time.Time) *DirEntry
  • func (e *DirEntry) Info() (fs.FileInfo, error)
  • func (e *DirEntry) IsDir() bool
  • func (e *DirEntry) Name() string
  • func (e *DirEntry) Type() fs.FileMode
• type Directory
  • func NewDirectory(tree *object.Tree, fileinfo *FileInfo) *Directory
  • func (d *Directory) Close() error
  • func (d *Directory) Read(b []byte) (int, error)
  • func (d *Directory) ReadDir(n int) ([]fs.DirEntry, error)
  • func (d *Directory) Stat() (fs.FileInfo, error)
• type FS
  • func (gfs *FS) Open(name string) (fs.File, error)
• type File
  • func NewFile(fileinfo *FileInfo, blob *object.Blob) *File
  • func (f *File) Close() error
  • func (f *File) Read(b []byte) (int, error)
  • func (f *File) Stat() (fs.FileInfo, error)
• type FileInfo
  • func NewFileInfo(entry object.TreeEntry, size int64, mtime time.Time) *FileInfo
  • func NewFileInfoFromTree(tree *object.Tree, name string, mtime time.Time) *FileInfo
  • func (f *FileInfo) IsDir() bool
  • func (f *FileInfo) ModTime() time.Time
  • func (f *FileInfo) Mode() fs.FileMode
  • func (f *FileInfo) Name() string
  • func (f *FileInfo) Size() int64
  • func (f *FileInfo) Sys() any

Functions

func New

func New(repo *git.Repository, tree *object.Tree, mtime time.Time) fs.FS

New returns a fs.FS for the specified tree of the git repository object, and using the specified modification time.

func NewForRevision

func NewForRevision(ctx context.Context, remoteURL string, revision string) (fs.FS, error)

NewForRevision returns a fs.FS git repository file system object that provides read access to the files in the remote repository at the specified tag. The repository gets downloaded into memory only, so there is no need for handling and cleaning up any temporary directories on the file system.

revision can be (as supported by github.com/go-git/go-git/v5/Repository.ResolveRevision):

• HEAD
• branch
• tag
• ...

Types

type DirEntry

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

DirEntry represents an entry read from a directory. They are returned by fs.ReadDir and fs.ReadDirFile.ReadDir. DirEntry objects also contain fs.FileInfo objects.

func NewDirEntry

func NewDirEntry(
	entry object.TreeEntry,
	size int64,
	mtime time.Time,
) *DirEntry

NewDirEntry returns a new DirEntry object for a file or directory entry.

func (*DirEntry) Info

func (e *DirEntry) Info() (fs.FileInfo, error)

Info returns the FileInfo for the file or subdirectory described by the entry. The returned FileInfo may be from the time of the original directory read or from the time of the call to Info. If the file has been removed or renamed since the directory read, Info may return an error satisfying errors.Is(err, ErrNotExist). If the entry denotes a symbolic link, Info reports the information about the link itself, not the link's target.

func (*DirEntry) IsDir

func (e *DirEntry) IsDir() bool

IsDir reports whether the entry describes a directory.

func (*DirEntry) Name

func (e *DirEntry) Name() string

Name returns the name of the file (or subdirectory) described by the entry. This name is only the final element of the path (the base name), not the entire path. For example, Name would return "hello.go" not "home/gopher/hello.go".

func (*DirEntry) Type

func (e *DirEntry) Type() fs.FileMode

Type returns the type bits for the entry. The type bits are a subset of the usual fs.FileMode bits, those returned by the fs.FileMode.Type method.

type Directory

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

Directory represents completely unexpectedly a git directory.

func NewDirectory

func NewDirectory(
	tree *object.Tree,
	fileinfo *FileInfo,
) *Directory

NewDirectory returns a new Directory object representing a git tree.

func (*Directory) Close

func (d *Directory) Close() error

Close this git file.

func (*Directory) Read

func (d *Directory) Read(b []byte) (int, error)

Read nothing from this git directory.

func (*Directory) ReadDir

func (d *Directory) ReadDir(n int) ([]fs.DirEntry, error)

func (*Directory) Stat

func (d *Directory) Stat() (fs.FileInfo, error)

Stat returns information about this git directory.

type FS

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

FS provides a view into a specific git tree.

func (*FS) Open

func (gfs *FS) Open(name string) (fs.File, error)

Open opens the named file or directory. The name must conform to the rules implemented in fs.ValidPath:

• unrooted, slash-separated path elements, like “x/y/z”, but not “/x/y/z”. Double slashes as separators are invlid.
• the root (top-level) directory on its own is named “.”.
• otherwise, neither “.” nor “..' are allowed.
• finally, the empty name “” isn't allowed either.

Please note that fs.ReadDir uses fs.ReadDirFS.ReadDir when available, but otherwise falls back to fs.FS.Open.

When Open returns an error, it is of type *fs.PathError with the Op field set to "open", the Path field set to name, and the Err field describing the problem.

Open rejects attempts to open names that do not satisfy fs.ValidPath(name), returning a [*fs.PathError with Err set to fs.ErrInvalid or fs.ErrNotExist.

type File

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

File represents a git regular or executable file. It never represents a directory, that is served by Directory instead.

func NewFile

func NewFile(fileinfo *FileInfo, blob *object.Blob) *File

NewFile returns a new File object, given a file information object and the file's contents blob.

func (*File) Close

func (f *File) Close() error

Close this git file.

func (*File) Read

func (f *File) Read(b []byte) (int, error)

Read some amount of contents from this git file.

func (*File) Stat

func (f *File) Stat() (fs.FileInfo, error)

Stat returns information about this git file.

type FileInfo

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

FileInfo implements fs.FileInfo for both a git (regular/executable) file blob as well as a directory.

According to the “fs.FS Zoo” FileInfo objects are returned from:

• fs.File.Stat
• directory entries: fs.DirEntry.Info

func NewFileInfo

func NewFileInfo(
	entry object.TreeEntry,
	size int64,
	mtime time.Time,
) *FileInfo

NewFileInfo returns a new FileInfo object, given a git tree entry, file size and modification time stamp.

The size can (and must) be determined beforehand given a tree object and then calling object.Tree.Size with the correct path.

func NewFileInfoFromTree

func NewFileInfoFromTree(
	tree *object.Tree,
	name string,
	mtime time.Time,
) *FileInfo

NewFileInfoFromTree returns a new FileInfo object that represents the specified tree as a directory itself.

func (*FileInfo) IsDir

func (f *FileInfo) IsDir() bool

IsDir returns true if the file actually is a directory.

func (*FileInfo) ModTime

func (f *FileInfo) ModTime() time.Time

ModTime returns the file's modification time.

func (*FileInfo) Mode

func (f *FileInfo) Mode() fs.FileMode

Mode returns the file's mode and permission bits.

func (*FileInfo) Name

func (f *FileInfo) Name() string

Name returns the name of a file (that can actually also happened to be a directory).

func (*FileInfo) Size

func (f *FileInfo) Size() int64

Size returns the size of the file. Always returns 0 for a directory (this is system-dependent anyway).

func (*FileInfo) Sys

func (f *FileInfo) Sys() any

Sys always return nil, as there is no-system specific file information provided by our git file system.